diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-08-18 13:50:51 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-08-18 13:50:51 +0300 |
| commit | db384e6b19af03b4c3c82a5760d83a3fd79f7982 (patch) | |
| tree | 34beaef37df5f47ccbcf5729d7583aae093cffa0 /doc | |
| parent | 54fd7b1bad233e3944434da91d257fa7f63c3996 (diff) | |
Add latest changes from gitlab-org/gitlab@16-3-stable-eev16.3.0-rc42
Diffstat (limited to 'doc')
1183 files changed, 22562 insertions, 13006 deletions
diff --git a/doc/.vale/gitlab/CommandStringsQuoted.yml b/doc/.vale/gitlab/CommandStringsQuoted.yml new file mode 100644 index 00000000000..531595ed10d --- /dev/null +++ b/doc/.vale/gitlab/CommandStringsQuoted.yml @@ -0,0 +1,14 @@ +--- +# Error: gitlab.CommandStringsQuoted +# +# Ensures all code blocks wrap URL strings in quotation marks. +# +# For a list of all options, see https://vale.sh/docs/topics/styles/ +extends: existence +message: "For the command example, use double quotes around the URL: %s" +link: https://docs.gitlab.com/ee/development/documentation/restful_api_styleguide.html#curl-commands +level: error +scope: raw +nonword: true +tokens: + - '(curl|--url)[^"\]\n]+?https?:\/\/[^ \n]*' diff --git a/doc/.vale/gitlab/CurlStringsQuoted.yml b/doc/.vale/gitlab/CurlStringsQuoted.yml deleted file mode 100644 index efe7aa23832..00000000000 --- a/doc/.vale/gitlab/CurlStringsQuoted.yml +++ /dev/null @@ -1,13 +0,0 @@ ---- -# Error: gitlab.CurlStringsQuoted -# -# Ensures all code blocks using `curl` wrap URL strings in quotation marks. -# -# For a list of all options, see https://vale.sh/docs/topics/styles/ -extends: existence -message: "For the cURL example, use double quotes around the URL: %s" -link: https://docs.gitlab.com/ee/development/documentation/restful_api_styleguide.html#curl-commands -level: error -scope: code -raw: - - 'curl [^"]+://.*' diff --git a/doc/.vale/gitlab/HeadingContent.yml b/doc/.vale/gitlab/HeadingContent.yml index 31ac3022934..ef130aa8bba 100644 --- a/doc/.vale/gitlab/HeadingContent.yml +++ b/doc/.vale/gitlab/HeadingContent.yml @@ -7,12 +7,13 @@ extends: existence message: "Rename the heading '%s', or re-purpose the content elsewhere." level: warning -scope: heading link: https://docs.gitlab.com/ee/development/documentation/topic_types/concept.html#concept-headings -ignorecase: false +ignorecase: true +nonword: true +scope: raw tokens: - - How it works - - Limitations - - Overview - - Use cases? - - Important notes? + - '\#+ How it works' + - '\#+ Limitations' + - '\#+ Overview' + - '\#+ Use cases?' + - '\#+ Important notes?' diff --git a/doc/.vale/gitlab/Markdown_emoji.yml b/doc/.vale/gitlab/Markdown_emoji.yml deleted file mode 100644 index 20f3ed0f5cb..00000000000 --- a/doc/.vale/gitlab/Markdown_emoji.yml +++ /dev/null @@ -1,13 +0,0 @@ ---- -# Warning: gitlab.Markdown_emoji -# -# Check for use of GLFM emoji syntax (https://docs.gitlab.com/ee/user/markdown.html#emoji), which doesn't render correctly in documentation. -# -# For a list of all options, see https://vale.sh/docs/topics/styles/ -extends: existence -message: "Replace '%s' with GitLab SVGs or Unicode emoji." -link: https://docs.gitlab.com/ee/development/documentation/styleguide/#gitlab-svg-icons -level: warning -scope: text -raw: - - '(?:\s+|^):[a-zA-Z0-9\-_\+]+:(?:\s+|$|\.)' diff --git a/doc/.vale/gitlab/MeaningfulLinkWords.yml b/doc/.vale/gitlab/MeaningfulLinkWords.yml index 6fb41c7ce95..a0b3bf9c611 100644 --- a/doc/.vale/gitlab/MeaningfulLinkWords.yml +++ b/doc/.vale/gitlab/MeaningfulLinkWords.yml @@ -5,11 +5,12 @@ # # For a list of all options, see https://vale.sh/docs/topics/styles/ extends: existence -message: "Improve SEO and accessibility by rewriting '%s' in the link text." +message: "Improve SEO and accessibility by rewriting the link text for '%s'." level: warning -scope: link ignorecase: true link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#text-for-links +scope: raw +nonword: true tokens: - - here - - this page + - \[here\]\(.*\) + - \[this page\]\(.*\) diff --git a/doc/.vale/gitlab/SubstitutionWarning.yml b/doc/.vale/gitlab/SubstitutionWarning.yml index d9d4200e88b..c081ca5a4f7 100644 --- a/doc/.vale/gitlab/SubstitutionWarning.yml +++ b/doc/.vale/gitlab/SubstitutionWarning.yml @@ -31,6 +31,8 @@ swap: file name: "filename" filesystem: "file system" info: "information" + installation from source: self-compiled installation + installations from source: self-compiled installations it is recommended: "you should" logged in user: "authenticated user" logged-in user: "authenticated user" @@ -52,6 +54,8 @@ swap: signed in user: "authenticated user" signed-in user: "authenticated user" since: "because' or 'after" + source (?:install|installation): self-compiled installation + source (?:installs|installations): self-compiled installations sub-group: "subgroup" sub-groups: "subgroups" timezone: "time zone" diff --git a/doc/.vale/gitlab/Wordy.yml b/doc/.vale/gitlab/Wordy.yml index 45546435ee9..808bedad35a 100644 --- a/doc/.vale/gitlab/Wordy.yml +++ b/doc/.vale/gitlab/Wordy.yml @@ -10,6 +10,7 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list. level: suggestion ignorecase: true swap: + as well as: "Use 'and' instead of 'as well as'." note that: "Remove the phrase 'note that'." please: "Use 'please' only if we've inconvenienced the user." respectively: "Remove 'respectively' and list each option instead." diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index ed505094e75..1e66d12adc9 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -995,7 +995,7 @@ tcpdump teardown templated Thanos -Thoughtbot +thoughtbot throughputs Tiller timebox diff --git a/doc/administration/application_settings_cache.md b/doc/administration/application_settings_cache.md index 30019df44aa..d88afcbb401 100644 --- a/doc/administration/application_settings_cache.md +++ b/doc/administration/application_settings_cache.md @@ -45,7 +45,7 @@ To change the expiry value: application_settings_cache_seconds: 60 ``` -1. Save the file, and then [restart](restart_gitlab.md#installations-from-source) +1. Save the file, and then [restart](restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. ::EndTabs diff --git a/doc/administration/audit_event_streaming/audit_event_types.md b/doc/administration/audit_event_streaming/audit_event_types.md new file mode 100644 index 00000000000..b69f1815394 --- /dev/null +++ b/doc/administration/audit_event_streaming/audit_event_types.md @@ -0,0 +1,291 @@ +--- +stage: Govern +group: Compliance +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +--- + +<!--- + This documentation is auto generated by a Rake task. + + Please do not edit this file directly. To update this file, run: + bundle exec rake gitlab:audit_event_types:compile_docs +---> + +# Audit event types **(ULTIMATE)** + +Audit event types are used to [filter streamed audit events](index.md#update-event-filters). + +Every audit event is associated with an event type. The association with the event type can mean that an audit event is: + +- Saved to database. Audit events associated with these types are retrievable by using the audit events dashboard or the [audit events API](../../api/audit_events.md). +- Streamed. Audit events associated with these types are [streamed to external destinations](../index.md) if a + destination is set. +- Not streamed. Audit events associated with these types are not streamed to external destinations even if a destination is set. + +## Available audit event types + +| Name | Description | Saved to database | Streamed | Feature category | Introduced in | +|:-----|:------------|:------------------|:---------|:-----------------|:--------------| +| [`add_gpg_key`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111744) | Event triggered when a GPG Key is created | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/373961) | +| [`allow_author_approval_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102256) | Event triggered on updating prevent merge request approval from authors from group merge request setting | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/373949) | +| [`allow_committer_approval_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102256) | Event triggered on updating prevent merge request approval from committers from group merge request setting | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/373949) | +| [`allow_merge_on_skipped_pipeline_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83922) | There is a project setting which toggles the ability to merge when a pipeline is skipped. This audit event tracks changes to that setting. This MR adds a setting to allow this (like previous GitLab versions). | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_integration` | GitLab [14.10](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) | +| [`allow_overrides_to_approver_list_per_merge_request_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102256) | Event triggered on updating prevent users from modifying MR approval rules in merge requests from group merge request setting | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/373949) | +| [`application_setting_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124639) | Triggered when Application setting is updated | **{check-circle}** Yes | **{check-circle}** Yes | `system_access` | GitLab [16.3](https://gitlab.com/gitlab-org/gitlab/-/issues/282428) | +| [`approval_rule_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89939) | Triggered when a merge request approval rule is created | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363092) | +| [`approval_rule_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82297) | Triggered on successful approval rule deletion | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [14.9](https://gitlab.com/gitlab-org/gitlab/-/issues/329514) | +| [`audit_events_streaming_headers_create`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92068) | Triggered when a streaming header for audit events is created | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [15.3](https://gitlab.com/gitlab-org/gitlab/-/issues/366350) | +| [`audit_events_streaming_headers_destroy`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92068) | Triggered when a streaming header for audit events is deleted | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [15.3](https://gitlab.com/gitlab-org/gitlab/-/issues/366350) | +| [`audit_events_streaming_headers_update`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92068) | Triggered when a streaming header for audit events is updated | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.3](https://gitlab.com/gitlab-org/gitlab/-/issues/366350) | +| [`audit_events_streaming_instance_headers_create`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125870) | Triggered when a streaming header for instance level external audit event destination is created | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [16.3](https://gitlab.com/gitlab-org/gitlab/-/issues/417433) | +| [`audit_events_streaming_instance_headers_destroy`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127228) | Triggered when a streaming header for instance level external audit event destination is deleted | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [16.3](https://gitlab.com/gitlab-org/gitlab/-/issues/417433) | +| [`audit_events_streaming_instance_headers_update`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127228) | Triggered when a streaming header for instance level external audit event destination is updated | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [16.3](https://gitlab.com/gitlab-org/gitlab/-/issues/417433) | +| [`authenticated_with_group_saml`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28575) | Triggered after successfully signing in with SAML authentication | **{check-circle}** Yes | **{check-circle}** Yes | `user_management` | GitLab [12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/35710) | +| [`ban_user`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116103) | Event triggered on user ban action | **{check-circle}** Yes | **{check-circle}** Yes | `user_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/377620) | +| [`change_membership_state`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87924) | Event triggered on a users membership is updated | **{check-circle}** Yes | **{check-circle}** Yes | `user_management` | GitLab [15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/362200) | +| [`ci_group_variable_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a CI variable is created at a group level | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_integration` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | +| [`ci_group_variable_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a group's CI variable is deleted | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_integration` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | +| [`ci_group_variable_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a group's CI variable is updated | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_integration` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | +| [`ci_variable_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a CI variable is created at a project level | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_integration` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | +| [`ci_variable_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a project's CI variable is deleted | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_integration` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | +| [`ci_variable_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a project's CI variable is updated | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_integration` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | +| [`cluster_agent_token_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112036) | Event triggered when a user creates a cluster agent token | **{check-circle}** Yes | **{check-circle}** Yes | `deployment_management` | GitLab [15.10](https://gitlab.com/gitlab-org/gitlab/-/issues/382133) | +| [`cluster_agent_token_revoked`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112036) | Event triggered when a user revokes a cluster agent token | **{check-circle}** Yes | **{check-circle}** Yes | `deployment_management` | GitLab [15.10](https://gitlab.com/gitlab-org/gitlab/-/issues/382133) | +| [`code_suggestions_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117174) | Code Suggestion UI group setting change | **{check-circle}** Yes | **{check-circle}** Yes | `code_suggestions` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/405295) | +| [`comment_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120927) | Triggered when a comment is added to an issue or an MR using the project access token | **{dotted-circle}** No | **{check-circle}** Yes | `team_planning` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`compliance_framework_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65343) | Triggered when a framework gets removed from a project | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/329362) | +| [`compliance_framework_id_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/94711) | audit when compliance framework ID is updated | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369310) | +| [`coverage_fuzzing_corpus_create`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71992) | Event triggered on a corpus action is added | **{check-circle}** Yes | **{check-circle}** Yes | `fuzz_testing` | GitLab [14.5](https://gitlab.com/gitlab-org/gitlab/-/issues/341485) | +| [`create_compliance_framework`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74292) | Triggered on successful compliance framework creation | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/340649) | +| [`create_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74632) | Event triggered when an external audit event destination is created | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/344664) | +| [`create_instance_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123882) | Event triggered when an instance level external audit event destination is created | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [16.2](https://gitlab.com/gitlab-org/gitlab/-/issues/404730) | +| [`create_status_check`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84624) | Event triggered when an external status check is created | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/355805) | +| [`dast_profile_create`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62604) | Triggered when a dynamic application security testing profile is created | **{check-circle}** Yes | **{check-circle}** Yes | `dynamic_application_security_testing` | GitLab [14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) | +| [`dast_profile_destroy`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62604) | Triggered when a dynamic application security profile is removed | **{check-circle}** Yes | **{check-circle}** Yes | `dynamic_application_security_testing` | GitLab [14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) | +| [`dast_profile_schedule_create`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68046) | Triggered when a dynamic application security testing profile schedule is created | **{check-circle}** Yes | **{check-circle}** Yes | `dynamic_application_security_testing` | GitLab [14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/330308) | +| [`dast_profile_schedule_update`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66445) | Triggered when a dynamic application security testing profile schedule is updated | **{check-circle}** Yes | **{check-circle}** Yes | `dynamic_application_security_testing` | GitLab [14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/330308) | +| [`dast_profile_update`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62604) | Triggered when a dynamic application security profile is updated | **{check-circle}** Yes | **{check-circle}** Yes | `dynamic_application_security_testing` | GitLab [14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) | +| [`dast_scanner_profile_create`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62007) | Triggered when a dynamic application security testing scanner profile is created | **{check-circle}** Yes | **{check-circle}** Yes | `dynamic_application_security_testing` | GitLab [14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) | +| [`dast_scanner_profile_destroy`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62007) | Triggered when a dynamic application security testing scanner profile is removed | **{check-circle}** Yes | **{check-circle}** Yes | `dynamic_application_security_testing` | GitLab [14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) | +| [`dast_scanner_profile_update`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62007) | Triggered when a dynamic application security testing scanner profile is updated | **{check-circle}** Yes | **{check-circle}** Yes | `dynamic_application_security_testing` | GitLab [14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) | +| [`dast_site_profile_create`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62465) | Triggered when a dynamic application security testing site profile is created | **{check-circle}** Yes | **{check-circle}** Yes | `dynamic_application_security_testing` | GitLab [14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) | +| [`dast_site_profile_destroy`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62465) | Triggered when a dynamic application security testing site profile is removed | **{check-circle}** Yes | **{check-circle}** Yes | `dynamic_application_security_testing` | GitLab [14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) | +| [`dast_site_profile_update`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62465) | Triggered when a dynamic application security testing site profile is updated | **{check-circle}** Yes | **{check-circle}** Yes | `dynamic_application_security_testing` | GitLab [14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) | +| [`delete_epic`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96773) | Event triggered on successful epic deletion | **{dotted-circle}** No | **{check-circle}** Yes | `portfolio_management` | GitLab [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/370487) | +| [`delete_issue`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96773) | Event triggered on successful issue deletion | **{dotted-circle}** No | **{check-circle}** Yes | `team_planning` | GitLab [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/370487) | +| [`delete_merge_request`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96773) | Event triggered on successful merge request deletion | **{dotted-circle}** No | **{check-circle}** Yes | `code_review` | GitLab [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/370487) | +| [`delete_status_check`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84624) | Event triggered when an external status check is deleted | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/355805) | +| [`delete_work_item`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96773) | Event triggered on successful work item deletion | **{dotted-circle}** No | **{check-circle}** Yes | `team_planning` | GitLab [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/370487) | +| [`deploy_key_added`](https://gitlab.com/gitlab-org/gitlab/-/commit/08586a616909c7f9efe2210c2b74fd3422d4eb62) | Triggered when deploy key is added | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_delivery` | GitLab [15.3](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`deploy_key_removed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92219) | Audit event triggered when deploy key is removed | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_delivery` | GitLab [15.3](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`deploy_token_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89391) | Audit event triggered when deploy token is created | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_delivery` | GitLab [15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`deploy_token_creation_failed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89391) | Audit event triggered when deploy token fails to create | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_delivery` | GitLab [15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`deploy_token_destroyed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89391) | Audit event triggered when deploy token is destroyed | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_delivery` | GitLab [15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`deploy_token_revoked`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89391) | Triggered when project deploy token is revoked | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_delivery` | GitLab [15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`destroy_compliance_framework`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74292) | Triggered on successful compliance framework deletion | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/340649) | +| [`destroy_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74632) | Event triggered when an external audit event destination is deleted | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/344664) | +| [`destroy_instance_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125846) | Event triggered when an instance level external audit event destination is deleted | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [16.2](https://gitlab.com/gitlab-org/gitlab/-/issues/404730) | +| [`email_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114546) | Event triggered when an email is created | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374107) | +| [`email_destroyed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114546) | Event triggered when an email is destroyed | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374107) | +| [`environment_protected`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108247) | This event is triggered when a protected environment is created. | **{check-circle}** Yes | **{dotted-circle}** No | `environment_management` | GitLab [15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/216164) | +| [`environment_unprotected`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108247) | This event is triggered when a protected environment is deleted. | **{check-circle}** Yes | **{dotted-circle}** No | `environment_management` | GitLab [15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/216164) | +| [`epic_closed_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when an epic is closed by a group access token | **{check-circle}** Yes | **{check-circle}** Yes | `portfolio_management` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`epic_created_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when an epic is created by a group access token | **{check-circle}** Yes | **{check-circle}** Yes | `portfolio_management` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`epic_reopened_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when an epic is reopened by a group access token | **{check-circle}** Yes | **{check-circle}** Yes | `portfolio_management` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`event_type_filters_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113081) | Event triggered when a new audit events streaming event type filter is created | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [15.10](https://gitlab.com/gitlab-org/gitlab/-/issues/344848) | +| [`event_type_filters_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113489) | Event triggered when audit events streaming event type filters are deleted | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [15.10](https://gitlab.com/gitlab-org/gitlab/-/issues/344848) | +| [`experiment_features_enabled_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118222) | Event triggered on toggling setting for enabling experiment AI features | **{check-circle}** Yes | **{check-circle}** Yes | `not_owned` | GitLab [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/404856/) | +| [`external_status_check_name_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106095) | Event triggered on updating name of a external status check | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369333) | +| [`external_status_check_url_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84624) | Whenever the URL that is used for external status checks for a pipeline is updated, this audit event is created | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/355805) | +| [`google_cloud_logging_configuration_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122025) | Triggered when Google Cloud Logging configuration is created | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) | +| [`google_cloud_logging_configuration_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122025) | Triggered when Google Cloud Logging configuration is deleted | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) | +| [`google_cloud_logging_configuration_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122025) | Triggered when Google Cloud Logging configuration is updated | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) | +| [`group_access_token_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92225) | Event triggered on creating a group access token | **{check-circle}** Yes | **{check-circle}** Yes | `subgroup` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`group_access_token_creation_failed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92225) | Event triggered on failing to create a group access token | **{check-circle}** Yes | **{check-circle}** Yes | `subgroup` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`group_access_token_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92225) | Event triggered on deleting a group access token | **{check-circle}** Yes | **{check-circle}** Yes | `subgroup` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`group_access_token_deletion_failed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92225) | Event triggered on failure to delete a group access token | **{check-circle}** Yes | **{check-circle}** Yes | `subgroup` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`group_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121005) | Event triggered when a group is created. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [16.3](https://gitlab.com/gitlab-org/gitlab/-/issues/411595) | +| [`group_deletion_marked`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116986) | Event triggered when a group is marked for deletion. | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374106) | +| [`group_deploy_token_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93091) | Audit event triggered when a groups deploy token is created | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_delivery` | GitLab [15.3](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`group_deploy_token_creation_failed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93091) | Audit event triggered when a groups deploy token fails to create | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_delivery` | GitLab [15.3](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`group_deploy_token_destroyed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93091) | Audit event triggered when group deploy token is destroyed | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_delivery` | GitLab [15.3](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`group_deploy_token_revoked`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93091) | Audit event triggered when group deploy token is revoked | **{check-circle}** Yes | **{check-circle}** Yes | `continuous_delivery` | GitLab [15.3](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`group_destroyed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116986) | Event triggered when a group is destroyed. | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374106) | +| [`group_lfs_enabled_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106079) | Event triggered when a groups lfs enabled is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369323) | +| [`group_membership_lock_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106079) | Event triggered when a groups membership lock is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369323) | +| [`group_merge_request_approval_setting_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87880) | Triggered when merge request approval settings are added on a group level. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/356152) | +| [`group_name_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106079) | Event triggered when a groups name is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369320) | +| [`group_path_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106079) | Event triggered when a groups path is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369321) | +| [`group_project_creation_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106079) | Event triggered when a groups project creation level is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369327) | +| [`group_push_rules_author_email_regex_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105791) | Event triggered when a groups push rules settings is changed for author email regex. | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369343) | +| [`group_push_rules_branch_name_regex_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105791) | Event triggered when a groups push rules settings is changed for branch name regex. | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369340) | +| [`group_push_rules_commit_committer_check_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86046) | Triggered when group push rule setting is updated for reject unverified users. | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/227629) | +| [`group_push_rules_commit_message_negative_regex_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105791) | Event triggered when a groups push rules settings is changed for commit message negative regex. | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369342) | +| [`group_push_rules_commit_message_regex_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105791) | Event triggered when a groups push rules settings is changed for commit message regex. | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369341) | +| [`group_push_rules_file_name_regex_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105791) | Event triggered when a groups push rules settings is changed for file name regex. | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369344) | +| [`group_push_rules_max_file_size_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105791) | Event triggered when a groups push rules settings is changed for max file size. | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369345) | +| [`group_push_rules_prevent_secrets_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86046) | Triggered when group push rule setting is updated to prevent pushing secret files. | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/227629) | +| [`group_push_rules_reject_deny_delete_tag_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86046) | Triggered when group push rule setting is updated to deny deletion of tags using Git push. | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/227629) | +| [`group_push_rules_reject_member_check_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86046) | Triggered when group push rule setting is updated to check if commit author is a GitLab user. | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/227629) | +| [`group_push_rules_reject_non_dco_commits_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86046) | Triggered when group push rule setting is updated for reject non DCO certified commits. | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/227629) | +| [`group_push_rules_reject_unsigned_commits_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86046) | Triggered when group push rule setting is updated for reject unsigned commits. | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/227629) | +| [`group_repository_size_limit_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106079) | Event triggered when a groups repository size limit is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369322) | +| [`group_request_access_enabled_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106079) | Event triggered when a groups request access enabled is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369323) | +| [`group_require_two_factor_authentication_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106079) | Event triggered when a groups require two factor authentication setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369325) | +| [`group_restored`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116986) | Event triggered when a group is restored. | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374106) | +| [`group_saml_provider_create`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111227) | Event triggered when a group SAML provider is created | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/373964) | +| [`group_saml_provider_update`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111227) | Event triggered when a group SAML provider is updated | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/373964) | +| [`group_share_with_group_link_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112719) | This event is triggered when you proceed to invite a group to another group via the 'invite group' tab on the group's membership page | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.10](https://gitlab.com/gitlab-org/gitlab/-/issues/327909) | +| [`group_share_with_group_link_removed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112719) | This event is triggered when you proceed to invite a group to another group via the 'invite group' tab on the group's membership page | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.10](https://gitlab.com/gitlab-org/gitlab/-/issues/327909) | +| [`group_share_with_group_link_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112719) | This event is triggered when you proceed to invite a group to another group via the 'invite group' tab on the group's membership page | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.10](https://gitlab.com/gitlab-org/gitlab/-/issues/327909) | +| [`group_shared_runners_minutes_limit_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106079) | Event triggered when a groups shared runners minutes limit is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369324) | +| [`group_two_factor_grace_period_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106079) | Event triggered when a groups two factor grace period is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369326) | +| [`group_visibility_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106079) | Event triggered when a groups visibility level is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369322) | +| [`incident_closed_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when an incident is closed using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `incident_management` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`incident_created_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when an incident is created using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `incident_management` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`incident_reopened_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when an incident is reopened using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `incident_management` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`ip_restrictions_changed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86037) | Event triggered on any changes in the IP AllowList | **{check-circle}** Yes | **{check-circle}** Yes | `system_access` | GitLab [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/358986) | +| [`issue_closed_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when an issue is closed using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `team_planning` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`issue_created_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when an issue is created using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `team_planning` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`issue_reopened_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when an issue is reopened using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `team_planning` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`member_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109711) | Event triggered when a membership is created | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/374112) | +| [`member_destroyed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109711) | Event triggered when a membership is destroyed | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/374112) | +| [`member_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109711) | Event triggered when a membership is updated | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/374112) | +| [`merge_commit_template_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107533) | audit when merge commit template is updated | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/369314) | +| [`merge_request_approval_operation`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92983) | Audit event triggered when a merge request is approved | **{dotted-circle}** No | **{check-circle}** Yes | `code_review_workflow` | GitLab [15.3](https://gitlab.com/gitlab-org/gitlab/-/issues/10869) | +| [`merge_request_closed_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120927) | Triggered when a merge request is closed using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `code_review_workflow` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`merge_request_create`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90911) | Event triggered when a Merge Request is created | **{dotted-circle}** No | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/367239) | +| [`merge_request_created_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120927) | Triggered when a merge request is created using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `code_review_workflow` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`merge_request_invalid_approver_rules`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100496) | Audit event triggered for an invalid rule when merge request is approved | **{check-circle}** Yes | **{check-circle}** Yes | `code_review_workflow` | GitLab [15.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100496) | +| [`merge_request_merged_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120927) | Triggered when a merge request is merged using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `code_review_workflow` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`merge_request_reopened_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120927) | Triggered when a merge request is reopened using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `code_review_workflow` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`merged_merge_request_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118793) | Audit event triggered when a merged merge request is deleted | **{dotted-circle}** No | **{check-circle}** Yes | `source_code_management` | GitLab [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/408288) | +| [`merged_merge_request_deletion_started`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118793) | Audit event triggered when a merged merge request's deletion is started | **{dotted-circle}** No | **{check-circle}** Yes | `source_code_management` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/408288) | +| [`omniauth_login_failed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123080) | Event triggered when an OmniAuth login fails | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [16.3](https://gitlab.com/gitlab-org/gitlab/-/issues/374107) | +| [`password_reset_requested`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114548) | Event triggered when a user requests a password reset using a registered email address | **{check-circle}** Yes | **{dotted-circle}** No | `compliance_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374107) | +| [`personal_access_token_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108952) | Event triggered when a user creates a personal access token | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/374113) | +| [`personal_access_token_revoked`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108952) | Event triggered when a personal access token is revoked | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/374113) | +| [`policy_project_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102154) | This event is triggered whenever the security policy project is updated for a project. | **{check-circle}** Yes | **{check-circle}** Yes | `security_policy_management` | GitLab [15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/377877) | +| [`project_access_token_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92225) | Event triggered on creating a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `project` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`project_access_token_creation_failed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92225) | Event triggered on failure to create a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `project` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`project_access_token_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92225) | Event triggered on creating a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `project` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`project_access_token_deletion_failed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92225) | Event triggered on failure to delete a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `project` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363087) | +| [`project_archived`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117528) | Event triggered when a project is archived. | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374105) | +| [`project_cicd_merge_pipelines_enabled_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107428) | audit when project cicd merge pipelines setting is updated | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/369317) | +| [`project_cicd_merge_trains_enabled_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107428) | Event triggered on updating project setting for enabling ci cd merge trains | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/369317) | +| [`project_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117543) | Event triggered when a project is created. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/374105) | +| [`project_default_branch_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117543) | Event triggered when default branch of a project's repository is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/374105) | +| [`project_deletion_marked`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117546) | Event triggered when a project is marked for deletion. | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374105) | +| [`project_description_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128978) | Triggered when a project's description is updated | **{dotted-circle}** No | **{check-circle}** Yes | `groups_and_projects` | GitLab [16.3](https://gitlab.com/gitlab-org/gitlab/-/issues/377769) | +| [`project_destroyed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117546) | Event triggered when a project is destroyed. | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374105) | +| [`project_disable_overriding_approvers_per_merge_request_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106652) | audit when project disable overriding approvers per mr setting is updated | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369288) | +| [`project_export_file_download_started`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117528) | Event triggered when download of project export file gets started. | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374105) | +| [`project_feature_analytics_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's analytics access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369299) | +| [`project_feature_builds_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's builds access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369294) | +| [`project_feature_container_registry_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's container registry access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369303) | +| [`project_feature_environments_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's environments access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369307) | +| [`project_feature_feature_flags_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's feature flags access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369306) | +| [`project_feature_forking_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's feature forking access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369290) | +| [`project_feature_infrastructure_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's infrastructure access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369305) | +| [`project_feature_issues_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's issues access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369289) | +| [`project_feature_merge_requests_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's merge request access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369289) | +| [`project_feature_metrics_dashboard_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's metrics dashboard access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369289) | +| [`project_feature_model_experiments_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121027) | Model experiments access level was updated | **{check-circle}** Yes | **{check-circle}** Yes | `mlops` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/412384) | +| [`project_feature_monitor_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's monitor access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369304) | +| [`project_feature_operations_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's operation access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369300) | +| [`project_feature_package_registry_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's package registry access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369296) | +| [`project_feature_pages_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's page access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369297) | +| [`project_feature_releases_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's releases access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369308) | +| [`project_feature_repository_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's repository access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369295) | +| [`project_feature_requirements_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's requirements access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369301) | +| [`project_feature_security_and_compliance_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's security and compliance access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369302) | +| [`project_feature_snippets_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's snippet access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369293) | +| [`project_feature_wiki_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106919) | Event triggered when a project's wiki access level setting is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369292) | +| [`project_fork_operation`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90916) | Audit event triggered when a project is forked | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90916) | +| [`project_fork_relationship_removed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101017) | Event triggered on successful removal of project's fork relationship | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/272532) | +| [`project_group_link_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108918) | Event triggered when a group is invited to a project | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/374114) | +| [`project_group_link_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108918) | Event triggered when a project group link is deleted | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/374114) | +| [`project_group_link_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108918) | Event triggered when a project group link is updated | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/374114) | +| [`project_imported`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117528) | Event triggered when a project is imported. | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374105) | +| [`project_merge_method_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83922) | Triggered when a project's merge request method has been changed. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [14.10](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) | +| [`project_merge_requests_author_approval_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106652) | audit when project mr author approval setting is updated | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369288) | +| [`project_merge_requests_disable_committers_approval_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106652) | Event triggered on updating project setting for disabling committers approval on merge requests | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369277) | +| [`project_merge_requests_template_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84624) | Whenever a MR template is updated for a project, this audit event is created | **{check-circle}** Yes | **{check-circle}** Yes | `code_review_workflow` | GitLab [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/355805) | +| [`project_name_updated`](https://gitlab.com/gitlab-org/gitlab/-/commit/8c0b52247e717cf84bc7b248d817f8baa55b18a4) | Create this audit event whenever a project has its name updated | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [10.2](https://gitlab.com/gitlab-org/gitlab/-/commit/8c0b52247e717cf84bc7b248d817f8baa55b18a4) | +| [`project_namespace_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106652) | audit when project namespace is updated | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369288) | +| [`project_only_allow_merge_if_all_discussions_are_resolved_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106652) | Event triggered on updating project setting for allowing merge only when all discussions are resolved | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369286) | +| [`project_only_allow_merge_if_pipeline_succeeds_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106652) | audit when project only allow merge if pipeline succeeds setting is updated | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369288) | +| [`project_packages_enabled_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7962) | When the setting that controls packages for a project is toggled, this audit event is created | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [11.5](https://gitlab.com/gitlab-org/gitlab/-/issues/369288) | +| [`project_path_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100770) | Event triggered on updating a project's path | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/369271) | +| [`project_printing_merge_request_link_enabled_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106652) | Event triggered on updating setting for projects for enabling printing merge request link | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369283) | +| [`project_remove_source_branch_after_merge_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83922) | Create this audit event whenever a project has its setting to remove branches after merges modified | **{check-circle}** Yes | **{check-circle}** Yes | `code_review_workflow` | GitLab [14.10](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) | +| [`project_repository_size_limit_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106652) | Event triggered on updating repository size limit of a project | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369274) | +| [`project_require_password_to_approve_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106652) | Event triggered on updating project setting for requiring user's password for approval of merge request | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369280) | +| [`project_reset_approvals_on_push_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66234) | Create this audit event whenever a project has its setting on whether approvals are reset on a push is updated | **{check-circle}** Yes | **{check-circle}** Yes | `code_review_workflow` | GitLab [14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/336211) | +| [`project_resolve_outdated_diff_discussions_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106652) | audit when project resolve outdated diff discussions setting is updated | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369288) | +| [`project_restored`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117528) | Event triggered when a project is restored. | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374105) | +| [`project_suggestion_commit_message_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83922) | Create this audit event whenever a project has its suggested commit message updated | **{check-circle}** Yes | **{check-circle}** Yes | `code_suggestions` | GitLab [14.10](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) | +| [`project_unarchived`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117528) | Event triggered when a project is unarchived. | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374105) | +| [`project_visibility_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106652) | audit when project visiblity level setting is updated | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369288) | +| [`protected_branch_allow_force_push_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68869) | This audit event is created when a protected branch has its ability to allow force pushes is toggled | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/338873) | +| [`protected_branch_code_owner_approval_required_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107530) | audit when protected branch code owner approval required setting is updated | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/369318) | +| [`protected_branch_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92074) | Triggered when a protected branch is created | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363091) | +| [`protected_branch_removed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92074) | Triggered when a protected branch is removed | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363091) | +| [`protected_branch_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107530) | Event triggered on the setting for protected branches is update | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/369318) | +| [`registration_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123080) | Event triggered when a user registers for instance access | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [16.3](https://gitlab.com/gitlab-org/gitlab/-/issues/374107) | +| [`release_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111080) | Event triggered when a release is created | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/374111) | +| [`release_deleted_audit_event`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111080) | Event triggered when a release is deleted | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/374111) | +| [`release_milestones_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111080) | Event triggered when a release's associated milestones are updated | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/374111) | +| [`release_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111080) | Event triggered when a release is updated | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/374111) | +| [`remove_gpg_key`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111744) | Event triggered when a GPG Key is destroyed | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/373961) | +| [`remove_ssh_key`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65615) | Audit event triggered when a SSH key is removed | **{check-circle}** Yes | **{check-circle}** Yes | `user_profile` | GitLab [14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/220127) | +| [`repository_download_operation`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111218) | Event triggered when a Git repository for a project is downloaded | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/374108) | +| [`repository_git_operation`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/76719) | Triggered when authenticated users push, pull, or clone a project using SSH, HTTP(S), or the UI | **{dotted-circle}** No | **{check-circle}** Yes | `source_code_management` | GitLab [14.9](https://gitlab.com/gitlab-org/gitlab/-/issues/373950) | +| [`require_password_to_approve_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102256) | Event triggered on updating require user password for approvals from group merge request setting | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/373949) | +| [`retain_approvals_on_push_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102256) | Event triggered on updating require new approvals when new commits are added to an MR from group merge request setting | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/373949) | +| [`saml_group_links_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110525) | Event triggered when a SAML Group Link is created | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/373954) | +| [`saml_group_links_removed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110525) | Event triggered when a SAML Group Link is destroyed | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/373954) | +| [`secure_ci_job_token_inbound_disabled`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115350) | Event triggered when CI_JOB_TOKEN permissions disabled for inbound | **{check-circle}** Yes | **{check-circle}** Yes | `verify_security` | GitLab [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/338255) | +| [`secure_ci_job_token_inbound_enabled`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115350) | Event triggered when CI_JOB_TOKEN permissions enabled for inbound | **{check-circle}** Yes | **{check-circle}** Yes | `verify_security` | GitLab [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/338255) | +| [`secure_ci_job_token_project_added`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115350) | Event triggered when project added to inbound CI_JOB_TOKEN scope | **{check-circle}** Yes | **{check-circle}** Yes | `verify_security` | GitLab [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/338255) | +| [`secure_ci_job_token_project_removed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115350) | Event triggered when project removed from inbound CI_JOB_TOKEN scope | **{check-circle}** Yes | **{check-circle}** Yes | `verify_security` | GitLab [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/338255) | +| [`set_runner_associated_projects`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/97666) | Event triggered on successful assignment of associated projects to a CI runner | **{check-circle}** Yes | **{check-circle}** Yes | `runner` | GitLab [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/359958) | +| [`smartcard_authentication_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8120) | Event triggered when a user authenticates with smartcard | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/726) | +| [`squash_commit_template_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107533) | Event triggered on updating the merge request squash commit template for a project | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/369314) | +| [`squash_option_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84624) | Triggered when squash option setting has been changed. | **{check-circle}** Yes | **{check-circle}** Yes | `groups_and_projects` | GitLab [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/301124) | +| [`task_closed_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when a task is closed using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `team_planning` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`task_created_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when a task is created using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `team_planning` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`task_reopened_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when a task is reopened using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `team_planning` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`test_case_closed_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when a test case is closed using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `quality_management` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`test_case_created_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when a test case is created using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `quality_management` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`test_case_reopened_by_project_bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121485) | Triggered when a test case is reopened using a project access token | **{check-circle}** Yes | **{check-circle}** Yes | `quality_management` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323299) | +| [`third_party_ai_features_enabled_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118222) | Event triggered on toggling setting for enabling third-party AI features | **{check-circle}** Yes | **{check-circle}** Yes | `not_owned` | GitLab [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/404856/) | +| [`unban_user`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116221) | Event triggered on user unban action | **{check-circle}** Yes | **{check-circle}** Yes | `user_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/377620) | +| [`unblock_user`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115727) | Event triggered on user unblock action | **{check-circle}** Yes | **{check-circle}** Yes | `user_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/377620) | +| [`update_approval_rules`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89939) | Event triggered on updating a merge approval rule | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363092) | +| [`update_compliance_framework`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74292) | Triggered when a compliance framework is updated | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/340649) | +| [`update_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74632) | Event triggered when an external audit event destination is updated | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/344664) | +| [`update_instance_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125846) | Event triggered when an instance level external audit event destination is updated | **{check-circle}** Yes | **{check-circle}** Yes | `audit_events` | GitLab [16.2](https://gitlab.com/gitlab-org/gitlab/-/issues/404730) | +| [`update_mismatched_group_saml_extern_uid`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104791) | Triggered when the external UID is changed on a SAML identity. | **{check-circle}** Yes | **{check-circle}** Yes | `system_access` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/382256) | +| [`update_status_check`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84624) | Event triggered when an external status check is updated | **{check-circle}** Yes | **{check-circle}** Yes | `compliance_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/355805) | +| [`user_access_locked`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124169) | Event triggered when user access to the instance is locked | **{check-circle}** Yes | **{check-circle}** Yes | `system_access` | GitLab [16.2](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/244) | +| [`user_access_unlocked`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124973) | Event triggered when user access to the instance is unlocked | **{check-circle}** Yes | **{check-circle}** Yes | `system_access` | GitLab [16.2](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/244) | +| [`user_activate`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121708) | Event triggered on user activate action | **{check-circle}** Yes | **{check-circle}** Yes | `user_management` | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/13473) | +| [`user_admin_status_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65168) | Adds an audit event when a user is either made an administrator, or removed as an administrator | **{check-circle}** Yes | **{check-circle}** Yes | `user_profile` | GitLab [14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/323905) | +| [`user_approved`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113784) | Event triggered when a user is approved for an instance | **{check-circle}** Yes | **{dotted-circle}** No | `user_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374107) | +| [`user_blocked`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113784) | Event triggered when a user is blocked | **{check-circle}** Yes | **{dotted-circle}** No | `user_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374107) | +| [`user_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113784) | Event triggered when a user is created | **{check-circle}** Yes | **{check-circle}** Yes | `user_management` | GitLab [15.10](https://gitlab.com/gitlab-org/gitlab/-/issues/374107) | +| [`user_deactivate`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117776) | Event triggered on user deactivate action | **{check-circle}** Yes | **{check-circle}** Yes | `user_management` | GitLab [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/13473) | +| [`user_destroyed`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113784) | Event triggered when a user is scheduled for removal from the instance | **{check-circle}** Yes | **{dotted-circle}** No | `user_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374107) | +| [`user_disable_two_factor`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89598) | Audit event triggered when user disables two factor authentication | **{check-circle}** Yes | **{check-circle}** Yes | `system_access` | GitLab [15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/238177) | +| [`user_email_address_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2103) | Adds an audit event when a user updates their email address | **{check-circle}** Yes | **{check-circle}** Yes | `user_profile` | GitLab [10.1](https://gitlab.com/gitlab-org/gitlab-ee/issues/1370) | +| [`user_email_changed_and_user_signed_in`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106090) | audit when user emailed changed and user signed in | **{check-circle}** Yes | **{check-circle}** Yes | `user_management` | GitLab [15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/369331) | +| [`user_enable_admin_mode`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104754) | Event triggered on enabling admin mode | **{check-circle}** Yes | **{check-circle}** Yes | `system_access` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/362101) | +| [`user_impersonation`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79340) | Triggered when an instance administrator starts or stops impersonating a user | **{check-circle}** Yes | **{check-circle}** Yes | `user_management` | GitLab [14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/300961) | +| [`user_password_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106086) | audit when user password is updated | **{check-circle}** Yes | **{check-circle}** Yes | `user_management` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369330) | +| [`user_rejected`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113784) | Event triggered when a user registration is rejected | **{check-circle}** Yes | **{dotted-circle}** No | `user_management` | GitLab [15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/374107) | +| [`user_username_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106086) | Event triggered on updating a user's username | **{check-circle}** Yes | **{check-circle}** Yes | `user_profile` | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/369329) | +| [`feature_flag_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113453) | Triggered when a feature flag is created. | **{check-circle}** Yes | **{check-circle}** Yes | `feature_flags` | GitLab [15.10](https://gitlab.com/gitlab-org/gitlab/-/issues/374109) | +| [`feature_flag_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113453) | Triggered when a feature flag is deleted. | **{check-circle}** Yes | **{check-circle}** Yes | `feature_flags` | GitLab [15.10](https://gitlab.com/gitlab-org/gitlab/-/issues/374109) | +| [`feature_flag_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113453) | Triggered when a feature flag is updated. | **{check-circle}** Yes | **{check-circle}** Yes | `feature_flags` | GitLab [15.10](https://gitlab.com/gitlab-org/gitlab/-/issues/374109) | +| [`manually_trigger_housekeeping`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112095) | Triggered when manually triggering housekeeping via API or admin UI | **{check-circle}** Yes | **{check-circle}** Yes | `source_code_management` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/390761) | diff --git a/doc/administration/audit_event_streaming/examples.md b/doc/administration/audit_event_streaming/examples.md index d741e5fd60d..1c9a14dbab0 100644 --- a/doc/administration/audit_event_streaming/examples.md +++ b/doc/administration/audit_event_streaming/examples.md @@ -24,7 +24,7 @@ Streaming audit events can be sent when authenticated users push, pull, or clone Audit events are not captured for users that are not signed in. For example, when downloading a public project. -To configure streaming audit events for Git operations, see [Add a new streaming destination](index.md#add-a-new-streaming-destination). +To configure streaming audit events for Git operations, see [Add a new HTTP destination](index.md#add-a-new-http-destination). ### Headers diff --git a/doc/administration/audit_event_streaming/graphql_api.md b/doc/administration/audit_event_streaming/graphql_api.md index 9f8fef0e3ca..e6584369e5a 100644 --- a/doc/administration/audit_event_streaming/graphql_api.md +++ b/doc/administration/audit_event_streaming/graphql_api.md @@ -4,7 +4,7 @@ group: Compliance 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 --- -# Audit event streaming GraphQL API **(ULTIMATE)** +# Audit event streaming GraphQL API **(ULTIMATE ALL)** > - API [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332747) in GitLab 14.5 [with a flag](../feature_flags.md) named `ff_external_audit_events_namespace`. Disabled by default. > - API [Enabled on GitLab.com and by default on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338939) in GitLab 14.7. @@ -19,15 +19,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w Audit event streaming destinations can be maintained using a GraphQL API. -## Add a new streaming destination +## Top-level group streaming destinations -Add a new streaming destination to top-level groups or an entire instance. +Manage streaming destinations for top-level groups. + +### HTTP destinations + +Manage HTTP streaming destinations for top-level groups. + +#### Add a new streaming destination + +Add a new streaming destination to top-level groups. WARNING: Streaming destinations receive **all** audit event data, which could include sensitive information. Make sure you trust the streaming destination. -### Top-level group streaming destinations - Prerequisites: - Owner role for a top-level group. @@ -113,197 +119,234 @@ mutation { The header is created if the returned `errors` object is empty. -### Instance streaming destinations - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335175) in GitLab 16.0 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default. -> - [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2. +#### List streaming destinations -FLAG: -On self-managed GitLab, by default this feature is enabled. To disable it, an administrator can [disable the feature flag](../feature_flags.md) named -`ff_external_audit_events`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. The feature is ready for production use. +List streaming destinations for a top-level groups. Prerequisites: -- Administrator access on the instance. +- Owner role for a top-level group. -To enable streaming and add a destination, use the -`instanceExternalAuditEventDestinationCreate` mutation in the GraphQL API. +You can view a list of streaming destinations for a top-level group using the `externalAuditEventDestinations` query +type. ```graphql -mutation { - instanceExternalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest"}) { - errors - instanceExternalAuditEventDestination { - destinationUrl - id - name - verificationToken +query { + group(fullPath: "my-group") { + id + externalAuditEventDestinations { + nodes { + destinationUrl + verificationToken + id + name + headers { + nodes { + key + value + id + } + } + eventTypeFilters + } } } } ``` -Event streaming is enabled if: +If the resulting list is empty, then audit streaming is not enabled for that group. -- The returned `errors` object is empty. -- The API responds with `200 OK`. +#### Update streaming destinations -You can optionally specify your own destination name (instead of the default GitLab-generated one) using the GraphQL -`instanceExternalAuditEventDestinationCreate` -mutation. Name length must not exceed 72 characters and trailing whitespace are not trimmed. This value should be unique. For example: +Update streaming destinations for a top-level group. + +Prerequisites: + +- Owner role for a top-level group. + +Users with the Owner role for a group can update streaming destinations' custom HTTP headers using the +`auditEventsStreamingHeadersUpdate` mutation type. You can retrieve the custom HTTP headers ID +by [listing all the custom HTTP headers](#list-streaming-destinations) for the group. ```graphql mutation { - instanceExternalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest", name: "destination-name-here"}) { + externalAuditEventDestinationUpdate(input: { + id:"gid://gitlab/AuditEvents::ExternalAuditEventDestination/1", + destinationUrl: "https://www.new-domain.com/webhook", + name: "destination-name"} ) { errors - instanceExternalAuditEventDestination { - destinationUrl + externalAuditEventDestination { id name + destinationUrl verificationToken + group { + name + } } } } ``` -Instance administrators can add an HTTP header using the GraphQL `auditEventsStreamingInstanceHeadersCreate` mutation. You can retrieve the destination ID -by [listing all the streaming destinations](#list-streaming-destinations) for the instance or from the mutation above. +Streaming destination is updated if: + +- The returned `errors` object is empty. +- The API responds with `200 OK`. + +Group owners can remove an HTTP header using the GraphQL `auditEventsStreamingHeadersDestroy` mutation. You can retrieve the header ID +by [listing all the custom HTTP headers](#list-streaming-destinations) for the group. ```graphql mutation { - auditEventsStreamingInstanceHeadersCreate(input: - { - destinationId: "gid://gitlab/AuditEvents::InstanceExternalAuditEventDestination/42", - key: "foo", - value: "bar" - }) { + auditEventsStreamingHeadersDestroy(input: { headerId: "gid://gitlab/AuditEvents::Streaming::Header/1" }) { errors - header { - id - key - value - } } } ``` -The header is created if the returned `errors` object is empty. +The header is deleted if the returned `errors` object is empty. -### Google Cloud Logging streaming +#### Delete streaming destinations -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) in GitLab 16.1. +Delete streaming destinations for a top-level group. + +When the last destination is successfully deleted, streaming is disabled for the group. Prerequisites: - Owner role for a top-level group. -- A Google Cloud project with the necessary permissions to create service accounts and enable Google Cloud Logging. -To enable streaming and add a configuration, use the -`googleCloudLoggingConfigurationCreate` mutation in the GraphQL API. +Users with the Owner role for a group can delete streaming destinations using the +`externalAuditEventDestinationDestroy` mutation type. You can retrieve the destinations ID +by [listing all the streaming destinations](#list-streaming-destinations) for the group. ```graphql mutation { - googleCloudLoggingConfigurationCreate(input: { groupPath: "my-group", googleProjectIdName: "my-google-project", clientEmail: "my-email@my-google-project.iam.gservice.account.com", privateKey: "YOUR_PRIVATE_KEY", logIdName: "audit-events" } ) { - errors - googleCloudLoggingConfiguration { - id - googleProjectIdName - logIdName - privateKey - clientEmail - } + externalAuditEventDestinationDestroy(input: { id: destination }) { errors } } ``` -Event streaming is enabled if: +Streaming destination is deleted if: - The returned `errors` object is empty. - The API responds with `200 OK`. -## List streaming destinations +Group owners can remove an HTTP header using the GraphQL `auditEventsStreamingHeadersDestroy` mutation. You can retrieve the header ID +by [listing all the custom HTTP headers](#list-streaming-destinations) for the group. -List new streaming destinations for top-level groups or an entire instance. +```graphql +mutation { + auditEventsStreamingHeadersDestroy(input: { headerId: "gid://gitlab/AuditEvents::Streaming::Header/1" }) { + errors + } +} +``` -### Top-level group streaming destinations +The header is deleted if the returned `errors` object is empty. + +#### Event type filters + +> Event type filters API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344845) in GitLab 15.7. + +When this feature is enabled for a group, you can use an API to permit users to filter streamed audit events per destination. +If the feature is enabled with no filters, the destination receives all audit events. + +A streaming destination that has an event type filter set has a **filtered** (**{filter}**) label. + +##### Use the API to add an event type filter Prerequisites: -- Owner role for a top-level group. +- You must have the Owner role for the group. -You can view a list of streaming destinations for a top-level group using the `externalAuditEventDestinations` query -type. +You can add a list of event type filters using the `auditEventsStreamingDestinationEventsAdd` query type: ```graphql -query { - group(fullPath: "my-group") { - id - externalAuditEventDestinations { - nodes { - destinationUrl - verificationToken - id - name - headers { - nodes { - key - value - id - } - } +mutation { + auditEventsStreamingDestinationEventsAdd(input: { + destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1", + eventTypeFilters: ["list of event type filters"]}){ + errors eventTypeFilters - } } +} +``` + +Event type filters are added if: + +- The returned `errors` object is empty. +- The API responds with `200 OK`. + +##### Use the API to remove an event type filter + +Prerequisites: + +- You must have the Owner role for the group. + +You can remove a list of event type filters using the `auditEventsStreamingDestinationEventsRemove` mutation type: + +```graphql +mutation { + auditEventsStreamingDestinationEventsRemove(input: { + destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1", + eventTypeFilters: ["list of event type filters"] + }){ + errors } } ``` -If the resulting list is empty, then audit streaming is not enabled for that group. +Event type filters are removed if: -### Instance streaming destinations +- The returned `errors` object is empty. +- The API responds with `200 OK`. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335175) in GitLab 16.0 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default. -> - [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2. +### Google Cloud Logging destinations -FLAG: -On self-managed GitLab, by default this feature is enabled. To disable it, an administrator can [disable the feature flag](../feature_flags.md) named -`ff_external_audit_events`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. The feature is ready for production use. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) in GitLab 16.1. + +Manage Google Cloud Logging destinations for top-level groups. + +Before setting up Google Cloud Logging streaming audit events, you must satisfy [the prerequisites](index.md#prerequisites). + +#### Add a new Google Cloud Logging destination + +Add a new Google Cloud Logging configuration destination to a top-level group. Prerequisites: -- Administrator access on the instance. +- Owner role for a top-level group. +- A Google Cloud project with the necessary permissions to create service accounts and enable Google Cloud Logging. -To view a list of streaming destinations for an instance, use the -`instanceExternalAuditEventDestinations` query type. +To enable streaming and add a configuration, use the +`googleCloudLoggingConfigurationCreate` mutation in the GraphQL API. ```graphql -query { - instanceExternalAuditEventDestinations { - nodes { +mutation { + googleCloudLoggingConfigurationCreate(input: { groupPath: "my-group", googleProjectIdName: "my-google-project", clientEmail: "my-email@my-google-project.iam.gservice.account.com", privateKey: "YOUR_PRIVATE_KEY", logIdName: "audit-events" } ) { + errors + googleCloudLoggingConfiguration { id - name - destinationUrl - verificationToken - headers { - nodes { - id - key - value - } - } + googleProjectIdName + logIdName + privateKey + clientEmail } + errors } } ``` -If the resulting list is empty, then audit streaming is not enabled for the instance. +Event streaming is enabled if: -You need the ID values returned by this query for the update and delete mutations. +- The returned `errors` object is empty. +- The API responds with `200 OK`. -### Google Cloud Logging configurations +#### List Google Cloud Logging configurations -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) in GitLab 16.1. +List all Google Cloud Logging configuration destinations for a top-level group. Prerequisite: @@ -333,59 +376,68 @@ If the resulting list is empty, then audit streaming is not enabled for the grou You need the ID values returned by this query for the update and delete mutations. -## Update streaming destinations - -Update streaming destinations for a top-level group or an entire instance. +#### Update Google Cloud Logging configurations -### Top-level group streaming destinations +Update a Google Cloud Logging configuration destinations for a top-level group. -Prerequisites: +Prerequisite: - Owner role for a top-level group. -Users with the Owner role for a group can update streaming destinations' custom HTTP headers using the -`auditEventsStreamingHeadersUpdate` mutation type. You can retrieve the custom HTTP headers ID -by [listing all the custom HTTP headers](#list-streaming-destinations) for the group. +To update streaming configuration for a top-level group, use the +`googleCloudLoggingConfigurationUpdate` mutation type. You can retrieve the configuration ID +by [listing all the external destinations](#list-streaming-destinations). ```graphql mutation { - externalAuditEventDestinationUpdate(input: { - id:"gid://gitlab/AuditEvents::ExternalAuditEventDestination/1", - destinationUrl: "https://www.new-domain.com/webhook", - name: "destination-name"} ) { + googleCloudLoggingConfigurationUpdate( + input: {id: "gid://gitlab/AuditEvents::GoogleCloudLoggingConfiguration/1", googleProjectIdName: "my-google-project", clientEmail: "my-email@my-google-project.iam.gservice.account.com", privateKey: "YOUR_PRIVATE_KEY", logIdName: "audit-events"} + ) { errors - externalAuditEventDestination { + googleCloudLoggingConfiguration { id - name - destinationUrl - verificationToken - group { - name - } + logIdName + privateKey + googleProjectIdName + clientEmail } } } ``` -Streaming destination is updated if: +Streaming configuration is updated if: - The returned `errors` object is empty. - The API responds with `200 OK`. -Group owners can remove an HTTP header using the GraphQL `auditEventsStreamingHeadersDestroy` mutation. You can retrieve the header ID -by [listing all the custom HTTP headers](#list-streaming-destinations) for the group. +#### Delete Google Cloud Logging configurations + +Delete streaming destinations for a top-level group. + +When the last destination is successfully deleted, streaming is disabled for the group. + +Prerequisite: + +- Owner role for a top-level group. + +Users with the Owner role for a group can delete streaming configurations using the +`googleCloudLoggingConfigurationDestroy` mutation type. You can retrieve the configurations ID +by [listing all the streaming destinations](#list-streaming-destinations) for the group. ```graphql mutation { - auditEventsStreamingHeadersDestroy(input: { headerId: "gid://gitlab/AuditEvents::Streaming::Header/1" }) { + googleCloudLoggingConfigurationDestroy(input: { id: "gid://gitlab/AuditEvents::GoogleCloudLoggingConfiguration/1" }) { errors } } ``` -The header is deleted if the returned `errors` object is empty. +Streaming configuration is deleted if: -### Instance streaming destinations +- The returned `errors` object is empty. +- The API responds with `200 OK`. + +## Instance streaming destinations **(ULTIMATE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335175) in GitLab 16.0 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default. > - [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2. @@ -394,20 +446,22 @@ FLAG: On self-managed GitLab, by default this feature is enabled. To disable it, an administrator can [disable the feature flag](../feature_flags.md) named `ff_external_audit_events`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. The feature is ready for production use. +Manage HTTP streaming destinations for an entire instance. + +### Add a new HTTP destination + +Add a new HTTP streaming destination to an instance. + Prerequisites: - Administrator access on the instance. -To update streaming destinations for an instance, use the -`instanceExternalAuditEventDestinationUpdate` mutation type. You can retrieve the destination ID -by [listing all the external destinations](#list-streaming-destinations) for the instance. +To enable streaming and add a destination, use the +`instanceExternalAuditEventDestinationCreate` mutation in the GraphQL API. ```graphql mutation { - instanceExternalAuditEventDestinationUpdate(input: { - id: "gid://gitlab/AuditEvents::InstanceExternalAuditEventDestination/1", - destinationUrl: "https://www.new-domain.com/webhook", - name: "destination-name"}) { + instanceExternalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest"}) { errors instanceExternalAuditEventDestination { destinationUrl @@ -419,18 +473,40 @@ mutation { } ``` -Streaming destination is updated if: +Event streaming is enabled if: - The returned `errors` object is empty. - The API responds with `200 OK`. -Instance administrators can update streaming destinations custom HTTP headers using the -`auditEventsStreamingInstanceHeadersUpdate` mutation type. You can retrieve the custom HTTP headers ID -by [listing all the custom HTTP headers](#list-streaming-destinations) for the instance. +You can optionally specify your own destination name (instead of the default GitLab-generated one) using the GraphQL +`instanceExternalAuditEventDestinationCreate` +mutation. Name length must not exceed 72 characters and trailing whitespace are not trimmed. This value should be unique. For example: ```graphql mutation { - auditEventsStreamingInstanceHeadersUpdate(input: { headerId: "gid://gitlab/AuditEvents::Streaming::InstanceHeader/2", key: "new-key", value: "new-value" }) { + instanceExternalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest", name: "destination-name-here"}) { + errors + instanceExternalAuditEventDestination { + destinationUrl + id + name + verificationToken + } + } +} +``` + +Instance administrators can add an HTTP header using the GraphQL `auditEventsStreamingInstanceHeadersCreate` mutation. You can retrieve the destination ID +by [listing all the streaming destinations](#list-streaming-destinations) for the instance or from the mutation above. + +```graphql +mutation { + auditEventsStreamingInstanceHeadersCreate(input: + { + destinationId: "gid://gitlab/AuditEvents::InstanceExternalAuditEventDestination/42", + key: "foo", + value: "bar" + }) { errors header { id @@ -441,92 +517,102 @@ mutation { } ``` -The header is updated if the returned `errors` object is empty. +The header is created if the returned `errors` object is empty. -### Google Cloud Logging configurations +### List streaming destinations -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) in GitLab 16.1. +List all HTTP streaming destinations for an instance. -Prerequisite: +Prerequisites: -- Owner role for a top-level group. +- Administrator access on the instance. -To update streaming configuration for a top-level group, use the -`googleCloudLoggingConfigurationUpdate` mutation type. You can retrieve the configuration ID -by [listing all the external destinations](#list-streaming-destinations). +To view a list of streaming destinations for an instance, use the +`instanceExternalAuditEventDestinations` query type. ```graphql -mutation { - googleCloudLoggingConfigurationUpdate( - input: {id: "gid://gitlab/AuditEvents::GoogleCloudLoggingConfiguration/1", googleProjectIdName: "my-google-project", clientEmail: "my-email@my-google-project.iam.gservice.account.com", privateKey: "YOUR_PRIVATE_KEY", logIdName: "audit-events"} - ) { - errors - googleCloudLoggingConfiguration { +query { + instanceExternalAuditEventDestinations { + nodes { id - logIdName - privateKey - googleProjectIdName - clientEmail + name + destinationUrl + verificationToken + headers { + nodes { + id + key + value + } + } + eventTypeFilters } } } ``` -Streaming configuration is updated if: - -- The returned `errors` object is empty. -- The API responds with `200 OK`. - -## Delete streaming destinations +If the resulting list is empty, then audit streaming is not enabled for the instance. -Delete streaming destinations for a top-level group or an entire instance. +You need the ID values returned by this query for the update and delete mutations. -When the last destination is successfully deleted, streaming is disabled for the group or the instance. +### Update streaming destinations -### Top-level group streaming destinations +Update a HTTP streaming destination for an instance. Prerequisites: -- Owner role for a top-level group. +- Administrator access on the instance. -Users with the Owner role for a group can delete streaming destinations using the -`externalAuditEventDestinationDestroy` mutation type. You can retrieve the destinations ID -by [listing all the streaming destinations](#list-streaming-destinations) for the group. +To update streaming destinations for an instance, use the +`instanceExternalAuditEventDestinationUpdate` mutation type. You can retrieve the destination ID +by [listing all the external destinations](#list-streaming-destinations-1) for the instance. ```graphql mutation { - externalAuditEventDestinationDestroy(input: { id: destination }) { + instanceExternalAuditEventDestinationUpdate(input: { + id: "gid://gitlab/AuditEvents::InstanceExternalAuditEventDestination/1", + destinationUrl: "https://www.new-domain.com/webhook", + name: "destination-name"}) { errors + instanceExternalAuditEventDestination { + destinationUrl + id + name + verificationToken + } } } ``` -Streaming destination is deleted if: +Streaming destination is updated if: - The returned `errors` object is empty. - The API responds with `200 OK`. -Group owners can remove an HTTP header using the GraphQL `auditEventsStreamingHeadersDestroy` mutation. You can retrieve the header ID -by [listing all the custom HTTP headers](#list-streaming-destinations) for the group. +Instance administrators can update streaming destinations custom HTTP headers using the +`auditEventsStreamingInstanceHeadersUpdate` mutation type. You can retrieve the custom HTTP headers ID +by [listing all the custom HTTP headers](#list-streaming-destinations-1) for the instance. ```graphql mutation { - auditEventsStreamingHeadersDestroy(input: { headerId: "gid://gitlab/AuditEvents::Streaming::Header/1" }) { + auditEventsStreamingInstanceHeadersUpdate(input: { headerId: "gid://gitlab/AuditEvents::Streaming::InstanceHeader/2", key: "new-key", value: "new-value" }) { errors + header { + id + key + value + } } } ``` -The header is deleted if the returned `errors` object is empty. +The header is updated if the returned `errors` object is empty. -### Instance streaming destinations +### Delete streaming destinations -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335175) in GitLab 16.0 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default. -> - [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2. +Delete streaming destinations for an entire instance. -FLAG: -On self-managed GitLab, by default this feature is enabled. To disable it, an administrator can [disable the feature flag](../feature_flags.md) named -`ff_external_audit_events`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. The feature is ready for production use. +When the last destination is successfully deleted, streaming is disabled for the instance. Prerequisites: @@ -534,7 +620,7 @@ Prerequisites: To delete streaming destinations, use the `instanceExternalAuditEventDestinationDestroy` mutation type. You can retrieve the destinations ID -by [listing all the streaming destinations](#list-streaming-destinations) for the instance. +by [listing all the streaming destinations](#list-streaming-destinations-1) for the instance. ```graphql mutation { @@ -563,52 +649,27 @@ mutation { The header is deleted if the returned `errors` object is empty. -### Google Cloud Logging configurations +### Event type filters -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) in GitLab 16.1. +> Event type filters API [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10868) in GitLab 16.2. -Prerequisite: - -- Owner role for a top-level group. - -Users with the Owner role for a group can delete streaming configurations using the -`googleCloudLoggingConfigurationDestroy` mutation type. You can retrieve the configurations ID -by [listing all the streaming destinations](#list-streaming-destinations) for the group. - -```graphql -mutation { - googleCloudLoggingConfigurationDestroy(input: { id: "gid://gitlab/AuditEvents::GoogleCloudLoggingConfiguration/1" }) { - errors - } -} -``` - -Streaming configuration is deleted if: - -- The returned `errors` object is empty. -- The API responds with `200 OK`. - -## Event type filters - -> Event type filters API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344845) in GitLab 15.7. - -When this feature is enabled for a group, you can use an API to permit users to filter streamed audit events per destination. +When this feature is enabled for an instance, you can use an API to permit users to filter streamed audit events per destination. If the feature is enabled with no filters, the destination receives all audit events. A streaming destination that has an event type filter set has a **filtered** (**{filter}**) label. -### Use the API to add an event type filter +#### Use the API to add an event type filter Prerequisites: -- You must have the Owner role for the group. +- You must have the Administrator access for the instance. -You can add a list of event type filters using the `auditEventsStreamingDestinationEventsAdd` query type: +You can add a list of event type filters using the `auditEventsStreamingDestinationInstanceEventsAdd` mutation: ```graphql mutation { - auditEventsStreamingDestinationEventsAdd(input: { - destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1", + auditEventsStreamingDestinationInstanceEventsAdd(input: { + destinationId: "gid://gitlab/AuditEvents::InstanceExternalAuditEventDestination/1", eventTypeFilters: ["list of event type filters"]}){ errors eventTypeFilters @@ -621,18 +682,18 @@ Event type filters are added if: - The returned `errors` object is empty. - The API responds with `200 OK`. -### Use the API to remove an event type filter +#### Use the API to remove an event type filter Prerequisites: -- You must have the Owner role for the group. +- You must have the Administrator access for the instance. -You can remove a list of event type filters using the `auditEventsStreamingDestinationEventsRemove` query type: +You can remove a list of event type filters using the `auditEventsStreamingDestinationInstanceEventsRemove` mutation: ```graphql mutation { - auditEventsStreamingDestinationEventsRemove(input: { - destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1", + auditEventsStreamingDestinationInstanceEventsRemove(input: { + destinationId: "gid://gitlab/AuditEvents::InstanceExternalAuditEventDestination/1", eventTypeFilters: ["list of event type filters"] }){ errors diff --git a/doc/administration/audit_event_streaming/index.md b/doc/administration/audit_event_streaming/index.md index 622d29fa9a7..ae566891ac7 100644 --- a/doc/administration/audit_event_streaming/index.md +++ b/doc/administration/audit_event_streaming/index.md @@ -4,33 +4,41 @@ group: Compliance 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 --- -# Audit event streaming **(ULTIMATE)** +# Audit event streaming **(ULTIMATE ALL)** > - UI [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336411) in GitLab 14.9. > - [Subgroup events recording](https://gitlab.com/gitlab-org/gitlab/-/issues/366878) fixed in GitLab 15.2. > - Custom HTTP headers UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361630) in GitLab 15.2 [with a flag](../feature_flags.md) named `custom_headers_streaming_audit_events_ui`. Disabled by default. > - Custom HTTP headers UI [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365259) in GitLab 15.3. [Feature flag `custom_headers_streaming_audit_events_ui`](https://gitlab.com/gitlab-org/gitlab/-/issues/365259) removed. > - [Improved user experience](https://gitlab.com/gitlab-org/gitlab/-/issues/367963) in GitLab 15.3. +> - [HTTP destination **Name*** field](https://gitlab.com/gitlab-org/gitlab/-/issues/411357) added in GitLab 16.3. -Users can set a streaming destination for a top-level group or instance to receive all audit events about the group, subgroups, and -projects as structured JSON. +Users can set a streaming destination for a top-level group or instance to receive all audit events about the group, +subgroups, and projects, as structured JSON. -Top-level group owners and instance administrators can manage their audit logs in third-party systems. Any service that can receive -structured JSON data can be used as the streaming destination. +Top-level group owners and instance administrators can manage their audit logs in third-party systems. Any service that +can receive structured JSON data can be used as the streaming destination. Each streaming destination can have up to 20 custom HTTP headers included with each streamed event. -NOTE: -GitLab can stream a single event more than once to the same destination. Use the `id` key in the payload to deduplicate incoming data. +GitLab can stream a single event more than once to the same destination. Use the `id` key in the payload to deduplicate +incoming data. -## Add a new streaming destination +WARNING: +Streaming destinations receive **all** audit event data, which could include sensitive information. Make sure you trust +the streaming destination. -Add a new streaming destination to top-level groups or an entire instance. +## Top-level group streaming destinations -WARNING: -Streaming destinations receive **all** audit event data, which could include sensitive information. Make sure you trust the streaming destination. +Manage streaming destinations for top-level groups. + +### HTTP destinations + +Manage HTTP streaming destinations for top-level groups. + +#### Add a new HTTP destination -### Top-level group streaming destinations +Add a new HTTP streaming destination to a top-level group. Prerequisites: @@ -42,7 +50,7 @@ To add streaming destinations to a top-level group: 1. Select **Secure > Audit events**. 1. On the main area, select **Streams** tab. 1. Select **Add streaming destination** and select **HTTP endpoint** to show the section for adding destinations. -1. Enter the destination URL to add. +1. In the **Name** and **Destination URL** fields, add a destination name and URL. 1. Optional. Locate the **Custom HTTP headers** table. 1. Ignore the **Active** checkbox because it isn't functional. To track progress on adding functionality to the **Active** checkbox, see [issue 367509](https://gitlab.com/gitlab-org/gitlab/-/issues/367509). @@ -50,157 +58,172 @@ To add streaming destinations to a top-level group: 20 headers per streaming destination. 1. After all headers have been filled out, select **Add** to add the new streaming destination. -### Instance streaming destinations **(ULTIMATE SELF)** +#### List HTTP destinations -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398107) in GitLab 16.1 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default. -> - [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2. +Prerequisites: -FLAG: -On self-managed GitLab, by default this feature is enabled. To disable it, an administrator can [disable the feature flag](../feature_flags.md) named -`ff_external_audit_events`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. The feature is ready for production use. +- Owner role for a group. + +To list the streaming destinations for a top-level group: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Secure > Audit events**. +1. On the main area, select **Streams** tab. +1. Select the stream to expand it and see all the custom HTTP headers. + +#### Update an HTTP destination Prerequisites: -- Administrator access on the instance. +- Owner role for a group. -To add a streaming destination for an instance: +To update a streaming destination's name: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Secure > Audit events**. 1. On the main area, select **Streams** tab. -1. Select **Add streaming destination** and select **HTTP endpoint** to show the section for adding destinations. -1. Enter the destination URL to add. -1. Optional. To add custom HTTP headers, select **Add header** to create a new name and value pair, and input their values. Repeat this step for as many name and value pairs are required. You can add up to 20 headers per streaming destination. +1. Select the stream to expand. +1. In the **Name** fields, add a destination name to update. +1. Select **Save** to update the streaming destination. + +To update a streaming destination's custom HTTP headers: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Secure > Audit events**. +1. On the main area, select **Streams** tab. +1. Select the stream to expand. +1. Locate the **Custom HTTP headers** table. +1. Locate the header that you wish to update. 1. Ignore the **Active** checkbox because it isn't functional. To track progress on adding functionality to the **Active** checkbox, see [issue 367509](https://gitlab.com/gitlab-org/gitlab/-/issues/367509). -1. Select **Add header** to create a new name and value pair. Repeat this step for as many name and value pairs are required. You can add up to +1. Select **Add header** to create a new name and value pair. Enter as many name and value pairs as required. You can add up to 20 headers per streaming destination. -1. After all headers have been filled out, select **Add** to add the new streaming destination. +1. Select **Save** to update the streaming destination. -### Google Cloud Logging streaming +#### Delete an HTTP destination -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124384) in GitLab 16.2. +Delete streaming destinations for a top-level group. When the last destination is successfully deleted, streaming is +disabled for the top-level group. Prerequisites: -- Owner role for a top-level group. +- Owner role for a group. -To add Google Cloud Logging streaming destinations to a top-level group: +To delete a streaming destination: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. -1. Select **Add streaming destination** and select **Google Cloud Logging** to show the section for adding destinations. -1. Enter the Google Project ID, Google Client Email, Log ID, and Google Private Key to add. -1. Select **Add** to add the new streaming destination. +1. On the main area, select the **Streams** tab. +1. Select the stream to expand. +1. Select **Delete destination**. +1. Confirm by selecting **Delete destination** in the dialog. + +To delete only the custom HTTP headers for a streaming destination: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Secure > Audit events**. +1. On the main area, select the **Streams** tab. +1. Select the stream to expand. +1. Locate the **Custom HTTP headers** table. +1. Locate the header that you wish to remove. +1. To the right of the header, select **Delete** (**{remove}**). +1. Select **Save** to update the streaming destination. -## List streaming destinations +#### Verify event authenticity -List new streaming destinations for top-level groups or an entire instance. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360814) in GitLab 15.2. -### For top-level group streaming destinations +Each streaming destination has a unique verification token (`verificationToken`) that can be used to verify the authenticity of the event. This +token is either specified by the Owner or generated automatically when the event destination is created and cannot be changed. + +Each streamed event contains the verification token in the `X-Gitlab-Event-Streaming-Token` HTTP header that can be verified against +the destination's value when listing streaming destinations. Prerequisites: - Owner role for a group. -To list the streaming destinations for a top-level group: +To list streaming destinations and see the verification tokens: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. -1. Select the stream URL to expand it and see all the custom HTTP headers. +1. On the main area, select the **Streams**. +1. Select the stream to expand. +1. Locate the **Verification token** input. -### For instance streaming destinations +#### Update event filters -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398107) in GitLab 16.1 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default. -> - [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2. +> Event type filtering in the UI with a defined list of audit event types [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413581) in GitLab 16.1. -FLAG: -On self-managed GitLab, by default this feature is enabled. To disable it, an administrator can [disable the feature flag](../feature_flags.md) named -`ff_external_audit_events`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. The feature is ready for production use. +When this feature is enabled for a group, you can permit users to filter streamed audit events per destination. +If the feature is enabled with no filters, the destination receives all audit events. -Prerequisites: +A streaming destination that has an event type filter set has a **filtered** (**{filter}**) label. -- Administrator access on the instance. +To update a streaming destination's event filters: -To list the streaming destinations for an instance: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Secure > Audit events**. +1. On the main area, select the **Streams** tab. +1. Select the stream to expand. +1. Locate the **Filter by audit event type** dropdown list. +1. Select the dropdown list and select or clear the required event types. +1. Select **Save** to update the event filters. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +#### Override default content type header -### Google Cloud Logging streaming +By default, streaming destinations use a `content-type` header of `application/x-www-form-urlencoded`. However, you +might want to set the `content-type` header to something else. For example ,`application/json`. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124384) in GitLab 16.2. +To override the `content-type` header default value for a top-level group streaming destination, use either: -Prerequisites: +- The [GitLab UI](#update-an-http-destination). +- The [GraphQL API](graphql_api.md#update-streaming-destinations). -- Owner role for a top-level group. +### Google Cloud Logging destinations -To list Google Cloud Logging streaming destinations for a top-level group: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124384) in GitLab 16.2. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. -1. Select the Google Cloud Logging stream to expand and see all the fields. +Manage Google Cloud Logging destinations for top-level groups. + +#### Prerequisites -## Update streaming destinations +Before setting up Google Cloud Logging streaming audit events, you must: -Update streaming destinations for a top-level group or an entire instance. +1. Create a service account for Google Cloud with the appropriate credentials and permissions. This account is used to configure audit log streaming authentication. + For more information, see [Creating and managing service accounts in the Google Cloud documentation](https://cloud.google.com/iam/docs/service-accounts-create#creating). +1. Enable the **Logs Writer** role for the service account to enable logging on Google Cloud. For more information, see [Access control with IAM](https://cloud.google.com/logging/docs/access-control#logging.logWriter). +1. Create a JSON key for the service account. For more information, see [Creating a service account key](https://cloud.google.com/iam/docs/keys-create-delete#creating). -### Top-level group streaming destinations +#### Add a new Google Cloud Logging destination Prerequisites: -- Owner role for a group. +- Owner role for a top-level group. -To update a streaming destination's custom HTTP headers: +To add Google Cloud Logging streaming destinations to a top-level group: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. Select **Secure > Audit events**. 1. On the main area, select **Streams** tab. -1. Select the stream URL to expand. -1. Locate the **Custom HTTP headers** table. -1. Locate the header that you wish to update. -1. Ignore the **Active** checkbox because it isn't functional. To track progress on adding functionality to the - **Active** checkbox, see [issue 367509](https://gitlab.com/gitlab-org/gitlab/-/issues/367509). -1. Select **Add header** to create a new name and value pair. Enter as many name and value pairs as required. You can add up to - 20 headers per streaming destination. -1. Select **Save** to update the streaming destination. - -### Instance streaming destinations **(ULTIMATE SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398107) in GitLab 16.1 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default. -> - [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2. +1. Select **Add streaming destination** and select **Google Cloud Logging** to show the section for adding destinations. +1. Enter the Google Project ID, Google Client Email, Log ID, and Google Private Key to add. +1. Select **Add** to add the new streaming destination. -FLAG: -On self-managed GitLab, by default this feature is enabled. To disable it, an administrator can [disable the feature flag](../feature_flags.md) named -`ff_external_audit_events`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. The feature is ready for production use. +#### List Google Cloud Logging destinations Prerequisites: -- Administrator access on the instance. +- Owner role for a top-level group. -To update the streaming destinations for an instance: +To list Google Cloud Logging streaming destinations for a top-level group: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. Select **Secure > Audit events**. -1. On the main area, select the **Streams** tab. -1. To the right of the item, select **Edit** (**{pencil}**). -1. Locate the **Custom HTTP headers** table. -1. Locate the header that you wish to update. -1. Ignore the **Active** checkbox because it isn't functional. To track progress on adding functionality to the - **Active** checkbox, see [issue 367509](https://gitlab.com/gitlab-org/gitlab/-/issues/367509). -1. Select **Add header** to create a new name and value pair. Enter as many name and value pairs as required. You can add up to - 20 headers per streaming destination. -1. Select **Save** to update the streaming destination. - -### Google Cloud Logging streaming +1. On the main area, select **Streams** tab. +1. Select the Google Cloud Logging stream to expand and see all the fields. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124384) in GitLab 16.2. +#### Update a Google Cloud Logging destination Prerequisites: @@ -215,38 +238,22 @@ To update Google Cloud Logging streaming destinations to a top-level group: 1. Enter the Google Project ID, Google Client Email, Log ID, and Google Private Key to update. 1. Select **Save** to update the streaming destination. -## Delete streaming destinations - -Delete streaming destinations for a top-level group or an entire instance. When the last destination is successfully -deleted, streaming is disabled for the group or the instance. - -### Top-level group streaming destinations +#### Delete a Google Cloud Logging streaming destination Prerequisites: -- Owner role for a group. +- Owner role for a top-level group. -To delete a streaming destination: +To delete Google Cloud Logging streaming destinations to a top-level group: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. Select **Secure > Audit events**. 1. On the main area, select the **Streams** tab. -1. Select the stream URL to expand. +1. Select the Google Cloud Logging stream to expand. 1. Select **Delete destination**. -1. Confirm by selecting **Delete destination** in the modal. - -To delete only the custom HTTP headers for a streaming destination: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. Select **Secure > Audit events**. -1. On the main area, select the **Streams** tab. -1. Select the stream URL to expand. -1. Locate the **Custom HTTP headers** table. -1. Locate the header that you wish to remove. -1. To the right of the header, select **Delete** (**{remove}**). -1. Select **Save** to update the streaming destination. +1. Confirm by selecting **Delete destination** in the dialog. -### Instance streaming destinations +## Instance streaming destinations **(ULTIMATE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398107) in GitLab 16.1 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default. > - [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2. @@ -255,76 +262,108 @@ FLAG: On self-managed GitLab, by default this feature is enabled. To disable it, an administrator can [disable the feature flag](../feature_flags.md) named `ff_external_audit_events`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. The feature is ready for production use. +Manage HTTP streaming destinations for an entire instance. + +### Add a new HTTP destination + +Add a new HTTP streaming destination to an instance. + Prerequisites: - Administrator access on the instance. -To delete the streaming destinations for an instance: +To add a streaming destination for an instance: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. 1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select the **Streams** tab. -1. Select the stream URL to expand. -1. Select **Delete destination**. -1. Confirm by selecting **Delete destination** in the modal. +1. On the main area, select **Streams** tab. +1. Select **Add streaming destination** and select **HTTP endpoint** to show the section for adding destinations. +1. In the **Name** and **Destination URL** fields, add a destination name and URL. +1. Optional. To add custom HTTP headers, select **Add header** to create a new name and value pair, and input their values. Repeat this step for as many name and value pairs are required. You can add up to 20 headers per streaming destination. +1. Ignore the **Active** checkbox because it isn't functional. To track progress on adding functionality to the + **Active** checkbox, see [issue 367509](https://gitlab.com/gitlab-org/gitlab/-/issues/367509). +1. Select **Add header** to create a new name and value pair. Repeat this step for as many name and value pairs are required. You can add up to + 20 headers per streaming destination. +1. After all headers have been filled out, select **Add** to add the new streaming destination. -To delete only the custom HTTP headers for a streaming destination: +### List HTTP destinations + +Prerequisites: + +- Administrator access on the instance. + +To list the streaming destinations for an instance: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. 1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select the **Streams** tab. -1. To the right of the item, **Edit** (**{pencil}**). -1. Locate the **Custom HTTP headers** table. -1. Locate the header that you wish to remove. -1. To the right of the header, select **Delete** (**{remove}**). -1. Select **Save** to update the streaming destination. - -### Google Cloud Logging streaming +1. On the main area, select **Streams** tab. +1. Select the stream to expand it and see all the custom HTTP headers. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124384) in GitLab 16.2. +### Update an HTTP destination Prerequisites: -- Owner role for a top-level group. +- Administrator access on the instance. -To delete Google Cloud Logging streaming destinations to a top-level group: +To update a instance streaming destination's name: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. Select **Secure > Audit events**. -1. On the main area, select the **Streams** tab. -1. Select the Google Cloud Logging stream to expand. -1. Select **Delete destination**. -1. Confirm by selecting **Delete destination** in the modal. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the main area, select **Streams** tab. +1. Select the stream to expand. +1. In the **Name** fields, add a destination name to update. +1. Select **Save** to update the streaming destination. -## Verify event authenticity +To update a instance streaming destination's custom HTTP headers: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345424) in GitLab 14.8. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the main area, select **Streams** tab. +1. Select the stream to expand. +1. Locate the **Custom HTTP headers** table. +1. Locate the header that you wish to update. +1. Ignore the **Active** checkbox because it isn't functional. To track progress on adding functionality to the + **Active** checkbox, see [issue 367509](https://gitlab.com/gitlab-org/gitlab/-/issues/367509). +1. Select **Add header** to create a new name and value pair. Enter as many name and value pairs as required. You can add up to + 20 headers per streaming destination. +1. Select **Save** to update the streaming destination. -Each streaming destination has a unique verification token (`verificationToken`) that can be used to verify the authenticity of the event. This -token is either specified by the Owner or generated automatically when the event destination is created and cannot be changed. +### Delete an HTTP destination -Each streamed event contains the verification token in the `X-Gitlab-Event-Streaming-Token` HTTP header that can be verified against -the destination's value when [listing streaming destinations](#list-streaming-destinations). +Delete streaming destinations for an entire instance. When the last destination is successfully deleted, streaming is +disabled for the instance. -### Top-level group streaming destinations +Prerequisites: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360814) in GitLab 15.2. +- Administrator access on the instance. -Prerequisites: +To delete the streaming destinations for an instance: -- Owner role for a group. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. +1. Select the stream to expand. +1. Select **Delete destination**. +1. Confirm by selecting **Delete destination** in the dialog. -To list streaming destinations and see the verification tokens: +To delete only the custom HTTP headers for a streaming destination: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. Select **Secure > Audit events**. -1. On the main area, select the **Streams**. -1. Select the stream URL to expand. -1. Locate the **Verification token** input. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. +1. To the right of the item, **Edit** (**{pencil}**). +1. Locate the **Custom HTTP headers** table. +1. Locate the header that you wish to remove. +1. To the right of the header, select **Delete** (**{remove}**). +1. Select **Save** to update the streaming destination. -### Instance streaming destinations +### Verify event authenticity > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398107) in GitLab 16.1 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default. > - [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2. @@ -333,6 +372,12 @@ FLAG: On self-managed GitLab, by default this feature is enabled. To disable it, an administrator can [disable the feature flag](../feature_flags.md) named `ff_external_audit_events`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. The feature is ready for production use. +Each streaming destination has a unique verification token (`verificationToken`) that can be used to verify the authenticity of the event. This +token is either specified by the Owner or generated automatically when the event destination is created and cannot be changed. + +Each streamed event contains the verification token in the `X-Gitlab-Event-Streaming-Token` HTTP header that can be verified against +the destination's value when listing streaming destinations. + Prerequisites: - Administrator access on the instance. @@ -342,36 +387,38 @@ To list streaming destinations for an instance and see the verification tokens: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. 1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select the **Streams**. +1. On the main area, select the **Streams** tab. 1. View the verification token on the right side of each item. -## Event type filters +### Update event filters -> Event type filtering in the UI with a defined list of audit event types [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413581) in GitLab 16.1. +> Event type filtering in the UI with a defined list of audit event types [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415013) in GitLab 16.3. -When this feature is enabled for a group, you can permit users to filter streamed audit events per destination. +When this feature is enabled, you can permit users to filter streamed audit events per destination. If the feature is enabled with no filters, the destination receives all audit events. A streaming destination that has an event type filter set has a **filtered** (**{filter}**) label. To update a streaming destination's event filters: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. Select **Secure > Audit events**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Monitoring > Audit Events**. 1. On the main area, select the **Streams** tab. -1. Select the stream URL to expand. -1. Locate the **Filter by audit event type** dropdown. +1. Select the stream to expand. +1. Locate the **Filter by audit event type** dropdown list. 1. Select the dropdown list and select or clear the required event types. 1. Select **Save** to update the event filters. -## Override default content type header +### Override default content type header By default, streaming destinations use a `content-type` header of `application/x-www-form-urlencoded`. However, you might want to set the `content-type` header to something else. For example ,`application/json`. -To override the `content-type` header default value for either a top-level group streaming destination or an instance -streaming destination, use either the [GitLab UI](#update-streaming-destinations) or using the -[GraphQL API](graphql_api.md#update-streaming-destinations). +To override the `content-type` header default value for an instance streaming destination, use either: + +- The [GitLab UI](#update-an-http-destination-1). +- The [GraphQL API](graphql_api.md#update-streaming-destinations). ## Payload schema diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index 69c97982562..9657994ba8f 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -4,7 +4,7 @@ group: Compliance 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 --- -# Audit events **(PREMIUM)** +# Audit events **(PREMIUM ALL)** Use audit events to track important events, including who performed the related action and when. You can use audit events to track, for example: @@ -77,6 +77,7 @@ To view instance audit events: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1449) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/285441) in GitLab 13.7. +> - Entity type `Gitlab::Audit::InstanceScope` for instance audit events [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418185) in GitLab 16.2. You can export the current view (including filters) of your instance audit events as a CSV file. To export the instance audit events to CSV: @@ -100,22 +101,22 @@ Data is encoded with: The first row contains the headers, which are listed in the following table along with a description of the values: -| Column | Description | -|:---------------------|:---------------------------------------------------| -| **ID** | Audit event `id`. | -| **Author ID** | ID of the author. | -| **Author Name** | Full name of the author. | -| **Entity ID** | ID of the scope. | -| **Entity Type** | Type of the scope (`Project`, `Group`, or `User`). | -| **Entity Path** | Path of the scope. | -| **Target ID** | ID of the target. | -| **Target Type** | Type of the target. | -| **Target Details** | Details of the target. | -| **Action** | Description of the action. | -| **IP Address** | IP address of the author who performed the action. | -| **Created At (UTC)** | Formatted as `YYYY-MM-DD HH:MM:SS`. | - -## View sign-in events **(FREE)** +| Column | Description | +|:---------------------|:-------------------------------------------------------------------| +| **ID** | Audit event `id`. | +| **Author ID** | ID of the author. | +| **Author Name** | Full name of the author. | +| **Entity ID** | ID of the scope. | +| **Entity Type** | Type of the scope (`Project`, `Group`, `User`, or `Gitlab::Audit::InstanceScope`). | +| **Entity Path** | Path of the scope. | +| **Target ID** | ID of the target. | +| **Target Type** | Type of the target. | +| **Target Details** | Details of the target. | +| **Action** | Description of the action. | +| **IP Address** | IP address of the author who performed the action. | +| **Created At (UTC)** | Formatted as `YYYY-MM-DD HH:MM:SS`. | + +## View sign-in events **(FREE ALL)** Successful sign-in events are the only audit events available at all tiers. To see successful sign-in events: @@ -252,10 +253,10 @@ The following actions on projects generate project audit events: [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377877) in GitLab 15.6. - Project was scheduled for deletion due to inactivity. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0. -- Project deploy token was successfully created, revoked or deleted. - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353451) in GitLab 14.9. -- Failed attempt to create a project deploy token. - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353451) in GitLab 14.9. +- Project deploy token was successfully created, revoked, or deleted. Introduced in GitLab 14.9. + GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/353451`. +- Failed attempt to create a project deploy token. Introduced in GitLab 14.9. + GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/353451`. - When [strategies for feature flags](../operations/feature_flags.md#feature-flag-strategies) are changed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68408) in GitLab 14.3. @@ -405,7 +406,7 @@ The following user actions on a GitLab instance generate instance audit events: Instance events can also be accessed using the [Instance Audit Events API](../api/audit_events.md#instance-audit-events). -#### Application settings **(PREMIUM)** +#### Application settings **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/282428) in GitLab 16.2. diff --git a/doc/administration/audit_reports.md b/doc/administration/audit_reports.md index 8e91466d345..84425dd7b89 100644 --- a/doc/administration/audit_reports.md +++ b/doc/administration/audit_reports.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: 'Learn how to create evidence artifacts typically requested by a 3rd party auditor.' --- -# Audit reports **(FREE)** +# Audit reports **(FREE ALL)** GitLab can help owners and administrators respond to auditors by generating comprehensive reports. These audit reports vary in scope, depending on the diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md index 8525b3e9b98..cbfb4921e14 100644 --- a/doc/administration/auth/atlassian.md +++ b/doc/administration/auth/atlassian.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 --- -# Atlassian OmniAuth Provider **(FREE SELF)** +# Use Atlassian as an OAuth 2.0 authentication provider **(FREE SELF)** To enable the Atlassian OmniAuth provider for passwordless authentication you must register an application with Atlassian. @@ -77,7 +77,7 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu 1. For the changes to take effect: - If you installed using the Linux package, [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). - - If you self-compiled your installation, [restart GitLab](../restart_gitlab.md#installations-from-source). + - If you self-compiled your installation, [restart GitLab](../restart_gitlab.md#self-compiled-installations). On the sign-in page there should now be an Atlassian icon below the regular sign in form. Select the icon to begin the authentication process. diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md index 8c8abf1524f..554b3d776ac 100644 --- a/doc/administration/auth/cognito.md +++ b/doc/administration/auth/cognito.md @@ -5,10 +5,10 @@ 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 --- -# Amazon Web Services Cognito **(FREE SELF)** +# Use AWS Cognito as an OAuth 2.0 authentication provider **(FREE SELF)** -Amazon Cognito lets you add user sign-up, sign-in, and access control to your GitLab instance. -The following documentation enables Cognito as an OAuth 2.0 provider. +Amazon Web Services (AWS) Cognito lets you add user sign-up, sign-in, and access control to your GitLab instance. +The following documentation enables AWS Cognito as an OAuth 2.0 provider. ## Configure AWS Cognito diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md index 08c1f5e7513..6ced9f844cd 100644 --- a/doc/administration/auth/crowd.md +++ b/doc/administration/auth/crowd.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 --- -# Atlassian Crowd OmniAuth provider (deprecated) **(FREE SELF)** +# Use Atlassian Crowd as an OAuth 2.0 authentication provider (deprecated) **(FREE SELF)** WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369117) in GitLab 15.3 and is planned for @@ -78,7 +78,7 @@ this provider also allows Crowd authentication for Git-over-https requests. 1. Change `YOUR_APP_PASSWORD` to the application password you've set. 1. Save the configuration file. 1. [Reconfigure](../restart_gitlab.md#reconfigure-a-linux-package-installation) (Linux package installations) or - [restart](../restart_gitlab.md#installations-from-source) (self-compiled installations) for the changes to take effect. + [restart](../restart_gitlab.md#self-compiled-installations) (self-compiled installations) for the changes to take effect. On the sign in page there should now be a Crowd tab in the sign in form. diff --git a/doc/administration/auth/index.md b/doc/administration/auth/index.md index 4a8e230a944..4e96cdf0411 100644 --- a/doc/administration/auth/index.md +++ b/doc/administration/auth/index.md @@ -19,7 +19,7 @@ and the following external authentication and authorization providers: NOTE: UltraAuth has removed their software which supports OmniAuth integration. We have therefore removed all references to UltraAuth integration. -## SaaS vs Self-Managed Comparison +## SaaS vs self-managed comparison The external authentication and authorization providers may support the following capabilities. For more information, see the links shown on this page for each external provider. diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md index 9a74064136a..9f95682fc47 100644 --- a/doc/administration/auth/jwt.md +++ b/doc/administration/auth/jwt.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 --- -# JWT OmniAuth provider **(FREE SELF)** +# Use JWT as an OAuth 2.0 authentication provider **(FREE SELF)** To enable the JWT OmniAuth provider, you must register your application with JWT. JWT provides you with a secret key for you to use. @@ -77,7 +77,7 @@ JWT provides you with a secret key for you to use. 1. Save the configuration file. 1. For changes to take effect, if you: - Used the Linux package to install GitLab, [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). - - Self-compiled your GitLab installation, [restart GitLab](../restart_gitlab.md#installations-from-source). + - Self-compiled your GitLab installation, [restart GitLab](../restart_gitlab.md#self-compiled-installations). On the sign in page there should now be a JWT icon below the regular sign in form. Select the icon to begin the authentication process. JWT asks the user to diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index d484059c79f..388288bbe49 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -210,7 +210,7 @@ For self-compiled installations: -----END PRIVATE KEY----- ``` -1. Save the file and [restart](../../restart_gitlab.md#installations-from-source) GitLab for the changes to take effect. +1. Save the file and [restart](../../restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. ## Using encrypted credentials diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 1905a009eb6..746d1f6b7fd 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -90,7 +90,7 @@ Here's an example of setting up LDAP with only the required options. 'port' => 636, 'uid' => 'sAMAccountName', 'encryption' => 'simple_tls', - 'base' => 'dc=example,dc=com', + 'base' => 'dc=example,dc=com' } } ``` @@ -155,7 +155,7 @@ For more information, see 'port' => 636, 'uid' => 'sAMAccountName', 'encryption' => 'simple_tls', - 'base' => 'dc=example,dc=com', + 'base' => 'dc=example,dc=com' } } ``` @@ -237,7 +237,8 @@ These configuration settings are available: ### SSL configuration settings -These SSL configuration settings are available: +SSL configuration settings can be configured under `tls_options` name/value +pairs. The following SSL configuration settings are available: | Setting | Description | Required | Examples | |---------------|-------------|----------|----------| @@ -247,6 +248,143 @@ These SSL configuration settings are available: | `cert` | Client certificate. | **{dotted-circle}** No | `'-----BEGIN CERTIFICATE----- <REDACTED> -----END CERTIFICATE -----'` | | `key` | Client private key. | **{dotted-circle}** No | `'-----BEGIN PRIVATE KEY----- <REDACTED> -----END PRIVATE KEY -----'` | +The examples below illustrate how to set `ca_file` and `ssl_version` in `tls_options`: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['ldap_enabled'] = true + gitlab_rails['ldap_servers'] = { + 'main' => { + 'label' => 'LDAP', + 'host' => 'ldap.mydomain.com', + 'port' => 636, + 'uid' => 'sAMAccountName', + 'encryption' => 'simple_tls', + 'base' => 'dc=example,dc=com' + 'tls_options' => { + 'ca_file' => '/path/to/ca_file.pem', + 'ssl_version' => 'TLSv1_2' + } + } + } + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + ldap: + servers: + main: + label: 'LDAP' + host: 'ldap.mydomain.com' + port: 636 + uid: 'sAMAccountName' + base: 'dc=example,dc=com' + encryption: 'simple_tls' + tls_options: + ca_file: '/path/to/ca_file.pem' + ssl_version: 'TLSv1_2' + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +For more information, see +[how to configure LDAP for a GitLab instance that was installed by using the Helm chart](https://docs.gitlab.com/charts/charts/globals.html#ldap). + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['ldap_enabled'] = true + gitlab_rails['ldap_servers'] = { + 'main' => { + 'label' => 'LDAP', + 'host' => 'ldap.mydomain.com', + 'port' => 636, + 'uid' => 'sAMAccountName', + 'encryption' => 'simple_tls', + 'base' => 'dc=example,dc=com', + 'tls_options' => { + 'ca_file' => '/path/to/ca_file.pem', + 'ssl_version' => 'TLSv1_2' + } + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + ldap: + enabled: true + servers: + main: + label: 'LDAP' + host: 'ldap.mydomain.com' + port: 636 + uid: 'sAMAccountName' + encryption: 'simple_tls' + base: 'dc=example,dc=com' + tls_options: + ca_file: '/path/to/ca_file.pem' + ssl_version: 'TLSv1_2' + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs + ### Attribute configuration settings GitLab uses these LDAP attributes to create an account for the LDAP user. The specified diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md index d48de109bd0..8ef95872ad4 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.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 --- -# OpenID Connect OmniAuth provider **(FREE SELF)** +# Use OpenID Connect as an OAuth 2.0 authentication provider **(FREE SELF)** GitLab can use [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) as an OmniAuth provider. @@ -22,7 +22,7 @@ The OpenID Connect provides you with a client's details and secret for you to us sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab @@ -187,7 +187,7 @@ The OpenID Connect provides you with a client's details and secret for you to us 1. For changes to take effect, if you: - Used the Linux package to install GitLab, [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). - - Self-compiled your GitLab installation, [restart GitLab](../restart_gitlab.md#installations-from-source). + - Self-compiled your GitLab installation, [restart GitLab](../restart_gitlab.md#self-compiled-installations). On the sign in page, you have an OpenID Connect option below the regular sign in form. Select this option to begin the authentication process. The OpenID Connect provider @@ -581,7 +581,7 @@ gitlab_rails['omniauth_providers'] = [ ] ``` -Example installations from source configuration (file path: `config/gitlab.yml`): +Example configuration for self-compiled installations (file path: `config/gitlab.yml`): ```yaml - { name: 'openid_connect', # do not change this parameter @@ -750,7 +750,7 @@ def sync_missing_provider(self, user: User, extern_uid: str) For more information, see the [GitLab API user method documentation](https://python-gitlab.readthedocs.io/en/stable/gl_objects/users.html#examples). -## Configure users based on OIDC group membership **(PREMIUM)** +## Configure users based on OIDC group membership **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209898) in GitLab 15.10. @@ -774,7 +774,9 @@ response to require users to be members of a certain group, configure GitLab to If you do not set `required_groups` or leave the setting empty, any user authenticated by the IdP through OIDC can use GitLab. -For Linux package installations: +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb`: @@ -808,7 +810,7 @@ For Linux package installations: 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. -For self-compiled installations: +:::TabTitle Self-compiled (source) 1. Edit `/home/git/gitlab/config/gitlab.yml`: @@ -839,9 +841,11 @@ For self-compiled installations: } ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#installations-from-source) +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. +::EndTabs + ### External groups Your IdP must pass group information to GitLab in the OIDC response. To use this @@ -853,7 +857,9 @@ based on group membership, configure GitLab to identify: [external user](../external_users.md), using the `external_groups` setting. -For Linux package installations: +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb`: @@ -887,7 +893,7 @@ For Linux package installations: 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. -For self-compiled installations: +:::TabTitle Self-compiled (source) 1. Edit `/home/git/gitlab/config/gitlab.yml`: @@ -918,9 +924,11 @@ For self-compiled installations: } ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#installations-from-source) +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. +::EndTabs + ### Auditor groups **(PREMIUM SELF)** Your IdP must pass group information to GitLab in the OIDC response. To use this @@ -930,7 +938,9 @@ response to assign users as auditors based on group membership, configure GitLab - Which group memberships grant the user auditor access, using the `auditor_groups` setting. -For Linux package installations: +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb`: @@ -964,7 +974,7 @@ For Linux package installations: 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. -For self-compiled installations: +:::TabTitle Self-compiled (source) 1. Edit `/home/git/gitlab/config/gitlab.yml`: @@ -995,9 +1005,11 @@ For self-compiled installations: } ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#installations-from-source) +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. +::EndTabs + ### Administrator groups Your IdP must pass group information to GitLab in the OIDC response. To use this @@ -1007,7 +1019,9 @@ response to assign users as administrator based on group membership, configure G - Which group memberships grant the user administrator access, using the `admin_groups` setting. -For Linux package installations: +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb`: @@ -1041,7 +1055,7 @@ For Linux package installations: 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. -For self-compiled installations: +:::TabTitle Self-compiled (source) 1. Edit `/home/git/gitlab/config/gitlab.yml`: @@ -1072,9 +1086,11 @@ For self-compiled installations: } ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#installations-from-source) +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. +::EndTabs + ## Troubleshooting 1. Ensure `discovery` is set to `true`. If you set it to `false`, you must diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md index 5802db78dd6..1662639dd29 100644 --- a/doc/administration/auth/smartcard.md +++ b/doc/administration/auth/smartcard.md @@ -230,7 +230,7 @@ For self-compiled installations: Assign a value to at least one of the following variables: `client_certificate_required_host` or `client_certificate_required_port`. -1. Save the file and [restart](../restart_gitlab.md#installations-from-source) +1. Save the file and [restart](../restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. ### Additional steps when using SAN extensions @@ -260,7 +260,7 @@ For self-compiled installations: san_extensions: true ``` -1. Save the file and [restart](../restart_gitlab.md#installations-from-source) +1. Save the file and [restart](../restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. ### Additional steps when authenticating against an LDAP server @@ -297,7 +297,7 @@ For self-compiled installations: smartcard_auth: optional ``` -1. Save the file and [restart](../restart_gitlab.md#installations-from-source) +1. Save the file and [restart](../restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. ### Require browser session with smartcard sign-in for Git access @@ -325,7 +325,7 @@ For self-compiled installations: required_for_git_access: true ``` -1. Save the file and [restart](../restart_gitlab.md#installations-from-source) +1. Save the file and [restart](../restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. ## Passwords for users created via smartcard authentication diff --git a/doc/administration/auth/test_oidc_oauth.md b/doc/administration/auth/test_oidc_oauth.md index 95cca1ced86..be0ea5c963e 100644 --- a/doc/administration/auth/test_oidc_oauth.md +++ b/doc/administration/auth/test_oidc_oauth.md @@ -4,7 +4,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 --- -# Test OIDC/OAuth in GitLab **(FREE)** +# Test OIDC/OAuth in GitLab **(FREE SELF)** To test OIDC/OAuth in GitLab, you must: diff --git a/doc/administration/backup_restore/backup_gitlab.md b/doc/administration/backup_restore/backup_gitlab.md index 24b7b453517..dc0724dc561 100644 --- a/doc/administration/backup_restore/backup_gitlab.md +++ b/doc/administration/backup_restore/backup_gitlab.md @@ -18,7 +18,9 @@ As a rough guideline, if you are using a [1k reference architecture](../referenc ## Scaling backups -As the volume of GitLab data grows, the [backup command](#backup-command) takes longer to execute. At some point, the execution time becomes impractical. For example, it can take 24 hours or more. +As the volume of GitLab data grows, the [backup command](#backup-command) takes longer to execute. [Backup options](#backup-options) such as [back up Git repositories concurrently](#back-up-git-repositories-concurrently) and [incremental repository backups](#incremental-repository-backups) can help to reduce execution time. At some point, the backup command becomes impractical by itself. For example, it can take 24 hours or more. + +In some cases, architecture changes may be warranted to allow backups to scale. If you are using a GitLab reference architecture, see [Back up and restore large reference architectures](backup_large_reference_architectures.md). For more information, see [alternative backup strategies](#alternative-backup-strategies). @@ -27,6 +29,7 @@ For more information, see [alternative backup strategies](#alternative-backup-st - [PostgreSQL databases](#postgresql-databases) - [Git repositories](#git-repositories) - [Blobs](#blobs) +- [Container Registry](#container-registry) - [Configuration files](#storing-configuration-files) - [Other data](#other-data) @@ -87,6 +90,25 @@ The [backup command](#backup-command) doesn't back up blobs that aren't stored o - [Amazon S3 backups](https://docs.aws.amazon.com/aws-backup/latest/devguide/s3-backups.html) - [Google Cloud Storage Transfer Service](https://cloud.google.com/storage-transfer-service) and [Google Cloud Storage Object Versioning](https://cloud.google.com/storage/docs/object-versioning) +### Container Registry + +[GitLab Container Registry](../packages/container_registry.md) storage can be configured in either: + +- The file system in a specific location. +- An [Object Storage](../object_storage.md) solution. Object Storage solutions can be: + - Cloud based like Amazon S3 and Google Cloud Storage. + - Hosted by you (like MinIO). + - A Storage Appliance that exposes an Object Storage-compatible API. + +The backup command backs up registry data when they are stored in the default location on the file system. + +#### Object storage + +The [backup command](#backup-command) doesn't back up blobs that aren't stored on the file system. If you're using [object storage](../object_storage.md), be sure to enable backups with your object storage provider. For example, see: + +- [Amazon S3 backups](https://docs.aws.amazon.com/aws-backup/latest/devguide/s3-backups.html) +- [Google Cloud Storage Transfer Service](https://cloud.google.com/storage-transfer-service) and [Google Cloud Storage Object Versioning](https://cloud.google.com/storage/docs/object-versioning) + ### Storing configuration files WARNING: @@ -684,7 +706,7 @@ if you see a `411 Length Required` error message after attempting to upload, you may need to downgrade the `aws_signature_version` value from the default value to `2`, [due to this issue](https://github.com/fog/fog-aws/issues/428). -For installations from source: +For self-compiled installations: 1. Edit `home/git/gitlab/config/gitlab.yml`: @@ -724,7 +746,7 @@ For installations from source: # server_side_encryption_kms_key_id: 'arn:aws:kms:YOUR-KEY-ID-HERE' ``` -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect If you're uploading your backups to S3, you should create a new @@ -813,7 +835,7 @@ For the Linux package (Omnibus): 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect -For installations from source: +For self-compiled installations: 1. Edit `home/git/gitlab/config/gitlab.yml`: @@ -827,7 +849,7 @@ For installations from source: remote_directory: 'my.google.bucket' ``` -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect ##### Using Azure Blob storage @@ -867,7 +889,7 @@ For installations from source: remote_directory: '<AZURE BLOB CONTAINER>' ``` -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect ::EndTabs @@ -928,8 +950,8 @@ Because file system performance may affect overall GitLab performance, Don't set the following configuration keys to the same path: -- `gitlab_rails['backup_path']` (`backup.path` for source installations). -- `gitlab_rails['backup_upload_connection'].local_root` (`backup.upload.connection.local_root` for source installations). +- `gitlab_rails['backup_path']` (`backup.path` for self-compiled installations). +- `gitlab_rails['backup_upload_connection'].local_root` (`backup.upload.connection.local_root` for self-compiled installations). The `backup_path` configuration key sets the local location of the backup file. The `upload` configuration key is intended for use when the backup file is uploaded to a separate server, perhaps for archival purposes. @@ -976,7 +998,7 @@ remaining after the failed upload attempt. remote_directory: 'gitlab_backups' ``` -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ::EndTabs @@ -1011,7 +1033,7 @@ setting. archive_permissions: 0644 # Makes the backup archives world-readable ``` -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ::EndTabs @@ -1102,7 +1124,7 @@ storage (for example, [AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/user- keep_time: 604800 ``` -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ::EndTabs @@ -1381,13 +1403,13 @@ after which users must reactivate 2FA. sudo gitlab-rails dbconsole --database main ``` - For installations from source, GitLab 14.1 and earlier: + For self-compiled installations, GitLab 14.1 and earlier: ```shell sudo -u git -H bundle exec rails dbconsole -e production ``` - For installations from source, GitLab 14.2 and later: + For self-compiled installations, GitLab 14.2 and later: ```shell sudo -u git -H bundle exec rails dbconsole -e production --database main @@ -1434,13 +1456,13 @@ You may need to reconfigure or restart GitLab for the changes to take effect. sudo gitlab-rails dbconsole --database main ``` - For installations from source, GitLab 14.1 and earlier: + For self-compiled installations, GitLab 14.1 and earlier: ```shell sudo -u git -H bundle exec rails dbconsole -e production ``` - For installations from source, GitLab 14.2 and later: + For self-compiled installations, GitLab 14.2 and later: ```shell sudo -u git -H bundle exec rails dbconsole -e production --database main @@ -1483,13 +1505,13 @@ You may need to reconfigure or restart GitLab for the changes to take effect. sudo gitlab-rails dbconsole --database main ``` - For installations from source, GitLab 14.1 and earlier: + For self-compiled installations, GitLab 14.1 and earlier: ```shell sudo -u git -H bundle exec rails dbconsole -e production ``` - For installations from source, GitLab 14.2 and later: + For self-compiled installations, GitLab 14.2 and later: ```shell sudo -u git -H bundle exec rails dbconsole -e production --database main @@ -1538,13 +1560,13 @@ You should verify that the secrets are the root cause before deleting any data. sudo gitlab-rails dbconsole --database main ``` - For installations from source, GitLab 14.1 and earlier: + For self-compiled installations, GitLab 14.1 and earlier: ```shell sudo -u git -H bundle exec rails dbconsole -e production ``` - For installations from source, GitLab 14.2 and later: + For self-compiled installations, GitLab 14.2 and later: ```shell sudo -u git -H bundle exec rails dbconsole -e production --database main @@ -1673,13 +1695,13 @@ Truncate the filenames in the `uploads` table: sudo gitlab-rails dbconsole ``` - For installations from source, GitLab 14.2 and later: + For self-compiled installations, GitLab 14.2 and later: ```shell sudo -u git -H bundle exec rails dbconsole -e production --database main ``` - For installations from source, GitLab 14.1 and earlier: + For self-compiled installations, GitLab 14.1 and earlier: ```shell sudo -u git -H bundle exec rails dbconsole -e production diff --git a/doc/administration/backup_restore/backup_large_reference_architectures.md b/doc/administration/backup_restore/backup_large_reference_architectures.md new file mode 100644 index 00000000000..4e11a707052 --- /dev/null +++ b/doc/administration/backup_restore/backup_large_reference_architectures.md @@ -0,0 +1,341 @@ +--- +stage: Systems +group: Geo +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 +--- + +# Back up and restore large reference architectures **(FREE SELF)** + +This document describes how to: + +- [Configure daily backups](#configure-daily-backups) +- Take a backup now (planned) +- [Restore a backup](#restore-a-backup) + +This document is intended for environments using: + +- [Linux package (Omnibus) and cloud-native hybrid reference architectures 3,000 users and up](../reference_architectures/index.md) +- [Amazon RDS](https://aws.amazon.com/rds/) for PostgreSQL data +- [Amazon S3](https://aws.amazon.com/s3/) for object storage +- [Object storage](../object_storage.md) to store everything possible, including [blobs](backup_gitlab.md#blobs) and [Container Registry](backup_gitlab.md#container-registry) + +## Configure daily backups + +### Configure backup of PostgreSQL and object storage data + +The [backup command](backup_gitlab.md) uses `pg_dump`, which is [not appropriate for databases over 100 GB](backup_gitlab.md#postgresql-databases). You must choose a PostgreSQL solution which has native, robust backup capabilities. + +[Object storage](../object_storage.md), ([not NFS](../nfs.md)) is recommended for storing GitLab data, including [blobs](backup_gitlab.md#blobs) and [Container registry](backup_gitlab.md#container-registry). + +1. [Configure AWS Backup](https://docs.aws.amazon.com/aws-backup/latest/devguide/creating-a-backup-plan.html) to back up both RDS and S3 data. For maximum protection, [configure continuous backups as well as snapshot backups](https://docs.aws.amazon.com/aws-backup/latest/devguide/point-in-time-recovery.html). +1. Configure AWS Backup to copy backups to a separate region. When AWS takes a backup, the backup can only be restored in the region the backup is stored. +1. After AWS Backup has run at least one scheduled backup, then you can [create an on-demand backup](https://docs.aws.amazon.com/aws-backup/latest/devguide/recov-point-create-on-demand-backup.html) as needed. + +### Configure backup of Git repositories + +NOTE: +There is a feature proposal to add the ability to back up repositories directly from Gitaly to object storage. See [epic 10077](https://gitlab.com/groups/gitlab-org/-/epics/10077). + +- Linux package (Omnibus): + + We will continue to use the [backup command](backup_gitlab.md#backup-command) to back up Git repositories. + + If utilization is low enough, you can run it from an existing GitLab Rails node. Otherwise, spin up another node. + +- Cloud native hybrid: + + [The `backup-utility` command in a `toolbox` pod fails when there is a large amount of data](https://gitlab.com/gitlab-org/gitlab/-/issues/396343#note_1352989908). In this case, you must run the [backup command](backup_gitlab.md#backup-command) to back up Git repositories, and you must run it in a VM running the GitLab Linux package: + + 1. Spin up a VM with 8 vCPU and 7.2 GB memory. This node will be used to back up Git repositories. Note that + [a Praefect node cannot be used to back up Git data](https://gitlab.com/gitlab-org/gitlab/-/issues/396343#note_1385950340). + 1. Configure the node as another **GitLab Rails** node as defined in your [reference architecture](../reference_architectures/index.md). As with other GitLab Rails nodes, this node must have access to your main Postgres database as well as to Gitaly Cluster. + +To back up the Git repositories: + +1. Ensure that the GitLab Rails node has enough attached storage to store Git repositories and an archive of the Git repositories. Additionally, the contents of forked repositories are duplicated into their forks during backup. + For example, if you have 5 GB worth of Git repositories and two forks of a 1 GB repository, then you require at least 14 GB of attached storage to account for: + - 7 GB of Git data. + - A 7 GB archive file of all Git data. +1. SSH into the GitLab Rails node. +1. [Configure uploading backups to remote cloud storage](backup_gitlab.md#upload-backups-to-a-remote-cloud-storage). +1. [Configure AWS Backup](https://docs.aws.amazon.com/aws-backup/latest/devguide/creating-a-backup-plan.html) for this bucket, or use a bucket in the same account and region as your production data object storage buckets, and ensure this bucket is included in your [preexisting AWS Backup](#configure-backup-of-postgresql-and-object-storage-data). +1. Run the [backup command](backup_gitlab.md#backup-command), skipping PostgreSQL data: + + ```shell + sudo gitlab-backup create SKIP=db + ``` + + The resulting tar file will include only the Git repositories and some metadata. Blobs such as uploads, artifacts, and LFS do not need to be explicitly skipped, because the command does not back up object storage by default. The tar file will be created in the [`/var/opt/gitlab/backups` directory](https://docs.gitlab.com/omnibus/settings/backups.html#creating-an-application-backup) and [the filename will end in `_gitlab_backup.tar`](backup_gitlab.md#backup-timestamp). + + Since we configured uploading backups to remote cloud storage, the tar file will be uploaded to the remote region and deleted from disk. + +1. Note the [timestamp](backup_gitlab.md#backup-timestamp) of the backup file for the next step. For example, if the backup name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`, the timestamp is `1493107454_2018_04_25_10.6.4-ce`. +1. Run the [backup command](backup_gitlab.md#backup-command) again, this time specifying [incremental backup of Git repositories](backup_gitlab.md#incremental-repository-backups), and the timestamp of the source backup file. Using the example timestamp from the previous step, the command is: + + ```shell + sudo gitlab-backup create SKIP=db INCREMENTAL=yes PREVIOUS_BACKUP=1493107454_2018_04_25_10.6.4-ce + ``` + +1. Check that the incremental backup succeeded and uploaded to object storage. +1. [Configure cron to make daily backups](backup_gitlab.md#configuring-cron-to-make-daily-backups). Edit the crontab for the `root` user: + + ```shell + sudo su - + crontab -e + ``` + +1. There, add the following line to schedule the backup for everyday at 2 AM: + + ```plaintext + 0 2 * * * /opt/gitlab/bin/gitlab-backup create SKIP=db INCREMENTAL=yes PREVIOUS_BACKUP=1493107454_2018_04_25_10.6.4-ce CRON=1 + ``` + +### Configure backup of configuration files + +If your configuration and secrets are defined outside of your deployment and then deployed into it, then the implementation of the backup strategy depends on your specific setup and requirements. As an example, you can store secrets in [AWS Secret Manager](https://aws.amazon.com/secrets-manager/) with [replication to multiple regions](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create-manage-multi-region-secrets.html) and configure a script to back up secrets automatically. + +If your configuration and secrets are only defined inside your deployment: + +1. [Storing configuration files](backup_gitlab.md#storing-configuration-files) describes how to extract configuration and secrets files. +1. These files should be uploaded to a separate, more restrictive, object storage account. + +## Restore a backup + +Restore a backup of a GitLab instance. + +### Prerequisites + +Before restoring a backup: + +1. Choose a [working destination GitLab instance](restore_gitlab.md#the-destination-gitlab-instance-must-already-be-working). +1. Ensure the destination GitLab instance is in a region where your AWS backups are stored. +1. Check that the [destination GitLab instance uses exactly the same version and type (CE or EE) of GitLab](restore_gitlab.md#the-destination-gitlab-instance-must-have-the-exact-same-version) + on which the backup data was created. For example, CE 15.1.4. +1. [Restore backed up secrets to the destination GitLab instance](restore_gitlab.md#gitlab-secrets-must-be-restored). +1. Ensure that the [destination GitLab instance has the same repository storages configured](restore_gitlab.md#certain-gitlab-configuration-must-match-the-original-backed-up-environment). + Additional storages are fine. +1. If the backed up GitLab instance had any blobs stored in object storage, + [ensure that object storage is configured for those kinds of blobs](restore_gitlab.md#certain-gitlab-configuration-must-match-the-original-backed-up-environment). +1. If the backed up GitLab instance had any blobs stored on the file system, [ensure that NFS is configured](restore_gitlab.md#certain-gitlab-configuration-must-match-the-original-backed-up-environment). +1. To use new secrets or configuration, and to avoid unexpected configuration changes during restore: + + - Linux package installations on all nodes: + 1. [Reconfigure](../restart_gitlab.md#reconfigure-a-linux-package-installation) the destination GitLab instance. + 1. [Restart](../restart_gitlab.md#restart-a-linux-package-installation) the destination GitLab instance. + + - Helm chart (Kubernetes) installations: + + 1. On all GitLab Linux package nodes, run: + + ```shell + sudo gitlab-ctl reconfigure + sudo gitlab-ctl start + ``` + + 1. Make sure you have a running GitLab instance by deploying the charts. + Ensure the Toolbox pod is enabled and running by executing the following command: + + ```shell + kubectl get pods -lrelease=RELEASE_NAME,app=toolbox + ``` + + 1. The Webservice, Sidekiq and Toolbox pods must be restarted. + The safest way to restart those pods is to run: + + ```shell + kubectl delete pods -lapp=sidekiq,release=<helm release name> + kubectl delete pods -lapp=webservice,release=<helm release name> + kubectl delete pods -lapp=toolbox,release=<helm release name> + ``` + +1. Confirm the destination GitLab instance still works. For example: + + - Make requests to the [health check endpoints](../monitoring/health_check.md). + - [Run GitLab check Rake tasks](../raketasks/maintenance.md#check-gitlab-configuration). + +1. Stop GitLab services which connect to the PostgreSQL database. + + - Linux package installations on all nodes running Puma or Sidekiq, run: + + ```shell + sudo gitlab-ctl stop + ``` + + - Helm chart (Kubernetes) installations: + + 1. Note the current number of replicas for database clients for subsequent restart: + + ```shell + kubectl get deploy -n <namespace> -lapp=sidekiq,release=<helm release name> -o jsonpath='{.items[].spec.replicas}{"\n"}' + kubectl get deploy -n <namespace> -lapp=webservice,release=<helm release name> -o jsonpath='{.items[].spec.replicas}{"\n"}' + kubectl get deploy -n <namespace> -lapp=prometheus,release=<helm release name> -o jsonpath='{.items[].spec.replicas}{"\n"}' + ``` + + 1. Stop the clients of the database to prevent locks interfering with the restore process: + + ```shell + kubectl scale deploy -lapp=sidekiq,release=<helm release name> -n <namespace> --replicas=0 + kubectl scale deploy -lapp=webservice,release=<helm release name> -n <namespace> --replicas=0 + kubectl scale deploy -lapp=prometheus,release=<helm release name> -n <namespace> --replicas=0 + ``` + +### Restore object storage data + +Each bucket exists as a separate backup within AWS and each backup can be restored to an existing or +new bucket. + +1. To restore buckets, an IAM role with the correct permissions is required: + + - `AWSBackupServiceRolePolicyForBackup` + - `AWSBackupServiceRolePolicyForRestores` + - `AWSBackupServiceRolePolicyForS3Restore` + - `AWSBackupServiceRolePolicyForS3Backup` + +1. If existing buckets are being used, they must have + [Access Control Lists enabled](https://docs.aws.amazon.com/AmazonS3/latest/userguide/managing-acls.html). +1. [Restore the S3 buckets using built-in tooling](https://docs.aws.amazon.com/aws-backup/latest/devguide/restoring-s3.html). +1. You can move on to [Restore PostgreSQL data](#restore-postgresql-data) while the restore job is + running. + +### Restore PostgreSQL data + +1. [Restore the AWS RDS database using built-in tooling](https://docs.aws.amazon.com/aws-backup/latest/devguide/restoring-rds.html), + which creates a new RDS instance. +1. Because the new RDS instance has a different endpoint, you must reconfigure the destination GitLab instance + to point to the new database: + + - For Linux package installations, follow + [Using a non-packaged PostgreSQL database management server](https://docs.gitlab.com/omnibus/settings/database.html#using-a-non-packaged-postgresql-database-management-server). + + - For Helm chart (Kubernetes) installations, follow + [Configure the GitLab chart with an external database](https://docs.gitlab.com/charts/advanced/external-db/index.html). + +1. Before moving on, wait until the new RDS instance is created and ready to use. + +### Restore Git repositories + +Select or create a node to restore: + +- For Linux package installations, choose a Rails node, which is a node that normally runs Puma or Sidekiq. +- For Helm chart (Kubernetes) installations, if you don't already have [a Git repository backup node](#configure-backup-of-git-repositories), + create one now: + + 1. Spin up a VM with 8 vCPU and 7.2 GB memory. + This node is used to back up and restore Git repositories because a Praefect node + [cannot be used to back up Git data](https://gitlab.com/gitlab-org/gitlab/-/issues/396343#note_1385950340). + 1. Configure the node as another **GitLab Rails** node as defined in your + [reference architecture](../reference_architectures/index.md). + As with other GitLab Rails nodes, this node must have access to your main PostgreSQL database as + well as to Gitaly Cluster. + 1. [Restore backed up secrets to the target GitLab](restore_gitlab.md#gitlab-secrets-must-be-restored). + +To restore Git repositories: + +1. Ensure the node has enough attached storage to store both the `.tar` file of Git repositories, + and its extracted data. +1. SSH into the GitLab Rails node. +1. As part of [Restore object storage data](#restore-object-storage-data), you should have restored + a bucket containing the GitLab backup `.tar` file of Git repositories. +1. Download the backup `.tar` file from its bucket into the backup directory described in the + `gitlab.rb` configuration `gitlab_rails['backup_path']`. + The default is `/var/opt/gitlab/backups`. + The backup file must be owned by the `git` user. + + ```shell + sudo cp 11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar /var/opt/gitlab/backups/ + sudo chown git:git /var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar + ``` + +1. Restore the backup, specifying the timestamp of the backup you wish to restore: + + WARNING: + The restore command requires + [additional parameters](backup_gitlab.md#back-up-and-restore-for-installations-using-pgbouncer) + when your installation is using PgBouncer, for either performance reasons or when using it with a + Patroni cluster. + + ```shell + # This command will overwrite the contents of your GitLab database! + # NOTE: "_gitlab_backup.tar" is omitted from the name + sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce + ``` + + If there's a GitLab version mismatch between your backup tar file and the installed version of + GitLab, the restore command aborts with an error message. + Install the [correct GitLab version](https://packages.gitlab.com/gitlab/), and then try again. + +1. Restart and [check](../raketasks/maintenance.md#check-gitlab-configuration) GitLab: + + - Linux package installations: + + 1. In all Puma or Sidekiq nodes, run: + + ```shell + sudo gitlab-ctl restart + ``` + + 1. In one Puma or Sidekiq node, run: + + ```shell + sudo gitlab-rake gitlab:check SANITIZE=true + ``` + + - Helm chart (Kubernetes) installations: + + 1. Start the stopped deployments, using the number of replicas noted in [Prerequisites](#prerequisites): + + ```shell + kubectl scale deploy -lapp=sidekiq,release=<helm release name> -n <namespace> --replicas=<original value> + kubectl scale deploy -lapp=webservice,release=<helm release name> -n <namespace> --replicas=<original value> + kubectl scale deploy -lapp=prometheus,release=<helm release name> -n <namespace> --replicas=<original value> + ``` + + 1. In the Toolbox pod, run: + + ```shell + sudo gitlab-rake gitlab:check SANITIZE=true + ``` + +1. Check that + [database values can be decrypted](../raketasks/check.md#verify-database-values-can-be-decrypted-using-the-current-secrets) + especially if `/etc/gitlab/gitlab-secrets.json` was restored, or if a different server is the + target for the restore: + + - For Linux package installations, in a Puma or Sidekiq node, run: + + ```shell + sudo gitlab-rake gitlab:doctor:secrets + ``` + + - For Helm chart (Kubernetes) installations, in the Toolbox pod, run: + + ```shell + sudo gitlab-rake gitlab:doctor:secrets + ``` + +1. For added assurance, you can perform + [an integrity check on the uploaded files](../raketasks/check.md#uploaded-files-integrity): + + - For Linux package installations, in a Puma or Sidekiq node, run: + + ```shell + sudo gitlab-rake gitlab:artifacts:check + sudo gitlab-rake gitlab:lfs:check + sudo gitlab-rake gitlab:uploads:check + ``` + + - For Helm chart (Kubernetes) installations, because these commands can take a long time because they iterate over all rows, run the following commands the GitLab Rails node, + rather than a Toolbox pod: + + ```shell + sudo gitlab-rake gitlab:artifacts:check + sudo gitlab-rake gitlab:lfs:check + sudo gitlab-rake gitlab:uploads:check + ``` + + If missing or corrupted files are found, it does not always mean the back up and restore process failed. + For example, the files might be missing or corrupted on the source GitLab instance. You might need to cross-reference prior backups. + If you are migrating GitLab to a new environment, you can run the same checks on the source GitLab instance to determine whether + the integrity check result is preexisting or related to the backup and restore process. + +The restoration should be complete. diff --git a/doc/administration/backup_restore/index.md b/doc/administration/backup_restore/index.md index 72a0176adc1..824fa56f443 100644 --- a/doc/administration/backup_restore/index.md +++ b/doc/administration/backup_restore/index.md @@ -60,7 +60,7 @@ To prepare the new server: 1. Install GitLab. 1. Configure by copying `/etc/gitlab` files from the old server to the new server, and update as necessary. Read the - [Omnibus configuration backup and restore instructions](https://docs.gitlab.com/omnibus/settings/backups.html) for more detail. + [Linux package installation backup and restore instructions](https://docs.gitlab.com/omnibus/settings/backups.html) for more detail. 1. If applicable, disable [incoming email](../incoming_email.md). 1. Block new CI/CD jobs from starting upon initial startup after the backup and restore. Edit `/etc/gitlab/gitlab.rb` and set the following: diff --git a/doc/administration/backup_restore/restore_gitlab.md b/doc/administration/backup_restore/restore_gitlab.md index 2cc0c68c66b..784a8708de6 100644 --- a/doc/administration/backup_restore/restore_gitlab.md +++ b/doc/administration/backup_restore/restore_gitlab.md @@ -13,18 +13,10 @@ The [restore prerequisites section](#restore-prerequisites) includes crucial information. Be sure to read and test the complete restore process at least once before attempting to perform it in a production environment. -NOTE: -You can only restore a backup to **exactly the same version and type (CE/EE)** -of GitLab on which it was created (for example CE 15.1.4). - -If your backup is a different version than the current installation, you must -[downgrade](../../update/package/downgrade.md) or [upgrade](../../update/package/index.md#upgrade-to-a-specific-version-using-the-official-repositories) your GitLab installation -before restoring the backup. - -Each backup archive contains a full self-contained backup, including those created through the [incremental repository backup procedure](backup_gitlab.md#incremental-repository-backups). To restore an incremental repository backup, use the same instructions as restoring any other regular backup archive. - ## Restore prerequisites +### The destination GitLab instance must already be working + You need to have a working GitLab installation before you can perform a restore. This is because the system user performing the restore actions (`git`) is usually not allowed to create or delete the SQL database needed to import @@ -32,6 +24,17 @@ data into (`gitlabhq_production`). All existing data is either erased (SQL) or moved to a separate directory (such as repositories and uploads). Restoring SQL data skips views owned by PostgreSQL extensions. +### The destination GitLab instance must have the exact same version + +You can only restore a backup to **exactly the same version and type (CE or EE)** +of GitLab on which it was created. For example, CE 15.1.4. + +If your backup is a different version than the current installation, you must +[downgrade](../../update/package/downgrade.md) or [upgrade](../../update/package/index.md#upgrade-to-a-specific-version-using-the-official-repositories) your GitLab installation +before restoring the backup. + +### GitLab secrets must be restored + To restore a backup, **you must also restore the GitLab secrets**. These include the database encryption key, [CI/CD variables](../../ci/variables/index.md), and variables used for [two-factor authentication](../../user/profile/account/two_factor_authentication.md). @@ -41,41 +44,37 @@ and GitLab Runners cannot log in. Restore: -- `/etc/gitlab/gitlab-secrets.json` (Linux package) +- `/etc/gitlab/gitlab-secrets.json` (Linux package installations) - `/home/git/gitlab/.secret` (self-compiled installations) -- Rails secret (cloud-native GitLab) - - [This can be converted to the Linux package format](https://docs.gitlab.com/charts/installation/migration/helm_to_package.html), if required. +- [Restoring the secrets](https://docs.gitlab.com/charts/backup-restore/restore.html#restoring-the-secrets) (cloud-native GitLab) + - [GitLab Helm chart secrets can be converted to the Linux package format](https://docs.gitlab.com/charts/installation/migration/helm_to_package.html), if required. + +### Certain GitLab configuration must match the original backed up environment -You may also want to restore your previous `/etc/gitlab/gitlab.rb` (for Omnibus packages) -or `/home/git/gitlab/config/gitlab.yml` (for installations from source) and +You likely also want to restore your previous `/etc/gitlab/gitlab.rb` (for Linux package installations) +or `/home/git/gitlab/config/gitlab.yml` (for self-compiled installations) and any TLS keys, certificates (`/etc/gitlab/ssl`, `/etc/gitlab/trusted-certs`), or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). -Depending on your case, you might want to run the restore command with one or -more of the following options: +Certain configuration is coupled to data in PostgreSQL. For example: -- `BACKUP=timestamp_of_backup`: Required if more than one backup exists. - Read what the [backup timestamp is about](backup_gitlab.md#backup-timestamp). -- `force=yes`: Doesn't ask if the `authorized_keys` file should get regenerated, - and assumes 'yes' for warning about database tables being removed, - enabling the `Write to authorized_keys file` setting, and updating LDAP - providers. +- If the original environment has three repository storages (for example, `default`, `my-storage-1`, and `my-storage-2`), then the target environment must also have at least those storage names defined in configuration. +- Restoring a backup from an environment using local storage restores to local storage even if the target environment uses object storage. Migrations to object storage must be done before or after restoration. + +### Restoring directories that are mount points If you're restoring into directories that are mount points, you must ensure these directories are empty before attempting a restore. Otherwise, GitLab attempts to move these directories before restoring the new data, which causes an error. -Read more about [configuring NFS mounts](../nfs.md) - -Restoring a backup from an instance using local storage restores to local storage even if the target instance uses object storage. -Migrations to object storage must be done before or after restoration. +Read more about [configuring NFS mounts](../nfs.md). -## Restore for Omnibus GitLab installations +## Restore for Linux package installations This procedure assumes that: - You have installed the **exact same version and type (CE/EE)** of GitLab - Omnibus with which the backup was created. + with which the backup was created. - You have run `sudo gitlab-ctl reconfigure` at least once. - GitLab is running. If not, start it using `sudo gitlab-ctl start`. @@ -203,7 +202,7 @@ docker restart <name of container> docker exec -it <name of container> gitlab-rake gitlab:check SANITIZE=true ``` -## Restore for installation from source +## Restore for self-compiled installations First, ensure your backup tar file is in the backup directory described in the `gitlab.yml` configuration: @@ -282,28 +281,43 @@ project or group from there: A feature request to provide direct restore of individual projects or groups is being discussed in [issue #17517](https://gitlab.com/gitlab-org/gitlab/-/issues/17517). +## Restoring an incremental repository backup + +Each backup archive contains a full self-contained backup, including those created through the [incremental repository backup procedure](backup_gitlab.md#incremental-repository-backups). To restore an incremental repository backup, use the same instructions as restoring any other regular backup archive. + ## Restore options The command line tool GitLab provides to restore from backup can accept more options. -### Disabling prompts during restore +### Specify backup to restore when there are more than one -During a restore from backup, the restore script may ask for confirmation before -proceeding. If you wish to disable these prompts, you can set the `GITLAB_ASSUME_YES` -environment variable to `1`. +By default, backup files use a naming scheme [starting with a timestamp](backup_gitlab.md#backup-timestamp). When more than one backup exists, you must specify which +`*_gitlab_backup.tar` file to restore by setting the environment variable `BACKUP=timestamp_of_backup`. -For Omnibus GitLab packages: +### Disable prompts during restore -```shell -sudo GITLAB_ASSUME_YES=1 gitlab-backup restore -``` +During a restore from backup, the restore script prompts for confirmation: -For installations from source: +- If the **Write to authorized_keys** setting is enabled, before the restore script deletes and rebuilds the `authorized_keys` file. +- When restoring the database, before the restore script removes all existing tables. +- After restoring the database, if there were errors in restoring the schema, before continuing because further problems are likely. -```shell -sudo -u git -H GITLAB_ASSUME_YES=1 bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` +To disable these prompts, set the `GITLAB_ASSUME_YES` environment variable to `1`. + +- Linux package installations: + + ```shell + sudo GITLAB_ASSUME_YES=1 gitlab-backup restore + ``` + +- Self-compiled installations: + + ```shell + sudo -u git -H GITLAB_ASSUME_YES=1 bundle exec rake gitlab:backup:restore RAILS_ENV=production + ``` + +The `force=yes` environment variable also disables these prompts. ### Excluding tasks on restore @@ -322,17 +336,19 @@ You can exclude specific tasks on restore by adding the environment variable `SK - `repositories` (Git repositories data) - `packages` (Packages) -For Omnibus GitLab packages: +To exclude specific tasks: -```shell -sudo gitlab-backup restore BACKUP=timestamp_of_backup SKIP=db,uploads -``` +- Linux package installations: -For installations from source: + ```shell + sudo gitlab-backup restore BACKUP=timestamp_of_backup SKIP=db,uploads + ``` -```shell -sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup SKIP=db,uploads RAILS_ENV=production -``` +- Self-compiled installations: + + ```shell + sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup SKIP=db,uploads RAILS_ENV=production + ``` ### Restore specific repository storages @@ -343,17 +359,19 @@ repositories from specific repository storages can be restored separately using the `REPOSITORIES_STORAGES` option. The option accepts a comma-separated list of storage names. -For example, for Omnibus GitLab installations: +For example: -```shell -sudo gitlab-backup restore BACKUP=timestamp_of_backup REPOSITORIES_STORAGES=storage1,storage2 -``` +- Linux package installations: + + ```shell + sudo gitlab-backup restore BACKUP=timestamp_of_backup REPOSITORIES_STORAGES=storage1,storage2 + ``` -For example, for installations from source: +- Self-compiled installations: -```shell -sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup REPOSITORIES_STORAGES=storage1,storage2 -``` + ```shell + sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup REPOSITORIES_STORAGES=storage1,storage2 + ``` ### Restore specific repositories @@ -367,13 +385,13 @@ descendent groups are included or skipped, depending on which option you used. T For example, to restore all repositories for all projects in **Group A** (`group-a`), the repository for **Project C** in **Group B** (`group-b/project-c`), and skip the **Project D** in **Group A** (`group-a/project-d`): -- Omnibus GitLab installations: +- Linux package installations: ```shell sudo gitlab-backup restore BACKUP=timestamp_of_backup REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d ``` -- Installations from source: +- Self-compiled installations: ```shell sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d @@ -384,24 +402,26 @@ and skip the **Project D** in **Group A** (`group-a/project-d`): If an [untarred backup](backup_gitlab.md#skipping-tar-creation) (made with `SKIP=tar`) is found, and no backup is chosen with `BACKUP=<timestamp>`, the untarred backup is used. -For example, for Omnibus GitLab installations: +For example: -```shell -sudo gitlab-backup restore -``` +- Linux package installations: -For example, for installations from source: + ```shell + sudo gitlab-backup restore + ``` -```shell -sudo -u git -H bundle exec rake gitlab:backup:restore -``` +- Self-compiled installations: + + ```shell + sudo -u git -H bundle exec rake gitlab:backup:restore + ``` ## Troubleshooting The following are possible problems you might encounter, along with potential solutions. -### Restoring database backup using Omnibus packages outputs warnings +### Restoring database backup using output warnings from a Linux package installation If you're using backup restore procedures, you may encounter the following warning messages: diff --git a/doc/administration/broadcast_messages.md b/doc/administration/broadcast_messages.md index 556edbd3e5e..78a4ec798d1 100644 --- a/doc/administration/broadcast_messages.md +++ b/doc/administration/broadcast_messages.md @@ -60,6 +60,7 @@ To add a broadcast message: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. 1. Select **Messages**. +1. Select **Add new message**. 1. Add the text for the message to the **Message** field. You can style a message's content using Markdown, emoji, and the `a` and `br` HTML tags. The `br` tag inserts a line break. The `a` HTML tag accepts `class` and `style` attributes with the following CSS properties: - `color` diff --git a/doc/administration/cicd.md b/doc/administration/cicd.md index a3d9a853aaf..4e98423ea60 100644 --- a/doc/administration/cicd.md +++ b/doc/administration/cicd.md @@ -14,13 +14,13 @@ GitLab administrators can manage the GitLab CI/CD configuration for their instan GitLab CI/CD is enabled by default in all new projects on an instance. You can set CI/CD to be disabled by default in new projects by modifying the settings in: -- `gitlab.yml` for source installations. +- `gitlab.yml` for self-compiled installations. - `gitlab.rb` for Linux package installations. Existing projects that already had CI/CD enabled are unchanged. Also, this setting only changes the project default, so project owners [can still enable CI/CD in the project settings](../ci/enable_or_disable_ci.md#enable-cicd-in-a-project). -For installations from source: +For self-compiled installations: 1. Open `gitlab.yml` with your editor and set `builds` to `false`: diff --git a/doc/administration/clusters/kas.md b/doc/administration/clusters/kas.md index 583a6401c05..b7247e2251f 100644 --- a/doc/administration/clusters/kas.md +++ b/doc/administration/clusters/kas.md @@ -41,7 +41,7 @@ To enable the agent server on a single node: 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). For additional configuration options, see the **Enable GitLab KAS** section of the -[`gitlab.rb.template`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/files/gitlab-config-template/gitlab.rb.template). +[`gitlab.rb.template`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/be52c36c243a3422ec38b7d45d459682a07e195f/files/gitlab-config-template/gitlab.rb.template#L1951). ##### Configure KAS to listen on a UNIX socket diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index 978e43b2e2c..3f4d781e2a2 100644 --- a/doc/administration/compliance.md +++ b/doc/administration/compliance.md @@ -4,7 +4,7 @@ group: Compliance 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 --- -# Compliance features **(FREE)** +# Compliance features **(FREE SELF)** GitLab compliance features ensure your GitLab instance meets common compliance standards, and are available at various pricing tiers. For more information about compliance management, see the compliance management [solutions page](https://about.gitlab.com/solutions/compliance/). @@ -57,7 +57,7 @@ These features can help provide visibility into GitLab and audit what is happeni | [Audit events](audit_events.md) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | To maintain the integrity of your code, audit events give administrators the ability to view any modifications made in the GitLab server in an advanced audit events system, so you can control, analyze, and track every change. | | [Audit reports](audit_reports.md) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Create and access reports based on the audit events that have occurred. Use pre-built GitLab reports or the API to build your own. | | [Auditor users](auditor_users.md) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Auditor users are users who are given read-only access to all projects, groups, and other resources on the GitLab instance. | -| [Compliance report](../user/compliance/compliance_report/index.md) | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Quickly get visibility into the compliance posture of your organization. | +| [Compliance center](../user/compliance/compliance_center/index.md) | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Quickly get visibility into the compliance posture of your organization. | ## Other compliance features @@ -69,7 +69,7 @@ These features can also help with compliance requirements: | [Enforce ToS acceptance](settings/terms.md) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Enforce your users accepting new terms of service by blocking GitLab traffic. | | [External Status Checks](../user/project/merge_requests/status_checks.md) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Interface with third-party systems you already use during development to ensure you remain compliant. | | [Generate reports on permission<br/>levels of users](../administration/admin_area.md#user-permission-export) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Generate a report listing all users' access permissions for groups and projects in the instance. | -| [License compliance](../user/compliance/license_compliance/index.md) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Search dependencies for their licenses. This lets you determine if the licenses of your project's dependencies are compatible with your project's license. | +| [License approval policies](../user/compliance/license_approval_policies.md) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Search dependencies for their licenses. This lets you determine if the licenses of your project's dependencies are compatible with your project's license. | | [Lock project membership to group](../user/group/access_and_permissions.md#prevent-members-from-being-added-to-projects-in-a-group) | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Group owners can prevent new members from being added to projects in a group. | | [LDAP group sync](auth/ldap/ldap_synchronization.md#group-sync) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Automatically synchronize groups and manage SSH keys, permissions, and authentication, so you can focus on building your product, not configuring your tools. | | [LDAP group sync filters](auth/ldap/ldap_synchronization.md#group-sync) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Gives more flexibility to synchronize with LDAP based on filters, meaning you can leverage LDAP attributes to map GitLab permissions. | diff --git a/doc/administration/consul.md b/doc/administration/consul.md index 5a8946dbcf7..a65b2100237 100644 --- a/doc/administration/consul.md +++ b/doc/administration/consul.md @@ -245,6 +245,12 @@ sudo gitlab-ctl start consul After this, the node should start back up, and the rest of the server agents rejoin. Shortly after that, the client agents should rejoin as well. +If they do not join, you might also need to erase the Consul data on the client: + +```shell +sudo rm -rf /var/opt/gitlab/consul/data +``` + #### Recover a failed node If you have taken advantage of Consul to store other data and want to restore diff --git a/doc/administration/dedicated/index.md b/doc/administration/dedicated/index.md index db30684ab1c..b995c837136 100644 --- a/doc/administration/dedicated/index.md +++ b/doc/administration/dedicated/index.md @@ -35,14 +35,41 @@ To request the creation of a new GitLab Dedicated environment for your organizat ### Maintenance window -When onboarding, you must also specify your preference for the weekly four-hour time slot that GitLab uses to perform maintenance and upgrade operations on the tenant instance. +When onboarding, you must also specify your preference for the weekly four-hour time slot that GitLab uses to perform routine maintenance and upgrade operations on all tenant instances. -- APAC (outside working hours): Wednesday 1pm-5pm UTC -- EU (outside working hours): Tuesday 1am-5am UTC -- AMER (outside working hours): Tuesday 7am-11am UTC +Available scheduled maintenance windows, performed outside standard working hours: -NOTE: -Some downtime may be incurred during this window. This downtime is not counting towards [the system SLA](https://about.gitlab.com/handbook/engineering/infrastructure/team/gitlab-dedicated/slas/). +- APAC: Wednesday 1 AM - 5 AM UTC +- EU: Tuesday 1 AM - 5 AM UTC +- AMER Option 1: Tuesday 7 AM - 11 AM UTC +- AMER Option 2: Sunday 9 PM - Monday 1 AM UTC + +Consider the following notes: + +- In case of a performance degradation or downtime during the scheduled maintenance window, + the impact to [the system SLA](https://about.gitlab.com/handbook/engineering/infrastructure/team/gitlab-dedicated/slas/) is not counted. +- The weekly scheduled maintenance window can be postponed into another window within the same week. + This option needs to be agreed with the assigned Customer Success Manager at least one week in advance. +- The scheduled weekly maintenance window is different from + [emergency maintenance](#emergency-maintenance). + +#### Emergency maintenance + +In an event of a platform outage, degradation or a security event requiring urgent action, +emergency maintenance will be carried out per +[the emergency change processes](https://about.gitlab.com/handbook/engineering/infrastructure/emergency-change-processes/). + +The emergency maintenance is initiated urgently when urgent actions need to be executed by GitLab +on a Dedicated tenant instance. +Communication with the customer will be provided on best effort basis prior to commencing the +maintenance, and full communication will follow after the immediate action is carried out. + +For example, when a critical security process is initiated to address an S1 vulnerability in GitLab, +emergency maintenance is carried out to upgrade GitLab to the non-vulnerable version and that +can occur outside of a scheduled maintenance window. +Postponing emergency maintenance is not possible, because the same process must be applied to all +existing Dedicated customers, and the primary concern is to ensure safety and availability of +Dedicated tenant instances. ## Configuration changes @@ -59,10 +86,12 @@ If you want your GitLab data to be encrypted at rest, the KMS keys used must be If you use a key per service, all services must be encrypted at rest. Selective enablement of this feature is not supported. -The keys provided have to reside in the same primary and secondary region specified during [onboarding](#onboarding). +The keys provided have to reside in the same primary, secondary and backup region specified during [onboarding](#onboarding). For instructions on how to create and manage KMS keys, visit [Managing keys](https://docs.aws.amazon.com/kms/latest/developerguide/getting-started.html) in the AWS KMS documentation. +GitLab Dedicated supports only AWS managed KMS keys with KMS [as key material](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-origin). + To create a KMS key using the AWS Console: 1. In `Configure key`, select: @@ -156,13 +185,15 @@ The last page asks you to confirm the KMS key policy. It should look similar to } ``` +Make sure the AWS KMS keys are replicated to your desired primary, secondary and backup region specified during [onboarding](#onboarding). + ### Inbound Private Link [AWS Private Link](https://docs.aws.amazon.com/vpc/latest/privatelink/what-is-privatelink.html) allows users and applications in your VPC on AWS to securely connect to the GitLab Dedicated endpoint without network traffic going over the public internet. To enable the Inbound Private Link: -1. In the body of your [support ticket](#configuration-changes), include the IAM Principal for the AWS user or role in your own AWS Organization that's establishing the VPC endpoint in your AWS account. GitLab Dedicated uses this IAM Principal for access-control. This IAM principal is the only one able to set up an endpoint to the service. +1. In the body of your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650), include the IAM Principal for the AWS user or role in your own AWS Organization that's establishing the VPC endpoint in your AWS account. GitLab Dedicated uses this IAM Principal for access-control. This IAM principal is the only one able to set up an endpoint to the service. 1. After your IAM Principal has been allowlisted, GitLab [creates the Endpoint Service](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html) and communicates the `Service Endpoint Name` on the support ticket. The service name is generated by AWS upon creation of the service endpoint. - GitLab handles the domain verification for the Private DNS name, so that DNS resolution of the tenant instance domain name in your VPC resolves to the PrivateLink endpoint. - GitLab makes the Endpoint Service available in the Availability Zones you specified during the initial onboarding. If you did not specify any Availability Zones, GitLab randomly selects the Availability Zones IDs. @@ -179,8 +210,8 @@ Outbound Private Links allow the GitLab Dedicated instance to securely communica To enable an Outbound Private Link: -1. In your [support ticket](#configuration-changes), GitLab provides you with an IAM role ARN that connects to your endpoint service. You can then add this ARN to the allowlist on your side to restrict connections to your endpoint service. -1. [Create the Endpoint service](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html) through which your internal service is available to GitLab Dedicated. Provide the associated `Service Endpoint Name` on the [support ticket](#configuration-changes). +1. In your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650), GitLab provides you with an IAM role ARN that connects to your endpoint service. You can then add this ARN to the allowlist on your side to restrict connections to your endpoint service. +1. [Create the Endpoint service](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html) through which your internal service is available to GitLab Dedicated. Provide the associated `Service Endpoint Name` on the [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650). 1. When creating the Endpoint service, you must provide GitLab with a [verified Private DNS Name](https://docs.aws.amazon.com/vpc/latest/privatelink/manage-dns-names.html#verify-domain-ownership) for your service. Optionally, if you would like GitLab Dedicated to reach your service via other aliases, you have the ability to specify a list of Private Hosted Zone (PHZ) entries. With this option, GitLab sets up a Private Hosted Zone with DNS names aliased to the verified Private DNS name. To enable this functionality, you must provide GitLab a list of PHZ entries on your support ticket. After the PHZ is created in the tenant environment, DNS resolution of any of the provided records correctly resolves to the PrivateLink endpoint. 1. GitLab then configures the tenant instance to create the necessary Endpoint Interfaces based on the service names you provided. Any outbound calls made from the tenant GitLab instance are directed through the PrivateLink into your VPC. @@ -188,7 +219,7 @@ To enable an Outbound Private Link: In some cases, the GitLab Dedicated instance can't reach an internal service you own because it exposes a certificate that can't be validated using a public Certification Authority (CA). In these cases, custom certificates are required. -To request that GitLab add custom certificates when communicating with your services over PrivateLink, attach the custom public certificate files to your [support ticket](#configuration-changes). +To request that GitLab add custom certificates when communicating with your services over PrivateLink, attach the custom public certificate files to your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650). #### Maximum number of reverse PrivateLink connections @@ -198,22 +229,54 @@ GitLab Dedicated limits the number of reverse PrivateLink connections to 10. GitLab Dedicated allows you to control which IP addresses can access your instance through an IP allowlist. -Specify a comma separated list of IP addresses that can access your GitLab Dedicated instance in your [support ticket](#configuration-changes). After the configuration has been applied, when an IP not on the allowlist tries to access your instance, the connection is refused. +Specify a comma separated list of IP addresses that can access your GitLab Dedicated instance in your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650). After the configuration has been applied, when an IP not on the allowlist tries to access your instance, the connection is refused. ### SAML +NOTE: +GitLab Dedicated supports a limited number of SAML parameters. Parameters not shown in the configuration below are unavailable for GitLab Dedicated tenant instances. + Prerequisites: - You must configure the identity provider before sending the required data to GitLab. To activate SAML for your GitLab Dedicated instance: -1. To make the necessary changes, include the desired [SAML configuration block](../../integration/saml.md#configure-saml-support-in-gitlab) for your GitLab application in your [support ticket](#configuration-changes). At a minimum, GitLab needs the following information to enable SAML for your instance: - - Assertion consumer service URL +1. To make the necessary changes, include the desired [SAML configuration block](../../integration/saml.md#configure-saml-support-in-gitlab) for your GitLab application in your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650). At a minimum, GitLab needs the following information to enable SAML for your instance: + - IDP SSO Target URL - Certificate fingerprint or certificate - NameID format - SSO login button description + ```json + "saml": { + "attribute_statements": { + //optional + }, + "enabled": true, + "groups_attribute": "", + "admin_groups": [ + // optional + ], + "idp_cert_fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8", + "idp_sso_target_url": "https://login.example.com/idp", + "label": "IDP Name", + "name_identifier_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent", + "security": { + // optional + }, + "auditor_groups": [ + // optional + ], + "external_groups": [ + // optional + ], + "required_groups": [ + // optional + ], + } + ``` + 1. After GitLab deploys the SAML configuration to your instance, you are notified on your support ticket. 1. To verify the SAML configuration is successful: - Check that the SSO login button description is displayed on your instance's login page. @@ -222,14 +285,14 @@ To activate SAML for your GitLab Dedicated instance: #### Request signing If [SAML request signing](../../integration/saml.md#sign-saml-authentication-requests-optional) is desired, a certificate must be obtained. This certificate can be self-signed which has the advantage of not having to prove ownership of an arbitrary Common Name (CN) to a public Certificate Authority (CA)). - -To enable SAML request signing, indicate on your SAML [support ticket](#configuration-changes) that you want request signing enabled. GitLab works with you on sending the Certificate Signing Request (CSR) for you to sign. Alternatively, the CSR can be signed with a public CA. After the certificate is signed, GitLab adds the certificate and its associated private key to the `security` section of the SAML configuration. Authentication requests from GitLab to your identity provider can then be signed. +If you choose to enable SAML request signing, the manual steps below will need to be completed before you are able to use SAML, since it requires certificate signing to happen. +To enable SAML request signing, indicate on your SAML [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650) that you want request signing enabled. GitLab works with you on sending the Certificate Signing Request (CSR) for you to sign. Alternatively, the CSR can be signed with a public CA. After the certificate is signed, GitLab adds the certificate and its associated private key to the `security` section of the SAML configuration. Authentication requests from GitLab to your identity provider can then be signed. #### SAML groups With SAML groups you can configure GitLab users based on SAML group membership. -To enable SAML groups, add the [required elements](../../integration/saml.md#configure-users-based-on-saml-group-membership) to the SAML configuration block you provide in your [support ticket](#configuration-changes). +To enable SAML groups, add the [required elements](../../integration/saml.md#configure-users-based-on-saml-group-membership) to the SAML configuration block you provide in your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650). #### Group sync @@ -237,7 +300,7 @@ With [group sync](../../user/group/saml_sso/group_sync.md), you can sync users a To enable group sync: -1. Add the [required elements](../../user/group/saml_sso/group_sync.md#configure-saml-group-sync) to the SAML configuration block you provide in your [support ticket](#configuration-changes). +1. Add the [required elements](../../user/group/saml_sso/group_sync.md#configure-saml-group-sync) to the SAML configuration block you provide in your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650). 1. Configure the [Group Links](../../user/group/saml_sso/group_sync.md#configure-saml-group-links). ### Access to application logs @@ -246,5 +309,5 @@ GitLab [application logs](../../administration/logs/index.md) are delivered to a To gain read only access to this bucket: -1. Open a [support ticket](#configuration-changes) with the title "Customer Log Access". In the body of the ticket, include a list of IAM Principal ARNs (users or roles) that are fetching the logs from S3. +1. Open a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650) with the title "Customer Log Access". In the body of the ticket, include a list of IAM Principal ARNs (users or roles) that are fetching the logs from S3. 1. GitLab then informs you of the name of the S3 bucket. Your nominated users/roles can then able to list and get all objects in the S3 bucket. diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md index 808967778fa..b8e04b6fa08 100644 --- a/doc/administration/encrypted_configuration.md +++ b/doc/administration/encrypted_configuration.md @@ -13,7 +13,7 @@ GitLab can read settings for certain features from encrypted settings files. The - [Incoming email `user` and `password`](incoming_email.md#use-encrypted-credentials). - [LDAP `bind_dn` and `password`](auth/ldap/index.md#use-encrypted-credentials). -- [Service Desk email `user` and `password`](../user/project/service_desk.md#use-encrypted-credentials). +- [Service Desk email `user` and `password`](../user/project/service_desk/index.md#use-encrypted-credentials). - [SMTP `user_name` and `password`](raketasks/smtp.md#secrets). To enable the encrypted configuration settings, a new base key must be generated for diff --git a/doc/administration/external_users.md b/doc/administration/external_users.md index f8ca379d10c..9be49fab95f 100644 --- a/doc/administration/external_users.md +++ b/doc/administration/external_users.md @@ -34,7 +34,7 @@ always take into account the as well as the permission level of the user. NOTE: -External users still count towards a license seat. +External users still count towards a license seat, unless the user has the [Guest role](../subscriptions/self_managed/index.md#free-guest-users) in the Ultimate tier. An administrator can flag a user as external by either of the following methods: diff --git a/doc/administration/file_hooks.md b/doc/administration/file_hooks.md index 904da47caff..2748984b51d 100644 --- a/doc/administration/file_hooks.md +++ b/doc/administration/file_hooks.md @@ -25,14 +25,13 @@ Instead of writing and supporting your own file hook, you can also make changes directly to the GitLab source code and contribute back upstream. In this way, we can ensure functionality is preserved across versions and covered by tests. -## Setup +## Set up a custom file hook -The file hooks must be placed directly into the `file_hooks` directory, subdirectories -are ignored. There is an -[`example` directory inside `file_hooks`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/file_hooks/examples) -where you can find some basic examples. +File hooks must be in the `file_hooks` directory. Subdirectories are ignored. +Find examples in the +[`example` directory under `file_hooks`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/file_hooks/examples). -Follow the steps below to set up a custom hook: +To set up a custom hook: 1. On the GitLab server, locate the plugin directory. For self-compiled installations, the path is usually `/home/git/gitlab/file_hooks/`. For Linux package installations, the path is usually @@ -51,8 +50,8 @@ Follow the steps below to set up a custom hook: 1. The data to the file hook is provided as JSON on `STDIN`. It is exactly the same as for [system hooks](system_hooks.md). -That's it! Assuming the file hook code is properly implemented, the hook fires -as appropriate. The file hooks file list is updated for each event, there is no +Assuming the file hook code is properly implemented, the hook fires +as appropriate. The file hooks file list is updated for each event. There is no need to restart GitLab to apply a new file hook. If a file hook executes with non-zero exit code or GitLab fails to execute it, a @@ -61,7 +60,7 @@ message is logged to: - `gitlab-rails/file_hook.log` in a Linux package installation. - `log/file_hook.log` in a self-compiled installation. -## Creating file hooks +## File hook example This example responds only on the event `project_create`, and the GitLab instance informs the administrators that a new project has been created. @@ -88,7 +87,7 @@ Mail.deliver do end ``` -## Validation +## Validation example Writing your own file hook can be tricky and it's easier if you can check it without altering the system. A Rake task is provided so that you can use it diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md index 6d7240a9f92..a67edc815c8 100644 --- a/doc/administration/geo/disaster_recovery/background_verification.md +++ b/doc/administration/geo/disaster_recovery/background_verification.md @@ -143,10 +143,7 @@ If the **primary** and **secondary** sites have a checksum verification mismatch 1. On the left sidebar, select **Overview > Projects**. 1. Find the project that you want to check the checksum differences and select its name. - 1. On the project administration page get the **Gitaly storage name**, - and **Gitaly relative path**. - -  + 1. On the project administration page, get the values in the **Storage name** and **Relative path** fields. 1. On a **Gitaly node on the primary** site and a **Gitaly node on the secondary** site, go to the project's repository directory. If using Gitaly Cluster, [check that it is in a healthy state](../../gitaly/troubleshooting.md#check-cluster-health) prior to running these commands. diff --git a/doc/administration/geo/disaster_recovery/img/checksum-differences-admin-project-page.png b/doc/administration/geo/disaster_recovery/img/checksum-differences-admin-project-page.png Binary files differdeleted file mode 100644 index 0a7b841897b..00000000000 --- a/doc/administration/geo/disaster_recovery/img/checksum-differences-admin-project-page.png +++ /dev/null diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index 396162fe9ef..151c0f7d9fb 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -542,7 +542,7 @@ Geo on the new **primary** site. To bring a new **secondary** site online, follow the [Geo setup instructions](../index.md#setup-instructions). -### Step 6. Removing the secondary's tracking database +### Step 6. Removing the former secondary's tracking database Every **secondary** has a special tracking database that is used to save the status of the synchronization of all the items from the **primary**. Because the **secondary** is already promoted, that data in the tracking database is no longer required. diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index 0ab24cc4fb8..0293caaf515 100644 --- a/doc/administration/geo/index.md +++ b/doc/administration/geo/index.md @@ -126,6 +126,7 @@ The following are required to run Geo: - If using different operating system versions between Geo sites, [check OS locale data compatibility](replication/troubleshooting.md#check-os-locale-data-compatibility) across Geo sites to avoid silent corruption of database indexes. +- All sites must define the same [repository storages](../repository_storage_paths.md). Additionally, check the GitLab [minimum requirements](../../install/requirements.md), and use the latest version of GitLab for a better experience. @@ -196,6 +197,7 @@ This list of limitations only reflects the latest version of GitLab. If you are - The **primary** site has to be online for OAuth login to happen. Existing sessions and Git are not affected. Support for the **secondary** site to use an OAuth provider independent from the primary is [being planned](https://gitlab.com/gitlab-org/gitlab/-/issues/208465). - The installation takes multiple manual steps that together can take about an hour depending on circumstances. Consider using [the GitLab Environment Toolkit](https://gitlab.com/gitlab-org/gitlab-environment-toolkit) to deploy and operate production GitLab instances based on our [Reference Architectures](../reference_architectures/index.md), including automation of common daily tasks. We are planning to [improve Geo's installation even further](https://gitlab.com/groups/gitlab-org/-/epics/1465). - Real-time updates of issues/merge requests (for example, via long polling) doesn't work on the **secondary** site. +- Using Geo secondary sites to accelerate runners is not officially supported. Support for this functionality is planned and can be tracked in [epic 9779](https://gitlab.com/groups/gitlab-org/-/epics/9779). If a replication lag occurs between the primary and secondary site, and the pipeline ref is not available on the secondary site when the job is executed, the job will fail. - GitLab Runners cannot register with a **secondary** site. Support for this is [planned for the future](https://gitlab.com/gitlab-org/gitlab/-/issues/3294). - [Selective synchronization](replication/configuration.md#selective-synchronization) only limits what repositories and files are replicated. The entire PostgreSQL data is still replicated. Selective synchronization is not built to accommodate compliance / export control use cases. - [Pages access control](../../user/project/pages/pages_access_control.md) doesn't work on secondaries. See [GitLab issue #9336](https://gitlab.com/gitlab-org/gitlab/-/issues/9336) for details. @@ -209,19 +211,6 @@ This list of limitations only reflects the latest version of GitLab. If you are There is a complete list of all GitLab [data types](replication/datatypes.md) and [existing support for replication and verification](replication/datatypes.md#limitations-on-replicationverification). -### View replication data on the primary site - -If you try to view replication data on the primary site, you receive a warning that this may be inconsistent: - -> Viewing projects data from a primary site is not possible when using a unified URL. Visit the secondary site directly. - -The only way to view projects replication data for a particular secondary site is to visit that secondary site directly. For example, `https://<IP of your secondary site>/admin/geo/replication/projects`. -An [epic exists](https://gitlab.com/groups/gitlab-org/-/epics/4623) to fix this limitation. - -Keep in mind that mentioned URLs don't work when [Admin Mode](../settings/sign_in_restrictions.md#admin-mode) is enabled. - -When using Unified URL, visiting the secondary site directly means you must route your requests to the secondary site. Exactly how this might be done depends on your networking configuration. If using DNS to route requests to the appropriate site, then you can, for example, edit your local machine's `/etc/hosts` file to route your requests to the desired secondary site. If the Geo sites are all behind a load balancer, then depending on the load balancer, you might be able to configure all requests from your IP to go to a particular secondary site. - ## Setup instructions For setup instructions, see [Setting up Geo](setup/index.md). diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index a5d85187812..f63f8edbc72 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.md @@ -190,7 +190,7 @@ keys must be manually replicated to the **secondary** site. ```ruby ## ## The unique identifier for the Geo site. See - ## https://docs.gitlab.com/ee/administration/geo_nodes.html#common-settings + ## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings ## gitlab_rails['geo_node_name'] = '<site_name_here>' ``` diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index b25700ccd29..cab3ef581cb 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -34,7 +34,7 @@ verification methods: | Git | Project designs repository | Geo with Gitaly | Gitaly Checksum | | Git | Project Snippets | Geo with Gitaly | Gitaly Checksum | | Git | Personal Snippets | Geo with Gitaly | Gitaly Checksum | -| Git | Group wiki repository | Geo with Gitaly | _Not implemented_ | +| Git | Group wiki repository | Geo with Gitaly | Gitaly Checksum | | Blobs | User uploads _(file system)_ | Geo with API | SHA256 checksum | | Blobs | User uploads _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | | Blobs | LFS objects _(file system)_ | Geo with API | SHA256 checksum | @@ -189,9 +189,9 @@ successfully, you must replicate their data using some other means. |Feature | Replicated (added in GitLab version) | Verified (added in GitLab version) | GitLab-managed object storage replication (added in GitLab version) | GitLab-managed object storage verification (added in GitLab version) | Notes | |:--------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------|:---------------------------------------------------------------------------|:--------------------------------------------------------------------|:----------------------------------------------------------------|:------| |[Application data in PostgreSQL](../../postgresql/index.md) | **Yes** (10.2) | **Yes** (10.2) | N/A | N/A | | -|[Project repository](../../../user/project/repository/index.md) | **Yes** (10.2) | **Yes** (10.7) | N/A | N/A | | +|[Project repository](../../../user/project/repository/index.md) | **Yes** (10.2) | **Yes** (10.7) | N/A | N/A | Migrated to [self-service framework](../../../development/geo/framework.md) in 16.2. See GitLab issue [#367925](https://gitlab.com/gitlab-org/gitlab/-/issues/367925) for more details.<br /><br />Behind feature flag `geo_project_repository_replication`, enabled by default in (16.3).<br /><br /> All projects, including [archived projects](../../../user/project/settings/index.md#archive-a-project), are replicated. | |[Project wiki repository](../../../user/project/wiki/index.md) | **Yes** (10.2)<sup>2</sup> | **Yes** (10.7)<sup>2</sup> | N/A | N/A | Migrated to [self-service framework](../../../development/geo/framework.md) in 15.11. See GitLab issue [#367925](https://gitlab.com/gitlab-org/gitlab/-/issues/367925) for more details.<br /><br />Behind feature flag `geo_project_wiki_repository_replication`, enabled by default in (15.11). | -|[Group wiki repository](../../../user/project/wiki/group.md) | [**Yes** (13.10)](https://gitlab.com/gitlab-org/gitlab/-/issues/208147) | No | N/A | N/A | Behind feature flag `geo_group_wiki_repository_replication`, enabled by default. | +|[Group wiki repository](../../../user/project/wiki/group.md) | [**Yes** (13.10)](https://gitlab.com/gitlab-org/gitlab/-/issues/208147) | [**Yes** (16.3)](https://gitlab.com/gitlab-org/gitlab/-/issues/323897) | N/A | N/A | Behind feature flag `geo_group_wiki_repository_replication`, enabled by default. | |[Uploads](../../uploads.md) | **Yes** (10.2) | **Yes** (14.6) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Replication is behind the feature flag `geo_upload_replication`, enabled by default. Verification was behind the feature flag `geo_upload_verification`, removed in 14.8. | |[LFS objects](../../lfs/index.md) | **Yes** (10.2) | **Yes** (14.6) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | GitLab versions 11.11.x and 12.0.x are affected by [a bug that prevents any new LFS objects from replicating](https://gitlab.com/gitlab-org/gitlab/-/issues/32696).<br /><br />Replication is behind the feature flag `geo_lfs_object_replication`, enabled by default. Verification was behind the feature flag `geo_lfs_object_verification`, removed in 14.7. | |[Personal snippets](../../../user/snippets.md) | **Yes** (10.2) | **Yes** (10.2) | N/A | N/A | | diff --git a/doc/administration/geo/replication/multiple_servers.md b/doc/administration/geo/replication/multiple_servers.md index 29edac1be83..786030736f6 100644 --- a/doc/administration/geo/replication/multiple_servers.md +++ b/doc/administration/geo/replication/multiple_servers.md @@ -67,7 +67,7 @@ The following steps enable a GitLab site to serve as the Geo **primary** site. ```ruby ## ## The unique identifier for the Geo site. See - ## https://docs.gitlab.com/ee/administration/geo_nodes.html#common-settings + ## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings ## gitlab_rails['geo_node_name'] = '<site_name_here>' @@ -217,7 +217,7 @@ then make the following modifications: ## ## The unique identifier for the Geo site. See - ## https://docs.gitlab.com/ee/administration/geo_nodes.html#common-settings + ## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings ## gitlab_rails['geo_node_name'] = '<site_name_here>' @@ -318,7 +318,7 @@ application nodes above, with some changes to run only the `sidekiq` service: ## ## The unique identifier for the Geo site. See - ## https://docs.gitlab.com/ee/administration/geo_nodes.html#common-settings + ## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings ## gitlab_rails['geo_node_name'] = '<site_name_here>' diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index c63480db389..ed11307f57b 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -163,7 +163,7 @@ http://secondary.example.com/ Sync Settings: Full Database replication lag: 0 seconds Last event ID seen from primary: 12345 (about 2 minutes ago) - Last event ID processed by cursor: 12345 (about 2 minutes ago) + Last event ID processed: 12345 (about 2 minutes ago) Last status report was: 1 minute ago ``` @@ -1271,7 +1271,7 @@ If you are using the Linux package installation, something might have failed dur ### GitLab indicates that more than 100% of repositories were synced This can be caused by orphaned records in the project registry. You can clear them -[using a Rake task](../../../administration/raketasks/geo.md#remove-orphaned-project-registries). +[using the Rake task to remove orphaned project registries](../../../administration/raketasks/geo.md#remove-orphaned-project-registries). ### Geo Admin Area returns 404 error for a secondary site diff --git a/doc/administration/geo/replication/version_specific_upgrades.md b/doc/administration/geo/replication/version_specific_upgrades.md index c0215c4551c..7e3160822b9 100644 --- a/doc/administration/geo/replication/version_specific_upgrades.md +++ b/doc/administration/geo/replication/version_specific_upgrades.md @@ -104,323 +104,3 @@ If you are running an affected version and need to remove your Primary site, you ### Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode GitLab 13.9 through GitLab 14.3 are affected by a bug in which enabling [GitLab Maintenance Mode](../../maintenance_mode/index.md) causes Geo secondary site statuses to appear to stop upgrading and become unhealthy. For more information, see [Troubleshooting - Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode](troubleshooting.md#geo-admin-area-shows-unhealthy-after-enabling-maintenance-mode). - -## Upgrading to GitLab 13.12 - -### Secondary sites re-download all LFS files upon upgrade - -We found an issue where [secondary sites re-download all LFS files](https://gitlab.com/gitlab-org/gitlab/-/issues/334550) upon upgrade. This bug: - -- Only applies to Geo secondary sites that have replicated LFS objects. -- Is _not_ a data loss risk. -- Causes churn and wasted bandwidth re-downloading all LFS objects. -- May impact performance for GitLab installations with a large number of LFS files. - -If you don't have many LFS objects or can stand a bit of churn, then it is safe to let the secondary sites re-download LFS objects. -If you do have many LFS objects, or many Geo secondary sites, or limited bandwidth, or a combination of them all, then we recommend you skip GitLab 13.12.0 through 13.12.6 and upgrade to GitLab 13.12.7 or newer. - -#### If you have already upgraded to an affected version, and the re-sync is ongoing - -You can manually migrate the legacy sync state to the new state column by running the following command in a [Rails console](../../operations/rails_console.md). It should take under a minute: - -```ruby -Geo::LfsObjectRegistry.where(state: 0, success: true).update_all(state: 2) -``` - -### Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode - -GitLab 13.9 through GitLab 14.3 are affected by a bug in which enabling [GitLab Maintenance Mode](../../maintenance_mode/index.md) causes Geo secondary site statuses to appear to stop upgrading and become unhealthy. For more information, see [Troubleshooting - Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode](troubleshooting.md#geo-admin-area-shows-unhealthy-after-enabling-maintenance-mode). - -## Upgrading to GitLab 13.11 - -We found an [issue with Git clone/pull through HTTP(s)](https://gitlab.com/gitlab-org/gitlab/-/issues/330787) on Geo secondaries and on any GitLab instance if maintenance mode is enabled. This was caused by a regression in GitLab Workhorse. This is fixed in the [GitLab 13.11.4 patch release](https://about.gitlab.com/releases/2021/05/14/gitlab-13-11-4-released/). To avoid this issue, upgrade to GitLab 13.11.4 or later. - -### Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode - -GitLab 13.9 through GitLab 14.3 are affected by a bug in which enabling [GitLab Maintenance Mode](../../maintenance_mode/index.md) causes Geo secondary site statuses to appear to stop upgrading and become unhealthy. For more information, see [Troubleshooting - Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode](troubleshooting.md#geo-admin-area-shows-unhealthy-after-enabling-maintenance-mode). - -## Upgrading to GitLab 13.10 - -### Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode - -GitLab 13.9 through GitLab 14.3 are affected by a bug in which enabling [GitLab Maintenance Mode](../../maintenance_mode/index.md) causes Geo secondary site statuses to appear to stop upgrading and become unhealthy. For more information, see [Troubleshooting - Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode](troubleshooting.md#geo-admin-area-shows-unhealthy-after-enabling-maintenance-mode). - -## Upgrading to GitLab 13.9 - -### Error during zero-downtime upgrade: `cannot drop column asset_proxy_whitelist` - -We've detected an issue [with a column rename](https://gitlab.com/gitlab-org/gitlab/-/issues/324160) -that prevents upgrades to GitLab 13.9.0, 13.9.1, 13.9.2 and 13.9.3 when following the zero-downtime steps. It is necessary -to perform the following additional steps for the zero-downtime upgrade: - -1. Before running the final `sudo gitlab-rake db:migrate` command on the deploy node, - execute the following queries using the PostgreSQL console (or `sudo gitlab-psql`) - to drop the problematic triggers: - - ```sql - drop trigger trigger_e40a6f1858e6 on application_settings; - drop trigger trigger_0d588df444c8 on application_settings; - drop trigger trigger_1572cbc9a15f on application_settings; - drop trigger trigger_22a39c5c25f3 on application_settings; - ``` - -1. Run the final migrations: - - ```shell - sudo gitlab-rake db:migrate - ``` - -1. Hot reload `puma` and `sidekiq` services: - - ```shell - sudo gitlab-ctl hup puma - sudo gitlab-ctl restart sidekiq - ``` - -If you have already run the final `sudo gitlab-rake db:migrate` command on the deploy node and have -encountered the [column rename issue](https://gitlab.com/gitlab-org/gitlab/-/issues/324160), you might -see the following error: - -```shell --- remove_column(:application_settings, :asset_proxy_whitelist) -rake aborted! -StandardError: An error has occurred, all later migrations canceled: -PG::DependentObjectsStillExist: ERROR: cannot drop column asset_proxy_whitelist of table application_settings because other objects depend on it -DETAIL: trigger trigger_0d588df444c8 on table application_settings depends on column asset_proxy_whitelist of table application_settings -``` - -To work around this bug, follow the previous steps to complete the upgrade. -More details are available [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/324160). - -### Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode - -GitLab 13.9 through GitLab 14.3 are affected by a bug in which enabling [GitLab Maintenance Mode](../../maintenance_mode/index.md) causes Geo secondary site statuses to appear to stop upgrading and become unhealthy. For more information, see [Troubleshooting - Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode](troubleshooting.md#geo-admin-area-shows-unhealthy-after-enabling-maintenance-mode). - -## Upgrading to GitLab 13.7 - -- We've detected an issue with the `FetchRemove` call used by Geo secondaries. - This causes performance issues as we execute reference transaction hooks for - each upgraded reference. Delay any upgrade attempts until this is in the - [13.7.5 patch release.](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3002). - More details are available [in this issue](https://gitlab.com/gitlab-org/git/-/issues/79). -- A new secret is generated in `/etc/gitlab/gitlab-secrets.json`. - In an HA GitLab or GitLab Geo environment, secrets need to be the same on all nodes. - Ensure this new secret is also accounted for if you are manually syncing the file across - nodes, or manually specifying secrets in `/etc/gitlab/gitlab.rb`. - -## Upgrading to GitLab 13.5 - -GitLab 13.5 has a [regression that prevents viewing a list of container repositories and registries](https://gitlab.com/gitlab-org/gitlab/-/issues/285475) -on Geo secondaries. This issue is fixed in GitLab 13.6.1 and later. - -## Upgrading to GitLab 13.3 - -In GitLab 13.3, Geo removed the PostgreSQL [Foreign Data Wrapper](https://www.postgresql.org/docs/11/postgres-fdw.html) -dependency for the tracking database. - -The FDW server, user, and the extension is removed during the upgrade -process on each secondary site. The GitLab settings related to the FDW in the -`/etc/gitlab/gitlab.rb` have been deprecated and can be safely removed. - -There are some scenarios like using an external PostgreSQL instance for the -tracking database where the FDW settings must be removed manually. Enter the -PostgreSQL console of that instance and remove them: - -```shell -DROP SERVER gitlab_secondary CASCADE; -DROP EXTENSION IF EXISTS postgres_fdw; -``` - -WARNING: -In GitLab 13.3, promoting a secondary site to a primary while the secondary is -paused fails. Do not pause replication before promoting a secondary. If the -site is paused, be sure to resume before promoting. To avoid this issue, -upgrade to GitLab 13.4 or later. - -WARNING: -Promoting the database during a failover can fail on XFS and filesystems ordering files lexically, -when using `--force` or `--skip-preflight-checks`, due to [an issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6076) fixed in 13.5. -The [troubleshooting steps](troubleshooting.md#errors-when-using---skip-preflight-checks-or---force) -contain a workaround if you run into errors during the failover. - -## Upgrading to GitLab 13.2 - -In GitLab 13.2, promoting a secondary site to a primary while the secondary is -paused fails. Do not pause replication before promoting a secondary. If the -site is paused, be sure to resume before promoting. To avoid this issue, -upgrade to GitLab 13.4 or later. - -## Upgrading to GitLab 13.0 - -Upgrading to GitLab 13.0 requires GitLab 12.10 to already be using PostgreSQL -version 11. For the recommended procedure, see how -[to upgrade a Geo instance](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). - -## Upgrading to GitLab 12.10 - -GitLab 12.10 doesn't attempt to upgrade the embedded PostgreSQL server when -using Geo, because the PostgreSQL upgrade requires downtime for secondaries -while reinitializing streaming replication. It must be upgraded manually. For -the recommended procedure, see how -[to upgrade a Geo instance](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). - -## Upgrading to GitLab 12.9 - -WARNING: -GitLab 12.9.0 through GitLab 12.9.3 are affected by -[a bug that stops repository verification](https://gitlab.com/gitlab-org/gitlab/-/issues/213523). -The issue is fixed in GitLab 12.9.4. Upgrade to GitLab 12.9.4 or later. - -By default, GitLab 12.9 attempts to upgrade the embedded PostgreSQL server -version from 9.6 to 10.12, which requires downtime on secondaries while -reinitializing streaming replication. For the recommended procedure, see how -[to upgrade a Geo instance](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). - -You can temporarily disable this behavior by running the following before -upgrading: - -```shell -sudo touch /etc/gitlab/disable-postgresql-upgrade -``` - -## Upgrading to GitLab 12.8 - -By default, GitLab 12.8 attempts to upgrade the embedded PostgreSQL server -version from 9.6 to 10.12, which requires downtime on secondaries while -reinitializing streaming replication. For the recommended procedure, see how -[to upgrade a Geo instance](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). - -You can temporarily disable this behavior by running the following before -upgrading: - -```shell -sudo touch /etc/gitlab/disable-postgresql-upgrade -``` - -## Upgrading to GitLab 12.7 - -WARNING: -Only upgrade to GitLab 12.7.5 or later. Do not upgrade to versions 12.7.0 -through 12.7.4 because there is [an initialization order bug](https://gitlab.com/gitlab-org/gitlab/-/issues/199672) that causes Geo secondaries to set the incorrect database connection pool size. -[The fix](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24021) was -shipped in 12.7.5. - -By default, GitLab 12.7 attempts to upgrade the embedded PostgreSQL server -version from 9.6 to 10.9, which requires downtime on secondaries while -reinitializing streaming replication. For the recommended procedure, see how -[to upgrade a Geo instance](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). - -You can temporarily disable this behavior by running the following before -upgrading: - -```shell -sudo touch /etc/gitlab/disable-postgresql-upgrade -``` - -## Upgrading to GitLab 12.6 - -By default, GitLab 12.6 attempts to upgrade the embedded PostgreSQL server -version from 9.6 to 10.9, which requires downtime on secondaries while -reinitializing streaming replication. For the recommended procedure, see how -[to upgrade a Geo instance](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). - -You can temporarily disable this behavior by running the following before -upgrading: - -```shell -sudo touch /etc/gitlab/disable-postgresql-upgrade -``` - -## Upgrading to GitLab 12.5 - -By default, GitLab 12.5 attempts to upgrade the embedded PostgreSQL server -version from 9.6 to 10.9, which requires downtime on secondaries while -reinitializing streaming replication. For the recommended procedure, see how -[to upgrade a Geo instance](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). - -You can temporarily disable this behavior by running the following before -upgrading: - -```shell -sudo touch /etc/gitlab/disable-postgresql-upgrade -``` - -## Upgrading to GitLab 12.4 - -By default, GitLab 12.4 attempts to upgrade the embedded PostgreSQL server -version from 9.6 to 10.9, which requires downtime on secondaries while -reinitializing streaming replication. For the recommended procedure, see how -[to upgrade a Geo instance](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). - -You can temporarily disable this behavior by running the following before -upgrading: - -```shell -sudo touch /etc/gitlab/disable-postgresql-upgrade -``` - -## Upgrading to GitLab 12.3 - -WARNING: -If the existing PostgreSQL server version is 9.6.x, we recommend upgrading to -GitLab 12.4 or later. By default, GitLab 12.3 attempts to upgrade the embedded -PostgreSQL server version from 9.6 to 10.9. In certain circumstances, it can -fail. For more information, see how -[to upgrade a Geo instance](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). - -Additionally, if the PostgreSQL upgrade doesn't fail, a successful upgrade -requires downtime for secondaries while reinitializing streaming replication. -For the recommended procedure, see how -[to upgrade a Geo instance](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). - -## Upgrading to GitLab 12.2 - -WARNING: -If the existing PostgreSQL server version is 9.6.x, we recommend upgrading to -GitLab 12.4 or later. By default, GitLab 12.2 attempts to upgrade the embedded -PostgreSQL server version from 9.6 to 10.9. In certain circumstances, it can -fail. For more information, see how -[to upgrade a Geo instance](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). - -Additionally, if the PostgreSQL upgrade doesn't fail, a successful upgrade -requires downtime for secondaries while reinitializing streaming replication. -For the recommended procedure, see how -[to upgrade a Geo instance](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). - -GitLab 12.2 includes the following minor PostgreSQL upgrades: - -- To version `9.6.14`, if you run PostgreSQL 9.6. -- To version `10.9`, if you run PostgreSQL 10. - -This upgrade occurs even if major PostgreSQL upgrades are disabled. - -Before [refreshing Foreign Data Wrapper during a Geo upgrade](../../../update/zero_downtime.md#step-4-run-post-deployment-migrations-and-checks), -restart the Geo tracking database: - -```shell -sudo gitlab-ctl restart geo-postgresql -``` - -The restart avoids a version mismatch when PostgreSQL tries to load the FDW -extension. - -## Upgrading to GitLab 12.1 - -WARNING: -If the existing PostgreSQL server version is 9.6.x, we recommend upgrading to -GitLab 12.4 or later. By default, GitLab 12.1 attempts to upgrade the embedded -PostgreSQL server version from 9.6 to 10.9. In certain circumstances, it can -fail. For more information, see how -[to upgrade a Geo instance](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). - -Additionally, if the PostgreSQL upgrade doesn't fail, a successful upgrade -requires downtime for secondaries while reinitializing streaming replication. -For the recommended procedure, see how -[to upgrade a Geo instance](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). - -## Upgrading to GitLab 12.0 - -WARNING: -This version is affected by a -[bug that results in new LFS objects not being replicated to Geo secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/32696). -The issue is fixed in GitLab 12.1. Be sure to upgrade to GitLab 12.1 or later. diff --git a/doc/administration/geo/secondary_proxy/index.md b/doc/administration/geo/secondary_proxy/index.md index 2ab96a3d33d..11e5cb1b7b8 100644 --- a/doc/administration/geo/secondary_proxy/index.md +++ b/doc/administration/geo/secondary_proxy/index.md @@ -122,14 +122,7 @@ for details. To use TLS certificates with Let's Encrypt, you can manually point the domain to one of the Geo sites, generate the certificate, then copy it to all other sites. -- [Viewing projects data from a primary site is not possible when using a unified URL](../index.md#view-replication-data-on-the-primary-site). - -- When secondary proxying is used together with separate URLs, registering [GitLab runners](https://docs.gitlab.com/runner/) to clone from -secondary sites is not supported. The runner registration succeeds, but the clone URL defaults to the primary site. The runner -[clone URL](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) is configured per GitLab deployment -and cannot be configured per Geo site. Therefore, all runners clone from the primary site (or configured clone URL) irrespective of -which Geo site they register on. For information about GitLab CI using a specific Geo secondary to clone from, see issue -[3294](https://gitlab.com/gitlab-org/gitlab/-/issues/3294#note_1009488466). +- Using Geo secondary sites to accelerate runners is not officially supported. Support for this functionality is planned and can be tracked in [epic 9779](https://gitlab.com/groups/gitlab-org/-/epics/9779). If a replication lag occurs between the primary and secondary site, and the pipeline ref is not available on the secondary site when the job is executed, the job will fail. - When secondary proxying is used together with separate URLs, [signing in the secondary site using SAML](../replication/single_sign_on.md#saml-with-separate-url-with-proxying-enabled) diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md index be6e327732d..d94c44a76f2 100644 --- a/doc/administration/geo/setup/database.md +++ b/doc/administration/geo/setup/database.md @@ -64,7 +64,7 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o #### Step 1. Configure the **primary** site -1. SSH into your GitLab **primary** site and login as root: +1. SSH into your GitLab **primary** site and log in as root: ```shell sudo -i @@ -75,7 +75,7 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o ```ruby ## ## The unique identifier for the Geo site. See - ## https://docs.gitlab.com/ee/administration/geo_nodes.html#common-settings + ## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings ## gitlab_rails['geo_node_name'] = '<site_name_here>' ``` @@ -320,7 +320,7 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o #### Step 2. Configure the **secondary** server -1. SSH into your GitLab **secondary** site and login as root: +1. SSH into your GitLab **secondary** site and log in as root: ```shell sudo -i @@ -462,7 +462,7 @@ WARNING: Make sure to run this on the **secondary** site as it removes all PostgreSQL's data before running `pg_basebackup`. -1. SSH into your GitLab **secondary** site and login as root: +1. SSH into your GitLab **secondary** site and log in as root: ```shell sudo -i @@ -680,7 +680,7 @@ and ensure password authentication is used. On each node running a Patroni instance on the primary site **starting on the Patroni Leader instance**: -1. SSH into your Patroni instance and login as root: +1. SSH into your Patroni instance and log in as root: ```shell sudo -i @@ -791,7 +791,7 @@ see [the relevant documentation](../../postgresql/replication_and_failover.md). On each node running a PgBouncer instance on the **secondary** site: -1. SSH into your PgBouncer node and login as root: +1. SSH into your PgBouncer node and log in as root: ```shell sudo -i @@ -850,7 +850,7 @@ and then you can switch over to another replica if you need to. For each node running a Patroni instance on the secondary site: -1. SSH into your Patroni node and login as root: +1. SSH into your Patroni node and log in as root: ```shell sudo -i @@ -955,7 +955,7 @@ and other database best practices. On each node running the PgBouncer service for the PostgreSQL tracking database: -1. SSH into your PgBouncer node and login as root: +1. SSH into your PgBouncer node and log in as root: ```shell sudo -i @@ -1017,7 +1017,7 @@ On each node running the PgBouncer service for the PostgreSQL tracking database: On each node running a Patroni instance on the secondary site for the PostgreSQL tracking database: -1. SSH into your Patroni node and login as root: +1. SSH into your Patroni node and log in as root: ```shell sudo -i @@ -1083,7 +1083,7 @@ On each node running a Patroni instance on the secondary site for the PostgreSQL For each node running the `gitlab-rails`, `sidekiq`, and `geo-logcursor` services: -1. SSH into your node and login as root: +1. SSH into your node and log in as root: ```shell sudo -i diff --git a/doc/administration/geo/setup/external_database.md b/doc/administration/geo/setup/external_database.md index 50383546da3..061ae2d4eb8 100644 --- a/doc/administration/geo/setup/external_database.md +++ b/doc/administration/geo/setup/external_database.md @@ -39,7 +39,7 @@ developed and tested. We aim to be compatible with most external ## ## The unique identifier for the Geo site. See - ## https://docs.gitlab.com/ee/administration/geo_nodes.html#common-settings + ## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings ## gitlab_rails['geo_node_name'] = '<site_name_here>' ``` @@ -189,6 +189,8 @@ potential replication issues. The Linux package automatically configures a track when `roles ['geo_secondary_role']` is set. If you want to run this database external to your Linux package installation, use the following instructions. +#### Cloud-managed database services + If you are using a cloud-managed service for the tracking database, you may need to grant additional roles to your tracking database user (by default, this is `gitlab_geo`): @@ -200,8 +202,6 @@ to grant additional roles to your tracking database user (by default, this is This is for the installation of extensions during installation and upgrades. As an alternative, [ensure the extensions are installed manually, and read about the problems that may arise during future GitLab upgrades](../../../install/postgresql_extensions.md). -To setup an external tracking database, follow the instructions below: - NOTE: If you want to use Amazon RDS as a tracking database, make sure it has access to the secondary database. Unfortunately, just assigning the same security group is not enough as @@ -209,9 +209,14 @@ outbound rules do not apply to RDS PostgreSQL databases. Therefore, you need to rule to the read-replica's security group allowing any TCP traffic from the tracking database on port 5432. +#### Create the tracking database + +Create and configure the tracking database in your PostgreSQL instance: + 1. Set up PostgreSQL according to the [database requirements document](../../../install/requirements.md#database). -1. Set up a `gitlab_geo` user with a password of your choice, create the `gitlabhq_geo_production` database, and make the user an owner of the database. You can see an example of this setup in the [installation from source documentation](../../../install/installation.md#7-database). +1. Set up a `gitlab_geo` user with a password of your choice, create the `gitlabhq_geo_production` database, and make the user an owner of the database. + You can see an example of this setup in the [self-compiled installation documentation](../../../install/installation.md#7-database). 1. If you are **not** using a cloud-managed PostgreSQL database, ensure that your secondary site can communicate with your tracking database by manually changing the `pg_hba.conf` that is associated with your tracking database. @@ -226,6 +231,10 @@ the tracking database on port 5432. host all all <trusted secondary IP>/32 md5 ``` +#### Configure GitLab + +Configure GitLab to use this database. These steps are for Linux package and Docker deployments. + 1. SSH into a GitLab **secondary** server and login as root: ```shell @@ -246,14 +255,19 @@ the tracking database on port 5432. 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#reconfigure-a-linux-package-installation) -1. The reconfigure should automatically create the database. If needed, you can perform this task manually. This task (whether run by itself or during reconfigure) requires the database user to be a superuser. +#### Set up the database schema + +The reconfigure in the [steps above](#configure-gitlab) for Linux package and Docker deployments should handle these steps automatically. + +1. This task creates the database schema. It requires the database user to be a superuser. ```shell - gitlab-rake db:create:geo + sudo gitlab-rake db:create:geo ``` -1. The reconfigure should automatically migrate the database. You can migrate the database manually if needed, for example if `geo_secondary['auto_migrate'] = false`: +1. Applying Rails database migrations (schema and data updates) is also performed by reconfigure. If `geo_secondary['auto_migrate'] = false` is set, or + the schema was created manually, this step will be required: ```shell - gitlab-rake db:migrate:geo + sudo gitlab-rake db:migrate:geo ``` diff --git a/doc/administration/geo/setup/index.md b/doc/administration/geo/setup/index.md index 8ac64a963bb..cb318783128 100644 --- a/doc/administration/geo/setup/index.md +++ b/doc/administration/geo/setup/index.md @@ -34,17 +34,28 @@ If both Geo sites are based on the [1K reference architecture](../../reference_a - [Using Linux package PostgreSQL instances](database.md) . - [Using external PostgreSQL instances](external_database.md) 1. [Configure GitLab](../replication/configuration.md) to set the **primary** and **secondary** sites. -1. Recommended: [Configure unified URLs](../secondary_proxy/index.md#set-up-a-unified-url-for-geo-sites) to use a single, unified URL for all Geo sites. -1. Optional: [Configure Object storage replication](../replication/object_storage.md) -1. Optional: [Configure a secondary LDAP server](../../auth/ldap/index.md) for the **secondary** sites. See [notes on LDAP](../index.md#ldap). -1. Optional: [Configure Container Registry for the secondary site](../replication/container_registry.md). 1. Follow the [Using a Geo Site](../replication/usage.md) guide. +Depending on your GitLab deployment, [additional configuration](#additional-configuration) for LDAP, object storage, and the Container Registry might be required. + ### Multi-node Geo sites If one or more of your sites is using the [2K reference architecture](../../reference_architectures/2k_users.md) or larger, see [Configure Geo for multiple nodes](../replication/multiple_servers.md). +Depending on your GitLab deployment, [additional configuration](#additional-configuration) for LDAP, object storage, and the Container Registry might be required. + +### Additional configuration + +Depending on how you use GitLab, the following configuration might be required: + +- If the **primary** site uses object storage, [configure object storage replication](../replication/object_storage.md) for the **secondary** sites. +- If you use LDAP, [configure a secondary LDAP server](../../auth/ldap/index.md) for the **secondary** sites. + For more information, see [LDAP with Geo](../replication/single_sign_on.md#ldap). +- If you use the Container Registry, [configure the Container Registry for replication](../replication/container_registry.md) on the **primary** and **secondary** sites. + +You should [configure unified URLs](../secondary_proxy/index.md#set-up-a-unified-url-for-geo-sites) to use a single, unified URL for all Geo sites. + ## Using GitLab Charts [Configure the GitLab chart with GitLab Geo](https://docs.gitlab.com/charts/advanced/geo/). diff --git a/doc/administration/geo/setup/two_single_node_sites.md b/doc/administration/geo/setup/two_single_node_sites.md new file mode 100644 index 00000000000..00002d501b2 --- /dev/null +++ b/doc/administration/geo/setup/two_single_node_sites.md @@ -0,0 +1,638 @@ +--- +stage: Systems +group: Geo +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 +--- + +# Set up Geo for two single-node sites **(PREMIUM SELF)** + +The following guide provides concise instructions on how to deploy GitLab Geo for a two single-node site installation using two Linux package instances. + +Prerequisites: + +- You have at least two independently working GitLab sites. + To create the sites, see the [GitLab reference architectures documentation](../../reference_architectures/index.md). + - One GitLab site serves as the **Geo primary site**. You can use different reference architecture sizes for each Geo site. If you already have a working GitLab instance, you can use it as the primary site. + - The second GitLab site serves as the **Geo secondary site**. Geo supports multiple secondary sites. +- The Geo primary site has at least a [GitLab Premium](https://about.gitlab.com/pricing/) license. + You need only one license for all sites. +- Confirm all sites meet the [requirements for running Geo](../index.md#requirements-for-running-geo). + +## Set up Geo for Linux package (Omnibus) + +Prerequisites: + +- You use PostgreSQL 12 or later, + which includes the [`pg_basebackup` tool](https://www.postgresql.org/docs/12/app-pgbasebackup.html). + +### Configure the primary site + +1. SSH into your GitLab primary site and sign in as root: + + ```shell + sudo -i + ``` + +1. Add a unique Geo site name to `/etc/gitlab/gitlab.rb`: + + ```ruby + ## + ## The unique identifier for the Geo site. See + ## https://docs.gitlab.com/ee/user/admin_area/geo_nodes.html#common-settings + ## + gitlab_rails['geo_node_name'] = '<site_name_here>' + ``` + +1. To apply the change, reconfigure the primary site: + + ```shell + gitlab-ctl reconfigure + ``` + +1. Define the site as your primary Geo site: + + ```shell + gitlab-ctl set-geo-primary-node + ``` + + This command uses the `external_url` defined in `/etc/gitlab/gitlab.rb`. + +1. Create a password for the `gitlab` database user. + + 1. Generate a MD5 hash of the desired password: + + ```shell + gitlab-ctl pg-password-md5 gitlab + # Enter password: <your_password_here> + # Confirm password: <your_password_here> + # fca0b89a972d69f00eb3ec98a5838484 + ``` + + 1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab` + postgresql['sql_user_password'] = '<md5_hash_of_your_password>' + + # Every node that runs Puma or Sidekiq needs to have the database + # password specified as below. If you have a high-availability setup, this + # must be present in all application nodes. + gitlab_rails['db_password'] = '<your_password_here>' + ``` + +1. Define a password for the database [replication user](https://wiki.postgresql.org/wiki/Streaming_Replication). + Use the username defined in `/etc/gitlab/gitlab.rb` under the `postgresql['sql_replication_user']` + setting. The default value is `gitlab_replicator`. + + 1. Generate an MD5 hash of the desired password: + + ```shell + gitlab-ctl pg-password-md5 gitlab_replicator + + # Enter password: <your_password_here> + # Confirm password: <your_password_here> + # 950233c0dfc2f39c64cf30457c3b7f1e + ``` + + 1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab_replicator` + postgresql['sql_replication_password'] = '<md5_hash_of_your_password>' + ``` + + 1. Optional. If you use an external database not managed by the Linux package, you must + create the `gitlab_replicator` user and define a password for that user manually: + + ```sql + --- Create a new user 'replicator' + CREATE USER gitlab_replicator; + + --- Set/change a password and grants replication privilege + ALTER USER gitlab_replicator WITH REPLICATION ENCRYPTED PASSWORD '<replication_password>'; + ``` + +1. In `/etc/gitlab/gitlab.rb`, set the role to [`geo_primary_role`](https://docs.gitlab.com/omnibus/roles/#gitlab-geo-roles): + + ```ruby + ## Geo Primary role + roles(['geo_primary_role']) + ``` + +1. Configure PostgreSQL to listen on network interfaces: + + 1. To look up the address of a Geo site, SSH into the Geo site and execute: + + ```shell + ## + ## Private address + ## + ip route get 255.255.255.255 | awk '{print "Private address:", $NF; exit}' + + ## + ## Public address + ## + echo "External address: $(curl --silent "ipinfo.io/ip")" + ``` + + In most cases, the following addresses are used to configure GitLab + Geo: + + | Configuration | Address | + |:----------------------------------------|:----------------------------------------------------------------------| + | `postgresql['listen_address']` | Primary site public or VPC private address. | + | `postgresql['md5_auth_cidr_addresses']` | Primary and secondary site public or VPC private addresses. | + + If you use Google Cloud Platform, SoftLayer, or any other vendor that + provides a virtual private cloud (VPC), you can use the primary and secondary site + private addresses (which correspond to "internal address" for Google Cloud Platform) for + `postgresql['md5_auth_cidr_addresses']` and `postgresql['listen_address']`. + + NOTE: + If you need to use `0.0.0.0` or `*` as the `listen_address`, you also must add + `127.0.0.1/32` to the `postgresql['md5_auth_cidr_addresses']` setting, to allow + Rails to connect through `127.0.0.1`. For more information, see [issue 5258](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5258). + + Depending on your network configuration, the suggested addresses might + be incorrect. If your primary and secondary sites connect over a local + area network, or a virtual network connecting availability zones like + [Amazon's VPC](https://aws.amazon.com/vpc/) or [Google's VPC](https://cloud.google.com/vpc/), + you should use the secondary site private address for `postgresql['md5_auth_cidr_addresses']`. + + 1. Add the following lines to `/etc/gitlab/gitlab.rb`. Be sure to replace the IP + addresses with addresses appropriate to your network configuration: + + ```ruby + ## + ## Primary address + ## - replace '<primary_node_ip>' with the public or VPC address of your Geo primary node + ## + postgresql['listen_address'] = '<primary_site_ip>' + + ## + # Allow PostgreSQL client authentication from the primary and secondary IPs. These IPs may be + # public or VPC addresses in CIDR format, for example ['198.51.100.1/32', '198.51.100.2/32'] + ## + postgresql['md5_auth_cidr_addresses'] = ['<primary_site_ip>/32', '<secondary_site_ip>/32'] + ``` + +1. Disable automatic database migrations temporarily until PostgreSQL is restarted and listening on the private address. + In `/etc/gitlab/gitlab.rb`, set `gitlab_rails['auto_migrate']` to false: + + ```ruby + ## Disable automatic database migrations + gitlab_rails['auto_migrate'] = false + ``` + +1. To apply these changes, reconfigure GitLab and restart PostgreSQL: + + ```shell + gitlab-ctl reconfigure + gitlab-ctl restart postgresql + ``` + +1. To re-enable migrations, edit `/etc/gitlab/gitlab.rb` and change `gitlab_rails['auto_migrate']` to `true`: + + ```ruby + gitlab_rails['auto_migrate'] = true + ``` + + Save the file and reconfigure GitLab: + + ```shell + gitlab-ctl reconfigure + ``` + + The PostgreSQL server is set up to accept remote connections + +1. Run `netstat -plnt | grep 5432` to ensure that PostgreSQL is listening on port + `5432` to the primary site private address. + +1. A certificate was automatically generated when GitLab was reconfigured. The certificate + is used automatically to protect your PostgreSQL traffic from + eavesdroppers. To protect against active ("man-in-the-middle") attackers, + copy the certificate to the secondary site: + + 1. Make a copy of `server.crt` on the primary site: + + ```shell + cat ~gitlab-psql/data/server.crt + ``` + + 1. Save the output for when you configure the secondary site. + The certificate is not sensitive data. + + The certificate is created with a generic `PostgreSQL` common name. + To prevent hostname mismatch errors, you must use the `verify-ca` + mode when replicating the database. + +### Configure the secondary server + +1. SSH into your GitLab secondary site and sign in as root: + + ```shell + sudo -i + ``` + +1. To prevent any commands from running before the site is configured, stop the application server and Sidekiq: + + ```shell + gitlab-ctl stop puma + gitlab-ctl stop sidekiq + ``` + +1. [Check TCP connectivity](../../raketasks/maintenance.md) to the primary site PostgreSQL server: + + ```shell + gitlab-rake gitlab:tcp_check[<primary_site_ip>,5432] + ``` + + If this step fails, you might be using the wrong IP address, or a firewall might + be preventing access to the site. Check the IP address, paying close + attention to the difference between public and private addresses. + If a firewall is present, ensure the secondary site is allowed to connect to the + primary site on port 5432. + +1. In the secondary site, create a file called `server.crt` and add the copy of the certificate you made when you configured the primary site. + + ```shell + editor server.crt + ``` + +1. To set up PostgreSQL TLS verification on the secondary site, install `server.crt`: + + ```shell + install \ + -D \ + -o gitlab-psql \ + -g gitlab-psql \ + -m 0400 \ + -T server.crt ~gitlab-psql/.postgresql/root.crt + ``` + + PostgreSQL now recognizes only this exact certificate when verifying TLS + connections. The certificate can be replicated by someone with access + to the private key, which is present on only the primary site. + +1. Test that the `gitlab-psql` user can connect to the primary site database. + The default Linux package name is `gitlabhq_production`: + + ```shell + sudo \ + -u gitlab-psql /opt/gitlab/embedded/bin/psql \ + --list \ + -U gitlab_replicator \ + -d "dbname=gitlabhq_production sslmode=verify-ca" \ + -W \ + -h <primary_site_ip> + ``` + + When prompted, enter the plaintext password you set for the `gitlab_replicator` user. + If all worked correctly, you should see the list of the primary site databases. + +1. Edit `/etc/gitlab/gitlab.rb` and set the role to `geo_secondary_role`: + + ```ruby + ## + ## Geo Secondary role + ## - configure dependent flags automatically to enable Geo + ## + roles(['geo_secondary_role']) + ``` + + For more information, see [Geo roles](https://docs.gitlab.com/omnibus/roles/#gitlab-geo-roles). + +1. To configure PostgreSQL, edit `/etc/gitlab/gitlab.rb` and add the following: + + ```ruby + ## + ## Secondary address + ## - replace '<secondary_site_ip>' with the public or VPC address of your Geo secondary site + ## + postgresql['listen_address'] = '<secondary_site_ip>' + postgresql['md5_auth_cidr_addresses'] = ['<secondary_site_ip>/32'] + + ## + ## Database credentials password (defined previously in primary site) + ## - replicate same values here as defined in primary site + ## + postgresql['sql_replication_password'] = '<md5_hash_of_your_password>' + postgresql['sql_user_password'] = '<md5_hash_of_your_password>' + gitlab_rails['db_password'] = '<your_password_here>' + ``` + + Be sure to replace the IP addresses with addresses appropriate to your network configuration. + +1. To apply the changes, reconfigure GitLab: + + ```shell + gitlab-ctl reconfigure + ``` + +1. To apply the IP address change, restart PostgreSQL: + + ```shell + gitlab-ctl restart postgresql + ``` + +### Replicate the database + +Connect the database on the secondary site to +the database on the primary site. +You can use the script below to replicate the +database and create the needed files for streaming replication. + +The script uses the default Linux package directories. +If you changed the defaults, replace the directory and path +names in the script below with your own names. + +WARNING: +Run the replication script on only the secondary site. +The script removes all PostgreSQL data before it runs `pg_basebackup`, +which can lead to data loss. + +To replicate the database: + +1. SSH into your GitLab secondary site and sign in as root: + + ```shell + sudo -i + ``` + +1. Choose a database-friendly name for your secondary site to + use as the replication slot name. For example, if your domain is + `secondary.geo.example.com`, use `secondary_example` as the slot + name. Replication slot names must only contain lowercase letters, + numbers, and the underscore character. + +1. Execute the following command to back up and restore the database, and begin the replication. + + WARNING: + Each Geo secondary site must have its own unique replication slot name. + Using the same slot name between two secondaries breaks PostgreSQL replication. + + ```shell + gitlab-ctl replicate-geo-database \ + --slot-name=<secondary_site_name> \ + --host=<primary_site_ip> \ + --sslmode=verify-ca + ``` + + When prompted, enter the plaintext password you set up for the `gitlab_replicator`. + +The replication process is complete. + +## Configure a new secondary site + +After the replication process is complete, you need to [configure fast lookup of authorized SSH keys](../../operations/fast_ssh_key_lookup.md). + +NOTE: +Authentication is handled by the primary site. Don't set up custom authentication for the secondary site. +Any change that requires access to the Admin Area should be made in the primary site, because the +secondary site is a read-only copy. + +### Manually replicate secret GitLab values + +GitLab stores a number of secret values in `/etc/gitlab/gitlab-secrets.json`. +This JSON file must be the same across each of the site nodes. +You must manually replicate the secret file across all of your secondary sites, although +[issue 3789](https://gitlab.com/gitlab-org/gitlab/-/issues/3789) proposes to change this behavior. + +1. SSH into a Rails node on your primary site, and execute the command below: + + ```shell + sudo cat /etc/gitlab/gitlab-secrets.json + ``` + + This displays the secrets you must replicate, in JSON format. + +1. SSH into each node on your secondary Geo site and sign in as root: + + ```shell + sudo -i + ``` + +1. Make a backup of any existing secrets: + + ```shell + mv /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.`date +%F` + ``` + +1. Copy `/etc/gitlab/gitlab-secrets.json` from the primary site Rails node to each secondary site node. + You can also copy-and-paste the file contents between nodes: + + ```shell + sudo editor /etc/gitlab/gitlab-secrets.json + + # paste the output of the `cat` command you ran on the primary + # save and exit + ``` + +1. Ensure the file permissions are correct: + + ```shell + chown root:root /etc/gitlab/gitlab-secrets.json + chmod 0600 /etc/gitlab/gitlab-secrets.json + ``` + +1. To apply the changes, reconfigure every Rails, Sidekiq and Gitaly secondary site node: + + ```shell + gitlab-ctl reconfigure + gitlab-ctl restart + ``` + +### Manually replicate the primary site SSH host keys + +1. SSH into each node on your secondary site and sign in as root: + + ```shell + sudo -i + ``` + +1. Back up any existing SSH host keys: + + ```shell + find /etc/ssh -iname 'ssh_host_*' -exec cp {} {}.backup.`date +%F` \; + ``` + +1. Copy OpenSSH host keys from the primary site. + + - If you can access as root one of the primary site nodes serving SSH traffic (usually, the main GitLab Rails application nodes): + + ```shell + # Run this from the secondary site, change `<primary_site_fqdn>` for the IP or FQDN of the server + scp root@<primary_node_fqdn>:/etc/ssh/ssh_host_*_key* /etc/ssh + ``` + + - If you only have access through a user with `sudo` privileges: + + ```shell + # Run this from the node on your primary site: + sudo tar --transform 's/.*\///g' -zcvf ~/geo-host-key.tar.gz /etc/ssh/ssh_host_*_key* + + # Run this on each node on your secondary site: + scp <user_with_sudo>@<primary_site_fqdn>:geo-host-key.tar.gz . + tar zxvf ~/geo-host-key.tar.gz -C /etc/ssh + ``` + +1. For each secondary site node, ensure the file permissions are correct: + + ```shell + chown root:root /etc/ssh/ssh_host_*_key* + chmod 0600 /etc/ssh/ssh_host_*_key + ``` + +1. To verify key fingerprint matches, execute the following command on both the primary and secondary nodes on each site: + + ```shell + for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done + ``` + + You should get an output similar to the following: + + ```shell + 1024 SHA256:FEZX2jQa2bcsd/fn/uxBzxhKdx4Imc4raXrHwsbtP0M root@serverhostname (DSA) + 256 SHA256:uw98R35Uf+fYEQ/UnJD9Br4NXUFPv7JAUln5uHlgSeY root@serverhostname (ECDSA) + 256 SHA256:sqOUWcraZQKd89y/QQv/iynPTOGQxcOTIXU/LsoPmnM root@serverhostname (ED25519) + 2048 SHA256:qwa+rgir2Oy86QI+PZi/QVR+MSmrdrpsuH7YyKknC+s root@serverhostname (RSA) + ``` + + The output should be identical on both nodes. + +1. Verify you have the correct public keys for the existing private keys: + + ```shell + # This will print the fingerprint for private keys: + for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done + + # This will print the fingerprint for public keys: + for file in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf $file; done + ``` + + The output for the public and private key commands should generate the same fingerprint. + +1. For each secondary site node, restart `sshd`: + + ```shell + # Debian or Ubuntu installations + sudo service ssh reload + + # CentOS installations + sudo service sshd reload + ``` + +1. To verify SSH is still functional, from a new terminal, SSH into your GitLab secondary server. + If you can't connect, make sure you have the correct permissions. + +### Add the secondary site + +1. SSH into each Rails and Sidekiq node on your secondary site and sign in as root: + + ```shell + sudo -i + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and add a unique name for your site. + + ```ruby + ## + ## The unique identifier for the Geo site. See + ## https://docs.gitlab.com/ee/user/admin_area/geo_nodes.html#common-settings + ## + gitlab_rails['geo_node_name'] = '<site_name_here>' + ``` + + Save the unique name for the next steps. + +1. To apply the changes, reconfigure each Rails and Sidekiq node on your secondary site. + + ```shell + gitlab-ctl reconfigure + ``` + +1. Navigate to the primary node GitLab instance: + 1. On the top bar, select **Main menu > Admin**. + 1. On the left sidebar, select **Geo > Sites**. + 1. Select **Add site**. + +  + + 1. In **Name**, enter the value for `gitlab_rails['geo_node_name']` in + `/etc/gitlab/gitlab.rb`. The values must match exactly. + 1. In **External URL**, enter the value for `external_url` in `/etc/gitlab/gitlab.rb`. + It's okay if one values ends in `/` and the other doesn't. Otherwise, the values must + match exactly. + 1. Optional. In **Internal URL (optional)**, enter an internal URL for the primary site. + 1. Optional. Select which groups or storage shards should be replicated by the + secondary site. To replicate all, leave the field blank. See [selective synchronization](../replication/configuration.md#selective-synchronization). + 1. Select **Save changes**. +1. SSH into each Rails and Sidekiq node on your secondary site and restart the services: + + ```shell + gitlab-ctl restart + ``` + +1. Check if there are any common issues with your Geo setup by running: + + ```shell + gitlab-rake gitlab:geo:check + ``` + + If any of the checks fail, see the [troubleshooting documentation](../replication/troubleshooting.md). + +1. To verify that the secondary site is reachable, SSH into a Rails or Sidekiq server on your primary site and sign in as root: + + ```shell + gitlab-rake gitlab:geo:check + ``` + + If any of the checks fail, check the [troubleshooting documentation](../replication/troubleshooting.md). + +After the secondary site is added to the Geo administration page and restarted, +the site automatically starts to replicate missing data from the primary site +in a process known as backfill. + +Meanwhile, the primary site starts to notify each secondary site of any changes, so +that the secondary site can act on the notifications immediately. + +Be sure the secondary site is running and accessible. You can sign in to the +secondary site with the same credentials as were used with the primary site. + +### Enable Git access over HTTP/HTTPS and SSH + +Geo synchronizes repositories over HTTP/HTTPS, and therefore requires this clone +method to be enabled. This is enabled by default. +If you convert an existing site to Geo, you should check that the clone method is enabled. + +On the primary site: + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility and access controls**. +1. If you use Git over SSH: + 1. Ensure **Enabled Git access protocols** is set to **Both SSH and HTTP(S)**. + 1. Follow [Fast lookup of authorized SSH keys in the database](../../operations/fast_ssh_key_lookup.md) on both the primary and secondary sites. +1. If you don't use Git over SSH, set **Enabled Git access protocols** to **Only HTTP(S)**. + +### Verify proper functioning of the secondary site + +You can sign in to the secondary site with the same credentials you used with +the primary site. + +After you sign in: + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Geo > Sites**. +1. Verify that the site is correctly identified as a secondary Geo site, and that + Geo is enabled. + +The initial replication might take some time. +You can monitor the synchronization process on each Geo site from the primary +site **Geo Sites** dashboard in your browser. + + + +## Related topics + +- [Troubleshooting Geo](../replication/troubleshooting.md) diff --git a/doc/administration/get_started.md b/doc/administration/get_started.md index bf3d38657f8..978ea519305 100644 --- a/doc/administration/get_started.md +++ b/doc/administration/get_started.md @@ -4,7 +4,7 @@ stage: none group: Tutorials --- -# Get started administering GitLab **(FREE)** +# Get started administering GitLab **(FREE SELF)** Get started with GitLab administration. Configure your organization and its authentication, then secure, monitor, and back up GitLab. @@ -36,7 +36,7 @@ Watch an overview of [groups and projects](https://www.youtube.com/watch?v=cqb2m Get started: -- Create a [project](../user/project/index.md#create-a-project). +- Create a [project](../user/project/index.md). - Create a [group](../user/group/index.md#create-a-group). - [Add members](../user/group/index.md#add-users-to-a-group) to the group. - Create a [subgroup](../user/group/subgroups/index.md#create-a-subgroup). diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index 1ece7d773ee..7fb241b8d1f 100644 --- a/doc/administration/git_protocol.md +++ b/doc/administration/git_protocol.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: "Set and configure Git protocol v2" --- -# Configuring Git Protocol v2 **(FREE)** +# Configuring Git Protocol v2 **(FREE SELF)** > [Re-enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/27828) in GitLab 12.8. diff --git a/doc/administration/gitaly/configure_gitaly.md b/doc/administration/gitaly/configure_gitaly.md index c7fa40014d0..b26ae84eef0 100644 --- a/doc/administration/gitaly/configure_gitaly.md +++ b/doc/administration/gitaly/configure_gitaly.md @@ -19,7 +19,7 @@ Configure Gitaly in one of two ways: :::TabTitle Self-compiled (source) 1. Edit `/home/git/gitaly/config.toml` and add or change the [Gitaly settings](https://gitlab.com/gitlab-org/gitaly/blob/master/config.toml.example). -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). ::EndTabs @@ -183,7 +183,7 @@ Edit `/etc/gitlab/gitlab.rb`: token: 'abc123secret' ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). 1. On the Gitaly servers, edit `/home/git/gitaly/config.toml`: ```toml @@ -191,7 +191,7 @@ Edit `/etc/gitlab/gitlab.rb`: token = 'abc123secret' ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). ::EndTabs @@ -351,7 +351,7 @@ Configure Gitaly server in one of two ways: gitlab_url: https://gitlab.example.com ``` -1. Save the files and [restart GitLab](../restart_gitlab.md#installations-from-source). +1. Save the files and [restart GitLab](../restart_gitlab.md#self-compiled-installations). 1. Confirm that Gitaly can perform callbacks to the GitLab internal API: - For GitLab 15.3 and later, run `sudo /opt/gitlab/embedded/bin/gitaly check /var/opt/gitlab/gitaly/config.toml`. - For GitLab 15.2 and earlier, run `sudo /opt/gitlab/embedded/bin/gitaly-hooks check /var/opt/gitlab/gitaly/config.toml`. @@ -456,7 +456,7 @@ Configure Gitaly clients in one of two ways: this folder. This requirement is scheduled to be removed when [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). 1. Run `sudo -u git -H bundle exec rake gitlab:gitaly:check RAILS_ENV=production` to confirm the Gitaly client can connect to Gitaly servers. 1. Tail the logs to see the requests: @@ -570,7 +570,7 @@ Disable Gitaly on a GitLab server in one of two ways: gitaly_enabled=false ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). ::EndTabs @@ -705,7 +705,7 @@ Configure Gitaly with TLS in one of two ways: in this folder. This requirement is scheduled to be removed when [Gitaly issue #1282](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). 1. On the Gitaly servers, create or edit `/etc/default/gitlab` and add: ```shell @@ -740,14 +740,14 @@ Configure Gitaly with TLS in one of two ways: key_path = '/etc/gitlab/ssl/key.pem' ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). 1. Verify Gitaly traffic is being served over TLS by [observing the types of Gitaly connections](#observe-type-of-gitaly-connections). 1. Optional. Improve security by: 1. Disabling non-TLS connections by commenting out or deleting `listen_addr` in `/home/git/gitaly/config.toml`. 1. Saving the file. - 1. [Restarting GitLab](../restart_gitlab.md#installations-from-source). + 1. [Restarting GitLab](../restart_gitlab.md#self-compiled-installations). ::EndTabs @@ -1453,7 +1453,7 @@ following keys (in this example, to disable the `hasDotgit` consistency check): } ``` -For source installs, edit the Gitaly configuration (`gitaly.toml`) to do the +For self-compiled installations, edit the Gitaly configuration (`gitaly.toml`) to do the equivalent: ```toml @@ -1552,7 +1552,7 @@ Configure Gitaly to sign commits made with the GitLab UI in one of two ways: signing_key = "/etc/gitlab/gitaly/signing_key.gpg" ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). ::EndTabs diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index 9577c4a4cb2..6eefd0a7bb5 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -671,8 +671,6 @@ Updates to example must be made at: } ``` -1. Enable [distribution of reads](index.md#distributed-reads). - 1. Save the changes to `/etc/gitlab/gitlab.rb` and [reconfigure Praefect](../restart_gitlab.md#reconfigure-a-linux-package-installation): @@ -853,7 +851,7 @@ For self-compiled installations: data is stored in this folder. This requirement is scheduled to be removed when [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). 1. Copy all Praefect server certificates, or their certificate authority, to the system trusted certificates on each Gitaly server so the Praefect server trusts the certificate when called by Gitaly servers: @@ -873,7 +871,7 @@ For self-compiled installations: key_path = '/etc/gitlab/ssl/key.pem' ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). #### Service discovery @@ -990,7 +988,7 @@ with Praefect service discovery address, such as `praefect.service.consul`. data is stored in this folder. [Issue 375254](https://gitlab.com/gitlab-org/gitlab/-/issues/375254) proposes to remove this requirement. -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). ::EndTabs @@ -1020,10 +1018,10 @@ Particular attention should be shown to: - The `gitaly['configuration'][:auth][:token]` configured in this section must match the `token` value under `praefect['configuration'][:virtual_storage][<index>][:node][<index>][:token]` on the Praefect node. This value was set in the [previous section](#praefect). This document uses the placeholder `PRAEFECT_INTERNAL_TOKEN` throughout. -- The storage names in `gitaly['configuration'][:storage]` configured in this section must match the - storage names under `praefect['configuration'][:virtual_storage]` on the Praefect node. This +- The physical storage names in `gitaly['configuration'][:storage]` configured in this section must match the + physical storage names under `praefect['configuration'][:virtual_storage]` on the Praefect node. This was set in the [previous section](#praefect). This document uses `gitaly-1`, - `gitaly-2`, and `gitaly-3` as Gitaly storage names. + `gitaly-2`, and `gitaly-3` as physical storage names. For more information on Gitaly server configuration, see our [Gitaly documentation](configure_gitaly.md#configure-gitaly-servers). @@ -1419,12 +1417,12 @@ cluster. ## Configure replication factor -WARNING: -Configurable replication factors require [repository-specific primary nodes](#repository-specific-primary-nodes) to be used. - Praefect supports configuring a replication factor on a per-repository basis, by assigning specific storage nodes to host a repository. +WARNING: +Configurable replication factors requires [repository-specific primary nodes](#repository-specific-primary-nodes). + Praefect does not store the actual replication factor, but assigns enough storages to host the repository so the desired replication factor is met. If a storage node is later removed from the virtual storage, the replication factor of repositories assigned to the storage is decreased accordingly. @@ -1436,13 +1434,13 @@ You can configure either: ### Configure default replication factor -If `default_replication_factor` is unset, the repositories are always replicated on every node defined in -`virtual_storages`. If a new node is introduced to the virtual storage, both new and existing repositories are +If `default_replication_factor` is unset, the repositories are always replicated on every storage node defined in +`virtual_storages`. If a new storage node is introduced to the virtual storage, both new and existing repositories are replicated to the node automatically. -For large Gitaly Cluster deployments with many Gitaly nodes, replicating a repository to every storage is often not -sensible and can cause problems. The higher the replication factor, the higher the pressure on the primary repository. -You should explicitly set the default replication factor for large Gitaly Cluster deployments. +For large Gitaly Cluster deployments with many storage nodes, replicating a repository to every storage node is often not +sensible and can cause problems. A replication factor of 3 is usually sufficient, which means replicate repositories to +three storages even if more are available. Higher replication factors increase the pressure on the primary storage. To configure a default replication factor, add configuration to the `/etc/gitlab/gitlab.rb` file: @@ -1453,7 +1451,7 @@ praefect['configuration'] = { { # ... name: 'default', - default_replication_factor: 1, + default_replication_factor: 3, }, ], } @@ -1718,26 +1716,3 @@ To migrate existing clusters: 1. Uncomment the secondary Gitaly node configuration commented out in the earlier step on all Praefect nodes. 1. Run `gitlab-ctl reconfigure` on all Praefect nodes to reconfigure and restart the Praefect processes. - -### Deprecated election strategies - -WARNING: -The below election strategies are deprecated and were removed in GitLab 14.0. -Migrate to [repository-specific primary nodes](#repository-specific-primary-nodes). - -- **PostgreSQL:** Enabled by default until GitLab 14.0, and equivalent to: - `praefect['failover_election_strategy'] = 'sql'`. - - This configuration option: - - - Allows multiple Praefect nodes to coordinate via the PostgreSQL database to elect a primary - Gitaly node. - - Causes Praefect nodes to elect a new primary Gitaly node, monitor its health, and elect a new primary - Gitaly node if the current one is not reached within 10 seconds by a majority of the Praefect - nodes. -- **Memory:** Enabled by setting `praefect['failover_election_strategy'] = 'local'` - in `/etc/gitlab/gitlab.rb` on the Praefect node. - - If a sufficient number of health checks fail for the current primary Gitaly node, a new primary is - elected. **Do not use with multiple Praefect nodes!** Using with multiple Praefect nodes is - likely to result in a split brain. diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 0024c42972b..6948009aab2 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -16,7 +16,7 @@ GitLab has several features based on receiving incoming email messages: - [New merge request by email](../user/project/merge_requests/creating_merge_requests.md#by-sending-an-email): allow GitLab users to create a new merge request by sending an email to a user-specific email address. -- [Service Desk](../user/project/service_desk.md): provide email support to +- [Service Desk](../user/project/service_desk/index.md): provide email support to your customers through GitLab. ## Requirements @@ -80,7 +80,7 @@ Email is processed correctly when a configured email address is present in one o The `References` header is also accepted, however it is used specifically to relate email responses to existing discussion threads. It is not used for creating issues by email. -In GitLab 14.6 and later, [Service Desk](../user/project/service_desk.md) +In GitLab 14.6 and later, [Service Desk](../user/project/service_desk/index.md) also checks accepted headers. Usually, the "To" field contains the email address of the primary receiver. @@ -179,7 +179,7 @@ list. Reply by email should now be working. -### Installations from source +### Self-compiled installations 1. Go to the GitLab installation directory: @@ -312,7 +312,7 @@ gitlab_rails['incoming_email_delete_after_delivery'] = true gitlab_rails['incoming_email_expunge_deleted'] = true ``` -Example for source installs: +Example for self-compiled installations: ```yaml incoming_email: @@ -404,7 +404,7 @@ gitlab_rails['incoming_email_delete_after_delivery'] = true gitlab_rails['incoming_email_expunge_deleted'] = true ``` -Example for source installs: +Example for self-compiled installations: ```yaml incoming_email: @@ -490,7 +490,7 @@ gitlab_rails['incoming_email_ssl'] = true gitlab_rails['incoming_email_expunge_deleted'] = true ``` -Example for source installs: +Example for self-compiled installations: ```yaml incoming_email: @@ -529,7 +529,7 @@ incoming_email: NOTE: Supports [Reply by Email](reply_by_email.md) only. -Cannot support [Service Desk](../user/project/service_desk.md). +Cannot support [Service Desk](../user/project/service_desk/index.md). Assumes the dedicated email address `incoming@exchange.example.com`. @@ -558,7 +558,7 @@ gitlab_rails['incoming_email_ssl'] = true gitlab_rails['incoming_email_expunge_deleted'] = true ``` -Example for source installs: +Example for self-compiled installations: ```yaml incoming_email: @@ -646,7 +646,7 @@ gitlab_rails['incoming_email_ssl'] = true gitlab_rails['incoming_email_expunge_deleted'] = true ``` -This example for source installs assumes the mailbox `incoming@office365.example.com`: +This example for self-compiled installations assumes the mailbox `incoming@office365.example.com`: ```yaml incoming_email: @@ -707,7 +707,7 @@ gitlab_rails['incoming_email_ssl'] = true gitlab_rails['incoming_email_expunge_deleted'] = true ``` -This example for source installs assumes the catch-all mailbox `incoming@office365.example.com`: +This example for self-compiled installations assumes the catch-all mailbox `incoming@office365.example.com`: ```yaml incoming_email: @@ -741,7 +741,7 @@ incoming_email: NOTE: Supports [Reply by Email](reply_by_email.md) only. -Cannot support [Service Desk](../user/project/service_desk.md). +Cannot support [Service Desk](../user/project/service_desk/index.md). This example for Linux package installations assumes the dedicated email address `incoming@office365.example.com`: @@ -767,7 +767,7 @@ gitlab_rails['incoming_email_ssl'] = true gitlab_rails['incoming_email_expunge_deleted'] = true ``` -This example for source installs assumes the dedicated email address `incoming@office365.example.com`: +This example for self-compiled installations assumes the dedicated email address `incoming@office365.example.com`: ```yaml incoming_email: @@ -865,7 +865,7 @@ gitlab_rails['incoming_email_inbox_options'] = { } ``` -The Microsoft Graph API is not yet supported in source installations. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/326169) for more details. +The Microsoft Graph API is not yet supported in self-compiled installations. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/326169) for more details. ### Use encrypted credentials diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index 679042c3114..34f6da1d01d 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.md @@ -760,6 +760,26 @@ You can change these limits in the [GitLab Rails console](operations/rails_conso ApplicationSetting.update(max_yaml_depth: 125) ``` +### Maximum size of the entire CI/CD configuration + +The maximum amount of memory, in bytes, that can be allocated for the full pipeline configuration, +with all included YAML configuration files. + +For new self-managed instances, the default is `157286400` bytes (150 MB). + +For existing self-managed instances that upgrade to GitLab 16.3 or later, the default is calculated +by multiplying [`max_yaml_size_bytes` (default 1 MB)](#maximum-size-and-depth-of-cicd-configuration-yaml-files) +with [`ci_max_includes` (default 150)](../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). +If both limits are unmodified, the default is set to 1 MB x 150 = `157286400` bytes (150 MB). + +You can change this limit via the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session). +To update the maximum memory that can be allocated for the CI/CD configuration, +update `ci_max_total_yaml_size_bytes` with the new value. For example, to set it to 20 MB: + +```ruby +ApplicationSetting.update(ci_max_total_yaml_size_bytes: 20.megabytes) +``` + ### Limit dotenv variables > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321552) in GitLab 14.5. @@ -840,7 +860,7 @@ panel_groups: label: Legend Label ``` -## Environment Dashboard limits **(PREMIUM)** +## Environment Dashboard limits **(PREMIUM ALL)** See [Environment Dashboard](../ci/environments/environments_dashboard.md#adding-a-project-to-the-dashboard) for the maximum number of displayed projects. diff --git a/doc/administration/integration/diagrams_net.md b/doc/administration/integration/diagrams_net.md index 335b26565e6..7f8c01ad7bd 100644 --- a/doc/administration/integration/diagrams_net.md +++ b/doc/administration/integration/diagrams_net.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Diagrams.net **(FREE)** +# Diagrams.net **(FREE SELF)** With the [diagrams.net](https://www.diagrams.net/) integration, you can create and embed SVG diagrams in wikis. The diagram editor is available in both the plain text editor and the rich text editor. diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index f05197d45e7..5e499e302db 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# PlantUML **(FREE)** +# PlantUML **(FREE SELF)** With the [PlantUML](https://plantuml.com) integration, you can create diagrams in snippets, wikis, and repositories. This integration is enabled on GitLab.com for all SaaS users and does not require any additional configuration. @@ -291,6 +291,14 @@ The default URL is different when using this approach. The Docker-based image makes the service available at the root URL, with no relative path. Adjust the configuration below accordingly. +#### `404` error when opening the PlantUML page in the browser + +You might get a `404` error when visiting `https://gitlab.example.com/-/plantuml/`, when the PlantUML +server is set up [in Debian or Ubuntu](#debianubuntu). + +This can happen even when the integration is working. +It does not necessarily indicate a problem with your PlantUML server or configuration. + ### Configure PlantUML security PlantUML has features that allow fetching network resources. If you self-host the diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index 1ab45d6ce99..2939e227a04 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Web terminals (deprecated) **(FREE)** +# Web terminals (deprecated) **(FREE SELF)** > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. > - [Disabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/353410) in GitLab 15.0. @@ -114,5 +114,5 @@ lifetime in your GitLab instance: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. -1. Select [**Settings > Web terminal**](../../administration/settings/index.md#general). +1. Select **Settings > Web terminal**. 1. Set a `max session time`. diff --git a/doc/administration/invalidate_markdown_cache.md b/doc/administration/invalidate_markdown_cache.md index 366cbea5711..5db08075449 100644 --- a/doc/administration/invalidate_markdown_cache.md +++ b/doc/administration/invalidate_markdown_cache.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Markdown cache **(FREE)** +# Markdown cache **(FREE SELF)** For performance reasons, GitLab caches the HTML version of Markdown text in fields such as: diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md index 1ea6b3bb49c..d179b77530a 100644 --- a/doc/administration/issue_closing_pattern.md +++ b/doc/administration/issue_closing_pattern.md @@ -21,11 +21,6 @@ in the project's default branch. The [default issue closing pattern](../user/project/issues/managing_issues.md#default-closing-pattern) covers a wide range of words. You can change the pattern to suit your needs. -NOTE: -To test the issue closing pattern, use <https://rubular.com>. -However, Rubular doesn't understand `%{issue_ref}`. When testing your patterns, -replace this string with `#\d+`, which matches only local issue references like `#123`. - To change the default issue closing pattern: ::Tabs @@ -108,3 +103,7 @@ To change the default issue closing pattern: ``` ::EndTabs + +To test the issue closing pattern, use <https://rubular.com>. +However, Rubular doesn't understand `%{issue_ref}`. When testing your patterns, +replace this string with `#\d+`, which matches only local issue references like `#123`. diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 106334b226d..b3778e89b19 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -399,428 +399,3 @@ an archive is a very large file. When selecting a specific file, [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) extracts it from the archive and the download begins. This implementation saves space, memory and disk I/O. - -## Troubleshooting - -### Job artifacts using too much disk space - -Job artifacts can fill up your disk space quicker than expected. Some possible -reasons are: - -- Users have configured job artifacts expiration to be longer than necessary. -- The number of jobs run, and hence artifacts generated, is higher than expected. -- Job logs are larger than expected, and have accumulated over time. -- The file system might run out of inodes because - [empty directories are left behind by artifact housekeeping](https://gitlab.com/gitlab-org/gitlab/-/issues/17465). - [The Rake task for _orphaned_ artifact files](../raketasks/cleanup.md#remove-orphan-artifact-files) - removes these. -- Artifact files might be left on disk and not deleted by housekeeping. Run the - [Rake task for _orphaned_ artifact files](../raketasks/cleanup.md#remove-orphan-artifact-files) - to remove these. This script should always find work to do, as it also removes empty directories (see above). -- [Artifact housekeeping was changed significantly](#artifacts-housekeeping-disabled-in-gitlab-146-to-152), - and you might need to enable a feature flag to used the updated system. -- The [keep latest artifacts from most recent success jobs](../ci/jobs/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs) - feature is enabled. - -In these and other cases, identify the projects most responsible -for disk space usage, figure out what types of artifacts are using the most -space, and in some cases, manually delete job artifacts to reclaim disk space. - -#### Artifacts housekeeping disabled in GitLab 14.6 to 15.2 - -Artifact housekeeping was significantly changed in GitLab 14.10, and the changes -were back ported to GitLab 14.6 and later. The updated housekeeping must be -enabled with feature flags [until GitLab 15.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92931). - -To check if the feature flags are enabled: - -1. Start a [Rails console](operations/rails_console.md#starting-a-rails-console-session). - -1. Check if the feature flags are enabled. - - - GitLab 14.10 and earlier: - - ```ruby - Feature.enabled?(:ci_detect_wrongly_expired_artifacts, default_enabled: :yaml) - Feature.enabled?(:ci_update_unlocked_job_artifacts, default_enabled: :yaml) - Feature.enabled?(:ci_destroy_unlocked_job_artifacts, default_enabled: :yaml) - ``` - - - GitLab 15.00 and later: - - ```ruby - Feature.enabled?(:ci_detect_wrongly_expired_artifacts) - Feature.enabled?(:ci_update_unlocked_job_artifacts) - Feature.enabled?(:ci_destroy_unlocked_job_artifacts) - ``` - -1. If any of the feature flags are disabled, enable them: - - ```ruby - Feature.enable(:ci_detect_wrongly_expired_artifacts) - Feature.enable(:ci_update_unlocked_job_artifacts) - Feature.enable(:ci_destroy_unlocked_job_artifacts) - ``` - -These changes include switching artifacts from `unlocked` to `locked` if -they [should be retained](../ci/jobs/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). - -Artifacts created before this feature was introduced have a status of `unknown`. After they expire, -these artifacts are not processed by the new housekeeping jobs. - -You can check the database to confirm if your instance has artifacts with the `unknown` status: - -1. Start a database console: - - ::Tabs - - :::TabTitle Linux package (Omnibus) - - ```shell - sudo gitlab-psql - ``` - - :::TabTitle Helm chart (Kubernetes) - - ```shell - # Find the toolbox pod - kubectl --namespace <namespace> get pods -lapp=toolbox - # Connect to the PostgreSQL console - kubectl exec -it <toolbox-pod-name> -- /srv/gitlab/bin/rails dbconsole --include-password --database main - ``` - - :::TabTitle Docker - - ```shell - sudo docker exec -it <container_name> /bin/bash - gitlab-psql - ``` - - :::TabTitle Self-compiled (source) - - ```shell - sudo -u git -H psql -d gitlabhq_production - ``` - - ::EndTabs - -1. Run the following query: - - ```sql - select expire_at, file_type, locked, count(*) from ci_job_artifacts - where expire_at is not null and - file_type != 3 - group by expire_at, file_type, locked having count(*) > 1; - ``` - -If records are returned, then there are artifacts which the housekeeping job -is unable to process. For example: - -```plaintext - expire_at | file_type | locked | count --------------------------------+-----------+--------+-------- - 2021-06-21 22:00:00+00 | 1 | 2 | 73614 - 2021-06-21 22:00:00+00 | 2 | 2 | 73614 - 2021-06-21 22:00:00+00 | 4 | 2 | 3522 - 2021-06-21 22:00:00+00 | 9 | 2 | 32 - 2021-06-21 22:00:00+00 | 12 | 2 | 163 -``` - -Artifacts with locked status `2` are `unknown`. Check -[issue #346261](https://gitlab.com/gitlab-org/gitlab/-/issues/346261#note_1028871458) -for more details. - -The Sidekiq worker that processes all `unknown` artifacts is enabled by default in -GitLab 15.3 and later. It analyzes the artifacts returned by the above database query and -determines which should be `locked` or `unlocked`. Artifacts are then deleted -by that worker if needed. - -The worker can be enabled on self-managed instances running GitLab 14.10 and later: - -1. Start a [Rails console](operations/rails_console.md#starting-a-rails-console-session). - -1. Check if the feature is enabled. - - - GitLab 14.10: - - ```ruby - Feature.enabled?(:ci_job_artifacts_backlog_work, default_enabled: :yaml) - ``` - - - GitLab 15.0 and later: - - ```ruby - Feature.enabled?(:ci_job_artifacts_backlog_work) - ``` - -1. Enable the feature, if needed: - - ```ruby - Feature.enable(:ci_job_artifacts_backlog_work) - ``` - -The worker processes 10,000 `unknown` artifacts every seven minutes, or roughly two million -in 24 hours. - -There is a related `ci_job_artifacts_backlog_large_loop_limit` feature flag -which causes the worker to process `unknown` artifacts -[in batches that are five times larger](https://gitlab.com/gitlab-org/gitlab/-/issues/356319). -This flag is not recommended for use on self-managed instances. - -#### List projects and builds with artifacts with a specific expiration (or no expiration) - -Using a [Rails console](operations/rails_console.md), you can find projects that have job artifacts with either: - -- No expiration date. -- An expiration date more than 7 days in the future. - -Similar to [deleting artifacts](#delete-job-artifacts-from-jobs-completed-before-a-specific-date), use the following example time frames -and alter them as needed: - -- `7.days.from_now` -- `10.days.from_now` -- `2.weeks.from_now` -- `3.months.from_now` - -Each of the following scripts also limits the search to 50 results with `.limit(50)`, but this number can also be changed as needed: - -```ruby -# Find builds & projects with artifacts that never expire -builds_with_artifacts_that_never_expire = Ci::Build.with_downloadable_artifacts.where(artifacts_expire_at: nil).limit(50) -builds_with_artifacts_that_never_expire.find_each do |build| - puts "Build with id #{build.id} has artifacts that don't expire and belongs to project #{build.project.full_path}" -end - -# Find builds & projects with artifacts that expire after 7 days from today -builds_with_artifacts_that_expire_in_a_week = Ci::Build.with_downloadable_artifacts.where('artifacts_expire_at > ?', 7.days.from_now).limit(50) -builds_with_artifacts_that_expire_in_a_week.find_each do |build| - puts "Build with id #{build.id} has artifacts that expire at #{build.artifacts_expire_at} and belongs to project #{build.project.full_path}" -end -``` - -#### List projects by total size of job artifacts stored - -List the top 20 projects, sorted by the total size of job artifacts stored, by -running the following code in the Rails console (`sudo gitlab-rails console`): - -```ruby -include ActionView::Helpers::NumberHelper -ProjectStatistics.order(build_artifacts_size: :desc).limit(20).each do |s| - puts "#{number_to_human_size(s.build_artifacts_size)} \t #{s.project.full_path}" -end -``` - -You can change the number of projects listed by modifying `.limit(20)` to the -number you want. - -#### List largest artifacts in a single project - -List the 50 largest job artifacts in a single project by running the following -code in the Rails console (`sudo gitlab-rails console`): - -```ruby -include ActionView::Helpers::NumberHelper -project = Project.find_by_full_path('path/to/project') -Ci::JobArtifact.where(project: project).order(size: :desc).limit(50).map { |a| puts "ID: #{a.id} - #{a.file_type}: #{number_to_human_size(a.size)}" } -``` - -You can change the number of job artifacts listed by modifying `.limit(50)` to -the number you want. - -#### List artifacts in a single project - -List the artifacts for a single project, sorted by artifact size. The output includes the: - -- ID of the job that created the artifact -- artifact size -- artifact file type -- artifact creation date -- on-disk location of the artifact - -```ruby -p = Project.find_by_id(<project_id>) -arts = Ci::JobArtifact.where(project: p) - -list = arts.order(size: :desc).limit(50).each do |art| - puts "Job ID: #{art.job_id} - Size: #{art.size}b - Type: #{art.file_type} - Created: #{art.created_at} - File loc: #{art.file}" -end -``` - -To change the number of job artifacts listed, change the number in `limit(50)`. - -#### Delete job artifacts from jobs completed before a specific date - -WARNING: -These commands remove data permanently from both the database and from disk. Before running them, we highly recommend seeking guidance from a Support Engineer, or running them in a test environment with a backup of the instance ready to be restored, just in case. - -If you need to manually remove job artifacts associated with multiple jobs while -**retaining their job logs**, this can be done from the Rails console (`sudo gitlab-rails console`): - -1. Select jobs to be deleted: - - To select all jobs with artifacts for a single project: - - ```ruby - project = Project.find_by_full_path('path/to/project') - builds_with_artifacts = project.builds.with_downloadable_artifacts - ``` - - To select all jobs with artifacts across the entire GitLab instance: - - ```ruby - builds_with_artifacts = Ci::Build.with_downloadable_artifacts - ``` - -1. Delete job artifacts older than a specific date: - - NOTE: - This step also erases artifacts that users have chosen to - ["keep"](../ci/jobs/job_artifacts.md#download-job-artifacts). - - ```ruby - builds_to_clear = builds_with_artifacts.where("finished_at < ?", 1.week.ago) - builds_to_clear.find_each do |build| - Ci::JobArtifacts::DeleteService.new(build).execute - build.update!(artifacts_expire_at: Time.now) - end - ``` - - In [GitLab 15.3 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/372537), use the following instead: - - ```ruby - builds_to_clear = builds_with_artifacts.where("finished_at < ?", 1.week.ago) - builds_to_clear.find_each do |build| - build.artifacts_expire_at = Time.now - build.erase_erasable_artifacts! - end - ``` - - `1.week.ago` is a Rails `ActiveSupport::Duration` method which calculates a new - date or time in the past. Other valid examples are: - - - `7.days.ago` - - `3.months.ago` - - `1.year.ago` - - `erase_erasable_artifacts!` is a synchronous method, and upon execution the artifacts are immediately removed; - they are not scheduled by a background queue. - -#### Delete job artifacts and logs from jobs completed before a specific date - -WARNING: -These commands remove data permanently from both the database and from disk. Before running them, we highly recommend seeking guidance from a Support Engineer, or running them in a test environment with a backup of the instance ready to be restored, just in case. - -If you need to manually remove **all** job artifacts associated with multiple jobs, -**including job logs**, this can be done from the Rails console (`sudo gitlab-rails console`): - -1. Select the jobs to be deleted: - - To select jobs with artifacts for a single project: - - ```ruby - project = Project.find_by_full_path('path/to/project') - builds_with_artifacts = project.builds.with_existing_job_artifacts(Ci::JobArtifact.trace) - ``` - - To select jobs with artifacts across the entire GitLab instance: - - ```ruby - builds_with_artifacts = Ci::Build.with_existing_job_artifacts(Ci::JobArtifact.trace) - ``` - -1. Select the user which is mentioned in the web UI as erasing the job: - - ```ruby - admin_user = User.find_by(username: 'username') - ``` - -1. Erase the job artifacts and logs older than a specific date: - - ```ruby - builds_to_clear = builds_with_artifacts.where("finished_at < ?", 1.week.ago) - builds_to_clear.find_each do |build| - print "Ci::Build ID #{build.id}... " - - if build.erasable? - Ci::BuildEraseService.new(build, admin_user).execute - puts "Erased" - else - puts "Skipped (Nothing to erase or not erasable)" - end - end - ``` - - In [GitLab 15.3 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/369132), replace - `Ci::BuildEraseService.new(build, admin_user).execute` with `build.erase(erased_by: admin_user)`. - - `1.week.ago` is a Rails `ActiveSupport::Duration` method which calculates a new - date or time in the past. Other valid examples are: - - - `7.days.ago` - - `3.months.ago` - - `1.year.ago` - -### Job artifact upload fails with error 500 - -If you are using object storage for artifacts and a job artifact fails to upload, -review: - -- The job log for an error message similar to: - - ```plaintext - WARNING: Uploading artifacts as "archive" to coordinator... failed id=12345 responseStatus=500 Internal Server Error status=500 token=abcd1234 - ``` - -- The [workhorse log](logs/index.md#workhorse-logs) for an error message similar to: - - ```json - {"error":"MissingRegion: could not find region configuration","level":"error","msg":"error uploading S3 session","time":"2021-03-16T22:10:55-04:00"} - ``` - -In both cases, you might need to add `region` to the job artifact [object storage configuration](object_storage.md). - -### Job artifact upload fails with `500 Internal Server Error (Missing file)` - -Bucket names that include folder paths are not supported with [consolidated object storage](object_storage.md#configure-a-single-storage-connection-for-all-object-types-consolidated-form). -For example, `bucket/path`. If a bucket name has a path in it, you might receive an error similar to: - -```plaintext -WARNING: Uploading artifacts as "archive" to coordinator... POST https://gitlab.example.com/api/v4/jobs/job_id/artifacts?artifact_format=zip&artifact_type=archive&expire_in=1+day: 500 Internal Server Error (Missing file) -FATAL: invalid argument -``` - -If a job artifact fails to upload with the above error when using consolidated object storage, make sure you are [using separate buckets](object_storage.md#use-separate-buckets) for each data type. - -### Job artifacts fail to upload with `FATAL: invalid argument` when using Windows mount - -If you are using a Windows mount with CIFS for job artifacts, you may see an -`invalid argument` error when the runner attempts to upload artifacts: - -```plaintext -WARNING: Uploading artifacts as "dotenv" to coordinator... POST https://<your-gitlab-instance>/api/v4/jobs/<JOB_ID>/artifacts: 500 Internal Server Error id=1296 responseStatus=500 Internal Server Error status=500 token=***** -FATAL: invalid argument -``` - -To work around this issue, you can try: - -- Switching to an ext4 mount instead of CIFS. -- Upgrading to at least Linux kernel 5.15 which contains a number of important bug fixes - relating to CIFS file leases. -- For older kernels, using the `nolease` mount option to disable file leasing. - -For more information, [see the investigation details](https://gitlab.com/gitlab-org/gitlab/-/issues/389995). - -### Usage quota shows incorrect artifact storage usage - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238536) in GitLab 14.10. - -Sometimes the [artifacts storage usage](../user/usage_quotas.md) displays an incorrect -value for the total storage space used by artifacts. To recalculate the artifact -usage statistics for all projects in the instance, you can run this background script: - -```shell -bin/rake 'gitlab:refresh_project_statistics_build_artifacts_size[file.csv]' -``` - -The artifact usage value can fluctuate to `0` while the script is running. After -recalculation, usage should display as expected again. diff --git a/doc/administration/job_artifacts_troubleshooting.md b/doc/administration/job_artifacts_troubleshooting.md new file mode 100644 index 00000000000..ba60cbd7aba --- /dev/null +++ b/doc/administration/job_artifacts_troubleshooting.md @@ -0,0 +1,460 @@ +--- +stage: Verify +group: Pipeline Security +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 +--- + +# Job artifact troubleshooting for administrators + +When administering job artifacts, you might encounter the following issues. + +## Job artifacts using too much disk space + +Job artifacts can fill up your disk space quicker than expected. Some possible +reasons are: + +- Users have configured job artifacts expiration to be longer than necessary. +- The number of jobs run, and hence artifacts generated, is higher than expected. +- Job logs are larger than expected, and have accumulated over time. +- The file system might run out of inodes because + [empty directories are left behind by artifact housekeeping](https://gitlab.com/gitlab-org/gitlab/-/issues/17465). + [The Rake task for _orphaned_ artifact files](../raketasks/cleanup.md#remove-orphan-artifact-files) + removes these. +- Artifact files might be left on disk and not deleted by housekeeping. Run the + [Rake task for _orphaned_ artifact files](../raketasks/cleanup.md#remove-orphan-artifact-files) + to remove these. This script should always find work to do, as it also removes empty directories (see above). +- [Artifact housekeeping was changed significantly](#housekeeping-disabled-in-gitlab-146-to-152), + and you might need to enable a feature flag to used the updated system. +- The [keep latest artifacts from most recent success jobs](../ci/jobs/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs) + feature is enabled. + +In these and other cases, identify the projects most responsible +for disk space usage, figure out what types of artifacts are using the most +space, and in some cases, manually delete job artifacts to reclaim disk space. + +### Artifacts housekeeping + +Artifacts housekeeping is the process that identifies which artifacts are expired +and can be deleted. + +#### Housekeeping disabled in GitLab 14.6 to 15.2 + +Artifact housekeeping was disabled in GitLab 14.6. It was significantly improved +in GitLab 14.10, and the changes were back ported to patch versions of GitLab 14.6 and later, +introduced behind [feature flags](feature_flags.md) disabled by default. The flags were +enabled by default [in GitLab 15.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92931). + +If artifacts housekeeping does not seem to be working in GitLab 14.6 to GitLab 15.2, +you should check if the feature flags are enabled. + +To check if the feature flags are enabled: + +1. Start a [Rails console](operations/rails_console.md#starting-a-rails-console-session). + +1. Check if the feature flags are enabled. + + - GitLab 14.10 and earlier: + + ```ruby + Feature.enabled?(:ci_detect_wrongly_expired_artifacts, default_enabled: :yaml) + Feature.enabled?(:ci_update_unlocked_job_artifacts, default_enabled: :yaml) + Feature.enabled?(:ci_job_artifacts_backlog_work, default_enabled: :yaml) + ``` + + - GitLab 15.0 and later: + + ```ruby + Feature.enabled?(:ci_detect_wrongly_expired_artifacts) + Feature.enabled?(:ci_update_unlocked_job_artifacts) + Feature.enabled?(:ci_job_artifacts_backlog_work) + ``` + +1. If any of the feature flags are disabled, enable them: + + ```ruby + Feature.enable(:ci_detect_wrongly_expired_artifacts) + Feature.enable(:ci_update_unlocked_job_artifacts) + Feature.enable(:ci_destroy_unlocked_job_artifacts) + ``` + +These changes include switching artifacts from `unlocked` to `locked` if +they [should be retained](../ci/jobs/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). + +#### Artifacts with `unknown` status + +Artifacts created before housekeeping was updated have a status of `unknown`. After they expire, +these artifacts are not processed by the new housekeeping. + +You can check the database to confirm if your instance has artifacts with the `unknown` status: + +1. Start a database console: + + ::Tabs + + :::TabTitle Linux package (Omnibus) + + ```shell + sudo gitlab-psql + ``` + + :::TabTitle Helm chart (Kubernetes) + + ```shell + # Find the toolbox pod + kubectl --namespace <namespace> get pods -lapp=toolbox + # Connect to the PostgreSQL console + kubectl exec -it <toolbox-pod-name> -- /srv/gitlab/bin/rails dbconsole --include-password --database main + ``` + + :::TabTitle Docker + + ```shell + sudo docker exec -it <container_name> /bin/bash + gitlab-psql + ``` + + :::TabTitle Self-compiled (source) + + ```shell + sudo -u git -H psql -d gitlabhq_production + ``` + + ::EndTabs + +1. Run the following query: + + ```sql + select expire_at, file_type, locked, count(*) from ci_job_artifacts + where expire_at is not null and + file_type != 3 + group by expire_at, file_type, locked having count(*) > 1; + ``` + +If records are returned, then there are artifacts which the housekeeping job +is unable to process. For example: + +```plaintext + expire_at | file_type | locked | count +-------------------------------+-----------+--------+-------- + 2021-06-21 22:00:00+00 | 1 | 2 | 73614 + 2021-06-21 22:00:00+00 | 2 | 2 | 73614 + 2021-06-21 22:00:00+00 | 4 | 2 | 3522 + 2021-06-21 22:00:00+00 | 9 | 2 | 32 + 2021-06-21 22:00:00+00 | 12 | 2 | 163 +``` + +Artifacts with locked status `2` are `unknown`. Check +[issue #346261](https://gitlab.com/gitlab-org/gitlab/-/issues/346261#note_1028871458) +for more details. + +#### Clean up `unknown` artifacts + +The Sidekiq worker that processes all `unknown` artifacts is enabled by default in +GitLab 15.3 and later. It analyzes the artifacts returned by the above database query and +determines which should be `locked` or `unlocked`. Artifacts are then deleted +by that worker if needed. + +The worker can be enabled on self-managed instances running GitLab 14.10 and later: + +1. Start a [Rails console](operations/rails_console.md#starting-a-rails-console-session). + +1. Check if the feature is enabled. + + - GitLab 14.10: + + ```ruby + Feature.enabled?(:ci_job_artifacts_backlog_work, default_enabled: :yaml) + ``` + + - GitLab 15.0 and later: + + ```ruby + Feature.enabled?(:ci_job_artifacts_backlog_work) + ``` + +1. Enable the feature, if needed: + + ```ruby + Feature.enable(:ci_job_artifacts_backlog_work) + ``` + +The worker processes 10,000 `unknown` artifacts every seven minutes, or roughly two million +in 24 hours. + +There is a related `ci_job_artifacts_backlog_large_loop_limit` feature flag +which causes the worker to process `unknown` artifacts +[in batches that are five times larger](https://gitlab.com/gitlab-org/gitlab/-/issues/356319). +This flag is not recommended for use on self-managed instances. + +### List projects and builds with artifacts with a specific expiration (or no expiration) + +Using a [Rails console](operations/rails_console.md), you can find projects that have job artifacts with either: + +- No expiration date. +- An expiration date more than 7 days in the future. + +Similar to [deleting artifacts](#delete-job-artifacts-from-jobs-completed-before-a-specific-date), use the following example time frames +and alter them as needed: + +- `7.days.from_now` +- `10.days.from_now` +- `2.weeks.from_now` +- `3.months.from_now` + +Each of the following scripts also limits the search to 50 results with `.limit(50)`, but this number can also be changed as needed: + +```ruby +# Find builds & projects with artifacts that never expire +builds_with_artifacts_that_never_expire = Ci::Build.with_downloadable_artifacts.where(artifacts_expire_at: nil).limit(50) +builds_with_artifacts_that_never_expire.find_each do |build| + puts "Build with id #{build.id} has artifacts that don't expire and belongs to project #{build.project.full_path}" +end + +# Find builds & projects with artifacts that expire after 7 days from today +builds_with_artifacts_that_expire_in_a_week = Ci::Build.with_downloadable_artifacts.where('artifacts_expire_at > ?', 7.days.from_now).limit(50) +builds_with_artifacts_that_expire_in_a_week.find_each do |build| + puts "Build with id #{build.id} has artifacts that expire at #{build.artifacts_expire_at} and belongs to project #{build.project.full_path}" +end +``` + +### List projects by total size of job artifacts stored + +List the top 20 projects, sorted by the total size of job artifacts stored, by +running the following code in the Rails console (`sudo gitlab-rails console`): + +```ruby +include ActionView::Helpers::NumberHelper +ProjectStatistics.order(build_artifacts_size: :desc).limit(20).each do |s| + puts "#{number_to_human_size(s.build_artifacts_size)} \t #{s.project.full_path}" +end +``` + +You can change the number of projects listed by modifying `.limit(20)` to the +number you want. + +### List largest artifacts in a single project + +List the 50 largest job artifacts in a single project by running the following +code in the Rails console (`sudo gitlab-rails console`): + +```ruby +include ActionView::Helpers::NumberHelper +project = Project.find_by_full_path('path/to/project') +Ci::JobArtifact.where(project: project).order(size: :desc).limit(50).map { |a| puts "ID: #{a.id} - #{a.file_type}: #{number_to_human_size(a.size)}" } +``` + +You can change the number of job artifacts listed by modifying `.limit(50)` to +the number you want. + +### List artifacts in a single project + +List the artifacts for a single project, sorted by artifact size. The output includes the: + +- ID of the job that created the artifact +- artifact size +- artifact file type +- artifact creation date +- on-disk location of the artifact + +```ruby +p = Project.find_by_id(<project_id>) +arts = Ci::JobArtifact.where(project: p) + +list = arts.order(size: :desc).limit(50).each do |art| + puts "Job ID: #{art.job_id} - Size: #{art.size}b - Type: #{art.file_type} - Created: #{art.created_at} - File loc: #{art.file}" +end +``` + +To change the number of job artifacts listed, change the number in `limit(50)`. + +### Delete job artifacts from jobs completed before a specific date + +WARNING: +These commands remove data permanently from both the database and from disk. Before running them, we highly recommend seeking guidance from a Support Engineer, or running them in a test environment with a backup of the instance ready to be restored, just in case. + +If you need to manually remove job artifacts associated with multiple jobs while +**retaining their job logs**, this can be done from the Rails console (`sudo gitlab-rails console`): + +1. Select jobs to be deleted: + + To select all jobs with artifacts for a single project: + + ```ruby + project = Project.find_by_full_path('path/to/project') + builds_with_artifacts = project.builds.with_downloadable_artifacts + ``` + + To select all jobs with artifacts across the entire GitLab instance: + + ```ruby + builds_with_artifacts = Ci::Build.with_downloadable_artifacts + ``` + +1. Delete job artifacts older than a specific date: + + NOTE: + This step also erases artifacts that users have chosen to + ["keep"](../ci/jobs/job_artifacts.md#download-job-artifacts). + + ```ruby + builds_to_clear = builds_with_artifacts.where("finished_at < ?", 1.week.ago) + builds_to_clear.find_each do |build| + Ci::JobArtifacts::DeleteService.new(build).execute + build.update!(artifacts_expire_at: Time.now) + end + ``` + + In [GitLab 15.3 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/372537), use the following instead: + + ```ruby + builds_to_clear = builds_with_artifacts.where("finished_at < ?", 1.week.ago) + builds_to_clear.find_each do |build| + build.artifacts_expire_at = Time.now + build.erase_erasable_artifacts! + end + ``` + + `1.week.ago` is a Rails `ActiveSupport::Duration` method which calculates a new + date or time in the past. Other valid examples are: + + - `7.days.ago` + - `3.months.ago` + - `1.year.ago` + + `erase_erasable_artifacts!` is a synchronous method, and upon execution the artifacts are immediately removed; + they are not scheduled by a background queue. + +### Delete job artifacts and logs from jobs completed before a specific date + +WARNING: +These commands remove data permanently from both the database and from disk. Before running them, we highly recommend seeking guidance from a Support Engineer, or running them in a test environment with a backup of the instance ready to be restored, just in case. + +If you need to manually remove **all** job artifacts associated with multiple jobs, +**including job logs**, this can be done from the Rails console (`sudo gitlab-rails console`): + +1. Select the jobs to be deleted: + + To select jobs with artifacts for a single project: + + ```ruby + project = Project.find_by_full_path('path/to/project') + builds_with_artifacts = project.builds.with_downloadable_artifacts + ``` + + To select jobs with artifacts across the entire GitLab instance: + + ```ruby + builds_with_artifacts = Ci::Build.with_downloadable_artifacts + ``` + + Occasionally, when choosing jobs with artifacts, there could be a risk of the process being terminated due to selecting a large number of rows. This can result in high memory usage and eventually lead to the process being killed due to an Out-of-Memory (OOM) error. To resolve this, you can run in small batches. The example below limits each batch to 1000. + + To select jobs with artifacts for a single project: + + ```ruby + project = Project.find_by_full_path('path/to/project') + builds_with_artifacts = project.builds.with_downloadable_artifacts.find_each(batch_size: 1000) + ``` + + To select jobs with artifacts across the entire GitLab instance: + + ```ruby + builds_with_artifacts = Ci::Build.with_downloadable_artifacts.find_each(batch_size: 1000) + ``` + +1. Select the user which is mentioned in the web UI as erasing the job: + + ```ruby + admin_user = User.find_by(username: 'username') + ``` + +1. Erase the job artifacts and logs older than a specific date: + + ```ruby + builds_to_clear = builds_with_artifacts.where("finished_at < ?", 1.week.ago) + builds_to_clear.find_each do |build| + print "Ci::Build ID #{build.id}... " + + if build.erasable? + Ci::BuildEraseService.new(build, admin_user).execute + puts "Erased" + else + puts "Skipped (Nothing to erase or not erasable)" + end + end + ``` + + In [GitLab 15.3 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/369132), replace + `Ci::BuildEraseService.new(build, admin_user).execute` with `build.erase(erased_by: admin_user)`. + + `1.week.ago` is a Rails `ActiveSupport::Duration` method which calculates a new + date or time in the past. Other valid examples are: + + - `7.days.ago` + - `3.months.ago` + - `1.year.ago` + +## Job artifact upload fails with error 500 + +If you are using object storage for artifacts and a job artifact fails to upload, +review: + +- The job log for an error message similar to: + + ```plaintext + WARNING: Uploading artifacts as "archive" to coordinator... failed id=12345 responseStatus=500 Internal Server Error status=500 token=abcd1234 + ``` + +- The [workhorse log](logs/index.md#workhorse-logs) for an error message similar to: + + ```json + {"error":"MissingRegion: could not find region configuration","level":"error","msg":"error uploading S3 session","time":"2021-03-16T22:10:55-04:00"} + ``` + +In both cases, you might need to add `region` to the job artifact [object storage configuration](object_storage.md). + +## Job artifact upload fails with `500 Internal Server Error (Missing file)` + +Bucket names that include folder paths are not supported with [consolidated object storage](object_storage.md#configure-a-single-storage-connection-for-all-object-types-consolidated-form). +For example, `bucket/path`. If a bucket name has a path in it, you might receive an error similar to: + +```plaintext +WARNING: Uploading artifacts as "archive" to coordinator... POST https://gitlab.example.com/api/v4/jobs/job_id/artifacts?artifact_format=zip&artifact_type=archive&expire_in=1+day: 500 Internal Server Error (Missing file) +FATAL: invalid argument +``` + +If a job artifact fails to upload with the above error when using consolidated object storage, make sure you are [using separate buckets](object_storage.md#use-separate-buckets) for each data type. + +## Job artifacts fail to upload with `FATAL: invalid argument` when using Windows mount + +If you are using a Windows mount with CIFS for job artifacts, you may see an +`invalid argument` error when the runner attempts to upload artifacts: + +```plaintext +WARNING: Uploading artifacts as "dotenv" to coordinator... POST https://<your-gitlab-instance>/api/v4/jobs/<JOB_ID>/artifacts: 500 Internal Server Error id=1296 responseStatus=500 Internal Server Error status=500 token=***** +FATAL: invalid argument +``` + +To work around this issue, you can try: + +- Switching to an ext4 mount instead of CIFS. +- Upgrading to at least Linux kernel 5.15 which contains a number of important bug fixes + relating to CIFS file leases. +- For older kernels, using the `nolease` mount option to disable file leasing. + +For more information, [see the investigation details](https://gitlab.com/gitlab-org/gitlab/-/issues/389995). + +## Usage quota shows incorrect artifact storage usage + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238536) in GitLab 14.10. + +Sometimes the [artifacts storage usage](../user/usage_quotas.md) displays an incorrect +value for the total storage space used by artifacts. To recalculate the artifact +usage statistics for all projects in the instance, you can run this background script: + +```shell +bin/rake 'gitlab:refresh_project_statistics_build_artifacts_size[file.csv]' +``` + +The artifact usage value can fluctuate to `0` while the script is running. After +recalculation, usage should display as expected again. diff --git a/doc/administration/libravatar.md b/doc/administration/libravatar.md index 1b7406546ef..899269fb9d1 100644 --- a/doc/administration/libravatar.md +++ b/doc/administration/libravatar.md @@ -52,7 +52,7 @@ For self-compiled installations: ssl_url: https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" ``` -1. Save the file, and then [restart](restart_gitlab.md#installations-from-source) +1. Save the file, and then [restart](restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. ## Set the Libravatar service to default (Gravatar) @@ -65,7 +65,7 @@ For Linux package installations: For self-compiled installations: 1. Remove `gravatar:` section from `config/gitlab.yml`. -1. Save the file, then [restart](restart_gitlab.md#installations-from-source) +1. Save the file, then [restart](restart_gitlab.md#self-compiled-installations) GitLab to apply the changes. ## Disable Gravatar service @@ -91,7 +91,7 @@ For self-compiled installations: enabled: false ``` -1. Save the file, then [restart](restart_gitlab.md#installations-from-source) +1. Save the file, then [restart](restart_gitlab.md#self-compiled-installations) GitLab to apply the changes. ### Your own Libravatar server diff --git a/doc/administration/logs/index.md b/doc/administration/logs/index.md index 449f33fbbef..bfab17d37e8 100644 --- a/doc/administration/logs/index.md +++ b/doc/administration/logs/index.md @@ -66,6 +66,7 @@ Some of these services have their own environment variables to override the log | Sidekiq (server) | `INFO` | | | Snowplow Tracker | `FATAL` | | | gRPC Client (Gitaly) | `WARN` | `GRPC_LOG_LEVEL` | +| LLM | `INFO` | `LLM_DEBUG` | ## Log Rotation @@ -466,7 +467,7 @@ only. For example: } ``` -## `audit_json.log` **(FREE)** +## `audit_json.log` **(FREE ALL)** NOTE: GitLab Free tracks a small number of different audit events. @@ -552,7 +553,7 @@ For Linux package installations, add the configuration option: sidekiq['log_format'] = 'json' ``` -For installations from source, edit the `gitlab.yml` and set the Sidekiq +For self-compiled installations, edit the `gitlab.yml` and set the Sidekiq `log_format` configuration option: ```yaml @@ -819,6 +820,23 @@ This file is located at: This structured log file records internal activity in the `mail_room` gem. Its name and path are configurable, so the name and path may not match the above. +## `web_hooks.log` + +> Introduced in GitLab 16.3. + +This file is located at: + +- `/var/log/gitlab/gitlab-rails/web_hooks.log` on Linux package installations. +- `/home/git/gitlab/log/web_hooks.log` on self-compiled installations. + +The back-off, disablement, and re-enablement events for Webhook are recorded in this file. For example: + +```json +{"severity":"INFO","time":"2020-11-24T02:30:59.860Z","hook_id":12,"action":"backoff","disabled_until":"2020-11-24T04:30:59.860Z","backoff_count":2,"recent_failures":2} +{"severity":"INFO","time":"2020-11-24T02:30:59.860Z","hook_id":12,"action":"disable","disabled_until":null,"backoff_count":5,"recent_failures":100} +{"severity":"INFO","time":"2020-11-24T02:30:59.860Z","hook_id":12,"action":"enable","disabled_until":null,"backoff_count":0,"recent_failures":0} +``` + ## Reconfigure logs Reconfigure log files are in `/var/log/gitlab/reconfigure` for Linux package installations. Self-compiled installations @@ -951,7 +969,7 @@ For example: ## `geo.log` **(PREMIUM SELF)** -Geo stores structured log messages in a `geo.log` file. For Omnibus GitLab +Geo stores structured log messages in a `geo.log` file. For Linux package installations, this file is at `/var/log/gitlab/gitlab-rails/geo.log`. This file contains information about when Geo attempts to sync repositories @@ -1127,7 +1145,7 @@ GitLab also tracks [Prometheus metrics for Praefect](../gitaly/monitoring.md#mon > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63832) in GitLab 14.1. -For Omnibus installations, the backup log is located at `/var/log/gitlab/gitlab-rails/backup_json.log`. +For Linux package installations, the backup log is located at `/var/log/gitlab/gitlab-rails/backup_json.log`. This log is populated when a [GitLab backup is created](../../administration/backup_restore/index.md). You can use this log to understand how the backup process performed. diff --git a/doc/administration/maintenance_mode/index.md b/doc/administration/maintenance_mode/index.md index 336067d1891..c5674527291 100644 --- a/doc/administration/maintenance_mode/index.md +++ b/doc/administration/maintenance_mode/index.md @@ -173,6 +173,8 @@ Package Registry allows you to install but not publish packages. ### Background jobs Background jobs (cron jobs, Sidekiq) continue running as is, because background jobs are not automatically disabled. +As background jobs perform operations that can change the internal state of your instance, you may want to disable +some or all of them while maintenance mode is enabled. [During a planned Geo failover](../geo/disaster_recovery/planned_failover.md#prevent-updates-to-the-primary-site), you should disable all cron jobs except for those related to Geo. @@ -182,6 +184,7 @@ To monitor queues and disable jobs: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. 1. On the left sidebar, select **Monitoring > Background Jobs**. +1. In the Sidekiq dashboard, select **Cron** and disable jobs individually or all at once by selecting **Disable All**. ### Incident management diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md index 00ea1e43600..746dccb99d6 100644 --- a/doc/administration/merge_request_diffs.md +++ b/doc/administration/merge_request_diffs.md @@ -62,7 +62,7 @@ For self-compiled installations: storage_path: /mnt/storage/external-diffs ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect. GitLab then migrates your existing merge request diffs to external storage. ## Using object storage @@ -97,7 +97,7 @@ For self-compiled installations: ``` 1. Set [object storage settings](#object-storage-settings). -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect. GitLab then migrates your existing merge request diffs to external storage. [Read more about using object storage with GitLab](object_storage.md). @@ -108,7 +108,7 @@ In GitLab 13.2 and later, you should use the [consolidated object storage settings](object_storage.md#configure-a-single-storage-connection-for-all-object-types-consolidated-form). This section describes the earlier configuration format. -For source installations, these settings are nested under `external_diffs:` and +For self-compiled installations, these settings are nested under `external_diffs:` and then `object_store:`. On Linux package installations, they are prefixed by `external_diffs_object_store_`. @@ -171,7 +171,7 @@ For self-compiled installations: region: eu-central-1 ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect. ## Alternative in-database storage @@ -203,7 +203,7 @@ For self-compiled installations: when: outdated ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect. With this feature enabled, diffs are initially stored in the database, rather than externally. They are moved to external storage after any of these diff --git a/doc/administration/monitoring/ip_allowlist.md b/doc/administration/monitoring/ip_allowlist.md index 364c1b27d33..c5f81e65466 100644 --- a/doc/administration/monitoring/ip_allowlist.md +++ b/doc/administration/monitoring/ip_allowlist.md @@ -49,6 +49,6 @@ gitlab: - 192.168.0.1 ``` -1. Save the file and [restart](../restart_gitlab.md#installations-from-source) GitLab for the changes to take effect. +1. Save the file and [restart](../restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. ::EndTabs diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index 8b3720ca8a9..72240be0b35 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -4,81 +4,29 @@ group: Respond 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 --- -# Grafana Configuration **(FREE SELF)** +# Configure Grafana **(FREE SELF)** -> [Deprecated](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7772) in GitLab 16.0. - -WARNING: -Bundled Grafana was deprecated GitLab 16.0 and is no longer supported. It will be removed in GitLab 16.3. -For more information, see [deprecation notes](#deprecation-of-bundled-grafana). +> - Grafana bundled with GitLab was [deprecated](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7772) in GitLab 16.0. +> - Grafana bundled with GitLab was [removed](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7772) in GitLab 16.3. [Grafana](https://grafana.com/) is a tool that enables you to visualize time series metrics through graphs and dashboards. GitLab writes performance data to Prometheus, and Grafana allows you to query the data to display graphs. -## Deprecation of bundled Grafana - -Bundled Grafana was an optional service for Linux package installations that provided a user interface to GitLab metrics. - -The version of Grafana that is bundled with Linux package installations is no longer supported. If you're using the -bundled Grafana, you should switch to a newer version from [Grafana Labs](https://grafana.com/grafana/). - -### Switch to new Grafana instance - -To switch away from bundled Grafana to a newer version of Grafana from Grafana Labs: - -1. Set up a version of Grafana from Grafana Labs. -1. [Export the existing dashboards](https://grafana.com/docs/grafana/latest/dashboards/manage-dashboards/#export-a-dashboard) from bundled Grafana. -1. [Import the existing dashboards](https://grafana.com/docs/grafana/latest/dashboards/manage-dashboards/#import-a-dashboard) in the new Grafana instance. -1. [Configure GitLab](#integrate-with-gitlab-ui) to use the new Grafana instance. - -### Temporary workaround - -In GitLab versions 16.0 to 16.2, you can still force Linux package installations to enable and configure Grafana by -setting the following: - -- `grafana['enable'] = true`. -- `grafana['enable_deprecated_service'] = true`. - -You see a deprecation message when reconfiguring GitLab. - -## Configure Grafana - -Prerequisites: - -- Grafana installed. - -1. Log in to Grafana as the administration user. -1. Select **Data Sources** from the **Configuration** menu. -1. Select **Add data source**. -1. Select the required data source type. For example, [Prometheus](../prometheus/index.md#prometheus-as-a-grafana-data-source). -1. Complete the details for the data source and select **Save & Test**. - -Grafana should indicate the data source is working. +WARNING: +Grafana bundled with GitLab was deprecated GitLab 16.0 and removed in GitLab 16.3. +For more information, see [deprecation notes](#deprecation-of-bundled-grafana). -## Import dashboards +## Import GitLab dashboards -You can now import a set of default dashboards to start displaying information. -GitLab has published a set of default -[Grafana dashboards](https://gitlab.com/gitlab-org/grafana-dashboards) to get you started. To use -them: +You can import a set of default dashboards to start displaying information. GitLab has published a set of default +[Grafana dashboards](https://gitlab.com/gitlab-org/grafana-dashboards) to get you started. To use them: 1. Clone the repository, or download a ZIP file or tarball. -1. Follow these steps to import each JSON file individually: - - 1. Log in to Grafana as the administration user. - 1. Select **Manage** from the **Dashboards** menu. - 1. Select **Import**, then **Upload JSON file**. - 1. Locate the JSON file to import and select **Choose for Upload**. Select **Import**. - 1. After the dashboard is imported, select the **Save dashboard** icon in the top bar. +1. Follow these steps to [import each dashboard JSON file individually](https://grafana.com/docs/grafana/latest/dashboards/manage-dashboards/#import-a-dashboard) -If you don't save the dashboard after importing it, the dashboard is removed -when you navigate away from the page. Repeat this process for each dashboard you wish to import. - -Alternatively, you can import all the dashboards into your Grafana -instance. For more information about this process, see the -[README of the Grafana dashboards](https://gitlab.com/gitlab-org/grafana-dashboards) -repository. +Alternatively, you can import all the dashboards into your Grafana instance. For more information about this process, +see the [GitLab Grafana dashboards](https://gitlab.com/gitlab-org/grafana-dashboards). ## Integrate with GitLab UI @@ -92,10 +40,7 @@ GitLab sidebar: 1. On the left sidebar, select **Settings > Metrics and profiling** and expand **Metrics - Grafana**. 1. Select the **Add a link to Grafana** checkbox. -1. Configure the **Grafana URL**: - - If Grafana is enabled through a Linux package installation and on the same server, - leave **Grafana URL** unchanged. It should be `/-/grafana`. - - Otherwise, enter the full URL of the Grafana instance. +1. Configure the **Grafana URL**. Enter the full URL of the Grafana instance. 1. Select **Save changes**. GitLab displays your link in the **Main menu > Admin > Monitoring > Metrics Dashboard**. @@ -120,57 +65,18 @@ configuration screen: - No scopes appear. - The `read_user` scope is included. -> Versions of GitLab prior 13.10 use the API scope instead of `read_user`. In versions of GitLab -> prior to 13.10, the API scope: -> -> - Is required to access Grafana through the GitLab OAuth provider. -> - Is set by enabling the Grafana application as shown in [Integration with GitLab UI](#integrate-with-gitlab-ui). - -## Security Update - -Users running GitLab version 12.0 or later should immediately upgrade to one of the -following security releases due to a known vulnerability with the embedded Grafana dashboard: - -- 12.0.6 -- 12.1.6 - -After upgrading, the Grafana dashboard is disabled, and the location of your -existing Grafana data is changed from `/var/opt/gitlab/grafana/data/` to -`/var/opt/gitlab/grafana/data.bak.#{Date.today}/`. - -To prevent the data from being relocated, you can run the following command prior to upgrading: - -```shell -echo "0" > /var/opt/gitlab/grafana/CVE_reset_status -``` - -To reinstate your old data, move it back into its original location: - -```shell -sudo mv /var/opt/gitlab/grafana/data.bak.xxxx/ /var/opt/gitlab/grafana/data/ -``` - -However, you should **not** reinstate your old data _except_ under one of the following conditions: - -1. If you're certain that you changed your default administration password when you enabled Grafana. -1. If you run GitLab in a private network, accessed only by trusted users, and your - Grafana login page has not been exposed to the internet. - -If you require access to your old Grafana data but don't meet one of these criteria, you may consider: +## Deprecation of bundled Grafana -1. Reinstating it temporarily. -1. [Exporting the dashboards](https://grafana.com/docs/grafana/latest/dashboards/manage-dashboards/#export-and-import-dashboards) you need. -1. Refreshing the data and [re-importing your dashboards](https://grafana.com/docs/grafana/latest/dashboards/manage-dashboards/#export-and-import-dashboards). +Bundled Grafana was an optional service for Linux package installations that provided a user interface to GitLab metrics. -WARNING: -These actions pose a temporary vulnerability while your old Grafana data is in use. -Deciding to take any of these actions should be weighed carefully with your need to access -existing data and dashboards. +The version of Grafana that is bundled with Linux package installations is no longer supported. If you're using the +bundled Grafana, you should switch to a newer version from [Grafana Labs](https://grafana.com/grafana/). -For more information and further mitigation details, refer to our -[blog post on the security release](https://about.gitlab.com/releases/2019/08/12/critical-security-release-gitlab-12-dot-1-dot-6-released/). +### Switch to new Grafana instance -Read more on: +To switch away from bundled Grafana to a newer version of Grafana from Grafana Labs: -- [Introduction to GitLab Performance Monitoring](index.md) -- [GitLab Configuration](gitlab_configuration.md) +1. Set up a version of Grafana from Grafana Labs. +1. [Export the existing dashboards](https://grafana.com/docs/grafana/latest/dashboards/manage-dashboards/#export-a-dashboard) from bundled Grafana. +1. [Import the existing dashboards](https://grafana.com/docs/grafana/latest/dashboards/manage-dashboards/#import-a-dashboard) in the new Grafana instance. +1. [Configure GitLab](#integrate-with-gitlab-ui) to use the new Grafana instance. diff --git a/doc/administration/monitoring/prometheus/gitlab_exporter.md b/doc/administration/monitoring/prometheus/gitlab_exporter.md index 22b73378cab..f4bc387cc8e 100644 --- a/doc/administration/monitoring/prometheus/gitlab_exporter.md +++ b/doc/administration/monitoring/prometheus/gitlab_exporter.md @@ -12,7 +12,7 @@ The [GitLab exporter](https://gitlab.com/gitlab-org/gitlab-exporter) enables you measure various GitLab metrics pulled from Redis and the database in Linux package instances. -For installations from source you must install and configure it yourself. +For self-compiled installations, you must install and configure it yourself. To enable the GitLab exporter in a Linux package instance: diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 713a1fb3b5d..6566def823c 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -15,7 +15,7 @@ To enable the GitLab Prometheus metrics: 1. Find the **Metrics - Prometheus** section, and select **Enable GitLab Prometheus metrics endpoint**. 1. [Restart GitLab](../../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. -For installations from source you must configure it yourself. +For self-compiled installations, you must configure it yourself. ## Collecting the metrics @@ -170,6 +170,16 @@ The following metrics are available: | `gitlab_sli_rails_request_apdex_total` | Counter | 14.4 | Total number of request Apdex measurements. For more information, see [Rails request SLIs](../../../development/application_slis/rails_request.md) | `endpoint_id`, `feature_category`, `request_urgency` | | `gitlab_sli_rails_request_apdex_success_total` | Counter | 14.4 | Total number of successful requests that met the target duration for their urgency. Divide by `gitlab_sli_rails_requests_apdex_total` to get a success ratio | `endpoint_id`, `feature_category`, `request_urgency` | | `gitlab_sli_rails_request_error_total` | Counter | 15.7 | Total number of request error measurements. For more information, see [Rails request SLIs](../../../development/application_slis/rails_request.md) | `endpoint_id`, `feature_category`, `request_urgency`, `error` | +| `job_register_attempts_failed_total` | Counter | 9.5 | Counts the times a runner fails to register a job | +| `job_register_attempts_total` | Counter | 9.5 | Counts the times a runner tries to register a job | +| `job_queue_duration_seconds` | Histogram | 9.5 | Request handling execution time | +| `gitlab_ci_queue_operations_total` | Counter | 16.3 | Counts all the operations that are happening inside a queue | +| `gitlab_ci_queue_depth_total` | Histogram | 16.3 | Size of a CI/CD builds queue in relation to the operation result | +| `gitlab_ci_queue_size_total` | Histogram | 16.3 | Size of initialized CI/CD builds queue | +| `gitlab_ci_current_queue_size` | Gauge | 16.3 | Current size of initialized CI/CD builds queue | +| `gitlab_ci_queue_iteration_duration_seconds` | Histogram | 16.3 | Time it takes to find a build in CI/CD queue | +| `gitlab_ci_queue_retrieval_duration_seconds` | Histogram | 16.3 | Time it takes to execute a SQL query to retrieve builds queue | +| `gitlab_ci_queue_active_runners_total` | Histogram | 16.3 | The amount of active runners that can process queue in a project | ## Metrics controlled by a feature flag @@ -178,6 +188,13 @@ The following metrics can be controlled by feature flags: | Metric | Feature flag | |:---------------------------------------------------------------|:-------------------------------------------------------------------| | `gitlab_view_rendering_duration_seconds` | `prometheus_metrics_view_instrumentation` | +| `gitlab_ci_queue_depth_total` | `gitlab_ci_builds_queuing_metrics` | +| `gitlab_ci_queue_size` | `gitlab_ci_builds_queuing_metrics` | +| `gitlab_ci_queue_size_total` | `gitlab_ci_builds_queuing_metrics` | +| `gitlab_ci_queue_iteration_duration_seconds` | `gitlab_ci_builds_queuing_metrics` | +| `gitlab_ci_current_queue_size` | `gitlab_ci_builds_queuing_metrics` | +| `gitlab_ci_queue_retrieval_duration_seconds` | `gitlab_ci_builds_queuing_metrics` | +| `gitlab_ci_queue_active_runners_total` | `gitlab_ci_builds_queuing_metrics` | ## Praefect metrics @@ -279,12 +296,16 @@ configuration option in `gitlab.yml`. These metrics are served from the | `geo_snippet_repositories_synced` | Gauge | 13.4 | Number of syncable snippets synced on secondary | `url` | | `geo_snippet_repositories_failed` | Gauge | 13.4 | Number of syncable snippets failed on secondary | `url` | | `geo_snippet_repositories_registry` | Gauge | 13.4 | Number of syncable snippets in the registry | `url` | -| `geo_group_wiki_repositories` | Gauge | 13.10 | Number of group wikis on primary | `url` | -| `geo_group_wiki_repositories_checksummed` | Gauge | 13.10 | Number of group wikis checksummed on primary | `url` | -| `geo_group_wiki_repositories_checksum_failed` | Gauge | 13.10 | Number of group wikis failed to calculate the checksum on primary | `url` | -| `geo_group_wiki_repositories_synced` | Gauge | 13.10 | Number of syncable group wikis synced on secondary | `url` | -| `geo_group_wiki_repositories_failed` | Gauge | 13.10 | Number of syncable group wikis failed on secondary | `url` | -| `geo_group_wiki_repositories_registry` | Gauge | 13.10 | Number of syncable group wikis in the registry | `url` | +| `geo_group_wiki_repositories` | Gauge | 13.10 | Number of group wikis on primary | `url` | +| `geo_group_wiki_repositories_checksum_total` | Gauge | 16.3 | Number of group wikis to checksum on primary | `url` | +| `geo_group_wiki_repositories_checksummed` | Gauge | 13.10 | Number of group wikis that successfully calculated the checksum on primary | `url` | +| `geo_group_wiki_repositories_checksum_failed` | Gauge | 13.10 | Number of group wikis that failed to calculate the checksum on primary | `url` | +| `geo_group_wiki_repositories_synced` | Gauge | 13.10 | Number of syncable group wikis synced on secondary | `url` | +| `geo_group_wiki_repositories_failed` | Gauge | 13.10 | Number of syncable group wikis failed to sync on secondary | `url` | +| `geo_group_wiki_repositories_registry` | Gauge | 13.10 | Number of group wikis in the registry | `url` | +| `geo_group_wiki_repositories_verification_total` | Gauge | 16.3 | Number of group wikis to attempt to verify on secondary | `url` | +| `geo_group_wiki_repositories_verified` | Gauge | 16.3 | Number of group wikis successfully verified on secondary | `url` | +| `geo_group_wiki_repositories_verification_failed` | Gauge | 16.3 | Number of group wikis that failed verification on secondary | `url` | | `geo_pages_deployments` | Gauge | 14.3 | Number of pages deployments on primary | `url` | | `geo_pages_deployments_checksum_total` | Gauge | 14.6 | Number of pages deployments to checksum on primary | `url` | | `geo_pages_deployments_checksummed` | Gauge | 14.6 | Number of pages deployments that successfully calculated the checksum on primary | `url` | diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index a9b393aab33..abdd2f1d0d3 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -13,7 +13,7 @@ GitLab provides out-of-the-box monitoring with Prometheus, providing access to h GitLab services. Prometheus and the various exporters listed in this page are bundled in Linux packages. Check each exporter's -documentation for the timeline they got added. For installations from source you must install them +documentation for the timeline they got added. For self-compiled installations, you must install them yourself. Over subsequent releases additional GitLab metrics are captured. Prometheus services are on by default. @@ -31,7 +31,7 @@ dashboard tool like [Grafana](https://grafana.com). ## Configuring Prometheus -For installations from source, you must install and configure it yourself. +For self-compiled installations, you must install and configure it yourself. Prometheus and its exporters are on by default. Prometheus runs as the `gitlab-prometheus` user and listen on diff --git a/doc/administration/monitoring/prometheus/node_exporter.md b/doc/administration/monitoring/prometheus/node_exporter.md index f4d5d9942ca..4de05034fff 100644 --- a/doc/administration/monitoring/prometheus/node_exporter.md +++ b/doc/administration/monitoring/prometheus/node_exporter.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The [node exporter](https://github.com/prometheus/node_exporter) enables you to measure various machine resources such as memory, disk and CPU utilization. -For installations from source you must install and configure it yourself. +For self-compiled installations, you must install and configure it yourself. To enable the node exporter: diff --git a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md index a95dc47dc34..6f925cb7fb6 100644 --- a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md +++ b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The [PgBouncer exporter](https://github.com/prometheus-community/pgbouncer_exporter) enables you to measure various [PgBouncer](https://www.pgbouncer.org/) metrics. -For installations from source you must install and configure it yourself. +For self-compiled installations, you must install and configure it yourself. To enable the PgBouncer exporter: diff --git a/doc/administration/monitoring/prometheus/postgres_exporter.md b/doc/administration/monitoring/prometheus/postgres_exporter.md index 39f6c81e8d0..20cfb078994 100644 --- a/doc/administration/monitoring/prometheus/postgres_exporter.md +++ b/doc/administration/monitoring/prometheus/postgres_exporter.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The [PostgreSQL Server Exporter](https://github.com/prometheus-community/postgres_exporter) allows you to export various PostgreSQL metrics. -For installations from source you must install and configure it yourself. +For self-compiled installations, you must install and configure it yourself. To enable the PostgreSQL Server Exporter: diff --git a/doc/administration/monitoring/prometheus/redis_exporter.md b/doc/administration/monitoring/prometheus/redis_exporter.md index 5f11034dc15..25c76fac743 100644 --- a/doc/administration/monitoring/prometheus/redis_exporter.md +++ b/doc/administration/monitoring/prometheus/redis_exporter.md @@ -10,7 +10,7 @@ The [Redis exporter](https://github.com/oliver006/redis_exporter) enables you to various [Redis](https://redis.io) metrics. For more information on what is exported, [read the upstream documentation](https://github.com/oliver006/redis_exporter/blob/master/README.md#whats-exported). -For installations from source you must install and configure it yourself. +For self-compiled installations, you must install and configure it yourself. To enable the Redis exporter: diff --git a/doc/administration/nfs.md b/doc/administration/nfs.md index 0273c4b03b1..119f757bfbc 100644 --- a/doc/administration/nfs.md +++ b/doc/administration/nfs.md @@ -60,10 +60,10 @@ options: a good security measure when NFS shares are accessed by many different users. However, in this case only GitLab uses the NFS share so it is safe. GitLab recommends the `no_root_squash` setting because we need to - manage file permissions automatically. Without the setting you may receive - errors when the Omnibus package tries to alter permissions. GitLab + manage file permissions automatically. Without the setting, you may receive + errors when the Linux package tries to alter permissions. GitLab and other bundled components do **not** run as `root` but as non-privileged - users. The recommendation for `no_root_squash` is to allow the Omnibus package + users. The recommendation for `no_root_squash` is to allow the Linux package to set ownership and permissions on files, as needed. In some cases where the `no_root_squash` option is not available, the `root` flag can achieve the same result. @@ -71,7 +71,7 @@ options: circumstances it could lead to data loss if a failure occurs before data has synced. -Due to the complexities of running Omnibus with LDAP and the complexities of +Due to the complexities of running the Linux package with LDAP and the complexities of maintaining ID mapping without LDAP, in most cases you should enable numeric UIDs and GIDs (which is off by default in some cases) for simplified permission management between systems: @@ -210,10 +210,10 @@ mountpoint └── uploads ``` -To do so, configure Omnibus with the paths to each directory nested +To do so, configure the Linux package with the paths to each directory nested in the mount point as follows: -Mount `/gitlab-nfs` then use the following Omnibus +Mount `/gitlab-nfs` then use the following Linux package configuration to move each data location to a subdirectory: ```ruby @@ -229,7 +229,7 @@ these new locations, and then restart GitLab. ### Bind mounts -Alternatively to changing the configuration in Omnibus, bind mounts can be used +Instead of changing the configuration in the Linux package, bind mounts can be used to store the data on an NFS mount. Bind mounts provide a way to specify just one NFS mount and then @@ -252,7 +252,7 @@ are empty before attempting a restore. Read more about the ### Multiple NFS mounts -When using default Omnibus configuration you need to share 4 data locations +When using default Linux package configuration, you need to share 4 data locations between all GitLab cluster nodes. No other locations should be shared. The following are the 4 locations need to be shared: @@ -265,8 +265,8 @@ following are the 4 locations need to be shared: Other GitLab directories should not be shared between nodes. They contain node-specific files and GitLab code that does not need to be shared. To ship -logs to a central location consider using remote syslog. Omnibus GitLab packages -provide configuration for [UDP log shipping](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only). +logs to a central location consider using remote syslog. The Linux package +provides configuration for [UDP log shipping](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only). Having multiple NFS mounts requires you to manually make sure the data directories are empty before attempting a restore. Read more about the diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md index 2bf3ef0275c..aa17452f260 100644 --- a/doc/administration/object_storage.md +++ b/doc/administration/object_storage.md @@ -114,7 +114,6 @@ The following table lists the valid `objects` that can be used: | `dependency_proxy` | [Dependency Proxy](packages/dependency_proxy.md) | | `terraform_state` | [Terraform state files](terraform_state.md) | | `pages` | [Pages](pages/index.md) | -| `ci_secure_files` | [Project-level Secure Files](secure_files.md) | Within each object type, three parameters can be defined: diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index 8382f3aa8b5..270bd778ea3 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -25,7 +25,7 @@ GitLab Shell solves this by providing a way to authorize SSH users via a fast, indexed lookup in the GitLab database. This page describes how to enable the fast lookup of authorized SSH keys. -## Fast lookup is required for Geo **(PREMIUM)** +## Fast lookup is required for Geo **(PREMIUM ALL)** Unlike [Cloud Native GitLab](https://docs.gitlab.com/charts/), by default Linux package installations manage an `authorized_keys` file that is located in the @@ -105,7 +105,7 @@ means that GitLab was able to find the key in the database, as it is not present in the file. NOTE: -For Installations from source, the command would be located at +For self-compiled installations, the command would be located at `/home/git/gitlab-shell/bin/gitlab-shell-authorized-keys-check` if [the install from source](../../install/installation.md#install-gitlab-shell) instructions were followed. You might want to consider creating a wrapper script somewhere else, as this command must be owned by `root` and not be writable by group or others. You could also consider changing the ownership of this command diff --git a/doc/administration/operations/gitlab_sshd.md b/doc/administration/operations/gitlab_sshd.md index 2707c8f08a0..43ca6251a0e 100644 --- a/doc/administration/operations/gitlab_sshd.md +++ b/doc/administration/operations/gitlab_sshd.md @@ -112,7 +112,7 @@ To enable the PROXY protocol: ```ruby gitlab_sshd['proxy_protocol'] = true - # # Proxy protocol policy ("use", "require", "reject", "ignore"), "use" is the default value + # Proxy protocol policy ("use", "require", "reject", "ignore"), "use" is the default value gitlab_sshd['proxy_policy'] = "use" ``` diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md index f471dcd44b0..f16f1ac46ae 100644 --- a/doc/administration/operations/puma.md +++ b/doc/administration/operations/puma.md @@ -395,7 +395,7 @@ gitlab_rails['env'] = { } ``` -For source installations, set the environment variable. +For self-compiled installations, set the environment variable. Refer to [Puma Worker timeout](../operations/puma.md#change-the-worker-timeout). [Reconfigure](../restart_gitlab.md#reconfigure-a-linux-package-installation) GitLab for the changes to take effect. diff --git a/doc/administration/operations/rails_console.md b/doc/administration/operations/rails_console.md index ac0a7e5870b..b3e7a97428a 100644 --- a/doc/administration/operations/rails_console.md +++ b/doc/administration/operations/rails_console.md @@ -508,7 +508,7 @@ def disable_two_factor! otp_grace_period_started_at: nil, otp_backup_codes: nil ) - self.u2f_registrations.destroy_all # rubocop: disable DestroyAll + self.webauthn_registrations.destroy_all # rubocop: disable DestroyAll end end diff --git a/doc/administration/package_information/postgresql_versions.md b/doc/administration/package_information/postgresql_versions.md index 101e1549d19..3a499be43b3 100644 --- a/doc/administration/package_information/postgresql_versions.md +++ b/doc/administration/package_information/postgresql_versions.md @@ -31,6 +31,7 @@ Read more about update policies and warnings in the PostgreSQL | GitLab version | PostgreSQL versions | Default version for fresh installs | Default version for upgrades | Notes | | -------------- | ------------------- | ---------------------------------- | ---------------------------- | ----- | +| 16.2.0 | 13.11, 14.8 | 13.11 | 13.11 | For upgrades, users can manually upgrade to 14.8 following the [upgrade documentation](https://docs.gitlab.com/omnibus/settings/database.html#gitlab-162-and-later). | | 16.0.2 | 13.11 | 13.11 | 13.11 | | | 16.0.0 | 13.8 | 13.8 | 13.8 | | | 15.11.7 | 13.11 | 13.11 | 12.12 | | diff --git a/doc/administration/package_information/supported_os.md b/doc/administration/package_information/supported_os.md index 16f4c2cdeab..eea4b8035b7 100644 --- a/doc/administration/package_information/supported_os.md +++ b/doc/administration/package_information/supported_os.md @@ -22,7 +22,8 @@ architecture. | OS Version | First supported GitLab version | Arch | Install Documentation | OS EOL | Details | | ------------------------------------------------------------ | ------------------------------ | --------------- | :----------------------------------------------------------: | ---------- | ------------------------------------------------------------ | -| AlmaLinux 8 | GitLab CE / GitLab EE 14.5.0 | x86_64, aarch64 | [AlmaLinux Install Documentation](https://about.gitlab.com/install/#almalinux-8) | 2029 | <https://almalinux.org/> | +| AlmaLinux 8 | GitLab CE / GitLab EE 14.5.0 | x86_64, aarch64 | [AlmaLinux Install Documentation](https://about.gitlab.com/install/#almalinux) | 2029 | <https://almalinux.org/> | +| AlmaLinux 9 | GitLab CE / GitLab EE 16.0.0 | x86_64, aarch64 | [AlmaLinux Install Documentation](https://about.gitlab.com/install/#almalinux) | 2032 | <https://almalinux.org/> | | CentOS 7 | GitLab CE / GitLab EE 7.10.0 | x86_64 | [CentOS Install Documentation](https://about.gitlab.com/install/#centos-7) | June 2024 | <https://wiki.centos.org/About/Product> | | Debian 10 | GitLab CE / GitLab EE 12.2.0 | amd64, arm64 | [Debian Install Documentation](https://about.gitlab.com/install/#debian) | 2024 | <https://wiki.debian.org/LTS> | | Debian 11 | GitLab CE / GitLab EE 14.6.0 | amd64, arm64 | [Debian Install Documentation](https://about.gitlab.com/install/#debian) | 2026 | <https://wiki.debian.org/LTS> | diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index 007072647a2..384df9a6e6a 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -75,7 +75,7 @@ Where: | `issuer` | This should be the same value as configured in Registry's `issuer`. Read the [token auth configuration documentation](https://docs.docker.com/registry/configuration/#token). | A Registry init file is not shipped with GitLab if you install it from source. -Hence, [restarting GitLab](../restart_gitlab.md#installations-from-source) does not restart the Registry should +Hence, [restarting GitLab](../restart_gitlab.md#self-compiled-installations) does not restart the Registry should you modify its settings. Read the upstream documentation on how to achieve that. At the **absolute** minimum, make sure your [Registry configuration](https://docs.docker.com/registry/configuration/#auth) @@ -187,7 +187,7 @@ registry_nginx['listen_port'] = 5678 port: 5050 ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. 1. Make the relevant changes in NGINX as well (domain, port, TLS certificates path). ::EndTabs @@ -256,7 +256,7 @@ registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key" host: registry.gitlab.example.com ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. 1. Make the relevant changes in NGINX as well (domain, port, TLS certificates path). ::EndTabs @@ -296,7 +296,7 @@ Registry application itself. enabled: false ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ::EndTabs @@ -334,7 +334,7 @@ the Container Registry by themselves, follow the steps below. container_registry: false ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ::EndTabs @@ -427,7 +427,7 @@ The default location where images are stored in self-compiled installations is path: shared/registry ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ::EndTabs @@ -443,7 +443,9 @@ GitLab does not back up Docker images that are not stored on the file system. Enable backups with your object storage provider if desired. -#### Linux package installations +#### Configure `s3` and `gcs` storage drivers for Linux package installations + +The following configuration steps are for the `s3` and `gcs` storage drivers. Other [storage drivers](#configure-storage-for-the-container-registry) are supported. To configure the `s3` storage driver for a Linux package installation: @@ -515,6 +517,25 @@ To configure the `s3` storage driver for a Linux package installation: 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. +To configure the `gcs` storage driver for a Linux package installation: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + registry['storage'] = { + 'gcs' => { + 'bucket' => 'BUCKET_NAME', + 'keyfile' => 'PATH/TO/KEYFILE', + # If you have the bucket shared with other apps beyond the registry, uncomment the following: + # 'rootdirectory' => '/gcs/object/name/prefix' + } + } + ``` + + GitLab supports all [available parameters](https://docs.docker.com/registry/storage-drivers/gcs/). + +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. + #### Self-compiled installations Configuring the storage driver is done in the registry configuration YAML file created @@ -705,7 +726,7 @@ However, this behavior is undesirable for registries used by internal hosts that enabled: true ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ::EndTabs @@ -756,7 +777,7 @@ on how you installed GitLab. Follow the instructions here that match your instal encrypt: true ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ::EndTabs @@ -911,7 +932,7 @@ You can use GitLab as an auth endpoint with an external container registry. [Read more](#enable-the-container-registry) about what these parameters mean. -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ## Configure Container Registry notifications @@ -1486,7 +1507,7 @@ Start with a value between `25000000` (25 MB) and `50000000` (50 MB). chunksize: 25000000 ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ::EndTabs @@ -1572,7 +1593,7 @@ and a simple solution would be to enable relative URLs in the Registry. relativeurls: true ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ::EndTabs @@ -1618,7 +1639,7 @@ this error appears: - `Error response from daemon: manifest invalid: Schema 1 manifest not supported` -For Self-Managed GitLab instances, you can regain access to these images by temporarily downgrading +For self-managed GitLab instances, you can regain access to these images by temporarily downgrading the GitLab Container Registry to a version lower than `v3.0.0-gitlab`. Follow these steps to regain access to these images: @@ -1671,7 +1692,7 @@ For Linux package installations: :::TabTitle Self-compiled (source) -For source installations, locate your `registry` binary and temporarily replace it with the one +Locate your `registry` binary and temporarily replace it with the one obtained from `v3.0.0-gitlab`, as explained for Linux package installations. Make sure to start by backing up the original registry binary, and restore it after performing the [images upgrade](#images-upgrade) steps. diff --git a/doc/administration/packages/dependency_proxy.md b/doc/administration/packages/dependency_proxy.md index ee352a82058..f84703b63e7 100644 --- a/doc/administration/packages/dependency_proxy.md +++ b/doc/administration/packages/dependency_proxy.md @@ -67,7 +67,7 @@ For more information, see [Configure Charts using Globals](https://docs.gitlab.c enabled: false ``` -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ::EndTabs @@ -115,7 +115,7 @@ installations under `shared/dependency_proxy/` (relative to the Git home directo storage_path: shared/dependency_proxy ``` -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ::EndTabs @@ -193,7 +193,7 @@ This section describes the earlier configuration format. [Migration steps still # path_style: false # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'. ``` -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ::EndTabs @@ -211,7 +211,7 @@ to remote storage. The processing is done in a background worker and requires no sudo gitlab-rake "gitlab:dependency_proxy:migrate" ``` -- For installations from source: +- For self-compiled installations: ```shell RAILS_ENV=production sudo -u git -H bundle exec rake gitlab:dependency_proxy:migrate diff --git a/doc/administration/packages/index.md b/doc/administration/packages/index.md index 77730384623..2eb3da4b5d7 100644 --- a/doc/administration/packages/index.md +++ b/doc/administration/packages/index.md @@ -196,6 +196,13 @@ To change the local storage path: ::EndTabs +If you already had packages stored in the old storage path, move everything +from the old to the new location to ensure existing packages stay accessible: + +```shell +mv /var/opt/gitlab/gitlab-rails/shared/packages/* /mnt/packages/ +``` + Docker and Kubernetes do not use local storage. - For the Helm chart (Kubernetes): Use object storage instead. diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 726307229d6..c84e5eb8c8c 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -350,7 +350,7 @@ world. Custom domains are supported, but no TLS. **Requirements:** - [Wildcard DNS setup](#dns-configuration) -- Wildcard TLS certificate +- TLS certificate. Can be either Wildcard, or any other type meeting the [requirements](../../user/project/pages/custom_domains_ssl_tls_certification/index.md#manual-addition-of-ssltls-certificates). - Secondary IP --- @@ -527,11 +527,11 @@ fails to work if the custom CA is not recognized. This usually results in this error: `Post /oauth/token: x509: certificate signed by unknown authority`. -For installation from source, this can be fixed by installing the custom Certificate -Authority (CA) in the system certificate store. - For Linux package installations, this is fixed by [installing a custom CA](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). +For self-compiled installations, this can be fixed by installing the custom Certificate +Authority (CA) in the system certificate store. + ### ZIP serving and cache configuration > [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/392) in GitLab 13.7. @@ -968,7 +968,7 @@ See [the available connection settings for different providers](../object_storag region: eu-central-1 ``` -1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. 1. [Migrate existing Pages deployments to object storage.](#migrate-pages-deployments-to-object-storage) diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 26dedd47473..97dacfc1902 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -183,8 +183,8 @@ The Pages daemon doesn't listen to the outside world. sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf ``` -1. Restart NGINX -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) +1. Restart NGINX. +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations). ### Wildcard domains with TLS support @@ -240,8 +240,8 @@ outside world. sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf ``` -1. Restart NGINX -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) +1. Restart NGINX. +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations). ## Advanced configuration @@ -310,8 +310,8 @@ world. Custom domains are supported, but no TLS. 1. Edit all GitLab related configurations in `/etc/nginx/site-available/` and replace `0.0.0.0` with `192.0.2.1`, where `192.0.2.1` the primary IP where GitLab listens to. -1. Restart NGINX -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) +1. Restart NGINX. +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations). ### Custom domains with TLS support @@ -378,13 +378,13 @@ world. Custom domains and TLS are supported. 1. Edit all GitLab related configurations in `/etc/nginx/site-available/` and replace `0.0.0.0` with `192.0.2.1`, where `192.0.2.1` the primary IP where GitLab listens to. -1. Restart NGINX -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) +1. Restart NGINX. +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations). ## NGINX caveats NOTE: -The following information applies only for installations from source. +The following information applies only to self-compiled installations. Be extra careful when setting up the domain name in the NGINX configuration. You must not remove the backslashes. @@ -438,7 +438,7 @@ Pages access control is disabled by default. To enable it: access_control: true ``` -1. [Restart GitLab](../restart_gitlab.md#installations-from-source). +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations). 1. Create a new [system OAuth application](../../integration/oauth_provider.md#create-a-user-owned-application). This should be called `GitLab Pages` and have a `Redirect URL` of `https://projects.example.io/auth`. It does not need to be a "trusted" @@ -471,7 +471,7 @@ are stored. path: /mnt/storage/pages ``` -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations). ## Set maximum Pages size diff --git a/doc/administration/pages/troubleshooting.md b/doc/administration/pages/troubleshooting.md index 7e184631515..a103c793763 100644 --- a/doc/administration/pages/troubleshooting.md +++ b/doc/administration/pages/troubleshooting.md @@ -212,8 +212,13 @@ Once added, reconfigure with `sudo gitlab-ctl reconfigure` and restart GitLab wi You may see this error if `pages_external_url` was updated at some point of time. Verify the following: -1. The **Callback URL**/Redirect URI in the GitLab Pages [System OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application) -is using the protocol (HTTP or HTTPS) that `pages_external_url` is configured to use. +1. Check the [System OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application): + + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. Select **Applications** and then **Add new application**. + 1. Ensure the **Callback URL/Redirect URI** is using the protocol (HTTP or HTTPS) that + `pages_external_url` is configured to use. 1. The domain and path components of `Redirect URI` are valid: they should look like `projects.<pages_external_url>/auth`. ## 500 error `cannot serve from disk` diff --git a/doc/administration/postgresql/external.md b/doc/administration/postgresql/external.md index 9c44d53213b..a9f857d8f00 100644 --- a/doc/administration/postgresql/external.md +++ b/doc/administration/postgresql/external.md @@ -17,7 +17,9 @@ If you use a cloud-managed service, or provide your own PostgreSQL instance: 1. Set up PostgreSQL according to the [database requirements document](../../install/requirements.md#database). -1. Set up a `gitlab` user with a password of your choice, create the `gitlabhq_production` database, and make the user an owner of the database. You can see an example of this setup in the [installation from source documentation](../../install/installation.md#7-database). +1. Set up a `gitlab` user with a password of your choice, create the `gitlabhq_production` database, and make the user an + owner of the database. You can see an example of this setup in the + [self-compiled installation documentation](../../install/installation.md#7-database). 1. If you are using a cloud-managed service, you may need to grant additional roles to your `gitlab` user: - Amazon RDS requires the [`rds_superuser`](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.html#Appendix.PostgreSQL.CommonDBATasks.Roles) role. diff --git a/doc/administration/postgresql/multiple_databases.md b/doc/administration/postgresql/multiple_databases.md index 5dcb080d707..9e5e34d930c 100644 --- a/doc/administration/postgresql/multiple_databases.md +++ b/doc/administration/postgresql/multiple_databases.md @@ -41,7 +41,7 @@ databases. Some examples: To migrate existing data from the `main` database to the `ci` database, you can copy the database across. -### Existing source installation +### Existing self-compiled installation 1. Stop GitLab, except for PostgreSQL: @@ -98,7 +98,7 @@ You must stop GitLab before setting up multiple databases. This prevents split-brain situations, where `main` data is written to the `ci` database, and the other way around. -### Installations from source +### Self-compiled installations 1. For existing installations, [migrate the data](#migrate-existing-installations) first. diff --git a/doc/administration/postgresql/replication_and_failover.md b/doc/administration/postgresql/replication_and_failover.md index 05ff6fa8a4a..c547e5c3638 100644 --- a/doc/administration/postgresql/replication_and_failover.md +++ b/doc/administration/postgresql/replication_and_failover.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # PostgreSQL replication and failover for Linux package installations **(PREMIUM SELF)** If you're a Free user of GitLab self-managed, consider using a cloud-hosted solution. -This document doesn't cover installations from source. +This document doesn't cover self-compiled installations. If a setup with replication and failover isn't what you were looking for, see the [database configuration document](https://docs.gitlab.com/omnibus/settings/database.html) diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index c2c6429ba8b..87cce30723e 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.md @@ -33,24 +33,23 @@ System: Ubuntu 20.04 Proxy: no Current User: git Using RVM: no -Ruby Version: 2.6.6p146 -Gem Version: 2.7.10 -Bundler Version:1.17.3 -Rake Version: 12.3.3 -Redis Version: 5.0.9 -Git Version: 2.27.0 -Sidekiq Version:5.2.9 +Ruby Version: 2.7.6p219 +Gem Version: 3.1.6 +Bundler Version:2.3.15 +Rake Version: 13.0.6 +Redis Version: 6.2.7 +Sidekiq Version:6.4.2 Go Version: unknown GitLab information -Version: 13.2.2-ee -Revision: 618883a1f9d +Version: 15.5.5-ee +Revision: 5f5109f142d Directory: /opt/gitlab/embedded/service/gitlab-rails DB Adapter: PostgreSQL -DB Version: 11.7 -URL: http://gitlab.example.com -HTTP Clone URL: http://gitlab.example.com/some-group/some-project.git -SSH Clone URL: git@gitlab.example.com:some-group/some-project.git +DB Version: 13.8 +URL: https://app.gitaly.gcp.gitlabsandbox.net +HTTP Clone URL: https://app.gitaly.gcp.gitlabsandbox.net/some-group/some-project.git +SSH Clone URL: git@app.gitaly.gcp.gitlabsandbox.net:some-group/some-project.git Elasticsearch: no Geo: no Using LDAP: no @@ -58,10 +57,20 @@ Using Omniauth: yes Omniauth Providers: GitLab Shell -Version: 13.3.0 +Version: 14.12.0 Repository storage paths: -- default: /var/opt/gitlab/git-data/repositories -GitLab Shell path: /opt/gitlab/embedded/service/gitlab-shell +- default: /var/opt/gitlab/git-data/repositories +- gitaly: /var/opt/gitlab/git-data/repositories +GitLab Shell path: /opt/gitlab/embedded/service/gitlab-shell + + +Gitaly +- default Address: unix:/var/opt/gitlab/gitaly/gitaly.socket +- default Version: 15.5.5 +- default Git Version: 2.37.1.gl1 +- gitaly Address: tcp://10.128.20.6:2305 +- gitaly Version: 15.5.5 +- gitaly Git Version: 2.37.1.gl1 ``` ## Show GitLab license information **(PREMIUM SELF)** @@ -234,7 +243,7 @@ clear Redis' cache. To do this, run: Sometimes during version upgrades you might end up with some wrong CSS or missing some icons. In that case, try to precompile the assets again. -This Rake task only applies to source installations. [Read more](../../update/package/index.md#missing-asset-files) +This Rake task only applies to self-compiled installations. [Read more](../../update/package/index.md#missing-asset-files) about troubleshooting this problem when running the Linux package. The guidance for Linux package might be applicable for Kubernetes and Docker deployments of GitLab, though in general, container-based installations @@ -399,6 +408,26 @@ task cleans up the temporary indexes. - The time it takes for database index rebuilding to complete depends on the size of the target database. It can take between several hours and several days. +## Dump the database schema + +In rare circumstances, the database schema can differ from what the application code expects +even if all database migrations are complete. If this does occur, it can lead to odd errors +in GitLab. + +To dump the database schema: + +```shell +SCHEMA=/tmp/structure.sql gitlab-rake db:schema:dump +``` + +The Rake task creates a `/tmp/structure.sql` file that contains the database schema dump. + +To determine if there are any differences: + +1. Go to the [`db/structure.sql`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/db/structure.sql) file in the [`gitlab`](https://gitlab.com/gitlab-org/gitlab) project. + Select the branch that matches your GitLab version. For example, the file for GitLab 16.2: <https://gitlab.com/gitlab-org/gitlab/-/blob/16-2-stable-ee/db/structure.sql>. +1. Compare `/tmp/structure.sql` with the `db/structure.sql` file for your version. + ## Import common metrics Sometimes you may need to re-import the common metrics that power the Metrics dashboards. diff --git a/doc/administration/raketasks/service_desk_email.md b/doc/administration/raketasks/service_desk_email.md index 9bf0846fef2..8d8585bb171 100644 --- a/doc/administration/raketasks/service_desk_email.md +++ b/doc/administration/raketasks/service_desk_email.md @@ -12,7 +12,7 @@ The following are Service Desk email-related Rake tasks. ## Secrets -GitLab can use [Service Desk email](../../user/project/service_desk.md#configure-service-desk-alias-email) secrets read from an encrypted file instead of storing them in plaintext in the file system. The following Rake tasks are provided for updating the contents of the encrypted file. +GitLab can use [Service Desk email](../../user/project/service_desk/index.md#configure-service-desk-alias-email) secrets read from an encrypted file instead of storing them in plaintext in the file system. The following Rake tasks are provided for updating the contents of the encrypted file. ### Show secret diff --git a/doc/administration/redis/index.md b/doc/administration/redis/index.md index 31ea879b289..ad5aca37830 100644 --- a/doc/administration/redis/index.md +++ b/doc/administration/redis/index.md @@ -11,32 +11,31 @@ Based on your infrastructure setup and how you have installed GitLab, there are multiple ways to configure Redis. You can choose to install and manage Redis and Sentinel yourself, use a hosted -cloud solution, or you can use the ones that come bundled with the Omnibus GitLab +cloud solution, or you can use the ones that come bundled with the Linux packages so you can only focus on configuration. Pick the one that suits your needs. -## Redis replication and failover using Omnibus GitLab +## Redis replication and failover using the Linux package This setup is for when you have installed GitLab using the -[Omnibus GitLab **Enterprise Edition** (EE) package](https://about.gitlab.com/install/?version=ee). +[Linux **Enterprise Edition** (EE) package](https://about.gitlab.com/install/?version=ee). -Both Redis and Sentinel are bundled in the package, so you can it to set up the whole -Redis infrastructure (primary, replica and sentinel). +Both Redis and Sentinel are bundled in the package, so you can use it to set up the whole Redis infrastructure (primary, +replica and sentinel). -[> Read how to set up Redis replication and failover using Omnibus GitLab](replication_and_failover.md) +For more information, see [Redis replication and failover with the Linux package](replication_and_failover.md). ## Redis replication and failover using the non-bundled Redis -This setup is for when you have installed GitLab using the -[Omnibus GitLab packages](https://about.gitlab.com/install/) (CE or EE), -or installed it [from source](../../install/installation.md), but you want to use -your own external Redis and sentinel servers. +This setup is for when you have either a [Linux package](https://about.gitlab.com/install/) installation or a +[self-compiled installation](../../install/installation.md), but you want to use your own external Redis and Sentinel +servers. -[> Read how to set up Redis replication and failover using the non-bundled Redis](replication_and_failover_external.md) +For more information, see [Redis replication and failover providing your own instance](replication_and_failover_external.md). -## Standalone Redis using Omnibus GitLab +## Standalone Redis using the Linux package This setup is for when you have installed the -[Omnibus GitLab **Community Edition** (CE) package](https://about.gitlab.com/install/?version=ce) +[Linux **Community Edition** (CE) package](https://about.gitlab.com/install/?version=ce) to use the bundled Redis, so you can use the package with only the Redis service enabled. -[> Read how to set up a standalone Redis instance using Omnibus GitLab](standalone.md) +For more information, see [Standalone Redis using the Linux package](standalone.md). diff --git a/doc/administration/redis/replication_and_failover.md b/doc/administration/redis/replication_and_failover.md index 1db5b82e7dc..82b9a33d2c6 100644 --- a/doc/administration/redis/replication_and_failover.md +++ b/doc/administration/redis/replication_and_failover.md @@ -5,13 +5,11 @@ group: Distribution 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 --- -# Redis replication and failover with Omnibus GitLab **(PREMIUM SELF)** +# Redis replication and failover with the Linux package **(PREMIUM SELF)** -NOTE: -This is the documentation for the Omnibus GitLab packages. For using your own -non-bundled Redis, follow the [relevant documentation](replication_and_failover_external.md). +This documentation is for the Linux package. To use your own +non-bundled Redis, see [Redis replication and failover providing your own instance](replication_and_failover_external.md). -NOTE: In Redis lingo, `primary` is called `master`. In this document, `primary` is used instead of `master`, except the settings where `master` is required. @@ -73,7 +71,7 @@ whole cluster down, invalidating the failover effort. ## Recommended setup -For a minimal setup, you need to install the Omnibus GitLab package in `3` +For a minimal setup, you need to install the Linux package in `3` **independent** machines, both with **Redis** and **Sentinel**: - Redis Primary + Sentinel @@ -85,7 +83,7 @@ from, read [Redis setup overview](#redis-setup-overview) and [Sentinel setup overview](#sentinel-setup-overview). For a recommended setup that can resist more failures, you need to install -the Omnibus GitLab package in `5` **independent** machines, both with +the Linux package in `5` **independent** machines, both with **Redis** and **Sentinel**: - Redis Primary + Sentinel @@ -241,9 +239,9 @@ If you fail to replicate first, you may loose data (unprocessed background jobs) ### Step 1. Configuring the primary Redis instance 1. SSH into the **Primary** Redis server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package you want using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version + - Make sure you select the correct Linux package, with the same version and type (Community, Enterprise editions) of your current install. - Do not complete any other steps on the download page. @@ -285,9 +283,9 @@ Read more about [roles](https://docs.gitlab.com/omnibus/roles/). ### Step 2. Configuring the replica Redis instances 1. SSH into the **replica** Redis server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package you want using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version + - Make sure you select the correct Linux package, with the same version and type (Community, Enterprise editions) of your current install. - Do not complete any other steps on the download page. @@ -361,19 +359,17 @@ You must have at least `3` Redis Sentinel servers, and they need to be each in an independent machine. You can configure them in the same machines where you've configured the other Redis servers. -With GitLab Enterprise Edition, you can use the Omnibus package to set up +With GitLab Enterprise Edition, you can use the Linux package to set up multiple machines with the Sentinel daemon. ---- - 1. SSH into the server that hosts Redis Sentinel. 1. **You can omit this step if the Sentinels is hosted in the same node as the other Redis instances.** - [Download/install](https://about.gitlab.com/install/) the - Omnibus GitLab Enterprise Edition package using **steps 1 and 2** from the + [Download and install](https://about.gitlab.com/install/) the + Linux Enterprise Edition package using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version + - Make sure you select the correct Linux package, with the same version the GitLab application is running. - Do not complete any other steps on the download page. @@ -644,12 +640,11 @@ gitlab_rails['redis_sentinels'] = [ ## Advanced configuration -Omnibus GitLab configures some things behind the curtains to make the sysadmins' -lives easier. If you want to know what happens underneath keep reading. +This section covers configuration options that go beyond the recommended and minimal configurations. ### Running multiple Redis clusters -Omnibus GitLab supports running separate Redis and Sentinel instances for different +The Linux package supports running separate Redis and Sentinel instances for different persistence classes. | Class | Purpose | diff --git a/doc/administration/redis/replication_and_failover_external.md b/doc/administration/redis/replication_and_failover_external.md index 14378b478da..54d13991f3f 100644 --- a/doc/administration/redis/replication_and_failover_external.md +++ b/doc/administration/redis/replication_and_failover_external.md @@ -11,7 +11,7 @@ If you're hosting GitLab on a cloud provider, you can optionally use a managed service for Redis. For example, AWS offers ElastiCache that runs Redis. Alternatively, you may opt to manage your own Redis instance separate from the -Omnibus GitLab package. +Linux package. ## Requirements @@ -52,7 +52,7 @@ Note the Redis node's IP address or hostname, port, and password (if required). This is the documentation for configuring a scalable Redis setup when you have installed Redis all by yourself and not using the bundled one that -comes with the Omnibus packages, although using the Omnibus GitLab packages is +comes with the Linux packages, although using the Linux packages is highly recommend as we optimize them specifically for GitLab, and we take care of upgrading Redis to the latest supported version. @@ -63,7 +63,7 @@ settings outlined in We cannot stress enough the importance of reading the [replication and failover](replication_and_failover.md) documentation of the -Omnibus Redis HA as it provides some invaluable information to the configuration +Linux package Redis HA because it provides some invaluable information to the configuration of Redis. Read it before going forward with this guide. Before proceeding on setting up the new Redis instances, here are some @@ -79,9 +79,8 @@ requirements: - If you are using Redis with Sentinel, you also need to define the same password for the replica password definition (`masterauth`) in the same instance. -In addition, read the prerequisites as described in the -[Omnibus Redis document](replication_and_failover.md#requirements) since they provide some -valuable information for the general setup. +In addition, read the prerequisites as described in +[Redis replication and failover with the Linux package](replication_and_failover.md#requirements). ### Step 1. Configuring the primary Redis instance @@ -237,7 +236,7 @@ which ideally should not have Redis or Sentinels in the same machine: port: 26379 # point to sentinel, not to redis port ``` -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ## Example of minimal configuration with 1 primary, 2 replicas and 3 sentinels @@ -362,7 +361,7 @@ or a failover promotes a different **Primary** node. port: 26379 # point to sentinel, not to redis port ``` -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. ## Troubleshooting diff --git a/doc/administration/redis/standalone.md b/doc/administration/redis/standalone.md index 703601cda42..b9d00b92f95 100644 --- a/doc/administration/redis/standalone.md +++ b/doc/administration/redis/standalone.md @@ -5,9 +5,9 @@ group: Distribution 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 --- -# Standalone Redis using Omnibus GitLab **(FREE SELF)** +# Standalone Redis using the Linux package **(FREE SELF)** -The Omnibus GitLab package can be used to configure a standalone Redis server. +The Linux package can be used to configure a standalone Redis server. In this configuration, Redis is not scaled, and represents a single point of failure. However, in a scaled environment the objective is to allow the environment to handle more users or to increase throughput. Redis itself @@ -18,10 +18,10 @@ page for an overview of GitLab scaling options. ## Set up the standalone Redis instance The steps below are the minimum necessary to configure a Redis server with -Omnibus GitLab: +the Linux package: 1. SSH into the Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package you want by using **steps 1 and 2** from the GitLab downloads page. Do not complete any other steps on the download page. diff --git a/doc/administration/redis/troubleshooting.md b/doc/administration/redis/troubleshooting.md index 947db2c1d4e..5f0be709d78 100644 --- a/doc/administration/redis/troubleshooting.md +++ b/doc/administration/redis/troubleshooting.md @@ -88,11 +88,9 @@ You must make sure you are defining the same value in `redis['master_name']` and `redis['master_password']` as you defined for your sentinel node. The way the Redis connector `redis-rb` works with sentinel is a bit -non-intuitive. We try to hide the complexity in omnibus, but it still requires +non-intuitive. We try to hide the complexity in the Linux package, but it still requires a few extra configurations. ---- - To make sure your configuration is correct: 1. SSH into your GitLab application server @@ -135,7 +133,7 @@ To make sure your configuration is correct: You should see a different port after a few seconds delay (the failover/reconnect time). -## Troubleshooting a non-bundled Redis with an installation from source +## Troubleshooting a non-bundled Redis with a self-compiled installation If you get an error in GitLab like `Redis::CannotConnectError: No sentinels available.`, there may be something wrong with your configuration files or it can be related diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index e9a77d15a6c..c94c76c6532 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -427,9 +427,9 @@ The following IPs will be used as an example: To configure Consul: 1. SSH in to the server that will host Consul. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab - package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version +1. [Download and install](https://about.gitlab.com/install/) the Linux + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -453,8 +453,8 @@ To configure Consul: gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -504,19 +504,19 @@ A reputable provider or solution should be used for this. [Google Cloud SQL](htt If you use a third party external service: -1. Note that the HA Omnibus PostgreSQL setup encompasses PostgreSQL, PgBouncer and Consul. All of these components would no longer be required when using a third party external service. +1. Note that the HA Linux package PostgreSQL setup encompasses PostgreSQL, PgBouncer and Consul. These components would no longer be required when using a third party external service. 1. Set up PostgreSQL according to the [database requirements document](../../install/requirements.md#database). 1. Set up a `gitlab` username with a password of your choice. The `gitlab` user needs privileges to create the `gitlabhq_production` database. 1. Configure the GitLab application servers with the appropriate details. This step is covered in [Configuring the GitLab Rails application](#configure-gitlab-rails). -1. The number of nodes required to achieve HA may differ depending on the service compared to Omnibus and doesn't need to match accordingly. +1. The number of nodes required to achieve HA may differ depending on the service compared to the Linux package and doesn't need to match accordingly. 1. However, if [Database Load Balancing](../postgresql/database_load_balancing.md) via Read Replicas is desired for further improved performance it's recommended to follow the node count for the Reference Architecture. -### Standalone PostgreSQL using Omnibus GitLab +### Standalone PostgreSQL using the Linux package -The recommended Omnibus GitLab configuration for a PostgreSQL cluster with +The recommended Linux package configuration for a PostgreSQL cluster with replication and failover requires: - A minimum of three PostgreSQL nodes. @@ -596,9 +596,6 @@ in the second step, do not supply the `EXTERNAL_URL` value. # available database connections. patroni['postgresql']['max_wal_senders'] = 7 - # Incoming recommended value for max connections is 500. See https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5691. - patroni['postgresql']['max_connections'] = 500 - # Prevent database migrations from running on upgrade automatically gitlab_rails['auto_migrate'] = false @@ -653,8 +650,8 @@ PostgreSQL, with Patroni managing its failover, will default to use `pg_rewind` Like most failover handling methods, this has a small chance of leading to data loss. For more information, see the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -726,8 +723,6 @@ The following IPs will be used as an example: password: '<pgbouncer_password_hash>' } } - # Incoming recommended value for max db connections is 150. See https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5691. - pgbouncer['max_db_connections'] = 150 # Configure Consul agent consul['watchers'] = %w(postgresql) @@ -742,8 +737,8 @@ The following IPs will be used as an example: node_exporter['listen_address'] = '0.0.0.0:9100' ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -851,9 +846,9 @@ a node and change its status from primary to replica (and vice versa). #### Configure the primary Redis Cache node 1. SSH in to the **Primary** Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab - package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version +1. [Download and install](https://about.gitlab.com/install/) the Linux + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -916,17 +911,17 @@ a node and change its status from primary to replica (and vice versa). gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. #### Configure the replica Redis Cache nodes 1. SSH in to the **replica** Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab - package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version +1. [Download and install](https://about.gitlab.com/install/) the Linux + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add same contents as the primary node in the previous section replacing `redis_master_node` with `redis_replica_node`: @@ -989,8 +984,8 @@ a node and change its status from primary to replica (and vice versa). gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. 1. Go through the steps again for all the other replica nodes, and @@ -1016,9 +1011,9 @@ a node and change its status from primary to replica (and vice versa). #### Configure the primary Redis Persistent node 1. SSH in to the **Primary** Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab - package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version +1. [Download and install](https://about.gitlab.com/install/) the Linux + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -1071,17 +1066,17 @@ a node and change its status from primary to replica (and vice versa). gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. #### Configure the replica Redis Persistent nodes 1. SSH in to the **replica** Redis Persistent server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab - package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version +1. [Download and install](https://about.gitlab.com/install/) the Linux + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -1134,8 +1129,8 @@ a node and change its status from primary to replica (and vice versa). gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. 1. Go through the steps again for all the other replica nodes, and @@ -1191,7 +1186,7 @@ Praefect, the routing and transaction manager for Gitaly Cluster, requires its o If you want to have a highly available setup, Praefect requires a third-party PostgreSQL database. A built-in solution is being [worked on](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7292). -#### Praefect non-HA PostgreSQL standalone using Omnibus GitLab +#### Praefect non-HA PostgreSQL standalone using the Linux package The following IPs will be used as an example: @@ -1222,7 +1217,6 @@ in the second step, do not supply the `EXTERNAL_URL` value. # PostgreSQL configuration postgresql['listen_address'] = '0.0.0.0' - postgresql['max_connections'] = 500 # Prevent database migrations from running on upgrade automatically gitlab_rails['auto_migrate'] = false @@ -1253,8 +1247,8 @@ in the second step, do not supply the `EXTERNAL_URL` value. # END user configuration ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -1296,11 +1290,11 @@ After the Praefect PostgreSQL server has been set up, you'll then need to config We recommend the user be named `praefect` and the database `praefect_production`, and these can be configured as standard in PostgreSQL. The password for the user is the same as the one you configured earlier as `<praefect_postgresql_password>`. -This is how this would work with a Omnibus GitLab PostgreSQL setup: +This is how this would work with a Linux package PostgreSQL setup: 1. SSH in to the Praefect PostgreSQL node. 1. Connect to the PostgreSQL server with administrative access. - The `gitlab-psql` user should be used here for this as it's added by default in Omnibus. + The `gitlab-psql` user should be used here for this as it's added by default in the Linux package. The database `template1` is used because it is created by default on all PostgreSQL servers. ```shell @@ -1361,7 +1355,7 @@ The following IPs will be used as an example: To configure the Praefect nodes, on each one: 1. SSH in to the Praefect server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Edit the `/etc/gitlab/gitlab.rb` file to configure Praefect: @@ -1473,8 +1467,8 @@ Updates to example must be made at: # END user configuration ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. Praefect requires to run some database migrations, much like the main GitLab application. For this you should select **one Praefect node only to run the migrations**, AKA the _Deploy Node_. This node @@ -1534,7 +1528,7 @@ The following IPs will be used as an example: On each node: -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. 1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure @@ -1656,8 +1650,8 @@ Updates to example must be made at: } ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). @@ -1762,7 +1756,7 @@ examples include the Object storage configuration. To configure the Sidekiq nodes, on each one: 1. SSH in to the Sidekiq server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Create or edit `/etc/gitlab/gitlab.rb` and use the following configuration: @@ -1774,18 +1768,7 @@ Updates to example must be made at: --> ```ruby - # Avoid running unnecessary services on the Sidekiq server - gitaly['enable'] = false - postgresql['enable'] = false - redis['enable'] = false - nginx['enable'] = false - puma['enable'] = false - gitlab_workhorse['enable'] = false - prometheus['enable'] = false - alertmanager['enable'] = false - grafana['enable'] = false - gitlab_exporter['enable'] = false - gitlab_kas['enable'] = false + roles ["sidekiq_role"] # External URL ## This should match the URL of the external load balancer @@ -1881,8 +1864,8 @@ Updates to example must be made at: gitlab_rails['backup_upload_remote_directory'] = "<gcp-backups-state-bucket-name>" ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: @@ -1926,7 +1909,7 @@ The following IPs will be used as an example: On each node perform the following: -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. @@ -2042,11 +2025,11 @@ On each node perform the following: sudo cp cert.pem /etc/gitlab/trusted-certs/ ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. -1. Copy the SSH host keys (all in the name format `/etc/ssh/ssh_host_*_key*`) from the first Omnibus node you configured and +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. +1. Copy the SSH host keys (all in the name format `/etc/ssh/ssh_host_*_key*`) from the first Linux package node you configured and add or replace the files of the same name on this server. This ensures host mismatch errors aren't thrown - for your users as they hit the load balanced Rails nodes. If this is the first Omnibus node you are configuring, + for your users as they hit the load balanced Rails nodes. If this is the first Linux package node you are configuring, then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: @@ -2104,7 +2087,7 @@ the [HTTPS documentation](https://docs.gitlab.com/omnibus/settings/ssl/index.htm ## Configure Prometheus -The Omnibus GitLab package can be used to configure a standalone Monitoring node +The Linux package can be used to configure a standalone Monitoring node running [Prometheus](../monitoring/prometheus/index.md) and [Grafana](../monitoring/performance/grafana_configuration.md). @@ -2115,7 +2098,7 @@ The following IP will be used as an example: To configure the Monitoring node: 1. SSH in to the Monitoring node. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. @@ -2214,7 +2197,7 @@ in the future. ### Enable incremental logging -GitLab Runner returns job logs in chunks which Omnibus GitLab caches temporarily on disk in `/var/opt/gitlab/gitlab-ci/builds` by default, even when using consolidated object storage. With default configuration, this directory needs to be shared through NFS on any GitLab Rails and Sidekiq nodes. +GitLab Runner returns job logs in chunks which the Linux package caches temporarily on disk in `/var/opt/gitlab/gitlab-ci/builds` by default, even when using consolidated object storage. With default configuration, this directory needs to be shared through NFS on any GitLab Rails and Sidekiq nodes. While sharing the job logs through NFS is supported, it's recommended to avoid the need to use NFS by enabling [incremental logging](../job_logs.md#incremental-logging-architecture) (required when no NFS node has been deployed). Incremental logging uses Redis instead of disk space for temporary caching of job logs. @@ -2246,7 +2229,7 @@ Prometheus, and Grafana. Hybrid installations leverage the benefits of both cloud native and traditional compute deployments. With this, _stateless_ components can benefit from cloud native workload management benefits while _stateful_ components are deployed in compute VMs -with Omnibus to benefit from increased permanence. +with Linux package installations to benefit from increased permanence. Refer to the Helm charts [Advanced configuration](https://docs.gitlab.com/charts/advanced/) documentation for setup instructions including guidance on what GitLab secrets to sync @@ -2281,7 +2264,7 @@ the overall makeup as desired as long as the minimum CPU and Memory requirements - Nodes configuration is shown as it is forced to ensure pod vCPU / memory ratios and avoid scaling during **performance testing**. - In production deployments, there is no need to assign pods to specific nodes. A minimum of three nodes per node group in three different availability zones is strongly recommended to align with resilient cloud architecture practices. -Next are the backend components that run on static compute VMs via Omnibus (or External PaaS +Next are the backend components that run on static compute VMs using the Linux package (or External PaaS services where applicable): | Service | Nodes | Configuration | GCP | AWS | diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index adcf8eeb4c6..7f8603f294d 100644 --- a/doc/administration/reference_architectures/1k_users.md +++ b/doc/administration/reference_architectures/1k_users.md @@ -92,7 +92,7 @@ cluster alongside your instance, read how to Cloud Native Hybrid Reference Architecture is an alternative approach where select _stateless_ components are deployed in Kubernetes via our official [Helm Charts](https://docs.gitlab.com/charts/), -and _stateful_ components are deployed in compute VMs with Omnibus. +and _stateful_ components are deployed in compute VMs with the Linux package. The [2k GitLab Cloud Native Hybrid](2k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative) (non HA) and [3k GitLab Cloud Native Hybrid](3k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative) (HA) reference architectures are the smallest we recommend in Kubernetes. For environments that serve fewer users, you can lower the node specs. Depending on your user count, you can lower all suggested node specs as desired. However, it's recommended that you don't go lower than the [general requirements](../../install/requirements.md). diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index 0e608a953b8..2b91d493145 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -444,9 +444,9 @@ The following IPs will be used as an example: To configure Consul: 1. SSH in to the server that will host Consul. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -470,8 +470,8 @@ To configure Consul: gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -521,19 +521,19 @@ A reputable provider or solution should be used for this. [Google Cloud SQL](htt If you use a third party external service: -1. Note that the HA Omnibus PostgreSQL setup encompasses PostgreSQL, PgBouncer and Consul. All of these components would no longer be required when using a third party external service. +1. Note that the HA Linux package PostgreSQL setup encompasses PostgreSQL, PgBouncer and Consul. These components would no longer be required when using a third party external service. 1. Set up PostgreSQL according to the [database requirements document](../../install/requirements.md#database). 1. Set up a `gitlab` username with a password of your choice. The `gitlab` user needs privileges to create the `gitlabhq_production` database. 1. Configure the GitLab application servers with the appropriate details. This step is covered in [Configuring the GitLab Rails application](#configure-gitlab-rails). -1. The number of nodes required to achieve HA may differ depending on the service compared to Omnibus and doesn't need to match accordingly. +1. The number of nodes required to achieve HA may differ depending on the service compared to the Linux package and doesn't need to match accordingly. 1. However, if [Database Load Balancing](../postgresql/database_load_balancing.md) via Read Replicas is desired for further improved performance it's recommended to follow the node count for the Reference Architecture. -### Standalone PostgreSQL using Omnibus GitLab +### Standalone PostgreSQL using the Linux package -The recommended Omnibus GitLab configuration for a PostgreSQL cluster with +The recommended Linux package configuration for a PostgreSQL cluster with replication and failover requires: - A minimum of three PostgreSQL nodes. @@ -613,9 +613,6 @@ in the second step, do not supply the `EXTERNAL_URL` value. # available database connections. patroni['postgresql']['max_wal_senders'] = 7 - # Incoming recommended value for max connections is 500. See https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5691. - patroni['postgresql']['max_connections'] = 500 - # Prevent database migrations from running on upgrade automatically gitlab_rails['auto_migrate'] = false @@ -670,8 +667,8 @@ PostgreSQL, with Patroni managing its failover, will default to use `pg_rewind` Like most failover handling methods, this has a small chance of leading to data loss. For more information, see the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -743,8 +740,6 @@ The following IPs will be used as an example: password: '<pgbouncer_password_hash>' } } - # Incoming recommended value for max db connections is 150. See https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5691. - pgbouncer['max_db_connections'] = 150 # Configure Consul agent consul['watchers'] = %w(postgresql) @@ -759,8 +754,8 @@ The following IPs will be used as an example: node_exporter['listen_address'] = '0.0.0.0:9100' ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -868,9 +863,9 @@ a node and change its status from primary to replica (and vice versa). #### Configure the primary Redis Cache node 1. SSH in to the **Primary** Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab - package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version +1. [Download and install](https://about.gitlab.com/install/) the Linux + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -932,17 +927,17 @@ a node and change its status from primary to replica (and vice versa). gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. #### Configure the replica Redis Cache nodes 1. SSH in to the **replica** Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the same contents as the primary node in the previous section replacing `redis_master_node` with `redis_replica_node`: @@ -1004,8 +999,8 @@ a node and change its status from primary to replica (and vice versa). gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -1031,9 +1026,9 @@ a node and change its status from primary to replica (and vice versa). #### Configure the primary Redis Persistent node 1. SSH in to the **Primary** Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -1086,17 +1081,17 @@ a node and change its status from primary to replica (and vice versa). gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. #### Configure the replica Redis Persistent nodes 1. SSH in to the **replica** Redis Persistent server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -1152,8 +1147,8 @@ a node and change its status from primary to replica (and vice versa). gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -1210,7 +1205,7 @@ Praefect, the routing and transaction manager for Gitaly Cluster, requires its o If you want to have a highly available setup, Praefect requires a third-party PostgreSQL database. A built-in solution is being [worked on](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7292). -#### Praefect non-HA PostgreSQL standalone using Omnibus GitLab +#### Praefect non-HA PostgreSQL standalone using the Linux package The following IPs will be used as an example: @@ -1241,7 +1236,6 @@ in the second step, do not supply the `EXTERNAL_URL` value. # PostgreSQL configuration postgresql['listen_address'] = '0.0.0.0' - postgresql['max_connections'] = 500 # Prevent database migrations from running on upgrade automatically gitlab_rails['auto_migrate'] = false @@ -1272,8 +1266,8 @@ in the second step, do not supply the `EXTERNAL_URL` value. # END user configuration ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -1313,11 +1307,11 @@ After the Praefect PostgreSQL server has been set up, you'll then need to config We recommend the user be named `praefect` and the database `praefect_production`, and these can be configured as standard in PostgreSQL. The password for the user is the same as the one you configured earlier as `<praefect_postgresql_password>`. -This is how this would work with a Omnibus GitLab PostgreSQL setup: +This is how this would work with a Linux package PostgreSQL setup: 1. SSH in to the Praefect PostgreSQL node. 1. Connect to the PostgreSQL server with administrative access. - The `gitlab-psql` user should be used here for this as it's added by default in Omnibus. + The `gitlab-psql` user should be used here for this as it's added by default in the Linux package. The database `template1` is used because it is created by default on all PostgreSQL servers. ```shell @@ -1378,7 +1372,7 @@ The following IPs will be used as an example: To configure the Praefect nodes, on each one: 1. SSH in to the Praefect server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Edit the `/etc/gitlab/gitlab.rb` file to configure Praefect: @@ -1490,8 +1484,8 @@ Updates to example must be made at: # END user configuration ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace -the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace +the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. Praefect requires to run some database migrations, much like the main GitLab application. For this you should select **one Praefect node only to run the migrations**, AKA the _Deploy Node_. This node @@ -1551,7 +1545,7 @@ The following IPs will be used as an example: On each node: -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. 1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure @@ -1673,8 +1667,8 @@ Updates to example must be made at: } ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). @@ -1779,7 +1773,7 @@ examples include the Object storage configuration. To configure the Sidekiq nodes, on each one: 1. SSH in to the Sidekiq server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Create or edit `/etc/gitlab/gitlab.rb` and use the following configuration: @@ -1791,18 +1785,7 @@ Updates to example must be made at: --> ```ruby - # Avoid running unnecessary services on the Sidekiq server - gitaly['enable'] = false - postgresql['enable'] = false - redis['enable'] = false - nginx['enable'] = false - puma['enable'] = false - gitlab_workhorse['enable'] = false - prometheus['enable'] = false - alertmanager['enable'] = false - grafana['enable'] = false - gitlab_exporter['enable'] = false - gitlab_kas['enable'] = false + roles ["sidekiq_role"] # External URL ## This should match the URL of the external load balancer @@ -1898,8 +1881,8 @@ Updates to example must be made at: gitlab_rails['backup_upload_remote_directory'] = "<gcp-backups-state-bucket-name>" ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: @@ -1945,7 +1928,7 @@ The following IPs will be used as an example: On each node perform the following: -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. @@ -2061,11 +2044,11 @@ On each node perform the following: sudo cp cert.pem /etc/gitlab/trusted-certs/ ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. -1. Copy the SSH host keys (all in the name format `/etc/ssh/ssh_host_*_key*`) from the first Omnibus node you configured and +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. +1. Copy the SSH host keys (all in the name format `/etc/ssh/ssh_host_*_key*`) from the first Linux package node you configured and add or replace the files of the same name on this server. This ensures host mismatch errors aren't thrown - for your users as they hit the load balanced Rails nodes. If this is the first Omnibus node you are configuring, + for your users as they hit the load balanced Rails nodes. If this is the first Linux package node you are configuring, then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: @@ -2123,7 +2106,7 @@ the [HTTPS documentation](https://docs.gitlab.com/omnibus/settings/ssl/index.htm ## Configure Prometheus -The Omnibus GitLab package can be used to configure a standalone Monitoring node +The Linux package can be used to configure a standalone Monitoring node running [Prometheus](../monitoring/prometheus/index.md) and [Grafana](../monitoring/performance/grafana_configuration.md). @@ -2134,7 +2117,7 @@ The following IP will be used as an example: To configure the Monitoring node: 1. SSH in to the Monitoring node. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. @@ -2232,7 +2215,7 @@ in the future. ### Enable incremental logging -GitLab Runner returns job logs in chunks which Omnibus GitLab caches temporarily on disk in `/var/opt/gitlab/gitlab-ci/builds` by default, even when using consolidated object storage. With default configuration, this directory needs to be shared through NFS on any GitLab Rails and Sidekiq nodes. +GitLab Runner returns job logs in chunks which the Linux package caches temporarily on disk in `/var/opt/gitlab/gitlab-ci/builds` by default, even when using consolidated object storage. With default configuration, this directory needs to be shared through NFS on any GitLab Rails and Sidekiq nodes. While sharing the job logs through NFS is supported, it's recommended to avoid the need to use NFS by enabling [incremental logging](../job_logs.md#incremental-logging-architecture) (required when no NFS node has been deployed). Incremental logging uses Redis instead of disk space for temporary caching of job logs. @@ -2264,7 +2247,7 @@ Prometheus, and Grafana. Hybrid installations leverage the benefits of both cloud native and traditional compute deployments. With this, _stateless_ components can benefit from cloud native workload management benefits while _stateful_ components are deployed in compute VMs -with Omnibus to benefit from increased permanence. +with Linux package installations to benefit from increased permanence. Refer to the Helm charts [Advanced configuration](https://docs.gitlab.com/charts/advanced/) documentation for setup instructions including guidance on what GitLab secrets to sync @@ -2299,7 +2282,7 @@ the overall makeup as desired as long as the minimum CPU and Memory requirements - Nodes configuration is shown as it is forced to ensure pod vCPU / memory ratios and avoid scaling during **performance testing**. - In production deployments, there is no need to assign pods to specific nodes. A minimum of three nodes per node group in three different availability zones is strongly recommended to align with resilient cloud architecture practices. -Next are the backend components that run on static compute VMs via Omnibus (or External PaaS +Next are the backend components that run on static compute VMs using the Linux package (or External PaaS services where applicable): | Service | Nodes | Configuration | GCP | AWS | diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index e3e361db133..bd184c372b3 100644 --- a/doc/administration/reference_architectures/2k_users.md +++ b/doc/administration/reference_architectures/2k_users.md @@ -253,7 +253,7 @@ A reputable provider or solution should be used for this. [Google Cloud SQL](htt If you use a third party external service: -1. Note that the HA Omnibus PostgreSQL setup encompasses PostgreSQL, PgBouncer and Consul. All of these components would no longer be required when using a third party external service. +1. Note that the HA Linux package PostgreSQL setup encompasses PostgreSQL, PgBouncer and Consul. All of these components would no longer be required when using a third party external service. 1. Set up PostgreSQL according to the [database requirements document](../../install/requirements.md#database). 1. Set up a `gitlab` username with a password of your choice. The `gitlab` user @@ -261,10 +261,10 @@ If you use a third party external service: 1. Configure the GitLab application servers with the appropriate details. This step is covered in [Configuring the GitLab Rails application](#configure-gitlab-rails). -### Standalone PostgreSQL using Omnibus GitLab +### Standalone PostgreSQL using the Linux package 1. SSH in to the PostgreSQL server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Generate a password hash for PostgreSQL. This assumes you will use the default @@ -308,8 +308,8 @@ If you use a third party external service: gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. 1. Note the PostgreSQL node's IP address or hostname, port, and @@ -336,14 +336,14 @@ You can optionally use a third party external service for Redis as long as it me A reputable provider or solution should be used for this. [Google Memorystore](https://cloud.google.com/memorystore/docs/redis/redis-overview) and [AWS Elasticache](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html) are known to work. However, note that the Redis Cluster mode specifically isn't supported by GitLab. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. -### Standalone Redis using Omnibus GitLab +### Standalone Redis using the Linux package -The Omnibus GitLab package can be used to configure a standalone Redis server. +The Linux package can be used to configure a standalone Redis server. The steps below are the minimum necessary to configure a Redis server with -Omnibus: +the Linux package: 1. SSH in to the Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -367,8 +367,8 @@ Omnibus: } ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -432,7 +432,7 @@ installation has two repository storages: `default` and `storage1`. To configure the Gitaly server, on the server node you want to use for Gitaly: -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. 1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure @@ -517,8 +517,8 @@ Updates to example must be made at: } ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -603,7 +603,7 @@ but this is dependent on workload. On each node perform the following: -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Create or edit `/etc/gitlab/gitlab.rb` and use the following configuration. @@ -717,8 +717,8 @@ On each node perform the following: sudo cp cert.pem /etc/gitlab/trusted-certs/ ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: @@ -768,12 +768,12 @@ the [HTTPS documentation](https://docs.gitlab.com/omnibus/settings/ssl/index.htm ## Configure Prometheus -The Omnibus GitLab package can be used to configure a standalone Monitoring node +The Linux package can be used to configure a standalone Monitoring node running [Prometheus](../monitoring/prometheus/index.md) and [Grafana](../monitoring/performance/grafana_configuration.md): 1. SSH in to the Monitoring node. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -908,7 +908,7 @@ in the future. ### Enable incremental logging -GitLab Runner returns job logs in chunks which Omnibus GitLab caches temporarily on disk in `/var/opt/gitlab/gitlab-ci/builds` by default, even when using consolidated object storage. With default configuration, this directory needs to be shared through NFS on any GitLab Rails and Sidekiq nodes. +GitLab Runner returns job logs in chunks which the Linux package caches temporarily on disk in `/var/opt/gitlab/gitlab-ci/builds` by default, even when using consolidated object storage. With default configuration, this directory needs to be shared through NFS on any GitLab Rails and Sidekiq nodes. While sharing the job logs through NFS is supported, it's recommended to avoid the need to use NFS by enabling [incremental logging](../job_logs.md#incremental-logging-architecture) (required when no NFS node has been deployed). Incremental logging uses Redis instead of disk space for temporary caching of job logs. @@ -940,7 +940,7 @@ Prometheus, and Grafana. Hybrid installations leverage the benefits of both cloud native and traditional compute deployments. With this, _stateless_ components can benefit from cloud native workload management benefits while _stateful_ components are deployed in compute VMs -with Omnibus to benefit from increased permanence. +with Linux package installations to benefit from increased permanence. Refer to the Helm charts [Advanced configuration](https://docs.gitlab.com/charts/advanced/) documentation for setup instructions including guidance on what GitLab secrets to sync @@ -979,7 +979,7 @@ the overall makeup as desired as long as the minimum CPU and Memory requirements - Nodes configuration is shown as it is forced to ensure pod vCPU / memory ratios and avoid scaling during **performance testing**. - In production deployments, there is no need to assign pods to specific nodes. A minimum of three nodes per node group in three different availability zones is strongly recommended to align with resilient cloud architecture practices. -Next are the backend components that run on static compute VMs via Omnibus (or External PaaS +Next are the backend components that run on static compute VMs using the Linux package (or External PaaS services where applicable): | Service | Nodes | Configuration | GCP | AWS | diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index 4b7563d9d8d..cf2d9667481 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -452,7 +452,7 @@ You can optionally use a third party external service for Redis as long as it me A reputable provider or solution should be used for this. [Google Memorystore](https://cloud.google.com/memorystore/docs/redis/redis-overview) and [AWS Elasticache](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html) are known to work. However, note that the Redis Cluster mode specifically isn't supported by GitLab. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. -### Standalone Redis using Omnibus GitLab +### Standalone Redis using the Linux package This is the section where we install and set up the new Redis instances. @@ -474,9 +474,9 @@ a node and change its status from primary to replica (and vice versa). #### Configuring the primary Redis instance 1. SSH in to the **Primary** Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -518,8 +518,8 @@ a node and change its status from primary to replica (and vice versa). gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -552,9 +552,9 @@ run: redis-exporter: (pid 30075) 76861s; run: log: (pid 29674) 76896s #### Configuring the replica Redis instances 1. SSH in to the **replica** Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -603,8 +603,8 @@ run: redis-exporter: (pid 30075) 76861s; run: log: (pid 29674) 76896s gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. 1. Go through the steps again for all the other replica nodes, and @@ -651,9 +651,9 @@ clients to report `NOAUTH Authentication required.`. To configure the Sentinel: 1. SSH in to the server that will host Consul/Sentinel. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -739,8 +739,8 @@ To configure the Sentinel: gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -791,19 +791,19 @@ A reputable provider or solution should be used for this. [Google Cloud SQL](htt If you use a third party external service: -1. Note that the HA Omnibus PostgreSQL setup encompasses PostgreSQL, PgBouncer and Consul. All of these components would no longer be required when using a third party external service. +1. Note that the HA Linux package PostgreSQL setup encompasses PostgreSQL, PgBouncer and Consul. All of these components would no longer be required when using a third party external service. 1. Set up PostgreSQL according to the [database requirements document](../../install/requirements.md#database). 1. Set up a `gitlab` username with a password of your choice. The `gitlab` user needs privileges to create the `gitlabhq_production` database. 1. Configure the GitLab application servers with the appropriate details. This step is covered in [Configuring the GitLab Rails application](#configure-gitlab-rails). -1. The number of nodes required to achieve HA may differ depending on the service compared to Omnibus and doesn't need to match accordingly. +1. The number of nodes required to achieve HA may differ depending on the service compared to the Linux package and doesn't need to match accordingly. 1. However, if [Database Load Balancing](../postgresql/database_load_balancing.md) via Read Replicas is desired for further improved performance it's recommended to follow the node count for the Reference Architecture. -### Standalone PostgreSQL using Omnibus GitLab +### Standalone PostgreSQL using the Linux package -The recommended Omnibus GitLab configuration for a PostgreSQL cluster with +The recommended Linux package configuration for a PostgreSQL cluster with replication and failover requires: - A minimum of three PostgreSQL nodes. @@ -883,9 +883,6 @@ in the second step, do not supply the `EXTERNAL_URL` value. # available database connections. patroni['postgresql']['max_wal_senders'] = 7 - # Incoming recommended value for max connections is 500. See https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5691. - patroni['postgresql']['max_connections'] = 500 - # Prevent database migrations from running on upgrade automatically gitlab_rails['auto_migrate'] = false @@ -940,8 +937,8 @@ PostgreSQL, with Patroni managing its failover, will default to use `pg_rewind` Like most failover handling methods, this has a small chance of leading to data loss. For more information, see the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -1013,8 +1010,6 @@ The following IPs will be used as an example: password: '<pgbouncer_password_hash>' } } - # Incoming recommended value for max db connections is 150. See https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5691. - pgbouncer['max_db_connections'] = 150 # Configure Consul agent consul['watchers'] = %w(postgresql) @@ -1030,8 +1025,8 @@ The following IPs will be used as an example: pgbouncer_exporter['listen_address'] = '0.0.0.0:9188' ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -1138,7 +1133,7 @@ Praefect, the routing and transaction manager for Gitaly Cluster, requires its o If you want to have a highly available setup, Praefect requires a third-party PostgreSQL database. A built-in solution is being [worked on](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7292). -#### Praefect non-HA PostgreSQL standalone using Omnibus GitLab +#### Praefect non-HA PostgreSQL standalone using the Linux package The following IPs will be used as an example: @@ -1169,7 +1164,6 @@ in the second step, do not supply the `EXTERNAL_URL` value. # PostgreSQL configuration postgresql['listen_address'] = '0.0.0.0' - postgresql['max_connections'] = 500 # Prevent database migrations from running on upgrade automatically gitlab_rails['auto_migrate'] = false @@ -1200,8 +1194,8 @@ in the second step, do not supply the `EXTERNAL_URL` value. # END user configuration ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. 1. Follow the [post configuration](#praefect-postgresql-post-configuration). @@ -1240,11 +1234,11 @@ After the Praefect PostgreSQL server has been set up, you'll then need to config We recommend the user be named `praefect` and the database `praefect_production`, and these can be configured as standard in PostgreSQL. The password for the user is the same as the one you configured earlier as `<praefect_postgresql_password>`. -This is how this would work with a Omnibus GitLab PostgreSQL setup: +This is how this would work with a Linux package PostgreSQL setup: 1. SSH in to the Praefect PostgreSQL node. 1. Connect to the PostgreSQL server with administrative access. - The `gitlab-psql` user should be used here for this as it's added by default in Omnibus. + The `gitlab-psql` user should be used here for this as it's added by default in the Linux package. The database `template1` is used because it is created by default on all PostgreSQL servers. ```shell @@ -1305,7 +1299,7 @@ The following IPs will be used as an example: To configure the Praefect nodes, on each one: 1. SSH in to the Praefect server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Edit the `/etc/gitlab/gitlab.rb` file to configure Praefect: @@ -1417,8 +1411,8 @@ Updates to example must be made at: # END user configuration ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace -the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace +the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. Praefect requires to run some database migrations, much like the main GitLab application. For this you should select **one Praefect node only to run the migrations**, AKA the _Deploy Node_. This node @@ -1478,7 +1472,7 @@ The following IPs will be used as an example: On each node: -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. 1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure @@ -1604,8 +1598,8 @@ Updates to example must be made at: } ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). @@ -1712,7 +1706,7 @@ The following IPs will be used as an example: To configure the Sidekiq nodes, one each one: 1. SSH in to the Sidekiq server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Create or edit `/etc/gitlab/gitlab.rb` and use the following configuration: @@ -1724,18 +1718,7 @@ Updates to example must be made at: --> ```ruby - # Avoid running unnecessary services on the Sidekiq server - gitaly['enable'] = false - postgresql['enable'] = false - redis['enable'] = false - nginx['enable'] = false - puma['enable'] = false - gitlab_workhorse['enable'] = false - prometheus['enable'] = false - alertmanager['enable'] = false - grafana['enable'] = false - gitlab_exporter['enable'] = false - gitlab_kas['enable'] = false + roles ["sidekiq_role"] # External URL ## This should match the URL of the external load balancer @@ -1824,8 +1807,8 @@ Updates to example must be made at: gitlab_rails['backup_upload_remote_directory'] = "<gcp-backups-state-bucket-name>" ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: @@ -1878,7 +1861,7 @@ examples include the Object storage configuration. On each node perform the following: -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Create or edit `/etc/gitlab/gitlab.rb` and use the following configuration. @@ -2011,11 +1994,11 @@ On each node perform the following: sudo cp cert.pem /etc/gitlab/trusted-certs/ ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. -1. Copy the SSH host keys (all in the name format `/etc/ssh/ssh_host_*_key*`) from the first Omnibus node you configured and +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. +1. Copy the SSH host keys (all in the name format `/etc/ssh/ssh_host_*_key*`) from the first Linux package node you configured and add or replace the files of the same name on this server. This ensures host mismatch errors aren't thrown - for your users as they hit the load balanced Rails nodes. If this is the first Omnibus node you are configuring, + for your users as they hit the load balanced Rails nodes. If this is the first Linux package node you are configuring, then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: @@ -2080,12 +2063,12 @@ the [HTTPS documentation](https://docs.gitlab.com/omnibus/settings/ssl/index.htm ## Configure Prometheus -The Omnibus GitLab package can be used to configure a standalone Monitoring node +The Linux package can be used to configure a standalone Monitoring node running [Prometheus](../monitoring/prometheus/index.md) and [Grafana](../monitoring/performance/grafana_configuration.md): 1. SSH in to the Monitoring node. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -2197,7 +2180,7 @@ in the future. ### Enable incremental logging -GitLab Runner returns job logs in chunks which Omnibus GitLab caches temporarily on disk in `/var/opt/gitlab/gitlab-ci/builds` by default, even when using consolidated object storage. With default configuration, this directory needs to be shared through NFS on any GitLab Rails and Sidekiq nodes. +GitLab Runner returns job logs in chunks which the Linux package caches temporarily on disk in `/var/opt/gitlab/gitlab-ci/builds` by default, even when using consolidated object storage. With default configuration, this directory needs to be shared through NFS on any GitLab Rails and Sidekiq nodes. While sharing the job logs through NFS is supported, it's recommended to avoid the need to use NFS by enabling [incremental logging](../job_logs.md#incremental-logging-architecture) (required when no NFS node has been deployed). Incremental logging uses Redis instead of disk space for temporary caching of job logs. @@ -2238,7 +2221,7 @@ but with smaller performance requirements, several modifications can be consider - Running select components in reputable Cloud PaaS solutions: Select components of the GitLab setup can instead be run on Cloud Provider PaaS solutions. By doing this, additional dependent components can also be removed: - PostgreSQL: Can be run on reputable Cloud PaaS solutions such as Google Cloud SQL or Amazon RDS. In this setup, the PgBouncer and Consul nodes are no longer required: - Consul may still be desired if [Prometheus](../monitoring/prometheus/index.md) auto discovery is a requirement, otherwise you would need to [manually add scrape configurations](../monitoring/prometheus/index.md#adding-custom-scrape-configurations) for all nodes. - - As Redis Sentinel runs on the same box as Consul in this architecture, it may need to be run on a separate box if Redis is still being run via Omnibus. + - As Redis Sentinel runs on the same box as Consul in this architecture, it may need to be run on a separate box if Redis is still being run using the Linux package. - Redis: Can be run on reputable Cloud PaaS solutions such as Google Memorystore and AWS ElastiCache. In this setup, the Redis Sentinel is no longer required. ## Cloud Native Hybrid reference architecture with Helm Charts (alternative) @@ -2253,7 +2236,7 @@ Prometheus, and Grafana. Hybrid installations leverage the benefits of both cloud native and traditional compute deployments. With this, _stateless_ components can benefit from cloud native workload management benefits while _stateful_ components are deployed in compute VMs -with Omnibus to benefit from increased permanence. +with Linux package installations to benefit from increased permanence. Refer to the Helm charts [Advanced configuration](https://docs.gitlab.com/charts/advanced/) documentation for setup instructions including guidance on what GitLab secrets to sync @@ -2288,7 +2271,7 @@ the overall makeup as desired as long as the minimum CPU and Memory requirements - Nodes configuration is shown as it is forced to ensure pod vCPU / memory ratios and avoid scaling during **performance testing**. - In production deployments, there is no need to assign pods to specific nodes. A minimum of three nodes per node group in three different availability zones is strongly recommended to align with resilient cloud architecture practices. -Next are the backend components that run on static compute VMs via Omnibus (or External PaaS +Next are the backend components that run on static compute VMs using the Linux package (or External PaaS services where applicable): | Service | Nodes | Configuration | GCP | AWS | diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index 6dc7f7affab..2187b0ff02c 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -436,9 +436,9 @@ The following IPs will be used as an example: To configure Consul: 1. SSH in to the server that will host Consul. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab - package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version +1. [Download and install](https://about.gitlab.com/install/) the Linux + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -462,8 +462,8 @@ To configure Consul: gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -513,19 +513,19 @@ A reputable provider or solution should be used for this. [Google Cloud SQL](htt If you use a third party external service: -1. Note that the HA Omnibus PostgreSQL setup encompasses PostgreSQL, PgBouncer and Consul. All of these components would no longer be required when using a third party external service. +1. Note that the HA Linux package PostgreSQL setup encompasses PostgreSQL, PgBouncer and Consul. All of these components would no longer be required when using a third party external service. 1. Set up PostgreSQL according to the [database requirements document](../../install/requirements.md#database). 1. Set up a `gitlab` username with a password of your choice. The `gitlab` user needs privileges to create the `gitlabhq_production` database. 1. Configure the GitLab application servers with the appropriate details. This step is covered in [Configuring the GitLab Rails application](#configure-gitlab-rails). -1. The number of nodes required to achieve HA may differ depending on the service compared to Omnibus and doesn't need to match accordingly. +1. The number of nodes required to achieve HA may differ depending on the service compared to the Linux package and doesn't need to match accordingly. 1. However, if [Database Load Balancing](../postgresql/database_load_balancing.md) via Read Replicas is desired for further improved performance it's recommended to follow the node count for the Reference Architecture. -### Standalone PostgreSQL using Omnibus GitLab +### Standalone PostgreSQL using the Linux package -The recommended Omnibus GitLab configuration for a PostgreSQL cluster with +The recommended Linux package configuration for a PostgreSQL cluster with replication and failover requires: - A minimum of three PostgreSQL nodes. @@ -605,9 +605,6 @@ in the second step, do not supply the `EXTERNAL_URL` value. # available database connections. patroni['postgresql']['max_wal_senders'] = 7 - # Incoming recommended value for max connections is 500. See https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5691. - patroni['postgresql']['max_connections'] = 500 - # Prevent database migrations from running on upgrade automatically gitlab_rails['auto_migrate'] = false @@ -663,8 +660,8 @@ PostgreSQL, with Patroni managing its failover, will default to use `pg_rewind` Like most failover handling methods, this has a small chance of leading to data loss. For more information, see the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -736,8 +733,6 @@ The following IPs will be used as an example: password: '<pgbouncer_password_hash>' } } - # Incoming recommended value for max db connections is 150. See https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5691. - pgbouncer['max_db_connections'] = 150 # Configure Consul agent consul['watchers'] = %w(postgresql) @@ -752,8 +747,8 @@ The following IPs will be used as an example: node_exporter['listen_address'] = '0.0.0.0:9100' ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -861,9 +856,9 @@ a node and change its status from primary to replica (and vice versa). #### Configure the primary Redis Cache node 1. SSH in to the **Primary** Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -926,17 +921,17 @@ a node and change its status from primary to replica (and vice versa). gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. #### Configure the replica Redis Cache nodes 1. SSH in to the **replica** Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the same contents as the primary node in the previous section by replacing `redis_master_node` with `redis_replica_node`: @@ -999,9 +994,9 @@ a node and change its status from primary to replica (and vice versa). gitlab_rails['auto_migrate'] = false ``` - 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus + 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace the file of the same name on this - server. If this is the first Omnibus node you are configuring then you + server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes @@ -1029,9 +1024,9 @@ a node and change its status from primary to replica (and vice versa). #### Configure the primary Redis Persistent node 1. SSH in to the **Primary** Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -1084,17 +1079,17 @@ a node and change its status from primary to replica (and vice versa). gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. #### Configure the replica Redis Persistent nodes 1. SSH in to the **replica** Redis Persistent server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -1147,8 +1142,8 @@ a node and change its status from primary to replica (and vice versa). gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -1204,7 +1199,7 @@ Praefect, the routing and transaction manager for Gitaly Cluster, requires its o If you want to have a highly available setup, Praefect requires a third-party PostgreSQL database. A built-in solution is being [worked on](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7292). -#### Praefect non-HA PostgreSQL standalone using Omnibus GitLab +#### Praefect non-HA PostgreSQL standalone using the Linux package The following IPs will be used as an example: @@ -1235,7 +1230,6 @@ in the second step, do not supply the `EXTERNAL_URL` value. # PostgreSQL configuration postgresql['listen_address'] = '0.0.0.0' - postgresql['max_connections'] = 500 # Prevent database migrations from running on upgrade automatically gitlab_rails['auto_migrate'] = false @@ -1266,8 +1260,8 @@ in the second step, do not supply the `EXTERNAL_URL` value. # END user configuration ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -1309,11 +1303,11 @@ After the Praefect PostgreSQL server has been set up, you'll then need to config We recommend the user be named `praefect` and the database `praefect_production`, and these can be configured as standard in PostgreSQL. The password for the user is the same as the one you configured earlier as `<praefect_postgresql_password>`. -This is how this would work with a Omnibus GitLab PostgreSQL setup: +This is how this would work with a Linux package PostgreSQL setup: 1. SSH in to the Praefect PostgreSQL node. 1. Connect to the PostgreSQL server with administrative access. - The `gitlab-psql` user should be used here for this as it's added by default in Omnibus. + The `gitlab-psql` user should be used here for this as it's added by default in the Linux package. The database `template1` is used because it is created by default on all PostgreSQL servers. ```shell @@ -1374,7 +1368,7 @@ The following IPs will be used as an example: To configure the Praefect nodes, on each one: 1. SSH in to the Praefect server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Edit the `/etc/gitlab/gitlab.rb` file to configure Praefect: @@ -1486,8 +1480,8 @@ Updates to example must be made at: # END user configuration ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace -the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace +the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. Praefect requires to run some database migrations, much like the main GitLab application. For this you should select **one Praefect node only to run the migrations**, AKA the _Deploy Node_. This node @@ -1547,7 +1541,7 @@ The following IPs will be used as an example: On each node: -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. 1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure @@ -1669,8 +1663,8 @@ Updates to example must be made at: } ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). @@ -1775,7 +1769,7 @@ examples include the Object storage configuration. To configure the Sidekiq nodes, on each one: 1. SSH in to the Sidekiq server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Create or edit `/etc/gitlab/gitlab.rb` and use the following configuration: @@ -1787,18 +1781,7 @@ Updates to example must be made at: --> ```ruby - # Avoid running unnecessary services on the Sidekiq server - gitaly['enable'] = false - postgresql['enable'] = false - redis['enable'] = false - nginx['enable'] = false - puma['enable'] = false - gitlab_workhorse['enable'] = false - prometheus['enable'] = false - alertmanager['enable'] = false - grafana['enable'] = false - gitlab_exporter['enable'] = false - gitlab_kas['enable'] = false + roles ["sidekiq_role"] # External URL ## This should match the URL of the external load balancer @@ -1894,8 +1877,8 @@ Updates to example must be made at: gitlab_rails['backup_upload_remote_directory'] = "<gcp-backups-state-bucket-name>" ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: @@ -1948,7 +1931,7 @@ The following IPs will be used as an example: On each node perform the following: -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. @@ -2064,8 +2047,8 @@ On each node perform the following: sudo cp cert.pem /etc/gitlab/trusted-certs/ ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: ```shell @@ -2122,7 +2105,7 @@ the [HTTPS documentation](https://docs.gitlab.com/omnibus/settings/ssl/index.htm ## Configure Prometheus -The Omnibus GitLab package can be used to configure a standalone Monitoring node +The Linux package can be used to configure a standalone Monitoring node running [Prometheus](../monitoring/prometheus/index.md) and [Grafana](../monitoring/performance/grafana_configuration.md). @@ -2133,7 +2116,7 @@ The following IP will be used as an example: To configure the Monitoring node: 1. SSH in to the Monitoring node. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. @@ -2231,7 +2214,7 @@ in the future. ### Enable incremental logging -GitLab Runner returns job logs in chunks which Omnibus GitLab caches temporarily on disk in `/var/opt/gitlab/gitlab-ci/builds` by default, even when using consolidated object storage. With default configuration, this directory needs to be shared through NFS on any GitLab Rails and Sidekiq nodes. +GitLab Runner returns job logs in chunks which the Linux package caches temporarily on disk in `/var/opt/gitlab/gitlab-ci/builds` by default, even when using consolidated object storage. With default configuration, this directory needs to be shared through NFS on any GitLab Rails and Sidekiq nodes. While sharing the job logs through NFS is supported, it's recommended to avoid the need to use NFS by enabling [incremental logging](../job_logs.md#incremental-logging-architecture) (required when no NFS node has been deployed). Incremental logging uses Redis instead of disk space for temporary caching of job logs. @@ -2263,7 +2246,7 @@ Prometheus, and Grafana. Hybrid installations leverage the benefits of both cloud native and traditional compute deployments. With this, _stateless_ components can benefit from cloud native workload management benefits while _stateful_ components are deployed in compute VMs -with Omnibus to benefit from increased permanence. +with Linux package installations to benefit from increased permanence. Refer to the Helm charts [Advanced configuration](https://docs.gitlab.com/charts/advanced/) documentation for setup instructions including guidance on what GitLab secrets to sync @@ -2289,7 +2272,7 @@ the overall makeup as desired as long as the minimum CPU and Memory requirements | Service Node Group | Nodes | Configuration | GCP | AWS | Min Allocatable CPUs and Memory | |---------------------|-------|-------------------------|-----------------|--------------|---------------------------------| -| Webservice | 16 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | `m5.8xlarge` | 510 vCPU, 472 GB memory | +| Webservice | 16 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | `c5.9xlarge` | 510 vCPU, 472 GB memory | | Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | 15.5 vCPU, 50 GB memory | | Supporting services | 2 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | 7.75 vCPU, 25 GB memory | @@ -2298,7 +2281,7 @@ the overall makeup as desired as long as the minimum CPU and Memory requirements - Nodes configuration is shown as it is forced to ensure pod vCPU / memory ratios and avoid scaling during **performance testing**. - In production deployments, there is no need to assign pods to specific nodes. A minimum of three nodes per node group in three different availability zones is strongly recommended to align with resilient cloud architecture practices. -Next are the backend components that run on static compute VMs via Omnibus (or External PaaS +Next are the backend components that run on static compute VMs using the Linux package (or External PaaS services where applicable): | Service | Nodes | Configuration | GCP | AWS | diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index 754a844df3f..2b85426de58 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -446,7 +446,7 @@ You can optionally use a third party external service for Redis as long as it me A reputable provider or solution should be used for this. [Google Memorystore](https://cloud.google.com/memorystore/docs/redis/redis-overview) and [AWS Elasticache](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html) are known to work. However, note that the Redis Cluster mode specifically isn't supported by GitLab. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. -### Standalone Redis using Omnibus GitLab +### Standalone Redis using the Linux package This is the section where we install and set up the new Redis instances. @@ -468,9 +468,9 @@ a node and change its status from primary to replica (and vice versa). #### Configuring the primary Redis instance 1. SSH in to the **Primary** Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -512,8 +512,8 @@ a node and change its status from primary to replica (and vice versa). gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -546,9 +546,9 @@ run: redis-exporter: (pid 30075) 76861s; run: log: (pid 29674) 76896s #### Configuring the replica Redis instances 1. SSH in to the **replica** Redis server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -597,8 +597,8 @@ run: redis-exporter: (pid 30075) 76861s; run: log: (pid 29674) 76896s gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. 1. Go through the steps again for all the other replica nodes, and @@ -645,9 +645,9 @@ clients to report `NOAUTH Authentication required.`. To configure the Sentinel: 1. SSH in to the server that hosts Consul/Sentinel. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to both follow _only_ installation steps 1 and 2 - on the page, and to select the correct Omnibus GitLab package, with the same version + on the page, and to select the correct Linux package, with the same version and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -733,8 +733,8 @@ To configure the Sentinel: gitlab_rails['auto_migrate'] = false ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. 1. Go through the steps again for all the other Consul/Sentinel nodes, and @@ -784,19 +784,19 @@ A reputable provider or solution should be used for this. [Google Cloud SQL](htt If you use a third party external service: -1. Note that the HA Omnibus PostgreSQL setup encompasses PostgreSQL, PgBouncer and Consul. All of these components would no longer be required when using a third party external service. +1. Note that the HA Linux package PostgreSQL setup encompasses PostgreSQL, PgBouncer and Consul. All of these components would no longer be required when using a third party external service. 1. Set up PostgreSQL according to the [database requirements document](../../install/requirements.md#database). 1. Set up a `gitlab` username with a password of your choice. The `gitlab` user needs privileges to create the `gitlabhq_production` database. 1. Configure the GitLab application servers with the appropriate details. This step is covered in [Configuring the GitLab Rails application](#configure-gitlab-rails). -1. The number of nodes required to achieve HA may differ depending on the service compared to Omnibus and doesn't need to match accordingly. +1. The number of nodes required to achieve HA may differ depending on the service compared to the Linux package and doesn't need to match accordingly. 1. However, if [Database Load Balancing](../postgresql/database_load_balancing.md) via Read Replicas is desired for further improved performance it's recommended to follow the node count for the Reference Architecture. -### Standalone PostgreSQL using Omnibus GitLab +### Standalone PostgreSQL using the Linux package -The recommended Omnibus GitLab configuration for a PostgreSQL cluster with +The recommended Linux package configuration for a PostgreSQL cluster with replication and failover requires: - A minimum of three PostgreSQL nodes. @@ -876,9 +876,6 @@ in the second step, do not supply the `EXTERNAL_URL` value. # available database connections. patroni['postgresql']['max_wal_senders'] = 7 - # Incoming recommended value for max connections is 500. See https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5691. - patroni['postgresql']['max_connections'] = 500 - # Prevent database migrations from running on upgrade automatically gitlab_rails['auto_migrate'] = false @@ -933,8 +930,8 @@ PostgreSQL, with Patroni managing its failover, defaults to use `pg_rewind` by d Like most failover handling methods, this has a small chance of leading to data loss. For more information, see the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -1006,8 +1003,6 @@ The following IPs are used as an example: password: '<pgbouncer_password_hash>' } } - # Incoming recommended value for max db connections is 150. See https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5691. - pgbouncer['max_db_connections'] = 150 # Configure Consul agent consul['watchers'] = %w(postgresql) @@ -1023,8 +1018,8 @@ The following IPs are used as an example: pgbouncer_exporter['listen_address'] = '0.0.0.0:9188' ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -1131,7 +1126,7 @@ Praefect, the routing and transaction manager for Gitaly Cluster, requires its o If you want to have a highly available setup, Praefect requires a third-party PostgreSQL database. A built-in solution is being [worked on](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7292). -#### Praefect non-HA PostgreSQL standalone using Omnibus GitLab +#### Praefect non-HA PostgreSQL standalone using the Linux package The following IPs are used as an example: @@ -1162,7 +1157,6 @@ in the second step, do not supply the `EXTERNAL_URL` value. # PostgreSQL configuration postgresql['listen_address'] = '0.0.0.0' - postgresql['max_connections'] = 500 # Prevent database migrations from running on upgrade automatically gitlab_rails['auto_migrate'] = false @@ -1193,8 +1187,8 @@ in the second step, do not supply the `EXTERNAL_URL` value. # END user configuration ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -1234,11 +1228,11 @@ After the Praefect PostgreSQL server has been set up, you then need to configure We recommend the user be named `praefect` and the database `praefect_production`, and these can be configured as standard in PostgreSQL. The password for the user is the same as the one you configured earlier as `<praefect_postgresql_password>`. -This is how this would work with a Omnibus GitLab PostgreSQL setup: +This is how this would work with a Linux package PostgreSQL setup: 1. SSH in to the Praefect PostgreSQL node. 1. Connect to the PostgreSQL server with administrative access. - The `gitlab-psql` user should be used here for this as it's added by default in Omnibus. + The `gitlab-psql` user should be used here for this as it's added by default in the Linux package. The database `template1` is used because it is created by default on all PostgreSQL servers. ```shell @@ -1299,7 +1293,7 @@ The following IPs are used as an example: To configure the Praefect nodes, on each one: 1. SSH in to the Praefect server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Edit the `/etc/gitlab/gitlab.rb` file to configure Praefect: @@ -1411,8 +1405,8 @@ Updates to example must be made at: # END user configuration ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace -the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace +the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. Praefect requires to run some database migrations, much like the main GitLab application. For this you should select **one Praefect node only to run the migrations**, AKA the _Deploy Node_. This node @@ -1472,7 +1466,7 @@ The following IPs are used as an example: On each node: -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. 1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure @@ -1594,8 +1588,8 @@ Updates to example must be made at: } ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). @@ -1700,7 +1694,7 @@ examples include the Object storage configuration. To configure the Sidekiq nodes, one each one: 1. SSH in to the Sidekiq server. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Create or edit `/etc/gitlab/gitlab.rb` and use the following configuration: @@ -1712,18 +1706,7 @@ Updates to example must be made at: --> ```ruby - # Avoid running unnecessary services on the Sidekiq server - gitaly['enable'] = false - postgresql['enable'] = false - redis['enable'] = false - nginx['enable'] = false - puma['enable'] = false - gitlab_workhorse['enable'] = false - prometheus['enable'] = false - alertmanager['enable'] = false - grafana['enable'] = false - gitlab_exporter['enable'] = false - gitlab_kas['enable'] = false + roles ["sidekiq_role"] # External URL ## This should match the URL of the external load balancer @@ -1813,8 +1796,8 @@ Updates to example must be made at: gitlab_rails['backup_upload_remote_directory'] = "<gcp-backups-state-bucket-name>" ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: @@ -1867,7 +1850,7 @@ examples include the Object storage configuration. On each node perform the following: -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Create or edit `/etc/gitlab/gitlab.rb` and use the following configuration. @@ -2003,11 +1986,11 @@ On each node perform the following: sudo cp cert.pem /etc/gitlab/trusted-certs/ ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace - the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. -1. Copy the SSH host keys (all in the name format `/etc/ssh/ssh_host_*_key*`) from the first Omnibus node you configured and +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Linux package node you configured and add or replace + the file of the same name on this server. If this is the first Linux package node you are configuring then you can skip this step. +1. Copy the SSH host keys (all in the name format `/etc/ssh/ssh_host_*_key*`) from the first Linux package node you configured and add or replace the files of the same name on this server. This ensures host mismatch errors aren't thrown - for your users as they hit the load balanced Rails nodes. If this is the first Omnibus node you are configuring, + for your users as they hit the load balanced Rails nodes. If this is the first Linux package node you are configuring, then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: @@ -2072,12 +2055,12 @@ the [HTTPS documentation](https://docs.gitlab.com/omnibus/settings/ssl/index.htm ## Configure Prometheus -The Omnibus GitLab package can be used to configure a standalone Monitoring node +The Linux package can be used to configure a standalone Monitoring node running [Prometheus](../monitoring/prometheus/index.md) and [Grafana](../monitoring/performance/grafana_configuration.md): 1. SSH in to the Monitoring node. -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab +1. [Download and install](https://about.gitlab.com/install/) the Linux package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: @@ -2189,7 +2172,7 @@ in the future. ### Enable incremental logging -GitLab Runner returns job logs in chunks which Omnibus GitLab caches temporarily on disk in `/var/opt/gitlab/gitlab-ci/builds` by default, even when using consolidated object storage. With default configuration, this directory needs to be shared through NFS on any GitLab Rails and Sidekiq nodes. +GitLab Runner returns job logs in chunks which the Linux package caches temporarily on disk in `/var/opt/gitlab/gitlab-ci/builds` by default, even when using consolidated object storage. With default configuration, this directory needs to be shared through NFS on any GitLab Rails and Sidekiq nodes. While sharing the job logs through NFS is supported, it's recommended to avoid the need to use NFS by enabling [incremental logging](../job_logs.md#incremental-logging-architecture) (required when no NFS node has been deployed). Incremental logging uses Redis instead of disk space for temporary caching of job logs. @@ -2221,7 +2204,7 @@ Prometheus, and Grafana. Hybrid installations leverage the benefits of both cloud native and traditional compute deployments. With this, _stateless_ components can benefit from cloud native workload management benefits while _stateful_ components are deployed in compute VMs -with Omnibus to benefit from increased permanence. +with Linux package installations to benefit from increased permanence. Refer to the Helm charts [Advanced configuration](https://docs.gitlab.com/charts/advanced/) documentation for setup instructions including guidance on what GitLab secrets to sync @@ -2256,7 +2239,7 @@ the overall makeup as desired as long as the minimum CPU and Memory requirements - Nodes configuration is shown as it is forced to ensure pod vCPU / memory ratios and avoid scaling during **performance testing**. - In production deployments, there is no need to assign pods to nodes. A minimum of three nodes in three different availability zones is strongly recommended to align with resilient cloud architecture practices. -Next are the backend components that run on static compute VMs via Omnibus (or External PaaS +Next are the backend components that run on static compute VMs using the Linux package (or External PaaS services where applicable): | Service | Nodes | Configuration | GCP | AWS | diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index 8fc9fbce119..98bbcc464b8 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -93,7 +93,7 @@ If you still need to have HA for a lower number of users, this can be achieved w #### Zero Downtime Upgrades -[Zero Downtime Upgrades](../../update/zero_downtime.md) are available for standard Reference Architecture environments with HA (Cloud Native Hybrid is not supported at this time). This allows for an environment to stay up during an upgrade, but the process is more complex as a result and has some limitations as detailed in the documentation. +[Zero Downtime Upgrades](../../update/zero_downtime.md) are available for standard Reference Architecture environments with HA (Cloud Native Hybrid is [not supported](https://gitlab.com/groups/gitlab-org/cloud-native/-/epics/52)). This allows for an environment to stay up during an upgrade, but the process is more complex as a result and has some limitations as detailed in the documentation. When going through this process it's worth noting that there may still be brief moments of downtime when the HA mechanisms take effect. @@ -268,7 +268,7 @@ Through testing and real life usage, the Reference Architectures are validated a </thead> <tbody> <tr> - <td>Omnibus</td> + <td>Linux package</td> <td>🟢</td> <td>🟢</td> <td>🟡<sup>1</sup></td> diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index 8cc635b50fc..1a33b6b5746 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -93,6 +93,10 @@ If periodic repository checks cause false alarms, you can clear all repository c 1. Expand the **Repository maintenance** section. 1. Select **Clear all repository checks**. +## Troubleshooting + +When working with repository checks, you might encounter the following issues. + ### Error: `failed to parse commit <commit SHA> from object database for commit-graph` You can see a `failed to parse commit <commit SHA> from object database for commit-graph` error in repository check logs. This error occurs if your `commit-graph` cache is out diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index 9967b623773..c09c88ee020 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -87,7 +87,7 @@ moving things between mount points, and problems can occur. Ideally, `/home/git` is the mount point, so things remain inside the same mount point. Linux package installations guarantee this because they don't specify the full repository path but instead -the parent path, but source installations do not. +the parent path, but self-compiled installations do not. ### Example configuration @@ -118,7 +118,7 @@ For self-compiled installations: path: /mnt/storage2/repositories ``` -1. [Restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. [Restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect. 1. [Configure where new repositories are stored](#configure-where-new-repositories-are-stored). diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index e1512038286..6e47d3099bd 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -29,9 +29,7 @@ The repository storage types documented here apply to any repository storage def ## Hashed storage -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28283) in GitLab 10.0. -> - Made the default for new installations in GitLab 12.0. -> - Enabled by default for new and renamed projects in GitLab 13.0. +> **Storage name** field [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128416) from **Gitaly storage name** and **Relative path** field [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128416) from **Gitaly relative path** in GitLab 16.3. Hashed storage stores projects on disk in a location based on a hash of the project's ID. Hashed storage is different to [legacy storage](#legacy-storage) where a project is stored based on: @@ -81,12 +79,11 @@ To look up a project's hash path in the Admin Area: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. 1. On the left sidebar, select **Overview > Projects** and select the project. +1. Locate the **Relative path** field. The value is similar to: -The **Gitaly relative path** is displayed there and looks similar to: - -```plaintext -"@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git" -``` + ```plaintext + "@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git" + ``` To look up a project's hash path using a Rails console: @@ -100,7 +97,7 @@ To look up a project's hash path using a Rails console: #### From hashed path to project name -Administrators can look up a project's name from its hashed storage path using: +Administrators can look up a project's name from its hashed relative path using: - A Rails console. - The `config` file in the `*.git` directory. diff --git a/doc/administration/restart_gitlab.md b/doc/administration/restart_gitlab.md index 51a4fe40b16..d0e4beccb3a 100644 --- a/doc/administration/restart_gitlab.md +++ b/doc/administration/restart_gitlab.md @@ -97,10 +97,10 @@ If you manually edit any files in `/var/opt/gitlab` that are managed by Chef, running `reconfigure` reverts the changes and restarts the services that depend on those files. -## Installations from source +## Self-compiled installations If you have followed the official installation guide to -[install GitLab from source](../install/installation.md), run the following command to restart GitLab: +[self-compile your installation](../install/installation.md), run the following command to restart GitLab: ```shell # For systems running systemd diff --git a/doc/administration/secure_files.md b/doc/administration/secure_files.md index 3c9d40c3e73..d4a57ed5d51 100644 --- a/doc/administration/secure_files.md +++ b/doc/administration/secure_files.md @@ -4,7 +4,7 @@ group: Mobile DevOps 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 --- -# Secure Files administration **(FREE)** +# Secure Files administration **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78227) in GitLab 14.8 [with a flag](feature_flags.md) named `ci_secure_files`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350748) in GitLab 15.7. Feature flag `ci_secure_files` removed. @@ -42,11 +42,7 @@ Prerequisite: gitlab_rails['ci_secure_files_enabled'] = false ``` -1. Save the file and reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` +1. Save the file and [reconfigure GitLab](restart_gitlab.md#reconfigure-a-linux-package-installation). **For self-compiled installations** @@ -57,7 +53,7 @@ Prerequisite: enabled: false ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect. ## Using local storage @@ -73,12 +69,7 @@ are stored locally, follow the steps below. gitlab_rails['ci_secure_files_storage_path'] = "/mnt/storage/ci_secure_files" ``` -1. Save the file and [reconfigure GitLab](restart_gitlab.md#reconfigure-a-linux-package-installation) -1. Save the file and reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` +1. Save the file and [reconfigure GitLab](restart_gitlab.md#reconfigure-a-linux-package-installation). **For self-compiled installations** @@ -91,7 +82,7 @@ are stored locally, follow the steps below. storage_path: /mnt/storage/ci_secure_files ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) +1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect. ## Using object storage **(FREE SELF)** @@ -109,7 +100,7 @@ Adding support is proposed in [issue 414673](https://gitlab.com/gitlab-org/gitla The following settings are: -- Nested under `ci_secure_files:` and then `object_store:` on source installations. +- Nested under `ci_secure_files:` and then `object_store:` on self-compiled installations. - Prefixed by `ci_secure_files_object_store_` on Linux package installations. | Setting | Description | Default | @@ -149,14 +140,8 @@ See [the available connection settings for different providers](object_storage.m } ``` -1. Save the file and [reconfigure GitLab](restart_gitlab.md#reconfigure-a-linux-package-installation) -1. Save the file and reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -1. [Migrate any existing local states to the object storage](#migrate-to-object-storage) +1. Save the file and [reconfigure GitLab](restart_gitlab.md#reconfigure-a-linux-package-installation). +1. [Migrate any existing local states to the object storage](#migrate-to-object-storage). **For self-compiled installations** @@ -175,8 +160,8 @@ See [the available connection settings for different providers](object_storage.m region: eu-central-1 ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. -1. [Migrate any existing local states to the object storage](#migrate-to-object-storage) +1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect. +1. [Migrate any existing local states to the object storage](#migrate-to-object-storage). ### Migrate to object storage diff --git a/doc/administration/server_hooks.md b/doc/administration/server_hooks.md index 82360581504..104eaafd8ad 100644 --- a/doc/administration/server_hooks.md +++ b/doc/administration/server_hooks.md @@ -74,7 +74,8 @@ To create server hooks for a repository: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. 1. Go to **Overview > Projects** and select the project you want to add a server hook to. -1. On the page that appears, locate the value of **Gitaly relative path**. This path is where server hooks must be located. +1. On the page that appears, locate the value of **Relative path**. This path is where server + hooks must be located. - If you are using [hashed storage](repository_storage_types.md#hashed-storage), see [Translate hashed storage paths](repository_storage_types.md#translate-hashed-storage-paths) for information on interpreting the relative path. @@ -134,7 +135,7 @@ For Linux package installations, the directory is set in `gitlab.rb` under `gita - Use the default suggestion of the `/var/opt/gitlab/gitaly/custom_hooks` directory by uncommenting it. - Add your own setting. -For installations from source: +For self-compiled installations: - The directory is set in a configuration file. The location of the configuration file depends on the GitLab version: - For GitLab 13.1 and later, the directory is set in `gitaly/config.toml` under the `[hooks]` section. However, diff --git a/doc/administration/settings/account_and_limit_settings.md b/doc/administration/settings/account_and_limit_settings.md index ca56a322237..3d632880113 100644 --- a/doc/administration/settings/account_and_limit_settings.md +++ b/doc/administration/settings/account_and_limit_settings.md @@ -107,6 +107,54 @@ details. For GitLab.com repository size limits, read [accounts and limit settings](../../user/gitlab_com/index.md#account-and-limit-settings). +## Maximum remote file size for imports + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384976) in GitLab 16.3. + +You can modify the maximum remote file size for imports from external object storages (for example, AWS) in GitLab. + +To modify the maximum import remote file size: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Account and limit**. +1. Increase or decrease by changing the value in **Maximum import remote file size (MB)**. Set to `0` to set no file size limit. + +## Maximum download file size for imports by direct transfer + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384976) in GitLab 16.3. + +You can modify the maximum download file size for imports by direct transfer in GitLab. + +To modify the maximum download file size for imports by direct transfer: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Account and limit**. +1. Increase or decrease by changing the value in **Direct transfer maximum download file size (MB)**. Set to `0` to set no download file size limit. + +## Maximum decompressed file size for imported archives + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128218) in GitLab 16.3. + +When you import a project using [file exports](../../user/project/settings/import_export.md) or [direct transfer](../../user/group/import/index.md#migrate-groups-by-direct-transfer-recommended), you can specify the maximum decompressed file size for imported archives. The default value is 25 GB. + +When you import a compressed file, the decompressed size cannot exceed the maximum decompressed file size limit. If the decompressed size exceeds the configured limit, the following error is returned: + +```plaintext +Decompressed archive size validation failed. +``` + +To modify the maximum decompressed file size for imports in GitLab: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Account and limit**. +1. Set another value for **Maximum decompressed size (MiB)**. + ## Personal access token prefix > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20968) in GitLab 13.7. @@ -147,7 +195,7 @@ For instance, consider the following workflow: 1. Your team develops apps which require large files to be stored in the application repository. -1. Although you have enabled [Git LFS](../../topics/git/lfs/index.md#git-large-file-storage-lfs) +1. Although you have enabled [Git LFS](../../topics/git/lfs/index.md) to your project, your storage has grown significantly. 1. Before you exceed available storage, you set up a limit of 10 GB per repository. diff --git a/doc/administration/settings/continuous_integration.md b/doc/administration/settings/continuous_integration.md index eaa240d4c96..edf61701a33 100644 --- a/doc/administration/settings/continuous_integration.md +++ b/doc/administration/settings/continuous_integration.md @@ -139,7 +139,7 @@ NOTE: Any changes to this setting applies to new artifacts only. The expiration time is not be updated for artifacts created before this setting was changed. The administrator may need to manually search for and expire previously-created -artifacts, as described in the [troubleshooting documentation](../../administration/job_artifacts.md#delete-job-artifacts-from-jobs-completed-before-a-specific-date). +artifacts, as described in the [troubleshooting documentation](../../administration/job_artifacts_troubleshooting.md#delete-job-artifacts-from-jobs-completed-before-a-specific-date). ## Keep the latest artifacts for all jobs in the latest successful pipelines @@ -172,9 +172,12 @@ All application settings have a [customizable cache expiry interval](../../admin ## Archive jobs -Archiving jobs is useful for reducing the CI/CD footprint on the system by removing some -of the capabilities of the jobs (metadata stored in the database needed to run the job), -but persisting the traces and artifacts for auditing purposes. +You can archive old jobs to prevent them from being re-run individually. Archived jobs +display a lock icon (**{lock}**) and **This job is archived** at the top of the job log. + +Future work is planned to reduce the CI/CD footprint on the system for archived jobs +by removing metadata stored in the database needed to run the job. See the [CI/CD data time decay](../../architecture/blueprints/ci_data_decay/index.md) +blueprint for more details. To set the duration for which the jobs are considered as old and expired: diff --git a/doc/administration/settings/img/protected_paths.png b/doc/administration/settings/img/protected_paths.png Binary files differdeleted file mode 100644 index 2233a71a139..00000000000 --- a/doc/administration/settings/img/protected_paths.png +++ /dev/null diff --git a/doc/administration/settings/index.md b/doc/administration/settings/index.md index 5fc0c029c30..a5746ad26e4 100644 --- a/doc/administration/settings/index.md +++ b/doc/administration/settings/index.md @@ -21,180 +21,8 @@ To access the **Admin Area**: 1. Sign in to your GitLab instance as an administrator. 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. -1. Select **Settings**, and the group of settings to view: - - [General](#general) - - [Geo](#geo) - - [CI/CD](#cicd) - - [Integrations](#integrations) - - [Metrics and profiling](#metrics-and-profiling) - - [Network](#network) - - [Preferences](#preferences) - - [Reporting](#reporting) - - [Repository](#repository) - - [Templates](#templates) -### General - -The **General** settings contain: - -- [Visibility and access controls](../settings/visibility_and_access_controls.md) - Set default and - restrict visibility levels. Configure import sources and Git access protocol. -- [Account and limit](../settings/account_and_limit_settings.md) - Set projects and maximum size limits, - session duration, user options, and check feature availability for namespace plan. -- [Diff limits](../diff_limits.md) - Diff content limits. -- [Sign-up restrictions](../settings/sign_up_restrictions.md) - Configure the way a user creates a new account. -- [Sign in restrictions](../settings/sign_in_restrictions.md) - Set requirements for a user to sign in. - Enable mandatory two-factor authentication. -- [Terms of Service and Privacy Policy](../settings/terms.md) - Include a Terms of Service agreement - and Privacy Policy that all users must accept. -- [External Authentication](../../administration/settings/external_authorization.md#configuration) - External Classification Policy Authorization. -- [Web terminal](../integration/terminal.md#limiting-websocket-connection-time) - - Set max session time for web terminal. -- [FLoC](floc.md) - Enable or disable - [Federated Learning of Cohorts (FLoC)](https://en.wikipedia.org/wiki/Federated_Learning_of_Cohorts) tracking. -- [GitLab for Slack app](../../user/admin_area/settings/slack_app.md) - Enable and configure the GitLab for Slack app. - -### CI/CD - -The **CI/CD** settings contain: - -- [Continuous Integration and Deployment](../../administration/settings/continuous_integration.md) - - Auto DevOps, runners and job artifacts. -- [Required pipeline configuration](../../administration/settings/continuous_integration.md#required-pipeline-configuration) - - Set an instance-wide auto included [pipeline configuration](../../ci/yaml/index.md). - This pipeline configuration is run after the project's own configuration. -- [Package Registry](../../administration/settings/continuous_integration.md#package-registry-configuration) - - Settings related to the use and experience of using the GitLab Package Registry. Some - [risks are involved](../../user/packages/container_registry/reduce_container_registry_storage.md#use-with-external-container-registries) - in enabling some of these settings. - -## Security and Compliance settings - -- [License compliance settings](security_and_compliance.md#choose-package-registry-metadata-to-sync): Enable or disable synchronization of package metadata by a registry type. - -### Geo **(PREMIUM SELF)** - -The **Geo** setting contains: - -- [Geo](../geo/index.md) - Replicate your GitLab instance to other - geographical locations. Redirects to **Admin Area > Geo > Settings** are no - longer available at **Admin Area > Settings > Geo** in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/36896). - -### Integrations - -The **Integrations** settings contain: - -- [Elasticsearch](../../integration/advanced_search/elasticsearch.md#enable-advanced-search) - - Elasticsearch integration. Elasticsearch AWS IAM. -- [Kroki](../integration/kroki.md#enable-kroki-in-gitlab) - - Allow rendering of diagrams in AsciiDoc and Markdown documents using [kroki.io](https://kroki.io). -- [Mailgun](../integration/mailgun.md) - Enable your GitLab instance - to receive invite email bounce events from Mailgun, if it is your email provider. -- [PlantUML](../integration/plantuml.md) - Allow rendering of PlantUML - diagrams in documents. -- [Customer experience improvement and third-party offers](../settings/third_party_offers.md) - - Control the display of customer experience improvement content and third-party offers. -- [Snowplow](../../development/internal_analytics/snowplow/index.md) - Configure the Snowplow integration. -- [Google GKE](../../user/project/clusters/add_gke_clusters.md) - Google GKE integration enables - you to provision GKE clusters from GitLab. -- [Amazon EKS](../../user/project/clusters/add_eks_clusters.md) - Amazon EKS integration enables - you to provision EKS clusters from GitLab. - -### Metrics and profiling - -The **Metrics and profiling** settings contain: - -- [Metrics - Prometheus](../monitoring/prometheus/gitlab_metrics.md) - - Enable and configure Prometheus metrics. -- [Metrics - Grafana](../monitoring/performance/grafana_configuration.md#integrate-with-gitlab-ui) - - Enable and configure Grafana. -- [Profiling - Performance bar](../monitoring/performance/performance_bar.md#enable-the-performance-bar-for-non-administrators) - - Enable access to the Performance Bar for non-administrator users in a given group. -- [Usage statistics](../settings/usage_statistics.md) - Enable or disable version check and Service Ping. - -### Network - -The **Network** settings contain: - -- Performance optimization - Various settings that affect GitLab performance, including: - - [Write to `authorized_keys` file](../operations/fast_ssh_key_lookup.md#set-up-fast-lookup). - - [Push event activities limit and bulk push events](../settings/push_event_activities_limit.md). -- [User and IP rate limits](../settings/user_and_ip_rate_limits.md) - Configure limits for web and API requests. - These rate limits can be overridden: - - [Package Registry Rate Limits](../settings/package_registry_rate_limits.md) - Configure specific - limits for Packages API requests that supersede the user and IP rate limits. - - [Git LFS Rate Limits](../settings/git_lfs_rate_limits.md) - Configure specific limits for - Git LFS requests that supersede the user and IP rate limits. - - [Files API Rate Limits](../settings/files_api_rate_limits.md) - Configure specific limits for - Files API requests that supersede the user and IP rate limits. - - [Search rate limits](../instance_limits.md#search-rate-limit) - Configure global search request rate limits for authenticated and unauthenticated users. - - [Deprecated API Rate Limits](../settings/deprecated_api_rate_limits.md) - Configure specific limits - for deprecated API requests that supersede the user and IP rate limits. -- [Outbound requests](../../security/webhooks.md) - Allow requests to the local network from webhooks and integrations, or deny all outbound requests. -- [Protected Paths](../settings/protected_paths.md) - Configure paths to be protected by Rack Attack. -- [Incident Management Limits](../../operations/incident_management/index.md) - Limit the - number of inbound alerts that can be sent to a project. -- [Notes creation limit](../settings/rate_limit_on_notes_creation.md) - Set a rate limit on the note creation requests. -- [Get single user limit](../settings/rate_limit_on_users_api.md) - Set a rate limit on users API endpoint to get a user by ID. -- [Projects API rate limits for unauthenticated requests](../settings/rate_limit_on_projects_api.md) - Set a rate limit on Projects list API endpoint for unauthenticated requests. - -### Preferences - -The **Preferences** settings contain: - -- [Email](../settings/email.md) - Various email settings. -- [What's new](../whats-new.md) - Configure **What's new** drawer and content. -- [Help page](help_page.md) - Help page text and support page URL. -- [Pages](../pages/index.md#custom-domain-verification) - - Size and domain settings for static websites. -- [Polling interval multiplier](../polling.md) - - Configure how frequently the GitLab UI polls for updates. -- [Gitaly timeouts](gitaly_timeouts.md) - Configure Gitaly timeouts. -- Localization: - - [Default first day of the week](../../user/profile/preferences.md). - - [Time tracking](../../user/project/time_tracking.md#limit-displayed-units-to-hours). -- [Sidekiq Job Limits](../settings/sidekiq_job_limits.md) - Limit the size of Sidekiq jobs stored in Redis. - -### Reporting - -The **Reporting** settings contain: - -- Spam and Anti-bot protection: - - Anti-spam services, such as [reCAPTCHA](../../integration/recaptcha.md), - [Akismet](../../integration/akismet.md), or [Spamcheck](../reporting/spamcheck.md). - - [IP address restrictions](../reporting/ip_addr_restrictions.md). -- [Abuse reports](../review_abuse_reports.md) - Set notification email for abuse reports. -- [Git abuse rate limit](../reporting/git_abuse_rate_limit.md) - Configure Git abuse rate limit settings. **(ULTIMATE SELF)** - -### Repository - -The **Repository** settings contain: - -- [Repository's custom initial branch name](../../user/project/repository/branches/default.md#instance-level-custom-initial-branch-name) - - Set a custom branch name for new repositories created in your instance. -- [Repository's initial default branch protection](../../user/project/repository/branches/default.md#instance-level-default-branch-protection) - - Configure the branch protections to apply to every repository's default branch. -- [Repository mirror](visibility_and_access_controls.md#enable-project-mirroring) - - Configure repository mirroring. -- [Repository storage](../repository_storage_types.md) - Configure storage path settings. -- Repository maintenance: - - [Repository checks](../repository_checks.md) - Configure - automatic Git checks on repositories. - - [Housekeeping](../housekeeping.md). Configure automatic - Git housekeeping on repositories. - - [Inactive project deletion](../inactive_project_deletion.md). Configure inactive - project deletion. -- [Repository static objects](../static_objects_external_storage.md) - - Serve repository static objects (for example, archives and blobs) from an external storage (for example, a CDN). - -### Templates **(PREMIUM SELF)** - -The **Templates** settings contain: - -- [Templates](instance_template_repository.md#configuration) - Set instance-wide template repository. -- [Custom project templates](../custom_project_templates.md) - Select the custom project template source group. - -## Default first day of the week +## Change the default first day of the week You can change the [Default first day of the week](../../user/profile/preferences.md) for the entire GitLab instance: @@ -204,7 +32,7 @@ for the entire GitLab instance: 1. Select **Settings > Preferences**. 1. Scroll to the **Localization** section, and select your desired first day of the week. -## Default language +## Change the default language You can change the [Default language](../../user/profile/preferences.md) for the entire GitLab instance: diff --git a/doc/administration/settings/project_integration_management.md b/doc/administration/settings/project_integration_management.md index 1bb4465020c..95dddf34182 100644 --- a/doc/administration/settings/project_integration_management.md +++ b/doc/administration/settings/project_integration_management.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Project integration management **(FREE)** +# Project integration management **(FREE SELF)** Project integrations can be configured and enabled by project administrators. As a GitLab instance administrator, you can set default configuration parameters for a given integration that all projects @@ -15,18 +15,19 @@ You can update these default settings at any time, changing the settings used fo are set to use instance-level or group-level defaults. Updating the default settings also enables the integration for all projects that didn't have it already enabled. -Only the complete settings for an integration can be inherited. Per-field inheritance is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). +Only the entire settings for an integration can be inherited. Per-field inheritance +is proposed in [epic 2137](https://gitlab.com/groups/gitlab-org/-/epics/2137). ## Manage instance-level default settings for a project integration **(FREE SELF)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2137) in GitLab 13.3 for project-level integrations. -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6 for group-level integrations. +To manage instance-level default settings for a project integration: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select an integration. -1. Enter configuration details and select **Save changes**. +1. Complete the fields. +1. Select **Save changes**. WARNING: This may affect all or most of the groups and projects on your GitLab instance. Review the details @@ -48,13 +49,17 @@ When you make further changes to the instance defaults: - Groups and projects with custom settings selected for the integration are not immediately affected and may choose to use the latest defaults at any time. -Only the complete settings for an integration can be inherited. Per-field inheritance -is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). This would allow -administrators to update settings inherited by groups and projects without enabling the -integration on all non-configured groups and projects by default. +If [group-level settings](#manage-group-level-default-settings-for-a-project-integration) have also +been configured for the same integration, projects in that group inherit the group-level settings +instead of the instance-level settings. + +Only the entire settings for an integration can be inherited. Per-field inheritance +is proposed in [epic 2137](https://gitlab.com/groups/gitlab-org/-/epics/2137). ### Remove an instance-level default setting +To remove an instance-level default setting: + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. 1. Select **Settings > Integrations**. @@ -63,12 +68,11 @@ integration on all non-configured groups and projects by default. Resetting an instance-level default setting removes the integration from all projects that have the integration set to use default settings. -### View projects that override the default settings +### View projects that use custom settings > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218252) in GitLab 14.2. -You can view which projects in your instance use custom settings that [override the instance-level default settings](#use-custom-settings-for-a-group-or-project-integration) -for an integration. +To view projects in your instance that [use custom settings](#use-custom-settings-for-a-project-or-group-integration): 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. @@ -78,11 +82,13 @@ for an integration. ## Manage group-level default settings for a project integration -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6. +To manage group-level default settings for a project integration: -1. Navigate to the group's **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > Integrations**. 1. Select an integration. -1. Enter configuration details and select **Save changes**. +1. Complete the fields. +1. Select **Save changes**. WARNING: This may affect all or most of the subgroups and projects belonging to the group. Review the details below. @@ -102,18 +108,21 @@ When you make further changes to the group defaults: - They are immediately applied to newer subgroups and projects, even those created after you last saved defaults for the integration. If your group-level default setting has the **Enable integration** toggle turned on, the integration is automatically enabled for all such subgroups and projects. - - Subgroups and projects with custom settings selected for the integration are not immediately affected and may choose to use the latest defaults at any time. -Only the complete settings for an integration can be inherited. Per-field inheritance -is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). This would allow -administrators to update settings inherited by subgroups and projects without enabling the -integration on all non-configured groups and projects by default. +If [instance-level settings](#manage-instance-level-default-settings-for-a-project-integration) +have also been configured for the same integration, projects in the group inherit settings from the group. + +Only the entire settings for an integration can be inherited. Per-field inheritance +is proposed in [epic 2137](https://gitlab.com/groups/gitlab-org/-/epics/2137). ### Remove a group-level default setting -1. Navigate to the group's **Settings > Integrations**. +To remove a group-level default setting: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > Integrations**. 1. Select an integration. 1. Select **Reset** and confirm. @@ -121,18 +130,24 @@ Resetting a group-level default setting removes integrations that use default se ## 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. +To use instance-level or group-level default settings for a project integration: -1. Navigate to **Project > Settings > Integrations**. -1. Choose the integration you want to enable or update. -1. From the dropdown list, select **Use default settings**. -1. Ensure the toggle is set to **Enable integration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. +1. Select an integration. +1. On the right, from the dropdown list, select **Use default settings**. +1. Under **Enable integration**, ensure the **Active** checkbox is selected. +1. Complete the fields. 1. Select **Save changes**. -## Use custom settings for a group or project integration +## Use custom settings for a project or group integration -1. Navigate to project or group's **Settings > Integrations**. -1. Choose the integration you want to enable or update. -1. From the dropdown list, select **Use custom settings**. -1. Ensure the toggle is set to **Enable integration** and enter all required settings. +To use custom settings for a project or group integration: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Settings > Integrations**. +1. Select an integration. +1. On the right, from the dropdown list, select **Use custom settings**. +1. Under **Enable integration**, ensure the **Active** checkbox is selected. +1. Complete the fields. 1. Select **Save changes**. diff --git a/doc/administration/settings/protected_paths.md b/doc/administration/settings/protected_paths.md index ba257983619..5deba7dca11 100644 --- a/doc/administration/settings/protected_paths.md +++ b/doc/administration/settings/protected_paths.md @@ -11,7 +11,7 @@ Rate limiting is a technique that improves the security and durability of a web application. For more details, see [Rate limits](../../security/rate_limits.md). You can rate limit (protect) specified paths. For these paths, GitLab responds with HTTP status -code `429` to POST requests at protected paths that exceed 10 requests per minute per IP address. +code `429` to POST requests that exceed 10 requests per minute per IP address and GET requests that exceed 10 requests per minute per IP address at protected paths. For example, the following are limited to a maximum 10 requests per minute: @@ -32,12 +32,11 @@ See also: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31246) in GitLab 12.4. Throttling of protected paths is enabled by default and can be disabled or -customized on **Admin > Network > Protected Paths**, along with these options: +customized. -- Maximum number of requests per period per user. -- Rate limit period in seconds. -- Paths to be protected. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **Protected paths**. - - -Requests over the rate limit are logged into `auth.log`. +Requests that exceed the rate limit are logged in `auth.log`. diff --git a/doc/administration/settings/push_event_activities_limit.md b/doc/administration/settings/push_event_activities_limit.md index 117e7322e30..ff924e0d208 100644 --- a/doc/administration/settings/push_event_activities_limit.md +++ b/doc/administration/settings/push_event_activities_limit.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Push event activities limit and bulk push events **(FREE)** +# Push event activities limit and bulk push events **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31007) in GitLab 12.4. diff --git a/doc/administration/settings/rate_limit_on_issues_creation.md b/doc/administration/settings/rate_limit_on_issues_creation.md index d8bc04fcdd3..20f3febbf28 100644 --- a/doc/administration/settings/rate_limit_on_issues_creation.md +++ b/doc/administration/settings/rate_limit_on_issues_creation.md @@ -5,12 +5,18 @@ group: Project Management 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 --- -# Rate limits on issue creation **(FREE SELF)** +# Rate limits on issue and epic creation **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28129) in GitLab 12.10. -This setting allows you to rate limit the requests to the issue and epic creation endpoints. -To can change its value: +Rate limits control the pace at which new epics and issues can be created. +For example, if you set the limit to `300`, the +[Projects::IssuesController#create](https://gitlab.com/gitlab-org/gitlab/blob/master/app/controllers/projects/issues_controller.rb) +action blocks requests that exceed a rate of 300 per minute. Access to the endpoint is available after one minute. + +## Set the rate limit + +To limit the number of requests made to the issue and epic creation endpoints: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. @@ -19,18 +25,12 @@ To can change its value: 1. Under **Max requests per minute**, enter the new value. 1. Select **Save changes**. -For example, if you set a limit of 300, requests using the -[Projects::IssuesController#create](https://gitlab.com/gitlab-org/gitlab/blob/master/app/controllers/projects/issues_controller.rb) -action exceeding a rate of 300 per minute are blocked. Access to the endpoint is allowed after one minute. - -When using [epics](../../user/group/epics/index.md), epic creation shares this rate limit with issues. -  -This limit is: +The limit for [epic](../../user/group/epics/index.md) creation is the same limit applied to issue creation. The rate limit: -- Applied independently per project and per user. -- Not applied per IP address. -- Disabled by default. To enable it, set the option to any value other than `0`. +- Is applied independently per project and per user. +- Is not applied per IP address. +- Can be set to `0` to disable the rate limit. Requests over the rate limit are logged into the `auth.log` file. diff --git a/doc/administration/settings/sign_up_restrictions.md b/doc/administration/settings/sign_up_restrictions.md index f213794eb75..f255e15c1be 100644 --- a/doc/administration/settings/sign_up_restrictions.md +++ b/doc/administration/settings/sign_up_restrictions.md @@ -64,7 +64,7 @@ A [user cap](#user-cap) can also be used to enforce approvals for new users. You can send confirmation emails during sign up and require that users confirm their email address before they are allowed to sign in. -For example, to enforce confirmation of the email address used for new sign ups: +To enforce confirmation of the email address used for new sign ups: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. @@ -75,33 +75,37 @@ For example, to enforce confirmation of the email address used for new sign ups: The following settings are available: - **Hard** - Send a confirmation email during sign up. New users must confirm their email address before they can log in. -- **Soft** - Send a confirmation email during sign up. New users can log in immediately, but must confirm their email in three days. Unconfirmed accounts are deleted. +- **Soft** - Send a confirmation email during sign up. New users can sign in immediately, but must confirm their email in three days. After three days, the user is not able to sign in until they confirm their email. - **Off** - New users can sign up without confirming their email address. ## User cap -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4315) in GitLab 13.7. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292600) in GitLab 13.9. +The user cap is the maximum number of billable users who can sign up or be added to a subscription +without administrator approval. After the user cap is reached, users who sign up or are +added must be [approved](../../administration/moderate_users.md#approve-or-reject-a-user-sign-up) +by an administrator. Users can use their account only after they have been approved by an administrator. -When the number of billable users reaches the user cap, any user who is added or requests access must be -[approved](../../administration/moderate_users.md#approve-or-reject-a-user-sign-up) by an administrator before they can start using -their account. - -If an administrator [increases](#set-the-user-cap-number) or [removes](#remove-the-user-cap) the -user cap, the users in pending approval state are automatically approved in a background job. +If an administrator increases or removes the user cap, users pending approval are automatically approved. NOTE: -The amount of billable users [is updated once a day](../../subscriptions/self_managed/index.md#billable-users). -This means the user cap might apply only retrospectively after the cap has already been exceeded. -To ensure the cap is enabled immediately, set it to a low value below the current number of -billable users, for example: `1`. +For instances that use LDAP or OmniAuth, when [administrator approval for new sign-ups](#require-administrator-approval-for-new-sign-ups) +is enabled or disabled, downtime might occur due to changes in the Rails configuration. +You can set a user cap to enforce approvals for new users. To ensure the user cap applies immediately, set the cap to a value below the current number of billable users (for example, `1`). + +### Set a user cap + +Set a user cap to restrict the number of users who can sign up without administrator approval. -On instances that use LDAP or OmniAuth, enabling and disabling -[administrator approval for new sign ups](#require-administrator-approval-for-new-sign-ups) -involves changing the Rails configuration, and may require downtime. -User cap can be used instead. As noted above, set the cap to value that ensures it is enforced immediately. +The number of [billable users](../../subscriptions/self_managed/index.md#billable-users) is updated once a day. +The user cap might apply only retrospectively after the cap has already been exceeded. +To ensure the cap is enabled immediately, set the cap to a value below the current number of +billable users (for example, `1`). -### Set the user cap number +Prerequisite: + +- You must be an administrator. + +To set a user cap: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. @@ -110,9 +114,18 @@ User cap can be used instead. As noted above, set the cap to value that ensures 1. Enter a number in **User cap**. 1. Select **Save changes**. -New user sign ups are subject to the user cap restriction. +### Remove the user cap + +Remove the user cap so that the number of new users who can sign up without +administrator approval is not restricted. -## Remove the user cap +After you remove the user cap, users pending approval are automatically approved. + +Prerequisite: + +- You must be an administrator. + +To remove the user cap: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. @@ -121,9 +134,6 @@ New user sign ups are subject to the user cap restriction. 1. Remove the number from **User cap**. 1. Select **Save changes**. -New users sign ups are not subject to the user cap restriction. Users in pending approval state are -automatically approved in a background job. - ## Minimum password length limit > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20661) in GitLab 12.6 diff --git a/doc/administration/settings/slack_app.md b/doc/administration/settings/slack_app.md new file mode 100644 index 00000000000..a8e672bc8fa --- /dev/null +++ b/doc/administration/settings/slack_app.md @@ -0,0 +1,113 @@ +--- +stage: Manage +group: Import and Integrate +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 +--- + +# GitLab for Slack app administration **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358872) for self-managed instances in GitLab 16.2. + +NOTE: +This page contains information about administering the GitLab for Slack app for self-managed instances. For user documentation, see [GitLab for Slack app](../../user/project/integrations/gitlab_slack_application.md). + +The GitLab for Slack app distributed through the Slack App Directory only works with GitLab.com. +On self-managed GitLab, you can create your own copy of the GitLab for Slack app from a [manifest file](https://api.slack.com/reference/manifests#creating_apps) and configure your instance. + +The app is a private one-time copy installed in your Slack workspace only and not distributed through the Slack App Directory. To have the [GitLab for Slack app](../../user/project/integrations/gitlab_slack_application.md) on your self-managed instance, you must enable the integration. + +## Create a GitLab for Slack app + +Prerequisite: + +- You must be at least a [Slack workspace administrator](https://slack.com/help/articles/360018112273-Types-of-roles-in-Slack). + +To create a GitLab for Slack app: + +- **In GitLab**: + + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. On the left sidebar, select **Settings > General**. + 1. Expand **GitLab for Slack app**. + 1. Select **Create Slack app**. + +You're then redirected to Slack for the next steps. + +- **In Slack**: + + 1. Select the Slack workspace to create the app in, then select **Next**. + 1. Slack displays a summary of the app for review. To view the complete manifest, select **Edit Configurations**. To go back to the review summary, select **Next**. + 1. Select **Create**. + 1. Select **Got it** to close the dialog. + 1. Select **Install to Workspace**. + +## Configure the settings + +After you've [created a GitLab for Slack app](#create-a-gitlab-for-slack-app), you can configure the settings in GitLab: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. +1. Expand **GitLab for Slack app**. +1. Select the **Enable GitLab for Slack app** checkbox. +1. Enter the details of your GitLab for Slack app: + 1. Go to [Slack API](https://api.slack.com/apps). + 1. Search for and select **GitLab (\<your host name\>)**. + 1. Scroll to **App Credentials**. +1. Select **Save changes**. + +### Test your configuration + +To test your GitLab for Slack app configuration: + +1. Enter the `/gitlab help` slash command into a channel in your Slack workspace. +1. Press <kbd>Enter</kbd>. + +You should see a list of available Slash commands. + +To use Slash commands for a project, configure the [GitLab for Slack app](../../user/project/integrations/gitlab_slack_application.md) for the project. + +## Update the GitLab for Slack app + +Prerequisite: + +- You must be at least a [Slack workspace administrator](https://slack.com/help/articles/360018112273-Types-of-roles-in-Slack). + +When GitLab releases new features for the GitLab for Slack app, you might have to manually update your copy to use the new features. + +To update your copy of the GitLab for Slack app: + +- **In GitLab**: + + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. On the left sidebar, select **Settings > General**. + 1. Expand **GitLab for Slack app**. + 1. Select **Download latest manifest file** to download `slack_manifest.json`. + +- **In Slack**: + + 1. Go to [Slack API](https://api.slack.com/apps). + 1. Search for and select **GitLab (\<your host name\>)**. + 1. On the left sidebar, select **App Manifest**. + 1. Select the **JSON** tab to switch to a JSON view of the manifest. + 1. Copy the contents of the `slack_manifest.json` file you've downloaded from GitLab. + 1. Paste the contents into the JSON viewer to replace any existing contents. + 1. Select **Save Changes**. + +## Connectivity requirements + +To enable the GitLab for Slack app functionality, your network must allow inbound and outbound connections between GitLab and Slack. + +- For [Slack notifications](../../user/project/integrations/gitlab_slack_application.md#slack-notifications), the GitLab instance must be able to send requests to `https://slack.com`. +- For [Slash commands](../../user/project/integrations/gitlab_slack_application.md#slash-commands) and other features, the GitLab instance must be able to receive requests from `https://slack.com`. + +## Troubleshooting + +### Slash commands return `/gitlab failed with the error "dispatch_failed"` in Slack + +Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. To resolve this issue, ensure: + +- The GitLab for Slack app is properly [configured](#configure-the-settings), and the **Enable GitLab for Slack app** checkbox is selected. +- Your GitLab instance [allows requests to and from Slack](#connectivity-requirements). diff --git a/doc/administration/settings/terraform_limits.md b/doc/administration/settings/terraform_limits.md index 90ab1c25522..5ba8bfe63e0 100644 --- a/doc/administration/settings/terraform_limits.md +++ b/doc/administration/settings/terraform_limits.md @@ -19,10 +19,6 @@ To add a storage limit: 1. Select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Terraform limits**. -1. Adjust the size limit. +1. Enter a size limit in bytes. Set to `0` to allow files of unlimited size. -## Available settings - -| Setting | Default | Description | -|------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------| -| Terraform state size limit (bytes) | 0 | Terraform state files that exceed this size are not saved, and associated Terraform operations are rejected. Set to 0 to allow files of unlimited size. | +When Terraform state files exceed this limit, they are not saved, and associated Terraform operations are rejected. diff --git a/doc/administration/settings/usage_statistics.md b/doc/administration/settings/usage_statistics.md index ba15ee4e33e..f77298dd038 100644 --- a/doc/administration/settings/usage_statistics.md +++ b/doc/administration/settings/usage_statistics.md @@ -141,9 +141,11 @@ The method to disable Service Ping in the GitLab configuration file does not wor GitLab versions 9.3 to 13.12.3. For more information about how to disable it, see [troubleshooting](../../development/internal_analytics/service_ping/troubleshooting.md#cannot-disable-service-ping-with-the-configuration-file). To disable Service Ping and prevent it from being configured in the future through -the Admin Area: +the Admin Area. -**For installations using the Linux package:** +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb`: @@ -157,7 +159,7 @@ the Admin Area: sudo gitlab-ctl reconfigure ``` -**For installations from source:** +:::TabTitle Self-compiled (source) 1. Edit `/home/git/gitlab/config/gitlab.yml`: @@ -175,6 +177,8 @@ the Admin Area: sudo service gitlab restart ``` +::EndTabs + ## View the Service Ping payload You can view the exact JSON payload sent to GitLab Inc. in the Admin Area. To view the payload: @@ -205,7 +209,7 @@ To upload the payload manually: 1. Select **Download payload**. 1. Save the JSON file. 1. Visit [Service usage data center](https://version.gitlab.com/usage_data/new). -1. Select **Choose file** and choose the file from p5. +1. Select **Choose file**, then select the JSON file that contains the downloaded payload. 1. Select **Upload**. The uploaded file is encrypted and sent using secure HTTPS protocol. HTTPS creates a secure diff --git a/doc/administration/settings/user_and_ip_rate_limits.md b/doc/administration/settings/user_and_ip_rate_limits.md index 44bd08a8824..822ba4dd03e 100644 --- a/doc/administration/settings/user_and_ip_rate_limits.md +++ b/doc/administration/settings/user_and_ip_rate_limits.md @@ -143,7 +143,7 @@ GitLab. For example: 1. Set the environment variable `GITLAB_THROTTLE_BYPASS_HEADER`. - For [Linux package installations](https://docs.gitlab.com/omnibus/settings/environment-variables.html), set `'GITLAB_THROTTLE_BYPASS_HEADER' => 'Gitlab-Bypass-Rate-Limiting'` in `gitlab_rails['env']`. - - For source installations, set `export GITLAB_THROTTLE_BYPASS_HEADER=Gitlab-Bypass-Rate-Limiting` + - For self-compiled installations, set `export GITLAB_THROTTLE_BYPASS_HEADER=Gitlab-Bypass-Rate-Limiting` in `/etc/default/gitlab`. It is important that your load balancer erases or overwrites the bypass @@ -175,7 +175,7 @@ the allowlist configuration would be `1,53,217`. - For [Linux package installations](https://docs.gitlab.com/omnibus/settings/environment-variables.html), set `'GITLAB_THROTTLE_USER_ALLOWLIST' => '1,53,217'` in `gitlab_rails['env']`. -- For source installations, set `export GITLAB_THROTTLE_USER_ALLOWLIST=1,53,217` +- For self-compiled installations, set `export GITLAB_THROTTLE_USER_ALLOWLIST=1,53,217` in `/etc/default/gitlab`. Requests that bypassed the rate limiter because of the user allowlist diff --git a/doc/administration/sidekiq/extra_sidekiq_processes.md b/doc/administration/sidekiq/extra_sidekiq_processes.md index 3a522c7171d..d85eae7a7f6 100644 --- a/doc/administration/sidekiq/extra_sidekiq_processes.md +++ b/doc/administration/sidekiq/extra_sidekiq_processes.md @@ -11,7 +11,7 @@ at a higher rate on a single instance. By default, Sidekiq starts one worker process and only uses a single core. NOTE: -The information in this page applies only to Omnibus GitLab. +The information in this page applies only to Linux package installations. ## Start multiple processes diff --git a/doc/administration/sidekiq/index.md b/doc/administration/sidekiq/index.md index c3e1182cb05..10fadc40a82 100644 --- a/doc/administration/sidekiq/index.md +++ b/doc/administration/sidekiq/index.md @@ -82,7 +82,7 @@ By default, GitLab uses UNIX sockets and is not set up to communicate via TCP. T telnet <GitLab host> 6379 # Redis ``` -1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package +1. [Download and install](https://about.gitlab.com/install/) the Linux package using steps 1 and 2. **Do not complete any other steps.** 1. Copy the `/etc/gitlab/gitlab.rb` file from the GitLab instance and add the following settings. Make sure @@ -227,7 +227,6 @@ node than Sidekiq, follow the steps below. 1. Edit `/etc/gitlab/gitlab.rb`, and configure the registry URL: ```ruby - registry_external_url 'https://registry.example.com' gitlab_rails['registry_api_url'] = "https://registry.example.com" ``` diff --git a/doc/administration/sidekiq/sidekiq_memory_killer.md b/doc/administration/sidekiq/sidekiq_memory_killer.md index 63d93919129..01eda32ded0 100644 --- a/doc/administration/sidekiq/sidekiq_memory_killer.md +++ b/doc/administration/sidekiq/sidekiq_memory_killer.md @@ -13,10 +13,9 @@ for a certain amount of time. We use the same approach to the Sidekiq processes used by GitLab to process background jobs. -GitLab monitors the available RSS limit by default only for installations using -the Linux packages (Omnibus) or Docker. The reason for this is that GitLab -relies on runit to restart Sidekiq after a memory-induced shutdown, and GitLab -self-compiled or Helm chart based installations don't use runit or an equivalent tool. +GitLab monitors the available RSS limit by default only for Linux package or Docker installations. The reason for this +is that GitLab relies on runit to restart Sidekiq after a memory-induced shutdown, and self-compiled and Helm chart +installations don't use runit or an equivalent tool. With the default settings, Sidekiq restarts no more often than once every 15 minutes, with the restart causing about one @@ -24,7 +23,7 @@ minute of delay for incoming background jobs. Some background jobs rely on long-running external processes. To ensure these are cleanly terminated when Sidekiq is restarted, each Sidekiq process should be -run as a process group leader (for example, using `chpst -P`). If using Omnibus or the +run as a process group leader (for example, using `chpst -P`). If using a Linux package installation or the `bin/background_jobs` script with `runit` installed, this is handled for you. ## Configuring the limits diff --git a/doc/administration/sidekiq/sidekiq_troubleshooting.md b/doc/administration/sidekiq/sidekiq_troubleshooting.md index 6802bb68b31..9ae2a59251a 100644 --- a/doc/administration/sidekiq/sidekiq_troubleshooting.md +++ b/doc/administration/sidekiq/sidekiq_troubleshooting.md @@ -63,7 +63,7 @@ and delays before CI pipelines start running. Potential causes include: -- The GitLab instance may need more Sidekiq workers. By default, a single-node Omnibus GitLab +- The GitLab instance may need more Sidekiq workers. By default, a single-node Linux package installation runs one worker, restricting the execution of Sidekiq jobs to a maximum of one CPU core. [Read more about running multiple Sidekiq workers](extra_sidekiq_processes.md). @@ -105,7 +105,14 @@ Gather data on the state of the Sidekiq workers with the following Ruby script. If the performance issue is intermittent: - - Run this in a cron job every five minutes. Write the files to a location with enough space: allow for 500 KB per file. + - Run this in a cron job every five minutes. Write the files to a location with enough space: allow for at least 500 KB per file. + + ```shell + cat > /etc/cron.d/sidekiqcheck <<EOF + */5 * * * * root /opt/gitlab/bin/gitlab-rails runner /var/opt/gitlab/sidekiqcheck.rb > /tmp/sidekiqcheck_$(date '+\%Y\%m\%d-\%H:\%M').out 2>&1 + EOF + ``` + - Refer back to the data to see what went wrong. 1. Analyze the output. The following commands assume that you have a directory of output files. @@ -555,9 +562,9 @@ but if you want to clear the idempotency key immediately, follow the following s dj.delete! ``` -## Omnibus GitLab 14.0 and later: remove the `sidekiq-cluster` service +## GitLab 14.0 and later: remove the `sidekiq-cluster` service (Linux package installations) -Omnibus GitLab instances that were configured to run `sidekiq-cluster` prior to GitLab 14.0 +Linux package instances that were configured to run `sidekiq-cluster` prior to GitLab 14.0 might still have this service running along side `sidekiq` in later releases. The code to manage `sidekiq-cluster` was removed in GitLab 14.0. diff --git a/doc/administration/silent_mode/index.md b/doc/administration/silent_mode/index.md index 0b04654beaa..005add1d2f4 100644 --- a/doc/administration/silent_mode/index.md +++ b/doc/administration/silent_mode/index.md @@ -63,11 +63,15 @@ This section documents the current behavior of GitLab when Silent Mode is enable ### Service Desk -Incoming emails still raise issues, but the users who sent the emails to [Service Desk](../../user/project/service_desk.md) are not notified of issue creation or comments on their issues. +Incoming emails still raise issues, but the users who sent the emails to [Service Desk](../../user/project/service_desk/index.md) are not notified of issue creation or comments on their issues. ### Webhooks -[Project and group webhooks](../../user/project/integrations/webhooks.md), and [system hooks](../system_hooks.md) are suppressed. The relevant Sidekiq jobs fail 4 times and then disappear, while Silent Mode is enabled. [Issue 393639](https://gitlab.com/gitlab-org/gitlab/-/issues/393639) discusses preventing the Sidekiq jobs from running in the first place. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393639) in GitLab 16.3. + +[Project and group webhooks](../../user/project/integrations/webhooks.md) and [system hooks](../system_hooks.md) are suppressed. + +In GitLab 16.2 and earlier, webhooks were triggered when Silent Mode was enabled, but the [webhook HTTP request was blocked](#outbound-http-requests). Triggering webhook tests via the UI results in HTTP status 500 responses. diff --git a/doc/administration/smime_signing_email.md b/doc/administration/smime_signing_email.md index 5748c4d32d4..06bf4978a6b 100644 --- a/doc/administration/smime_signing_email.md +++ b/doc/administration/smime_signing_email.md @@ -65,7 +65,7 @@ For self-compiled installations: ca_certs_file: /etc/pki/smime/certs/gitlab_cas.crt ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect. The key must be readable by the GitLab system user (`git` by default). diff --git a/doc/administration/snippets/index.md b/doc/administration/snippets/index.md index 9b485140070..b59432b0b9e 100644 --- a/doc/administration/snippets/index.md +++ b/doc/administration/snippets/index.md @@ -5,47 +5,28 @@ group: Source Code 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" --- -# Snippets settings **(FREE SELF)** +# Snippets **(FREE SELF)** -Adjust the snippets' settings of your GitLab instance. - -## Snippets content size limit - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31133) in GitLab 12.6. - -You can set a maximum content size limit for snippets. This limit can prevent -abuse of the feature. The default value is **52428800 Bytes** (50 MB). - -### How does it work? - -The content size limit is applied when a snippet is created or updated. - -This limit doesn't affect existing snippets until they're updated and their +You can configure a maximum size for a snippet to prevent abuse. +The default limit is 52428800 bytes (50 MB). +The limit is applied when a snippet is created or updated. +The limit does not affect existing snippets unless they are updated and their content changes. -### Snippets size limit configuration +## Configure the snippet size limit -This setting is not available through the [Admin Area settings](../settings/index.md). -To configure this setting, use either the Rails console +To configure the snippet size limit, you can use the Rails console or the [Application settings API](../../api/settings.md). -NOTE: -The value of the limit **must** be in bytes. - -#### Through the Rails console +The limit **must** be in bytes. -The steps to configure this setting through the Rails console are: +This setting is not available in the [Admin Area settings](../settings/index.md). -1. Start the Rails console: +### Use the Rails console - ```shell - # For Omnibus installations - sudo gitlab-rails console - - # For installations from source - sudo -u git -H bundle exec rails console -e production - ``` +To configure this setting through the Rails console: +1. [Start the Rails console](../operations/rails_console.md#starting-a-rails-console-session). 1. Update the snippets maximum file size: ```ruby @@ -58,19 +39,23 @@ To retrieve the current value, start the Rails console and run: Gitlab::CurrentSettings.snippet_size_limit ``` -#### Through the API +### Use the API -To set the snippets size limit through the Application Settings API (similar to -[updating any other setting](../../api/settings.md#change-application-settings)), use this command: +To set the limit by using the Application Settings API +(similar to [updating any other setting](../../api/settings.md#change-application-settings)), +use this command: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings?snippet_size_limit=52428800" +curl --request PUT \ + --header "PRIVATE-TOKEN: <your_access_token>" + --url "https://gitlab.example.com/api/v4/application/settings?snippet_size_limit=52428800" ``` You can also use the API to [retrieve the current value](../../api/settings.md#get-current-application-settings). ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/application/settings" ``` ## Related topics diff --git a/doc/administration/static_objects_external_storage.md b/doc/administration/static_objects_external_storage.md index c7a22da38de..6b232ddc25f 100644 --- a/doc/administration/static_objects_external_storage.md +++ b/doc/administration/static_objects_external_storage.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# External storage for static objects **(FREE)** +# External storage for static objects **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31025) in GitLab 12.3. diff --git a/doc/administration/system_hooks.md b/doc/administration/system_hooks.md index dcacacaf47b..1c84d4fadb8 100644 --- a/doc/administration/system_hooks.md +++ b/doc/administration/system_hooks.md @@ -57,6 +57,7 @@ To create a system hook: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Admin Area**. 1. On the left sidebar, select **System Hooks**. +1. Select **Add new webhook**. 1. Provide the **URL** and **Secret Token**. 1. Select the checkbox next to each optional **Trigger** you want to enable. 1. Select **Enable SSL verification**, if desired. diff --git a/doc/administration/terraform_state.md b/doc/administration/terraform_state.md index 2b738f975ba..90b030e6e13 100644 --- a/doc/administration/terraform_state.md +++ b/doc/administration/terraform_state.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Terraform state administration **(FREE)** +# Terraform state administration **(FREE SELF)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 12.10. @@ -14,7 +14,7 @@ files. The files are encrypted before being stored. This feature is enabled by d The storage location of these files defaults to: - `/var/opt/gitlab/gitlab-rails/shared/terraform_state` for Linux package installations. -- `/home/git/gitlab/shared/terraform_state` for source installations. +- `/home/git/gitlab/shared/terraform_state` for self-compiled installations. These locations can be configured using the options described below. @@ -59,7 +59,7 @@ For self-compiled installations: enabled: false ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect. ## Using local storage @@ -88,7 +88,7 @@ For self-compiled installations: storage_path: /mnt/storage/terraform_state ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect. ## Using object storage **(FREE SELF)** @@ -102,8 +102,8 @@ This configuration relies on valid credentials to be configured already. The following settings are: -- Nested under `terraform_state:` and then `object_store:` on source installations. - Prefixed by `terraform_state_object_store_` on Linux package installations. +- Nested under `terraform_state:` and then `object_store:` on self-compiled installations. | Setting | Description | Default | |---------|-------------|---------| @@ -180,7 +180,9 @@ This section describes the earlier configuration format. See [the available connection settings for different providers](object_storage.md#configure-the-connection-settings). -**In Omnibus installations:** +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb` and add the following lines; replacing with the values you want: @@ -210,7 +212,7 @@ See [the available connection settings for different providers](object_storage.m 1. Save the file and [reconfigure GitLab](restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. 1. [Migrate any existing local states to the object storage](#migrate-to-object-storage) -**In installations from source:** +:::TabTitle Self-compiled (source) 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines: @@ -228,5 +230,7 @@ See [the available connection settings for different providers](object_storage.m region: eu-central-1 ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect. 1. [Migrate any existing local states to the object storage](#migrate-to-object-storage) + +::EndTabs diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index f164e8ccbad..00e56568a1b 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -40,7 +40,7 @@ This content has been converted to a Rake task, see [verify database values can ### Transfer mirror users and tokens to a single service account -This content has been moved to [Troubleshooting Repository mirroring](../../user/project/repository/mirror/index.md#transfer-mirror-users-and-tokens-to-a-single-service-account-in-rails-console). +This content has been moved to [Troubleshooting Repository mirroring](../../user/project/repository/mirror/troubleshooting.md#transfer-mirror-users-and-tokens-to-a-single-service-account-in-rails-console). ## Merge requests diff --git a/doc/administration/troubleshooting/postgresql.md b/doc/administration/troubleshooting/postgresql.md index 88e0d4e6c6b..53bde005232 100644 --- a/doc/administration/troubleshooting/postgresql.md +++ b/doc/administration/troubleshooting/postgresql.md @@ -26,7 +26,7 @@ This section is for links to information elsewhere in the GitLab documentation. - [Connect to the PostgreSQL console](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database). -- [Omnibus database procedures](https://docs.gitlab.com/omnibus/settings/database.html) including: +- [Database procedures for Linux package installations](https://docs.gitlab.com/omnibus/settings/database.html) including: - SSL: enabling, disabling, and verifying. - Enabling Write Ahead Log (WAL) archiving. - Using an external (non-Omnibus) PostgreSQL installation; and backing it up. @@ -44,7 +44,7 @@ This section is for links to information elsewhere in the GitLab documentation. - Consuming PostgreSQL from [within CI runners](../../ci/services/postgres.md). -- Managing Omnibus PostgreSQL versions [from the development docs](https://docs.gitlab.com/omnibus/development/managing-postgresql-versions.html). +- Managing PostgreSQL versions on Linux package installations [from the development docs](https://docs.gitlab.com/omnibus/development/managing-postgresql-versions.html). - [PostgreSQL scaling](../postgresql/replication_and_failover.md) - Including [troubleshooting](../postgresql/replication_and_failover.md#troubleshooting) @@ -107,7 +107,7 @@ PostgreSQL defaults: Comments in issue [#30528](https://gitlab.com/gitlab-org/gitlab/-/issues/30528) indicate that these should both be set to at least a number of minutes for all -Omnibus GitLab installations (so they don't hang indefinitely). However, 15 s +Linux package installations (so they don't hang indefinitely). However, 15 s for `statement_timeout` is very short, and is only effective if the underlying infrastructure is very performant. @@ -138,7 +138,8 @@ postgresql['idle_in_transaction_session_timeout'] = '60s' Once saved, [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. NOTE: -These are Omnibus GitLab settings. If an external database, such as a customer's PostgreSQL installation or Amazon RDS is being used, these values don't get set, and would have to be set externally. +These are Linux package settings. If an external database, such as a customer's PostgreSQL installation +or Amazon RDS is being used, these values don't get set, and would have to be set externally. ### Temporarily changing the statement timeout @@ -211,10 +212,8 @@ To resolve the error, run `VACUUM` manually: ### GitLab database requirements -The [database requirements](../../install/requirements.md#database) for GitLab include: - -- Support for MySQL was removed in [GitLab 12.1](../../update/index.md#1210). -- Review and install the [required extension list](../../install/postgresql_extensions.md). +See [database requirements](../../install/requirements.md#database) and review and install the +[required extension list](../../install/postgresql_extensions.md). ### Serialization errors in the `production/sidekiq` log diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index d8f82f13875..6259304d68e 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -52,7 +52,7 @@ _The uploads are stored by default in base_dir: uploads ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect. ## Using object storage **(FREE SELF)** @@ -134,5 +134,5 @@ _The uploads are stored by default in region: eu-central-1 ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect. 1. Migrate any existing local uploads to the object storage with the [`gitlab:uploads:migrate:all` Rake task](raketasks/uploads/migrate.md). diff --git a/doc/administration/user_settings.md b/doc/administration/user_settings.md index f480f05f6a2..43e88bf6eac 100644 --- a/doc/administration/user_settings.md +++ b/doc/administration/user_settings.md @@ -38,7 +38,7 @@ For self-compiled installations: # default_can_create_group: false # default: true ``` -1. [Restart GitLab](restart_gitlab.md#installations-from-source). +1. [Restart GitLab](restart_gitlab.md#self-compiled-installations). ### Prevent existing users from creating top-level groups @@ -70,4 +70,4 @@ For self-compiled installations: # username_changing_enabled: false # default: true - User can change their username/namespace ``` -1. [Restart GitLab](restart_gitlab.md#installations-from-source). +1. [Restart GitLab](restart_gitlab.md#self-compiled-installations). diff --git a/doc/administration/whats-new.md b/doc/administration/whats-new.md index b34b054d87c..8e1fc412a62 100644 --- a/doc/administration/whats-new.md +++ b/doc/administration/whats-new.md @@ -4,7 +4,7 @@ group: unassigned info: For assistance with this What's new page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- -# What's new **(FREE)** +# What's new **(FREE ALL)** You can view some of the highlights from the last 10 GitLab versions in the **What's new** feature. It lists new features available in different diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index 8f8f6881162..341cb768154 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -4,7 +4,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" --- -# Group and project access requests API **(FREE)** +# Group and project access requests API **(FREE ALL)** ## Valid access levels diff --git a/doc/api/alert_management_alerts.md b/doc/api/alert_management_alerts.md index c4293cc76f1..5da77d08605 100644 --- a/doc/api/alert_management_alerts.md +++ b/doc/api/alert_management_alerts.md @@ -4,7 +4,7 @@ group: Respond 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 --- -# Alert Management alerts API **(FREE)** +# Alert Management alerts API **(FREE ALL)** The Alert Management alerts API is limited to metric images. For more API endpoints, see the [GraphQL API](graphql/reference/index.md#alertmanagementalert). diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index a97e4ad8adb..5b918fa50ab 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# REST API resources **(FREE)** +# REST API resources **(FREE ALL)** Available resources for the [GitLab REST API](index.md) can be grouped in the following contexts: @@ -44,6 +44,7 @@ The following API resources are available in the project context: | [Environments](environments.md) | `/projects/:id/environments` | | [Error Tracking](error_tracking.md) | `/projects/:id/error_tracking/settings` | | [Events](events.md) | `/projects/:id/events` (also available for users and standalone) | +| [External status checks](status_checks.md) | `/projects/:id/external_status_checks` | | [Feature flag User Lists](feature_flag_user_lists.md) | `/projects/:id/feature_flags_user_lists` | | [Feature flags](feature_flags.md) | `/projects/:id/feature_flags` | | [Freeze Periods](freeze_periods.md) | `/projects/:id/freeze_periods` | @@ -60,7 +61,6 @@ The following API resources are available in the project context: | [Jobs](jobs.md) | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs` | | [Jobs Artifacts](job_artifacts.md) | `/projects/:id/jobs/:job_id/artifacts` | | [Labels](labels.md) | `/projects/:id/labels` | -| [Managed licenses](managed_licenses.md) **(ULTIMATE)** | `/projects/:id/managed_licenses` | | [Maven repository](packages/maven.md) | `/projects/:id/packages/maven` (also available for groups and standalone) | | [Members](members.md) | `/projects/:id/members` (also available for groups) | | [Merge request approvals](merge_request_approvals.md) **(PREMIUM)** | `/projects/:id/approvals`, `/projects/:id/merge_requests/.../approvals` | diff --git a/doc/api/applications.md b/doc/api/applications.md index 53ea2f51d1a..f597e1acc44 100644 --- a/doc/api/applications.md +++ b/doc/api/applications.md @@ -4,7 +4,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 --- -# Applications API **(FREE)** +# Applications API **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8160) in GitLab 10.5. diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md index 89e89366de5..714c79c42c5 100644 --- a/doc/api/audit_events.md +++ b/doc/api/audit_events.md @@ -4,7 +4,7 @@ group: Compliance 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 --- -# Audit Events API **(PREMIUM)** +# Audit Events API **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/121) in GitLab 12.4. > - [Author Email added to the response body](https://gitlab.com/gitlab-org/gitlab/-/issues/386322) in GitLab 15.9. @@ -18,18 +18,19 @@ To retrieve audit events using the API, you must [authenticate yourself](rest/in ### Retrieve all instance audit events -> Support for keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367528) in GitLab 15.11. +> - Support for keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367528) in GitLab 15.11. +> - Entity type `Gitlab::Audit::InstanceScope` for instance audit events [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418185) in GitLab 16.2. ```plaintext GET /audit_events ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `created_after` | string | no | Return audit events created on or after the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | -| `created_before` | string | no | Return audit events created on or before the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | -| `entity_type` | string | no | Return audit events for the given entity type. Valid values are: `User`, `Group`, or `Project`. | -| `entity_id` | integer | no | Return audit events for the given entity ID. Requires `entity_type` attribute to be present. | +| Attribute | Type | Required | Description | +| --------- | ---- | -------- |-----------------------------------------------------------------------------------------------------------------| +| `created_after` | string | no | Return audit events created on or after the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | +| `created_before` | string | no | Return audit events created on or before the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | +| `entity_type` | string | no | Return audit events for the given entity type. Valid values are: `User`, `Group`, `Project`, or `Gitlab::Audit::InstanceScope`. | +| `entity_id` | integer | no | Return audit events for the given entity ID. Requires `entity_type` attribute to be present. | This endpoint supports both offset-based and [keyset-based](rest/index.md#keyset-based-pagination) pagination. You should use keyset-based pagination when requesting consecutive pages of results. @@ -96,6 +97,30 @@ Example response: "entity_path": "Andreas" }, "created_at": "2019-08-22T16:34:25.639Z" + }, + { + "id": 4, + "author_id": 43, + "entity_id": 1, + "entity_type": "Gitlab::Audit::InstanceScope", + "details": { + "author_name": "Administrator", + "author_class": "User", + "target_id": 32, + "target_type": "AuditEvents::Streaming::InstanceHeader", + "target_details": "unknown", + "custom_message": "Created custom HTTP header with key X-arg.", + "ip_address": "127.0.0.1", + "entity_path": "gitlab_instance" + }, + "ip_address": "127.0.0.1", + "author_name": "Administrator", + "entity_path": "gitlab_instance", + "target_details": "unknown", + "created_at": "2023-08-01T11:29:44.764Z", + "target_type": "AuditEvents::Streaming::InstanceHeader", + "target_id": 32, + "event_type": "audit_events_streaming_instance_headers_create" } ] ``` diff --git a/doc/api/avatar.md b/doc/api/avatar.md index d6b9c9f70b7..68031a05f43 100644 --- a/doc/api/avatar.md +++ b/doc/api/avatar.md @@ -4,7 +4,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 --- -# Avatar API **(FREE)** +# Avatar API **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19121) in GitLab 11.0. diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md index 2ff71a088e6..2591c6ea490 100644 --- a/doc/api/award_emoji.md +++ b/doc/api/award_emoji.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/product/ux/technical-writing/#assignments --- -# Emoji reactions API **(FREE)** +# Emoji reactions API **(FREE ALL)** > [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409884) from "award emoji" to "emoji reactions" in GitLab 16.0. diff --git a/doc/api/boards.md b/doc/api/boards.md index 00ab9a7b9cb..2438508f2f9 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.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/product/ux/technical-writing/#assignments --- -# Project issue boards API **(FREE)** +# Project issue boards API **(FREE ALL)** Every API call to [issue boards](../user/project/issue_board.md) must be authenticated. diff --git a/doc/api/branches.md b/doc/api/branches.md index fa508292e5c..b925d3ddadf 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Branches API **(FREE)** +# Branches API **(FREE ALL)** This API operates on [repository branches](../user/project/repository/branches/index.md). diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md index 9dbae6f5727..35afd2ad164 100644 --- a/doc/api/broadcast_messages.md +++ b/doc/api/broadcast_messages.md @@ -16,7 +16,7 @@ As of GitLab 12.8, GET requests do not require authentication. All other broadca - Guests result in `401 Unauthorized`. - Regular users result in `403 Forbidden`. -## Get all broadcast messages **(FREE)** +## Get all broadcast messages **(FREE ALL)** List all broadcast messages. @@ -49,7 +49,7 @@ Example response: ] ``` -## Get a specific broadcast message **(FREE)** +## Get a specific broadcast message **(FREE ALL)** Get a specific broadcast message. diff --git a/doc/api/bulk_imports.md b/doc/api/bulk_imports.md index 65a3ff71b8e..ec1a7d44253 100644 --- a/doc/api/bulk_imports.md +++ b/doc/api/bulk_imports.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Group and project migration by direct transfer API **(FREE)** +# Group and project migration by direct transfer API **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64335) in GitLab 14.1. > - Project migration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390515) in GitLab 15.11. @@ -43,9 +43,10 @@ POST /bulk_imports | `entities` | Array | yes | List of entities to import. | | `entities[source_type]` | String | yes | Source entity type. Valid values are `group_entity` (GitLab 14.2 and later) and `project_entity` (GitLab 15.11 and later). | | `entities[source_full_path]` | String | yes | Source full path of the entity to import. | -| `entities[destination_name]` | String | yes | Deprecated: Use :destination_slug instead. Destination slug for the entity. | | `entities[destination_slug]` | String | yes | Destination slug for the entity. | +| `entities[destination_name]` | String | no | Deprecated: Use `destination_slug` instead. Destination slug for the entity. | | `entities[destination_namespace]` | String | yes | Destination namespace for the entity. | +| `entities[migrate_projects]` | Boolean | no | Also import all nested projects of the group (if `source_type` is `group_entity`). Defaults to `true`. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/bulk_imports" \ diff --git a/doc/api/cluster_agents.md b/doc/api/cluster_agents.md index 5abdece3909..552c549e3b9 100644 --- a/doc/api/cluster_agents.md +++ b/doc/api/cluster_agents.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Agents API **(FREE)** +# Agents API **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83270) in GitLab 14.10. > - Agent Tokens API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347046) in GitLab 15.0. diff --git a/doc/api/code_suggestions.md b/doc/api/code_suggestions.md index 8057686897f..528f7db067b 100644 --- a/doc/api/code_suggestions.md +++ b/doc/api/code_suggestions.md @@ -34,7 +34,8 @@ Example response: ## Generate code completions (Experiment) -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415581) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `code_suggestions_completion_api`. Disabled by default. This feature is an Experiment. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415581) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `code_suggestions_completion_api`. Disabled by default. This feature is an Experiment. +> - Requirement to generate a JWT before calling this endpoint was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127863) in GitLab 16.3. FLAG: On self-managed GitLab, by default this feature is not available. @@ -49,10 +50,8 @@ POST /code_suggestions/completions Requests to this endpoint are proxied directly to the [model gateway](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist#completions). The documentation for the endpoint is currently the SSoT for named parameters. -Authentication to this endpoint requires both a GitLab access token and a Code Suggestions JWT. The access token is used to authenticate the user and the JWT is used to authenticate the request to the model gateway. - ```shell -curl --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>" --header "X-Gitlab-Oidc-Token: <TOKEN_GENERATED_FROM_TOKENS_ENDPOINT>" --data "<JSON_BODY>" https://gitlab.example.com/api/v4/code_suggestions/completions +curl --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>" --data "<JSON_BODY>" https://gitlab.example.com/api/v4/code_suggestions/completions ``` Example body: diff --git a/doc/api/commits.md b/doc/api/commits.md index 7c4d15e5d80..cd955717e39 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Commits API **(FREE)** +# Commits API **(FREE ALL)** This API operates on [repository commits](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository). Read more about [GitLab-specific information](../user/project/repository/index.md#commit-changes-to-a-repository) for commits. diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index 5fc4cb138a1..901b0b93529 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -4,11 +4,11 @@ group: Container Registry 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 --- -# Container Registry API **(FREE)** +# Container Registry API **(FREE ALL)** > The use of `CI_JOB_TOKEN` scoped to the current project was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49750) in GitLab 13.12. -This is the API documentation of the [GitLab Container Registry](../user/packages/container_registry/index.md). +This API documentation is about the [GitLab Container Registry](../user/packages/container_registry/index.md). When the `ci_job_token_scope` feature flag is enabled (it is **disabled by default**), you can use the below endpoints from a CI/CD job, by passing the `$CI_JOB_TOKEN` variable as the `JOB-TOKEN` header. @@ -51,7 +51,7 @@ If the project is public, the Container Registry is also public. If the project private, the Container Registry is also internal or private. - **private**: The Container Registry is visible only to project members with Reporter role or -higher. This is similar to the behavior of a private project with Container Registry visibility set +higher. This behavior is similar to that of a private project with Container Registry visibility set to **enabled**. - **disabled**: The Container Registry is disabled. @@ -380,34 +380,45 @@ To schedule tags for automatic deletion, use a [cleanup policy](../user/packages Examples: -1. Remove tag names that are matching the regex (Git SHA), keep always at least 5, - and remove ones that are older than 2 days: +- Remove tag names that are matching the regex (Git SHA), keep always at least 5, + and remove ones that are older than 2 days: - ```shell - curl --request DELETE --data 'name_regex_delete=[0-9a-z]{40}' --data 'keep_n=5' --data 'older_than=2d' \ - --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" - ``` + ```shell + curl --request DELETE --data 'name_regex_delete=[0-9a-z]{40}' --data 'keep_n=5' --data 'older_than=2d' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" + ``` -1. Remove all tags, but keep always the latest 5: +- Remove all tags, but keep always the latest 5: - ```shell - curl --request DELETE --data 'name_regex_delete=.*' --data 'keep_n=5' \ - --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" - ``` + ```shell + curl --request DELETE --data 'name_regex_delete=.*' --data 'keep_n=5' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" + ``` -1. Remove all tags, but keep always tags beginning with `stable`: +- Remove all tags, but keep always tags beginning with `stable`: - ```shell - curl --request DELETE --data 'name_regex_delete=.*' --data 'name_regex_keep=stable.*' \ - --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" - ``` + ```shell + curl --request DELETE --data 'name_regex_delete=.*' --data 'name_regex_keep=stable.*' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" + ``` -1. Remove all tags that are older than 1 month: +- Remove all tags that are older than 1 month: - ```shell - curl --request DELETE --data 'name_regex_delete=.*' --data 'older_than=1month' \ - --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" - ``` + ```shell + curl --request DELETE --data 'name_regex_delete=.*' --data 'older_than=1month' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" + ``` + +### Use cURL with a regular expression that contains `+` + +When using cURL, the `+` character in regular expressions must be +[URL-encoded](https://curl.se/docs/manpage.html#--data-urlencode), +to be processed correctly by the GitLab Rails backend. For example: + +```shell +curl --request DELETE --data-urlencode 'name_regex_delete=dev-.+' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" +``` ## Instance-wide endpoints diff --git a/doc/api/dependencies.md b/doc/api/dependencies.md index 23eed014bc0..388ea3c71fc 100644 --- a/doc/api/dependencies.md +++ b/doc/api/dependencies.md @@ -4,7 +4,7 @@ group: Composition Analysis 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 --- -# Dependencies API **(ULTIMATE)** +# Dependencies API **(ULTIMATE ALL)** WARNING: This API is in an [Experiment](../policy/experiment-beta-support.md#experiment) and considered unstable. diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md index 53b4b0db0d7..1ffd959d18d 100644 --- a/doc/api/dependency_proxy.md +++ b/doc/api/dependency_proxy.md @@ -4,7 +4,7 @@ group: Container Registry 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 --- -# Dependency Proxy API **(FREE)** +# Dependency Proxy API **(FREE ALL)** ## Purge the dependency proxy for a group diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index 003a5963ada..3d5fa092416 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Deploy keys API **(FREE)** +# Deploy keys API **(FREE ALL)** The deploy keys API can return in responses fingerprints of the public key in the following fields: diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index ec9da949e48..bc0cee1d627 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Deploy Tokens API **(FREE)** +# Deploy Tokens API **(FREE ALL)** ## List all deploy tokens **(FREE SELF)** diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 9ef75741142..aad3567879a 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Deployments API **(FREE)** +# Deployments API **(FREE ALL)** > Support for [GitLab CI/CD job token](../ci/jobs/ci_job_token.md) authentication [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414549) in GitLab 16.2. @@ -530,7 +530,7 @@ It supports the same parameters as the [Merge Requests API](merge_requests.md#li curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/42/merge_requests" ``` -## Approve or reject a blocked deployment **(PREMIUM)** +## Approve or reject a blocked deployment **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343864) in GitLab 14.7 [with a flag](../administration/feature_flags.md) named `deployment_approvals`. Disabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/347342) in GitLab 14.8. diff --git a/doc/api/discussions.md b/doc/api/discussions.md index 15bbc802817..6b475473790 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, api --- -# Discussions API **(FREE)** +# Discussions API **(FREE ALL)** Discussions are a set of related notes on: @@ -458,7 +458,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636" ``` -## Epics **(ULTIMATE)** +## Epics **(ULTIMATE ALL)** ### List group epic discussion items diff --git a/doc/api/dora/metrics.md b/doc/api/dora/metrics.md index d30194c3da0..1af21e84f5e 100644 --- a/doc/api/dora/metrics.md +++ b/doc/api/dora/metrics.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, api --- -# DevOps Research and Assessment (DORA) key metrics API **(ULTIMATE)** +# DevOps Research and Assessment (DORA) key metrics API **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab 13.10. > - The legacy key/value pair `{ "<date>" => "<value>" }` was removed from the payload in GitLab 14.0. diff --git a/doc/api/draft_notes.md b/doc/api/draft_notes.md index e532de6a502..3f4ea46f00d 100644 --- a/doc/api/draft_notes.md +++ b/doc/api/draft_notes.md @@ -4,7 +4,7 @@ group: Code Review 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 --- -# Draft Notes API **(FREE)** +# Draft Notes API **(FREE ALL)** Draft notes are pending, unpublished comments on merge requests. They can be either start a discussion, or be associated with an existing discussion as a reply. They are viewable only by the author until they are published. @@ -102,14 +102,28 @@ Create a draft note for a given merge request. POST /projects/:id/merge_requests/:merge_request_iid/draft_notes ``` -| Attribute | Type | Required | Description | -| --------------------------- | ----------------- | ----------- | --------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). -| `merge_request_iid` | integer | yes | The IID of a project merge request. -| `note` | string | yes | The content of a note. -| `commit_id` | string | no | The SHA of a commit to associate the draft note to. -| `in_reply_to_discussion_id` | integer | no | The ID of a discussion the draft note replies to. -| `resolve_discussion` | boolean | no | The associated discussion should be resolved. +| Attribute | Type | Required | Description | +| ---------------------------------------- | ----------------- | ----------- | --------------------- | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). +| `merge_request_iid` | integer | yes | The IID of a project merge request. +| `note` | string | yes | The content of a note. +| `commit_id` | string | no | The SHA of a commit to associate the draft note to. +| `in_reply_to_discussion_id` | string | no | The ID of a discussion the draft note replies to. +| `resolve_discussion` | boolean | no | The associated discussion should be resolved. +| `position[base_sha]` | string | yes | Base commit SHA in the source branch. | +| `position[head_sha]` | string | yes | SHA referencing HEAD of this merge request. | +| `position[start_sha]` | string | yes | SHA referencing commit in target branch. | +| `position[new_path]` | string | yes (if the position type is `text`) | File path after change. | +| `position[old_path]` | string | yes (if the position type is `text`) | File path before change. | +| `position[position_type]` | string | yes | Type of the position reference. Allowed values: `text` or `image`. | +| `position` | hash | no | Position when creating a diff note. | +| `position[new_line]` | integer | no | For `text` diff notes, the line number after change. | +| `position[old_line]` | integer | no | For `text` diff notes, the line number before change. | +| `position[line_range]` | hash | no | Line range for a multi-line diff note. | +| `position[width]` | integer | no | For `image` diff notes, width of the image. | +| `position[height]` | integer | no | For `image` diff notes, height of the image. | +| `position[x]` | float | no | For `image` diff notes, X coordinate. | +| `position[y]` | float | no | For `image` diff notes, Y coordinate. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes?note=note @@ -123,12 +137,26 @@ Modify a draft note for a given merge request. PUT /projects/:id/merge_requests/:merge_request_iid/draft_notes/:draft_note_id ``` -| Attribute | Type | Required | Description | -| ------------------- | ----------------- | ----------- | --------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). -| `draft_note_id` | integer | yes | The ID of a draft note. -| `merge_request_iid` | integer | yes | The IID of a project merge request. -| `note` | string | no | The content of a note. +| Attribute | Type | Required | Description | +| ------------------- | ----------------- | ----------- | --------------------- | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). +| `draft_note_id` | integer | yes | The ID of a draft note. +| `merge_request_iid` | integer | yes | The IID of a project merge request. +| `note` | string | no | The content of a note. +| `position[base_sha]` | string | yes | Base commit SHA in the source branch. | +| `position[head_sha]` | string | yes | SHA referencing HEAD of this merge request. | +| `position[start_sha]` | string | yes | SHA referencing commit in target branch. | +| `position[new_path]` | string | yes (if the position type is `text`) | File path after change. | +| `position[old_path]` | string | yes (if the position type is `text`) | File path before change. | +| `position[position_type]` | string | yes | Type of the position reference. Allowed values: `text` or `image`. | +| `position` | hash | no | Position when creating a diff note. | +| `position[new_line]` | integer | no | For `text` diff notes, the line number after change. | +| `position[old_line]` | integer | no | For `text` diff notes, the line number before change. | +| `position[line_range]` | hash | no | Line range for a multi-line diff note. | +| `position[width]` | integer | no | For `image` diff notes, width of the image. | +| `position[height]` | integer | no | For `image` diff notes, height of the image. | +| `position[x]` | float | no | For `image` diff notes, X coordinate. | +| `position[y]` | float | no | For `image` diff notes, Y coordinate. | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5" diff --git a/doc/api/environments.md b/doc/api/environments.md index 87f99bc9034..1cecf61e8df 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Environments API **(FREE)** +# Environments API **(FREE ALL)** > Support for [GitLab CI/CD job token](../ci/jobs/ci_job_token.md) authentication [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414549) in GitLab 16.2. diff --git a/doc/api/epic_issues.md b/doc/api/epic_issues.md index 506d6d4b339..1b22447da97 100644 --- a/doc/api/epic_issues.md +++ b/doc/api/epic_issues.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Epic Issues API **(PREMIUM)** +# Epic Issues API **(PREMIUM ALL)** Every API call to the epic issues API endpoint must be authenticated. diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md index f46fa8e0989..aa88aa563e7 100644 --- a/doc/api/epic_links.md +++ b/doc/api/epic_links.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Epic Links API **(ULTIMATE)** +# Epic Links API **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9188) in GitLab 11.8. diff --git a/doc/api/epics.md b/doc/api/epics.md index 3d8e19a6e99..d80cc0efab8 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Epics API **(PREMIUM)** +# Epics API **(PREMIUM ALL)** > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2. > - Single-level Epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md index 9037c1b58d2..0858e105a1f 100644 --- a/doc/api/error_tracking.md +++ b/doc/api/error_tracking.md @@ -4,7 +4,7 @@ group: Observability 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 --- -# Error Tracking settings API **(FREE)** +# Error Tracking settings API **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34940) in GitLab 12.7. diff --git a/doc/api/events.md b/doc/api/events.md index 493f8f43bfd..9889e8d7701 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -4,7 +4,7 @@ group: Compliance 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 --- -# Events API **(FREE)** +# Events API **(FREE ALL)** ## Filter parameters diff --git a/doc/api/feature_flag_user_lists.md b/doc/api/feature_flag_user_lists.md index 0152ec62c7f..39c5f298be4 100644 --- a/doc/api/feature_flag_user_lists.md +++ b/doc/api/feature_flag_user_lists.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Feature flag user lists API **(FREE)** +# Feature flag user lists API **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205409) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to GitLab Free in 13.5. diff --git a/doc/api/feature_flags.md b/doc/api/feature_flags.md index e83bb2eb300..d7bf4fe826e 100644 --- a/doc/api/feature_flags.md +++ b/doc/api/feature_flags.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Feature flags API **(FREE)** +# Feature flags API **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in GitLab Premium 12.5. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to GitLab Free in 13.5. diff --git a/doc/api/freeze_periods.md b/doc/api/freeze_periods.md index c2cf2d84056..55a083ae9a7 100644 --- a/doc/api/freeze_periods.md +++ b/doc/api/freeze_periods.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Freeze Periods API **(FREE)** +# Freeze Periods API **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29382) in GitLab 13.0. diff --git a/doc/api/graphql/audit_report.md b/doc/api/graphql/audit_report.md index bad6a7a1e83..dbe5681028b 100644 --- a/doc/api/graphql/audit_report.md +++ b/doc/api/graphql/audit_report.md @@ -4,7 +4,7 @@ group: Compliance 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 --- -# Set up an Audit Report with GraphQL **(FREE)** +# Set up an Audit Report with GraphQL **(FREE ALL)** This page describes how you can use the GraphiQL explorer to set up an audit report for a specific subset of users. diff --git a/doc/api/graphql/branch_rules.md b/doc/api/graphql/branch_rules.md index 5709ce9fafb..f0c4dc308b7 100644 --- a/doc/api/graphql/branch_rules.md +++ b/doc/api/graphql/branch_rules.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# List branch rules for a project **(FREE)** +# List branch rules for a project **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106954) in GitLab 15.8. diff --git a/doc/api/graphql/custom_emoji.md b/doc/api/graphql/custom_emoji.md index c39ac955c01..a0a329ca4b5 100644 --- a/doc/api/graphql/custom_emoji.md +++ b/doc/api/graphql/custom_emoji.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/product/ux/technical-writing/#assignments --- -# Use custom emoji with GraphQL **(FREE)** +# Use custom emoji with GraphQL **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37911) in GitLab 13.6 [with a flag](../../administration/feature_flags.md) named `custom_emoji`. Disabled by default. > - Enabled on GitLab.com in GitLab 14.0. diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index 5142496753c..52592f943fc 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Run GraphQL API queries and mutations **(FREE)** +# Run GraphQL API queries and mutations **(FREE ALL)** This guide demonstrates basic usage of the GitLab GraphQL API. diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 9a78d43ff4b..36f16ff9141 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# GraphQL API **(FREE)** +# GraphQL API **(FREE ALL)** > Enabled and [made generally available](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) in GitLab 12.1. [Feature flag `graphql`](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) removed. diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 425a2b7e980..c9fc446303f 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Please do not edit this file directly, check compile_docs task on lib/tasks/gitlab/graphql.rake. ---> -# GraphQL API Resources +# GraphQL API resources This documentation is self-generated based on GitLab current GraphQL schema. @@ -36,6 +36,42 @@ in [Removed Items](../removed_items.md). The `Query` type contains the API's top-level entry points for all executable queries. +### `Query.abuseReport` + +Find an abuse report. + +WARNING: +**Introduced** in 16.3. +This feature is an Experiment. It can be changed or removed at any time. + +Returns [`AbuseReport`](#abusereport). + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="queryabusereportid"></a>`id` | [`AbuseReportID!`](#abusereportid) | ID of the abuse report. | + +### `Query.abuseReportLabels` + +Abuse report labels. + +WARNING: +**Introduced** in 16.3. +This feature is an Experiment. It can be changed or removed at any time. + +Returns [`LabelConnection`](#labelconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="queryabusereportlabelssearchterm"></a>`searchTerm` | [`String`](#string) | Search term to find labels with. | + ### `Query.aiMessages` Find AI messages. @@ -783,6 +819,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="queryvulnerabilitiesclusteragentid"></a>`clusterAgentId` | [`[ClustersAgentID!]`](#clustersagentid) | Filter vulnerabilities by `cluster_agent_id`. Vulnerabilities with a `reportType` of `cluster_image_scanning` are only included with this filter. | | <a id="queryvulnerabilitiesclusterid"></a>`clusterId` | [`[ClustersClusterID!]`](#clustersclusterid) | Filter vulnerabilities by `cluster_id`. Vulnerabilities with a `reportType` of `cluster_image_scanning` are only included with this filter. | +| <a id="queryvulnerabilitiesdismissalreason"></a>`dismissalReason` | [`[VulnerabilityDismissalReason!]`](#vulnerabilitydismissalreason) | Filter by dismissal reason. Only dismissed Vulnerabilities will be included with the filter. | | <a id="queryvulnerabilitieshasissues"></a>`hasIssues` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have linked issues. | | <a id="queryvulnerabilitieshasresolution"></a>`hasResolution` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have been resolved on default branch. | | <a id="queryvulnerabilitiesimage"></a>`image` | [`[String!]`](#string) | Filter vulnerabilities by location image. When this filter is present, the response only matches entries for a `reportType` that includes `container_scanning`, `cluster_image_scanning`. | @@ -1226,7 +1263,7 @@ Input type: `AuditEventsStreamingDestinationEventsRemoveInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationauditeventsstreamingdestinationeventsremoveclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationauditeventsstreamingdestinationeventsremovedestinationid"></a>`destinationId` | [`AuditEventsExternalAuditEventDestinationID!`](#auditeventsexternalauditeventdestinationid) | Destination URL. | +| <a id="mutationauditeventsstreamingdestinationeventsremovedestinationid"></a>`destinationId` | [`AuditEventsExternalAuditEventDestinationID!`](#auditeventsexternalauditeventdestinationid) | Destination id. | | <a id="mutationauditeventsstreamingdestinationeventsremoveeventtypefilters"></a>`eventTypeFilters` | [`[String!]!`](#string) | List of event type filters to remove from streaming. | #### Fields @@ -1256,6 +1293,25 @@ Input type: `AuditEventsStreamingDestinationInstanceEventsAddInput` | <a id="mutationauditeventsstreamingdestinationinstanceeventsadderrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationauditeventsstreamingdestinationinstanceeventsaddeventtypefilters"></a>`eventTypeFilters` | [`[String!]`](#string) | List of event type filters for the audit event external destination. | +### `Mutation.auditEventsStreamingDestinationInstanceEventsRemove` + +Input type: `AuditEventsStreamingDestinationInstanceEventsRemoveInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationauditeventsstreamingdestinationinstanceeventsremoveclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationauditeventsstreamingdestinationinstanceeventsremovedestinationid"></a>`destinationId` | [`AuditEventsInstanceExternalAuditEventDestinationID!`](#auditeventsinstanceexternalauditeventdestinationid) | Destination id. | +| <a id="mutationauditeventsstreamingdestinationinstanceeventsremoveeventtypefilters"></a>`eventTypeFilters` | [`[String!]!`](#string) | List of event type filters to remove from streaming. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationauditeventsstreamingdestinationinstanceeventsremoveclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationauditeventsstreamingdestinationinstanceeventsremoveerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.auditEventsStreamingHeadersCreate` Input type: `AuditEventsStreamingHeadersCreateInput` @@ -1392,7 +1448,7 @@ Input type: `AwardEmojiAddInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationawardemojiaddawardemoji"></a>`awardEmoji` | [`AwardEmoji`](#awardemoji) | Award emoji after mutation. | +| <a id="mutationawardemojiaddawardemoji"></a>`awardEmoji` | [`AwardEmoji`](#awardemoji) | Emoji reactions after mutation. | | <a id="mutationawardemojiaddclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationawardemojiadderrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | @@ -1412,7 +1468,7 @@ Input type: `AwardEmojiRemoveInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationawardemojiremoveawardemoji"></a>`awardEmoji` | [`AwardEmoji`](#awardemoji) | Award emoji after mutation. | +| <a id="mutationawardemojiremoveawardemoji"></a>`awardEmoji` | [`AwardEmoji`](#awardemoji) | Emoji reactions after mutation. | | <a id="mutationawardemojiremoveclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationawardemojiremoveerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | @@ -1432,7 +1488,7 @@ Input type: `AwardEmojiToggleInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationawardemojitoggleawardemoji"></a>`awardEmoji` | [`AwardEmoji`](#awardemoji) | Award emoji after mutation. | +| <a id="mutationawardemojitoggleawardemoji"></a>`awardEmoji` | [`AwardEmoji`](#awardemoji) | Emoji reactions after mutation. | | <a id="mutationawardemojitoggleclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationawardemojitoggleerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationawardemojitoggletoggledon"></a>`toggledOn` | [`Boolean!`](#boolean) | Indicates the status of the emoji. True if the toggle awarded the emoji, and false if the toggle removed the emoji. | @@ -3204,6 +3260,7 @@ Input type: `EnvironmentCreateInput` | <a id="mutationenvironmentcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationenvironmentcreateclusteragentid"></a>`clusterAgentId` | [`ClustersAgentID`](#clustersagentid) | Cluster agent of the environment. | | <a id="mutationenvironmentcreateexternalurl"></a>`externalUrl` | [`String`](#string) | External URL of the environment. | +| <a id="mutationenvironmentcreatefluxresourcepath"></a>`fluxResourcePath` | [`String`](#string) | Flux resource path of the environment. | | <a id="mutationenvironmentcreatekubernetesnamespace"></a>`kubernetesNamespace` | [`String`](#string) | Kubernetes namespace of the environment. | | <a id="mutationenvironmentcreatename"></a>`name` | [`String!`](#string) | Name of the environment. | | <a id="mutationenvironmentcreateprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project. | @@ -3272,6 +3329,7 @@ Input type: `EnvironmentUpdateInput` | <a id="mutationenvironmentupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationenvironmentupdateclusteragentid"></a>`clusterAgentId` | [`ClustersAgentID`](#clustersagentid) | Cluster agent of the environment. | | <a id="mutationenvironmentupdateexternalurl"></a>`externalUrl` | [`String`](#string) | External URL of the environment. | +| <a id="mutationenvironmentupdatefluxresourcepath"></a>`fluxResourcePath` | [`String`](#string) | Flux resource path of the environment. | | <a id="mutationenvironmentupdateid"></a>`id` | [`EnvironmentID!`](#environmentid) | Global ID of the environment to update. | | <a id="mutationenvironmentupdatekubernetesnamespace"></a>`kubernetesNamespace` | [`String`](#string) | Kubernetes namespace of the environment. | | <a id="mutationenvironmentupdatetier"></a>`tier` | [`DeploymentTier`](#deploymenttier) | Tier of the environment. | @@ -5300,6 +5358,76 @@ Input type: `PipelineScheduleUpdateInput` | <a id="mutationpipelinescheduleupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationpipelinescheduleupdatepipelineschedule"></a>`pipelineSchedule` | [`PipelineSchedule`](#pipelineschedule) | Updated pipeline schedule. | +### `Mutation.pipelineTriggerCreate` + +WARNING: +**Introduced** in 16.3. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `PipelineTriggerCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationpipelinetriggercreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationpipelinetriggercreatedescription"></a>`description` | [`String!`](#string) | Description of the pipeline trigger token. | +| <a id="mutationpipelinetriggercreateprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project that the pipeline trigger token to mutate is in. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationpipelinetriggercreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationpipelinetriggercreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationpipelinetriggercreatepipelinetrigger"></a>`pipelineTrigger` | [`PipelineTrigger`](#pipelinetrigger) | Mutated pipeline trigger token. | + +### `Mutation.pipelineTriggerDelete` + +WARNING: +**Introduced** in 16.3. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `PipelineTriggerDeleteInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationpipelinetriggerdeleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationpipelinetriggerdeleteid"></a>`id` | [`CiTriggerID!`](#citriggerid) | ID of the pipeline trigger token to mutate. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationpipelinetriggerdeleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationpipelinetriggerdeleteerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + +### `Mutation.pipelineTriggerUpdate` + +WARNING: +**Introduced** in 16.3. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `PipelineTriggerUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationpipelinetriggerupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationpipelinetriggerupdatedescription"></a>`description` | [`String!`](#string) | Description of the pipeline trigger token. | +| <a id="mutationpipelinetriggerupdateid"></a>`id` | [`CiTriggerID!`](#citriggerid) | ID of the pipeline trigger token to mutate. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationpipelinetriggerupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationpipelinetriggerupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationpipelinetriggerupdatepipelinetrigger"></a>`pipelineTrigger` | [`PipelineTrigger`](#pipelinetrigger) | Mutated pipeline trigger token. | + ### `Mutation.projectCiCdSettingsUpdate` Input type: `ProjectCiCdSettingsUpdateInput` @@ -6695,6 +6823,8 @@ Input type: `UpdateNamespacePackageSettingsInput` | <a id="mutationupdatenamespacepackagesettingsmavenpackagerequestsforwarding"></a>`mavenPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether Maven package forwarding is allowed for this namespace. | | <a id="mutationupdatenamespacepackagesettingsnamespacepath"></a>`namespacePath` | [`ID!`](#id) | Namespace path where the namespace package setting is located. | | <a id="mutationupdatenamespacepackagesettingsnpmpackagerequestsforwarding"></a>`npmPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether npm package forwarding is allowed for this namespace. | +| <a id="mutationupdatenamespacepackagesettingsnugetduplicateexceptionregex"></a>`nugetDuplicateExceptionRegex` | [`UntrustedRegexp`](#untrustedregexp) | When nuget_duplicates_allowed is false, you can publish duplicate packages with names that match this regex. Otherwise, this setting has no effect. Error is raised if `nuget_duplicates_option` feature flag is disabled. | +| <a id="mutationupdatenamespacepackagesettingsnugetduplicatesallowed"></a>`nugetDuplicatesAllowed` | [`Boolean`](#boolean) | Indicates whether duplicate NuGet packages are allowed for this namespace. Error is raised if `nuget_duplicates_option` feature flag is disabled. | | <a id="mutationupdatenamespacepackagesettingspypipackagerequestsforwarding"></a>`pypiPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether PyPI package forwarding is allowed for this namespace. | #### Fields @@ -6846,6 +6976,54 @@ Input type: `UserAchievementsDeleteInput` | <a id="mutationuserachievementsdeleteerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationuserachievementsdeleteuserachievement"></a>`userAchievement` | [`UserAchievement`](#userachievement) | Deleted user achievement. | +### `Mutation.userAddOnAssignmentCreate` + +WARNING: +**Introduced** in 16.3. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `UserAddOnAssignmentCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationuseraddonassignmentcreateaddonpurchaseid"></a>`addOnPurchaseId` | [`GitlabSubscriptionsAddOnPurchaseID!`](#gitlabsubscriptionsaddonpurchaseid) | Global ID of AddOnPurchase to be assinged to. | +| <a id="mutationuseraddonassignmentcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationuseraddonassignmentcreateuserid"></a>`userId` | [`UserID!`](#userid) | Global ID of user to be assigned. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationuseraddonassignmentcreateaddonpurchase"></a>`addOnPurchase` | [`AddOnPurchase`](#addonpurchase) | AddOnPurchase state after mutation. | +| <a id="mutationuseraddonassignmentcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationuseraddonassignmentcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + +### `Mutation.userAddOnAssignmentRemove` + +WARNING: +**Introduced** in 16.3. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `UserAddOnAssignmentRemoveInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationuseraddonassignmentremoveaddonpurchaseid"></a>`addOnPurchaseId` | [`GitlabSubscriptionsAddOnPurchaseID!`](#gitlabsubscriptionsaddonpurchaseid) | Global ID of AddOnPurchase assignment belongs to. | +| <a id="mutationuseraddonassignmentremoveclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationuseraddonassignmentremoveuserid"></a>`userId` | [`UserID!`](#userid) | Global ID of user whose assignment will be removed. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationuseraddonassignmentremoveaddonpurchase"></a>`addOnPurchase` | [`AddOnPurchase`](#addonpurchase) | AddOnPurchase state after mutation. | +| <a id="mutationuseraddonassignmentremoveclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationuseraddonassignmentremoveerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.userCalloutCreate` Input type: `UserCalloutCreateInput` @@ -6907,10 +7085,6 @@ Input type: `UserSetNamespaceCommitEmailInput` ### `Mutation.vulnerabilitiesDismiss` -WARNING: -**Introduced** in 16.2. -This feature is an Experiment. It can be changed or removed at any time. - Input type: `VulnerabilitiesDismissInput` #### Arguments @@ -6928,7 +7102,7 @@ Input type: `VulnerabilitiesDismissInput` | ---- | ---- | ----------- | | <a id="mutationvulnerabilitiesdismissclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationvulnerabilitiesdismisserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationvulnerabilitiesdismissvulnerabilities"></a>`vulnerabilities` **{warning-solid}** | [`[Vulnerability!]!`](#vulnerability) | **Deprecated:** This feature is an Experiment. It can be changed or removed at any time. Introduced in 16.2. | +| <a id="mutationvulnerabilitiesdismissvulnerabilities"></a>`vulnerabilities` | [`[Vulnerability!]!`](#vulnerability) | Vulnerabilities after state change. | ### `Mutation.vulnerabilityConfirm` @@ -7102,6 +7276,34 @@ Input type: `VulnerabilityRevertToDetectedInput` | <a id="mutationvulnerabilityreverttodetectederrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationvulnerabilityreverttodetectedvulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability after state change. | +### `Mutation.workItemAddLinkedItems` + +Add linked items to the work item. + +WARNING: +**Introduced** in 16.3. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `WorkItemAddLinkedItemsInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationworkitemaddlinkeditemsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationworkitemaddlinkeditemsid"></a>`id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | +| <a id="mutationworkitemaddlinkeditemslinktype"></a>`linkType` | [`WorkItemRelatedLinkType`](#workitemrelatedlinktype) | Type of link. Defaults to `RELATED`. | +| <a id="mutationworkitemaddlinkeditemsworkitemsids"></a>`workItemsIds` | [`[WorkItemID!]!`](#workitemid) | Global IDs of the items to link. Maximum number of IDs you can provide: 3. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationworkitemaddlinkeditemsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationworkitemaddlinkeditemserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationworkitemaddlinkeditemsmessage"></a>`message` | [`String`](#string) | Linked items update result message. | +| <a id="mutationworkitemaddlinkeditemsworkitem"></a>`workItem` | [`WorkItem`](#workitem) | Updated work item. | + ### `Mutation.workItemConvert` Converts the work item to a new type. @@ -7270,6 +7472,30 @@ Input type: `WorkItemExportInput` | <a id="mutationworkitemexporterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationworkitemexportmessage"></a>`message` | [`String`](#string) | Export request result message. | +### `Mutation.workItemSubscribe` + +WARNING: +**Introduced** in 16.3. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `WorkItemSubscribeInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationworkitemsubscribeclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationworkitemsubscribeid"></a>`id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | +| <a id="mutationworkitemsubscribesubscribed"></a>`subscribed` | [`Boolean!`](#boolean) | Desired state of the subscription. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationworkitemsubscribeclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationworkitemsubscribeerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationworkitemsubscribeworkitem"></a>`workItem` | [`WorkItem`](#workitem) | Work item after mutation. | + ### `Mutation.workItemUpdate` Updates a work item by Global ID. @@ -7285,7 +7511,7 @@ Input type: `WorkItemUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationworkitemupdateassigneeswidget"></a>`assigneesWidget` | [`WorkItemWidgetAssigneesInput`](#workitemwidgetassigneesinput) | Input for assignees widget. | -| <a id="mutationworkitemupdateawardemojiwidget"></a>`awardEmojiWidget` | [`WorkItemWidgetAwardEmojiUpdateInput`](#workitemwidgetawardemojiupdateinput) | Input for award emoji widget. | +| <a id="mutationworkitemupdateawardemojiwidget"></a>`awardEmojiWidget` | [`WorkItemWidgetAwardEmojiUpdateInput`](#workitemwidgetawardemojiupdateinput) | Input for emoji reactions widget. | | <a id="mutationworkitemupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationworkitemupdateconfidential"></a>`confidential` | [`Boolean`](#boolean) | Sets the work item confidentiality. | | <a id="mutationworkitemupdatecurrentusertodoswidget"></a>`currentUserTodosWidget` | [`WorkItemWidgetCurrentUserTodosInput`](#workitemwidgetcurrentusertodosinput) | Input for to-dos widget. | @@ -7439,6 +7665,7 @@ The connection type for [`Achievement`](#achievement). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="achievementconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | | <a id="achievementconnectionedges"></a>`edges` | [`[AchievementEdge]`](#achievementedge) | A list of edges. | | <a id="achievementconnectionnodes"></a>`nodes` | [`[Achievement]`](#achievement) | A list of nodes. | | <a id="achievementconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | @@ -8708,6 +8935,7 @@ The connection type for [`CustomEmoji`](#customemoji). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="customemojiconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | | <a id="customemojiconnectionedges"></a>`edges` | [`[CustomEmojiEdge]`](#customemojiedge) | A list of edges. | | <a id="customemojiconnectionnodes"></a>`nodes` | [`[CustomEmoji]`](#customemoji) | A list of nodes. | | <a id="customemojiconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | @@ -9926,6 +10154,29 @@ The edge type for [`LicenseHistoryEntry`](#licensehistoryentry). | <a id="licensehistoryentryedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="licensehistoryentryedgenode"></a>`node` | [`LicenseHistoryEntry`](#licensehistoryentry) | The item at the end of the edge. | +#### `LinkedWorkItemTypeConnection` + +The connection type for [`LinkedWorkItemType`](#linkedworkitemtype). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="linkedworkitemtypeconnectionedges"></a>`edges` | [`[LinkedWorkItemTypeEdge]`](#linkedworkitemtypeedge) | A list of edges. | +| <a id="linkedworkitemtypeconnectionnodes"></a>`nodes` | [`[LinkedWorkItemType]`](#linkedworkitemtype) | A list of nodes. | +| <a id="linkedworkitemtypeconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `LinkedWorkItemTypeEdge` + +The edge type for [`LinkedWorkItemType`](#linkedworkitemtype). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="linkedworkitemtypeedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="linkedworkitemtypeedgenode"></a>`node` | [`LinkedWorkItemType`](#linkedworkitemtype) | The item at the end of the edge. | + #### `MemberInterfaceConnection` The connection type for [`MemberInterface`](#memberinterface). @@ -10622,6 +10873,30 @@ The edge type for [`PipelineSecurityReportFinding`](#pipelinesecurityreportfindi | <a id="pipelinesecurityreportfindingedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="pipelinesecurityreportfindingedgenode"></a>`node` | [`PipelineSecurityReportFinding`](#pipelinesecurityreportfinding) | The item at the end of the edge. | +#### `PipelineTriggerConnection` + +The connection type for [`PipelineTrigger`](#pipelinetrigger). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="pipelinetriggerconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | +| <a id="pipelinetriggerconnectionedges"></a>`edges` | [`[PipelineTriggerEdge]`](#pipelinetriggeredge) | A list of edges. | +| <a id="pipelinetriggerconnectionnodes"></a>`nodes` | [`[PipelineTrigger]`](#pipelinetrigger) | A list of nodes. | +| <a id="pipelinetriggerconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `PipelineTriggerEdge` + +The edge type for [`PipelineTrigger`](#pipelinetrigger). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="pipelinetriggeredgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="pipelinetriggeredgenode"></a>`node` | [`PipelineTrigger`](#pipelinetrigger) | The item at the end of the edge. | + #### `ProductAnalyticsDashboardConnection` The connection type for [`ProductAnalyticsDashboard`](#productanalyticsdashboard). @@ -11789,6 +12064,7 @@ The connection type for [`UserAchievement`](#userachievement). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="userachievementconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | | <a id="userachievementconnectionedges"></a>`edges` | [`[UserAchievementEdge]`](#userachievementedge) | A list of edges. | | <a id="userachievementconnectionnodes"></a>`nodes` | [`[UserAchievement]`](#userachievement) | A list of nodes. | | <a id="userachievementconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | @@ -12093,6 +12369,16 @@ For more information, see [Object Types and Fields](https://graphql.org/learn/schema/#object-types-and-fields) on `graphql.org`. +### `AbuseReport` + +An abuse report. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="abusereportlabels"></a>`labels` | [`LabelConnection`](#labelconnection) | Labels of the abuse report. (see [Connections](#connections)) | + ### `AccessLevel` Represents the access level of a relationship between a User and object that it is related to. @@ -12104,6 +12390,19 @@ Represents the access level of a relationship between a User and object that it | <a id="accesslevelintegervalue"></a>`integerValue` | [`Int`](#int) | Integer representation of access level. | | <a id="accesslevelstringvalue"></a>`stringValue` | [`AccessLevelEnum`](#accesslevelenum) | String representation of access level. | +### `AccessLevelDeployKey` + +Representation of a GitLab deploy key. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="accessleveldeploykeyexpiresat"></a>`expiresAt` | [`Date`](#date) | Expiration date of the deploy key. | +| <a id="accessleveldeploykeyid"></a>`id` | [`ID!`](#id) | ID of the deploy key. | +| <a id="accessleveldeploykeytitle"></a>`title` | [`String!`](#string) | Title of the deploy key. | +| <a id="accessleveldeploykeyuser"></a>`user` | [`AccessLevelUser!`](#accessleveluser) | User assigned to the deploy key. | + ### `AccessLevelGroup` Representation of a GitLab group. @@ -12130,7 +12429,7 @@ Representation of a GitLab user. | <a id="accessleveluserid"></a>`id` | [`ID!`](#id) | ID of the user. | | <a id="accesslevelusername"></a>`name` | [`String!`](#string) | Human-readable name of the user. Returns `****` if the user is a project bot and the requester does not have permission to view the project. | | <a id="accessleveluserpublicemail"></a>`publicEmail` | [`String`](#string) | User's public email. | -| <a id="accessleveluserusername"></a>`username` | [`String!`](#string) | Username of the user. Unique within this instance of GitLab. | +| <a id="accessleveluserusername"></a>`username` | [`String!`](#string) | Username of the user. | | <a id="accessleveluserwebpath"></a>`webPath` | [`String!`](#string) | Web path of the user. | | <a id="accessleveluserweburl"></a>`webUrl` | [`String!`](#string) | Web URL of the user. | @@ -12219,6 +12518,8 @@ Information about a connected Agent. | <a id="airesponseerrors"></a>`errors` | [`[String!]`](#string) | Errors return by AI API as response. | | <a id="airesponserequestid"></a>`requestId` | [`String`](#string) | ID of the original request. | | <a id="airesponseresponsebody"></a>`responseBody` | [`String`](#string) | Response body from AI API. | +| <a id="airesponserole"></a>`role` | [`AiCachedMessageRole!`](#aicachedmessagerole) | Message role. | +| <a id="airesponsetimestamp"></a>`timestamp` | [`Time!`](#time) | Message timestamp. | ### `AlertManagementAlert` @@ -12243,6 +12544,7 @@ Describes an alert from the project's Alert Management. | <a id="alertmanagementalertiid"></a>`iid` | [`ID!`](#id) | Internal ID of the alert. | | <a id="alertmanagementalertissue"></a>`issue` | [`Issue`](#issue) | Issue attached to the alert. | | <a id="alertmanagementalertissueiid"></a>`issueIid` **{warning-solid}** | [`ID`](#id) | **Deprecated** in 13.10. Use issue field. | +| <a id="alertmanagementalertmetricsdashboardurl"></a>`metricsDashboardUrl` **{warning-solid}** | [`String`](#string) | **Deprecated** in 16.0. Returns no data. Underlying feature was removed in 16.0. | | <a id="alertmanagementalertmonitoringtool"></a>`monitoringTool` | [`String`](#string) | Monitoring tool the alert came from. | | <a id="alertmanagementalertnotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | | <a id="alertmanagementalertprometheusalert"></a>`prometheusAlert` | [`PrometheusAlert`](#prometheusalert) | Alert condition for Prometheus. | @@ -12468,6 +12770,297 @@ Represents a HTTP header key/value that belongs to an instance level audit strea | <a id="auditeventsstreaminginstanceheaderkey"></a>`key` | [`String!`](#string) | Key of the header. | | <a id="auditeventsstreaminginstanceheadervalue"></a>`value` | [`String!`](#string) | Value of the header. | +### `AutocompletedUser` + +Core represention of a GitLab user. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="autocompleteduseravatarurl"></a>`avatarUrl` | [`String`](#string) | URL of the user's avatar. | +| <a id="autocompleteduserbio"></a>`bio` | [`String`](#string) | Bio of the user. | +| <a id="autocompleteduserbot"></a>`bot` | [`Boolean!`](#boolean) | Indicates if the user is a bot. | +| <a id="autocompletedusercallouts"></a>`callouts` | [`UserCalloutConnection`](#usercalloutconnection) | User callouts that belong to the user. (see [Connections](#connections)) | +| <a id="autocompletedusercommitemail"></a>`commitEmail` | [`String`](#string) | User's default commit email. | +| <a id="autocompletedusercreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of when the user was created. | +| <a id="autocompleteduserdiscord"></a>`discord` | [`String`](#string) | Discord ID of the user. | +| <a id="autocompleteduseremail"></a>`email` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.7. This was renamed. Use: [`User.publicEmail`](#userpublicemail). | +| <a id="autocompleteduseremails"></a>`emails` | [`EmailConnection`](#emailconnection) | User's email addresses. (see [Connections](#connections)) | +| <a id="autocompletedusergitpodenabled"></a>`gitpodEnabled` | [`Boolean`](#boolean) | Whether Gitpod is enabled at the user level. | +| <a id="autocompletedusergroupcount"></a>`groupCount` | [`Int`](#int) | Group count for the user. | +| <a id="autocompletedusergroupmemberships"></a>`groupMemberships` | [`GroupMemberConnection`](#groupmemberconnection) | Group memberships of the user. (see [Connections](#connections)) | +| <a id="autocompleteduserid"></a>`id` | [`ID!`](#id) | ID of the user. | +| <a id="autocompleteduseride"></a>`ide` | [`Ide`](#ide) | IDE settings. | +| <a id="autocompleteduserjobtitle"></a>`jobTitle` | [`String`](#string) | Job title of the user. | +| <a id="autocompleteduserlinkedin"></a>`linkedin` | [`String`](#string) | LinkedIn profile name of the user. | +| <a id="autocompleteduserlocation"></a>`location` | [`String`](#string) | Location of the user. | +| <a id="autocompletedusername"></a>`name` | [`String!`](#string) | Human-readable name of the user. Returns `****` if the user is a project bot and the requester does not have permission to view the project. | +| <a id="autocompletedusernamespace"></a>`namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | +| <a id="autocompletedusernamespacecommitemails"></a>`namespaceCommitEmails` | [`NamespaceCommitEmailConnection`](#namespacecommitemailconnection) | User's custom namespace commit emails. (see [Connections](#connections)) | +| <a id="autocompleteduserorganization"></a>`organization` | [`String`](#string) | Who the user represents or works for. | +| <a id="autocompleteduserpreferencesgitpodpath"></a>`preferencesGitpodPath` | [`String`](#string) | Web path to the Gitpod section within user preferences. | +| <a id="autocompleteduserprofileenablegitpodpath"></a>`profileEnableGitpodPath` | [`String`](#string) | Web path to enable Gitpod for the user. | +| <a id="autocompleteduserprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | +| <a id="autocompleteduserpronouns"></a>`pronouns` | [`String`](#string) | Pronouns of the user. | +| <a id="autocompleteduserpublicemail"></a>`publicEmail` | [`String`](#string) | User's public email. | +| <a id="autocompletedusersavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. Will not return saved replies if `saved_replies` feature flag is disabled. (see [Connections](#connections)) | +| <a id="autocompleteduserstate"></a>`state` | [`UserState!`](#userstate) | State of the user. | +| <a id="autocompleteduserstatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | +| <a id="autocompletedusertwitter"></a>`twitter` | [`String`](#string) | Twitter username of the user. | +| <a id="autocompleteduseruserachievements"></a>`userAchievements` **{warning-solid}** | [`UserAchievementConnection`](#userachievementconnection) | **Introduced** in 15.10. This feature is an Experiment. It can be changed or removed at any time. Achievements for the user. Only returns for namespaces where the `achievements` feature flag is enabled. | +| <a id="autocompleteduseruserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | +| <a id="autocompleteduserusername"></a>`username` | [`String!`](#string) | Username of the user. Unique within this instance of GitLab. | +| <a id="autocompleteduserwebpath"></a>`webPath` | [`String!`](#string) | Web path of the user. | +| <a id="autocompleteduserweburl"></a>`webUrl` | [`String!`](#string) | Web URL of the user. | + +#### Fields with arguments + +##### `AutocompletedUser.assignedMergeRequests` + +Merge requests assigned to the user. + +Returns [`MergeRequestConnection`](#mergerequestconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="autocompleteduserassignedmergerequestsapproved"></a>`approved` | [`Boolean`](#boolean) | Limit results to approved merge requests. Available only when the feature flag `mr_approved_filter` is enabled. | +| <a id="autocompleteduserassignedmergerequestsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author. | +| <a id="autocompleteduserassignedmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | +| <a id="autocompleteduserassignedmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="autocompleteduserassignedmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | +| <a id="autocompleteduserassignedmergerequestsgroupid"></a>`groupId` | [`GroupID`](#groupid) | The global ID of the group the authored merge requests should be in. Merge requests in subgroups are included. | +| <a id="autocompleteduserassignedmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | +| <a id="autocompleteduserassignedmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | +| <a id="autocompleteduserassignedmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | +| <a id="autocompleteduserassignedmergerequestsmergedbefore"></a>`mergedBefore` | [`Time`](#time) | Merge requests merged before this date. | +| <a id="autocompleteduserassignedmergerequestsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Title of the milestone. | +| <a id="autocompleteduserassignedmergerequestsnot"></a>`not` | [`MergeRequestsResolverNegatedParams`](#mergerequestsresolvernegatedparams) | List of negated arguments. Warning: this argument is experimental and a subject to change in future. | +| <a id="autocompleteduserassignedmergerequestsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | The global ID of the project the authored merge requests should be in. Incompatible with projectPath. | +| <a id="autocompleteduserassignedmergerequestsprojectpath"></a>`projectPath` | [`String`](#string) | The full-path of the project the authored merge requests should be in. Incompatible with projectId. | +| <a id="autocompleteduserassignedmergerequestsreviewerusername"></a>`reviewerUsername` | [`String`](#string) | Username of the reviewer. | +| <a id="autocompleteduserassignedmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | +| <a id="autocompleteduserassignedmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | +| <a id="autocompleteduserassignedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | +| <a id="autocompleteduserassignedmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| <a id="autocompleteduserassignedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| <a id="autocompleteduserassignedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | + +##### `AutocompletedUser.authoredMergeRequests` + +Merge requests authored by the user. + +Returns [`MergeRequestConnection`](#mergerequestconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="autocompleteduserauthoredmergerequestsapproved"></a>`approved` | [`Boolean`](#boolean) | Limit results to approved merge requests. Available only when the feature flag `mr_approved_filter` is enabled. | +| <a id="autocompleteduserauthoredmergerequestsassigneeusername"></a>`assigneeUsername` | [`String`](#string) | Username of the assignee. | +| <a id="autocompleteduserauthoredmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | +| <a id="autocompleteduserauthoredmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="autocompleteduserauthoredmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | +| <a id="autocompleteduserauthoredmergerequestsgroupid"></a>`groupId` | [`GroupID`](#groupid) | The global ID of the group the authored merge requests should be in. Merge requests in subgroups are included. | +| <a id="autocompleteduserauthoredmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | +| <a id="autocompleteduserauthoredmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | +| <a id="autocompleteduserauthoredmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | +| <a id="autocompleteduserauthoredmergerequestsmergedbefore"></a>`mergedBefore` | [`Time`](#time) | Merge requests merged before this date. | +| <a id="autocompleteduserauthoredmergerequestsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Title of the milestone. | +| <a id="autocompleteduserauthoredmergerequestsnot"></a>`not` | [`MergeRequestsResolverNegatedParams`](#mergerequestsresolvernegatedparams) | List of negated arguments. Warning: this argument is experimental and a subject to change in future. | +| <a id="autocompleteduserauthoredmergerequestsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | The global ID of the project the authored merge requests should be in. Incompatible with projectPath. | +| <a id="autocompleteduserauthoredmergerequestsprojectpath"></a>`projectPath` | [`String`](#string) | The full-path of the project the authored merge requests should be in. Incompatible with projectId. | +| <a id="autocompleteduserauthoredmergerequestsreviewerusername"></a>`reviewerUsername` | [`String`](#string) | Username of the reviewer. | +| <a id="autocompleteduserauthoredmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | +| <a id="autocompleteduserauthoredmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | +| <a id="autocompleteduserauthoredmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | +| <a id="autocompleteduserauthoredmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| <a id="autocompleteduserauthoredmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| <a id="autocompleteduserauthoredmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | + +##### `AutocompletedUser.groups` + +Groups where the user has access. + +Returns [`GroupConnection`](#groupconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="autocompletedusergroupspermissionscope"></a>`permissionScope` | [`GroupPermission`](#grouppermission) | Filter by permissions the user has on groups. | +| <a id="autocompletedusergroupssearch"></a>`search` | [`String`](#string) | Search by group name or path. | + +##### `AutocompletedUser.mergeRequestInteraction` + +Merge request state related to the user. + +Returns [`UserMergeRequestInteraction`](#usermergerequestinteraction). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="autocompletedusermergerequestinteractionid"></a>`id` | [`MergeRequestID!`](#mergerequestid) | Global ID of the merge request. | + +##### `AutocompletedUser.reviewRequestedMergeRequests` + +Merge requests assigned to the user for review. + +Returns [`MergeRequestConnection`](#mergerequestconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="autocompleteduserreviewrequestedmergerequestsapproved"></a>`approved` | [`Boolean`](#boolean) | Limit results to approved merge requests. Available only when the feature flag `mr_approved_filter` is enabled. | +| <a id="autocompleteduserreviewrequestedmergerequestsassigneeusername"></a>`assigneeUsername` | [`String`](#string) | Username of the assignee. | +| <a id="autocompleteduserreviewrequestedmergerequestsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author. | +| <a id="autocompleteduserreviewrequestedmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | +| <a id="autocompleteduserreviewrequestedmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="autocompleteduserreviewrequestedmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | +| <a id="autocompleteduserreviewrequestedmergerequestsgroupid"></a>`groupId` | [`GroupID`](#groupid) | The global ID of the group the authored merge requests should be in. Merge requests in subgroups are included. | +| <a id="autocompleteduserreviewrequestedmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | +| <a id="autocompleteduserreviewrequestedmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | +| <a id="autocompleteduserreviewrequestedmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | +| <a id="autocompleteduserreviewrequestedmergerequestsmergedbefore"></a>`mergedBefore` | [`Time`](#time) | Merge requests merged before this date. | +| <a id="autocompleteduserreviewrequestedmergerequestsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Title of the milestone. | +| <a id="autocompleteduserreviewrequestedmergerequestsnot"></a>`not` | [`MergeRequestsResolverNegatedParams`](#mergerequestsresolvernegatedparams) | List of negated arguments. Warning: this argument is experimental and a subject to change in future. | +| <a id="autocompleteduserreviewrequestedmergerequestsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | The global ID of the project the authored merge requests should be in. Incompatible with projectPath. | +| <a id="autocompleteduserreviewrequestedmergerequestsprojectpath"></a>`projectPath` | [`String`](#string) | The full-path of the project the authored merge requests should be in. Incompatible with projectId. | +| <a id="autocompleteduserreviewrequestedmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | +| <a id="autocompleteduserreviewrequestedmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | +| <a id="autocompleteduserreviewrequestedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | +| <a id="autocompleteduserreviewrequestedmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| <a id="autocompleteduserreviewrequestedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| <a id="autocompleteduserreviewrequestedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | + +##### `AutocompletedUser.savedReply` + +Saved reply authored by the user. Will not return saved reply if `saved_replies` feature flag is disabled. + +Returns [`SavedReply`](#savedreply). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="autocompletedusersavedreplyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | ID of a saved reply. | + +##### `AutocompletedUser.snippets` + +Snippets authored by the user. + +Returns [`SnippetConnection`](#snippetconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="autocompletedusersnippetsids"></a>`ids` | [`[SnippetID!]`](#snippetid) | Array of global snippet IDs. For example, `gid://gitlab/ProjectSnippet/1`. | +| <a id="autocompletedusersnippetstype"></a>`type` | [`TypeEnum`](#typeenum) | Type of snippet. | +| <a id="autocompletedusersnippetsvisibility"></a>`visibility` | [`VisibilityScopesEnum`](#visibilityscopesenum) | Visibility of the snippet. | + +##### `AutocompletedUser.starredProjects` + +Projects starred by the user. + +Returns [`ProjectConnection`](#projectconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="autocompleteduserstarredprojectssearch"></a>`search` | [`String`](#string) | Search query. | + +##### `AutocompletedUser.timelogs` + +Time logged by the user. + +Returns [`TimelogConnection`](#timelogconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="autocompletedusertimelogsenddate"></a>`endDate` | [`Time`](#time) | List timelogs within a date range where the logged date is equal to or before endDate. | +| <a id="autocompletedusertimelogsendtime"></a>`endTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or before endTime. | +| <a id="autocompletedusertimelogsgroupid"></a>`groupId` | [`GroupID`](#groupid) | List timelogs for a group. | +| <a id="autocompletedusertimelogsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | List timelogs for a project. | +| <a id="autocompletedusertimelogssort"></a>`sort` | [`TimelogSort`](#timelogsort) | List timelogs in a particular order. | +| <a id="autocompletedusertimelogsstartdate"></a>`startDate` | [`Time`](#time) | List timelogs within a date range where the logged date is equal to or after startDate. | +| <a id="autocompletedusertimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. | +| <a id="autocompletedusertimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. | + +##### `AutocompletedUser.todos` + +To-do items of the user. + +Returns [`TodoConnection`](#todoconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="autocompletedusertodosaction"></a>`action` | [`[TodoActionEnum!]`](#todoactionenum) | Action to be filtered. | +| <a id="autocompletedusertodosauthorid"></a>`authorId` | [`[ID!]`](#id) | ID of an author. | +| <a id="autocompletedusertodosgroupid"></a>`groupId` | [`[ID!]`](#id) | ID of a group. | +| <a id="autocompletedusertodosprojectid"></a>`projectId` | [`[ID!]`](#id) | ID of a project. | +| <a id="autocompletedusertodosstate"></a>`state` | [`[TodoStateEnum!]`](#todostateenum) | State of the todo. | +| <a id="autocompletedusertodostype"></a>`type` | [`[TodoTargetEnum!]`](#todotargetenum) | Type of the todo. | + +##### `AutocompletedUser.workspaces` + +Workspaces owned by the current user. + +Returns [`WorkspaceConnection`](#workspaceconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="autocompleteduserworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Array of global workspace IDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | +| <a id="autocompleteduserworkspacesincludeactualstates"></a>`includeActualStates` | [`[String!]`](#string) | Includes all workspaces that match any of the actual states. | +| <a id="autocompleteduserworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project id. | + ### `AwardEmoji` An emoji awarded by a user. @@ -12593,7 +13186,7 @@ Represents an epic on an issue board. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="boardepicauthor"></a>`author` | [`UserCore!`](#usercore) | Author of the epic. | -| <a id="boardepicawardemoji"></a>`awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | List of award emojis associated with the epic. (see [Connections](#connections)) | +| <a id="boardepicawardemoji"></a>`awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | List of emoji reactions associated with the epic. (see [Connections](#connections)) | | <a id="boardepicblocked"></a>`blocked` | [`Boolean`](#boolean) | Indicates the epic is blocked. | | <a id="boardepicblockedbycount"></a>`blockedByCount` | [`Int`](#int) | Count of epics blocking this epic. | | <a id="boardepicblockedbyepics"></a>`blockedByEpics` | [`EpicConnection`](#epicconnection) | Epics blocking this epic. (see [Connections](#connections)) | @@ -12889,6 +13482,8 @@ Represents the total number of issues and their weights for a particular day. | <a id="cicatalogresourceid"></a>`id` **{warning-solid}** | [`ID!`](#id) | **Introduced** in 15.11. This feature is an Experiment. It can be changed or removed at any time. ID of the catalog resource. | | <a id="cicatalogresourcelatestversion"></a>`latestVersion` **{warning-solid}** | [`Release`](#release) | **Introduced** in 16.1. This feature is an Experiment. It can be changed or removed at any time. Latest version of the catalog resource. | | <a id="cicatalogresourcename"></a>`name` **{warning-solid}** | [`String`](#string) | **Introduced** in 15.11. This feature is an Experiment. It can be changed or removed at any time. Name of the catalog resource. | +| <a id="cicatalogresourceopenissuescount"></a>`openIssuesCount` **{warning-solid}** | [`Int!`](#int) | **Introduced** in 16.3. This feature is an Experiment. It can be changed or removed at any time. Count of open issues that belong to the the catalog resource. | +| <a id="cicatalogresourceopenmergerequestscount"></a>`openMergeRequestsCount` **{warning-solid}** | [`Int!`](#int) | **Introduced** in 16.3. This feature is an Experiment. It can be changed or removed at any time. Count of open merge requests that belong to the the catalog resource. | | <a id="cicatalogresourcereadmehtml"></a>`readmeHtml` **{warning-solid}** | [`String!`](#string) | **Introduced** in 16.1. This feature is an Experiment. It can be changed or removed at any time. GitLab Flavored Markdown rendering of `readme`. | | <a id="cicatalogresourcerootnamespace"></a>`rootNamespace` **{warning-solid}** | [`Namespace`](#namespace) | **Introduced** in 16.1. This feature is an Experiment. It can be changed or removed at any time. Root namespace of the catalog resource. | | <a id="cicatalogresourcestarcount"></a>`starCount` **{warning-solid}** | [`Int!`](#int) | **Introduced** in 16.1. This feature is an Experiment. It can be changed or removed at any time. Number of times the catalog resource has been starred. | @@ -13299,6 +13894,7 @@ CI/CD variables for a project. ##### `CiRunner.jobCount` Number of jobs processed by the runner (limited to 1000, plus one to indicate that more items exist). +`jobCount` is an optimized version of `jobs { count }`, and can be requested for multiple runners on the same request. Returns [`Int`](#int). @@ -13368,6 +13964,7 @@ Returns [`CiRunnerStatus!`](#cirunnerstatus). | <a id="cirunnermanagerexecutorname"></a>`executorName` | [`String`](#string) | Executor last advertised by the runner. | | <a id="cirunnermanagerid"></a>`id` | [`CiRunnerManagerID!`](#cirunnermanagerid) | ID of the runner manager. | | <a id="cirunnermanageripaddress"></a>`ipAddress` | [`String`](#string) | IP address of the runner manager. | +| <a id="cirunnermanagerjobexecutionstatus"></a>`jobExecutionStatus` **{warning-solid}** | [`CiRunnerJobExecutionStatus`](#cirunnerjobexecutionstatus) | **Introduced** in 16.3. This feature is an Experiment. It can be changed or removed at any time. Job execution status of the runner manager. | | <a id="cirunnermanagerplatformname"></a>`platformName` | [`String`](#string) | Platform provided by the runner manager. | | <a id="cirunnermanagerrevision"></a>`revision` | [`String`](#string) | Revision of the runner. | | <a id="cirunnermanagerrunner"></a>`runner` | [`CiRunner`](#cirunner) | Runner configuration for the runner manager. | @@ -13392,7 +13989,12 @@ Represents the Geo replication and verification state of a ci_secure_file. | <a id="cisecurefileregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the CiSecureFileRegistry is resynced. | | <a id="cisecurefileregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the CiSecureFileRegistry. | | <a id="cisecurefileregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the CiSecureFileRegistry. | +| <a id="cisecurefileregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the CiSecureFileRegistry. | +| <a id="cisecurefileregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the CiSecureFileRegistry. | | <a id="cisecurefileregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the CiSecureFileRegistry is reverified. | +| <a id="cisecurefileregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the CiSecureFileRegistry. | +| <a id="cisecurefileregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of CiSecureFileRegistry. | +| <a id="cisecurefileregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the CiSecureFileRegistry. | | <a id="cisecurefileregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the CiSecureFileRegistry. | ### `CiStage` @@ -13550,8 +14152,12 @@ Code Quality report for a pipeline. | <a id="commitauthorgravatar"></a>`authorGravatar` | [`String`](#string) | Commit authors gravatar. | | <a id="commitauthorname"></a>`authorName` | [`String`](#string) | Commit authors name. | | <a id="commitauthoreddate"></a>`authoredDate` | [`Time`](#time) | Timestamp of when the commit was authored. | +| <a id="commitcommitteddate"></a>`committedDate` | [`Time`](#time) | Timestamp of when the commit was committed. | +| <a id="commitcommitteremail"></a>`committerEmail` | [`String`](#string) | Email of the committer. | +| <a id="commitcommittername"></a>`committerName` | [`String`](#string) | Name of the committer. | | <a id="commitdescription"></a>`description` | [`String`](#string) | Description of the commit message. | | <a id="commitdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | +| <a id="commitdiffs"></a>`diffs` | [`[Diff!]`](#diff) | Diffs contained within the commit. This field can only be resolved for 10 diffs in any single request. | | <a id="commitfulltitle"></a>`fullTitle` | [`String`](#string) | Full title of the commit message. | | <a id="commitfulltitlehtml"></a>`fullTitleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `full_title`. | | <a id="commitid"></a>`id` | [`ID!`](#id) | ID (global ID) of the commit. | @@ -13676,6 +14282,8 @@ Represents finding. | ---- | ---- | ----------- | | <a id="comparedsecurityreportfindingdescription"></a>`description` | [`String`](#string) | Description of the vulnerability finding. | | <a id="comparedsecurityreportfindingfoundbypipelineiid"></a>`foundByPipelineIid` | [`String`](#string) | IID of the pipeline. | +| <a id="comparedsecurityreportfindingidentifiers"></a>`identifiers` **{warning-solid}** | [`[VulnerabilityIdentifier!]`](#vulnerabilityidentifier) | **Introduced** in 16.3. This feature is an Experiment. It can be changed or removed at any time. Identifiers of the vulnerability finding. Returns `null` if `sast_reports_in_inline_diff` feature flag is disabled. | +| <a id="comparedsecurityreportfindinglocation"></a>`location` **{warning-solid}** | [`VulnerabilityLocation`](#vulnerabilitylocation) | **Introduced** in 16.3. This feature is an Experiment. It can be changed or removed at any time. Location of the vulnerability finding. Returns `null` if `sast_reports_in_inline_diff` feature flag is disabled. | | <a id="comparedsecurityreportfindingseverity"></a>`severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the vulnerability finding. | | <a id="comparedsecurityreportfindingstate"></a>`state` | [`VulnerabilityState`](#vulnerabilitystate) | Finding status. | | <a id="comparedsecurityreportfindingtitle"></a>`title` | [`String`](#string) | Title of the vulnerability finding. | @@ -13892,7 +14500,12 @@ Represents the Geo replication and verification state of an Container Repository | <a id="containerrepositoryregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the ContainerRepositoryRegistry is resynced. | | <a id="containerrepositoryregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the ContainerRepositoryRegistry. | | <a id="containerrepositoryregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the ContainerRepositoryRegistry. | +| <a id="containerrepositoryregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the ContainerRepositoryRegistry. | +| <a id="containerrepositoryregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the ContainerRepositoryRegistry. | | <a id="containerrepositoryregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the ContainerRepositoryRegistry is reverified. | +| <a id="containerrepositoryregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the ContainerRepositoryRegistry. | +| <a id="containerrepositoryregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of ContainerRepositoryRegistry. | +| <a id="containerrepositoryregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the ContainerRepositoryRegistry. | | <a id="containerrepositoryregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the ContainerRepositoryRegistry. | ### `ContainerRepositoryTag` @@ -13975,10 +14588,22 @@ A custom emoji uploaded by user. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="customemojicreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the custom emoji was created. | | <a id="customemojiexternal"></a>`external` | [`Boolean!`](#boolean) | Whether the emoji is an external link. | | <a id="customemojiid"></a>`id` | [`CustomEmojiID!`](#customemojiid) | ID of the emoji. | | <a id="customemojiname"></a>`name` | [`String!`](#string) | Name of the emoji. | | <a id="customemojiurl"></a>`url` | [`String!`](#string) | Link to file of the emoji. | +| <a id="customemojiuserpermissions"></a>`userPermissions` | [`CustomEmojiPermissions!`](#customemojipermissions) | Permissions for the current user on the resource. | + +### `CustomEmojiPermissions` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="customemojipermissionscreatecustomemoji"></a>`createCustomEmoji` | [`Boolean!`](#boolean) | Indicates the user can perform `create_custom_emoji` on this resource. | +| <a id="customemojipermissionsdeletecustomemoji"></a>`deleteCustomEmoji` | [`Boolean!`](#boolean) | Indicates the user can perform `delete_custom_emoji` on this resource. | +| <a id="customemojipermissionsreadcustomemoji"></a>`readCustomEmoji` | [`Boolean!`](#boolean) | Indicates the user can perform `read_custom_emoji` on this resource. | ### `CustomerRelationsContact` @@ -14240,7 +14865,12 @@ Represents the Geo replication and verification state of a dependency_proxy_blob | <a id="dependencyproxyblobregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the DependencyProxyBlobRegistry is resynced. | | <a id="dependencyproxyblobregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the DependencyProxyBlobRegistry. | | <a id="dependencyproxyblobregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the DependencyProxyBlobRegistry. | +| <a id="dependencyproxyblobregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the DependencyProxyBlobRegistry. | +| <a id="dependencyproxyblobregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the DependencyProxyBlobRegistry. | | <a id="dependencyproxyblobregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the DependencyProxyBlobRegistry is reverified. | +| <a id="dependencyproxyblobregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the DependencyProxyBlobRegistry. | +| <a id="dependencyproxyblobregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of DependencyProxyBlobRegistry. | +| <a id="dependencyproxyblobregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the DependencyProxyBlobRegistry. | | <a id="dependencyproxyblobregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the DependencyProxyBlobRegistry. | ### `DependencyProxyImageTtlGroupPolicy` @@ -14289,7 +14919,12 @@ Represents the Geo replication and verification state of a dependency_proxy_mani | <a id="dependencyproxymanifestregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the DependencyProxyManifestRegistry is resynced. | | <a id="dependencyproxymanifestregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the DependencyProxyManifestRegistry. | | <a id="dependencyproxymanifestregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the DependencyProxyManifestRegistry. | +| <a id="dependencyproxymanifestregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the DependencyProxyManifestRegistry. | +| <a id="dependencyproxymanifestregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the DependencyProxyManifestRegistry. | | <a id="dependencyproxymanifestregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the DependencyProxyManifestRegistry is reverified. | +| <a id="dependencyproxymanifestregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the DependencyProxyManifestRegistry. | +| <a id="dependencyproxymanifestregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of DependencyProxyManifestRegistry. | +| <a id="dependencyproxymanifestregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the DependencyProxyManifestRegistry. | | <a id="dependencyproxymanifestregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the DependencyProxyManifestRegistry. | ### `DependencyProxySetting` @@ -14615,7 +15250,12 @@ Represents the Geo replication and verification state of a Design Management Rep | <a id="designmanagementrepositoryregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the DesignManagementRepositoryRegistry is resynced. | | <a id="designmanagementrepositoryregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the DesignManagementRepositoryRegistry. | | <a id="designmanagementrepositoryregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the DesignManagementRepositoryRegistry. | +| <a id="designmanagementrepositoryregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the DesignManagementRepositoryRegistry. | +| <a id="designmanagementrepositoryregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the DesignManagementRepositoryRegistry. | | <a id="designmanagementrepositoryregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the DesignManagementRepositoryRegistry is reverified. | +| <a id="designmanagementrepositoryregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the DesignManagementRepositoryRegistry. | +| <a id="designmanagementrepositoryregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of DesignManagementRepositoryRegistry. | +| <a id="designmanagementrepositoryregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the DesignManagementRepositoryRegistry. | | <a id="designmanagementrepositoryregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the DesignManagementRepositoryRegistry. | ### `DesignVersion` @@ -14739,6 +15379,21 @@ Snapshot. | <a id="devopsadoptionsnapshottotalprojectscount"></a>`totalProjectsCount` | [`Int`](#int) | Total number of projects. | | <a id="devopsadoptionsnapshotvulnerabilitymanagementusedcount"></a>`vulnerabilityManagementUsedCount` | [`Int`](#int) | Total number of projects with vulnerability management used at least once. | +### `Diff` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="diffamode"></a>`aMode` | [`String`](#string) | Old file mode of the file. | +| <a id="diffbmode"></a>`bMode` | [`String`](#string) | New file mode of the file. | +| <a id="diffdeletedfile"></a>`deletedFile` | [`String`](#string) | Indicates if the file has been removed. | +| <a id="diffdiff"></a>`diff` | [`String`](#string) | Diff representation of the changes made to the file. | +| <a id="diffnewfile"></a>`newFile` | [`String`](#string) | Indicates if the file has just been added. | +| <a id="diffnewpath"></a>`newPath` | [`String`](#string) | New path of the file. | +| <a id="diffoldpath"></a>`oldPath` | [`String`](#string) | Old path of the file. | +| <a id="diffrenamedfile"></a>`renamedFile` | [`String`](#string) | Indicates if the file has been renamed. | + ### `DiffPosition` #### Fields @@ -14897,6 +15552,7 @@ Describes where code is deployed for a project. | <a id="environmentdeployfreezes"></a>`deployFreezes` | [`[CiFreezePeriod!]`](#cifreezeperiod) | Deployment freeze periods of the environment. | | <a id="environmentenvironmenttype"></a>`environmentType` | [`String`](#string) | Folder name of the environment. | | <a id="environmentexternalurl"></a>`externalUrl` | [`String`](#string) | External URL of the environment. | +| <a id="environmentfluxresourcepath"></a>`fluxResourcePath` | [`String`](#string) | Flux resource path of the environment. | | <a id="environmentid"></a>`id` | [`ID!`](#id) | ID of the environment. | | <a id="environmentkubernetesnamespace"></a>`kubernetesNamespace` | [`String`](#string) | Kubernetes namespace of the environment. | | <a id="environmentlatestopenedmostseverealert"></a>`latestOpenedMostSevereAlert` | [`AlertManagementAlert`](#alertmanagementalert) | Most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned. | @@ -14959,7 +15615,7 @@ Represents an epic. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="epicauthor"></a>`author` | [`UserCore!`](#usercore) | Author of the epic. | -| <a id="epicawardemoji"></a>`awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | List of award emojis associated with the epic. (see [Connections](#connections)) | +| <a id="epicawardemoji"></a>`awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | List of emoji reactions associated with the epic. (see [Connections](#connections)) | | <a id="epicblocked"></a>`blocked` | [`Boolean`](#boolean) | Indicates the epic is blocked. | | <a id="epicblockedbycount"></a>`blockedByCount` | [`Int`](#int) | Count of epics blocking this epic. | | <a id="epicblockedbyepics"></a>`blockedByEpics` | [`EpicConnection`](#epicconnection) | Epics blocking this epic. (see [Connections](#connections)) | @@ -15219,7 +15875,8 @@ Relationship between an epic and an issue. | <a id="epicissuediscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | <a id="epicissuedownvotes"></a>`downvotes` | [`Int!`](#int) | Number of downvotes the issue has received. | | <a id="epicissueduedate"></a>`dueDate` | [`Time`](#time) | Due date of the issue. | -| <a id="epicissueemailsdisabled"></a>`emailsDisabled` | [`Boolean!`](#boolean) | Indicates if a project has email notifications disabled: `true` if email notifications are disabled. | +| <a id="epicissueemailsdisabled"></a>`emailsDisabled` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 16.3. Use `emails_enabled`. | +| <a id="epicissueemailsenabled"></a>`emailsEnabled` | [`Boolean!`](#boolean) | Indicates if a project has email notifications disabled: `false` if email notifications are disabled. | | <a id="epicissueepic"></a>`epic` | [`Epic`](#epic) | Epic to which this issue belongs. | | <a id="epicissueepicissueid"></a>`epicIssueId` | [`ID!`](#id) | ID of the epic-issue relation. | | <a id="epicissueescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | Escalation policy associated with the issue. Available for issues which support escalation. | @@ -15438,12 +16095,22 @@ Representing an event. | <a id="eventid"></a>`id` | [`ID!`](#id) | ID of the event. | | <a id="eventupdatedat"></a>`updatedAt` | [`Time!`](#time) | When this event was updated. | +### `ExplainVulnerabilityPresubmissionCheckResults` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="explainvulnerabilitypresubmissioncheckresultspotentialsecretsincode"></a>`potentialSecretsInCode` | [`Boolean!`](#boolean) | This flag is true if we think there might be a secret in the code that would be sent in the LLM prompt. | +| <a id="explainvulnerabilitypresubmissioncheckresultssecretdetectionresult"></a>`secretDetectionResult` | [`Boolean!`](#boolean) | This flag is true if the vulnerability being explained is specifically a secret detection vulnerability. | + ### `ExplainVulnerabilityPrompt` #### Fields | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="explainvulnerabilitypromptpresubmissionchecks"></a>`presubmissionChecks` | [`ExplainVulnerabilityPresubmissionCheckResults!`](#explainvulnerabilitypresubmissioncheckresults) | An object containing booleans. Each booolean indicates the result of a presubmission check: `true` for passed, and `false` for failed. | | <a id="explainvulnerabilitypromptpromptwithcode"></a>`promptWithCode` | [`String`](#string) | AI text prompt generated using the vulnerability's information, including the vulnerable code. | | <a id="explainvulnerabilitypromptpromptwithoutcode"></a>`promptWithoutCode` | [`String`](#string) | AI text prompt generated using the vulnerability's information, excluding the vulnerable code. | @@ -15812,10 +16479,6 @@ four standard [pagination arguments](#connection-pagination-arguments): Find Project registries on this Geo node. Ignored if `geo_project_repository_replication` feature flag is disabled. -WARNING: -**Introduced** in 16.2. -This feature is an Experiment. It can be changed or removed at any time. - Returns [`ProjectRepositoryRegistryConnection`](#projectrepositoryregistryconnection). This field returns a [connection](#connections). It accepts the @@ -15957,7 +16620,7 @@ GPG signature for a signed commit. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="groupactualrepositorysizelimit"></a>`actualRepositorySizeLimit` | [`Float`](#float) | Size limit for repositories in the namespace in bytes. This limit only applies to namespaces under Project limit enforcement. | -| <a id="groupactualsizelimit"></a>`actualSizeLimit` | [`Float`](#float) | Actual storage size limit for the namespace in bytes. This limit is agnostic of enforcement type. | +| <a id="groupactualsizelimit"></a>`actualSizeLimit` | [`Float`](#float) | The actual storage size limit (in bytes) based on the enforcement type of either repository or namespace. This limit is agnostic of enforcement type. | | <a id="groupadditionalpurchasedstoragesize"></a>`additionalPurchasedStorageSize` | [`Float`](#float) | Additional storage purchased for the root namespace in bytes. | | <a id="groupallowstalerunnerpruning"></a>`allowStaleRunnerPruning` | [`Boolean!`](#boolean) | Indicates whether to regularly prune stale group runners. Defaults to false. | | <a id="groupautodevopsenabled"></a>`autoDevopsEnabled` | [`Boolean`](#boolean) | Indicates whether Auto DevOps is enabled for all projects within this group. | @@ -16006,7 +16669,7 @@ GPG signature for a signed commit. | <a id="groupsharewithgrouplock"></a>`shareWithGroupLock` | [`Boolean`](#boolean) | Indicates if sharing a project with another group within this group is prevented. | | <a id="groupsharedrunnerssetting"></a>`sharedRunnersSetting` | [`SharedRunnersSetting`](#sharedrunnerssetting) | Shared runners availability for the namespace and its descendants. | | <a id="groupstats"></a>`stats` | [`GroupStats`](#groupstats) | Group statistics. | -| <a id="groupstoragesizelimit"></a>`storageSizeLimit` | [`Float`](#float) | Storage limit included in the root namespace plan in bytes. This limit only applies to namespaces under Namespace limit enforcement. | +| <a id="groupstoragesizelimit"></a>`storageSizeLimit` | [`Float`](#float) | The storage limit (in bytes) included with the root namespace plan. This limit only applies to namespaces under namespace limit enforcement. | | <a id="groupsubgroupcreationlevel"></a>`subgroupCreationLevel` | [`String`](#string) | Permission level required to create subgroups within the group. | | <a id="grouptemporarystorageincreaseendson"></a>`temporaryStorageIncreaseEndsOn` | [`Time`](#time) | Date until the temporary storage increase is active. | | <a id="grouptimelogcategories"></a>`timelogCategories` **{warning-solid}** | [`TimeTrackingTimelogCategoryConnection`](#timetrackingtimelogcategoryconnection) | **Introduced** in 15.3. This feature is an Experiment. It can be changed or removed at any time. Timelog categories for the namespace. | @@ -16017,6 +16680,7 @@ GPG signature for a signed commit. | <a id="groupvisibility"></a>`visibility` | [`String`](#string) | Visibility of the namespace. | | <a id="groupvulnerabilityscanners"></a>`vulnerabilityScanners` | [`VulnerabilityScannerConnection`](#vulnerabilityscannerconnection) | Vulnerability scanners reported on the project vulnerabilities of the group and its subgroups. (see [Connections](#connections)) | | <a id="groupweburl"></a>`webUrl` | [`String!`](#string) | Web URL of the group. | +| <a id="groupworkitems"></a>`workItems` **{warning-solid}** | [`WorkItemConnection`](#workitemconnection) | **Introduced** in 16.3. This feature is an Experiment. It can be changed or removed at any time. Work items that belong to the namespace. | #### Fields with arguments @@ -16052,6 +16716,18 @@ Returns [`AddOnPurchase`](#addonpurchase). | ---- | ---- | ----------- | | <a id="groupaddonpurchaseaddonname"></a>`addOnName` | [`String!`](#string) | AddOn name. | +##### `Group.autocompleteUsers` + +Search users for autocompletion. + +Returns [`[AutocompletedUser!]`](#autocompleteduser). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="groupautocompleteuserssearch"></a>`search` | [`String`](#string) | Query to search users by name, username, or public email. | + ##### `Group.billableMembersCount` Number of billable users in the group. @@ -16801,6 +17477,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="groupvulnerabilitiesclusteragentid"></a>`clusterAgentId` | [`[ClustersAgentID!]`](#clustersagentid) | Filter vulnerabilities by `cluster_agent_id`. Vulnerabilities with a `reportType` of `cluster_image_scanning` are only included with this filter. | | <a id="groupvulnerabilitiesclusterid"></a>`clusterId` | [`[ClustersClusterID!]`](#clustersclusterid) | Filter vulnerabilities by `cluster_id`. Vulnerabilities with a `reportType` of `cluster_image_scanning` are only included with this filter. | +| <a id="groupvulnerabilitiesdismissalreason"></a>`dismissalReason` | [`[VulnerabilityDismissalReason!]`](#vulnerabilitydismissalreason) | Filter by dismissal reason. Only dismissed Vulnerabilities will be included with the filter. | | <a id="groupvulnerabilitieshasissues"></a>`hasIssues` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have linked issues. | | <a id="groupvulnerabilitieshasresolution"></a>`hasResolution` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have been resolved on default branch. | | <a id="groupvulnerabilitiesimage"></a>`image` | [`[String!]`](#string) | Filter vulnerabilities by location image. When this filter is present, the response only matches entries for a `reportType` that includes `container_scanning`, `cluster_image_scanning`. | @@ -16926,6 +17603,7 @@ Returns [`UserMergeRequestInteraction`](#usermergerequestinteraction). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="grouppermissionscreatecustomemoji"></a>`createCustomEmoji` | [`Boolean!`](#boolean) | Indicates the user can perform `create_custom_emoji` on this resource. | | <a id="grouppermissionscreateprojects"></a>`createProjects` | [`Boolean!`](#boolean) | Indicates the user can perform `create_projects` on this resource. | | <a id="grouppermissionsreadgroup"></a>`readGroup` | [`Boolean!`](#boolean) | Indicates the user can perform `read_group` on this resource. | @@ -17069,7 +17747,12 @@ Represents the Geo sync and verification state of a group wiki repository. | <a id="groupwikirepositoryregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the GroupWikiRepositoryRegistry is resynced. | | <a id="groupwikirepositoryregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the GroupWikiRepositoryRegistry. | | <a id="groupwikirepositoryregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the GroupWikiRepositoryRegistry. | +| <a id="groupwikirepositoryregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the GroupWikiRepositoryRegistry. | +| <a id="groupwikirepositoryregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the GroupWikiRepositoryRegistry. | | <a id="groupwikirepositoryregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the GroupWikiRepositoryRegistry is reverified. | +| <a id="groupwikirepositoryregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the GroupWikiRepositoryRegistry. | +| <a id="groupwikirepositoryregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of GroupWikiRepositoryRegistry. | +| <a id="groupwikirepositoryregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the GroupWikiRepositoryRegistry. | | <a id="groupwikirepositoryregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the GroupWikiRepositoryRegistry. | ### `HelmFileMetadata` @@ -17322,7 +18005,8 @@ Describes an issuable resource link for incident issues. | <a id="issuediscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | <a id="issuedownvotes"></a>`downvotes` | [`Int!`](#int) | Number of downvotes the issue has received. | | <a id="issueduedate"></a>`dueDate` | [`Time`](#time) | Due date of the issue. | -| <a id="issueemailsdisabled"></a>`emailsDisabled` | [`Boolean!`](#boolean) | Indicates if a project has email notifications disabled: `true` if email notifications are disabled. | +| <a id="issueemailsdisabled"></a>`emailsDisabled` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 16.3. Use `emails_enabled`. | +| <a id="issueemailsenabled"></a>`emailsEnabled` | [`Boolean!`](#boolean) | Indicates if a project has email notifications disabled: `false` if email notifications are disabled. | | <a id="issueepic"></a>`epic` | [`Epic`](#epic) | Epic to which this issue belongs. | | <a id="issueescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | Escalation policy associated with the issue. Available for issues which support escalation. | | <a id="issueescalationstatus"></a>`escalationStatus` | [`IssueEscalationStatus`](#issueescalationstatus) | Escalation status of the issue. | @@ -17603,7 +18287,12 @@ Represents the Geo replication and verification state of a job_artifact. | <a id="jobartifactregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the JobArtifactRegistry is resynced. | | <a id="jobartifactregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the JobArtifactRegistry. | | <a id="jobartifactregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the JobArtifactRegistry. | +| <a id="jobartifactregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the JobArtifactRegistry. | +| <a id="jobartifactregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the JobArtifactRegistry. | | <a id="jobartifactregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the JobArtifactRegistry is reverified. | +| <a id="jobartifactregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the JobArtifactRegistry. | +| <a id="jobartifactregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of JobArtifactRegistry. | +| <a id="jobartifactregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the JobArtifactRegistry. | | <a id="jobartifactregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the JobArtifactRegistry. | ### `JobPermissions` @@ -17671,7 +18360,12 @@ Represents the Geo sync and verification state of an LFS object. | <a id="lfsobjectregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the LfsObjectRegistry is resynced. | | <a id="lfsobjectregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the LfsObjectRegistry. | | <a id="lfsobjectregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the LfsObjectRegistry. | +| <a id="lfsobjectregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the LfsObjectRegistry. | +| <a id="lfsobjectregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the LfsObjectRegistry. | | <a id="lfsobjectregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the LfsObjectRegistry is reverified. | +| <a id="lfsobjectregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the LfsObjectRegistry. | +| <a id="lfsobjectregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of LfsObjectRegistry. | +| <a id="lfsobjectregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the LfsObjectRegistry. | | <a id="lfsobjectregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the LfsObjectRegistry. | ### `LicenseHistoryEntry` @@ -17695,6 +18389,18 @@ Represents an entry from the Cloud License history. | <a id="licensehistoryentrytype"></a>`type` | [`String!`](#string) | Type of the license. | | <a id="licensehistoryentryusersinlicensecount"></a>`usersInLicenseCount` | [`Int`](#int) | Number of paid users in the license. | +### `LinkedWorkItemType` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="linkedworkitemtypelinkcreatedat"></a>`linkCreatedAt` | [`Time!`](#time) | Timestamp the link was created. | +| <a id="linkedworkitemtypelinkid"></a>`linkId` | [`WorkItemsRelatedWorkItemLinkID!`](#workitemsrelatedworkitemlinkid) | Global ID of the link. | +| <a id="linkedworkitemtypelinktype"></a>`linkType` | [`String!`](#string) | Type of link. | +| <a id="linkedworkitemtypelinkupdatedat"></a>`linkUpdatedAt` | [`Time!`](#time) | Timestamp the link was updated. | +| <a id="linkedworkitemtypeworkitem"></a>`workItem` | [`WorkItem!`](#workitem) | Linked work item. | + ### `Location` #### Fields @@ -17743,14 +18449,14 @@ Defines which user roles, users, or groups can merge into a protected branch. | <a id="mergerequestapprovalstate"></a>`approvalState` | [`MergeRequestApprovalState!`](#mergerequestapprovalstate) | Information relating to rules that must be satisfied to merge this merge request. | | <a id="mergerequestapprovalsleft"></a>`approvalsLeft` | [`Int`](#int) | Number of approvals left. | | <a id="mergerequestapprovalsrequired"></a>`approvalsRequired` | [`Int`](#int) | Number of approvals required. | -| <a id="mergerequestapproved"></a>`approved` | [`Boolean!`](#boolean) | Indicates if the merge request has all the required approvals. Returns true if no required approvals are configured. | +| <a id="mergerequestapproved"></a>`approved` | [`Boolean!`](#boolean) | Indicates if the merge request has all the required approvals. | | <a id="mergerequestapprovedby"></a>`approvedBy` | [`UserCoreConnection`](#usercoreconnection) | Users who approved the merge request. (see [Connections](#connections)) | | <a id="mergerequestassignees"></a>`assignees` | [`MergeRequestAssigneeConnection`](#mergerequestassigneeconnection) | Assignees of the merge request. (see [Connections](#connections)) | | <a id="mergerequestauthor"></a>`author` | [`MergeRequestAuthor`](#mergerequestauthor) | User who created this merge request. | | <a id="mergerequestautomergeenabled"></a>`autoMergeEnabled` | [`Boolean!`](#boolean) | Indicates if auto merge is enabled for the merge request. | | <a id="mergerequestautomergestrategy"></a>`autoMergeStrategy` | [`String`](#string) | Selected auto merge strategy. | | <a id="mergerequestavailableautomergestrategies"></a>`availableAutoMergeStrategies` | [`[String!]`](#string) | Array of available auto merge strategies. | -| <a id="mergerequestawardemoji"></a>`awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | List of award emojis associated with the merge request. (see [Connections](#connections)) | +| <a id="mergerequestawardemoji"></a>`awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | List of emoji reactions associated with the merge request. (see [Connections](#connections)) | | <a id="mergerequestcommenters"></a>`commenters` | [`UserCoreConnection!`](#usercoreconnection) | All commenters on this noteable. (see [Connections](#connections)) | | <a id="mergerequestcommitcount"></a>`commitCount` | [`Int`](#int) | Number of commits in the merge request. | | <a id="mergerequestcommits"></a>`commits` | [`CommitConnection`](#commitconnection) | Merge request commits. (see [Connections](#connections)) | @@ -18532,7 +19238,12 @@ Represents the Geo sync and verification state of a Merge Request diff. | <a id="mergerequestdiffregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the MergeRequestDiffRegistry is resynced. | | <a id="mergerequestdiffregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the MergeRequestDiffRegistry. | | <a id="mergerequestdiffregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the MergeRequestDiffRegistry. | +| <a id="mergerequestdiffregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the MergeRequestDiffRegistry. | +| <a id="mergerequestdiffregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the MergeRequestDiffRegistry. | | <a id="mergerequestdiffregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the MergeRequestDiffRegistry is reverified. | +| <a id="mergerequestdiffregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the MergeRequestDiffRegistry. | +| <a id="mergerequestdiffregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of MergeRequestDiffRegistry. | +| <a id="mergerequestdiffregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the MergeRequestDiffRegistry. | | <a id="mergerequestdiffregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the MergeRequestDiffRegistry. | ### `MergeRequestParticipant` @@ -19224,7 +19935,7 @@ Contains statistics about a milestone. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="namespaceactualrepositorysizelimit"></a>`actualRepositorySizeLimit` | [`Float`](#float) | Size limit for repositories in the namespace in bytes. This limit only applies to namespaces under Project limit enforcement. | -| <a id="namespaceactualsizelimit"></a>`actualSizeLimit` | [`Float`](#float) | Actual storage size limit for the namespace in bytes. This limit is agnostic of enforcement type. | +| <a id="namespaceactualsizelimit"></a>`actualSizeLimit` | [`Float`](#float) | The actual storage size limit (in bytes) based on the enforcement type of either repository or namespace. This limit is agnostic of enforcement type. | | <a id="namespaceadditionalpurchasedstoragesize"></a>`additionalPurchasedStorageSize` | [`Float`](#float) | Additional storage purchased for the root namespace in bytes. | | <a id="namespacecontainslockedprojects"></a>`containsLockedProjects` | [`Boolean!`](#boolean) | Includes at least one project where the repository size exceeds the limit. This only applies to namespaces under Project limit enforcement. | | <a id="namespacecrossprojectpipelineavailable"></a>`crossProjectPipelineAvailable` | [`Boolean!`](#boolean) | Indicates if the cross_project_pipeline feature is available for the namespace. | @@ -19242,7 +19953,7 @@ Contains statistics about a milestone. | <a id="namespacerequestaccessenabled"></a>`requestAccessEnabled` | [`Boolean`](#boolean) | Indicates if users can request access to namespace. | | <a id="namespacerootstoragestatistics"></a>`rootStorageStatistics` | [`RootStorageStatistics`](#rootstoragestatistics) | Aggregated storage statistics of the namespace. Only available for root namespaces. | | <a id="namespacesharedrunnerssetting"></a>`sharedRunnersSetting` | [`SharedRunnersSetting`](#sharedrunnerssetting) | Shared runners availability for the namespace and its descendants. | -| <a id="namespacestoragesizelimit"></a>`storageSizeLimit` | [`Float`](#float) | Storage limit included in the root namespace plan in bytes. This limit only applies to namespaces under Namespace limit enforcement. | +| <a id="namespacestoragesizelimit"></a>`storageSizeLimit` | [`Float`](#float) | The storage limit (in bytes) included with the root namespace plan. This limit only applies to namespaces under namespace limit enforcement. | | <a id="namespacetemporarystorageincreaseendson"></a>`temporaryStorageIncreaseEndsOn` | [`Time`](#time) | Date until the temporary storage increase is active. | | <a id="namespacetimelogcategories"></a>`timelogCategories` **{warning-solid}** | [`TimeTrackingTimelogCategoryConnection`](#timetrackingtimelogcategoryconnection) | **Introduced** in 15.3. This feature is an Experiment. It can be changed or removed at any time. Timelog categories for the namespace. | | <a id="namespacetotalrepositorysize"></a>`totalRepositorySize` | [`Float`](#float) | Total repository size of all projects in the root namespace in bytes. | @@ -19426,7 +20137,7 @@ Represents the network policy. | ---- | ---- | ----------- | | <a id="noteauthor"></a>`author` | [`UserCore!`](#usercore) | User who wrote this note. | | <a id="noteauthoriscontributor"></a>`authorIsContributor` | [`Boolean`](#boolean) | Indicates whether the note author is a contributor. | -| <a id="noteawardemoji"></a>`awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | List of award emojis associated with the note. (see [Connections](#connections)) | +| <a id="noteawardemoji"></a>`awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | List of emoji reactions associated with the note. (see [Connections](#connections)) | | <a id="notebody"></a>`body` | [`String!`](#string) | Content of the note. | | <a id="notebodyhtml"></a>`bodyHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `note`. | | <a id="noteconfidential"></a>`confidential` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated** in 15.5. This was renamed. Use: `internal`. | @@ -19674,7 +20385,12 @@ Represents the Geo sync and verification state of a package file. | <a id="packagefileregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the PackageFileRegistry is resynced. | | <a id="packagefileregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the PackageFileRegistry. | | <a id="packagefileregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the PackageFileRegistry. | +| <a id="packagefileregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the PackageFileRegistry. | +| <a id="packagefileregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the PackageFileRegistry. | | <a id="packagefileregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the PackageFileRegistry is reverified. | +| <a id="packagefileregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the PackageFileRegistry. | +| <a id="packagefileregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of PackageFileRegistry. | +| <a id="packagefileregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the PackageFileRegistry. | | <a id="packagefileregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the PackageFileRegistry. | ### `PackageHelmDependencyType` @@ -19761,6 +20477,8 @@ Namespace-level Package Registry settings. | <a id="packagesettingsmavenpackagerequestsforwardinglocked"></a>`mavenPackageRequestsForwardingLocked` | [`Boolean!`](#boolean) | Indicates whether Maven package forwarding settings are locked by a parent namespace. | | <a id="packagesettingsnpmpackagerequestsforwarding"></a>`npmPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether npm package forwarding is allowed for this namespace. | | <a id="packagesettingsnpmpackagerequestsforwardinglocked"></a>`npmPackageRequestsForwardingLocked` | [`Boolean!`](#boolean) | Indicates whether npm package forwarding settings are locked by a parent namespace. | +| <a id="packagesettingsnugetduplicateexceptionregex"></a>`nugetDuplicateExceptionRegex` | [`UntrustedRegexp`](#untrustedregexp) | When nuget_duplicates_allowed is false, you can publish duplicate packages with names that match this regex. Otherwise, this setting has no effect. Error is raised if `nuget_duplicates_option` feature flag is disabled. | +| <a id="packagesettingsnugetduplicatesallowed"></a>`nugetDuplicatesAllowed` | [`Boolean!`](#boolean) | Indicates whether duplicate NuGet packages are allowed for this namespace. Error is raised if `nuget_duplicates_option` feature flag is disabled. | | <a id="packagesettingspypipackagerequestsforwarding"></a>`pypiPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether PyPI package forwarding is allowed for this namespace. | | <a id="packagesettingspypipackagerequestsforwardinglocked"></a>`pypiPackageRequestsForwardingLocked` | [`Boolean!`](#boolean) | Indicates whether PyPI package forwarding settings are locked by a parent namespace. | @@ -19817,7 +20535,12 @@ Represents the Geo replication and verification state of a pages_deployment. | <a id="pagesdeploymentregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the PagesDeploymentRegistry is resynced. | | <a id="pagesdeploymentregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the PagesDeploymentRegistry. | | <a id="pagesdeploymentregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the PagesDeploymentRegistry. | +| <a id="pagesdeploymentregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the PagesDeploymentRegistry. | +| <a id="pagesdeploymentregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the PagesDeploymentRegistry. | | <a id="pagesdeploymentregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the PagesDeploymentRegistry is reverified. | +| <a id="pagesdeploymentregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the PagesDeploymentRegistry. | +| <a id="pagesdeploymentregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of PagesDeploymentRegistry. | +| <a id="pagesdeploymentregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the PagesDeploymentRegistry. | | <a id="pagesdeploymentregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the PagesDeploymentRegistry. | ### `PathLock` @@ -20003,7 +20726,12 @@ Represents the Geo sync and verification state of a pipeline artifact. | <a id="pipelineartifactregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the PipelineArtifactRegistry is resynced. | | <a id="pipelineartifactregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the PipelineArtifactRegistry. | | <a id="pipelineartifactregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the PipelineArtifactRegistry. | +| <a id="pipelineartifactregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the PipelineArtifactRegistry. | +| <a id="pipelineartifactregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the PipelineArtifactRegistry. | | <a id="pipelineartifactregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the PipelineArtifactRegistry is reverified. | +| <a id="pipelineartifactregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the PipelineArtifactRegistry. | +| <a id="pipelineartifactregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of PipelineArtifactRegistry. | +| <a id="pipelineartifactregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the PipelineArtifactRegistry. | | <a id="pipelineartifactregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the PipelineArtifactRegistry. | ### `PipelineCounts` @@ -20124,6 +20852,31 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="pipelinesecurityreportfindinguuid"></a>`uuid` | [`String`](#string) | UUIDv5 digest based on the vulnerability's report type, primary identifier, location, fingerprint, project identifier. | | <a id="pipelinesecurityreportfindingvulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability related to the security report finding. | +### `PipelineTrigger` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="pipelinetriggercanaccessproject"></a>`canAccessProject` | [`Boolean!`](#boolean) | Indicates if the pipeline trigger token has access to the project. | +| <a id="pipelinetriggerdescription"></a>`description` | [`String`](#string) | Description of the pipeline trigger token. | +| <a id="pipelinetriggerhastokenexposed"></a>`hasTokenExposed` | [`Boolean!`](#boolean) | Indicates if the token is exposed. | +| <a id="pipelinetriggerid"></a>`id` | [`ID!`](#id) | ID of the pipeline trigger token. | +| <a id="pipelinetriggerlastused"></a>`lastUsed` | [`Time`](#time) | Timestamp of the last usage of the pipeline trigger token. | +| <a id="pipelinetriggerowner"></a>`owner` | [`UserCore!`](#usercore) | Owner of the pipeline trigger token. | +| <a id="pipelinetriggertoken"></a>`token` | [`String!`](#string) | Value of the pipeline trigger token. | + +### `PolicyApprovalGroup` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="policyapprovalgroupavatarurl"></a>`avatarUrl` | [`String`](#string) | Avatar URL of the group. | +| <a id="policyapprovalgroupfullpath"></a>`fullPath` | [`ID!`](#id) | Full path of the namespace. | +| <a id="policyapprovalgroupid"></a>`id` | [`ID!`](#id) | ID of the namespace. | +| <a id="policyapprovalgroupweburl"></a>`webUrl` | [`String!`](#string) | Web URL of the group. | + ### `PreviewBillableUserChange` #### Fields @@ -20170,6 +20923,7 @@ Represents a product analytics dashboard visualization. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="productanalyticsdashboardvisualizationdata"></a>`data` | [`JSON!`](#json) | Data of the visualization. | +| <a id="productanalyticsdashboardvisualizationerrors"></a>`errors` | [`[String!]`](#string) | Validation errors in the visualization. | | <a id="productanalyticsdashboardvisualizationoptions"></a>`options` | [`JSON!`](#json) | Options of the visualization. | | <a id="productanalyticsdashboardvisualizationslug"></a>`slug` | [`String!`](#string) | Slug of the visualization. | | <a id="productanalyticsdashboardvisualizationtype"></a>`type` | [`String!`](#string) | Type of the visualization. | @@ -20238,6 +20992,7 @@ Represents a product analytics dashboard visualization. | <a id="projectpath"></a>`path` | [`String!`](#string) | Path of the project. | | <a id="projectpathlocks"></a>`pathLocks` | [`PathLockConnection`](#pathlockconnection) | The project's path locks. (see [Connections](#connections)) | | <a id="projectpipelineanalytics"></a>`pipelineAnalytics` | [`PipelineAnalytics`](#pipelineanalytics) | Pipeline analytics. | +| <a id="projectpipelinetriggers"></a>`pipelineTriggers` **{warning-solid}** | [`PipelineTriggerConnection`](#pipelinetriggerconnection) | **Introduced** in 16.3. This feature is an Experiment. It can be changed or removed at any time. List of pipeline trigger tokens. | | <a id="projectprintingmergerequestlinkenabled"></a>`printingMergeRequestLinkEnabled` | [`Boolean`](#boolean) | Indicates if a link to create or view a merge request should display after a push to Git repositories of the project from the command line. | | <a id="projectproductanalyticsinstrumentationkey"></a>`productAnalyticsInstrumentationKey` **{warning-solid}** | [`String`](#string) | **Introduced** in 16.0. This feature is an Experiment. It can be changed or removed at any time. Product Analytics instrumentation key assigned to the project. | | <a id="projectproductanalyticsstate"></a>`productAnalyticsState` **{warning-solid}** | [`ProductAnalyticsState`](#productanalyticsstate) | **Introduced** in 15.10. This feature is an Experiment. It can be changed or removed at any time. Current state of the product analytics stack for this project.Can only be called for one project in a single request. | @@ -20374,6 +21129,18 @@ Returns [`[AlertManagementPayloadAlertField!]`](#alertmanagementpayloadalertfiel | ---- | ---- | ----------- | | <a id="projectalertmanagementpayloadfieldspayloadexample"></a>`payloadExample` | [`String!`](#string) | Sample payload for extracting alert fields for custom mappings. | +##### `Project.autocompleteUsers` + +Search users for autocompletion. + +Returns [`[AutocompletedUser!]`](#autocompleteduser). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectautocompleteuserssearch"></a>`search` | [`String`](#string) | Query to search users by name, username, or public email. | + ##### `Project.board` A single board of the project. @@ -21571,6 +22338,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="projectvulnerabilitiesclusteragentid"></a>`clusterAgentId` | [`[ClustersAgentID!]`](#clustersagentid) | Filter vulnerabilities by `cluster_agent_id`. Vulnerabilities with a `reportType` of `cluster_image_scanning` are only included with this filter. | | <a id="projectvulnerabilitiesclusterid"></a>`clusterId` | [`[ClustersClusterID!]`](#clustersclusterid) | Filter vulnerabilities by `cluster_id`. Vulnerabilities with a `reportType` of `cluster_image_scanning` are only included with this filter. | +| <a id="projectvulnerabilitiesdismissalreason"></a>`dismissalReason` | [`[VulnerabilityDismissalReason!]`](#vulnerabilitydismissalreason) | Filter by dismissal reason. Only dismissed Vulnerabilities will be included with the filter. | | <a id="projectvulnerabilitieshasissues"></a>`hasIssues` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have linked issues. | | <a id="projectvulnerabilitieshasresolution"></a>`hasResolution` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have been resolved on default branch. | | <a id="projectvulnerabilitiesimage"></a>`image` | [`[String!]`](#string) | Filter vulnerabilities by location image. When this filter is present, the response only matches entries for a `reportType` that includes `container_scanning`, `cluster_image_scanning`. | @@ -21794,7 +22562,12 @@ Represents the Geo replication and verification state of a project repository. | <a id="projectrepositoryregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the ProjectRepositoryRegistry is resynced. | | <a id="projectrepositoryregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the ProjectRepositoryRegistry. | | <a id="projectrepositoryregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the ProjectRepositoryRegistry. | +| <a id="projectrepositoryregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the ProjectRepositoryRegistry. | +| <a id="projectrepositoryregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the ProjectRepositoryRegistry. | | <a id="projectrepositoryregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the ProjectRepositoryRegistry is reverified. | +| <a id="projectrepositoryregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the ProjectRepositoryRegistry. | +| <a id="projectrepositoryregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of ProjectRepositoryRegistry. | +| <a id="projectrepositoryregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the ProjectRepositoryRegistry. | | <a id="projectrepositoryregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the ProjectRepositoryRegistry. | ### `ProjectSecurityPolicySource` @@ -21956,7 +22729,12 @@ Represents the Geo replication and verification state of a project_wiki_reposito | <a id="projectwikirepositoryregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the ProjectWikiRepositoryRegistry is resynced. | | <a id="projectwikirepositoryregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the ProjectWikiRepositoryRegistry. | | <a id="projectwikirepositoryregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the ProjectWikiRepositoryRegistry. | +| <a id="projectwikirepositoryregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the ProjectWikiRepositoryRegistry. | +| <a id="projectwikirepositoryregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the ProjectWikiRepositoryRegistry. | | <a id="projectwikirepositoryregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the ProjectWikiRepositoryRegistry is reverified. | +| <a id="projectwikirepositoryregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the ProjectWikiRepositoryRegistry. | +| <a id="projectwikirepositoryregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of ProjectWikiRepositoryRegistry. | +| <a id="projectwikirepositoryregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the ProjectWikiRepositoryRegistry. | | <a id="projectwikirepositoryregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the ProjectWikiRepositoryRegistry. | ### `PrometheusAlert` @@ -22037,6 +22815,7 @@ Defines which user roles, users, or groups can push to a protected branch. | ---- | ---- | ----------- | | <a id="pushaccesslevelaccesslevel"></a>`accessLevel` | [`Int!`](#int) | GitLab::Access level. | | <a id="pushaccesslevelaccessleveldescription"></a>`accessLevelDescription` | [`String!`](#string) | Human readable representation for this access level. | +| <a id="pushaccessleveldeploykey"></a>`deployKey` | [`AccessLevelDeployKey`](#accessleveldeploykey) | Deploy key assigned to the access level. | | <a id="pushaccesslevelgroup"></a>`group` | [`AccessLevelGroup`](#accesslevelgroup) | Group associated with this access level. | | <a id="pushaccessleveluser"></a>`user` | [`AccessLevelUser`](#accessleveluser) | User associated with this access level. | @@ -22272,6 +23051,7 @@ Returns [`RepositoryCodeownerValidation`](#repositorycodeownervalidation). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="repositoryvalidatecodeownerfilepath"></a>`path` | [`String`](#string) | Path of a file called CODEOWNERS that should be validated. Default to file in use. | | <a id="repositoryvalidatecodeownerfileref"></a>`ref` | [`String`](#string) | Ref where code owners file needs to be checked. Defaults to the repository's default branch. | ### `RepositoryBlob` @@ -22576,6 +23356,7 @@ Represents the scan result policy. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="scanresultpolicyallgroupapprovers"></a>`allGroupApprovers` | [`[PolicyApprovalGroup!]`](#policyapprovalgroup) | All potential approvers of the group type, including groups inaccessible to the user. | | <a id="scanresultpolicydescription"></a>`description` | [`String!`](#string) | Description of the policy. | | <a id="scanresultpolicyenabled"></a>`enabled` | [`Boolean!`](#boolean) | Indicates whether this policy is enabled. | | <a id="scanresultpolicygroupapprovers"></a>`groupApprovers` | [`[Group!]`](#group) | Approvers of the group type. | @@ -22953,7 +23734,12 @@ Represents the Geo sync and verification state of a snippet repository. | <a id="snippetrepositoryregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the SnippetRepositoryRegistry. | | <a id="snippetrepositoryregistrysnippetrepositoryid"></a>`snippetRepositoryId` | [`ID!`](#id) | ID of the Snippet Repository. | | <a id="snippetrepositoryregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the SnippetRepositoryRegistry. | +| <a id="snippetrepositoryregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the SnippetRepositoryRegistry. | +| <a id="snippetrepositoryregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the SnippetRepositoryRegistry. | | <a id="snippetrepositoryregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the SnippetRepositoryRegistry is reverified. | +| <a id="snippetrepositoryregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the SnippetRepositoryRegistry. | +| <a id="snippetrepositoryregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of SnippetRepositoryRegistry. | +| <a id="snippetrepositoryregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the SnippetRepositoryRegistry. | | <a id="snippetrepositoryregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the SnippetRepositoryRegistry. | ### `SshSignature` @@ -23095,7 +23881,12 @@ Represents the Geo sync and verification state of a terraform state version. | <a id="terraformstateversionregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the TerraformStateVersionRegistry. | | <a id="terraformstateversionregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the TerraformStateVersionRegistry. | | <a id="terraformstateversionregistryterraformstateversionid"></a>`terraformStateVersionId` | [`ID!`](#id) | ID of the terraform state version. | +| <a id="terraformstateversionregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the TerraformStateVersionRegistry. | +| <a id="terraformstateversionregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the TerraformStateVersionRegistry. | | <a id="terraformstateversionregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the TerraformStateVersionRegistry is reverified. | +| <a id="terraformstateversionregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the TerraformStateVersionRegistry. | +| <a id="terraformstateversionregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of TerraformStateVersionRegistry. | +| <a id="terraformstateversionregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the TerraformStateVersionRegistry. | | <a id="terraformstateversionregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the TerraformStateVersionRegistry. | ### `TestCase` @@ -23402,7 +24193,12 @@ Represents the Geo replication and verification state of an upload. | <a id="uploadregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the UploadRegistry is resynced. | | <a id="uploadregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the UploadRegistry. | | <a id="uploadregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the UploadRegistry. | +| <a id="uploadregistryverificationchecksum"></a>`verificationChecksum` | [`String`](#string) | The local checksum of the UploadRegistry. | +| <a id="uploadregistryverificationfailure"></a>`verificationFailure` | [`String`](#string) | Error message during verification of the UploadRegistry. | | <a id="uploadregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the UploadRegistry is reverified. | +| <a id="uploadregistryverificationretrycount"></a>`verificationRetryCount` | [`Int`](#int) | Number of consecutive failed verification attempts of the UploadRegistry. | +| <a id="uploadregistryverificationstartedat"></a>`verificationStartedAt` | [`Time`](#time) | Timestamp when the verification started of UploadRegistry. | +| <a id="uploadregistryverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Verification state of the UploadRegistry. | | <a id="uploadregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the UploadRegistry. | ### `UsageTrendsMeasurement` @@ -23822,12 +24618,13 @@ Represents a vulnerability. | <a id="vulnerabilitydetails"></a>`details` | [`[VulnerabilityDetail!]!`](#vulnerabilitydetail) | Details of the vulnerability. | | <a id="vulnerabilitydetectedat"></a>`detectedAt` | [`Time!`](#time) | Timestamp of when the vulnerability was first detected. | | <a id="vulnerabilitydiscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | -| <a id="vulnerabilitydismissalreason"></a>`dismissalReason` | [`VulnerabilityDismissalReason`](#vulnerabilitydismissalreason) | Reason for dismissal. Returns `null` if `expose_dismissal_reason`feature flag is disabled. | +| <a id="vulnerabilitydismissalreason"></a>`dismissalReason` | [`VulnerabilityDismissalReason`](#vulnerabilitydismissalreason) | Reason for dismissal. Returns `null` for states other than `dismissed`. Returns `null` if `expose_dismissal_reason` feature flag is disabled. | | <a id="vulnerabilitydismissedat"></a>`dismissedAt` | [`Time`](#time) | Timestamp of when the vulnerability state was changed to dismissed. | | <a id="vulnerabilitydismissedby"></a>`dismissedBy` | [`UserCore`](#usercore) | User that dismissed the vulnerability. | | <a id="vulnerabilityexternalissuelinks"></a>`externalIssueLinks` | [`VulnerabilityExternalIssueLinkConnection!`](#vulnerabilityexternalissuelinkconnection) | List of external issue links related to the vulnerability. (see [Connections](#connections)) | | <a id="vulnerabilityfalsepositive"></a>`falsePositive` | [`Boolean`](#boolean) | Indicates whether the vulnerability is a false positive. | -| <a id="vulnerabilityhassolutions"></a>`hasSolutions` | [`Boolean`](#boolean) | Indicates whether there is a solution available for this vulnerability. | +| <a id="vulnerabilityhasremediations"></a>`hasRemediations` | [`Boolean`](#boolean) | Indicates whether there is a remediation available for this vulnerability. | +| <a id="vulnerabilityhassolutions"></a>`hasSolutions` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated** in 16.3. Use `hasRemediations`. | | <a id="vulnerabilityid"></a>`id` | [`ID!`](#id) | GraphQL ID of the vulnerability. | | <a id="vulnerabilityidentifiers"></a>`identifiers` | [`[VulnerabilityIdentifier!]!`](#vulnerabilityidentifier) | Identifiers of the vulnerability. | | <a id="vulnerabilitylinks"></a>`links` | [`[VulnerabilityLink!]!`](#vulnerabilitylink) | List of links associated with the vulnerability. | @@ -24530,13 +25327,13 @@ Represents an assignees widget. ### `WorkItemWidgetAwardEmoji` -Represents the award emoji widget. +Represents the emoji reactions widget. #### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="workitemwidgetawardemojiawardemoji"></a>`awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | Award emoji on the work item. (see [Connections](#connections)) | +| <a id="workitemwidgetawardemojiawardemoji"></a>`awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | Emoji reactions on the work item. (see [Connections](#connections)) | | <a id="workitemwidgetawardemojidownvotes"></a>`downvotes` | [`Int!`](#int) | Number of downvotes the work item has received. | | <a id="workitemwidgetawardemojitype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | | <a id="workitemwidgetawardemojiupvotes"></a>`upvotes` | [`Int!`](#int) | Number of upvotes the work item has received. | @@ -24631,6 +25428,20 @@ Represents the labels widget. | <a id="workitemwidgetlabelslabels"></a>`labels` | [`LabelConnection`](#labelconnection) | Labels assigned to the work item. (see [Connections](#connections)) | | <a id="workitemwidgetlabelstype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | +### `WorkItemWidgetLinkedItems` + +Represents the linked items widget. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgetlinkeditemsblocked"></a>`blocked` | [`Boolean`](#boolean) | Indicates the work item is blocked. Returns `null`if `linked_work_items` feature flag is disabled. | +| <a id="workitemwidgetlinkeditemsblockedbycount"></a>`blockedByCount` | [`Int`](#int) | Count of items blocking the work item. Returns `null`if `linked_work_items` feature flag is disabled. | +| <a id="workitemwidgetlinkeditemsblockingcount"></a>`blockingCount` | [`Int`](#int) | Count of items the work item is blocking. Returns `null`if `linked_work_items` feature flag is disabled. | +| <a id="workitemwidgetlinkeditemslinkeditems"></a>`linkedItems` **{warning-solid}** | [`LinkedWorkItemTypeConnection`](#linkedworkitemtypeconnection) | **Introduced** in 16.3. This feature is an Experiment. It can be changed or removed at any time. Linked items for the work item. Returns `null`if `linked_work_items` feature flag is disabled. | +| <a id="workitemwidgetlinkeditemstype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | + ### `WorkItemWidgetMilestone` Represents a milestone widget. @@ -24689,7 +25500,10 @@ Represents a progress widget. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="workitemwidgetprogresscurrentvalue"></a>`currentValue` | [`Int`](#int) | Current value of the work item. | +| <a id="workitemwidgetprogressendvalue"></a>`endValue` | [`Int`](#int) | End value of the work item. | | <a id="workitemwidgetprogressprogress"></a>`progress` | [`Int`](#int) | Progress of the work item. | +| <a id="workitemwidgetprogressstartvalue"></a>`startValue` | [`Int`](#int) | Start value of the work item. | | <a id="workitemwidgetprogresstype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | | <a id="workitemwidgetprogressupdatedat"></a>`updatedAt` | [`Time`](#time) | Timestamp of last progress update. | @@ -25259,7 +26073,9 @@ Name of the check for the compliance standard. | Value | Description | | ----- | ----------- | +| <a id="compliancestandardsadherencechecknameat_least_two_approvals"></a>`AT_LEAST_TWO_APPROVALS` | At least two approvals. | | <a id="compliancestandardsadherencechecknameprevent_approval_by_merge_request_author"></a>`PREVENT_APPROVAL_BY_MERGE_REQUEST_AUTHOR` | Prevent approval by merge request author. | +| <a id="compliancestandardsadherencechecknameprevent_approval_by_merge_request_committers"></a>`PREVENT_APPROVAL_BY_MERGE_REQUEST_COMMITTERS` | Prevent approval by merge request committers. | ### `ComplianceStandardsAdherenceStandard` @@ -25673,6 +26489,7 @@ Type of file the position refers to. | Value | Description | | ----- | ----------- | +| <a id="diffpositiontypefile"></a>`file` | Unknown file type. | | <a id="diffpositiontypeimage"></a>`image` | An image. | | <a id="diffpositiontypetext"></a>`text` | Text file. | @@ -25823,6 +26640,7 @@ Geo registry class. | <a id="georegistryclassdependency_proxy_blob_registry"></a>`DEPENDENCY_PROXY_BLOB_REGISTRY` | Geo::DependencyProxyBlobRegistry registry class. | | <a id="georegistryclassdependency_proxy_manifest_registry"></a>`DEPENDENCY_PROXY_MANIFEST_REGISTRY` | Geo::DependencyProxyManifestRegistry registry class. | | <a id="georegistryclassdesign_management_repository_registry"></a>`DESIGN_MANAGEMENT_REPOSITORY_REGISTRY` | Geo::DesignManagementRepositoryRegistry registry class. | +| <a id="georegistryclassgroup_wiki_repository_registry"></a>`GROUP_WIKI_REPOSITORY_REGISTRY` | Geo::GroupWikiRepositoryRegistry registry class. | | <a id="georegistryclassjob_artifact_registry"></a>`JOB_ARTIFACT_REGISTRY` | Geo::JobArtifactRegistry registry class. | | <a id="georegistryclasslfs_object_registry"></a>`LFS_OBJECT_REGISTRY` | Geo::LfsObjectRegistry registry class. | | <a id="georegistryclassmerge_request_diff_registry"></a>`MERGE_REQUEST_DIFF_REGISTRY` | Geo::MergeRequestDiffRegistry registry class. | @@ -26093,6 +26911,7 @@ Iteration ID wildcard values. | Value | Description | | ----- | ----------- | | <a id="jobartifactfiletypeaccessibility"></a>`ACCESSIBILITY` | ACCESSIBILITY job artifact file type. | +| <a id="jobartifactfiletypeannotations"></a>`ANNOTATIONS` | ANNOTATIONS job artifact file type. | | <a id="jobartifactfiletypeapi_fuzzing"></a>`API_FUZZING` | API FUZZING job artifact file type. | | <a id="jobartifactfiletypearchive"></a>`ARCHIVE` | ARCHIVE job artifact file type. | | <a id="jobartifactfiletypebrowser_performance"></a>`BROWSER_PERFORMANCE` | BROWSER PERFORMANCE job artifact file type. | @@ -26258,7 +27077,7 @@ State of a GitLab merge request. | <a id="mergerequeststateclosed"></a>`closed` | In closed state. | | <a id="mergerequeststatelocked"></a>`locked` | Discussion has been locked. | | <a id="mergerequeststatemerged"></a>`merged` | Merge request has been merged. | -| <a id="mergerequeststateopened"></a>`opened` | In open state. | +| <a id="mergerequeststateopened"></a>`opened` | Opened merge request. | ### `MergeStatus` @@ -26941,6 +27760,7 @@ Values for sorting timelogs. | <a id="todoactionenummentioned"></a>`mentioned` | User was mentioned. | | <a id="todoactionenummerge_train_removed"></a>`merge_train_removed` | Merge request authored by the user was removed from the merge train. | | <a id="todoactionenumreview_requested"></a>`review_requested` | Review was requested from the user. | +| <a id="todoactionenumreview_submitted"></a>`review_submitted` | Merge request authored by the user received a review. | | <a id="todoactionenumunmergeable"></a>`unmergeable` | Merge request authored by the user could not be merged. | ### `TodoStateEnum` @@ -27236,6 +28056,16 @@ Values for work item award emoji update enum. | <a id="workitemawardemojiupdateactionadd"></a>`ADD` | Adds the emoji. | | <a id="workitemawardemojiupdateactionremove"></a>`REMOVE` | Removes the emoji. | +### `WorkItemRelatedLinkType` + +Values for work item link types. + +| Value | Description | +| ----- | ----------- | +| <a id="workitemrelatedlinktypeblocked_by"></a>`BLOCKED_BY` | Blocked by type. | +| <a id="workitemrelatedlinktypeblocks"></a>`BLOCKS` | Blocks type. | +| <a id="workitemrelatedlinktyperelated"></a>`RELATED` | Related type. | + ### `WorkItemSort` Values for sorting work items. @@ -27294,6 +28124,7 @@ Type of a work item widget. | <a id="workitemwidgettypehierarchy"></a>`HIERARCHY` | Hierarchy widget. | | <a id="workitemwidgettypeiteration"></a>`ITERATION` | Iteration widget. | | <a id="workitemwidgettypelabels"></a>`LABELS` | Labels widget. | +| <a id="workitemwidgettypelinked_items"></a>`LINKED_ITEMS` | Linked Items widget. | | <a id="workitemwidgettypemilestone"></a>`MILESTONE` | Milestone widget. | | <a id="workitemwidgettypenotes"></a>`NOTES` | Notes widget. | | <a id="workitemwidgettypenotifications"></a>`NOTIFICATIONS` | Notifications widget. | @@ -27315,6 +28146,12 @@ each kind of object. For more information, read about [Scalar Types](https://graphql.org/learn/schema/#scalar-types) on `graphql.org`. +### `AbuseReportID` + +A `AbuseReportID` is a global ID. It is encoded as a string. + +An example `AbuseReportID` is: `"gid://gitlab/AbuseReport/1"`. + ### `AchievementsAchievementID` A `AchievementsAchievementID` is a global ID. It is encoded as a string. @@ -27473,6 +28310,12 @@ A `CiStageID` is a global ID. It is encoded as a string. An example `CiStageID` is: `"gid://gitlab/Ci::Stage/1"`. +### `CiTriggerID` + +A `CiTriggerID` is a global ID. It is encoded as a string. + +An example `CiTriggerID` is: `"gid://gitlab/Ci::Trigger/1"`. + ### `ClustersAgentID` A `ClustersAgentID` is a global ID. It is encoded as a string. @@ -28045,6 +28888,12 @@ An example `WorkItemID` is: `"gid://gitlab/WorkItem/1"`. While we transition from Issues into Work Items this type will temporarily support `IssueID` like: `"gid://gitlab/Issue/1"`. This behavior will be removed without notice in the future. +### `WorkItemsRelatedWorkItemLinkID` + +A `WorkItemsRelatedWorkItemLinkID` is a global ID. It is encoded as a string. + +An example `WorkItemsRelatedWorkItemLinkID` is: `"gid://gitlab/WorkItems::RelatedWorkItemLink/1"`. + ### `WorkItemsTypeID` A `WorkItemsTypeID` is a global ID. It is encoded as a string. @@ -28125,6 +28974,7 @@ One of: - [`DependencyProxyBlobRegistry`](#dependencyproxyblobregistry) - [`DependencyProxyManifestRegistry`](#dependencyproxymanifestregistry) - [`DesignManagementRepositoryRegistry`](#designmanagementrepositoryregistry) +- [`GroupWikiRepositoryRegistry`](#groupwikirepositoryregistry) - [`JobArtifactRegistry`](#jobartifactregistry) - [`LfsObjectRegistry`](#lfsobjectregistry) - [`MergeRequestDiffRegistry`](#mergerequestdiffregistry) @@ -28522,6 +29372,7 @@ Representation of a GitLab user. Implementations: +- [`AutocompletedUser`](#autocompleteduser) - [`MergeRequestAssignee`](#mergerequestassignee) - [`MergeRequestAuthor`](#mergerequestauthor) - [`MergeRequestParticipant`](#mergerequestparticipant) @@ -28815,6 +29666,7 @@ Implementations: - [`WorkItemWidgetHierarchy`](#workitemwidgethierarchy) - [`WorkItemWidgetIteration`](#workitemwidgetiteration) - [`WorkItemWidgetLabels`](#workitemwidgetlabels) +- [`WorkItemWidgetLinkedItems`](#workitemwidgetlinkeditems) - [`WorkItemWidgetMilestone`](#workitemwidgetmilestone) - [`WorkItemWidgetNotes`](#workitemwidgetnotes) - [`WorkItemWidgetNotifications`](#workitemwidgetnotifications) @@ -29534,7 +30386,7 @@ A time-frame defined as a closed inclusive range of two dates. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="workitemupdatedtaskinputassigneeswidget"></a>`assigneesWidget` | [`WorkItemWidgetAssigneesInput`](#workitemwidgetassigneesinput) | Input for assignees widget. | -| <a id="workitemupdatedtaskinputawardemojiwidget"></a>`awardEmojiWidget` | [`WorkItemWidgetAwardEmojiUpdateInput`](#workitemwidgetawardemojiupdateinput) | Input for award emoji widget. | +| <a id="workitemupdatedtaskinputawardemojiwidget"></a>`awardEmojiWidget` | [`WorkItemWidgetAwardEmojiUpdateInput`](#workitemwidgetawardemojiupdateinput) | Input for emoji reactions widget. | | <a id="workitemupdatedtaskinputconfidential"></a>`confidential` | [`Boolean`](#boolean) | Sets the work item confidentiality. | | <a id="workitemupdatedtaskinputcurrentusertodoswidget"></a>`currentUserTodosWidget` | [`WorkItemWidgetCurrentUserTodosInput`](#workitemwidgetcurrentusertodosinput) | Input for to-dos widget. | | <a id="workitemupdatedtaskinputdescriptionwidget"></a>`descriptionWidget` | [`WorkItemWidgetDescriptionInput`](#workitemwidgetdescriptioninput) | Input for description widget. | @@ -29648,6 +30500,8 @@ A time-frame defined as a closed inclusive range of two dates. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="workitemwidgetprogressinputcurrentvalue"></a>`currentValue` | [`Int!`](#int) | Current progress value of the work item. | +| <a id="workitemwidgetprogressinputendvalue"></a>`endValue` | [`Int`](#int) | End value of the work item. | +| <a id="workitemwidgetprogressinputstartvalue"></a>`startValue` | [`Int`](#int) | Start value of the work item. | ### `WorkItemWidgetStartAndDueDateUpdateInput` diff --git a/doc/api/graphql/removed_items.md b/doc/api/graphql/removed_items.md index 4c506d93436..f47a6d37528 100644 --- a/doc/api/graphql/removed_items.md +++ b/doc/api/graphql/removed_items.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# GraphQL API removed items **(FREE)** +# GraphQL API removed items **(FREE ALL)** GraphQL is a versionless API, unlike the REST API. Occasionally, items have to be updated or removed from the GraphQL API. diff --git a/doc/api/graphql/sample_issue_boards.md b/doc/api/graphql/sample_issue_boards.md index 1a189914b28..e78d2f07e2e 100644 --- a/doc/api/graphql/sample_issue_boards.md +++ b/doc/api/graphql/sample_issue_boards.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/product/ux/technical-writing/#assignments --- -# Identify issue boards with GraphQL **(FREE)** +# Identify issue boards with GraphQL **(FREE ALL)** This page describes how you can use the GraphiQL explorer to identify existing [issue boards](../../user/project/issue_board.md) in the `gitlab-docs` documentation repository. diff --git a/doc/api/graphql/users_example.md b/doc/api/graphql/users_example.md index 83cc2d6ac5e..2234528c52a 100644 --- a/doc/api/graphql/users_example.md +++ b/doc/api/graphql/users_example.md @@ -4,7 +4,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 --- -# Query users with GraphQL **(FREE)** +# Query users with GraphQL **(FREE ALL)** This page describes how you can use the GraphiQL explorer to query users. diff --git a/doc/api/group_access_tokens.md b/doc/api/group_access_tokens.md index 2493dfcc039..d8b221a8f94 100644 --- a/doc/api/group_access_tokens.md +++ b/doc/api/group_access_tokens.md @@ -4,7 +4,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 --- -# Group access tokens API **(FREE)** +# Group access tokens API **(FREE ALL)** You can read more about [group access tokens](../user/group/settings/group_access_tokens.md). @@ -152,6 +152,11 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla - Token with the specified ID does not exist. - `404: Not Found` if the user is an administrator but the token with the specified ID does not exist. +### Automatic reuse detection + +Refer to [automatic reuse detection for personal access tokens](personal_access_tokens.md#automatic-reuse-detection) +for more information. + ## Revoke a group access token > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77236) in GitLab 14.7. diff --git a/doc/api/group_activity_analytics.md b/doc/api/group_activity_analytics.md index 6d1c1ec155a..5426c4912c4 100644 --- a/doc/api/group_activity_analytics.md +++ b/doc/api/group_activity_analytics.md @@ -4,7 +4,7 @@ group: Optimize 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 --- -# Group Activity Analytics API **(PREMIUM)** +# Group Activity Analytics API **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26460) in GitLab 12.9. diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index 4c225e8aacb..fc7ec51af4d 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -4,7 +4,7 @@ group: Tenant Scale 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 --- -# Group badges API **(FREE)** +# Group badges API **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17082) in GitLab 10.6. diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index 9208f54c0bf..267b9feb750 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.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/product/ux/technical-writing/#assignments --- -# Group issue boards API **(FREE)** +# Group issue boards API **(FREE ALL)** Every API call to [group issue boards](../user/project/issue_board.md#group-issue-boards) must be authenticated. @@ -242,7 +242,7 @@ Example response: } ``` -## Create a group issue board **(PREMIUM)** +## Create a group issue board **(PREMIUM ALL)** Creates a group issue board. @@ -349,7 +349,7 @@ Example response: } ``` -## Delete a group issue board **(PREMIUM)** +## Delete a group issue board **(PREMIUM ALL)** Deletes a group issue board. diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index a4369ecad5f..912d5e197c6 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Group clusters API (certificate-based) (deprecated) **(FREE)** +# Group clusters API (certificate-based) (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30213) in GitLab 12.1. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/api/group_epic_boards.md b/doc/api/group_epic_boards.md index e85147a2868..fa5580dcbbc 100644 --- a/doc/api/group_epic_boards.md +++ b/doc/api/group_epic_boards.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Group epic boards API **(PREMIUM)** +# Group epic boards API **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385903) in GitLab 15.9. diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md index 314fb63058c..e95f4b307c8 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Group import and export API **(FREE)** +# Group import and export API **(FREE ALL)** Use the group import and export API to export a group structure and import it to a new location. When you use the group import and export API with the [project import and export API](project_import_export.md), you can preserve connections with diff --git a/doc/api/group_iterations.md b/doc/api/group_iterations.md index cae271e6365..a2e23e29d89 100644 --- a/doc/api/group_iterations.md +++ b/doc/api/group_iterations.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/product/ux/technical-writing/#assignments --- -# Group iterations API **(PREMIUM)** +# Group iterations API **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.5. > - Moved to GitLab Premium in 13.9. @@ -30,6 +30,7 @@ GET /groups/:id/iterations?updated_after=2013-10-02T09%3A24%3A18Z | ------------------- | ------- | -------- | ----------- | | `state` | string | no | 'Return `opened`, `upcoming`, `current`, `closed`, or `all` iterations.' | | `search` | string | no | Return only iterations with a title matching the provided string. | +| `in` | array of strings | no | Fields in which fuzzy search should be performed with the query given in the argument `search`. The available options are `title` and `cadence_title`. Default is `[title]`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350991) in GitLab 16.2. | | `include_ancestors` | boolean | no | Include iterations from parent group and its ancestors. Defaults to `true`. | | `updated_before` | datetime | no | Return only iterations updated before the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378662) in GitLab 15.10. | | `updated_after` | datetime | no | Return only iterations updated after the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378662) in GitLab 15.10. | diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index 298847f929b..4f745987156 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.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/product/ux/technical-writing/#assignments --- -# Group labels API **(FREE)** +# Group labels API **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21368) in GitLab 11.8. diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index 08fb9e55f32..8aebbff1814 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.md @@ -4,7 +4,7 @@ group: Pipeline Security 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 --- -# Group-level Variables API **(FREE)** +# Group-level Variables API **(FREE ALL)** ## List group variables diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index 52bce54119a..92664376365 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.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/product/ux/technical-writing/#assignments --- -# Group milestones API **(FREE)** +# Group milestones API **(FREE ALL)** Use the group [milestones](../user/project/milestones/index.md) using the REST API. There's a separate [project milestones API](milestones.md) page. @@ -166,7 +166,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of a group milestone | -## Get all burndown chart events for a single milestone **(PREMIUM)** +## Get all burndown chart events for a single milestone **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4737) in GitLab 12.1 > - Moved to GitLab Premium in 13.9. diff --git a/doc/api/group_protected_environments.md b/doc/api/group_protected_environments.md index 67b2b818ea9..a7b0eee08b7 100644 --- a/doc/api/group_protected_environments.md +++ b/doc/api/group_protected_environments.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Group-level protected environments API **(PREMIUM)** +# Group-level protected environments API **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215888) in GitLab 14.0. [Deployed behind the `group_level_protected_environments` flag](../administration/feature_flags.md), disabled by default. > - [Feature flag `group_level_protected_environments`](https://gitlab.com/gitlab-org/gitlab/-/issues/331085) removed in GitLab 14.3. diff --git a/doc/api/group_relations_export.md b/doc/api/group_relations_export.md index 8e8eb05b6b9..c32dec54177 100644 --- a/doc/api/group_relations_export.md +++ b/doc/api/group_relations_export.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Group relations export API **(FREE)** +# Group relations export API **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59978) in GitLab 13.12. diff --git a/doc/api/group_releases.md b/doc/api/group_releases.md index b8d15afcf06..05b4b3b0655 100644 --- a/doc/api/group_releases.md +++ b/doc/api/group_releases.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Group releases API **(FREE)** +# Group releases API **(FREE ALL)** Review your groups' [releases](../user/project/releases/index.md) with the REST API. diff --git a/doc/api/group_repository_storage_moves.md b/doc/api/group_repository_storage_moves.md index 95d261e79a9..6f0e0ee0b74 100644 --- a/doc/api/group_repository_storage_moves.md +++ b/doc/api/group_repository_storage_moves.md @@ -9,9 +9,11 @@ type: reference > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53016) in GitLab 13.9. -Group repositories can be moved between storages. This API can help you when -[migrating to Gitaly Cluster](../administration/gitaly/index.md#migrate-to-gitaly-cluster), for -example, or to migrate a [group wiki](../user/project/wiki/group.md). +Group wiki repositories can be moved between storages. This API can help you, for example, +[migrate to Gitaly Cluster](../administration/gitaly/index.md#migrate-to-gitaly-cluster) +or migrate a [group wiki](../user/project/wiki/group.md). This API does not manage +project repositories in a group. To schedule project moves, use the +[project repository storage moves API](project_repository_storage_moves.md). As group repository storage moves are processed, they transition through different states. Values of `state` are: diff --git a/doc/api/group_wikis.md b/doc/api/group_wikis.md index c03224373de..7396758ac40 100644 --- a/doc/api/group_wikis.md +++ b/doc/api/group_wikis.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Group wikis API **(PREMIUM)** +# Group wikis API **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212199) in GitLab 13.5. > - The `encoding` field was [added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/81150) in GitLab 14.9. diff --git a/doc/api/groups.md b/doc/api/groups.md index 235ef119e7b..930a682c157 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -4,7 +4,7 @@ group: Tenant Scale 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 --- -# Groups API **(FREE)** +# Groups API **(FREE ALL)** Interact with [groups](../user/group/index.md) by using the REST API. @@ -26,18 +26,19 @@ When accessed without authentication, this endpoint also supports [keyset pagina Parameters: -| Attribute | Type | Required | Description | -| ------------------------ | ----------------- | -------- | ---------- | -| `skip_groups` | array of integers | no | Skip the group IDs passed | -| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for administrators); Attributes `owned` and `min_access_level` have precedence | -| `search` | string | no | Return the list of authorized groups matching the search criteria | -| `order_by` | string | no | Order groups by `name`, `path`, `id`, or `similarity` (if searching, [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332889) in GitLab 14.1). Default is `name` | -| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | -| `statistics` | boolean | no | Include group statistics (administrators only).<br>*Note:* The REST API response does not provide the full `RootStorageStatistics` data that is shown in the UI. To match the data in the UI, use GraphQL instead of REST. For more information, see the [Group GraphQL reference](../api/graphql/reference/index.md#group).| -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | -| `owned` | boolean | no | Limit to groups explicitly owned by the current user | -| `min_access_level` | integer | no | Limit to groups where current user has at least this [role (`access_level`)](members.md#roles) | -| `top_level_only` | boolean | no | Limit to top level groups, excluding all subgroups | +| Attribute | Type | Required | Description | +| ------------------------------------- | ----------------- | -------- | ---------- | +| `skip_groups` | array of integers | no | Skip the group IDs passed | +| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for administrators); Attributes `owned` and `min_access_level` have precedence | +| `search` | string | no | Return the list of authorized groups matching the search criteria | +| `order_by` | string | no | Order groups by `name`, `path`, `id`, or `similarity` (if searching, [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332889) in GitLab 14.1). Default is `name` | +| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | +| `statistics` | boolean | no | Include group statistics (administrators only).<br>*Note:* The REST API response does not provide the full `RootStorageStatistics` data that is shown in the UI. To match the data in the UI, use GraphQL instead of REST. For more information, see the [Group GraphQL API resources](../api/graphql/reference/index.md#group).| +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | +| `owned` | boolean | no | Limit to groups explicitly owned by the current user | +| `min_access_level` | integer | no | Limit to groups where current user has at least this [role (`access_level`)](members.md#roles) | +| `top_level_only` | boolean | no | Limit to top level groups, excluding all subgroups | +| `repository_storage` **(PREMIUM)** | string | no | Filter by repository storage used by the group _(administrators only)_. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419643) in GitLab 16.3 | ```plaintext GET /groups @@ -64,6 +65,7 @@ GET /groups "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg", "web_url": "http://localhost:3000/groups/foo-bar", "request_access_enabled": false, + "repository_storage": "default", "full_name": "Foobar Group", "full_path": "foo-bar", "file_template_project_id": 1, @@ -101,6 +103,7 @@ GET /groups?statistics=true "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg", "web_url": "http://localhost:3000/groups/foo-bar", "request_access_enabled": false, + "repository_storage": "default", "full_name": "Foobar Group", "full_path": "foo-bar", "file_template_project_id": 1, @@ -184,6 +187,7 @@ GET /groups/:id/subgroups "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/foo.jpg", "web_url": "http://gitlab.example.com/groups/foo-bar", "request_access_enabled": false, + "repository_storage": "default", "full_name": "Foobar Group", "full_path": "foo-bar", "file_template_project_id": 1, @@ -470,6 +474,7 @@ Example response: "open_issues_count":10, "ci_default_git_depth":50, "ci_forward_deployment_enabled":true, + "ci_forward_deployment_rollback_allowed": true, "ci_allow_fork_pipelines_to_run_in_parent_project":true, "public_jobs":true, "build_timeout":3600, @@ -547,6 +552,7 @@ Example response: "avatar_url": null, "web_url": "https://gitlab.example.com/groups/twitter", "request_access_enabled": false, + "repository_storage": "default", "full_name": "Twitter", "full_path": "twitter", "runners_token": "ba324ca7b1c77fc20bb9", @@ -745,6 +751,7 @@ Example response: "avatar_url": null, "web_url": "https://gitlab.example.com/groups/twitter", "request_access_enabled": false, + "repository_storage": "default", "full_name": "Twitter", "full_path": "twitter", "file_template_project_id": 1, @@ -837,7 +844,7 @@ The `default_branch_protection` attribute determines whether users with the Deve | `1` | Partial protection. Users with the Developer or Maintainer role can: <br>- Push new commits | | `2` | Full protection. Only users with the Maintainer role can: <br>- Push new commits | | `3` | Protected against pushes. Users with the Maintainer role can: <br>- Push new commits<br>- Force push changes<br>- Accept merge requests<br>Users with the Developer role can:<br>- Accept merge requests| -| `4` | Protected against pushes except initial push. User with the Developer role can: <br>- Push commit to empty repository.<br> Users with the Maintainer role can: <br>- Push new commits<br>- Force push changes<br>- Accept merge requests<br>Users with the Developer role can:<br>- Accept merge requests| +| `4` | Full protection after initial push. User with the Developer role can: <br>- Push commit to empty repository.<br> Users with the Maintainer role can: <br>- Push new commits<br>- Accept merge requests| ## New Subgroup @@ -1021,6 +1028,7 @@ Example response: "avatar_url": null, "web_url": "http://gitlab.example.com/groups/h5bp", "request_access_enabled": false, + "repository_storage": "default", "full_name": "Foobar Group", "full_path": "h5bp", "file_template_project_id": 1, @@ -1161,7 +1169,7 @@ The response is `202 Accepted` if the user has authorization. NOTE: A GitLab.com group can't be removed if it is linked to a subscription. To remove such a group, first [link the subscription](../subscriptions/gitlab_com/index.md#change-the-linked-namespace) with a different group. -## Restore group marked for deletion **(PREMIUM)** +## Restore group marked for deletion **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33257) in GitLab 12.8. @@ -1196,7 +1204,7 @@ GET /groups?search=foobar ] ``` -## List provisioned users **(PREMIUM)** +## List provisioned users **(PREMIUM ALL)** > Introduced in GitLab 14.8. @@ -1270,7 +1278,7 @@ Example response: ] ``` -## Service Accounts **(PREMIUM)** +## Service Accounts **(PREMIUM ALL)** ### Create Service Account User @@ -1354,7 +1362,7 @@ Example response: } ``` -## Hooks **(PREMIUM)** +## Hooks **(PREMIUM ALL)** Also called Group Hooks and Webhooks. These are different from [System Hooks](system_hooks.md) that are system wide and [Project Hooks](projects.md#hooks) that are limited to one project. @@ -1485,7 +1493,7 @@ DELETE /groups/:id/hooks/:hook_id | `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of the group hook. | -## Group Audit Events **(PREMIUM)** +## Group Audit Events **(PREMIUM ALL)** Group audit events can be accessed via the [Group Audit Events API](audit_events.md#group-audit-events) @@ -1583,7 +1591,7 @@ DELETE /groups/:id/ldap_group_links NOTE: To delete the LDAP group link, provide either a `cn` or a `filter`, but not both. -## SAML Group Links **(PREMIUM)** +## SAML Group Links **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3.0. > - `access_level` type [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95607) from `string` to `integer` in GitLab 15.3.3. @@ -1788,7 +1796,7 @@ DELETE /groups/:id/share/:group_id | `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `group_id` | integer | yes | The ID of the group to share with | -## Push Rules **(PREMIUM)** +## Push Rules **(PREMIUM ALL)** > Introduced in GitLab 13.4. diff --git a/doc/api/import.md b/doc/api/import.md index 7bbc19cb36a..b981c1b57da 100644 --- a/doc/api/import.md +++ b/doc/api/import.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Import API **(FREE)** +# Import API **(FREE ALL)** Use the Import API to import repositories from GitHub or Bitbucket Server. @@ -34,7 +34,7 @@ POST /import/github | `target_namespace` | string | yes | Namespace to import repository into. Supports subgroups like `/namespace/subgroup`. In GitLab 15.8 and later, must not be blank | | `github_hostname` | string | no | Custom GitHub Enterprise hostname. Do not set for GitHub.com. | | `optional_stages` | object | no | [Additional items to import](../user/project/import/github.md#select-additional-items-to-import). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373705) in GitLab 15.5 | -| `additional_access_tokens` | string | no | Additional list of comma-separated personal access tokens. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337232) in GitLab 16.2 | +| `additional_access_tokens` | string | no | Comma-separated list of [additional](#use-multiple-github-personal-access-tokens) GitHub personal access tokens. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337232) in GitLab 16.2 | ```shell curl --request POST \ @@ -79,6 +79,17 @@ Example response: } ``` +### Use multiple GitHub personal access tokens + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337232) in GitLab 16.2. + +The GitHub import API can accept more than one GitHub personal access token using the `additional_access_tokens` +property so the API can make more calls to GitHub before hitting the rate limit. The additional GitHub personal access +tokens: + +- Cannot be from the same account because they would all share one rate limit. +- Must have the same permissions and sufficient privileges to the repositories to import. + ### Import a public project through the API using a group access token > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362683) in GitLab 15.7, projects are not imported into a [bot user's](../user/group/settings/group_access_tokens.md#bot-users-for-groups) namespace in any circumstances. Projects imported into a bot user's namespace could not be deleted by users with valid tokens, which represented a security risk. @@ -210,7 +221,7 @@ curl --request POST \ }' ``` -## Automate group and project import **(PREMIUM)** +## Automate group and project import **(PREMIUM ALL)** For information on automating user, group, and project import API calls, see [Automate group and project import](../user/project/import/index.md#automate-group-and-project-import). diff --git a/doc/api/index.md b/doc/api/index.md index 8073cbec94a..7cb25c4ce17 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Develop with GitLab **(FREE)** +# Develop with GitLab **(FREE ALL)** Automate and interact with GitLab, and integrate with external applications. diff --git a/doc/api/integrations.md b/doc/api/integrations.md index b1cb6ed6560..530506c9bed 100644 --- a/doc/api/integrations.md +++ b/doc/api/integrations.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Integrations API **(FREE)** +# Integrations API **(FREE ALL)** This API enables you to work with external services that integrate with GitLab. @@ -637,6 +637,8 @@ Send notifications about project events to a Discord channel. ### Create/Edit Discord integration +> `_channel` parameters [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125621) in GitLab 16.3. + Set Discord integration for a project. ```plaintext @@ -650,15 +652,24 @@ Parameters: | `webhook` | string | true | Discord webhook. For example, `https://discord.com/api/webhooks/…` | | `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are `all`, `default`, `protected`, and `default_and_protected`. The default value is "default" | | `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | +| `confidential_issue_channel` | string | false | The webhook override to receive confidential issues events notifications | | `confidential_note_events` | boolean | false | Enable notifications for confidential note events | +| `confidential_note_channel` | string | false | The webhook override to receive confidential note events notifications | | `issues_events` | boolean | false | Enable notifications for issue events | +| `issue_channel` | string | false | The webhook override to receive issues events notifications | | `merge_requests_events` | boolean | false | Enable notifications for merge request events | +| `merge_request_channel` | string | false | The webhook override to receive merge request events notifications | | `note_events` | boolean | false | Enable notifications for note events | +| `note_channel` | string | false | The webhook override to receive note events notifications | | `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | | `pipeline_events` | boolean | false | Enable notifications for pipeline events | +| `pipeline_channel` | string | false | The webhook override to receive pipeline events notifications | | `push_events` | boolean | false | Enable notifications for push events | +| `push_channel` | string | false | The webhook override to receive push events notifications | | `tag_push_events` | boolean | false | Enable notifications for tag push events | +| `tag_push_channel` | string | false | The webhook override to receive tag push events notifications | | `wiki_page_events` | boolean | false | Enable notifications for wiki page events | +| `wiki_page_channel` | string | false | The webhook override to receive wiki page events notifications | ### Disable Discord integration @@ -890,7 +901,7 @@ Get External wiki integration settings for a project. GET /projects/:id/integrations/external-wiki ``` -## GitHub **(PREMIUM)** +## GitHub **(PREMIUM ALL)** Code collaboration software. diff --git a/doc/api/invitations.md b/doc/api/invitations.md index 2484cfe1728..0b976736bc5 100644 --- a/doc/api/invitations.md +++ b/doc/api/invitations.md @@ -4,7 +4,7 @@ group: Acquisition 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 --- -# Invitations API **(FREE)** +# Invitations API **(FREE ALL)** Use the Invitations API to invite or add users to a group or project, and to list pending invitations. diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index 46cf8e9b2b6..a7cacd64cbb 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.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/product/ux/technical-writing/#assignments --- -# Issue links API **(FREE)** +# Issue links API **(FREE ALL)** > The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to GitLab Free in 13.4. diff --git a/doc/api/issues.md b/doc/api/issues.md index 9f9775c1746..f318515e0a6 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.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/product/ux/technical-writing/#assignments --- -# Issues API **(FREE)** +# Issues API **(FREE ALL)** Interact with [GitLab Issues](../user/project/issues/index.md) using the REST API. @@ -1945,7 +1945,7 @@ Example response: WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -## Promote an issue to an epic **(PREMIUM)** +## Promote an issue to an epic **(PREMIUM ALL)** Promotes an issue to an epic by adding a comment with the `/promote` [quick action](../user/project/quick_actions.md). diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md index 3910594f086..d2148b001cb 100644 --- a/doc/api/issues_statistics.md +++ b/doc/api/issues_statistics.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/product/ux/technical-writing/#assignments --- -# Issues statistics API **(FREE)** +# Issues statistics API **(FREE ALL)** Every API call to the [issues](../user/project/issues/index.md) statistics API must be authenticated. diff --git a/doc/api/iterations.md b/doc/api/iterations.md index 567a2def09f..364cca9c977 100644 --- a/doc/api/iterations.md +++ b/doc/api/iterations.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/product/ux/technical-writing/#assignments --- -# Project iterations API **(PREMIUM)** +# Project iterations API **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.5. > - Moved to GitLab Premium in 13.9. @@ -32,6 +32,7 @@ GET /projects/:id/iterations?updated_after=2013-10-02T09%3A24%3A18Z | ------------------- | ------- | -------- | ----------- | | `state` | string | no | 'Return `opened`, `upcoming`, `current`, `closed`, or `all` iterations.' | | `search` | string | no | Return only iterations with a title matching the provided string. | +| `in` | array of strings | no | Fields in which fuzzy search should be performed with the query given in the argument `search`. The available options are `title` and `cadence_title`. Default is `[title]`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350991) in GitLab 16.2. | | `include_ancestors` | boolean | no | Include iterations from parent group and its ancestors. Defaults to `true`. | | `updated_before` | datetime | no | Return only iterations updated before the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378662) in GitLab 15.10. | | `updated_after` | datetime | no | Return only iterations updated after the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378662) in GitLab 15.10. | diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index d8343cb7c44..5a3861f888e 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -4,7 +4,7 @@ group: Pipeline Security 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 --- -# Job Artifacts API **(FREE)** +# Job Artifacts API **(FREE ALL)** ## Get job artifacts diff --git a/doc/api/jobs.md b/doc/api/jobs.md index a48168c8362..92ab12ec0d0 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Jobs API **(FREE)** +# Jobs API **(FREE ALL)** ## List project jobs @@ -497,7 +497,7 @@ Example of response } ``` -## Get GitLab agent by `CI_JOB_TOKEN` **(PREMIUM)** +## Get GitLab agent by `CI_JOB_TOKEN` **(PREMIUM ALL)** Retrieve the job that generated the `CI_JOB_TOKEN`, along with a list of allowed [agents](../user/clusters/agent/index.md). @@ -842,7 +842,7 @@ Example of response NOTE: You can't delete archived jobs with the API, but you can -[delete job artifacts and logs from jobs completed before a specific date](../administration/job_artifacts.md#delete-job-artifacts-and-logs-from-jobs-completed-before-a-specific-date) +[delete job artifacts and logs from jobs completed before a specific date](../administration/job_artifacts_troubleshooting.md#delete-job-artifacts-and-logs-from-jobs-completed-before-a-specific-date) ## Run a job diff --git a/doc/api/keys.md b/doc/api/keys.md index 337758e6c33..571c193c1d3 100644 --- a/doc/api/keys.md +++ b/doc/api/keys.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Keys API **(FREE)** +# Keys API **(FREE ALL)** If using a SHA256 fingerprint in an API call, you should URL-encode the fingerprint. diff --git a/doc/api/labels.md b/doc/api/labels.md index a5d5461c1ac..c96350219b9 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.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/product/ux/technical-writing/#assignments --- -# Labels API **(FREE)** +# Labels API **(FREE ALL)** Interact with [labels](../user/project/labels.md) using the REST API. diff --git a/doc/api/linked_epics.md b/doc/api/linked_epics.md index 434e6080ffb..1cb70fa38f0 100644 --- a/doc/api/linked_epics.md +++ b/doc/api/linked_epics.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Linked epics API **(ULTIMATE)** +# Linked epics API **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352493) in GitLab 14.9 [with a flag](../administration/feature_flags.md) named `related_epics_widget`. Enabled by default. > - [Feature flag `related_epics_widget`](https://gitlab.com/gitlab-org/gitlab/-/issues/357089) removed in GitLab 15.0. diff --git a/doc/api/lint.md b/doc/api/lint.md index b0282b89f6e..32318b9955d 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -4,7 +4,7 @@ group: Pipeline Authoring 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 --- -# CI Lint API **(FREE)** +# CI Lint API **(FREE ALL)** ## Validate the CI/CD configuration for a namespace diff --git a/doc/api/managed_licenses.md b/doc/api/managed_licenses.md index e7ac247ae4a..d9f74ddddb2 100644 --- a/doc/api/managed_licenses.md +++ b/doc/api/managed_licenses.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: 'index.md' --- -# Managed Licenses API (removed) **(ULTIMATE)** +# Managed Licenses API (removed) **(ULTIMATE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/390417) in GitLab 15.9 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/397067) in 16.0. diff --git a/doc/api/markdown.md b/doc/api/markdown.md index 42948661cbb..fdbdbf65b53 100644 --- a/doc/api/markdown.md +++ b/doc/api/markdown.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/product/ux/technical-writing/#assignments --- -# Markdown API **(FREE)** +# Markdown API **(FREE ALL)** Convert Markdown content to HTML. diff --git a/doc/api/member_roles.md b/doc/api/member_roles.md index 3ef6e287418..9d3e51efabd 100644 --- a/doc/api/member_roles.md +++ b/doc/api/member_roles.md @@ -4,10 +4,14 @@ 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 --- -# Member roles API **(ULTIMATE)** +# Member roles API **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96996) in GitLab 15.4. [Deployed behind the `customizable_roles` flag](../administration/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110810) in GitLab 15.9. +> - [Read vulnerability added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114734) in GitLab 16.0. +> - [Admin vulnerability added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121534) in GitLab 16.1. +> - [Read dependency added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126247) in GitLab 16.3. +> - [Name and description fields added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126423) in GitLab 16.3. ## List all member roles of a group @@ -23,12 +27,17 @@ GET /groups/:id/member_roles If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes: -| Attribute | Type | Description | -|:-------------------------|:---------|:----------------------| +| Attribute | Type | Description | +|:-------------------------|:--------|:----------------------| | `[].id` | integer | The ID of the member role. | +| `[].name` | string | The name of the member role. | +| `[].description` | string | The description of the member role. | | `[].group_id` | integer | The ID of the group that the member role belongs to. | -| `[].base_access_level` | integer | Base access level for member role. | -| `[].read_code` | boolean | Permission to read code. | +| `[].base_access_level` | integer | Base access level for member role. Valid values are 10 (Guest), 20 (Reporter), 30 (Developer), 40 (Maintainer), or 50 (Owner).| +| `[].admin_vulnerability` | boolean | Permission to admin project vulnerabilities. | +| `[].read_code` | boolean | Permission to read project code. | +| `[].read_dependency` | boolean | Permission to read project dependencies. | +| `[].read_vulnerability` | boolean | Permission to read project vulnerabilities. | Example request: @@ -42,21 +51,33 @@ Example response: [ { "id": 2, + "name": "Custom + code", + "description: "Custom guest that can read code", "group_id": 84, "base_access_level": 10, - "read_code": true + "admin_vulnerability": false, + "read_code": true, + "read_dependency": false, + "read_vulnerability": false }, { "id": 3, + "name": "Guest + security", + "description: "Custom guest that read and admin security entities", "group_id": 84, "base_access_level": 10, - "read_code": false + "admin_vulnerability": true, + "read_code": false, + "read_dependency": true, + "read_vulnerability": true } ] ``` ## Add a member role to a group +> Ability to add a name and description when creating a custom role [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126423) in GitLab 16.3. + Adds a member role to a group. ```plaintext @@ -65,25 +86,35 @@ POST /groups/:id/member_roles To add a member role to a group, the group must be at root-level (have no parent group). -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `base_access_level` | integer | yes | Base access level for configured role. | -| `read_code` | boolean | no | Permission to read code. | +| Attribute | Type | Required | Description | +| --------- | ------------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `name` | string | yes | The name of the member role. | +| `description` | string | no | The description of the member role. | +| `base_access_level` | integer | yes | Base access level for configured role. Valid values are 10 (Guest), 20 (Reporter), 30 (Developer), 40 (Maintainer), or 50 (Owner).| +| `admin_vulnerability` | boolean | no | Permission to admin project vulnerabilities. | +| `read_code` | boolean | no | Permission to read project code. | +| `read_dependency` | boolean | no | Permission to read project dependencies. | +| `read_vulnerability` | boolean | no | Permission to read project vulnerabilities. | If successful, returns [`201`](rest/index.md#status-codes) and the following attributes: | Attribute | Type | Description | |:-------------------------|:---------|:----------------------| | `id` | integer | The ID of the member role. | +| `name` | string | The name of the member role. | +| `description` | string | The description of the member role. | | `group_id` | integer | The ID of the group that the member role belongs to. | | `base_access_level` | integer | Base access level for member role. | -| `read_code` | boolean | Permission to read code. | +| `admin_vulnerability` | boolean | Permission to admin project vulnerabilities. | +| `read_code` | boolean | Permission to read project code. | +| `read_dependency` | boolean | Permission to read project dependencies. | +| `read_vulnerability` | boolean | Permission to read project vulnerabilities. | Example request: ```shell - curl --request POST --header "Content-Type: application/json" --header "Authorization: Bearer $YOUR_ACCESS_TOKEN" --data '{"base_access_level" : 10, "read_code" : true}' "https://example.gitlab.com/api/v4/groups/:id/member_roles" + curl --request POST --header "Content-Type: application/json" --header "Authorization: Bearer $YOUR_ACCESS_TOKEN" --data '{"name" : "Custom guest", "base_access_level" : 10, "read_code" : true}' "https://example.gitlab.com/api/v4/groups/:id/member_roles" ``` Example response: @@ -91,12 +122,23 @@ Example response: ```json { "id": 3, + "name": "Custom guest", + "description": null, "group_id": 84, "base_access_level": 10, - "read_code": true + "admin_vulnerability": false, + "read_code": true, + "read_dependency": false, + "read_vulnerability": false } ``` +In GitLab 16.3 and later, you can use the API to: + +- Add a name (required) and description (optional) when you + [create a new custom role](../user/permissions.md#create-a-custom-role). +- Update an existing custom role's name and description. + ### Remove member role of a group Deletes a member role of a group. diff --git a/doc/api/members.md b/doc/api/members.md index 02fa4be3d64..f7e3d6898ec 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -4,7 +4,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 --- -# Group and project members API **(FREE)** +# Group and project members API **(FREE ALL)** > `created_by` field [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28789) in GitLab 14.10. @@ -521,7 +521,7 @@ POST /projects/:id/members | `user_id` | integer/string | yes | The user ID of the new member or multiple IDs separated by commas | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format `YEAR-MONTH-DAY` | -| `invite_source` | string | no | The source of the invitation that starts the member creation process. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/327120). | +| `invite_source` | string | no | The source of the invitation that starts the member creation process. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/327120>`. | | `tasks_to_be_done` | array of strings | no | Tasks the inviter wants the member to focus on. The tasks are added as issues to a specified project. The possible values are: `ci`, `code` and `issues`. If specified, requires `tasks_project_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/69299) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `invite_members_for_task`. Disabled by default. | | `tasks_project_id` | integer | no | The project ID in which to create the task issues. If specified, requires `tasks_to_be_done`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/69299) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `invite_members_for_task`. Disabled by default. | diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 9123fe0dc1e..d64c71367a9 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -4,7 +4,7 @@ group: Source Code 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" --- -# Merge request approvals API **(PREMIUM)** +# Merge request approvals API **(PREMIUM ALL)** > - Changing approval configuration with the `/approvals` endpoint was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/11132) in GitLab 12.3. > - Endpoint `/approvals` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/353097) in GitLab 16.0. @@ -31,7 +31,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-----------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | ```json { @@ -62,14 +62,14 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | -| `approvals_before_merge` (deprecated) | integer | **{dotted-circle}** No | How many approvals are required before a merge request can be merged. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/11132) in GitLab 12.3. Use [Approval Rules](#create-project-level-rule) instead. | -| `disable_overriding_approvers_per_merge_request` | boolean | **{dotted-circle}** No | Allow or prevent overriding approvers per merge request. | -| `merge_requests_author_approval` | boolean | **{dotted-circle}** No | Allow or prevent authors from self approving merge requests; `true` means authors can self approve. | -| `merge_requests_disable_committers_approval` | boolean | **{dotted-circle}** No | Allow or prevent committers from self approving merge requests. | -| `require_password_to_approve` | boolean | **{dotted-circle}** No | Require approver to enter a password to authenticate before adding the approval. | -| `reset_approvals_on_push` | boolean | **{dotted-circle}** No | Reset approvals on a new push. | -| `selective_code_owner_removals` | boolean | **{dotted-circle}** No | Reset approvals from Code Owners if their files changed. Can be enabled only if `reset_approvals_on_push` is disabled. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `approvals_before_merge` (deprecated) | integer | No | How many approvals are required before a merge request can be merged. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/11132) in GitLab 12.3. Use [Approval Rules](#create-project-level-rule) instead. | +| `disable_overriding_approvers_per_merge_request` | boolean | No | Allow or prevent overriding approvers per merge request. | +| `merge_requests_author_approval` | boolean | No | Allow or prevent authors from self approving merge requests; `true` means authors can self approve. | +| `merge_requests_disable_committers_approval` | boolean | No | Allow or prevent committers from self approving merge requests. | +| `require_password_to_approve` | boolean | No | Require approver to enter a password to authenticate before adding the approval. | +| `reset_approvals_on_push` | boolean | No | Reset approvals on a new push. | +| `selective_code_owner_removals` | boolean | No | Reset approvals from Code Owners if their files changed. Can be enabled only if `reset_approvals_on_push` is disabled. | ```json { @@ -89,7 +89,7 @@ Supported attributes: > - Pagination support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31011) in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `approval_rules_pagination`. Enabled by default. > - `applies_to_all_protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3. > - Pagination support [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366823) in GitLab 15.7. Feature flag `approval_rules_pagination` removed. -> - `usernames` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 15.8. +> - `usernames` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102446) in GitLab 15.8. You can request information about a project's approval rules using the following endpoint: @@ -103,7 +103,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-----------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | ```json [ @@ -193,7 +193,7 @@ Supported attributes: > - Introduced in GitLab 13.7. > - `applies_to_all_protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3. -> - `usernames` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 1x.x. +> - `usernames` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102446) in GitLab 15.8. You can request information about a single project approval rules using the following endpoint: @@ -205,8 +205,8 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | -| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `approval_rule_id` | integer | Yes | The ID of a approval rule. | ```json { @@ -295,7 +295,7 @@ Supported attributes: > - Moved to GitLab Premium in 13.9. > - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357300) the Vulnerability-Check feature in GitLab 15.0. > - `applies_to_all_protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3. -> - `usernames` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 1x.x. +> - `usernames` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102446) in GitLab 15.8. You can create project approval rules using the following endpoint: @@ -307,16 +307,16 @@ Supported attributes: | Attribute | Type | Required | Description | |-------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | -| `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | -| `name` | string | **{check-circle}** Yes | The name of the approval rule. | -| `applies_to_all_protected_branches` | boolean | **{dotted-circle}** No | Whether the rule is applied to all protected branches. If set to `true`, the value of `protected_branch_ids` is ignored. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3. | -| `group_ids` | Array | **{dotted-circle}** No | The IDs of groups as approvers. | -| `protected_branch_ids` | Array | **{dotted-circle}** No | The IDs of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | -| `report_type` | string | **{dotted-circle}** No | The report type required when the rule type is `report_approver`. The supported report types are `license_scanning` [(Deprecated in GitLab 15.9)](../update/deprecations.md#license-check-and-the-policies-tab-on-the-license-compliance-page) and `code_coverage`. | -| `rule_type` | string | **{dotted-circle}** No | The type of rule. `any_approver` is a pre-configured default rule with `approvals_required` at `0`. Other rules are `regular`. | -| `user_ids` | Array | **{dotted-circle}** No | The IDs of users as approvers. | -| `usernames` | string array | **{dotted-circle}** No | The usernames for this rule. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `approvals_required` | integer | Yes | The number of required approvals for this rule. | +| `name` | string | Yes | The name of the approval rule. | +| `applies_to_all_protected_branches` | boolean | No | Whether the rule is applied to all protected branches. If set to `true`, the value of `protected_branch_ids` is ignored. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3. | +| `group_ids` | Array | No | The IDs of groups as approvers. | +| `protected_branch_ids` | Array | No | The IDs of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | +| `report_type` | string | No | The report type required when the rule type is `report_approver`. The supported report types are `license_scanning` [(Deprecated in GitLab 15.9)](../update/deprecations.md#license-check-and-the-policies-tab-on-the-license-compliance-page) and `code_coverage`. | +| `rule_type` | string | No | The type of rule. `any_approver` is a pre-configured default rule with `approvals_required` at `0`. Other rules are `regular` and `report_approver`. | +| `user_ids` | Array | No | The IDs of users as approvers. If you provide both `user_ids` and `usernames`, both lists of users are added. | +| `usernames` | string array | No | The usernames of approvers for this rule (same as `user_ids` but requires a list of usernames). If you provide both `user_ids` and `usernames`, both lists of users are added. | ```json { @@ -422,7 +422,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ > - Moved to GitLab Premium in 13.9. > - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357300) the Vulnerability-Check feature in GitLab 15.0. > - `applies_to_all_protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3. -> - `usernames` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 1x.x. +> - `usernames` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102446) in GitLab 15.8. You can update project approval rules using the following endpoint: @@ -430,22 +430,27 @@ You can update project approval rules using the following endpoint: PUT /projects/:id/approval_rules/:approval_rule_id ``` -**Important:** Approvers and groups not in the `users`/`groups` parameters are **removed** +NOTE: +Approvers and groups (except hidden groups not in the `users` or `groups` +parameters) are **removed**. Hidden groups are private groups the user doesn't +have permission to view. Hidden groups are not removed by default unless the +`remove_hidden_groups` parameter is `true`. This ensures hidden groups are +not removed unintentionally when a user updates an approval rule. Supported attributes: | Attribute | Type | Required | Description | |-------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | -| `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | -| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | -| `name` | string | **{check-circle}** Yes | The name of the approval rule. | -| `applies_to_all_protected_branches` | boolean | **{dotted-circle}** No | Whether the rule is applied to all protected branches. If set to `true`, the value of `protected_branch_ids` is ignored. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3. | -| `group_ids` | Array | **{dotted-circle}** No | The IDs of groups as approvers. | -| `protected_branch_ids` | Array | **{dotted-circle}** No | The IDs of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | -| `remove_hidden_groups` | boolean | **{dotted-circle}** No | Whether hidden groups should be removed. | -| `user_ids` | Array | **{dotted-circle}** No | The IDs of users as approvers. | -| `usernames` | string array | **{dotted-circle}** No | The usernames for this rule. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `approvals_required` | integer | Yes | The number of required approvals for this rule. | +| `approval_rule_id` | integer | Yes | The ID of a approval rule. | +| `name` | string | Yes | The name of the approval rule. | +| `applies_to_all_protected_branches` | boolean | No | Whether the rule is applied to all protected branches. If set to `true`, the value of `protected_branch_ids` is ignored. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3. | +| `group_ids` | Array | No | The IDs of groups as approvers. | +| `protected_branch_ids` | Array | No | The IDs of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | +| `remove_hidden_groups` | boolean | No | Whether hidden groups should be removed from approval rule. | +| `user_ids` | Array | No | The IDs of users as approvers. If you provide both `user_ids` and `usernames`, both lists of users are added. | +| `usernames` | string array | No | The usernames of approvers for this rule (same as `user_ids` but requires a list of usernames). If you provide both `user_ids` and `usernames`, both lists of users are added.| ```json { @@ -543,8 +548,8 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | -| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `approval_rule_id` | integer | Yes | The ID of a approval rule. | ## Merge request-level MR approvals @@ -565,8 +570,8 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `merge_request_iid` | integer | Yes | The IID of the merge request. | ```json { @@ -630,8 +635,8 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `merge_request_iid` | integer | Yes | The IID of the merge request. | ```json { @@ -700,8 +705,8 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `merge_request_iid` | integer | Yes | The IID of the merge request. | ```json [ @@ -777,9 +782,9 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | -| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `approval_rule_id` | integer | Yes | The ID of an approval rule. | +| `merge_request_iid` | integer | Yes | The IID of a merge request. | ```json { @@ -853,14 +858,14 @@ Supported attributes: | Attribute | Type | Required | Description | |----------------------------|-------------------|------------------------|------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding) | -| `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | -| `name` | string | **{check-circle}** Yes | The name of the approval rule. | -| `approval_project_rule_id` | integer | **{dotted-circle}** No | The ID of a project-level approval rule. | -| `group_ids` | Array | **{dotted-circle}** No | The IDs of groups as approvers. | -| `user_ids` | Array | **{dotted-circle}** No | The IDs of users as approvers. | -| `usernames` | string array | **{dotted-circle}** No | The usernames for this rule. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding) | +| `approvals_required` | integer | Yes | The number of required approvals for this rule. | +| `merge_request_iid` | integer | Yes | The IID of the merge request. | +| `name` | string | Yes | The name of the approval rule. | +| `approval_project_rule_id` | integer | No | The ID of a project-level approval rule. | +| `group_ids` | Array | No | The IDs of groups as approvers. | +| `user_ids` | Array | No | The IDs of users as approvers. If you provide both `user_ids` and `usernames`, both lists of users are added. +| `usernames` | string array | No | The usernames of approvers for this rule (same as `user_ids` but requires a list of usernames). If you provide both `user_ids` and `usernames`, both lists of users are added. | **Important:** When `approval_project_rule_id` is set, the `name`, `users` and `groups` of project-level rule are copied. The `approvals_required` specified @@ -943,15 +948,15 @@ Supported attributes: | Attribute | Type | Required | Description | |------------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | -| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | -| `approvals_required` | integer | **{check-circle}** No | The number of required approvals for this rule. | -| `group_ids` | Array | **{dotted-circle}** No | The IDs of groups as approvers. | -| `name` | string | **{check-circle}** No | The name of the approval rule. | -| `remove_hidden_groups` | boolean | **{dotted-circle}** No | Whether hidden groups should be removed. | -| `user_ids` | Array | **{dotted-circle}** No | The IDs of users as approvers. | -| `usernames` | string array | **{dotted-circle}** No | The usernames for this rule. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `approval_rule_id` | integer | Yes | The ID of an approval rule. | +| `merge_request_iid` | integer | Yes | The IID of a merge request. | +| `approvals_required` | integer | No | The number of required approvals for this rule. | +| `group_ids` | Array | No | The IDs of groups as approvers. | +| `name` | string | No | The name of the approval rule. | +| `remove_hidden_groups` | boolean | No | Whether hidden groups should be removed. | +| `user_ids` | Array | No | The IDs of users as approvers. If you provide both `user_ids` and `usernames`, both lists of users are added. | +| `usernames` | string array | No | The usernames of approvers for this rule (same as `user_ids` but requires a list of usernames). If you provide both `user_ids` and `usernames`, both lists of users are added. | ```json { @@ -1028,9 +1033,9 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | -| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `approval_rule_id` | integer | Yes | The ID of an approval rule. | +| `merge_request_iid` | integer | Yes | The IID of the merge request. | ## Approve merge request @@ -1047,10 +1052,10 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | -| `approval_password` | string | **{dotted-circle}** No | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-user-password-to-approve) is enabled in the project settings. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | -| `sha` | string | **{dotted-circle}** No | The `HEAD` of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `approval_password` | string | No | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-user-password-to-approve) is enabled in the project settings. | +| `merge_request_iid` | integer | Yes | The IID of the merge request. | +| `sha` | string | No | The `HEAD` of the merge request. | The `sha` parameter works in the same way as when [accepting a merge request](merge_requests.md#merge-a-merge-request): if it is passed, then it must @@ -1110,8 +1115,8 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | +| `merge_request_iid` | integer | Yes | The IID of a merge request. | ## Reset approvals of a merge request @@ -1126,8 +1131,8 @@ PUT /projects/:id/merge_requests/:merge_request_iid/reset_approvals | Attribute | Type | Required | Description | |---------------------|-------------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/76/merge_requests/1/reset_approvals" diff --git a/doc/api/merge_request_context_commits.md b/doc/api/merge_request_context_commits.md index 756f54586db..26fb561e5e7 100644 --- a/doc/api/merge_request_context_commits.md +++ b/doc/api/merge_request_context_commits.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Merge request context commits API **(FREE)** +# Merge request context commits API **(FREE ALL)** ## List MR context commits @@ -19,8 +19,8 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|---------|----------|-------------| -| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```json [ @@ -53,8 +53,8 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|---------|----------|-------------| -| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```plaintext POST /projects/:id/merge_requests/ @@ -62,7 +62,7 @@ POST /projects/:id/merge_requests/ | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `commits` | string array | **{check-circle}** Yes | The context commits' SHA. | +| `commits` | string array | Yes | The context commits' SHA. | ```json [ @@ -94,6 +94,6 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|--------------|----------|--------------| -| `commits` | string array | **{check-circle}** Yes | The context commits' SHA. | -| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `commits` | string array | Yes | The context commits' SHA. | +| `id` | integer | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index d6360552baf..5f637dd28a3 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -4,7 +4,7 @@ group: Code Review 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 --- -# Merge requests API **(FREE)** +# Merge requests API **(FREE ALL)** > - `reference` was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) in GitLab 12.7. > - `draft` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63473) as a replacement for `work_in_progress` in GitLab 14.0. @@ -51,37 +51,37 @@ Supported attributes: | Attribute | Type | Required | Description | | ------------------------------- | -------------- | -------- | ----------- | -| `approved_by_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | Returns merge requests which have been approved by all the users with the given `id`. Maximum of 5. `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | -| `approver_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | Returns merge requests which have specified all the users with the given `id` as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | -| `approved` | string | **{dotted-circle}** No | Filters merge requests by their `approved` status. `yes` returns only approved merge requests. `no` returns only non-approved merge requests. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3159) in GitLab 15.11. Available only when the feature flag `mr_approved_filter` is enabled. | -| `assignee_id` | integer | **{dotted-circle}** No | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | -| `author_id` | integer | **{dotted-circle}** No | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | -| `author_username` | string | **{dotted-circle}** No | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. | -| `created_after` | datetime | **{dotted-circle}** No | Returns merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | -| `created_before` | datetime | **{dotted-circle}** No | Returns merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | -| `deployed_after` | datetime | **{dotted-circle}** No | Returns merge requests deployed after the given date/time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | -| `deployed_before` | datetime | **{dotted-circle}** No | Returns merge requests deployed before the given date/time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | -| `environment` | string | **{dotted-circle}** No | Returns merge requests deployed to the given environment. | -| `in` | string | **{dotted-circle}** No | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description`. | -| `labels` | string | **{dotted-circle}** No | Returns merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. Predefined names are case-insensitive. | -| `milestone` | string | **{dotted-circle}** No | Returns merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | -| `my_reaction_emoji` | string | **{dotted-circle}** No | Returns merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | -| `not` | Hash | **{dotted-circle}** No | Returns merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. | -| `order_by` | string | **{dotted-circle}** No | Returns requests ordered by `created_at`, `title`, or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8.| -| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | -| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | -| `scope` | string | **{dotted-circle}** No | Returns merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`. | -| `search` | string | **{dotted-circle}** No | Search merge requests against their `title` and `description`. | -| `sort` | string | **{dotted-circle}** No | Returns requests sorted in `asc` or `desc` order. Default is `desc`. | -| `source_branch` | string | **{dotted-circle}** No | Returns merge requests with the given source branch. | -| `state` | string | **{dotted-circle}** No | Returns all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. | -| `target_branch` | string | **{dotted-circle}** No | Returns merge requests with the given target branch. | -| `updated_after` | datetime | **{dotted-circle}** No | Returns merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | -| `updated_before` | datetime | **{dotted-circle}** No | Returns merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | -| `view` | string | **{dotted-circle}** No | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | -| `with_labels_details` | boolean | **{dotted-circle}** No | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. | -| `with_merge_status_recheck` | boolean | **{dotted-circle}** No | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. In GitLab 15.11 and later, enable the `restrict_merge_status_recheck` feature [flag](../administration/feature_flags.md) for this attribute to be ignored when requested by users without at least the Developer role. | -| `wip` | string | **{dotted-circle}** No | Filter merge requests against their `wip` status. `yes` to return *only* draft merge requests, `no` to return *non-draft* merge requests. | +| `approved_by_ids` **(PREMIUM)** | integer array | No | Returns merge requests which have been approved by all the users with the given `id`. Maximum of 5. `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | +| `approver_ids` **(PREMIUM)** | integer array | No | Returns merge requests which have specified all the users with the given `id` as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | +| `approved` | string | No | Filters merge requests by their `approved` status. `yes` returns only approved merge requests. `no` returns only non-approved merge requests. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3159) in GitLab 15.11. Available only when the feature flag `mr_approved_filter` is enabled. | +| `assignee_id` | integer | No | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | +| `author_id` | integer | No | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | +| `author_username` | string | No | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. | +| `created_after` | datetime | No | Returns merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `created_before` | datetime | No | Returns merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `deployed_after` | datetime | No | Returns merge requests deployed after the given date/time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `deployed_before` | datetime | No | Returns merge requests deployed before the given date/time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `environment` | string | No | Returns merge requests deployed to the given environment. | +| `in` | string | No | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description`. | +| `labels` | string | No | Returns merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. Predefined names are case-insensitive. | +| `milestone` | string | No | Returns merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | +| `my_reaction_emoji` | string | No | Returns merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | +| `not` | Hash | No | Returns merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. | +| `order_by` | string | No | Returns requests ordered by `created_at`, `title`, or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8.| +| `reviewer_id` | integer | No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | +| `reviewer_username` | string | No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | +| `scope` | string | No | Returns merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`. | +| `search` | string | No | Search merge requests against their `title` and `description`. | +| `sort` | string | No | Returns requests sorted in `asc` or `desc` order. Default is `desc`. | +| `source_branch` | string | No | Returns merge requests with the given source branch. | +| `state` | string | No | Returns all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. | +| `target_branch` | string | No | Returns merge requests with the given target branch. | +| `updated_after` | datetime | No | Returns merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `updated_before` | datetime | No | Returns merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `view` | string | No | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | +| `with_labels_details` | boolean | No | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. | +| `with_merge_status_recheck` | boolean | No | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. In GitLab 15.11 and later, enable the `restrict_merge_status_recheck` feature [flag](../administration/feature_flags.md) for this attribute to be ignored when requested by users without at least the Developer role. | +| `wip` | string | No | Filter merge requests against their `wip` status. `yes` to return *only* draft merge requests, `no` to return *non-draft* merge requests. | ```json [ @@ -241,36 +241,36 @@ Supported attributes: | Attribute | Type | Required | Description | | ------------------------------- | -------------- | -------- | ----------- | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `approved_by_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | Returns merge requests which have been approved by all the users with the given `id`, with a maximum of 5. `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | -| `approver_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | Returns merge requests which have specified all the users with the given `id` as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | -| `approved` | string | **{dotted-circle}** No | Filters merge requests by their `approved` status. `yes` returns only approved merge requests. `no` returns only non-approved merge requests. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3159) in GitLab 15.11. Available only when the feature flag `mr_approved_filter` is enabled. | -| `assignee_id` | integer | **{dotted-circle}** No | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | -| `author_id` | integer | **{dotted-circle}** No | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. | -| `author_username` | string | **{dotted-circle}** No | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. | -| `created_after` | datetime | **{dotted-circle}** No | Returns merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | -| `created_before` | datetime | **{dotted-circle}** No | Returns merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | -| `environment` | string | **{dotted-circle}** No | Returns merge requests deployed to the given environment. | -| `iids[]` | integer array | **{dotted-circle}** No | Returns the request having the given `iid`. | -| `labels` | string | **{dotted-circle}** No | Returns merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. Predefined names are case-insensitive. | -| `milestone` | string | **{dotted-circle}** No | Returns merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | -| `my_reaction_emoji` | string | **{dotted-circle}** No | Returns merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | -| `not` | Hash | **{dotted-circle}** No | Returns merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. | -| `order_by` | string | **{dotted-circle}** No | Returns requests ordered by `created_at`, `title` or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8. | -| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | -| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | -| `scope` | string | **{dotted-circle}** No | Returns merge requests for the given scope: `created_by_me`, `assigned_to_me`, or `all`. | -| `search` | string | **{dotted-circle}** No | Search merge requests against their `title` and `description`. | -| `sort` | string | **{dotted-circle}** No | Returns requests sorted in `asc` or `desc` order. Default is `desc`. | -| `source_branch` | string | **{dotted-circle}** No | Returns merge requests with the given source branch. | -| `state` | string | **{dotted-circle}** No | Returns all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. | -| `target_branch` | string | **{dotted-circle}** No | Returns merge requests with the given target branch. | -| `updated_after` | datetime | **{dotted-circle}** No | Returns merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | -| `updated_before` | datetime | **{dotted-circle}** No | Returns merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | -| `view` | string | **{dotted-circle}** No | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | -| `wip` | string | **{dotted-circle}** No | Filter merge requests against their `wip` status. `yes` to return *only* draft merge requests, `no` to return *non-draft* merge requests. | -| `with_labels_details` | boolean | **{dotted-circle}** No | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. | -| `with_merge_status_recheck` | boolean | **{dotted-circle}** No | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. In GitLab 15.11 and later, enable the `restrict_merge_status_recheck` feature [flag](../administration/feature_flags.md) for this attribute to be ignored when requested by users without at least the Developer role. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `approved_by_ids` **(PREMIUM)** | integer array | No | Returns merge requests which have been approved by all the users with the given `id`, with a maximum of 5. `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | +| `approver_ids` **(PREMIUM)** | integer array | No | Returns merge requests which have specified all the users with the given `id` as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | +| `approved` | string | No | Filters merge requests by their `approved` status. `yes` returns only approved merge requests. `no` returns only non-approved merge requests. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3159) in GitLab 15.11. Available only when the feature flag `mr_approved_filter` is enabled. | +| `assignee_id` | integer | No | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | +| `author_id` | integer | No | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. | +| `author_username` | string | No | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. | +| `created_after` | datetime | No | Returns merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `created_before` | datetime | No | Returns merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `environment` | string | No | Returns merge requests deployed to the given environment. | +| `iids[]` | integer array | No | Returns the request having the given `iid`. | +| `labels` | string | No | Returns merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. Predefined names are case-insensitive. | +| `milestone` | string | No | Returns merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | +| `my_reaction_emoji` | string | No | Returns merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | +| `not` | Hash | No | Returns merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. | +| `order_by` | string | No | Returns requests ordered by `created_at`, `title` or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8. | +| `reviewer_id` | integer | No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | +| `reviewer_username` | string | No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | +| `scope` | string | No | Returns merge requests for the given scope: `created_by_me`, `assigned_to_me`, or `all`. | +| `search` | string | No | Search merge requests against their `title` and `description`. | +| `sort` | string | No | Returns requests sorted in `asc` or `desc` order. Default is `desc`. | +| `source_branch` | string | No | Returns merge requests with the given source branch. | +| `state` | string | No | Returns all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. | +| `target_branch` | string | No | Returns merge requests with the given target branch. | +| `updated_after` | datetime | No | Returns merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `updated_before` | datetime | No | Returns merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `view` | string | No | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | +| `wip` | string | No | Filter merge requests against their `wip` status. `yes` to return *only* draft merge requests, `no` to return *non-draft* merge requests. | +| `with_labels_details` | boolean | No | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. | +| `with_merge_status_recheck` | boolean | No | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. In GitLab 15.11 and later, enable the `restrict_merge_status_recheck` feature [flag](../administration/feature_flags.md) for this attribute to be ignored when requested by users without at least the Developer role. | ```json [ @@ -418,35 +418,35 @@ Supported attributes: | Attribute | Type | Required | Description | | ------------------------------- | -------------- | -------- | ----------- | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `approved_by_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | Returns merge requests which have been approved by all the users with the given `id`, with a maximum of 5. `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | -| `approved_by_usernames` **(PREMIUM)** | string array | **{dotted-circle}** No | Returns merge requests which have been approved by all the users with the given `username`, with a maximum of 5. `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | -| `approver_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | -| `approved` | string | **{dotted-circle}** No | Filters merge requests by their `approved` status. `yes` returns only approved merge requests. `no` returns only non-approved merge requests. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3159) in GitLab 15.11. Available only when the feature flag `mr_approved_filter` is enabled. | -| `assignee_id` | integer | **{dotted-circle}** No | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | -| `author_id` | integer | **{dotted-circle}** No | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. | -| `author_username` | string | **{dotted-circle}** No | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. | -| `created_after` | datetime | **{dotted-circle}** No | Returns merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | -| `created_before` | datetime | **{dotted-circle}** No | Returns merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | -| `labels` | string | **{dotted-circle}** No | Returns merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. Predefined names are case-insensitive. | -| `milestone` | string | **{dotted-circle}** No | Returns merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | -| `my_reaction_emoji` | string | **{dotted-circle}** No | Returns merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | -| `non_archived` | boolean | **{dotted-circle}** No | Returns merge requests from non archived projects only. Default is `true`. | -| `not` | Hash | **{dotted-circle}** No | Returns merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. | -| `order_by` | string | **{dotted-circle}** No | Returns merge requests ordered by `created_at`, `title` or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8. | -| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | -| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | -| `scope` | string | **{dotted-circle}** No | Returns merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. | -| `search` | string | **{dotted-circle}** No | Search merge requests against their `title` and `description`. | -| `source_branch` | string | **{dotted-circle}** No | Returns merge requests with the given source branch. | -| `sort` | string | **{dotted-circle}** No | Returns merge requests sorted in `asc` or `desc` order. Default is `desc`. | -| `state` | string | **{dotted-circle}** No | Returns all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. | -| `target_branch` | string | **{dotted-circle}** No | Returns merge requests with the given target branch. | -| `updated_after` | datetime | **{dotted-circle}** No | Returns merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | -| `updated_before` | datetime | **{dotted-circle}** No | Returns merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | -| `view` | string | **{dotted-circle}** No | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | -| `with_labels_details` | boolean | **{dotted-circle}** No | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. | -| `with_merge_status_recheck` | boolean | **{dotted-circle}** No | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. In GitLab 15.11 and later, enable the `restrict_merge_status_recheck` feature [flag](../administration/feature_flags.md) for this attribute to be ignored when requested by users without at least the Developer role. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `approved_by_ids` **(PREMIUM)** | integer array | No | Returns merge requests which have been approved by all the users with the given `id`, with a maximum of 5. `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | +| `approved_by_usernames` **(PREMIUM)** | string array | No | Returns merge requests which have been approved by all the users with the given `username`, with a maximum of 5. `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | +| `approver_ids` **(PREMIUM)** | integer array | No | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | +| `approved` | string | No | Filters merge requests by their `approved` status. `yes` returns only approved merge requests. `no` returns only non-approved merge requests. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3159) in GitLab 15.11. Available only when the feature flag `mr_approved_filter` is enabled. | +| `assignee_id` | integer | No | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | +| `author_id` | integer | No | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. | +| `author_username` | string | No | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. | +| `created_after` | datetime | No | Returns merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `created_before` | datetime | No | Returns merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `labels` | string | No | Returns merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. Predefined names are case-insensitive. | +| `milestone` | string | No | Returns merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | +| `my_reaction_emoji` | string | No | Returns merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | +| `non_archived` | boolean | No | Returns merge requests from non archived projects only. Default is `true`. | +| `not` | Hash | No | Returns merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. | +| `order_by` | string | No | Returns merge requests ordered by `created_at`, `title` or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8. | +| `reviewer_id` | integer | No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | +| `reviewer_username` | string | No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | +| `scope` | string | No | Returns merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. | +| `search` | string | No | Search merge requests against their `title` and `description`. | +| `source_branch` | string | No | Returns merge requests with the given source branch. | +| `sort` | string | No | Returns merge requests sorted in `asc` or `desc` order. Default is `desc`. | +| `state` | string | No | Returns all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. | +| `target_branch` | string | No | Returns merge requests with the given target branch. | +| `updated_after` | datetime | No | Returns merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `updated_before` | datetime | No | Returns merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `view` | string | No | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | +| `with_labels_details` | boolean | No | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. | +| `with_merge_status_recheck` | boolean | No | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. In GitLab 15.11 and later, enable the `restrict_merge_status_recheck` feature [flag](../administration/feature_flags.md) for this attribute to be ignored when requested by users without at least the Developer role. | ```json [ @@ -588,11 +588,11 @@ Supported attributes: | Attribute | Type | Required | Description | |----------------------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | -| `include_diverged_commits_count` | boolean | **{dotted-circle}** No | If `true`, response includes the commits behind the target branch. | -| `include_rebase_in_progress` | boolean | **{dotted-circle}** No | If `true`, response includes whether a rebase operation is in progress. | -| `render_html` | boolean | **{dotted-circle}** No | If `true`, response includes rendered HTML for title and description. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +| `include_diverged_commits_count` | boolean | No | If `true`, response includes the commits behind the target branch. | +| `include_rebase_in_progress` | boolean | No | If `true`, response includes whether a rebase operation is in progress. | +| `render_html` | boolean | No | If `true`, response includes rendered HTML for title and description. | ### Response @@ -852,8 +852,8 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```json [ @@ -888,8 +888,8 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```json [ @@ -932,8 +932,8 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```json [ @@ -983,9 +983,9 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | -| `access_raw_diffs` | boolean | **{dotted-circle}** No | Retrieve change diffs via Gitaly. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +| `access_raw_diffs` | boolean | No | Retrieve change diffs via Gitaly. | ```json { @@ -1106,10 +1106,10 @@ Supported attributes: | Attribute | Type | Required | Description | |-----------|------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | -| `page` | integer | **{dotted-circle}** no | The page of results to return. Defaults to 1. | -| `per_page` | integer | **{dotted-circle}** no | The number of results per page. Defaults to 20. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +| `page` | integer | no | The page of results to return. Defaults to 1. | +| `per_page` | integer | no | The number of results per page. Defaults to 20. | If successful, returns [`200 OK`](rest/index.md#status-codes) and the following response attributes: @@ -1171,8 +1171,8 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```json [ @@ -1205,8 +1205,8 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```json { @@ -1257,23 +1257,22 @@ POST /projects/:id/merge_requests | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `source_branch` | string | **{check-circle}** Yes | The source branch. | -| `target_branch` | string | **{check-circle}** Yes | The target branch. | -| `title` | string | **{check-circle}** Yes | Title of MR. | -| `allow_collaboration` | boolean | **{dotted-circle}** No | Allow commits from members who can merge to the target branch. | -| `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | Number of approvals required before this can be merged (see below). To configure approval rules, see [Merge request approvals API](merge_request_approvals.md). [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/353097) in GitLab 16.0. | -| `allow_maintainer_to_push` | boolean | **{dotted-circle}** No | Alias of `allow_collaboration`. | -| `assignee_id` | integer | **{dotted-circle}** No | Assignee user ID. | -| `assignee_ids` | integer array | **{dotted-circle}** No | The ID of the users to assign the merge request to. Set to `0` or provide an empty value to unassign all assignees. | -| `description` | string | **{dotted-circle}** No | Description of the merge request. Limited to 1,048,576 characters. | -| `labels` | string | **{dotted-circle}** No | Labels for the merge request, as a comma-separated list. | -| `milestone_id` | integer | **{dotted-circle}** No | The global ID of a milestone. | -| `remove_source_branch` | boolean | **{dotted-circle}** No | Flag indicating if a merge request should remove the source branch when merging. | -| `reviewer_ids` | integer array | **{dotted-circle}** No | The ID of the users added as a reviewer to the merge request. If set to `0` or left empty, no reviewers are added. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | -| `squash` | boolean | no | Indicates if the merge request is set to be squashed when merged. [Project settings](../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project) may override this value. Use `squash_on_merge` instead to take project squash options into account. | -| `squash_on_merge` | boolean | no | Indicates if the merge request will be squashed when merged. | -| `target_project_id` | integer | **{dotted-circle}** No | Numeric ID of the target project. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | +| `source_branch` | string | Yes | The source branch. | +| `target_branch` | string | Yes | The target branch. | +| `title` | string | Yes | Title of MR. | +| `allow_collaboration` | boolean | No | Allow commits from members who can merge to the target branch. | +| `approvals_before_merge` **(PREMIUM)** | integer | No | Number of approvals required before this can be merged (see below). To configure approval rules, see [Merge request approvals API](merge_request_approvals.md). [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/353097) in GitLab 16.0. | +| `allow_maintainer_to_push` | boolean | No | Alias of `allow_collaboration`. | +| `assignee_id` | integer | No | Assignee user ID. | +| `assignee_ids` | integer array | No | The ID of the users to assign the merge request to. Set to `0` or provide an empty value to unassign all assignees. | +| `description` | string | No | Description of the merge request. Limited to 1,048,576 characters. | +| `labels` | string | No | Labels for the merge request, as a comma-separated list. | +| `milestone_id` | integer | No | The global ID of a milestone. | +| `remove_source_branch` | boolean | No | Flag indicating if a merge request should remove the source branch when merging. | +| `reviewer_ids` | integer array | No | The ID of the users added as a reviewer to the merge request. If set to `0` or left empty, no reviewers are added. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | +| `squash` | boolean | No | Indicates if the merge request is set to be squashed when merged. [Project settings](../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project) may override this value. | +| `target_project_id` | integer | No | Numeric ID of the target project. | ```json { @@ -1409,25 +1408,24 @@ PUT /projects/:id/merge_requests/:merge_request_iid | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The ID of a merge request. | -| `add_labels` | string | **{dotted-circle}** No | Comma-separated label names to add to a merge request. | -| `allow_collaboration` | boolean | **{dotted-circle}** No | Allow commits from members who can merge to the target branch. | -| `allow_maintainer_to_push` | boolean | **{dotted-circle}** No | Alias of `allow_collaboration`. | -| `assignee_id` | integer | **{dotted-circle}** No | The ID of the user to assign the merge request to. Set to `0` or provide an empty value to unassign all assignees. | -| `assignee_ids` | integer array | **{dotted-circle}** No | The ID of the users to assign the merge request to. Set to `0` or provide an empty value to unassign all assignees. | -| `description` | string | **{dotted-circle}** No | Description of the merge request. Limited to 1,048,576 characters. | -| `discussion_locked` | boolean | **{dotted-circle}** No | Flag indicating if the merge request's discussion is locked. If the discussion is locked only project members can add, edit or resolve comments. | -| `labels` | string | **{dotted-circle}** No | Comma-separated label names for a merge request. Set to an empty string to unassign all labels. | -| `milestone_id` | integer | **{dotted-circle}** No | The global ID of a milestone to assign the merge request to. Set to `0` or provide an empty value to unassign a milestone.| -| `remove_labels` | string | **{dotted-circle}** No | Comma-separated label names to remove from a merge request. | -| `remove_source_branch` | boolean | **{dotted-circle}** No | Flag indicating if a merge request should remove the source branch when merging. | -| `reviewer_ids` | integer array | **{dotted-circle}** No | The ID of the users set as a reviewer to the merge request. Set the value to `0` or provide an empty value to unset all reviewers. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | -| `squash` | boolean | no | Indicates if the merge request is set to be squashed when merged. [Project settings](../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project) may override this value. Use `squash_on_merge` instead to take project squash options into account. | -| `squash_on_merge` | boolean | no | Indicates if the merge request will be squashed when merged. | -| `state_event` | string | **{dotted-circle}** No | New state (close/reopen). | -| `target_branch` | string | **{dotted-circle}** No | The target branch. | -| `title` | string | **{dotted-circle}** No | Title of MR. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The ID of a merge request. | +| `add_labels` | string | No | Comma-separated label names to add to a merge request. | +| `allow_collaboration` | boolean | No | Allow commits from members who can merge to the target branch. | +| `allow_maintainer_to_push` | boolean | No | Alias of `allow_collaboration`. | +| `assignee_id` | integer | No | The ID of the user to assign the merge request to. Set to `0` or provide an empty value to unassign all assignees. | +| `assignee_ids` | integer array | No | The ID of the users to assign the merge request to. Set to `0` or provide an empty value to unassign all assignees. | +| `description` | string | No | Description of the merge request. Limited to 1,048,576 characters. | +| `discussion_locked` | boolean | No | Flag indicating if the merge request's discussion is locked. If the discussion is locked only project members can add, edit or resolve comments. | +| `labels` | string | No | Comma-separated label names for a merge request. Set to an empty string to unassign all labels. | +| `milestone_id` | integer | No | The global ID of a milestone to assign the merge request to. Set to `0` or provide an empty value to unassign a milestone.| +| `remove_labels` | string | No | Comma-separated label names to remove from a merge request. | +| `remove_source_branch` | boolean | No | Flag indicating if a merge request should remove the source branch when merging. | +| `reviewer_ids` | integer array | No | The ID of the users set as a reviewer to the merge request. Set the value to `0` or provide an empty value to unset all reviewers. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | +| `squash` | boolean | No | Indicates if the merge request is set to be squashed when merged. [Project settings](../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project) may override this value. | +| `state_event` | string | No | New state (close/reopen). | +| `target_branch` | string | No | The target branch. | +| `title` | string | No | Title of MR. | Must include at least one non-required attribute from above. @@ -1581,8 +1579,8 @@ DELETE /projects/:id/merge_requests/:merge_request_iid | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/merge_requests/85" @@ -1600,14 +1598,14 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | -| `merge_commit_message` | string | **{dotted-circle}** No | Custom merge commit message. | -| `merge_when_pipeline_succeeds` | boolean | **{dotted-circle}** No | If `true`, the merge request is merged when the pipeline succeeds. | -| `sha` | string | **{dotted-circle}** No | If present, then this SHA must match the HEAD of the source branch, otherwise the merge fails. | -| `should_remove_source_branch` | boolean | **{dotted-circle}** No | If `true`, removes the source branch. | -| `squash_commit_message` | string | **{dotted-circle}** No | Custom squash commit message. | -| `squash` | boolean | **{dotted-circle}** No | If `true`, the commits are squashed into a single commit on merge. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +| `merge_commit_message` | string | No | Custom merge commit message. | +| `merge_when_pipeline_succeeds` | boolean | No | If `true`, the merge request is merged when the pipeline succeeds. | +| `sha` | string | No | If present, then this SHA must match the HEAD of the source branch, otherwise the merge fails. | +| `should_remove_source_branch` | boolean | No | If `true`, removes the source branch. | +| `squash_commit_message` | string | No | Custom squash commit message. | +| `squash` | boolean | No | If `true`, the commits are squashed into a single commit on merge. | ```json { @@ -1781,8 +1779,8 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```json { @@ -1808,8 +1806,8 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```json { @@ -1965,9 +1963,9 @@ PUT /projects/:id/merge_requests/:merge_request_iid/rebase | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | -| `skip_ci` | boolean | **{dotted-circle}** No | Set to `true` to skip creating a CI pipeline. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +| `skip_ci` | boolean | No | Set to `true` to skip creating a CI pipeline. | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/76/merge_requests/1/rebase" @@ -2028,8 +2026,8 @@ GET /projects/:id/merge_requests/:merge_request_iid/closes_issues | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/76/merge_requests/1/closes_issues" @@ -2104,8 +2102,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/subscribe | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/17/subscribe" @@ -2264,8 +2262,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/unsubscribe | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/17/unsubscribe" @@ -2424,8 +2422,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/todo | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/27/todo" @@ -2552,8 +2550,8 @@ GET /projects/:id/merge_requests/:merge_request_iid/versions | Attribute | Type | Required | Description | |---------------------|---------|----------|---------------------------------------| -| `id` | String | **{check-circle}** Yes | The ID of the project. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | String | Yes | The ID of the project. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/merge_requests/1/versions" @@ -2602,9 +2600,9 @@ GET /projects/:id/merge_requests/:merge_request_iid/versions/:version_id | Attribute | Type | Required | Description | |---------------------|---------|----------|-------------------------------------------| -| `id` | String | **{check-circle}** Yes | The ID of the project. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | -| `version_id` | integer | **{check-circle}** Yes | The ID of the merge request diff version. | +| `id` | String | Yes | The ID of the project. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +| `version_id` | integer | Yes | The ID of the merge request diff version. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/merge_requests/1/versions/1" @@ -2670,9 +2668,9 @@ POST /projects/:id/merge_requests/:merge_request_iid/time_estimate | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | -| `duration` | string | **{check-circle}** Yes | The duration in human format, such as `3h30m`. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +| `duration` | string | Yes | The duration in human format, such as `3h30m`. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/93/time_estimate?duration=3h30m" @@ -2699,8 +2697,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_time_estimate | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of a project's merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of a project's merge request. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/93/reset_time_estimate" @@ -2727,10 +2725,10 @@ POST /projects/:id/merge_requests/:merge_request_iid/add_spent_time | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | -| `duration` | string | **{check-circle}** Yes | The duration in human format, such as `3h30m` | -| `summary` | string | **{dotted-circle}** No | A summary of how the time was spent. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +| `duration` | string | Yes | The duration in human format, such as `3h30m` | +| `summary` | string | No | A summary of how the time was spent. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/93/add_spent_time?duration=1h" @@ -2757,8 +2755,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_spent_time | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of a project's merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of a project's merge request. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/93/reset_spent_time" @@ -2783,8 +2781,8 @@ GET /projects/:id/merge_requests/:merge_request_iid/time_stats | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/93/time_stats" diff --git a/doc/api/merge_trains.md b/doc/api/merge_trains.md index 536cf616a88..8ef6a318ced 100644 --- a/doc/api/merge_trains.md +++ b/doc/api/merge_trains.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Merge Trains API **(PREMIUM)** +# Merge Trains API **(PREMIUM ALL)** Every API call for [merge train](../ci/pipelines/merge_trains.md) must be authenticated with at lease the Developer [role](../user/permissions.md). diff --git a/doc/api/metadata.md b/doc/api/metadata.md index 9a02ca2a5e4..88afc9719a7 100644 --- a/doc/api/metadata.md +++ b/doc/api/metadata.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Metadata API **(FREE)** +# Metadata API **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357032) in GitLab 15.2. > - `enterprise` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103969) in GitLab 15.6. diff --git a/doc/api/metrics_dashboard_annotations.md b/doc/api/metrics_dashboard_annotations.md index 99d7b01d1a0..37d19860e6a 100644 --- a/doc/api/metrics_dashboard_annotations.md +++ b/doc/api/metrics_dashboard_annotations.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Dashboard annotations API **(FREE)** +# Dashboard annotations API **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29089) in GitLab 12.10 behind a disabled feature flag. diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index 80d47da94e0..6e839e75ae9 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# User-starred metrics dashboards API **(FREE)** +# User-starred metrics dashboards API **(FREE ALL)** The starred dashboard feature makes navigating to frequently-used dashboards easier by displaying favorited dashboards at the top of the select list. diff --git a/doc/api/milestones.md b/doc/api/milestones.md index e1acf4c14bb..38c11216e4f 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.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/product/ux/technical-writing/#assignments --- -# Project milestones API **(FREE)** +# Project milestones API **(FREE ALL)** Use project [milestones](../user/project/milestones/index.md) with the REST API. There's a separate [group milestones API](group_milestones.md) page. @@ -92,8 +92,8 @@ Parameters: | `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | The title of a milestone | | `description` | string | no | The description of the milestone | -| `due_date` | string | no | The due date of the milestone (`YYYYMMDD`) | -| `start_date` | string | no | The start date of the milestone (`YYYYMMDD`) | +| `due_date` | string | no | The due date of the milestone (`YYYY-MM-DD`) | +| `start_date` | string | no | The start date of the milestone (`YYYY-MM-DD`) | ## Edit milestone @@ -111,8 +111,8 @@ Parameters: | `milestone_id` | integer | yes | The ID of the project's milestone | | `title` | string | no | The title of a milestone | | `description` | string | no | The description of the milestone | -| `due_date` | string | no | The due date of the milestone (`YYYYMMDD`) | -| `start_date` | string | no | The start date of the milestone (`YYYYMMDD`) | +| `due_date` | string | no | The due date of the milestone (`YYYY-MM-DD`) | +| `start_date` | string | no | The start date of the milestone (`YYYY-MM-DD`) | | `state_event` | string | no | The state event of the milestone (close or activate) | ## Delete project milestone @@ -179,7 +179,7 @@ Parameters: | `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | -## Get all burndown chart events for a single milestone **(PREMIUM)** +## Get all burndown chart events for a single milestone **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4737) in GitLab 12.1 > - Moved to GitLab Premium in 13.9. diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index ddf56209be2..1ede530578b 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -4,7 +4,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 --- -# Namespaces API **(FREE)** +# Namespaces API **(FREE ALL)** Usernames and group names fall under a special category called [namespaces](../user/namespace/index.md). diff --git a/doc/api/notes.md b/doc/api/notes.md index ab8abc0973f..3df8b787667 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.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/product/ux/technical-writing/#assignments --- -# Notes API **(FREE)** +# Notes API **(FREE ALL)** Notes are comments on: @@ -466,7 +466,7 @@ Parameters: curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602" ``` -## Epics **(PREMIUM)** +## Epics **(PREMIUM ALL)** ### List all epic notes diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index aa8e47d6141..c4b2d90f2c7 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.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/product/ux/technical-writing/#assignments --- -# Notification settings API **(FREE)** +# Notification settings API **(FREE ALL)** Change [notification settings](../user/profile/notifications.md) using the REST API. @@ -200,7 +200,7 @@ Example responses: ``` Users on [GitLab Ultimate](https://about.gitlab.com/pricing/) also see the `new_epic` -parameter: +parameter for global and group-level notification settings: ```json { diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index eb9d1d3bc8a..75b50829ddd 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.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 --- -# OAuth 2.0 identity provider API **(FREE)** +# OAuth 2.0 identity provider API **(FREE ALL)** GitLab provides an API to allow third-party services to access GitLab resources on a user's behalf with the [OAuth 2.0](https://oauth.net/2/) protocol. @@ -362,6 +362,10 @@ The username must be `oauth2`, not your username: https://oauth2:<your_access_token>@gitlab.example.com/project_path/project_name.git ``` +Alternatively, you can use a [Git credential helper](../user/profile/account/two_factor_authentication.md#oauth-credential-helpers) +to authenticate to GitLab with OAuth. This handles OAuth token refresh +automatically. + ## Retrieve the token information To verify the details of a token, use the `token/info` endpoint provided by the diff --git a/doc/api/packages.md b/doc/api/packages.md index efb27a29e0f..ac692956f22 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Packages API **(FREE)** +# Packages API **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/349418) support for [GitLab CI/CD job token](../ci/jobs/ci_job_token.md) authentication for the project-level API in GitLab 15.3. diff --git a/doc/api/packages/composer.md b/doc/api/packages/composer.md index 857f87a751e..ae986b082d6 100644 --- a/doc/api/packages/composer.md +++ b/doc/api/packages/composer.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Composer API **(FREE)** +# Composer API **(FREE ALL)** This is the API documentation for [Composer Packages](../../user/packages/composer_repository/index.md). diff --git a/doc/api/packages/conan.md b/doc/api/packages/conan.md index a2c20756737..92e9f687242 100644 --- a/doc/api/packages/conan.md +++ b/doc/api/packages/conan.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Conan API **(FREE)** +# Conan API **(FREE ALL)** This is the API documentation for [Conan Packages](../../user/packages/conan_repository/index.md). diff --git a/doc/api/packages/helm.md b/doc/api/packages/helm.md index d69f524c47c..0a6bee6e55c 100644 --- a/doc/api/packages/helm.md +++ b/doc/api/packages/helm.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Helm API **(FREE)** +# Helm API **(FREE ALL)** This is the API documentation for [Helm](../../user/packages/helm_repository/index.md). diff --git a/doc/api/packages/maven.md b/doc/api/packages/maven.md index 733f4735ba2..fc81f41d52b 100644 --- a/doc/api/packages/maven.md +++ b/doc/api/packages/maven.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Maven API **(FREE)** +# Maven API **(FREE ALL)** This is the API documentation for [Maven Packages](../../user/packages/maven_repository/index.md). diff --git a/doc/api/packages/npm.md b/doc/api/packages/npm.md index 3aa23ad1044..0bfc39ab92b 100644 --- a/doc/api/packages/npm.md +++ b/doc/api/packages/npm.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# npm API **(FREE)** +# npm API **(FREE ALL)** This is the API documentation for [npm Packages](../../user/packages/npm_registry/index.md). diff --git a/doc/api/packages/nuget.md b/doc/api/packages/nuget.md index afe384b5a29..a549d6af086 100644 --- a/doc/api/packages/nuget.md +++ b/doc/api/packages/nuget.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# NuGet API **(FREE)** +# NuGet API **(FREE ALL)** This is the API documentation for [NuGet Packages](../../user/packages/nuget_repository/index.md). @@ -80,13 +80,22 @@ This writes the downloaded file to `MyNuGetPkg.1.3.0.17.nupkg` in the current di ## Upload a package file -> Introduced in GitLab 12.8. +> - Introduced in GitLab 12.8 for NuGet v3 feed. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416404) in GitLab 16.2 for NuGet v2 feed. Upload a NuGet package file: -```plaintext -PUT projects/:id/packages/nuget -``` +- For NuGet v3 feed: + + ```plaintext + PUT projects/:id/packages/nuget + ``` + +- For NuGet V2 feed: + + ```plaintext + PUT projects/:id/packages/nuget/v2 + ``` | Attribute | Type | Required | Description | | ----------------- | ------ | -------- | ----------- | @@ -95,12 +104,23 @@ PUT projects/:id/packages/nuget | `package_version` | string | yes | The version of the package. | | `package_filename`| string | yes | The name of the file. | -```shell -curl --request PUT \ - --form 'package=@path/to/mynugetpkg.1.3.0.17.nupkg' \ - --user <username>:<personal_access_token> \ - "https://gitlab.example.com/api/v4/projects/1/packages/nuget/" -``` +- For NuGet v3 feed: + + ```shell + curl --request PUT \ + --form 'package=@path/to/mynugetpkg.1.3.0.17.nupkg' \ + --user <username>:<personal_access_token> \ + "https://gitlab.example.com/api/v4/projects/1/packages/nuget/" + ``` + +- For NuGet v2 feed: + + ```shell + curl --request PUT \ + --form 'package=@path/to/mynugetpkg.1.3.0.17.nupkg' \ + --user <username>:<personal_access_token> \ + "https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2" + ``` ## Upload a symbol package file @@ -158,6 +178,37 @@ The examples in this document all use the project-level prefix. ## Service Index +### V2 source feed/protocol + +Returns an XML document that represents the service index of the v2 NuGet source feed. +Authentication is not required: + +```plaintext +GET <route-prefix>/v2 +``` + +Example Request: + +```shell +curl "https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2" +``` + +Example response: + +```xml +<?xml version="1.0" encoding="utf-8"?> +<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom" xml:base="https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2"> + <workspace> + <atom:title type="text">Default</atom:title> + <collection href="Packages"> + <atom:title type="text">Packages</atom:title> + </collection> + </workspace> +</service> +``` + +### V3 source feed/protocol + > - Introduced in GitLab 12.6. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/214674) to be public in GitLab 16.1. @@ -273,7 +324,8 @@ Example response: "version": "1.3.0.17", "tags": "", "packageContent": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/helloworld.1.3.0.17.nupkg", - "summary": "Summary of the package", + "description": "Description of the package", + "summary": "Description of the package", "published": "2023-05-08T17:23:25Z", } } @@ -316,7 +368,8 @@ Example response: "version": "1.3.0.17", "tags": "", "packageContent": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/helloworld.1.3.0.17.nupkg", - "summary": "Summary of the package", + "description": "Description of the package", + "summary": "Description of the package", "published": "2023-05-08T17:23:25Z", } } @@ -354,7 +407,8 @@ Example response: "authors": "Author1, Author2", "id": "MyNuGetPkg", "title": "MyNuGetPkg", - "summary": "Summary of the package", + "description": "Description of the package", + "summary": "Description of the package", "totalDownloads": 0, "verified": true, "version": "1.3.0.17", @@ -370,3 +424,54 @@ Example response: ] } ``` + +## V2 Feed Metadata Endpoint + +> Introduced in GitLab 16.3. + +Authentication is not required. Returns metadata for a V2 feed available endpoints: + +```plaintext +GET <route-prefix>/v2/$metadata +``` + +```shell + curl "https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2/$metadata" +``` + +Example response: + +```xml +<edmx:Edmx xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx" Version="1.0"> + <edmx:DataServices xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:DataServiceVersion="2.0" m:MaxDataServiceVersion="2.0"> + <Schema xmlns="http://schemas.microsoft.com/ado/2006/04/edm" Namespace="NuGetGallery.OData"> + <EntityType Name="V2FeedPackage" m:HasStream="true"> + <Key> + <PropertyRef Name="Id"/> + <PropertyRef Name="Version"/> + </Key> + <Property Name="Id" Type="Edm.String" Nullable="false"/> + <Property Name="Version" Type="Edm.String" Nullable="false"/> + <Property Name="Authors" Type="Edm.String"/> + <Property Name="Dependencies" Type="Edm.String"/> + <Property Name="Description" Type="Edm.String"/> + <Property Name="DownloadCount" Type="Edm.Int64" Nullable="false"/> + <Property Name="IconUrl" Type="Edm.String"/> + <Property Name="Published" Type="Edm.DateTime" Nullable="false"/> + <Property Name="ProjectUrl" Type="Edm.String"/> + <Property Name="Tags" Type="Edm.String"/> + <Property Name="Title" Type="Edm.String"/> + <Property Name="LicenseUrl" Type="Edm.String"/> + </EntityType> + </Schema> + <Schema xmlns="http://schemas.microsoft.com/ado/2006/04/edm" Namespace="NuGetGallery"> + <EntityContainer Name="V2FeedContext" m:IsDefaultEntityContainer="true"> + <EntitySet Name="Packages" EntityType="NuGetGallery.OData.V2FeedPackage"/> + <FunctionImport Name="FindPackagesById" ReturnType="Collection(NuGetGallery.OData.V2FeedPackage)" EntitySet="Packages"> + <Parameter Name="id" Type="Edm.String" FixedLength="false" Unicode="false"/> + </FunctionImport> + </EntityContainer> + </Schema> + </edmx:DataServices> +</edmx:Edmx> +``` diff --git a/doc/api/packages/pypi.md b/doc/api/packages/pypi.md index 1b155feb8b5..f13665f16c9 100644 --- a/doc/api/packages/pypi.md +++ b/doc/api/packages/pypi.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# PyPI API **(FREE)** +# PyPI API **(FREE ALL)** This is the API documentation for [PyPI Packages](../../user/packages/pypi_repository/index.md). @@ -28,7 +28,7 @@ is recommended when [FIPS mode](../../development/fips_compliance.md) is enabled > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225545) in GitLab 13.12. -Download a PyPI package file. The [simple API](#group-level-simple-api-entry-point) +Download a PyPI package file. The [simple API](#group-level-simple-api-entry-point) usually supplies this URL. ```plaintext diff --git a/doc/api/packages/terraform-modules.md b/doc/api/packages/terraform-modules.md index ff6ac24495e..30775be5d28 100644 --- a/doc/api/packages/terraform-modules.md +++ b/doc/api/packages/terraform-modules.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Terraform Module Registry API **(FREE)** +# Terraform Module Registry API **(FREE ALL)** This is the API documentation for the [Terraform Module Registry](../../user/packages/terraform_module_registry/index.md). diff --git a/doc/api/pages.md b/doc/api/pages.md index 2821f5d510c..1a1ccf4143d 100644 --- a/doc/api/pages.md +++ b/doc/api/pages.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# Pages API **(FREE)** +# Pages API **(FREE ALL)** Endpoints for managing [GitLab Pages](https://about.gitlab.com/stages-devops-lifecycle/pages/). diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 7d52c803c88..d66c2d9d567 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# Pages domains API **(FREE)** +# Pages domains API **(FREE ALL)** Endpoints for connecting custom domains and TLS certificates in [GitLab Pages](https://about.gitlab.com/stages-devops-lifecycle/pages/). diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index 691c094f9eb..901f99caee7 100644 --- a/doc/api/personal_access_tokens.md +++ b/doc/api/personal_access_tokens.md @@ -4,9 +4,9 @@ group: Compliance 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 --- -# Personal access tokens API **(FREE)** +# Personal access tokens API **(FREE ALL)** -You can read more about [personal access tokens](../user/profile/personal_access_tokens.md#personal-access-tokens). +You can read more about [personal access tokens](../user/profile/personal_access_tokens.md). ## List personal access tokens @@ -235,6 +235,21 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla - Token with the specified ID does not exist. - `404: Not Found` if the user is an administrator but the token with the specified ID does not exist. +### Automatic reuse detection + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/395352) in GitLab 16.3 + +For each rotated token, the previous and now revoked token is referenced. This +chain of references defines a token family. In a token family, only the latest +token is active, and all other tokens in that family are revoked. + +When a revoked token from a token family is used in an authentication attempt, +that attempt fails and the active token from the token family gets revoked. +This mechanism helps to prevent compromise when a personal access token is +leaked. + +Automatic reuse detection is enabled for API requests. + ## Revoke a personal access token Revoke a personal access token by either: diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md index 115e5b279b8..871d6d42885 100644 --- a/doc/api/pipeline_schedules.md +++ b/doc/api/pipeline_schedules.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Pipeline schedules API **(FREE)** +# Pipeline schedules API **(FREE ALL)** You can read more about [pipeline schedules](../ci/pipelines/schedules.md). diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md index c62e622e31e..a3fbed600ff 100644 --- a/doc/api/pipeline_triggers.md +++ b/doc/api/pipeline_triggers.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Pipeline trigger tokens API **(FREE)** +# Pipeline trigger tokens API **(FREE ALL)** You can read more about [triggering pipelines through the API](../ci/triggers/index.md). @@ -43,7 +43,7 @@ user. Trigger tokens created by other users are shortened to four characters. ## Get trigger token details -Get details of a project's pipeline trigger. +Get details of a project's pipeline trigger token. ```plaintext GET /projects/:id/triggers/:trigger_id @@ -72,7 +72,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ## Create a trigger token -Create a pipeline trigger for a project. +Create a pipeline trigger token for a project. ```plaintext POST /projects/:id/triggers @@ -100,9 +100,9 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ } ``` -## Update a project trigger token +## Update a pipeline trigger token -Update a pipeline trigger token for a project. +Update a project's pipeline trigger token. ```plaintext PUT /projects/:id/triggers/:trigger_id @@ -131,7 +131,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ } ``` -## Remove a project trigger token +## Remove a pipeline trigger token Remove a project's pipeline trigger token. @@ -150,7 +150,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git ## Trigger a pipeline with a token -Trigger a pipeline by using a pipeline [trigger token](../ci/triggers/index.md#create-a-trigger-token) +Trigger a pipeline by using a [pipeline trigger token](../ci/triggers/index.md#create-a-pipeline-trigger-token) or a [CI/CD job token](../ci/jobs/ci_job_token.md) for authentication. With a CI/CD job token, the [triggered pipeline is a multi-project pipeline](../ci/pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api). diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 4fca878fcec..e908f4adb34 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Pipelines API **(FREE)** +# Pipelines API **(FREE ALL)** ## Pipelines pagination @@ -16,13 +16,15 @@ Read more on [pagination](rest/index.md#pagination). ## List project pipelines > - `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6. -> - `name` in request and response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115310) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `pipeline_name_in_api`. Disabled by default. +> - `name` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115310) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `pipeline_name_in_api`. Disabled by default. +> - `name` in request [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115310) in 15.11 [with a flag](../administration/feature_flags.md) named `pipeline_name_search`. Disabled by default. +> - `name` in response [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/398131) in GitLab 16.3. Feature flag `pipeline_name_in_api` removed. FLAG: -On self-managed GitLab, by default the `name` field is not available. +On self-managed GitLab, by default the `name` field in a request is ignored. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) -named `pipeline_name_in_api`. This feature is not ready for production use. -On GitLab.com, this feature is not available. +named `pipeline_name_search`. +On GitLab.com, this feature is available. List pipelines in a project. Child pipelines are not included in the results, but you can [get child pipeline](pipelines.md#get-a-single-pipeline) individually. @@ -88,12 +90,7 @@ Example of response > - `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6. > - `name` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115310) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `pipeline_name_in_api`. Disabled by default. - -FLAG: -On self-managed GitLab, by default the `name` field is not available. -To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) -named `pipeline_name_in_api`. This feature is not ready for production use. -On GitLab.com, this feature is not available. +> - `name` in response [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/398131) in GitLab 16.3. Feature flag `pipeline_name_in_api` removed. Get one pipeline from a project. @@ -286,13 +283,8 @@ Sample response: ## Get the latest pipeline -> `name` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115310) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `pipeline_name_in_api`. Disabled by default. - -FLAG: -On self-managed GitLab, by default the `name` field is not available. -To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) -named `pipeline_name_in_api`. This feature is not ready for production use. -On GitLab.com, this feature is not available. +> - `name` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115310) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `pipeline_name_in_api`. Disabled by default. +> - `name` in response [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/398131) in GitLab 16.3. Feature flag `pipeline_name_in_api` removed. Get the latest pipeline for a specific ref in a project. diff --git a/doc/api/product_analytics.md b/doc/api/product_analytics.md index 70f0d40f7b5..efa9c637fea 100644 --- a/doc/api/product_analytics.md +++ b/doc/api/product_analytics.md @@ -4,7 +4,7 @@ group: Product Analytics 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 --- -# Product analytics API **(ULTIMATE)** +# Product analytics API **(ULTIMATE ALL)** > - Introduced in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default. > - `cube_api_proxy` removed and replaced with `product_analytics_internal_preview` in GitLab 15.10. diff --git a/doc/api/project_access_tokens.md b/doc/api/project_access_tokens.md index 36129bf6576..41bfcbd209b 100644 --- a/doc/api/project_access_tokens.md +++ b/doc/api/project_access_tokens.md @@ -4,7 +4,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 --- -# Project access tokens API **(FREE)** +# Project access tokens API **(FREE ALL)** You can read more about [project access tokens](../user/project/settings/project_access_tokens.md). @@ -161,6 +161,11 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla - Token with the specified ID does not exist. - `404: Not Found` if the user is an administrator but the token with the specified ID does not exist. +### Automatic reuse detection + +Refer to [automatic reuse detection for personal access tokens](personal_access_tokens.md#automatic-reuse-detection) +for more information. + ## Revoke a project access token > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238991) in GitLab 13.9. diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md index a8940a7875c..5c621bf6426 100644 --- a/doc/api/project_badges.md +++ b/doc/api/project_badges.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Project badges API **(FREE)** +# Project badges API **(FREE ALL)** ## Placeholder tokens diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index 65efcaf13b9..85aa28804b0 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Project clusters API (certificate-based) (deprecated) **(FREE)** +# Project clusters API (certificate-based) (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23922) in GitLab 11.7. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index bae300efaf4..113504aba8a 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Project import and export API **(FREE)** +# Project import and export API **(FREE ALL)** Use the project import and export API to import and export projects using file transfers. diff --git a/doc/api/project_job_token_scopes.md b/doc/api/project_job_token_scopes.md index 4d1e013ee14..4117c8c4971 100644 --- a/doc/api/project_job_token_scopes.md +++ b/doc/api/project_job_token_scopes.md @@ -4,7 +4,7 @@ group: Pipeline Security 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" --- -# Project CI/CD job token scope API **(FREE)** +# Project CI/CD job token scope API **(FREE ALL)** You can read more about the [CI/CD job token](../ci/jobs/ci_job_token.md) @@ -50,7 +50,9 @@ Example response: ## Patch a project's CI/CD job token access settings -Patch the [**Allow access to this project with a CI_JOB_TOKEN** setting](../ci/jobs/ci_job_token.md#disable-the-job-token-scope-allowlist) (job token scope) of a project. +> **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3. + +Patch the [**Limit access _to_ this project** setting](../ci/jobs/ci_job_token.md#disable-the-job-token-scope-allowlist) (job token scope) of a project. ```plaintext PATCH /projects/:id/job_token_scope @@ -142,7 +144,7 @@ Example response: } ``` -## Create a new project to a project's CI/CD job token inbound allowlist +## Add a project to a CI/CD job token inbound allowlist Add a project to the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#allow-access-to-your-project-with-a-job-token) of a project. @@ -159,16 +161,16 @@ Supported attributes: If successful, returns [`201`](rest/index.md#status-codes) and the following response attributes: -| Attribute | Type | Description | -|:--------------------|:--------|:----------------------| -| `source_project_id` | integer | The ID of the project whose CI/CD job token inbound allowlist is added to. | -| `target_project_id` | integer | The ID of the project that is added to the inbound allowlist of the source project. | +| Attribute | Type | Description | +|---------------------|---------|-------------| +| `source_project_id` | integer | ID of the project containing the CI/CD job token inbound allowlist to update. | +| `target_project_id` | integer | ID of the project that is added to the source project's inbound allowlist. | Example request: ```shell -curl --request PATCH \ - --url "https://gitlab.example.com/api/v4/projects/1/job_token_scope" \ +curl --request POST \ + --url "https://gitlab.example.com/api/v4/projects/1/job_token_scope/allowlist" \ --header 'PRIVATE-TOKEN: <your_access_token>' \ --header 'Content-Type: application/json' \ --data '{ "target_project_id": 2 }' @@ -183,7 +185,7 @@ Example response: } ``` -## Remove a project from a project's CI/CD job token inbound allowlist +## Remove a project from a CI/CD job token inbound allowlist Remove a project from the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#allow-access-to-your-project-with-a-job-token) of a project. @@ -203,7 +205,6 @@ If successful, returns [`204`](rest/index.md#status-codes) and no response body. Example request: ```shell - curl --request DELETE \ --url "https://gitlab.example.com/api/v4/projects/1/job_token_scope/allowlist/2" \ --header 'PRIVATE-TOKEN: <your_access_token>' \ diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index 46e491453f9..7cc10816f5e 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, api --- -# Project-level CI/CD variables API **(FREE)** +# Project-level CI/CD variables API **(FREE ALL)** ## List project variables diff --git a/doc/api/project_relations_export.md b/doc/api/project_relations_export.md index e209259c6cc..bce3c6271af 100644 --- a/doc/api/project_relations_export.md +++ b/doc/api/project_relations_export.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Project relations export API **(FREE)** +# Project relations export API **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70330) in GitLab 14.4 behind the `bulk_import` [feature flag](../administration/feature_flags.md), disabled by default. diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index b82e46a03cc..7a7f34046d2 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Project snippets **(FREE)** +# Project snippets **(FREE ALL)** ## Snippet visibility level diff --git a/doc/api/project_statistics.md b/doc/api/project_statistics.md index 2bf8a908116..adc977d7d73 100644 --- a/doc/api/project_statistics.md +++ b/doc/api/project_statistics.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Project statistics API **(FREE)** +# Project statistics API **(FREE ALL)** Every API call to [project](../user/project/index.md) statistics must be authenticated. Retrieving these statistics requires write access to the repository. diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index dfcfa3d7254..dad09b0e479 100644 --- a/doc/api/project_templates.md +++ b/doc/api/project_templates.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Project templates API **(FREE)** +# Project templates API **(FREE ALL)** This API is a project-specific version of these endpoints: diff --git a/doc/api/project_vulnerabilities.md b/doc/api/project_vulnerabilities.md index 446c629c3bf..c38ee31ddfc 100644 --- a/doc/api/project_vulnerabilities.md +++ b/doc/api/project_vulnerabilities.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Project Vulnerabilities API **(ULTIMATE)** +# Project Vulnerabilities API **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in GitLab 12.6. diff --git a/doc/api/projects.md b/doc/api/projects.md index 6afed915135..5bd2ec07647 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -4,7 +4,7 @@ group: Tenant Scale 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 --- -# Projects API **(FREE)** +# Projects API **(FREE ALL)** Interact with [projects](../user/project/index.md) by using the REST API. @@ -222,6 +222,7 @@ When the user is authenticated and `simple` is not set this returns something li "container_registry_access_level": "enabled", "security_and_compliance_access_level": "private", "emails_disabled": null, + "emails_enabled": null, "shared_runners_enabled": true, "group_runners_enabled": true, "lfs_enabled": true, @@ -233,6 +234,7 @@ When the user is authenticated and `simple` is not set this returns something li "open_issues_count": 0, "ci_default_git_depth": 20, "ci_forward_deployment_enabled": true, + "ci_forward_deployment_rollback_allowed": true, "ci_allow_fork_pipelines_to_run_in_parent_project": true, "ci_job_token_scope_enabled": false, "ci_separated_caches": true, @@ -406,6 +408,7 @@ GET /users/:user_id/projects "runners_token": "b8547b1dc37721d05889db52fa2f02", "ci_default_git_depth": 50, "ci_forward_deployment_enabled": true, + "ci_forward_deployment_rollback_allowed": true, "ci_allow_fork_pipelines_to_run_in_parent_project": true, "ci_separated_caches": true, "public_jobs": true, @@ -524,6 +527,7 @@ GET /users/:user_id/projects "runners_token": "b8547b1dc37721d05889db52fa2f02", "ci_default_git_depth": 0, "ci_forward_deployment_enabled": true, + "ci_forward_deployment_rollback_allowed": true, "ci_allow_fork_pipelines_to_run_in_parent_project": true, "ci_separated_caches": true, "public_jobs": true, @@ -1193,6 +1197,7 @@ GET /projects/:id "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", "ci_default_git_depth": 50, "ci_forward_deployment_enabled": true, + "ci_forward_deployment_rollback_allowed": true, "ci_allow_fork_pipelines_to_run_in_parent_project": true, "ci_separated_caches": true, "public_jobs": true, @@ -1333,7 +1338,7 @@ target the upstream project by default. } ``` -### Templates for issues and merge requests **(PREMIUM)** +### Templates for issues and merge requests **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55718) in GitLab 13.10. @@ -1482,7 +1487,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \ --header "Content-Type: application/json" --data '{ "name": "new_project", "description": "New Project", "path": "new_project", "namespace_id": "42", "initialize_with_readme": "true"}' \ - --url 'https://gitlab.example.com/api/v4/projects/' + --url "https://gitlab.example.com/api/v4/projects/" ``` | Attribute | Type | Required | Description | @@ -1507,9 +1512,11 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \ | `container_registry_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable container registry for this project. Use `container_registry_access_level` instead. | | `default_branch` | string | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. Requires `initialize_with_readme` to be `true`. | | `description` | string | **{dotted-circle}** No | Short project description. | -| `emails_disabled` | boolean | **{dotted-circle}** No | Disable email notifications. | +| `emails_disabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Disable email notifications. Use `emails_enabled` instead| +| `emails_enabled` | boolean | **{dotted-circle}** No | Enable email notifications. | | `external_authorization_classification_label` **(PREMIUM)** | string | **{dotted-circle}** No | The classification label for the project. | | `forking_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `group_runners_enabled` | boolean | **{dotted-circle}** No | Enable group runners for this project. | | `group_with_project_templates_id` **(PREMIUM)** | integer | **{dotted-circle}** No | For group-level custom templates, specifies ID of group from which all the custom project templates are sourced. Leave empty for instance-level templates. Requires `use_custom_template` to be true. | | `import_url` | string | **{dotted-circle}** No | URL to import repository from. When the URL value isn't empty, you must not set `initialize_with_readme` to `true`. Doing so might result in the [following error](https://gitlab.com/gitlab-org/gitlab/-/issues/360266): `not a git repository`. | | `initialize_with_readme` | boolean | **{dotted-circle}** No | Whether to create a Git repository with just a `README.md` file. Default is `false`. When this boolean is true, you must not pass `import_url` or other attributes of this endpoint which specify alternative contents for the repository. Doing so might result in the [following error](https://gitlab.com/gitlab-org/gitlab/-/issues/360266): `not a git repository`. | @@ -1544,7 +1551,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \ | `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | | `security_and_compliance_access_level` | string | **{dotted-circle}** No | (GitLab 14.9 and later) Security and compliance access level. One of `disabled`, `private`, or `enabled`. | | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | -| `group_runners_enabled` | boolean | **{dotted-circle}** No | Enable group runners for this project. | +| `show_default_award_emojis` | boolean | **{dotted-circle}** No | Show default award emojis. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | | `squash_option` | string | **{dotted-circle}** No | One of `never`, `always`, `default_on`, or `default_off`. | @@ -1592,10 +1599,12 @@ POST /projects/user/:user_id | `container_registry_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable container registry for this project. Use `container_registry_access_level` instead. | | `default_branch` | string | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. Requires `initialize_with_readme` to be `true`. | | `description` | string | **{dotted-circle}** No | Short project description. | -| `emails_disabled` | boolean | **{dotted-circle}** No | Disable email notifications. | +| `emails_disabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Disable email notifications. Use `emails_enabled` instead| +| `emails_enabled` | boolean | **{dotted-circle}** No | Enable email notifications. | | `enforce_auth_checks_on_uploads` | boolean | **{dotted-circle}** No | Enforce [auth checks](../security/user_file_uploads.md#enable-authorization-checks-for-all-media-files) on uploads. | | `external_authorization_classification_label` **(PREMIUM)** | string | **{dotted-circle}** No | The classification label for the project. | | `forking_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `group_runners_enabled` | boolean | **{dotted-circle}** No | Enable group runners for this project. | | `group_with_project_templates_id` **(PREMIUM)** | integer | **{dotted-circle}** No | For group-level custom templates, specifies ID of group from which all the custom project templates are sourced. Leave empty for instance-level templates. Requires `use_custom_template` to be true. | | `import_url` | string | **{dotted-circle}** No | URL to import repository from. | | `initialize_with_readme` | boolean | **{dotted-circle}** No | `false` by default. | @@ -1630,7 +1639,7 @@ POST /projects/user/:user_id | `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | | `security_and_compliance_access_level` | string | **{dotted-circle}** No | (GitLab 14.9 and later) Security and compliance access level. One of `disabled`, `private`, or `enabled`. | | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | -| `group_runners_enabled` | boolean | **{dotted-circle}** No | Enable group runners for this project. | +| `show_default_award_emojis` | boolean | **{dotted-circle}** No | Show default award emojis. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | | `issue_branch_template` | string | **{dotted-circle}** No | Template used to suggest names for [branches created from issues](../user/project/merge_requests/creating_merge_requests.md#from-an-issue). _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21243) in GitLab 15.6.)_ | @@ -1664,7 +1673,7 @@ For example, to toggle the setting for ```shell curl --request PUT --header "PRIVATE-TOKEN: <your-token>" \ - --url 'https://gitlab.com/api/v4/projects/<your-project-ID>' \ + --url "https://gitlab.com/api/v4/projects/<your-project-ID>" \ --data "shared_runners_enabled=true" # to turn off: "shared_runners_enabled=false" ``` @@ -1689,6 +1698,7 @@ Supported attributes: | `ci_config_path` | string | **{dotted-circle}** No | The path to CI configuration file. | | `ci_default_git_depth` | integer | **{dotted-circle}** No | Default number of revisions for [shallow cloning](../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone). | | `ci_forward_deployment_enabled` | boolean | **{dotted-circle}** No | Enable or disable [prevent outdated deployment jobs](../ci/pipelines/settings.md#prevent-outdated-deployment-jobs). | +| `ci_forward_deployment_rollback_allowed` | boolean | **{dotted-circle}** No | Enable or disable [allow job retries for rollback deployments](../ci/pipelines/settings.md#prevent-outdated-deployment-jobs). | | `ci_allow_fork_pipelines_to_run_in_parent_project` | boolean | **{dotted-circle}** No | Enable or disable [running pipelines in the parent project for merge requests from forks](../ci/pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project). _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325189) in GitLab 15.3.)_ | | `ci_separated_caches` | boolean | **{dotted-circle}** No | Set whether or not caches should be [separated](../ci/caching/index.md#cache-key-names) by branch protection status. | | `container_expiration_policy_attributes` | hash | **{dotted-circle}** No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (integer), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). | @@ -1696,10 +1706,12 @@ Supported attributes: | `container_registry_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable container registry for this project. Use `container_registry_access_level` instead. | | `default_branch` | string | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. | | `description` | string | **{dotted-circle}** No | Short project description. | -| `emails_disabled` | boolean | **{dotted-circle}** No | Disable email notifications. | +| `emails_disabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Disable email notifications. Use `emails_enabled` instead| +| `emails_enabled` | boolean | **{dotted-circle}** No | Enable email notifications. | | `enforce_auth_checks_on_uploads` | boolean | **{dotted-circle}** No | Enforce [auth checks](../security/user_file_uploads.md#enable-authorization-checks-for-all-media-files) on uploads. | | `external_authorization_classification_label` **(PREMIUM)** | string | **{dotted-circle}** No | The classification label for the project. | | `forking_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `group_runners_enabled` | boolean | **{dotted-circle}** No | Enable group runners for this project. | | `import_url` | string | **{dotted-circle}** No | URL the repository was imported from. | | `issues_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `issues_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable issues for this project. Use `issues_access_level` instead. | @@ -1743,7 +1755,7 @@ Supported attributes: | `security_and_compliance_access_level` | string | **{dotted-circle}** No | (GitLab 14.9 and later) Security and compliance access level. One of `disabled`, `private`, or `enabled`. | | `service_desk_enabled` | boolean | **{dotted-circle}** No | Enable or disable Service Desk feature. | | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | -| `group_runners_enabled` | boolean | **{dotted-circle}** No | Enable group runners for this project. | +| `show_default_award_emojis` | boolean | **{dotted-circle}** No | Show default award emojis. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | | `issue_branch_template` | string | **{dotted-circle}** No | Template used to suggest names for [branches created from issues](../user/project/merge_requests/creating_merge_requests.md#from-an-issue). _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21243) in GitLab 15.6.)_ | @@ -2290,6 +2302,7 @@ Example response: "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", "ci_default_git_depth": 50, "ci_forward_deployment_enabled": true, + "ci_forward_deployment_rollback_allowed": true, "ci_allow_fork_pipelines_to_run_in_parent_project": true, "ci_separated_caches": true, "public_jobs": true, @@ -2421,6 +2434,7 @@ Example response: "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", "ci_default_git_depth": 50, "ci_forward_deployment_enabled": true, + "ci_forward_deployment_rollback_allowed": true, "ci_allow_fork_pipelines_to_run_in_parent_project": true, "ci_separated_caches": true, "public_jobs": true, @@ -2484,7 +2498,7 @@ DELETE /projects/:id | `permanently_remove` **(PREMIUM)** | boolean/string | no | Immediately deletes a project if it is marked for deletion. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396500) in GitLab 15.11 | | `full_path` **(PREMIUM)** | string | no | Full path of project to use with `permanently_remove`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396500) in GitLab 15.11. To find the project path, use `path_with_namespace` from [get single project](projects.md#get-single-project) | -## Restore project marked for deletion **(PREMIUM)** +## Restore project marked for deletion **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. @@ -2647,6 +2661,33 @@ Returns: - `404 Project Not Found` if the target or source project does not exist or cannot be accessed by the requester. - `422 Unprocessable Entity` if the import of project members does not complete successfully. +Example responses: + +When all emails were successfully sent (`200` HTTP status code): + +```json +{ "status": "success" } +``` + +When there was any error importing 1 or more members (`200` HTTP status code): + +```json +{ + "status": "error", + "message": { + "john_smith": "Some individual error message", + "jane_smith": "Some individual error message" + }, + "total_members_count": 3 +} +``` + +When there is a system error (`404` and `422` HTTP status codes): + +```json +{ "message": "Import failed" } +``` + ## Hooks Also called Project Hooks and Webhooks. These are different for [System Hooks](system_hooks.md) @@ -2836,7 +2877,7 @@ POST /projects/:id/housekeeping | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `task` | string | **{dotted-circle}** No | `prune` to trigger manual prune of unreachable objects or `eager` to trigger eager housekeeping. | -## Push rules **(PREMIUM)** +## Push rules **(PREMIUM ALL)** ### Get project push rules @@ -3076,6 +3117,7 @@ Example response: "pages_access_level": "enabled", "security_and_compliance_access_level": "enabled", "emails_disabled": null, + "emails_enabled": null, "shared_runners_enabled": true, "group_runners_enabled": true, "lfs_enabled": true, @@ -3124,7 +3166,7 @@ Read more in the [Project members](members.md) documentation. Read more in the [Project vulnerabilities](project_vulnerabilities.md) documentation. -## Get a project's pull mirror details **(PREMIUM)** +## Get a project's pull mirror details **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354506) in GitLab 15.6. @@ -3160,7 +3202,7 @@ Example response: } ``` -## Configure pull mirroring for a project **(PREMIUM)** +## Configure pull mirroring for a project **(PREMIUM ALL)** > - Field `mirror_branch_regex` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 15.8 [with a flag](../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 16.0. @@ -3184,7 +3226,7 @@ with the API scope enabled. | `only_mirror_protected_branches`| boolean | **{dotted-circle}** No | Limits mirroring to only protected branches when set to `true`. | | `mirror_branch_regex` | String | **{dotted-circle}** No | Contains a regular expression. Only branches with names matching the regex are mirrored. Requires `only_mirror_protected_branches` to be disabled. | -## Start the pull mirroring process for a Project **(PREMIUM)** +## Start the pull mirroring process for a Project **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 0de32a4a25d..6bccc777e04 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Protected branches API **(FREE)** +# Protected branches API **(FREE ALL)** ## Valid access levels @@ -310,7 +310,7 @@ Example response: } ``` -### Example with user / group level access **(PREMIUM)** +### Example with user / group level access **(PREMIUM ALL)** Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect` array should take the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md). @@ -357,7 +357,7 @@ Example response: } ``` -### Example with allow to push and allow to merge access **(PREMIUM)** +### Example with allow to push and allow to merge access **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index 023046a4821..5a25844c754 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Protected environments API **(PREMIUM)** +# Protected environments API **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30595) in GitLab 12.8. diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md index 7aff87b54f0..b996a6a8098 100644 --- a/doc/api/protected_tags.md +++ b/doc/api/protected_tags.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Protected tags API **(FREE)** +# Protected tags API **(FREE ALL)** **Valid access levels** diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index 3ec4b77a646..7a352ccc073 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Releases API **(FREE)** +# Releases API **(FREE ALL)** > - Release Evidences were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.5. > - `description_html` became an opt-in field [with GitLab 13.12 for performance reasons](https://gitlab.com/gitlab-org/gitlab/-/issues/299447). diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md index a1abded5ed4..49c96fb9c1d 100644 --- a/doc/api/releases/links.md +++ b/doc/api/releases/links.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Release links API **(FREE)** +# Release links API **(FREE ALL)** > Support for [GitLab CI/CD job token](../../ci/jobs/ci_job_token.md) authentication [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250819) in GitLab 15.1. diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md index a755553b645..6b7bd3a485f 100644 --- a/doc/api/remote_mirrors.md +++ b/doc/api/remote_mirrors.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Project remote mirrors API **(FREE)** +# Project remote mirrors API **(FREE ALL)** [Push mirrors](../user/project/repository/mirror/push.md) defined on a project's repository settings are called "remote mirrors". You diff --git a/doc/api/repositories.md b/doc/api/repositories.md index d3bee8de2c5..49415f42789 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Repositories API **(FREE)** +# Repositories API **(FREE ALL)** ## List repository tree diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index 65ed67541d3..969470dcc54 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Repository files API **(FREE)** +# Repository files API **(FREE ALL)** You can fetch, create, update, and delete files in your repository with this API. You can also [configure rate limits](../administration/settings/files_api_rate_limits.md) @@ -214,8 +214,8 @@ GET /projects/:id/repository/files/:file_path/raw |-------------|----------------|----------|------------| | `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `file_path` | string | yes | URL-encoded full path to new file, such as `lib%2Fclass%2Erb`. | -| `ref` | string | yes | The name of branch, tag or commit. Default is the `HEAD` of the project. | -| `lfs` | boolean | no | Determines if the response should be Git LFS file contents, rather than the pointer. If the file is not tracked by Git LFS, ignored. Defaults to `false`. | +| `ref` | string | no | The name of branch, tag or commit. Default is the `HEAD` of the project. | +| `lfs` | boolean | no | Determines if the response should be Git LFS file contents, rather than the pointer. If the file is not tracked by Git LFS, ignored. Defaults to `false`. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb/raw?ref=master" diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md index b4988b39eaf..650dc7783b8 100644 --- a/doc/api/repository_submodules.md +++ b/doc/api/repository_submodules.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Repository submodules API **(FREE)** +# Repository submodules API **(FREE ALL)** ## Update existing submodule reference in repository diff --git a/doc/api/resource_groups.md b/doc/api/resource_groups.md index 23c982c9296..df4c01404c7 100644 --- a/doc/api/resource_groups.md +++ b/doc/api/resource_groups.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Resource group API **(FREE)** +# Resource group API **(FREE ALL)** You can read more about [controlling the job concurrency with resource groups](../ci/resource_groups/index.md). diff --git a/doc/api/resource_iteration_events.md b/doc/api/resource_iteration_events.md index e8537750f0d..e31081be4dc 100644 --- a/doc/api/resource_iteration_events.md +++ b/doc/api/resource_iteration_events.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/product/ux/technical-writing/#assignments --- -# Resource iteration events API **(PREMIUM)** +# Resource iteration events API **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229463) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229463) in GitLab 13.5. diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md index 9f0c9db6d71..316abb67920 100644 --- a/doc/api/resource_label_events.md +++ b/doc/api/resource_label_events.md @@ -4,7 +4,7 @@ group: Compliance 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 --- -# Resource label events API **(FREE)** +# Resource label events API **(FREE ALL)** Resource label events keep track about who, when, and which label was added to (or removed from) an issue, merge request, or epic. @@ -95,7 +95,7 @@ Parameters: curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/resource_label_events/1" ``` -## Epics **(PREMIUM)** +## Epics **(PREMIUM ALL)** ### List group epic label events diff --git a/doc/api/resource_milestone_events.md b/doc/api/resource_milestone_events.md index 897f5bf7ca2..9ffb15a8e63 100644 --- a/doc/api/resource_milestone_events.md +++ b/doc/api/resource_milestone_events.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/product/ux/technical-writing/#assignments --- -# Resource milestone events API **(FREE)** +# Resource milestone events API **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31720) in GitLab 13.1. diff --git a/doc/api/resource_state_events.md b/doc/api/resource_state_events.md index d17b6c39686..366c70e5206 100644 --- a/doc/api/resource_state_events.md +++ b/doc/api/resource_state_events.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/product/ux/technical-writing/#assignments --- -# Resource state events API **(FREE)** +# Resource state events API **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35210/) in GitLab 13.2. diff --git a/doc/api/resource_weight_events.md b/doc/api/resource_weight_events.md index 1c18e85479c..ff3c470cbdf 100644 --- a/doc/api/resource_weight_events.md +++ b/doc/api/resource_weight_events.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/product/ux/technical-writing/#assignments --- -# Resource weight events API **(FREE)** +# Resource weight events API **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/32542) in GitLab 13.2. diff --git a/doc/api/rest/index.md b/doc/api/rest/index.md index 947142e3a50..ba705a771c1 100644 --- a/doc/api/rest/index.md +++ b/doc/api/rest/index.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# REST API **(FREE)** +# REST API **(FREE ALL)** The REST APIs have been around for a longer time compared to GraphQL APIs, which may make them more familiar to some developers. It is often a good choice for @@ -200,7 +200,9 @@ header. By default, impersonation is enabled. To disable impersonation: -**For Omnibus installations** +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit the `/etc/gitlab/gitlab.rb` file: @@ -211,10 +213,7 @@ By default, impersonation is enabled. To disable impersonation: 1. Save the file, and then [reconfigure](../../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) GitLab for the changes to take effect. -To re-enable impersonation, remove this configuration, and then reconfigure -GitLab. - -**For installations from source** +:::TabTitle Self-compiled (source) 1. Edit the `config/gitlab.yml` file: @@ -223,10 +222,13 @@ GitLab. impersonation_enabled: false ``` -1. Save the file, and then [restart](../../administration/restart_gitlab.md#installations-from-source) +1. Save the file, and then [restart](../../administration/restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. -To re-enable impersonation, remove this configuration, and then restart GitLab. +::EndTabs + +To re-enable impersonation, remove this configuration and reconfigure GitLab (Linux package installations) or restart +GitLab (self-compiled installations). ### Sudo @@ -314,6 +316,7 @@ The following table shows the possible return codes for API requests. | `201 Created` | The `POST` request was successful, and the resource is returned as JSON. | | `202 Accepted` | The `GET`, `PUT` or `DELETE` request was successful, and the resource is scheduled for processing. | | `204 No Content` | The server has successfully fulfilled the request, and there is no additional content to send in the response payload body. | +| `301 Moved Permanently` | The resource has been definitively moved to the URL given by the `Location` headers. | | `304 Not Modified` | The resource hasn't been modified since the last request. | | `400 Bad Request` | A required attribute of the API request is missing. For example, the title of an issue is not given. | | `401 Unauthorized` | The user isn't authenticated. A valid [user token](#authentication) is necessary. | @@ -327,6 +330,33 @@ The following table shows the possible return codes for API requests. | `500 Server Error` | While handling the request, something went wrong on the server. | | `503 Service Unavailable` | The server cannot handle the request because the server is temporarily overloaded. | +## Redirects + +> Introduced in GitLab 16.4 [with a flag](../../user/feature_flags.md) named `api_redirect_moved_projects`. Disabled by default. + +FLAG: +On GitLab.com, this feature is not available. +On self-managed GitLab, by default this feature is not available. To make it available, +an administrator can [enable the feature flag](../../user/feature_flags.md) named `api_redirect_moved_projects`. + +REST API can respond with a redirect and users should be able to handle such responses. +The users should follow the redirect and repeat the request to the URI specified in the `Location` header. + +Example of a project moved to a different path: + +```shell +curl --verbose "https://gitlab.example.com/api/v4/projects/gitlab-org%2Fold-path-project" +``` + +The response is: + +```plaintext +... +< Location: http://gitlab.example.com/api/v4/projects/81 +... +This resource has been moved permanently to https://gitlab.example.com/api/v4/projects/81 +``` + ## Pagination GitLab supports the following pagination methods: @@ -745,10 +775,56 @@ The correct encoding for the query parameter would be: 2017-10-17T23:11:13.000%2B05:30 ``` -## Clients +## Third-party clients + +You can integrate third-party API client libraries with GitLab. The following libraries are maintained by community members and not officially supported by GitLab. +Report bugs and feature proposals to the respective projects. + +For questions about these integrations, use the [GitLab community forum](https://forum.gitlab.com/). + +### `C#` + +- [`GitLabApiClient`](https://github.com/nmklotas/GitLabApiClient) + +### Go + +- [`go-gitlab`](https://github.com/xanzy/go-gitlab) + +### Haskell + +- [`gitlab-haskell`](http://hackage.haskell.org/package/gitlab-haskell) + +### Java + +- [`gitlab4j-api`](https://github.com/gmessner/gitlab4j-api) +- [`java-gitlab-api`](https://github.com/timols/java-gitlab-api) + +### Node.js + +- [`gitlab-yaac`](https://www.npmjs.com/package/gitlab-yaac) +- [`backbone-gitlab`](https://github.com/oreillymedia/backbone-gitlab) + +### Perl + +- [`GitLab::API::v4`](https://metacpan.org/pod/GitLab::API::v4) + +### PHP + +- [`php-gitlab-api`](https://github.com/GitLabPHP/Client) + +### Python + +- [`python-gitlab`](https://github.com/python-gitlab/python-gitlab) + - Blog post: [Efficient DevSecOps workflows: Hands-on `python-gitlab` API automation](https://about.gitlab.com/blog/2023/02/01/efficient-devsecops-workflows-hands-on-python-gitlab-api-automation/) +- [`libsaas_gitlab`](https://gitlab.com/bor-sh-infrastructure/libsaas_gitlab) + +### Ruby + +- [Ruby wrapper and CLI for the GitLab REST API](https://github.com/NARKOZ/gitlab) + +### Swift -Many unofficial GitLab API Clients are available for most of the popular programming -languages. For a complete list, see the [GitLab website](https://about.gitlab.com/partners/technology-partners/#api-clients). +- [`RxGitLabKit`](https://github.com/Qase/RxGitLabKit) ## Rate limits diff --git a/doc/api/runners.md b/doc/api/runners.md index 525cfaaff3e..7c2bceb70eb 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -4,7 +4,7 @@ group: Runner 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 --- -# Runners API **(FREE)** +# Runners API **(FREE ALL)** [Pagination](rest/index.md#pagination) is available on the following API endpoints (they return 20 items by default): diff --git a/doc/api/saml.md b/doc/api/saml.md index 168c6ed2b6a..a44e1537f1e 100644 --- a/doc/api/saml.md +++ b/doc/api/saml.md @@ -4,7 +4,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 --- -# SAML API **(PREMIUM)** +# SAML API **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5. diff --git a/doc/api/scim.md b/doc/api/scim.md index 95e4435f0d7..94662250313 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -4,7 +4,7 @@ stage: Manage group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# SCIM API **(PREMIUM)** +# SCIM API **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98354) in GitLab 15.5. diff --git a/doc/api/search.md b/doc/api/search.md index b412d86a613..06e62d28534 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -4,13 +4,13 @@ group: Global Search info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Search API **(FREE)** +# Search API **(FREE ALL)** > [Feature flag `search_filter_by_confidential` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/244923) in GitLab 13.6. Every API call to search must be authenticated. -## Additional scopes **(PREMIUM)** +## Additional scopes **(PREMIUM ALL)** Additional scopes are available for the [Advanced Search API](#advanced-search-api) and [Group Search API](#group-search-api) if @@ -269,7 +269,7 @@ Example response: ] ``` -### Scope: `wiki_blobs` **(PREMIUM)** +### Scope: `wiki_blobs` **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -301,7 +301,7 @@ Example response: NOTE: `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). -### Scope: commits **(PREMIUM)** +### Scope: commits **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -336,7 +336,7 @@ Example response: ] ``` -### Scope: blobs **(PREMIUM)** +### Scope: blobs **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -377,7 +377,7 @@ Example response: NOTE: `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). -### Scope: notes **(PREMIUM)** +### Scope: notes **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -660,7 +660,7 @@ Example response: ] ``` -### Scope: `wiki_blobs` **(PREMIUM)** +### Scope: `wiki_blobs` **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -692,7 +692,7 @@ Example response: NOTE: `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). -### Scope: `commits` **(PREMIUM)** +### Scope: `commits` **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -727,7 +727,7 @@ Example response: ] ``` -### Scope: `blobs` **(PREMIUM)** +### Scope: `blobs` **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -768,7 +768,7 @@ Example response: NOTE: `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). -### Scope: `notes` **(PREMIUM)** +### Scope: `notes` **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -1019,7 +1019,7 @@ Example response: ] ``` -### Scope: `notes` **(PREMIUM)** +### Scope: `notes` **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -1056,7 +1056,7 @@ Example response: ] ``` -### Scope: `wiki_blobs` **(PREMIUM)** +### Scope: `wiki_blobs` **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -1105,7 +1105,7 @@ Example response: NOTE: `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` are intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). -### Scope: `commits` **(PREMIUM)** +### Scope: `commits` **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -1140,7 +1140,7 @@ Example response: ] ``` -### Scope: `blobs` **(PREMIUM)** +### Scope: `blobs` **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. diff --git a/doc/api/secure_files.md b/doc/api/secure_files.md index c912746f07e..b3d59127fe6 100644 --- a/doc/api/secure_files.md +++ b/doc/api/secure_files.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, api --- -# Project-level Secure Files API **(FREE)** +# Project-level Secure Files API **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78227) in GitLab 14.8 [with a flag](../administration/feature_flags.md) named `ci_secure_files`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350748) in GitLab 15.7. Feature flag `ci_secure_files` removed. diff --git a/doc/api/settings.md b/doc/api/settings.md index ea023a25a1d..cc233ec69d9 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -43,6 +43,8 @@ Example response: "max_attachment_size" : 10, "max_export_size": 50, "max_import_size": 50, + "max_import_remote_file_size": 10240, + "max_decompressed_archive_size": 25600, "user_oauth_applications" : true, "updated_at" : "2016-01-04T15:44:55.176Z", "session_expire_delay" : 10080, @@ -83,6 +85,8 @@ Example response: "terms": "Hello world!", "performance_bar_allowed_group_id": 42, "user_show_add_ssh_key_message": true, + "allow_account_deletion": true, + "updating_name_disabled_for_users": false, "local_markdown_version": 0, "allow_local_requests_from_hooks_and_services": true, "allow_local_requests_from_web_hooks_and_services": true, @@ -109,7 +113,9 @@ Example response: "external_pipeline_validation_service_url": null, "jira_connect_application_key": null, "jira_connect_proxy_url": null, - "silent_mode_enabled": false + "silent_mode_enabled": false, + "package_registry_allow_anyone_to_pull_option": true, + "bulk_import_max_download_file_size": 5120 } ``` @@ -179,6 +185,8 @@ Example response: "max_attachment_size": 10, "max_export_size": 50, "max_import_size": 50, + "max_import_remote_file_size": 10240, + "max_decompressed_archive_size": 25600, "session_expire_delay": 10080, "default_ci_config_path" : null, "default_project_visibility": "internal", @@ -224,6 +232,7 @@ Example response: "asset_proxy_enabled": true, "asset_proxy_url": "https://assets.example.com", "asset_proxy_allowlist": ["example.com", "*.example.com", "your-instance.com"], + "globally_allowed_ips": "", "geo_node_allowed_ips": "0.0.0.0/0, ::/0", "allow_local_requests_from_hooks_and_services": true, "allow_local_requests_from_web_hooks_and_services": true, @@ -249,7 +258,9 @@ Example response: "user_defaults_to_private_profile": true, "projects_api_rate_limit_unauthenticated": 400, "silent_mode_enabled": false, - "security_policy_global_group_approvers_enabled": true + "security_policy_global_group_approvers_enabled": true, + "package_registry_allow_anyone_to_pull_option": true, + "bulk_import_max_download_file_size": 5120 } ``` @@ -283,6 +294,7 @@ Example responses: **(PREMIUM SELF)** > - Fields `housekeeping_full_repack_period`, `housekeeping_gc_period`, and `housekeeping_incremental_repack_period` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106963) in GitLab 15.8. Use `housekeeping_optimize_repository_period` instead. > - Parameters `sign_in_text` and `help_text` were [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124461) in GitLab 16.2. Use `description` parameter in the [Appearance API](../api/appearance.md) instead. +> - Parameter `allow_account_deletion` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412411) in GitLab 16.1. In general, all settings are optional. Certain settings though, if enabled, require other settings to be set to function properly. These requirements are @@ -291,12 +303,16 @@ listed in the descriptions of the relevant settings. | Attribute | Type | Required | Description | |------------------------------------------|------------------|:------------------------------------:|-------------| | `admin_mode` | boolean | no | Require administrators to enable Admin Mode by re-authenticating for administrative tasks. | -| `admin_notification_email` | string | no | Deprecated: Use `abuse_notification_email` instead. If set, [abuse reports](../administration/review_abuse_reports.md) are sent to this address. Abuse reports are always available in the Admin Area. | -| `abuse_notification_email` | string | no | If set, [abuse reports](../administration/review_abuse_reports.md) are sent to this address. Abuse reports are always available in the Admin Area. | +| `admin_notification_email` | string | no | Deprecated: Use `abuse_notification_email` instead. If set, [abuse reports](../administration/review_abuse_reports.md) are sent to this address. Abuse reports are always available in the Admin Area. | +| `abuse_notification_email` | string | no | If set, [abuse reports](../administration/review_abuse_reports.md) are sent to this address. Abuse reports are always available in the Admin Area. | +| `notify_on_unknown_sign_in` | boolean | no | Enable sending notification if sign in from unknown IP address happens. | | `after_sign_out_path` | string | no | Where to redirect users after logout. | +| `email_restrictions_enabled` | boolean | no | Enable restriction for sign-up by email. | +| `email_restrictions` | string | required by: `email_restrictions_enabled` | Regular expression that is checked against the email used during registration. | | `after_sign_up_text` | string | no | Text shown to the user after signing up. | | `akismet_api_key` | string | required by: `akismet_enabled` | API key for Akismet spam protection. | | `akismet_enabled` | boolean | no | (**If enabled, requires:** `akismet_api_key`) Enable or disable Akismet spam protection. | +| `allow_account_deletion` **(PREMIUM)** | boolean | no | Set to `true` to allow users to delete their accounts. | | `allow_group_owners_to_manage_ldap` **(PREMIUM)** | boolean | no | Set to `true` to allow group owners to manage LDAP. | | `allow_local_requests_from_hooks_and_services` | boolean | no | (Deprecated: Use `allow_local_requests_from_web_hooks_and_services` instead) Allow requests to the local network from webhooks and integrations. | | `allow_local_requests_from_system_hooks` | boolean | no | Allow requests to the local network from system hooks. | @@ -313,23 +329,27 @@ listed in the descriptions of the relevant settings. | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for projects by default. It automatically builds, tests, and deploys applications based on a predefined CI/CD configuration. | | `automatic_purchased_storage_allocation` | boolean | no | Enabling this permits automatic allocation of purchased storage in a namespace. Relevant only to EE distributions. | | `bulk_import_enabled` | boolean | no | Enable migrating GitLab groups by direct transfer. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. Setting also [available](../administration/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer) in the Admin Area. | -| `can_create_group` | boolean | no | Indicates whether users can create top-level groups. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367754) in GitLab 15.5. Defaults to `true`. | +| `bulk_import_max_download_file_size` | integer | no | Maximum download file size when importing from source GitLab instances by direct transfer. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384976) in GitLab 16.3. | +| `can_create_group` | boolean | no | Indicates whether users can create top-level groups. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367754) in GitLab 15.5. Defaults to `true`. | | `check_namespace_plan` **(PREMIUM)** | boolean | no | Enabling this makes only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | -| `ci_max_includes` | integer | no | The maximum number of [includes](../ci/yaml/includes.md) per pipeline. Default is `150`. | +| `ci_max_total_yaml_size_bytes` | integer | no | The maximum amount of memory, in bytes, that can be allocated for the pipeline configuration, with all included YAML configuration files. | +| `ci_max_includes` | integer | no | The [maximum number of includes](../administration/settings/continuous_integration.md#maximum-includes) per pipeline. Default is `150`. | | `commit_email_hostname` | string | no | Custom hostname (for private commit emails). | -| `container_expiration_policies_enable_historic_entries` | boolean | no | Enable [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#enable-the-cleanup-policy) for all projects. | -| `container_registry_cleanup_tags_service_max_list_size` | integer | no | The maximum number of tags that can be deleted in a single execution of [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). | -| `container_registry_delete_tags_service_timeout` | integer | no | The maximum time, in seconds, that the cleanup process can take to delete a batch of tags for [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). | -| `container_registry_expiration_policies_caching` | boolean | no | Caching during the execution of [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). | -| `container_registry_expiration_policies_worker_capacity` | integer | no | Number of workers for [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). | -| `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes. | -| `package_registry_cleanup_policies_worker_capacity` | integer | no | Number of workers assigned to the packages cleanup policies. | +| `container_expiration_policies_enable_historic_entries` | boolean | no | Enable [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#enable-the-cleanup-policy) for all projects. | +| `container_registry_cleanup_tags_service_max_list_size` | integer | no | The maximum number of tags that can be deleted in a single execution of [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). | +| `container_registry_delete_tags_service_timeout` | integer | no | The maximum time, in seconds, that the cleanup process can take to delete a batch of tags for [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). | +| `container_registry_expiration_policies_caching` | boolean | no | Caching during the execution of [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). | +| `container_registry_expiration_policies_worker_capacity` | integer | no | Number of workers for [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). | +| `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes. | +| `package_registry_cleanup_policies_worker_capacity` | integer | no | Number of workers assigned to the packages cleanup policies. | +| `updating_name_disabled_for_users` | boolean | no | [Disable user profile name changes](../administration/settings/account_and_limit_settings.md#disable-user-profile-name-changes). | +| `allow_account_deletion` | boolean | no | Enable [users to delete their accounts](../administration/settings/account_and_limit_settings.md#prevent-users-from-deleting-their-accounts). | | `deactivate_dormant_users` | boolean | no | Enable [automatic deactivation of dormant users](../administration/moderate_users.md#automatically-deactivate-dormant-users). | | `deactivate_dormant_users_period` | integer | no | Length of time (in days) after which a user is considered dormant. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336747) in GitLab 15.3. | | `default_artifacts_expire_in` | string | no | Set the default expiration time for each job's artifacts. | | `default_branch_name` | string | no | [Instance-level custom initial branch name](../user/project/repository/branches/default.md#instance-level-custom-initial-branch-name). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225258) in GitLab 13.2. | | `default_branch_protection` | integer | no | Determine if developers can push to the default branch. Can take: `0` _(not protected, both users with the Developer role or Maintainer role can push new commits and force push)_, `1` _(partially protected, users with the Developer role or Maintainer role can push new commits, but cannot force push)_ or `2` _(fully protected, users with the Developer or Maintainer role cannot push new commits, but users with the Developer or Maintainer role can; no one can force push)_ as a parameter. Default is `2`. | -| `default_ci_config_path` | string | no | Default CI/CD configuration file and path for new projects (`.gitlab-ci.yml` if not set). | +| `default_ci_config_path` | string | no | Default CI/CD configuration file and path for new projects (`.gitlab-ci.yml` if not set). | | `default_group_visibility` | string | no | What visibility level new groups receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `default_preferred_language` | string | no | Default preferred language for users who are not logged in. | | `default_project_creation` | integer | no | Default project creation protection. Can take: `0` _(No one)_, `1` _(Maintainers)_ or `2` _(Developers + Maintainers)_| @@ -337,13 +357,13 @@ listed in the descriptions of the relevant settings. | `default_projects_limit` | integer | no | Project limit per user. Default is `100000`. | | `default_snippet_visibility` | string | no | What visibility level new snippets receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `default_syntax_highlighting_theme` | integer | no | Default syntax highlighting theme for new users and users who are not signed in. See [IDs of available themes](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/themes.rb#L16). -| `delayed_project_deletion` **(PREMIUM SELF)** | boolean | no | Enable delayed project deletion by default in new groups. Default is `false`. [From GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/352960), can only be enabled when `delayed_group_deletion` is true. From [GitLab 15.11](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113332), with the `always_perform_delayed_deletion` feature flag enabled, this attribute has been removed. This attribute will be completely removed in GitLab 16.0. | -| `delayed_group_deletion` **(PREMIUM SELF)** | boolean | no | Enable delayed group deletion. Default is `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352959) in GitLab 15.0. [From GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/352960), disables and locks the group-level setting for delayed protect deletion when set to `false`. From [GitLab 15.11](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113332), with the `always_perform_delayed_deletion` feature flag enabled, this attribute has been removed. This attribute will be completely removed in GitLab 16.0. | +| `delayed_project_deletion` **(PREMIUM SELF)** | boolean | no | Enable delayed project deletion by default in new groups. Default is `false`. [From GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/352960), can only be enabled when `delayed_group_deletion` is true. From [GitLab 15.11](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113332), with the `always_perform_delayed_deletion` feature flag enabled, this attribute has been removed. This attribute will be completely removed in GitLab 16.0. | +| `delayed_group_deletion` **(PREMIUM SELF)** | boolean | no | Enable delayed group deletion. Default is `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352959) in GitLab 15.0. [From GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/352960), disables and locks the group-level setting for delayed protect deletion when set to `false`. From [GitLab 15.11](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113332), with the `always_perform_delayed_deletion` feature flag enabled, this attribute has been removed. This attribute will be completely removed in GitLab 16.0. | | `default_project_deletion_protection` **(PREMIUM SELF)** | boolean | no | Enable default project deletion protection so only administrators can delete projects. Default is `false`. | | `delete_unconfirmed_users` **(PREMIUM SELF)** | boolean | no | Specifies whether users who have not confirmed their email should be deleted. Default is `false`. When set to `true`, unconfirmed users are deleted after `unconfirmed_users_delete_after_days` days. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352514) in GitLab 16.1. | | `deletion_adjourned_period` **(PREMIUM SELF)** | integer | no | The number of days to wait before deleting a project or group that is marked for deletion. Value must be between `1` and `90`. Defaults to `7`. [From GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/352960), a hook on `deletion_adjourned_period` sets the period to `1` on every update, and sets both `delayed_project_deletion` and `delayed_group_deletion` to `false` if the period is `0`. | -| `diagramsnet_enabled` | boolean | no | (If enabled, requires `diagramsnet_url`) Enable [Diagrams.net integration](../administration/integration/diagrams_net.md). Default is `true`. | -| `diagramsnet_url` | string | required by: `diagramsnet_enabled` | The Diagrams.net instance URL for integration. | +| `diagramsnet_enabled` | boolean | no | (If enabled, requires `diagramsnet_url`) Enable [Diagrams.net integration](../administration/integration/diagrams_net.md). Default is `true`. | +| `diagramsnet_url` | string | required by: `diagramsnet_enabled` | The Diagrams.net instance URL for integration. | | `diff_max_patch_bytes` | integer | no | Maximum [diff patch size](../administration/diff_limits.md), in bytes. | | `diff_max_files` | integer | no | Maximum [files in a diff](../administration/diff_limits.md). | | `diff_max_lines` | integer | no | Maximum [lines in a diff](../administration/diff_limits.md). | @@ -364,27 +384,28 @@ listed in the descriptions of the relevant settings. | `eks_account_id` | string | no | Amazon account ID. | | `eks_integration_enabled` | boolean | no | Enable integration with Amazon EKS. | | `eks_secret_access_key` | string | no | AWS IAM secret access key. | -| `elasticsearch_aws_access_key` **(PREMIUM)** | string | no | AWS IAM access key. | -| `elasticsearch_aws_region` **(PREMIUM)** | string | no | The AWS region the Elasticsearch domain is configured. | -| `elasticsearch_aws_secret_access_key` **(PREMIUM)** | string | no | AWS IAM secret access key. | -| `elasticsearch_aws` **(PREMIUM)** | boolean | no | Enable the use of AWS hosted Elasticsearch. | -| `elasticsearch_indexed_field_length_limit` **(PREMIUM)** | integer | no | Maximum size of text fields to index by Elasticsearch. 0 value means no limit. This does not apply to repository and wiki indexing. | -| `elasticsearch_indexed_file_size_limit_kb` **(PREMIUM)** | integer | no | Maximum size of repository and wiki files that are indexed by Elasticsearch. | -| `elasticsearch_indexing` **(PREMIUM)** | boolean | no | Enable Elasticsearch indexing. | -| `elasticsearch_requeue_workers` **(PREMIUM)** | boolean | no | Enable automatic requeuing of indexing workers. This improves non-code indexing throughput by enqueuing Sidekiq jobs until all documents are processed. | -| `elasticsearch_limit_indexing` **(PREMIUM)** | boolean | no | Limit Elasticsearch to index certain namespaces and projects. | -| `elasticsearch_max_bulk_concurrency` **(PREMIUM)** | integer | no | Maximum concurrency of Elasticsearch bulk requests per indexing operation. This only applies to repository indexing operations. | -| `elasticsearch_worker_number_of_shards` **(PREMIUM)** | integer | no | Number of indexing worker shards. This improves non-code indexing throughput by enqueuing more parallel Sidekiq jobs. Default is `2`. | -| `elasticsearch_max_bulk_size_mb` **(PREMIUM)** | integer | no | Maximum size of Elasticsearch bulk indexing requests in MB. This only applies to repository indexing operations. | -| `elasticsearch_namespace_ids` **(PREMIUM)** | array of integers | no | The namespaces to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | -| `elasticsearch_project_ids` **(PREMIUM)** | array of integers | no | The projects to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | -| `elasticsearch_search` **(PREMIUM)** | boolean | no | Enable Elasticsearch search. | -| `elasticsearch_url` **(PREMIUM)** | string | no | The URL to use for connecting to Elasticsearch. Use a comma-separated list to support cluster (for example, `http://localhost:9200, http://localhost:9201"`). | -| `elasticsearch_username` **(PREMIUM)** | string | no | The `username` of your Elasticsearch instance. | -| `elasticsearch_password` **(PREMIUM)** | string | no | The password of your Elasticsearch instance. | +| `elasticsearch_aws_access_key` **(PREMIUM)** | string | no | AWS IAM access key. | +| `elasticsearch_aws_region` **(PREMIUM)** | string | no | The AWS region the Elasticsearch domain is configured. | +| `elasticsearch_aws_secret_access_key` **(PREMIUM)** | string | no | AWS IAM secret access key. | +| `elasticsearch_aws` **(PREMIUM)** | boolean | no | Enable the use of AWS hosted Elasticsearch. | +| `elasticsearch_indexed_field_length_limit` **(PREMIUM)** | integer | no | Maximum size of text fields to index by Elasticsearch. 0 value means no limit. This does not apply to repository and wiki indexing. | +| `elasticsearch_indexed_file_size_limit_kb` **(PREMIUM)** | integer | no | Maximum size of repository and wiki files that are indexed by Elasticsearch. | +| `elasticsearch_indexing` **(PREMIUM)** | boolean | no | Enable Elasticsearch indexing. | +| `elasticsearch_requeue_workers` **(PREMIUM)** | boolean | no | Enable automatic requeuing of indexing workers. This improves non-code indexing throughput by enqueuing Sidekiq jobs until all documents are processed. | +| `elasticsearch_limit_indexing` **(PREMIUM)** | boolean | no | Limit Elasticsearch to index certain namespaces and projects. | +| `elasticsearch_max_bulk_concurrency` **(PREMIUM)** | integer | no | Maximum concurrency of Elasticsearch bulk requests per indexing operation. This only applies to repository indexing operations. | +| `elasticsearch_worker_number_of_shards` **(PREMIUM)** | integer | no | Number of indexing worker shards. This improves non-code indexing throughput by enqueuing more parallel Sidekiq jobs. Default is `2`. | +| `elasticsearch_max_bulk_size_mb` **(PREMIUM)** | integer | no | Maximum size of Elasticsearch bulk indexing requests in MB. This only applies to repository indexing operations. | +| `elasticsearch_namespace_ids` **(PREMIUM)** | array of integers | no | The namespaces to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | +| `elasticsearch_project_ids` **(PREMIUM)** | array of integers | no | The projects to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | +| `elasticsearch_search` **(PREMIUM)** | boolean | no | Enable Elasticsearch search. | +| `elasticsearch_url` **(PREMIUM)** | string | no | The URL to use for connecting to Elasticsearch. Use a comma-separated list to support cluster (for example, `http://localhost:9200, http://localhost:9201"`). | +| `elasticsearch_username` **(PREMIUM)** | string | no | The `username` of your Elasticsearch instance. | +| `elasticsearch_password` **(PREMIUM)** | string | no | The password of your Elasticsearch instance. | | `email_additional_text` **(PREMIUM)** | string | no | Additional text added to the bottom of every email for legal/auditing/compliance reasons. | | `email_author_in_body` | boolean | no | Some email servers do not support overriding the email sender name. Enable this option to include the name of the author of the issue, merge request or comment in the email body instead. | | `email_confirmation_setting` | string | no | Specifies whether users must confirm their email before sign in. Possible values are `off`, `soft`, and `hard`. | +| `custom_http_clone_url_root` | string | no | Set a custom Git clone URL for HTTP(S). | | `enabled_git_access_protocol` | string | no | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `nil` to allow both protocols. | | `enforce_namespace_storage_limit` | boolean | no | Enabling this permits enforcement of namespace storage limits. | | `enforce_terms` | boolean | no | (**If enabled, requires:** `terms`) Enforce application ToS to all users. | @@ -392,14 +413,17 @@ listed in the descriptions of the relevant settings. | `external_auth_client_key_pass` | string | no | Passphrase to use for the private key when authenticating with the external service this is encrypted when stored. | | `external_auth_client_key` | string | required by: `external_auth_client_cert` | Private key for the certificate when authentication is required for the external authorization service, this is encrypted when stored. | | `external_authorization_service_default_label` | string | required by:<br>`external_authorization_service_enabled` | The default classification label to use when requesting authorization and no classification label has been specified on the project. | -| `external_authorization_service_enabled` | boolean | no | (**If enabled, requires:** `external_authorization_service_default_label`, `external_authorization_service_timeout` and `external_authorization_service_url`) Enable using an external authorization service for accessing projects. | -| `external_authorization_service_timeout` | float | required by:<br>`external_authorization_service_enabled` | The timeout after which an authorization request is aborted, in seconds. When a request times out, access is denied to the user. (min: 0.001, max: 10, step: 0.001). | -| `external_authorization_service_url` | string | required by:<br>`external_authorization_service_enabled` | URL to which authorization requests are directed. | -| `external_pipeline_validation_service_url` | string | no | URL to use for pipeline validation requests. | -| `external_pipeline_validation_service_token` | string | no | Optional. Token to include as the `X-Gitlab-Token` header in requests to the URL in `external_pipeline_validation_service_url`. | +| `external_authorization_service_enabled` | boolean | no | (**If enabled, requires:** `external_authorization_service_default_label`, `external_authorization_service_timeout` and `external_authorization_service_url`) Enable using an external authorization service for accessing projects. | +| `external_authorization_service_timeout` | float | required by:<br>`external_authorization_service_enabled` | The timeout after which an authorization request is aborted, in seconds. When a request times out, access is denied to the user. (min: 0.001, max: 10, step: 0.001). | +| `external_authorization_service_url` | string | required by:<br>`external_authorization_service_enabled` | URL to which authorization requests are directed. | +| `external_pipeline_validation_service_url` | string | no | URL to use for pipeline validation requests. | +| `external_pipeline_validation_service_token` | string | no | Optional. Token to include as the `X-Gitlab-Token` header in requests to the URL in `external_pipeline_validation_service_url`. | | `external_pipeline_validation_service_timeout` | integer | no | How long to wait for a response from the pipeline validation service. Assumes `OK` if it times out. | -| `file_template_project_id` **(PREMIUM)** | integer | no | The ID of a project to load custom file templates from. | -| `first_day_of_week` | integer | no | Start day of the week for calendar views and date pickers. Valid values are `0` (default) for Sunday, `1` for Monday, and `6` for Saturday. | +| `static_objects_external_storage_url` | string | no | URL to an external storage for repository static objects. | +| `static_objects_external_storage_auth_token` | string | required by: `static_objects_external_storage_url` | Authentication token for the external storage linked in `static_objects_external_storage_url`. | +| `file_template_project_id` **(PREMIUM)** | integer | no | The ID of a project to load custom file templates from. | +| `first_day_of_week` | integer | no | Start day of the week for calendar views and date pickers. Valid values are `0` (default) for Sunday, `1` for Monday, and `6` for Saturday. | +| `globally_allowed_ips` | string | no | Comma-separated list of IP addresses and CIDRs always allowed for inbound traffic. For example, `1.1.1.1, 2.2.2.0/24`. | | `geo_node_allowed_ips` **(PREMIUM)** | string | yes | Comma-separated list of IPs and CIDRs of allowed secondary nodes. For example, `1.1.1.1, 2.2.2.0/24`. | | `geo_status_timeout` **(PREMIUM)** | integer | no | The amount of seconds after which a request to get a secondary node status times out. | | `git_two_factor_session_expiry` **(PREMIUM)** | integer | no | Maximum duration (in minutes) of a session for Git operations when 2FA is enabled. | @@ -410,7 +434,7 @@ listed in the descriptions of the relevant settings. | `grafana_enabled` | boolean | no | Enable Grafana. | | `grafana_url` | string | no | Grafana URL. | | `gravatar_enabled` | boolean | no | Enable Gravatar. | -| `group_owners_can_manage_default_branch_protection` **(PREMIUM SELF)** | boolean | no | Prevent overrides of default branch protection. | +| `group_owners_can_manage_default_branch_protection` **(PREMIUM SELF)** | boolean | no | Prevent overrides of default branch protection. | | `hashed_storage_enabled` | boolean | no | Create new projects using hashed storage paths: Enable immutable, hash-based paths and repository names to store repositories on disk. This prevents repositories from having to be moved or renamed when the Project URL changes and may improve disk I/O performance. (Always enabled in GitLab versions 13.0 and later, configuration is scheduled for removal in 14.0) | | `help_page_hide_commercial_content` | boolean | no | Hide marketing-related entries from help. | | `help_page_support_url` | string | no | Alternate support URL for help page and help dropdown list. | @@ -437,31 +461,35 @@ listed in the descriptions of the relevant settings. | `maintenance_mode` **(PREMIUM)** | boolean | no | When instance is in maintenance mode, non-administrative users can sign in with read-only access and make read-only API requests. | | `max_artifacts_size` | integer | no | Maximum artifacts size in MB. | | `max_attachment_size` | integer | no | Limit attachment size in MB. | +| `max_decompressed_archive_size` | integer | no | Maximum decompressed file size for imported archives in MB. Set to `0` for unlimited. Default is `25600`. | | `max_export_size` | integer | no | Maximum export size in MB. 0 for unlimited. Default = 0 (unlimited). | | `max_import_size` | integer | no | Maximum import size in MB. 0 for unlimited. Default = 0 (unlimited). [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to 0 in GitLab 13.8. | +| `max_import_remote_file_size` | integer | no | Maximum remote file size for imports from external object storages. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384976) in GitLab 16.3. | | `max_pages_size` | integer | no | Maximum size of pages repositories in MB. | -| `max_personal_access_token_lifetime` **(ULTIMATE SELF)** | integer | no | Maximum allowable lifetime for access tokens in days. When left blank, default value of 365 is applied. When set, value must be 365 or less. When changed, existing access tokens with an expiration date beyond the maximum allowable lifetime are revoked.| +| `max_personal_access_token_lifetime` **(ULTIMATE SELF)** | integer | no | Maximum allowable lifetime for access tokens in days. When left blank, default value of 365 is applied. When set, value must be 365 or less. When changed, existing access tokens with an expiration date beyond the maximum allowable lifetime are revoked.| | `max_ssh_key_lifetime` **(ULTIMATE SELF)** | integer | no | Maximum allowable lifetime for SSH keys in days. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1007) in GitLab 14.6. | -| `max_terraform_state_size_bytes` | integer | no | Maximum size in bytes of the [Terraform state](../administration/terraform_state.md) files. Set this to 0 for unlimited file size. | +| `max_terraform_state_size_bytes` | integer | no | Maximum size in bytes of the [Terraform state](../administration/terraform_state.md) files. Set this to 0 for unlimited file size. | | `metrics_method_call_threshold` | integer | no | A method call is only tracked when it takes longer than the given amount of milliseconds. | -| `max_number_of_repository_downloads` **(ULTIMATE SELF)** | integer | no | Maximum number of unique repositories a user can download in the specified time period before they are banned. Default: 0, Maximum: 10,000 repositories. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87980) in GitLab 15.1. | -| `max_number_of_repository_downloads_within_time_period` **(ULTIMATE SELF)** | integer | no | Reporting time period (in seconds). Default: 0, Maximum: 864000 seconds (10 days). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87980) in GitLab 15.1. | -| `max_yaml_depth` | integer | no | The maximum depth of nested CI/CD configuration added with the [`include` keyword](../ci/yaml/index.md#include). Default: `100`. | -| `max_yaml_size_bytes` | integer | no | The maximum size in bytes of a single CI/CD configuration file. Default: `1048576`. | -| `git_rate_limit_users_allowlist` **(ULTIMATE SELF)** | array of strings | no | List of usernames excluded from Git anti-abuse rate limits. Default: `[]`, Maximum: 100 usernames. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90815) in GitLab 15.2. | -| `git_rate_limit_users_alertlist` **(ULTIMATE SELF)** | array of integers | no | List of user IDs that are emailed when the Git abuse rate limit is exceeded. Default: `[]`, Maximum: 100 user IDs. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110201) in GitLab 15.9. | -| `auto_ban_user_on_excessive_projects_download` **(ULTIMATE SELF)** | boolean | no | When enabled, users will get automatically banned from the application when they download more than the maximum number of unique projects in the time period specified by `max_number_of_repository_downloads` and `max_number_of_repository_downloads_within_time_period` respectively. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/94153) in GitLab 15.4 | +| `max_number_of_repository_downloads` **(ULTIMATE SELF)** | integer | no | Maximum number of unique repositories a user can download in the specified time period before they are banned. Default: 0, Maximum: 10,000 repositories. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87980) in GitLab 15.1. | +| `max_number_of_repository_downloads_within_time_period` **(ULTIMATE SELF)** | integer | no | Reporting time period (in seconds). Default: 0, Maximum: 864000 seconds (10 days). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87980) in GitLab 15.1. | +| `max_yaml_depth` | integer | no | The maximum depth of nested CI/CD configuration added with the [`include` keyword](../ci/yaml/index.md#include). Default: `100`. | +| `max_yaml_size_bytes` | integer | no | The maximum size in bytes of a single CI/CD configuration file. Default: `1048576`. | +| `git_rate_limit_users_allowlist` **(ULTIMATE SELF)** | array of strings | no | List of usernames excluded from Git anti-abuse rate limits. Default: `[]`, Maximum: 100 usernames. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90815) in GitLab 15.2. | +| `git_rate_limit_users_alertlist` **(ULTIMATE SELF)** | array of integers | no | List of user IDs that are emailed when the Git abuse rate limit is exceeded. Default: `[]`, Maximum: 100 user IDs. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110201) in GitLab 15.9. | +| `auto_ban_user_on_excessive_projects_download` **(ULTIMATE SELF)** | boolean | no | When enabled, users will get automatically banned from the application when they download more than the maximum number of unique projects in the time period specified by `max_number_of_repository_downloads` and `max_number_of_repository_downloads_within_time_period` respectively. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/94153) in GitLab 15.4 | | `mirror_available` | boolean | no | Allow repository mirroring to configured by project Maintainers. If disabled, only Administrators can configure repository mirroring. | -| `mirror_capacity_threshold` **(PREMIUM)** | integer | no | Minimum capacity to be available before scheduling more mirrors preemptively. | +| `mirror_capacity_threshold` **(PREMIUM)** | integer | no | Minimum capacity to be available before scheduling more mirrors preemptively. | | `mirror_max_capacity` **(PREMIUM)** | integer | no | Maximum number of mirrors that can be synchronizing at the same time. | | `mirror_max_delay` **(PREMIUM)** | integer | no | Maximum time (in minutes) between updates that a mirror can have when scheduled to synchronize. | -| `maven_package_requests_forwarding` **(PREMIUM)** | boolean | no | Use repo.maven.apache.org as a default remote repository when the package is not found in the GitLab Package Registry for Maven. | -| `npm_package_requests_forwarding` **(PREMIUM)** | boolean | no | Use npmjs.org as a default remote repository when the package is not found in the GitLab Package Registry for npm. | -| `pypi_package_requests_forwarding` **(PREMIUM)** | boolean | no | Use pypi.org as a default remote repository when the package is not found in the GitLab Package Registry for PyPI. | +| `maven_package_requests_forwarding` **(PREMIUM)** | boolean | no | Use repo.maven.apache.org as a default remote repository when the package is not found in the GitLab Package Registry for Maven. | +| `npm_package_requests_forwarding` **(PREMIUM)** | boolean | no | Use npmjs.org as a default remote repository when the package is not found in the GitLab Package Registry for npm. | +| `pypi_package_requests_forwarding` **(PREMIUM)** | boolean | no | Use pypi.org as a default remote repository when the package is not found in the GitLab Package Registry for PyPI. | | `outbound_local_requests_whitelist` | array of strings | no | Define a list of trusted domains or IP addresses to which local requests are allowed when local requests for webhooks and integrations are disabled. -| `pages_domain_verification_enabled` | boolean | no | Require users to prove ownership of custom domains. Domain verification is an essential security measure for public GitLab sites. Users are required to demonstrate they control a domain before it is enabled. | +| `package_registry_allow_anyone_to_pull_option` | boolean | no | Enable to [allow anyone to pull from Package Registry](../user/packages/package_registry/index.md#allow-anyone-to-pull-from-package-registry) visible and changeable. +| `pages_domain_verification_enabled` | boolean | no | Require users to prove ownership of custom domains. Domain verification is an essential security measure for public GitLab sites. Users are required to demonstrate they control a domain before it is enabled. | | `password_authentication_enabled_for_git` | boolean | no | Enable authentication for Git over HTTP(S) via a GitLab account password. Default is `true`. | | `password_authentication_enabled_for_web` | boolean | no | Enable authentication for the web interface via a GitLab account password. Default is `true`. | +| `minimum_password_length` **(PREMIUM)** | integer | no | Indicates whether passwords require a minimum length. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85763) in GitLab 15.1. | | `password_number_required` **(PREMIUM)** | boolean | no | Indicates whether passwords require at least one number. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85763) in GitLab 15.1. | | `password_symbol_required` **(PREMIUM)** | boolean | no | Indicates whether passwords require at least one symbol character. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85763) in GitLab 15.1. | | `password_uppercase_required` **(PREMIUM)** | boolean | no | Indicates whether passwords require at least one uppercase letter. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85763) in GitLab 15.1. | @@ -469,15 +497,23 @@ listed in the descriptions of the relevant settings. | `performance_bar_allowed_group_id` | string | no | (Deprecated: Use `performance_bar_allowed_group_path` instead) Path of the group that is allowed to toggle the performance bar. | | `performance_bar_allowed_group_path` | string | no | Path of the group that is allowed to toggle the performance bar. | | `performance_bar_enabled` | boolean | no | (Deprecated: Pass `performance_bar_allowed_group_path: nil` instead) Allow enabling the performance bar. | -| `personal_access_token_prefix` | string | no | Prefix for all generated personal access tokens. | +| `personal_access_token_prefix` | string | no | Prefix for all generated personal access tokens. | | `pipeline_limit_per_project_user_sha` | integer | no | Maximum number of pipeline creation requests per minute per user and commit. Disabled by default. | +| `gitpod_enabled` | boolean | no | (**If enabled, requires:** `gitpod_url`) Enable [Gitpod integration](../integration/gitpod.md). Default is `false`. | +| `gitpod_url` | boolean | required by: `gitpod_enabled` | The Gitpod instance URL for integration. | +| `kroki_enabled` | boolean | no | (**If enabled, requires:** `kroki_url`) Enable [Kroki integration](../administration/integration/kroki.md). Default is `false`. | +| `kroki_url` | boolean | required by: `kroki_enabled` | The Kroki instance URL for integration. | +| `kroki_formats` | object | no | Additional formats supported by the Kroki instance. Possible values are: <code>bpmn: (true|false)</code>, <code>blockdiag: (true|false)</code> and <code>excalidraw: (true|false)</code> | | `plantuml_enabled` | boolean | no | (**If enabled, requires:** `plantuml_url`) Enable [PlantUML integration](../administration/integration/plantuml.md). Default is `false`. | | `plantuml_url` | string | required by: `plantuml_enabled` | The PlantUML instance URL for integration. | | `polling_interval_multiplier` | decimal | no | Interval multiplier used by endpoints that perform polling. Set to `0` to disable polling. | | `project_export_enabled` | boolean | no | Enable project export. | -| `projects_api_rate_limit_unauthenticated` | integer | no | [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112283) in GitLab 15.10. Max number of requests per 10 minutes per IP address for unauthenticated requests to the [list all projects API](projects.md#list-all-projects). Default: 400. To disable throttling set to 0.| +| `projects_api_rate_limit_unauthenticated` | integer | no | [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112283) in GitLab 15.10. Max number of requests per 10 minutes per IP address for unauthenticated requests to the [list all projects API](projects.md#list-all-projects). Default: 400. To disable throttling set to 0.| | `prometheus_metrics_enabled` | boolean | no | Enable Prometheus metrics. | | `protected_ci_variables` | boolean | no | CI/CD variables are protected by default. | +| `disable_overriding_approvers_per_merge_request` | boolean | no | Prevent editing approval rules in projects and merge requests | +| `prevent_merge_requests_author_approval` | boolean | no | Prevent approval by author | +| `prevent_merge_requests_committers_approval` | boolean | no | Prevent editing approval rules in projects and merge requests | | `push_event_activities_limit` | integer | no | Maximum number of changes (branches or tags) in a single push above which a [bulk push event is created](../administration/settings/push_event_activities_limit.md). Setting to `0` does not disable throttling. | | `push_event_hooks_limit` | integer | no | Maximum number of changes (branches or tags) in a single push above which webhooks and integrations are not triggered. Setting to `0` does not disable throttling. | | `rate_limiting_response_text` | string | no | When rate limiting is enabled via the `throttle_*` settings, send this plain text response when a rate limit is exceeded. 'Retry later' is sent if this is blank. | @@ -486,6 +522,7 @@ listed in the descriptions of the relevant settings. | `search_rate_limit` | integer | no | Max number of requests per minute for performing a search while authenticated. Default: 30. To disable throttling set to 0.| | `search_rate_limit_unauthenticated` | integer | no | Max number of requests per minute for performing a search while unauthenticated. Default: 10. To disable throttling set to 0.| | `recaptcha_enabled` | boolean | no | (**If enabled, requires:** `recaptcha_private_key` and `recaptcha_site_key`) Enable reCAPTCHA. | +| `login_recaptcha_protection_enabled` | boolean | no | Enable reCAPTCHA for login. | | `recaptcha_private_key` | string | required by: `recaptcha_enabled` | Private key for reCAPTCHA. | | `recaptcha_site_key` | string | required by: `recaptcha_enabled` | Site key for reCAPTCHA. | | `receive_max_input_size` | integer | no | Maximum push size (MB). | @@ -502,9 +539,12 @@ listed in the descriptions of the relevant settings. | `shared_runners_enabled` | boolean | no | (**If enabled, requires:** `shared_runners_text` and `shared_runners_minutes`) Enable shared runners for new projects. | | `shared_runners_minutes` **(PREMIUM)** | integer | required by: `shared_runners_enabled` | Set the maximum number of compute minutes that a group can use on shared runners per month. | | `shared_runners_text` | string | required by: `shared_runners_enabled` | Shared runners text. | -| `sidekiq_job_limiter_mode` | string | no | `track` or `compress`. Sets the behavior for [Sidekiq job size limits](../administration/settings/sidekiq_job_limits.md). Default: 'compress'. | -| `sidekiq_job_limiter_compression_threshold_bytes` | integer | no | The threshold in bytes at which Sidekiq jobs are compressed before being stored in Redis. Default: 100,000 bytes (100 KB). | -| `sidekiq_job_limiter_limit_bytes` | integer | no | The threshold in bytes at which Sidekiq jobs are rejected. Default: 0 bytes (doesn't reject any job). | +| `runner_token_expiration_interval` | integer | no | Set the expiration time (in seconds) of authentication tokens of newly registered instance runners. Minimum value is 7200 seconds. For more information, see [Automatically rotate authentication tokens](../ci/runners/configure_runners.md#automatically-rotate-authentication-tokens). | +| `group_runner_token_expiration_interval` | integer | no | Set the expiration time (in seconds) of authentication tokens of newly registered group runners. Minimum value is 7200 seconds. For more information, see [Automatically rotate authentication tokens](../ci/runners/configure_runners.md#automatically-rotate-authentication-tokens). | +| `project_runner_token_expiration_interval` | integer | no | Set the expiration time (in seconds) of authentication tokens of newly registered project runners. Minimum value is 7200 seconds. For more information, see [Automatically rotate authentication tokens](../ci/runners/configure_runners.md#automatically-rotate-authentication-tokens). | +| `sidekiq_job_limiter_mode` | string | no | `track` or `compress`. Sets the behavior for [Sidekiq job size limits](../administration/settings/sidekiq_job_limits.md). Default: 'compress'. | +| `sidekiq_job_limiter_compression_threshold_bytes` | integer | no | The threshold in bytes at which Sidekiq jobs are compressed before being stored in Redis. Default: 100,000 bytes (100 KB). | +| `sidekiq_job_limiter_limit_bytes` | integer | no | The threshold in bytes at which Sidekiq jobs are rejected. Default: 0 bytes (doesn't reject any job). | | `sign_in_text` | string | no | Deprecated: Use `description` parameter in the [Appearance API](../api/appearance.md). Custom text in sign-in page. | | `signin_enabled` | string | no | (Deprecated: Use `password_authentication_enabled_for_web` instead) Flag indicating if password authentication is enabled for the web interface. | | `signup_enabled` | boolean | no | Enable registration. Default is `true`. | @@ -528,39 +568,39 @@ listed in the descriptions of the relevant settings. | `suggest_pipeline_enabled` | boolean | no | Enable pipeline suggestion banner. | | `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to `0` for unlimited time. | | `terms` | text | required by: `enforce_terms` | (**Required by:** `enforce_terms`) Markdown content for the ToS. | -| `throttle_authenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_api_period_in_seconds` and `throttle_authenticated_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | -| `throttle_authenticated_api_period_in_seconds` | integer | required by:<br>`throttle_authenticated_api_enabled` | Rate limit period (in seconds). | -| `throttle_authenticated_api_requests_per_period` | integer | required by:<br>`throttle_authenticated_api_enabled` | Maximum requests per period per user. | -| `throttle_authenticated_packages_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_packages_api_period_in_seconds` and `throttle_authenticated_packages_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). View [Package Registry rate limits](../administration/settings/package_registry_rate_limits.md) for more details. | -| `throttle_authenticated_packages_api_period_in_seconds` | integer | required by:<br>`throttle_authenticated_packages_api_enabled` | Rate limit period (in seconds). View [Package Registry rate limits](../administration/settings/package_registry_rate_limits.md) for more details. | -| `throttle_authenticated_packages_api_requests_per_period` | integer | required by:<br>`throttle_authenticated_packages_api_enabled` | Maximum requests per period per user. View [Package Registry rate limits](../administration/settings/package_registry_rate_limits.md) for more details. | -| `throttle_authenticated_web_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_web_period_in_seconds` and `throttle_authenticated_web_requests_per_period`) Enable authenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | -| `throttle_authenticated_web_period_in_seconds` | integer | required by:<br>`throttle_authenticated_web_enabled` | Rate limit period (in seconds). | -| `throttle_authenticated_web_requests_per_period` | integer | required by:<br>`throttle_authenticated_web_enabled` | Maximum requests per period per user. | -| `throttle_unauthenticated_enabled` | boolean | no | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_enabled` or `throttle_unauthenticated_api_enabled` instead.) (**If enabled, requires:** `throttle_unauthenticated_period_in_seconds` and `throttle_unauthenticated_requests_per_period`) Enable unauthenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | -| `throttle_unauthenticated_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_enabled` | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_period_in_seconds` or `throttle_unauthenticated_api_period_in_seconds` instead.) Rate limit period in seconds. | -| `throttle_unauthenticated_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_enabled` | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_requests_per_period` or `throttle_unauthenticated_api_requests_per_period` instead.) Max requests per period per IP. | -| `throttle_unauthenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_api_period_in_seconds` and `throttle_unauthenticated_api_requests_per_period`) Enable unauthenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | -| `throttle_unauthenticated_api_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_api_enabled` | Rate limit period in seconds. | -| `throttle_unauthenticated_api_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_api_enabled` | Max requests per period per IP. | -| `throttle_unauthenticated_packages_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_packages_api_period_in_seconds` and `throttle_unauthenticated_packages_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). View [Package Registry rate limits](../administration/settings/package_registry_rate_limits.md) for more details. | -| `throttle_unauthenticated_packages_api_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_packages_api_enabled` | Rate limit period (in seconds). View [Package Registry rate limits](../administration/settings/package_registry_rate_limits.md) for more details. | -| `throttle_unauthenticated_packages_api_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_packages_api_enabled` | Maximum requests per period per user. View [Package Registry rate limits](../administration/settings/package_registry_rate_limits.md) for more details. | -| `throttle_unauthenticated_web_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_web_period_in_seconds` and `throttle_unauthenticated_web_requests_per_period`) Enable unauthenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | -| `throttle_unauthenticated_web_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_web_enabled` | Rate limit period in seconds. | -| `throttle_unauthenticated_web_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_web_enabled` | Max requests per period per IP. | +| `throttle_authenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_api_period_in_seconds` and `throttle_authenticated_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | +| `throttle_authenticated_api_period_in_seconds` | integer | required by:<br>`throttle_authenticated_api_enabled` | Rate limit period (in seconds). | +| `throttle_authenticated_api_requests_per_period` | integer | required by:<br>`throttle_authenticated_api_enabled` | Maximum requests per period per user. | +| `throttle_authenticated_packages_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_packages_api_period_in_seconds` and `throttle_authenticated_packages_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). View [Package Registry rate limits](../administration/settings/package_registry_rate_limits.md) for more details. | +| `throttle_authenticated_packages_api_period_in_seconds` | integer | required by:<br>`throttle_authenticated_packages_api_enabled` | Rate limit period (in seconds). View [Package Registry rate limits](../administration/settings/package_registry_rate_limits.md) for more details. | +| `throttle_authenticated_packages_api_requests_per_period` | integer | required by:<br>`throttle_authenticated_packages_api_enabled` | Maximum requests per period per user. View [Package Registry rate limits](../administration/settings/package_registry_rate_limits.md) for more details. | +| `throttle_authenticated_web_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_web_period_in_seconds` and `throttle_authenticated_web_requests_per_period`) Enable authenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | +| `throttle_authenticated_web_period_in_seconds` | integer | required by:<br>`throttle_authenticated_web_enabled` | Rate limit period (in seconds). | +| `throttle_authenticated_web_requests_per_period` | integer | required by:<br>`throttle_authenticated_web_enabled` | Maximum requests per period per user. | +| `throttle_unauthenticated_enabled` | boolean | no | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_enabled` or `throttle_unauthenticated_api_enabled` instead.) (**If enabled, requires:** `throttle_unauthenticated_period_in_seconds` and `throttle_unauthenticated_requests_per_period`) Enable unauthenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | +| `throttle_unauthenticated_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_enabled` | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_period_in_seconds` or `throttle_unauthenticated_api_period_in_seconds` instead.) Rate limit period in seconds. | +| `throttle_unauthenticated_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_enabled` | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_requests_per_period` or `throttle_unauthenticated_api_requests_per_period` instead.) Max requests per period per IP. | +| `throttle_unauthenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_api_period_in_seconds` and `throttle_unauthenticated_api_requests_per_period`) Enable unauthenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | +| `throttle_unauthenticated_api_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_api_enabled` | Rate limit period in seconds. | +| `throttle_unauthenticated_api_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_api_enabled` | Max requests per period per IP. | +| `throttle_unauthenticated_packages_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_packages_api_period_in_seconds` and `throttle_unauthenticated_packages_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). View [Package Registry rate limits](../administration/settings/package_registry_rate_limits.md) for more details. | +| `throttle_unauthenticated_packages_api_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_packages_api_enabled` | Rate limit period (in seconds). View [Package Registry rate limits](../administration/settings/package_registry_rate_limits.md) for more details. | +| `throttle_unauthenticated_packages_api_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_packages_api_enabled` | Maximum requests per period per user. View [Package Registry rate limits](../administration/settings/package_registry_rate_limits.md) for more details. | +| `throttle_unauthenticated_web_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_web_period_in_seconds` and `throttle_unauthenticated_web_requests_per_period`) Enable unauthenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | +| `throttle_unauthenticated_web_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_web_enabled` | Rate limit period in seconds. | +| `throttle_unauthenticated_web_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_web_enabled` | Max requests per period per IP. | | `time_tracking_limit_to_hours` | boolean | no | Limit display of time tracking units to hours. Default is `false`. | | `two_factor_grace_period` | integer | required by: `require_two_factor_authentication` | Amount of time (in hours) that users are allowed to skip forced configuration of two-factor authentication. | -| `unconfirmed_users_delete_after_days` **(PREMIUM SELF)** | integer | no | Specifies how many days after sign-up to delete users who have not confirmed their email. Only applicable if `delete_unconfirmed_users` is set to `true`. Must be `1` or greater. Default is `7`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352514) in GitLab 16.1. | +| `unconfirmed_users_delete_after_days` **(PREMIUM SELF)** | integer | no | Specifies how many days after sign-up to delete users who have not confirmed their email. Only applicable if `delete_unconfirmed_users` is set to `true`. Must be `1` or greater. Default is `7`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352514) in GitLab 16.1. | | `unique_ips_limit_enabled` | boolean | no | (**If enabled, requires:** `unique_ips_limit_per_user` and `unique_ips_limit_time_window`) Limit sign in from multiple IPs. | | `unique_ips_limit_per_user` | integer | required by: `unique_ips_limit_enabled` | Maximum number of IPs per user. | | `unique_ips_limit_time_window` | integer | required by: `unique_ips_limit_enabled` | How many seconds an IP is counted towards the limit. | -| `update_runner_versions_enabled` | boolean | no | Fetch GitLab Runner release version data from GitLab.com. For more information, see how to [determine which runners need to be upgraded](../ci/runners/runners_scope.md#determine-which-runners-need-to-be-upgraded). | +| `update_runner_versions_enabled` | boolean | no | Fetch GitLab Runner release version data from GitLab.com. For more information, see how to [determine which runners need to be upgraded](../ci/runners/runners_scope.md#determine-which-runners-need-to-be-upgraded). | | `usage_ping_enabled` | boolean | no | Every week GitLab reports license usage back to GitLab, Inc. | | `user_deactivation_emails_enabled` | boolean | no | Send an email to users upon account deactivation. | | `user_default_external` | boolean | no | Newly registered users are external by default. | | `user_default_internal_regex` | string | no | Specify an email address regex pattern to identify default internal users. | -| `user_defaults_to_private_profile` | boolean | no | Newly created users have private profile by default. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231301) in GitLab 15.8. Defaults to `false`. | +| `user_defaults_to_private_profile` | boolean | no | Newly created users have private profile by default. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231301) in GitLab 15.8. Defaults to `false`. | | `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider. | | `user_show_add_ssh_key_message` | boolean | no | When set to `false` disable the `You won't be able to pull or push project code via SSH` warning shown to users with no uploaded SSH key. | | `version_check_enabled` | boolean | no | Let GitLab inform you when an update is available. | diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 578c72a0502..6fa6be3a43b 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Snippets API **(FREE)** +# Snippets API **(FREE ALL)** Snippets API operates on [snippets](../user/snippets.md). Related APIs exist for [project snippets](project_snippets.md) and @@ -23,7 +23,7 @@ Valid values for snippet visibility levels are: | `internal` | Snippet is visible for any authenticated user except [external users](../administration/external_users.md). | | `public` | Snippet can be accessed without any authentication. | -## List all snippets for a user +## List all snippets for current user Get a list of the current user's snippets. @@ -455,6 +455,107 @@ Example response: ] ``` +## List all snippets + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419640) in GitLab 16.3. + +List all snippets the current user has access to. +Users with the Administrator or Auditor access levels can see all snippets +(both personal and project). + +```plaintext +GET /snippets/all +``` + +Parameters: + +| Attribute | Type | Required | Description | +|------------------|----------|----------|----------------------------------------| +| `created_after` | datetime | no | Return snippets created after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `created_before` | datetime | no | Return snippets created before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `page` | integer | no | Page to retrieve. | +| `per_page` | integer | no | Number of snippets to return per page. | +| `repository_storage` | string | no | Filter by repository storage used by the snippet _(administrators only)_. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419640) in GitLab 16.3 | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/snippets/all?per_page=2&page=1" +``` + +Example response: + +```json +[ + { + "id": 113, + "title": "Internal Project Snippet", + "description": null, + "visibility": "internal", + "author": { + "id": 17, + "username": "tim_kreiger", + "name": "Tim Kreiger", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/edaf55a9e363ea263e3b981d09e0f7f7?s=80&d=identicon", + "web_url": "http://example.com/tim_kreiger" + }, + "created_at": "2023-08-03T10:21:02.480Z", + "updated_at": "2023-08-03T10:21:02.480Z", + "project_id": 35, + "web_url": "http://example.com/tim_kreiger/internal_project/-/snippets/113", + "raw_url": "http://example.com/tim_kreiger/internal_project/-/snippets/113/raw", + "file_name": "", + "files": [], + "repository_storage": "default" + }, + { + "id": 112, + "title": "Private Personal Snippet", + "description": null, + "visibility": "private", + "author": { + "id": 1, + "username": "root", + "name": "Administrator", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/edaf55a9e363ea263e3b981d09e0f7f7?s=80&d=identicon", + "web_url": "http://example.com/root" + }, + "created_at": "2023-08-03T10:20:59.994Z", + "updated_at": "2023-08-03T10:20:59.994Z", + "project_id": null, + "web_url": "http://example.com/-/snippets/112", + "raw_url": "http://example.com/-/snippets/112/raw", + "file_name": "", + "files": [], + "repository_storage": "default" + }, + { + "id": 111, + "title": "Public Personal Snippet", + "description": null, + "visibility": "public", + "author": { + "id": 17, + "username": "tim_kreiger", + "name": "Tim Kreiger", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/edaf55a9e363ea263e3b981d09e0f7f7?s=80&d=identicon", + "web_url": "http://example.com/tim_kreiger" + }, + "created_at": "2023-08-03T10:21:01.312Z", + "updated_at": "2023-08-03T10:21:01.312Z", + "project_id": null, + "web_url": "http://example.com/-/snippets/111", + "raw_url": "http://example.com/-/snippets/111/raw", + "file_name": "", + "files": [], + "repository_storage": "default" + }, +] +``` + ## Get user agent details NOTE: diff --git a/doc/api/status_checks.md b/doc/api/status_checks.md index c024558b90c..c988f8d63fc 100644 --- a/doc/api/status_checks.md +++ b/doc/api/status_checks.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# External Status Checks API **(ULTIMATE)** +# External Status Checks API **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0, disabled behind the `:ff_external_status_checks` feature flag. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320783) in GitLab 14.1. diff --git a/doc/api/suggestions.md b/doc/api/suggestions.md index bb1f3968cf3..3dd3ef3712c 100644 --- a/doc/api/suggestions.md +++ b/doc/api/suggestions.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Suggest Changes API **(FREE)** +# Suggest Changes API **(FREE ALL)** This page describes the API for [suggesting changes](../user/project/merge_requests/reviews/suggestions.md). diff --git a/doc/api/tags.md b/doc/api/tags.md index 3f15cdd02f4..4b85c70f901 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Tags API **(FREE)** +# Tags API **(FREE ALL)** ## List project repository tags @@ -181,7 +181,7 @@ Parameters: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106578) in GitLab 15.7. -Get the [X.509 signature from a tag](../user/project/repository/x509_signed_commits/index.md#sign-commits-and-tags-with-x509-certificates), +Get the [X.509 signature from a tag](../user/project/repository/x509_signed_commits/index.md), if it is signed. Unsigned tags return a `404 Not Found` response. ```plaintext diff --git a/doc/api/templates/dockerfiles.md b/doc/api/templates/dockerfiles.md index 70c104612b8..0f20d38d9e8 100644 --- a/doc/api/templates/dockerfiles.md +++ b/doc/api/templates/dockerfiles.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Dockerfiles API **(FREE)** +# Dockerfiles API **(FREE ALL)** GitLab provides an API endpoint for instance-level Dockerfile templates. Default templates are defined at diff --git a/doc/api/templates/gitignores.md b/doc/api/templates/gitignores.md index 1569a2bc89d..d22b9373ccd 100644 --- a/doc/api/templates/gitignores.md +++ b/doc/api/templates/gitignores.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# .gitignore API **(FREE)** +# .gitignore API **(FREE ALL)** In GitLab, the `/gitignores` endpoint returns a list of Git `.gitignore` templates. For more information, see the [Git documentation for `.gitignore`](https://git-scm.com/docs/gitignore). diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md index 69346f8ab3d..d436e6385a9 100644 --- a/doc/api/templates/gitlab_ci_ymls.md +++ b/doc/api/templates/gitlab_ci_ymls.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab CI YAML API **(FREE)** +# GitLab CI YAML API **(FREE ALL)** In GitLab, there is an API endpoint available to work with GitLab CI/CD YAML. For more information on CI/CD pipeline configuration in GitLab, see the diff --git a/doc/api/templates/licenses.md b/doc/api/templates/licenses.md index 6abdb3ca3b0..fc9af40a963 100644 --- a/doc/api/templates/licenses.md +++ b/doc/api/templates/licenses.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Licenses API **(FREE)** +# Licenses API **(FREE ALL)** In GitLab, there is an API endpoint available for working with various open source license templates. For more information on the terms of various diff --git a/doc/api/todos.md b/doc/api/todos.md index b66270d2f5d..a529839fd30 100644 --- a/doc/api/todos.md +++ b/doc/api/todos.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/product/ux/technical-writing/#assignments --- -# GitLab To-Do List API **(FREE)** +# GitLab To-Do List API **(FREE ALL)** Interact with [to-do items](../user/todos.md) using the REST API. diff --git a/doc/api/topics.md b/doc/api/topics.md index 8f2aae9e070..5d413eec7c0 100644 --- a/doc/api/topics.md +++ b/doc/api/topics.md @@ -4,7 +4,7 @@ group: Tenant Scale 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 --- -# Topics API **(FREE)** +# Topics API **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340920) in GitLab 14.5. diff --git a/doc/api/users.md b/doc/api/users.md index 3fb9d655ff9..9b00dc5c7e0 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -4,7 +4,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 --- -# Users API **(FREE)** +# Users API **(FREE ALL)** This documentation has information on API calls, parameters and responses for the Users API. @@ -97,7 +97,7 @@ GET /users?external=true ``` GitLab supports bot users such as the [alert bot](../operations/incident_management/integrations.md) -or the [support bot](../user/project/service_desk.md#support-bot-user). +or the [support bot](../user/project/service_desk/index.md#support-bot-user). You can exclude the following types of [internal users](../development/internal_users.md#internal-users) from the users' list with the `exclude_internal=true` parameter ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241144) in GitLab 13.4): @@ -131,6 +131,7 @@ GET /users?without_project_bots=true > - The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10. > - The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6. > - The `scim_identities` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324247) in GitLab 16.1. +> - The `auditors` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418023) in GitLab 16.2. ```plaintext GET /users @@ -145,6 +146,7 @@ You can use all [parameters available for everyone](#for-non-administrator-users | `two_factor` | string | no | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users | | `without_projects` | boolean | no | Filter users without projects. Default is `false`, which means that all users are returned, with and without projects. | | `admins` | boolean | no | Return only administrators. Default is `false` | +| `auditors` **(PREMIUM)** | boolean | no | Return only auditor users. Default is `false`. If not included, it returns all users. | | `saml_provider_id` **(PREMIUM)** | number | no | Return only users created by the specified SAML provider ID. If not included, it returns all users. | | `skip_ldap` **(PREMIUM)** | boolean | no | Skip LDAP users. | @@ -534,7 +536,7 @@ Parameters: | `avatar` | No | Image file for user's avatar | | `bio` | No | User's biography | | `can_create_group` | No | User can create top-level groups - true or false | -| `color_scheme_id` | No | User's color scheme for the file viewer (for more information, see the [user preference documentation](../user/profile/preferences.md#syntax-highlighting-theme)) | +| `color_scheme_id` | No | User's color scheme for the file viewer (for more information, see the [user preference documentation](../user/profile/preferences.md#change-the-syntax-highlighting-theme)) | | `email` | Yes | Email | | `extern_uid` | No | External UID | | `external` | No | Flags the user as external - true or false (default) | @@ -554,7 +556,7 @@ Parameters: | `shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Maximum number of monthly compute minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | | `skip_confirmation` | No | Skip confirmation - true or false (default) | | `skype` | No | Skype ID | -| `theme_id` | No | GitLab theme for the user (for more information, see the [user preference documentation](../user/profile/preferences.md#navigation-theme) for more information) | +| `theme_id` | No | GitLab theme for the user (for more information, see the [user preference documentation](../user/profile/preferences.md#change-the-color-theme) for more information) | | `twitter` | No | Twitter account | | `discord` | No | Discord account | | `username` | Yes | Username | @@ -583,7 +585,7 @@ Parameters: | `avatar` | No | Image file for user's avatar | | `bio` | No | User's biography | | `can_create_group` | No | User can create groups - true or false | -| `color_scheme_id` | No | User's color scheme for the file viewer (for more information, see the [user preference documentation](../user/profile/preferences.md#syntax-highlighting-theme) for more information) | +| `color_scheme_id` | No | User's color scheme for the file viewer (for more information, see the [user preference documentation](../user/profile/preferences.md#change-the-syntax-highlighting-theme) for more information) | | `commit_email` | No | User's commit email. Set to `_private` to use the private commit email. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375148) in GitLab 15.5. | | `email` | No | Email | | `extern_uid` | No | External UID | @@ -605,7 +607,7 @@ Parameters: | `shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Maximum number of monthly compute minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0`. | | `skip_reconfirmation` | No | Skip reconfirmation - true or false (default) | | `skype` | No | Skype ID | -| `theme_id` | No | GitLab theme for the user (for more information, see the [user preference documentation](../user/profile/preferences.md#navigation-theme) for more information) | +| `theme_id` | No | GitLab theme for the user (for more information, see the [user preference documentation](../user/profile/preferences.md#change-the-color-theme) for more information) | | `twitter` | No | Twitter account | | `discord` | No | Discord account | | `username` | No | Username | @@ -880,10 +882,10 @@ Example response: ```json { "id": 1, - "user_id": 1 - "view_diffs_file_by_file": true, - "show_whitespace_in_diffs": false, - "pass_user_identities_to_ci_jwt": false + "user_id": 1, + "view_diffs_file_by_file": true, + "show_whitespace_in_diffs": false, + "pass_user_identities_to_ci_jwt": false } ``` @@ -902,10 +904,10 @@ PUT /user/preferences ```json { "id": 1, - "user_id": 1 - "view_diffs_file_by_file": true, - "show_whitespace_in_diffs": false, - "pass_user_identities_to_ci_jwt": false + "user_id": 1, + "view_diffs_file_by_file": true, + "show_whitespace_in_diffs": false, + "pass_user_identities_to_ci_jwt": false } ``` @@ -1035,7 +1037,7 @@ Example response: > Ability to create a service account user was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/406782) in GitLab 16.1 -Creates a service account user with an auto-generated email address and username. +Creates a service account user with an auto-generated email address and username. Available only for administrators. ```plaintext POST /service_accounts @@ -2261,7 +2263,7 @@ Returns: - `403 Forbidden` if not authenticated as an administrator. - `404 User Not Found` if user cannot be found. -## Create a runner **(FREE)** +## Create a runner **(FREE ALL)** Creates a runner linked to the current user. diff --git a/doc/api/version.md b/doc/api/version.md index d7a13d78c14..14875f96589 100644 --- a/doc/api/version.md +++ b/doc/api/version.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Version API **(FREE)** +# Version API **(FREE ALL)** NOTE: We recommend you use the [Metadata API](metadata.md) instead of the Version API. diff --git a/doc/api/visual_review_discussions.md b/doc/api/visual_review_discussions.md index f6d6636280a..5b6cb07897d 100644 --- a/doc/api/visual_review_discussions.md +++ b/doc/api/visual_review_discussions.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w --- <!--- start_remove The following content will be removed on remove_date: '2024-05-22' --> -# Visual Review discussions API (deprecated) **(PREMIUM)** +# Visual Review discussions API (deprecated) **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18710) in GitLab 12.5. > - [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9. diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index 6f790227dea..9c496ba8bdc 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.md @@ -4,7 +4,7 @@ group: Threat Insights 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 --- -# Vulnerabilities API **(ULTIMATE)** +# Vulnerabilities API **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in GitLab 12.6. diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md index c72e4a36929..ab25ca9e511 100644 --- a/doc/api/vulnerability_exports.md +++ b/doc/api/vulnerability_exports.md @@ -4,7 +4,7 @@ group: Threat Insights 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 --- -# Vulnerability export API **(ULTIMATE)** +# Vulnerability export API **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197494) in GitLab 12.10. [Updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30397) in GitLab 13.0. diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md index 8cc4ed31425..a031e07fddf 100644 --- a/doc/api/vulnerability_findings.md +++ b/doc/api/vulnerability_findings.md @@ -4,7 +4,7 @@ group: Threat Insights 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 --- -# Vulnerability Findings API **(ULTIMATE)** +# Vulnerability Findings API **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19029) in GitLab 12.5. diff --git a/doc/api/wikis.md b/doc/api/wikis.md index 17317b7c594..3a5b8b075f5 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# Project wikis API **(FREE)** +# Project wikis API **(FREE ALL)** > - The `encoding` field was [added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/81150) in GitLab 14.9. > - The `render_html` attribute was [added](https://gitlab.com/gitlab-org/gitlab/-/issues/336792) in GitLab 14.9. diff --git a/doc/architecture/blueprints/ai_gateway/img/architecture.png b/doc/architecture/blueprints/ai_gateway/img/architecture.png Binary files differindex dea8b5ddb45..e63b4ba45d1 100644 --- a/doc/architecture/blueprints/ai_gateway/img/architecture.png +++ b/doc/architecture/blueprints/ai_gateway/img/architecture.png diff --git a/doc/architecture/blueprints/cells/cells-feature-admin-area.md b/doc/architecture/blueprints/cells/cells-feature-admin-area.md index 31d5388d40b..a9cd170b2a7 100644 --- a/doc/architecture/blueprints/cells/cells-feature-admin-area.md +++ b/doc/architecture/blueprints/cells/cells-feature-admin-area.md @@ -15,21 +15,16 @@ we can document the reasons for not choosing this approach. # Cells: Admin Area -In our Cells architecture proposal we plan to share all admin related tables in -GitLab. This allows simpler management of all Cells in one interface and reduces -the risk of settings diverging in different Cells. This introduces challenges -with admin pages that allow you to manage data that will be spread across all -Cells. +In our Cells architecture proposal we plan to share all admin related tables in GitLab. +This allows for simpler management of all Cells in one interface and reduces the risk of settings diverging in different Cells. +This introduces challenges with Admin Area pages that allow you to manage data that will be spread across all Cells. ## 1. Definition -There are consequences for admin pages that contain data that spans "the whole -instance" as the Admin pages may be served by any Cell or possibly just 1 cell. -There are already many parts of the Admin interface that will have data that -spans many cells. For example lists of all Groups, Projects, Topics, Jobs, -Analytics, Applications and more. There are also administrative monitoring -capabilities in the Admin page that will span many cells such as the "Background -Jobs" and "Background Migrations" pages. +There are consequences for Admin Area pages that contain data that span "the whole instance" as the Admin Area pages may be served by any Cell or possibly just one Cell. +There are already many parts of the Admin Area that will have data that span many Cells. +For example lists of all Groups, Projects, Topics, Jobs, Analytics, Applications and more. +There are also administrative monitoring capabilities in the Admin Area that will span many Cells such as the "Background Jobs" and "Background Migrations" pages. ## 2. Data flow @@ -38,20 +33,47 @@ Jobs" and "Background Migrations" pages. We will need to decide how to handle these exceptions with a few possible options: -1. Move all these pages out into a dedicated per-cell Admin section. Probably +1. Move all these pages out into a dedicated per-Cell admin section. Probably the URL will need to be routable to a single Cell like `/cells/<cell_id>/admin`, - then we can display this data per Cell. These pages will be distinct from - other Admin pages which control settings that are shared across all Cells. We + then we can display these data per Cell. These pages will be distinct from + other Admin Area pages which control settings that are shared across all Cells. We will also need to consider how this impacts self-managed customers and - whether, or not, this should be visible for single-cell instances of GitLab. + whether, or not, this should be visible for single-Cell instances of GitLab. 1. Build some aggregation interfaces for this data so that it can be fetched from all Cells and presented in a single UI. This may be beneficial to an administrator that needs to see and filter all data at a glance, especially when they don't know which Cell the data is on. The downside, however, is - that building this kind of aggregation is very tricky when all the Cells are - designed to be totally independent, and it does also enforce more strict + that building this kind of aggregation is very tricky when all Cells are + designed to be totally independent, and it does also enforce stricter requirements on compatibility between Cells. +The following overview describes at what level each feature contained in the current Admin Area will be managed: + +| Feature | Cluster | Cell | Organization | +| --- | --- | --- | --- | +| Abuse reports | | | | +| Analytics | | | | +| Applications | | | | +| Deploy keys | | | | +| Labels | | | | +| Messages | ✓ | | | +| Monitoring | | ✓ | | +| Subscription | | | | +| System hooks | | | | +| Overview | | | | +| Settings - General | ✓ | | | +| Settings - Integrations | ✓ | | | +| Settings - Repository | ✓ | | | +| Settings - CI/CD (1) | ✓ | ✓ | | +| Settings - Reporting | ✓ | | | +| Settings - Metrics | ✓ | | | +| Settings - Service usage data | | ✓ | | +| Settings - Network | ✓ | | | +| Settings - Appearance | ✓ | | | +| Settings - Preferences | ✓ | | | + +(1) Depending on the specific setting, some will be managed at the cluster-level, and some at the Cell-level. + ## 4. Evaluation ## 4.1. Pros diff --git a/doc/architecture/blueprints/cells/cells-feature-backups.md b/doc/architecture/blueprints/cells/cells-feature-backups.md index b5d5d7afdcf..3d20d6e2caa 100644 --- a/doc/architecture/blueprints/cells/cells-feature-backups.md +++ b/doc/architecture/blueprints/cells/cells-feature-backups.md @@ -15,47 +15,38 @@ we can document the reasons for not choosing this approach. # Cells: Backups -Each cells will take its own backups, and consequently have its own isolated -backup / restore procedure. +Each Cell will take its own backups, and consequently have its own isolated backup/restore procedure. ## 1. Definition -GitLab Backup takes a backup of the PostgreSQL database used by the application, -and also Git repository data. +GitLab backup takes a backup of the PostgreSQL database used by the application, and also Git repository data. ## 2. Data flow -Each cell has a number of application databases to back up (for example, `main`, and `ci`). - -Additionally, there may be cluster-wide metadata tables (for example, `users` table) -which is directly accessible via PostgreSQL. +Each Cell has a number of application databases to back up (for example, `main`, and `ci`). +Additionally, there may be cluster-wide metadata tables (for example, `users` table) which is directly accessible via PostgreSQL. ## 3. Proposal ### 3.1. Cluster-wide metadata -It is currently unknown how cluster-wide metadata tables will be accessible. We -may choose to have cluster-wide metadata tables backed up separately, or have -each cell back up its copy of cluster-wide metdata tables. +It is currently unknown how cluster-wide metadata tables will be accessible. +We may choose to have cluster-wide metadata tables backed up separately, or have each Cell back up its copy of cluster-wide metadata tables. ### 3.2 Consistency #### 3.2.1 Take backups independently -As each cell will communicate with each other via API, and there will be no joins -to the users table, it should be acceptable for each cell to take a backup -independently of each other. +As each Cell will communicate with each other via API, and there will be no joins to the `users` table, it should be acceptable for each Cell to take a backup independently of each other. #### 3.2.2 Enforce snapshots -We can require that each cell take a snapshot for the PostgreSQL databases at -around the same time to allow for a consistent-enough backup. +We can require that each Cell take a snapshot for the PostgreSQL databases at around the same time to allow for a consistent enough backup. ## 4. Evaluation -As the number of cells increases, it will likely not be feasible to take a -snapshot at the same time for all cells. Hence taking backups independently is -the better option. +As the number of Cells increases, it will likely not be feasible to take a snapshot at the same time for all Cells. +Hence taking backups independently is the better option. ## 4.1. Pros diff --git a/doc/architecture/blueprints/cells/cells-feature-ci-runners.md b/doc/architecture/blueprints/cells/cells-feature-ci-runners.md index 8a6790ae49f..4e7cea5bfd5 100644 --- a/doc/architecture/blueprints/cells/cells-feature-ci-runners.md +++ b/doc/architecture/blueprints/cells/cells-feature-ci-runners.md @@ -15,156 +15,129 @@ we can document the reasons for not choosing this approach. # Cells: CI Runners -GitLab in order to execute CI jobs [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/), -very often managed by customer in their infrastructure. - -All CI jobs created as part of CI pipeline are run in a context of project -it poses a challenge how to manage GitLab Runners. +GitLab executes CI jobs via [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/), very often managed by customers in their infrastructure. +All CI jobs created as part of the CI pipeline are run in the context of a Project. +This poses a challenge how to manage GitLab Runners. ## 1. Definition There are 3 different types of runners: -- instance-wide: runners that are registered globally with specific tags (selection criteria) -- group runners: runners that execute jobs from a given top-level group or subprojects of that group -- project runners: runners that execute jobs from projects or many projects: some runners might - have projects assigned from projects in different top-level groups. +- Instance-wide: Runners that are registered globally with specific tags (selection criteria) +- Group runners: Runners that execute jobs from a given top-level Group or Projects in that Group +- Project runners: Runners that execute jobs from one Projects or many Projects: some runners might + have Projects assigned from Projects in different top-level Groups. -This alongside with existing data structure where `ci_runners` is a table describing -all types of runners poses a challenge how the `ci_runners` should be managed in a Cells environment. +This, alongside with the existing data structure where `ci_runners` is a table describing all types of runners, poses a challenge as to how the `ci_runners` should be managed in a Cells environment. ## 2. Data flow -GitLab Runners use a set of globally scoped endpoints to: +GitLab runners use a set of globally scoped endpoints to: -- registration of a new runner via registration token `https://gitlab.com/api/v4/runners` +- Register a new runner via registration token `https://gitlab.com/api/v4/runners` ([subject for removal](../runner_tokens/index.md)) (`registration token`) -- creation of a new runner in the context of a user `https://gitlab.com/api/v4/user/runners` (`runner token`) -- requests jobs via an authenticated `https://gitlab.com/api/v4/jobs/request` endpoint (`runner token`) -- upload job status via `https://gitlab.com/api/v4/jobs/:job_id` (`build token`) -- upload trace via `https://gitlab.com/api/v4/jobs/:job_id/trace` (`build token`) -- download and upload artifacts via `https://gitlab.com/api/v4/jobs/:job_id/artifacts` (`build token`) +- Create a new runner in the context of a user `https://gitlab.com/api/v4/user/runners` (`runner token`) +- Request jobs via an authenticated `https://gitlab.com/api/v4/jobs/request` endpoint (`runner token`) +- Upload job status via `https://gitlab.com/api/v4/jobs/:job_id` (`build token`) +- Upload trace via `https://gitlab.com/api/v4/jobs/:job_id/trace` (`build token`) +- Download and upload artifacts via `https://gitlab.com/api/v4/jobs/:job_id/artifacts` (`build token`) Currently three types of authentication tokens are used: -- runner registration token ([subject for removal](../runner_tokens/index.md)) -- runner token representing an registered runner in a system with specific configuration (`tags`, `locked`, etc.) -- build token representing an ephemeral token giving a limited access to updating a specific - job, uploading artifacts, downloading dependent artifacts, downloading and uploading - container registry images +- Runner registration token ([subject for removal](../runner_tokens/index.md)) +- Runner token representing a registered runner in a system with specific configuration (`tags`, `locked`, etc.) +- Build token representing an ephemeral token giving limited access to updating a specific job, uploading artifacts, downloading dependent artifacts, downloading and uploading container registry images -Each of those endpoints do receive an authentication token via header (`JOB-TOKEN` for `/trace`) -or body parameter (`token` all other endpoints). +Each of those endpoints receive an authentication token via header (`JOB-TOKEN` for `/trace`) or body parameter (`token` all other endpoints). -Since the CI pipeline would be created in a context of a specific Cell it would be required -that pick of a build would have to be processed by that particular Cell. This requires -that build picking depending on a solution would have to be either: +Since the CI pipeline would be created in the context of a specific Cell, it would be required that pick of a build would have to be processed by that particular Cell. +This requires that build picking depending on a solution would have to be either: -- routed to correct Cell for a first time -- be made to be two phase: request build from global pool, claim build on a specific Cell using a Cell specific URL +- Routed to the correct Cell for the first time +- Be two-phased: Request build from global pool, claim build on a specific Cell using a Cell specific URL ## 3. Proposal -This section describes various proposals. Reader should consider that those -proposals do describe solutions for different problems. Many or some aspects -of those proposals might be the solution to the stated problem. - ### 3.1. Authentication tokens -Even though the paths for CI Runners are not routable they can be made routable with -those two possible solutions: +Even though the paths for CI runners are not routable, they can be made routable with these two possible solutions: - The `https://gitlab.com/api/v4/jobs/request` uses a long polling mechanism with - a ticketing mechanism (based on `X-GitLab-Last-Update` header). Runner when first - starts sends a request to GitLab to which GitLab responds with either a build to pick + a ticketing mechanism (based on `X-GitLab-Last-Update` header). When the runner first + starts, it sends a request to GitLab to which GitLab responds with either a build to pick by runner. This value is completely controlled by GitLab. This allows GitLab - to use JWT or any other means to encode `cell` identifier that could be easily + to use JWT or any other means to encode a `cell` identifier that could be easily decodable by Router. -- The majority of communication (in terms of volume) is using `build token` making it - the easiest target to change since GitLab is sole owner of the token that Runner later - uses for specific job. There were prior discussions about not storing `build token` - but rather using `JWT` token with defined scopes. Such token could encode the `cell` - to which router could easily route all requests. +- The majority of communication (in terms of volume) is using `build token`, making it + the easiest target to change since GitLab is the sole owner of the token that the runner later + uses for a specific job. There were prior discussions about not storing the `build token` + but rather using a `JWT` token with defined scopes. Such a token could encode the `cell` + to which the Router could route all requests. ### 3.2. Request body -- The most of used endpoints pass authentication token in request body. It might be desired - to use HTTP Headers as an easier way to access this information by Router without +- The most used endpoints pass the authentication token in the request body. It might be desired + to use HTTP headers as an easier way to access this information by Router without a need to proxy requests. -### 3.3. Instance-wide are Cell local +### 3.3. Instance-wide are Cell-local We can pick a design where all runners are always registered and local to a given Cell: -- Each Cell has it's own set of instance-wide runners that are updated at it's own pace -- The project runners can only be linked to projects from the same organization - creating strong isolation. +- Each Cell has its own set of instance-wide runners that are updated at its own pace +- The Project runners can only be linked to Projects from the same Organization, creating strong isolation. - In this model the `ci_runners` table is local to the Cell. -- In this model we would require the above endpoints to be scoped to a Cell in some way - or made routable. It might be via prefixing them, adding additional Cell parameter, - or providing much more robust way to decode runner token and match it to Cell. -- If routable token is used, we could move away from cryptographic random stored in - database to rather prefer to use JWT tokens that would encode -- The Admin Area showing registered Runners would have to be scoped to a Cell - -This model might be desired since it provides strong isolation guarantees. -This model does significantly increase maintenance overhead since each Cell is managed -separately. +- In this model we would require the above endpoints to be scoped to a Cell in some way, or be made routable. It might be via prefixing them, adding additional Cell parameters, or providing much more robust ways to decode runner tokens and match it to a Cell. +- If a routable token is used, we could move away from cryptographic random stored in database to rather prefer to use JWT tokens. +- The Admin Area showing registered runners would have to be scoped to a Cell. -This model may require adjustments to runner tags feature so that projects have consistent runner experience across cells. +This model might be desired because it provides strong isolation guarantees. +This model does significantly increase maintenance overhead because each Cell is managed separately. +This model may require adjustments to the runner tags feature so that Projects have a consistent runner experience across Cells. ### 3.4. Instance-wide are cluster-wide -Contrary to proposal where all runners are Cell local, we can consider that runners +Contrary to the proposal where all runners are Cell-local, we can consider that runners are global, or just instance-wide runners are global. -However, this requires significant overhaul of system and to change the following aspects: +However, this requires significant overhaul of the system and we would have to change the following aspects: -- `ci_runners` table would likely have to be split decomposed into `ci_instance_runners`, ... -- all interfaces would have to be adopted to use correct table -- build queuing would have to be reworked to be two phase where each Cell would know of all pending - and running builds, but the actual claim of a build would happen against a Cell containing data -- likely `ci_pending_builds` and `ci_running_builds` would have to be made `cluster-wide` tables - increasing likelihood of creating hotspots in a system related to CI queueing +- The `ci_runners` table would likely have to be decomposed into `ci_instance_runners`, ... +- All interfaces would have to be adopted to use the correct table. +- Build queuing would have to be reworked to be two-phased where each Cell would know of all pending and running builds, but the actual claim of a build would happen against a Cell containing data. +- It is likely that `ci_pending_builds` and `ci_running_builds` would have to be made `cluster-wide` tables, increasing the likelihood of creating hotspots in a system related to CI queueing. -This model makes it complex to implement from engineering side. Does make some data being shared -between Cells. Creates hotspots / scalability issues in a system (ex. during abuse) that -might impact experience of organizations on other Cells. +This model is complex to implement from an engineering perspective. +Some data are shared between Cells. +It creates hotspots/scalability issues in a system that might impact the experience of Organizations on other Cells, for instance during abuse. ### 3.5. GitLab CI Daemon -Another potential solution to explore is to have a dedicated service responsible for builds queueing -owning it's database and working in a model of either sharded or celled service. There were prior -discussions about [CI/CD Daemon](https://gitlab.com/gitlab-org/gitlab/-/issues/19435). +Another potential solution to explore is to have a dedicated service responsible for builds queueing, owning its database and working in a model of either sharded or Cell-ed service. +There were prior discussions about [CI/CD Daemon](https://gitlab.com/gitlab-org/gitlab/-/issues/19435). -If the service would be sharded: +If the service is sharded: -- depending on a model if runners are cluster-wide or cell-local this service would have to fetch - data from all Cells -- if the sharded service would be used we could adapt a model of either sharing database containing - `ci_pending_builds/ci_running_builds` with the service -- if the sharded service would be used we could consider a push model where each Cell pushes to CI/CD Daemon - builds that should be picked by Runner -- the sharded service would be aware which Cell is responsible for processing the given build and could - route processing requests to designated Cell +- Depending on the model, if runners are cluster-wide or Cell-local, this service would have to fetch data from all Cells. +- If the sharded service is used we could adapt a model of sharing a database containing `ci_pending_builds/ci_running_builds` with the service. +- If the sharded service is used we could consider a push model where each Cell pushes to CI/CD Daemon builds that should be picked by runner. +- The sharded service would be aware which Cell is responsible for processing the given build and could route processing requests to the designated Cell. -If the service would be celled: +If the service is Cell-ed: -- all expectations of routable endpoints are still valid +- All expectations of routable endpoints are still valid. -In general usage of CI Daemon does not help significantly with the stated problem. However, this offers -a few upsides related to more efficient processing and decoupling model: push model and it opens a way -to offer stateful communication with GitLab Runners (ex. gRPC or Websockets). +In general usage of CI Daemon does not help significantly with the stated problem. +However, this offers a few upsides related to more efficient processing and decoupling model: push model and it opens a way to offer stateful communication with GitLab runners (ex. gRPC or Websockets). ## 4. Evaluation -Considering all solutions it appears that solution giving the most promise is: +Considering all options it appears that the most promising solution is to: -- use "instance-wide are Cell local" -- refine endpoints to have routable identities (either via specific paths, or better tokens) +- Use [Instance-wide are Cell-local](#33-instance-wide-are-cell-local) +- Refine endpoints to have routable identities (either via specific paths, or better tokens) -Other potential upsides is to get rid of `ci_builds.token` and rather use a `JWT token` -that can much better and easier encode wider set of scopes allowed by CI runner. +Another potential upside is to get rid of `ci_builds.token` and rather use a `JWT token` that can much better and easier encode a wider set of scopes allowed by CI runner. ## 4.1. Pros diff --git a/doc/architecture/blueprints/cells/cells-feature-container-registry.md b/doc/architecture/blueprints/cells/cells-feature-container-registry.md index a5761808941..25af65a8700 100644 --- a/doc/architecture/blueprints/cells/cells-feature-container-registry.md +++ b/doc/architecture/blueprints/cells/cells-feature-container-registry.md @@ -15,46 +15,37 @@ we can document the reasons for not choosing this approach. # Cells: Container Registry -GitLab Container Registry is a feature allowing to store Docker Container Images -in GitLab. You can read about GitLab integration [here](../../../user/packages/container_registry/index.md). +GitLab [Container Registry](../../../user/packages/container_registry/index.md) is a feature allowing to store Docker container images in GitLab. ## 1. Definition -GitLab Container Registry is a complex service requiring usage of PostgreSQL, Redis -and Object Storage dependencies. Right now there's undergoing work to introduce -[Container Registry Metadata](../container_registry_metadata_database/index.md) -to optimize data storage and image retention policies of Container Registry. +GitLab Container Registry is a complex service requiring usage of PostgreSQL, Redis and Object Storage dependencies. +Right now there's undergoing work to introduce [Container Registry Metadata](../container_registry_metadata_database/index.md) to optimize data storage and image retention policies of Container Registry. -GitLab Container Registry is serving as a container for stored data, -but on it's own does not authenticate `docker login`. The `docker login` -is executed with user credentials (can be `personal access token`) -or CI build credentials (ephemeral `ci_builds.token`). +GitLab Container Registry is serving as a container for stored data, but on its own does not authenticate `docker login`. +The `docker login` is executed with user credentials (can be `personal access token`) or CI build credentials (ephemeral `ci_builds.token`). -Container Registry uses data deduplication. It means that the same blob -(image layer) that is shared between many projects is stored only once. +Container Registry uses data deduplication. +It means that the same blob (image layer) that is shared between many Projects is stored only once. Each layer is hashed by `sha256`. -The `docker login` does request JWT time-limited authentication token that -is signed by GitLab, but validated by Container Registry service. The JWT -token does store all authorized scopes (`container repository images`) -and operation types (`push` or `pull`). A single JWT authentication token -can be have many authorized scopes. This allows container registry and client -to mount existing blobs from another scopes. GitLab responds only with -authorized scopes. Then it is up to GitLab Container Registry to validate -if the given operation can be performed. +The `docker login` does request a JWT time-limited authentication token that is signed by GitLab, but validated by Container Registry service. +The JWT token does store all authorized scopes (`container repository images`) and operation types (`push` or `pull`). +A single JWT authentication token can have many authorized scopes. +This allows Container Registry and client to mount existing blobs from other scopes. +GitLab responds only with authorized scopes. +Then it is up to GitLab Container Registry to validate if the given operation can be performed. -The GitLab.com pages are always scoped to project. Each project can have many -container registry images attached. +The GitLab.com pages are always scoped to a Project. +Each Project can have many container registry images attached. -Currently in case of GitLab.com the actual registry service is served -via `https://registry.gitlab.com`. +Currently, on GitLab.com the actual registry service is served via `https://registry.gitlab.com`. The main identifiable problems are: -- the authentication request (`https://gitlab.com/jwt/auth`) that is processed by GitLab.com -- the `https://registry.gitlab.com` that is run by external service and uses it's own data store -- the data deduplication, the Cells architecture with registry run in a Cell would reduce - efficiency of data storage +- The authentication request (`https://gitlab.com/jwt/auth`) that is processed by GitLab.com. +- The `https://registry.gitlab.com` that is run by an external service and uses its own data store. +- Data deduplication. The Cells architecture with registry run in a Cell would reduce efficiency of data storage. ## 2. Data flow @@ -99,33 +90,24 @@ curl \ ### 3.1. Shard Container Registry separately to Cells architecture -Due to it's architecture it extensive architecture and in general highly scalable -horizontal architecture it should be evaluated if the GitLab Container Registry -should be run not in Cell, but in a Cluster and be scaled independently. - +Due to its extensive and in general highly scalable horizontal architecture it should be evaluated if the GitLab Container Registry should be run not in Cell, but in a Cluster and be scaled independently. This might be easier, but would definitely not offer the same amount of data isolation. ### 3.2. Run Container Registry within a Cell -It appears that except `/jwt/auth` which would likely have to be processed by Router -(to decode `scope`) the container registry could be run as a local service of a Cell. - -The actual data at least in case of GitLab.com is not forwarded via registry, -but rather served directly from Object Storage / CDN. +It appears that except `/jwt/auth` which would likely have to be processed by Router (to decode `scope`) the Container Registry could be run as a local service of a Cell. +The actual data at least in case of GitLab.com is not forwarded via registry, but rather served directly from Object Storage / CDN. Its design encodes container repository image in a URL that is easily routable. -It appears that we could re-use the same stateless Router service in front of Container Registry -to serve manifests and blobs redirect. +It appears that we could re-use the same stateless Router service in front of Container Registry to serve manifests and blobs redirect. -The only downside is increased complexity of managing standalone registry for each Cell, -but this might be desired approach. +The only downside is increased complexity of managing standalone registry for each Cell, but this might be desired approach. ## 4. Evaluation -There do not seem any theoretical problems with running GitLab Container Registry in a Cell. -Service seems that can be easily made routable to work well. - -The practical complexities are around managing complex service from infrastructure side. +There do not seem to be any theoretical problems with running GitLab Container Registry in a Cell. +It seems that the service can be easily made routable to work well. +The practical complexities are around managing a complex service from an infrastructure side. ## 4.1. Pros diff --git a/doc/architecture/blueprints/cells/cells-feature-contributions-forks.md b/doc/architecture/blueprints/cells/cells-feature-contributions-forks.md index 8a67383c5e4..8e144386908 100644 --- a/doc/architecture/blueprints/cells/cells-feature-contributions-forks.md +++ b/doc/architecture/blueprints/cells/cells-feature-contributions-forks.md @@ -15,37 +15,33 @@ we can document the reasons for not choosing this approach. # Cells: Contributions: Forks -[Forking workflow](../../../user/project/repository/forking_workflow.md) allows users -to copy existing project sources into their own namespace of choice (personal or group). +The [Forking workflow](../../../user/project/repository/forking_workflow.md) allows users to copy existing Project sources into their own namespace of choice (Personal or Group). ## 1. Definition -[Forking workflow](../../../user/project/repository/forking_workflow.md) is common workflow -with various usage patterns: +The [Forking workflow](../../../user/project/repository/forking_workflow.md) is a common workflow with various usage patterns: -- allows users to contribute back to upstream project -- persist repositories into their personal namespace -- copy to make changes and release as modified project +- It allows users to contribute back to upstream Project. +- It persists repositories into their Personal Namespace. +- Users can copy to make changes and release as modified Project. -Forks allow users not having write access to parent project to make changes. The forking workflow -is especially important for the Open Source community which is able to contribute back -to public projects. However, it is equally important in some companies which prefer the strong split -of responsibilities and tighter access control. The access to project is restricted -to designated list of developers. +Forks allow users not having write access to a parent Project to make changes. +The forking workflow is especially important for the open source community to contribute back to public Projects. +However, it is equally important in some companies that prefer a strong split of responsibilities and tighter access control. +The access to a Project is restricted to a designated list of developers. Forks enable: -- tighter control of who can modify the upstream project -- split of the responsibilities: parent project might use CI configuration connecting to production systems -- run CI pipelines in context of fork in much more restrictive environment -- consider all forks to be unveted which reduces risks of leaking secrets, or any other information - tied with the project +- Tighter control of who can modify the upstream Project. +- Split of responsibilities: Parent Project might use CI configuration connecting to production systems. +- To run CI pipelines in the context of a fork in a much more restrictive environment. +- To consider all forks to be unvetted which reduces risks of leaking secrets, or any other information tied to the Project. -The forking model is problematic in Cells architecture for following reasons: +The forking model is problematic in a Cells architecture for the following reasons: -- Forks are clones of existing repositories, forks could be created across different organizations, Cells and Gitaly shards. -- User can create merge request and contribute back to upstream project, this upstream project might in a different organization and Cell. -- The merge request CI pipeline is to executed in a context of source project, but presented in a context of target project. +- Forks are clones of existing repositories. Forks could be created across different Organizations, Cells and Gitaly shards. +- Users can create merge requests and contribute back to an upstream Project. This upstream Project might in a different Organization and Cell. +- The merge request CI pipeline is executed in the context of the source Project, but presented in the context of the target Project. ## 2. Data flow @@ -53,66 +49,55 @@ The forking model is problematic in Cells architecture for following reasons: ### 3.1. Intra-Cluster forks -This proposal makes us to implement forks as a intra-ClusterCell forks where communication is done via API -between all trusted Cells of a cluster: - -- Forks when created, they are created always in context of user choice of group. -- Forks are isolated from Organization. -- Organization or group owner could disable forking across organizations or forking in general. -- When a Merge Request is created it is created in context of target project, referencing - external project on another Cell. -- To target project the merge reference is transfered that is used for presenting information - in context of target project. -- CI pipeline is fetched in context of source project as it-is today, the result is fetched into - Merge Request of target project. -- The Cell holding target project internally uses GraphQL to fetch status of source project - and include in context of the information for merge request. +This proposal implements forks as intra-Cluster forks where communication is done via API between all trusted Cells of a cluster: + +- Forks are created always in the context of a user's choice of Group. +- Forks are isolated from the Organization. +- Organization or Group owner could disable forking across Organizations, or forking in general. +- A merge request is created in the context of the target Project, referencing the external Project on another Cell. +- To target Project the merge reference is transferred that is used for presenting information in context of the target Project. +- CI pipeline is fetched in the context of the source Project as it is today, the result is fetched into the merge request of the target Project. +- The Cell holding the target Project internally uses GraphQL to fetch the status of the source Project and includes in context of the information for merge request. Upsides: -- All existing forks continue to work as-is, as they are treated as intra-Cluster forks. +- All existing forks continue to work as they are, as they are treated as intra-Cluster forks. Downsides: -- The purpose of Organizations is to provide strong isolation between organizations - allowing to fork across does break security boundaries. -- However, this is no different to ability of users today to clone repository to local computer - and push it to any repository of choice. -- Access control of source project can be lower than those of target project. System today - requires that in order to contribute back the access level needs to be the same for fork and upstream. - -### 3.2. Forks are created in a personal namespace of the current organization - -Instead of creating projects across organizations, the forks are created in a user personal namespace -tied with the organization. Example: - -- Each user that is part of organization receives their personal namespace. For example for `GitLab Inc.` - it could be `gitlab.com/organization/gitlab-inc/@ayufan`. -- The user has to fork into it's own personal namespace of the organization. -- The user has that many personal namespaces as many organizations it belongs to. -- The personal namespace behaves similar to currently offered personal namespace. -- The user can manage and create projects within a personal namespace. -- The organization can prevent or disable usage of personal namespaces disallowing forks. -- All current forks are migrated into personal namespace of user in Organization. -- All forks are part of to the organization. -- The forks are not federated features. -- The personal namespace and forked project do not share configuration with parent project. - -### 3.3. Forks are created as internal projects under current project - -Instead of creating projects across organizations, the forks are attachments to existing projects. -Each user forking a project receives their unique project. Example: - -- For project: `gitlab.com/gitlab-org/gitlab`, forks would be created in `gitlab.com/gitlab-org/gitlab/@kamil-gitlab`. -- Forks are created in a context of current organization, they do not cross organization boundaries - and are managed by the organization. +- The purpose of Organizations is to provide strong isolation between Organizations. Allowing to fork across does break security boundaries. +- However, this is no different to the ability of users today to clone a repository to a local computer and push it to any repository of choice. +- Access control of source Project can be lower than those of target Project. Today, the system requires that in order to contribute back, the access level needs to be the same for fork and upstream. + +### 3.2. Forks are created in a Personal Namespace of the current Organization + +Instead of creating Projects across Organizations, forks are created in a user's Personal Namespace tied to the Organization. Example: + +- Each user that is part of an Organization receives their Personal Namespace. For example for `GitLab Inc.` it could be `gitlab.com/organization/gitlab-inc/@ayufan`. +- The user has to fork into their own Personal Namespace of the Organization. +- The user has as many Personal Namespaces as Organizations they belongs to. +- The Personal Namespace behaves similar to the currently offered Personal Namespace. +- The user can manage and create Projects within a Personal Namespace. +- The Organization can prevent or disable usage of Personal Namespaces, disallowing forks. +- All current forks are migrated into the Personal Namespace of user in an Organization. +- All forks are part of the Organization. +- Forks are not federated features. +- The Personal Namespace and forked Project do not share configuration with the parent Project. + +### 3.3. Forks are created as internal Projects under current Projects + +Instead of creating Projects across Organizations, forks are attachments to existing Projects. +Each user forking a Project receives their unique Project. Example: + +- For Project: `gitlab.com/gitlab-org/gitlab`, forks would be created in `gitlab.com/gitlab-org/gitlab/@kamil-gitlab`. +- Forks are created in the context of the current Organization, they do not cross Organization boundaries and are managed by the Organization. - Tied to the user (or any other user-provided name of the fork). -- The forks are not federated features. +- Forks are not federated features. Downsides: -- Does not answer how to handle and migrate all exisiting forks. -- Might share current group / project settings - breaking some security boundaries. +- Does not answer how to handle and migrate all existing forks. +- Might share current Group/Project settings, which could be breaking some security boundaries. ## 4. Evaluation diff --git a/doc/architecture/blueprints/cells/cells-feature-data-migration.md b/doc/architecture/blueprints/cells/cells-feature-data-migration.md index ef0865b4081..9ff661ddf68 100644 --- a/doc/architecture/blueprints/cells/cells-feature-data-migration.md +++ b/doc/architecture/blueprints/cells/cells-feature-data-migration.md @@ -6,15 +6,6 @@ description: 'Cells: Data migration' <!-- vale gitlab.FutureTense = NO --> -DISCLAIMER: -This page may contain information related to upcoming products, features and -functionality. It is important to note that the information presented is for -informational purposes only, so please do not rely on the information for -purchasing or planning purposes. Just like with all projects, the items -mentioned on the page are subject to change or delay, and the development, -release, and timing of any products, features, or functionality remain at the -sole discretion of GitLab Inc. - This document is a work-in-progress and represents a very early state of the Cells design. Significant aspects are not documented, though we expect to add them in the future. This is one possible architecture for Cells, and we intend to @@ -24,26 +15,18 @@ we can document the reasons for not choosing this approach. # Cells: Data migration -It is essential for Cells architecture to provide a way to migrate data out of big Cells -into smaller ones. This describes various approaches to provide this type of split. - -We also need to handle for cases where data is already violating the expected -isolation constraints of Cells (ie. references cannot span multiple -organizations). We know that existing features like linked issues allowed users -to link issues across any projects regardless of their hierarchy. There are many -similar features. All of this data will need to be migrated in some way before -it can be split across different cells. This may mean some data needs to be -deleted, or the feature changed and modelled slightly differently before we can -properly split or migrate the organizations between cells. - -Having schema deviations across different Cells, which is a necessary -consequence of different databases, will also impact our ability to migrate -data between cells. Different schemas impact our ability to reliably replicate -data across cells and especially impact our ability to validate that the data is -correctly replicated. It might force us to only be able to move data between -cells when the schemas are all in sync (slowing down deployments and the -rebalancing process) or possibly only migrate from newer to older schemas which -would be complex. +It is essential for a Cells architecture to provide a way to migrate data out of big Cells into smaller ones. +This document describes various approaches to provide this type of split. + +We also need to handle cases where data is already violating the expected isolation constraints of Cells, for example references cannot span multiple Organizations. +We know that existing features like linked issues allowed users to link issues across any Projects regardless of their hierarchy. +There are many similar features. +All of this data will need to be migrated in some way before it can be split across different Cells. +This may mean some data needs to be deleted, or the feature needs to be changed and modelled slightly differently before we can properly split or migrate Organizations between Cells. + +Having schema deviations across different Cells, which is a necessary consequence of different databases, will also impact our ability to migrate data between Cells. +Different schemas impact our ability to reliably replicate data across Cells and especially impact our ability to validate that the data is correctly replicated. +It might force us to only be able to move data between Cells when the schemas are all in sync (slowing down deployments and the rebalancing process) or possibly only migrate from newer to older schemas which would be complex. ## 1. Definition @@ -53,34 +36,27 @@ would be complex. ### 3.1. Split large Cells -A single Cell can only be divided into many Cells. This is based on principle -that it is easier to create exact clone of an existing Cell in many replicas -out of which some will be made authoritative once migrated. Keeping those -replicas up-to date with Cell 0 is also much easier due to pre-existing -replication solutions that can replicate the whole systems: Geo, PostgreSQL -physical replication, etc. +A single Cell can only be divided into many Cells. +This is based on the principle that it is easier to create an exact clone of an existing Cell in many replicas out of which some will be made authoritative once migrated. +Keeping those replicas up-to-date with Cell 0 is also much easier due to pre-existing replication solutions that can replicate the whole systems: Geo, PostgreSQL physical replication, etc. -1. All data of an organization needs to not be divided across many Cells. +1. All data of an Organization needs to not be divided across many Cells. 1. Split should be doable online. 1. New Cells cannot contain pre-existing data. 1. N Cells contain exact replica of Cell 0. 1. The data of Cell 0 is live replicated to as many Cells it needs to be split. -1. Once consensus is achieved between Cell 0 and N-Cells the organizations to be migrated away - are marked as read-only cluster-wide. -1. The `routes` is updated on for all organizations to be split to indicate an authoritative - Cell holding the most recent data, like `gitlab-org` on `cell-100`. -1. The data for `gitlab-org` on Cell 0, and on other non-authoritative N-Cells are dormant - and will be removed in the future. -1. All accesses to `gitlab-org` on a given Cell are validated about `cell_id` of `routes` - to ensure that given Cell is authoritative to handle the data. +1. Once consensus is achieved between Cell 0 and N-Cells, the Organizations to be migrated away are marked as read-only cluster-wide. +1. The `routes` is updated on for all Organizations to be split to indicate an authoritative Cell holding the most recent data, like `gitlab-org` on `cell-100`. +1. The data for `gitlab-org` on Cell 0, and on other non-authoritative N-Cells are dormant and will be removed in the future. +1. All accesses to `gitlab-org` on a given Cell are validated about `cell_id` of `routes` to ensure that given Cell is authoritative to handle the data. #### More challenges of this proposal 1. There is no streaming replication capability for Elasticsearch, but you could snapshot the whole Elasticsearch index and recreate, but this takes hours. - It could be handled by pausing Elasticsearch indexing on the initial cell during + It could be handled by pausing Elasticsearch indexing on the initial Cell during the migration as indexing downtime is not a big issue, but this still needs - to be coordinated with the migration process + to be coordinated with the migration process. 1. Syncing Redis, Gitaly, CI Postgres, Main Postgres, registry Postgres, other new data stores snapshots in an online system would likely lead to gaps without a long downtime. You need to choose a sync point and at the sync @@ -88,39 +64,31 @@ physical replication, etc. there are to migrate at the same time the longer the write downtime for the failover. We would also need to find a reliable place in the application to actually block updates to all these systems with a high degree of - confidence. In the past we've only been confident by shutting down all rails - services because any rails process could write directly to any of these at + confidence. In the past we've only been confident by shutting down all Rails + services because any Rails process could write directly to any of these at any time due to async workloads or other surprising code paths. 1. How to efficiently delete all the orphaned data. Locating all `ci_builds` - associated with half the organizations would be very expensive if we have to + associated with half the Organizations would be very expensive if we have to do joins. We haven't yet determined if we'd want to store an `organization_id` column on every table, but this is the kind of thing it would be helpful for. -### 3.2. Migrate organization from an existing Cell - -This is different to split, as we intend to perform logical and selective replication -of data belonging to a single organization. +### 3.2. Migrate Organization from an existing Cell -Today this type of selective replication is only implemented by Gitaly where we can migrate -Git repository from a single Gitaly node to another with minimal downtime. +This is different to split, as we intend to perform logical and selective replication of data belonging to a single Organization. +Today this type of selective replication is only implemented by Gitaly where we can migrate Git repository from a single Gitaly node to another with minimal downtime. -In this model we would require identifying all resources belonging to a given organization: -database rows, object storage files, Git repositories, etc. and selectively copy them over -to another (likely) existing Cell importing data into it. Ideally ensuring that we can -perform logical replication live of all changed data, but change similarly to split -which Cell is authoritative for this organization. +In this model we would require identifying all resources belonging to a given Organization: database rows, object storage files, Git repositories, etc. and selectively copy them over to another (likely) existing Cell importing data into it. +Ideally ensuring that we can perform logical replication live of all changed data, but change similarly to split which Cell is authoritative for this Organization. -1. It is hard to identify all resources belonging to organization. -1. It requires either downtime for organization or a robust system to identify - live changes made. -1. It likely will require a full database structure analysis (more robust than project import/export) - to perform selective PostgreSQL logical replication. +1. It is hard to identify all resources belonging to an Organization. +1. It requires either downtime for the Organization or a robust system to identify live changes made. +1. It likely will require a full database structure analysis (more robust than Project import/export) to perform selective PostgreSQL logical replication. #### More challenges of this proposal 1. Logical replication is still not performant enough to keep up with our scale. Even if we could use logical replication we still don't have an - efficient way to filter data related to a single organization without + efficient way to filter data related to a single Organization without joining all the way to the `organizations` table which will slow down logical replication dramatically. diff --git a/doc/architecture/blueprints/cells/cells-feature-database-sequences.md b/doc/architecture/blueprints/cells/cells-feature-database-sequences.md index d94dc3be864..2aeaaed7d64 100644 --- a/doc/architecture/blueprints/cells/cells-feature-database-sequences.md +++ b/doc/architecture/blueprints/cells/cells-feature-database-sequences.md @@ -6,15 +6,6 @@ description: 'Cells: Database Sequences' <!-- vale gitlab.FutureTense = NO --> -DISCLAIMER: -This page may contain information related to upcoming products, features and -functionality. It is important to note that the information presented is for -informational purposes only, so please do not rely on the information for -purchasing or planning purposes. Just like with all projects, the items -mentioned on the page are subject to change or delay, and the development, -release, and timing of any products, features, or functionality remain at the -sole discretion of GitLab Inc. - This document is a work-in-progress and represents a very early state of the Cells design. Significant aspects are not documented, though we expect to add them in the future. This is one possible architecture for Cells, and we intend to @@ -24,14 +15,10 @@ we can document the reasons for not choosing this approach. # Cells: Database Sequences -GitLab today ensures that every database row create has unique ID, allowing -to access Merge Request, CI Job or Project by a known global ID. - -Cells will use many distinct and not connected databases, each of them having -a separate IDs for most of entities. - -It might be desirable to retain globally unique IDs for all database rows -to allow migrating resources between Cells in the future. +GitLab today ensures that every database row create has a unique ID, allowing to access a merge request, CI Job or Project by a known global ID. +Cells will use many distinct and not connected databases, each of them having a separate ID for most entities. +At a minimum, any ID referenced between a Cell and the shared schema will need to be unique across the cluster to avoid ambiguous references. +Further to required global IDs, it might also be desirable to retain globally unique IDs for all database rows to allow migrating resources between Cells in the future. ## 1. Definition @@ -39,54 +26,46 @@ to allow migrating resources between Cells in the future. ## 3. Proposal -This are some preliminary ideas how we can retain unique IDs across the system. +These are some preliminary ideas how we can retain unique IDs across the system. ### 3.1. UUID -Instead of using incremental sequences use UUID (128 bit) that is stored in database. +Instead of using incremental sequences, use UUID (128 bit) that is stored in the database. -- This might break existing IDs and requires adding UUID column for all existing tables. +- This might break existing IDs and requires adding a UUID column for all existing tables. - This makes all indexes larger as it requires storing 128 bit instead of 32/64 bit in index. ### 3.2. Use Cell index encoded in ID -Since significant number of tables already use 64 bit ID numbers we could use MSB to encode -Cell ID effectively enabling +Because a significant number of tables already use 64 bit ID numbers we could use MSB to encode the Cell ID: -- This might limit amount of Cells that can be enabled in system, as we might decide to only - allocate 1024 possible Cell numbers. -- This might make IDs to be migratable between Cells, since even if entity from Cell 1 is migrated to Cell 100 - this ID would still be unique. -- If resources are migrated the ID itself will not be enough to decode Cell number and we would need - lookup table. +- This might limit the amount of Cells that can be enabled in a system, as we might decide to only allocate 1024 possible Cell numbers. +- This would make it possible to migrate IDs between Cells, because even if an entity from Cell 1 is migrated to Cell 100 this ID would still be unique. +- If resources are migrated the ID itself will not be enough to decode the Cell number and we would need a lookup table. - This requires updating all IDs to 32 bits. ### 3.3. Allocate sequence ranges from central place -Each Cell might receive its own range of the sequences as they are consumed from a centrally managed place. -Once Cell consumes all IDs assigned for a given table it would be replenished and a next range would be allocated. +Each Cell might receive its own range of sequences as they are consumed from a centrally managed place. +Once a Cell consumes all IDs assigned for a given table it would be replenished and a next range would be allocated. Ranges would be tracked to provide a faster lookup table if a random access pattern is required. -- This might make IDs to be migratable between Cells, since even if entity from Cell 1 is migrated to Cell 100 - this ID would still be unique. -- If resources are migrated the ID itself will not be enough to decode Cell number and we would need - much more robust lookup table as we could be breaking previously assigned sequence ranges. +- This might make IDs migratable between Cells, because even if an entity from Cell 1 is migrated to Cell 100 this ID would still be unique. +- If resources are migrated the ID itself will not be enough to decode the Cell number and we would need a much more robust lookup table as we could be breaking previously assigned sequence ranges. - This does not require updating all IDs to 64 bits. -- This adds some performance penalty to all `INSERT` statements in Postgres or at least from Rails as we need to check for the sequence number and potentially wait for our range to be refreshed from the ID server +- This adds some performance penalty to all `INSERT` statements in Postgres or at least from Rails as we need to check for the sequence number and potentially wait for our range to be refreshed from the ID server. - The available range will need to be stored and incremented in a centralized place so that concurrent transactions cannot possibly get the same value. ### 3.4. Define only some tables to require unique IDs -Maybe this is acceptable only for some tables to have a globally unique IDs. It could be projects, groups -and other top-level entities. All other tables like `merge_requests` would only offer Cell-local ID, -but when referenced outside it would rather use IID (an ID that is monotonic in context of a given resource, like project). +Maybe it is acceptable only for some tables to have a globally unique IDs. It could be Projects, Groups and other top-level entities. +All other tables like `merge_requests` would only offer a Cell-local ID, but when referenced outside it would rather use an IID (an ID that is monotonic in context of a given resource, like a Project). -- This makes the ID 10000 for `merge_requests` be present on all Cells, which might be sometimes confusing - as for uniqueness of the resource. -- This might make random access by ID (if ever needed) be impossible without using composite key, like: `project_id+merge_request_id`. -- This would require us to implement a transformation/generation of new ID if we need to migrate records to another cell. This can lead to very difficult migration processes when these IDs are also used as foreign keys for other records being migrated. -- If IDs need to change when moving between cells this means that any links to records by ID would no longer work even if those links included the `project_id`. -- If we plan to allow these ids to not be unique and change the unique constraint to be based on a composite key then we'd need to update all foreign key references to be based on the composite key +- This makes the ID 10000 for `merge_requests` be present on all Cells, which might be sometimes confusing regarding the uniqueness of the resource. +- This might make random access by ID (if ever needed) impossible without using a composite key, like: `project_id+merge_request_id`. +- This would require us to implement a transformation/generation of new ID if we need to migrate records to another Cell. This can lead to very difficult migration processes when these IDs are also used as foreign keys for other records being migrated. +- If IDs need to change when moving between Cells this means that any links to records by ID would no longer work even if those links included the `project_id`. +- If we plan to allow these IDs to not be unique and change the unique constraint to be based on a composite key then we'd need to update all foreign key references to be based on the composite key. ## 4. Evaluation diff --git a/doc/architecture/blueprints/cells/cells-feature-explore.md b/doc/architecture/blueprints/cells/cells-feature-explore.md new file mode 100644 index 00000000000..4eab99d63e7 --- /dev/null +++ b/doc/architecture/blueprints/cells/cells-feature-explore.md @@ -0,0 +1,71 @@ +--- +stage: enablement +group: Tenant Scale +description: 'Cells: Explore' +--- + +<!-- vale gitlab.FutureTense = NO --> + +This document is a work-in-progress and represents a very early state of the +Cells design. Significant aspects are not documented, though we expect to add +them in the future. This is one possible architecture for Cells, and we intend to +contrast this with alternatives before deciding which approach to implement. +This documentation will be kept even if we decide not to implement this so that +we can document the reasons for not choosing this approach. + +# Cells: Explore + +Explore may not play a critical role in GitLab as it functions today, but GitLab today is not isolated. It is the isolation that makes Explore or some viable replacement necessary. + +The existing Group and Project Explore will initially be scoped to an Organization. However, there is a need for a global Explore that spans across Organizations to support the discoverability of public Groups and Projects, in particular in the context of discovering open source Projects. See user feedback [here](https://gitlab.com/gitlab-org/gitlab/-/issues/21582#note_1458298192) and [here](https://gitlab.com/gitlab-org/gitlab/-/issues/418228#note_1470045468). + +## 1. Definition + +The Explore functionality helps users in discovering Groups and Projects. Unauthenticated Users are only able to explore public Groups and Projects, authenticated Users can see all the Groups and Projects that they have access to, including private and internal Groups and Projects. + +## 2. Data flow + +## 3. Proposal + +The Explore feature problem falls under the broader umbrella of solving inter-Cell communication. [This topic warrants deeper research](index.md#can-different-cells-communicate-with-each-other). + +Below are possible directions for further investigation. + +### 3.1. Read only table mirror + +- Create a `shared_projects` table in the shared cluster-wide database. +- The model for this table is read-only. No inserts/updates/deletes are allowed. +- The table is filled with data (or a subset of data) from the Projects Cell-local table. + - The write model Project (which is Cell-local) writes to the local database. We will primarily use this model for anything Cell-local. + - This data is synchronized with `shared_projects` via a background job any time something changes. + - The data in `shared_projects` is stored normalized, so that all the information necessary to display the Project Explore is there. +- The Project Explore (as of today) is part of an instance-wide functionality, since it's not namespaced to any organizations/groups. + - This section will read data using the read model for `shared_projects`. +- Once the user clicks on a Project, they are redirected to the Cell containing the Organization. + +Downsides: + +- Need to have an explicit pattern to access instance-wide data. This however may be useful for admin functionalities too. +- The Project Explore may not be as rich in features as it is today (various filtering options, role you have on that Project, etc.). +- Extra complexity in managing CQRS. + +### 3.2 Explore scoped to an Organization + +The Project Explore and Group Explore are scoped to an Organization. + +Downsides: + +- No global discoverability of Groups and Projects. + +## 4. Evaluation + +The existing Group and Project Explore will initially be scoped to an Organization. Considering the [current usage of the Explore feature](https://gitlab.com/gitlab-data/product-analytics/-/issues/1302#note_1491215521), we deem this acceptable. Since all existing Users, Groups and Projects will initially be part of the default Organization, Groups and Projects will remain explorable and accessible as they are today. Only once existing Groups and Projects are moved out of the default Organization into different Organizations will this become a noticeable problem. Solutions to mitigate this are discussed in [issue #418228](https://gitlab.com/gitlab-org/gitlab/-/issues/418228). Ultimately, Explore could be replaced with a better search experience altogether. + +## 4.1. Pros + +- Initially the lack of discoverability will not be a problem. +- Only around [1.5% of all exisiting Users are using the Explore functionality on a monthly basis](https://gitlab.com/gitlab-data/product-analytics/-/issues/1302#note_1491215521). + +## 4.2. Cons + +- The GitLab owned top-level Groups would be some of the first to be moved into their own Organization and thus be detached from the explorability of the default Organization. diff --git a/doc/architecture/blueprints/cells/cells-feature-git-access.md b/doc/architecture/blueprints/cells/cells-feature-git-access.md index 70b3f136904..611b4db5f43 100644 --- a/doc/architecture/blueprints/cells/cells-feature-git-access.md +++ b/doc/architecture/blueprints/cells/cells-feature-git-access.md @@ -15,35 +15,30 @@ we can document the reasons for not choosing this approach. # Cells: Git Access -This document describes impact of Cells architecture on all Git access (over HTTPS and SSH) -patterns providing explanation of how potentially those features should be changed -to work well with Cells. +This document describes impact of Cells architecture on all Git access (over HTTPS and SSH) patterns providing explanation of how potentially those features should be changed to work well with Cells. ## 1. Definition -Git access is done through out the application. It can be an operation performed by the system -(read Git repository) or by user (create a new file via Web IDE, `git clone` or `git push` via command line). +Git access is done throughout the application. +It can be an operation performed by the system (read Git repository) or by a user (create a new file via Web IDE, `git clone` or `git push` via command line). +The Cells architecture defines that all Git repositories will be local to the Cell, so no repository could be shared with another Cell. -The Cells architecture defines that all Git repositories will be local to the Cell, -so no repository could be shared with another Cell. - -The Cells architecture will require that any Git operation done can only be handled by a Cell holding -the data. It means that any operation either via Web interface, API, or GraphQL needs to be routed -to the correct Cell. It means that any `git clone` or `git push` operation can only be performed -in a context of a Cell. +The Cells architecture will require that any Git operation can only be handled by a Cell holding the data. +It means that any operation either via Web interface, API, or GraphQL needs to be routed to the correct Cell. +It means that any `git clone` or `git push` operation can only be performed in the context of a Cell. ## 2. Data flow -The are various operations performed today by the GitLab on a Git repository. This describes -the data flow how they behave today to better represent the impact. +The are various operations performed today by GitLab on a Git repository. +This describes the data flow how they behave today to better represent the impact. -It appears that Git access does require changes only to a few endpoints that are scoped to project. +It appears that Git access does require changes only to a few endpoints that are scoped to a Project. There appear to be different types of repositories: - Project: assigned to Group - Wiki: additional repository assigned to Project - Design: similar to Wiki, additional repository assigned to Project -- Snippet: creates a virtual project to hold repository, likely tied to the User +- Snippet: creates a virtual Project to hold repository, likely tied to the User ### 2.1. Git clone over HTTPS @@ -131,9 +126,8 @@ sequenceDiagram ## 3. Proposal -The Cells stateless router proposal requires that any ambiguous path (that is not routable) -will be made to be routable. It means that at least the following paths will have to be updated -do introduce a routable entity (project, group, or organization). +The Cells stateless router proposal requires that any ambiguous path (that is not routable) will be made routable. +It means that at least the following paths will have to be updated to introduce a routable entity (Project, Group, or Organization). Change: @@ -150,9 +144,7 @@ Where: ## 4. Evaluation Supporting Git repositories if a Cell can access only its own repositories does not appear to be complex. - -The one major complication is supporting snippets, but this likely falls in the same category as for the approach -to support user's personal namespaces. +The one major complication is supporting snippets, but this likely falls in the same category as for the approach to support a user's Personal Namespace. ## 4.1. Pros @@ -161,4 +153,4 @@ to support user's personal namespaces. ## 4.2. Cons 1. The sharing of repositories objects is limited to the given Cell and Gitaly node. -1. The across-Cells forks are likely impossible to be supported (discover: how this work today across different Gitaly node). +1. Cross-Cells forks are likely impossible to be supported (discover: How this works today across different Gitaly node). diff --git a/doc/architecture/blueprints/cells/cells-feature-global-search.md b/doc/architecture/blueprints/cells/cells-feature-global-search.md index c1e2b93bc2d..475db381ff5 100644 --- a/doc/architecture/blueprints/cells/cells-feature-global-search.md +++ b/doc/architecture/blueprints/cells/cells-feature-global-search.md @@ -6,15 +6,6 @@ description: 'Cells: Global search' <!-- vale gitlab.FutureTense = NO --> -DISCLAIMER: -This page may contain information related to upcoming products, features and -functionality. It is important to note that the information presented is for -informational purposes only, so please do not rely on the information for -purchasing or planning purposes. Just like with all projects, the items -mentioned on the page are subject to change or delay, and the development, -release, and timing of any products, features, or functionality remain at the -sole discretion of GitLab Inc. - This document is a work-in-progress and represents a very early state of the Cells design. Significant aspects are not documented, though we expect to add them in the future. This is one possible architecture for Cells, and we intend to @@ -24,12 +15,9 @@ we can document the reasons for not choosing this approach. # Cells: Global search -When we introduce multiple Cells we intend to isolate all services related to -those Cells. This will include Elasticsearch which means our current global -search functionality will not work. It may be possible to implement aggregated -search across all cells, but it is unlikely to be performant to do fan-out -searches across all cells especially once you start to do pagination which -requires setting the correct offset and page number for each search. +When we introduce multiple Cells we intend to isolate all services related to those Cells. +This will include Elasticsearch which means our current global search functionality will not work. +It may be possible to implement aggregated search across all Cells, but it is unlikely to be performant to do fan-out searches across all Cells especially once you start to do pagination which requires setting the correct offset and page number for each search. ## 1. Definition @@ -37,9 +25,8 @@ requires setting the correct offset and page number for each search. ## 3. Proposal -Likely first versions of Cells will simply not support global searches and then -we may later consider if building global searches to support popular use cases -is worthwhile. +Likely the first versions of Cells will not support global searches. +Later, we may consider if building global searches to support popular use cases is worthwhile. ## 4. Evaluation diff --git a/doc/architecture/blueprints/cells/cells-feature-graphql.md b/doc/architecture/blueprints/cells/cells-feature-graphql.md index d936a1b81ba..e8850dfbee3 100644 --- a/doc/architecture/blueprints/cells/cells-feature-graphql.md +++ b/doc/architecture/blueprints/cells/cells-feature-graphql.md @@ -6,15 +6,6 @@ description: 'Cells: GraphQL' <!-- vale gitlab.FutureTense = NO --> -DISCLAIMER: -This page may contain information related to upcoming products, features and -functionality. It is important to note that the information presented is for -informational purposes only, so please do not rely on the information for -purchasing or planning purposes. Just like with all projects, the items -mentioned on the page are subject to change or delay, and the development, -release, and timing of any products, features, or functionality remain at the -sole discretion of GitLab Inc. - This document is a work-in-progress and represents a very early state of the Cells design. Significant aspects are not documented, though we expect to add them in the future. This is one possible architecture for Cells, and we intend to @@ -25,9 +16,8 @@ we can document the reasons for not choosing this approach. # Cells: GraphQL GitLab extensively uses GraphQL to perform efficient data query operations. -GraphQL due to it's nature is not directly routable. The way how GitLab uses -it calls the `/api/graphql` endpoint, and only query or mutation of body request -might define where the data can be accessed. +GraphQL due to it's nature is not directly routable. +The way GitLab uses it calls the `/api/graphql` endpoint, and only the query or mutation of the body request might define where the data can be accessed. ## 1. Definition @@ -35,21 +25,19 @@ might define where the data can be accessed. ## 3. Proposal -There are at least two main ways to implement GraphQL in Cells architecture. +There are at least two main ways to implement GraphQL in a Cells architecture. ### 3.1. GraphQL routable by endpoint Change `/api/graphql` to `/api/organization/<organization>/graphql`. -- This breaks all existing usages of `/api/graphql` endpoint - since the API URI is changed. +- This breaks all existing usages of `/api/graphql` endpoint because the API URI is changed. ### 3.2. GraphQL routable by body As part of router parse GraphQL body to find a routable entity, like `project`. -- This still makes the GraphQL query be executed only in context of a given Cell - and not allowing the data to be merged. +- This still makes the GraphQL query be executed only in context of a given Cell and not allowing the data to be merged. ```json # Good example @@ -71,11 +59,9 @@ As part of router parse GraphQL body to find a routable entity, like `project`. ### 3.3. Merging GraphQL Proxy -Implement as part of router GraphQL Proxy which can parse body -and merge results from many Cells. +Implement as part of router GraphQL Proxy which can parse body and merge results from many Cells. -- This might make pagination hard to achieve, or we might assume that - we execute many queries of which results are merged across all Cells. +- This might make pagination hard to achieve, or we might assume that we execute many queries of which results are merged across all Cells. ```json { diff --git a/doc/architecture/blueprints/cells/cells-feature-organizations.md b/doc/architecture/blueprints/cells/cells-feature-organizations.md index 03178d9e6ce..f1527b40ef4 100644 --- a/doc/architecture/blueprints/cells/cells-feature-organizations.md +++ b/doc/architecture/blueprints/cells/cells-feature-organizations.md @@ -6,15 +6,6 @@ description: 'Cells: Organizations' <!-- vale gitlab.FutureTense = NO --> -DISCLAIMER: -This page may contain information related to upcoming products, features and -functionality. It is important to note that the information presented is for -informational purposes only, so please do not rely on the information for -purchasing or planning purposes. Just like with all projects, the items -mentioned on the page are subject to change or delay, and the development, -release, and timing of any products, features, or functionality remain at the -sole discretion of GitLab Inc. - This document is a work-in-progress and represents a very early state of the Cells design. Significant aspects are not documented, though we expect to add them in the future. This is one possible architecture for Cells, and we intend to @@ -24,36 +15,22 @@ we can document the reasons for not choosing this approach. # Cells: Organizations -One of the major designs of Cells architecture is strong isolation between Groups. -Organizations as described by this blueprint provides a way to have plausible UX -for joining together many Groups that are isolated from the rest of systems. +One of the major designs of a Cells architecture is strong isolation between Groups. +Organizations as described by the [Organization blueprint](../organization/index.md) provides a way to have plausible UX for joining together many Groups that are isolated from the rest of the system. ## 1. Definition -Cells do require that all groups and projects of a single organization can -only be stored on a single Cell since a Cell can only access data that it holds locally -and has very limited capabilities to read information from other Cells. - -Cells with Organizations do require strong isolation between organizations. - -It will have significant implications on various user-facing features, -like Todos, dropdowns allowing to select projects, references to other issues -or projects, or any other social functions present at GitLab. Today those functions -were able to reference anything in the whole system. With the introduction of -organizations such will be forbidden. - -This problem definition aims to answer effort and implications required to add -strong isolation between organizations to the system. Including features affected -and their data processing flow. The purpose is to ensure that our solution when -implemented consistently avoids data leakage between organizations residing on -a single Cell. +Cells do require that all Groups and Projects of a single Organization can only be stored on a single Cell because a Cell can only access data that it holds locally and has very limited capabilities to read information from other Cells. -## 2. Data flow +Cells with Organizations do require strong isolation between Organizations. -## 3. Proposal +It will have significant implications on various user-facing features, like Todos, dropdowns allowing to select Projects, references to other issues or Projects, or any other social functions present at GitLab. +Today those functions were able to reference anything in the whole system. +With the introduction of Organizations this will be forbidden. -## 4. Evaluation +This problem definition aims to answer effort and implications required to add strong isolation between Organizations to the system, including features affected and their data processing flow. +The purpose is to ensure that our solution when implemented consistently avoids data leakage between Organizations residing on a single Cell. -## 4.1. Pros +## 2. Proposal -## 4.2. Cons +See the [Organization blueprint](../organization/index.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-dashboard.md b/doc/architecture/blueprints/cells/cells-feature-personal-access-tokens.md index 135f69c6ed3..3aca9f1e116 100644 --- a/doc/architecture/blueprints/cells/cells-feature-dashboard.md +++ b/doc/architecture/blueprints/cells/cells-feature-personal-access-tokens.md @@ -1,7 +1,7 @@ --- stage: enablement group: Tenant Scale -description: 'Cells: Dashboard' +description: 'Cells: Personal Access Tokens' --- <!-- vale gitlab.FutureTense = NO --> @@ -13,12 +13,13 @@ contrast this with alternatives before deciding which approach to implement. This documentation will be kept even if we decide not to implement this so that we can document the reasons for not choosing this approach. -# Cells: Dashboard - -> TL;DR +# Cells: Personal Access Tokens ## 1. Definition +Personal Access Tokens associated with a User are a way for Users to interact with the API of GitLab to perform operations. +Personal Access Tokens today are scoped to the User, and can access all Groups that a User has access to. + ## 2. Data flow ## 3. Proposal diff --git a/doc/architecture/blueprints/cells/cells-feature-router-endpoints-classification.md b/doc/architecture/blueprints/cells/cells-feature-router-endpoints-classification.md index 7c2974ca258..d403d6ff963 100644 --- a/doc/architecture/blueprints/cells/cells-feature-router-endpoints-classification.md +++ b/doc/architecture/blueprints/cells/cells-feature-router-endpoints-classification.md @@ -6,15 +6,6 @@ description: 'Cells: Router Endpoints Classification' <!-- vale gitlab.FutureTense = NO --> -DISCLAIMER: -This page may contain information related to upcoming products, features and -functionality. It is important to note that the information presented is for -informational purposes only, so please do not rely on the information for -purchasing or planning purposes. Just like with all projects, the items -mentioned on the page are subject to change or delay, and the development, -release, and timing of any products, features, or functionality remain at the -sole discretion of GitLab Inc. - This document is a work-in-progress and represents a very early state of the Cells design. Significant aspects are not documented, though we expect to add them in the future. This is one possible architecture for Cells, and we intend to @@ -24,15 +15,11 @@ we can document the reasons for not choosing this approach. # Cells: Router Endpoints Classification -Classification of all endpoints is essential to properly route request -hitting load balancer of a GitLab installation to a Cell that can serve it. - -Each Cell should be able to decode each request and classify for which Cell -it belongs to. +Classification of all endpoints is essential to properly route requests hitting the load balancer of a GitLab installation to a Cell that can serve it. +Each Cell should be able to decode each request and classify which Cell it belongs to. -GitLab currently implements hundreds of endpoints. This document tries -to describe various techniques that can be implemented to allow the Rails -to provide this information efficiently. +GitLab currently implements hundreds of endpoints. +This document tries to describe various techniques that can be implemented to allow the Rails to provide this information efficiently. ## 1. Definition diff --git a/doc/architecture/blueprints/cells/cells-feature-schema-changes.md b/doc/architecture/blueprints/cells/cells-feature-schema-changes.md index d712b24a8a0..dd0f6c0705c 100644 --- a/doc/architecture/blueprints/cells/cells-feature-schema-changes.md +++ b/doc/architecture/blueprints/cells/cells-feature-schema-changes.md @@ -6,15 +6,6 @@ description: 'Cells: Schema changes' <!-- vale gitlab.FutureTense = NO --> -DISCLAIMER: -This page may contain information related to upcoming products, features and -functionality. It is important to note that the information presented is for -informational purposes only, so please do not rely on the information for -purchasing or planning purposes. Just like with all projects, the items -mentioned on the page are subject to change or delay, and the development, -release, and timing of any products, features, or functionality remain at the -sole discretion of GitLab Inc. - This document is a work-in-progress and represents a very early state of the Cells design. Significant aspects are not documented, though we expect to add them in the future. This is one possible architecture for Cells, and we intend to @@ -24,24 +15,15 @@ we can document the reasons for not choosing this approach. # Cells: Schema changes -When we introduce multiple Cells that own their own databases this will -complicate the process of making schema changes to Postgres and Elasticsearch. -Today we already need to be careful to make changes comply with our zero -downtime deployments. For example, -[when removing a column we need to make changes over 3 separate deployments](../../../development/database/avoiding_downtime_in_migrations.md#dropping-columns). -We have tooling like `post_migrate` that helps with these kinds of changes to -reduce the number of merge requests needed, but these will be complicated when -we are dealing with deploying multiple rails applications that will be at -different versions at any one time. This problem will be particularly tricky to -solve for shared databases like our plan to share the `users` related tables -among all Cells. - -A key benefit of Cells may be that it allows us to run different -customers on different versions of GitLab. We may choose to update our own cell -before all our customers giving us even more flexibility than our current -canary architecture. But doing this means that schema changes need to have even -more versions of backward compatibility support which could slow down -development as we need extra steps to make schema changes. +When we introduce multiple Cells that own their own databases this will complicate the process of making schema changes to Postgres and Elasticsearch. +Today we already need to be careful to make changes comply with our zero downtime deployments. +For example, [when removing a column we need to make changes over 3 separate deployments](../../../development/database/avoiding_downtime_in_migrations.md#dropping-columns). +We have tooling like `post_migrate` that helps with these kinds of changes to reduce the number of merge requests needed, but these will be complicated when we are dealing with deploying multiple Rails applications that will be at different versions at any one time. +This problem will be particularly tricky to solve for shared databases like our plan to share the `users` related tables among all Cells. + +A key benefit of Cells may be that it allows us to run different customers on different versions of GitLab. +We may choose to update our own Cell before all our customers giving us even more flexibility than our current canary architecture. +But doing this means that schema changes need to have even more versions of backward compatibility support which could slow down development as we need extra steps to make schema changes. ## 1. Definition diff --git a/doc/architecture/blueprints/cells/cells-feature-secrets.md b/doc/architecture/blueprints/cells/cells-feature-secrets.md index 50ccf926b4d..681c229711d 100644 --- a/doc/architecture/blueprints/cells/cells-feature-secrets.md +++ b/doc/architecture/blueprints/cells/cells-feature-secrets.md @@ -15,32 +15,26 @@ we can document the reasons for not choosing this approach. # Cells: Secrets -Where possible, each cell should have its own distinct set of secrets. -However, there will be some secrets that will be required to be the same for all -cells in the cluster +Where possible, each Cell should have its own distinct set of secrets. +However, there will be some secrets that will be required to be the same for all Cells in the cluster. ## 1. Definition -GitLab has a lot of -[secrets](https://docs.gitlab.com/charts/installation/secrets.html) that needs -to be configured. - -Some secrets are for inter-component communication, for example, `GitLab Shell secret`, -and used only within a cell. - +GitLab has a lot of [secrets](https://docs.gitlab.com/charts/installation/secrets.html) that need to be configured. +Some secrets are for inter-component communication, for example, `GitLab Shell secret`, and used only within a Cell. Some secrets are used for features, for example, `ci_jwt_signing_key`. ## 2. Data flow ## 3. Proposal -1. Secrets used for features will need to be consistent across all cells, so that the UX is consistent. +1. Secrets used for features will need to be consistent across all Cells, so that the UX is consistent. 1. This is especially true for the `db_key_base` secret which is used for - encrypting data at rest in the database - so that projects that are - transferred to another cell will continue to work. We do not want to have - to re-encrypt such rows when we move projects/groups between cells. -1. Secrets which are used for intra-cell communication only should be uniquely generated - per-cell. + encrypting data at rest in the database - so that Projects that are + transferred to another Cell will continue to work. We do not want to have + to re-encrypt such rows when we move Projects/Groups between Cells. +1. Secrets which are used for intra-Cell communication only should be uniquely generated + per Cell. ## 4. Evaluation diff --git a/doc/architecture/blueprints/cells/cells-feature-snippets.md b/doc/architecture/blueprints/cells/cells-feature-snippets.md index f5e72c0e3a0..bde0b098609 100644 --- a/doc/architecture/blueprints/cells/cells-feature-snippets.md +++ b/doc/architecture/blueprints/cells/cells-feature-snippets.md @@ -15,16 +15,42 @@ we can document the reasons for not choosing this approach. # Cells: Snippets -> TL;DR +Snippets will be scoped to an Organization. Initially it will not be possible to aggregate snippet collections across Organizations. See also [issue #416954](https://gitlab.com/gitlab-org/gitlab/-/issues/416954). ## 1. Definition +Two different types of snippets exist: + +- [Project snippets](../../../api/project_snippets.md). These snippets have URLs + like `/<group>/<project>/-/snippets/123` +- [Personal snippets](../../../user/snippets.md). These snippets have URLs like + `/-/snippets/123` + +Snippets are backed by a Git repository. + ## 2. Data flow ## 3. Proposal +### 3.1. Scoped to an organization + +Both project and personal snippets will be scoped to an Organization. + +- Project snippets URLs will remain unchanged, as the URLs are routable. +- Personal snippets URLs will need to change to be `/-/organizations/<organization>/snippets/123`, + so that the URL is routeable + +Creation of snippets will also be scoped to a User's current Organization. Because of that, we recommend renaming `personal snippets` to `organization snippets` once the Organization is rolled out. A User can create many independent snippet collections across multiple Organizations. + ## 4. Evaluation +Snippets are scoped to an Organization because Gitaly is confined to a Cell. + ## 4.1. Pros +- No need to have clusterwide Gitaly. + ## 4.2. Cons + +- We will break [snippet discovery](/ee/user/snippets.md#discover-snippets). +- Snippet access may become subordinate to the visibility of the Organization. diff --git a/doc/architecture/blueprints/cells/cells-feature-user-profile.md b/doc/architecture/blueprints/cells/cells-feature-user-profile.md new file mode 100644 index 00000000000..fc02548f371 --- /dev/null +++ b/doc/architecture/blueprints/cells/cells-feature-user-profile.md @@ -0,0 +1,52 @@ +--- +stage: enablement +group: Tenant Scale +description: 'Cells: User Profile' +--- + +<!-- vale gitlab.FutureTense = NO --> + +This document is a work-in-progress and represents a very early state of the +Cells design. Significant aspects are not documented, though we expect to add +them in the future. This is one possible architecture for Cells, and we intend to +contrast this with alternatives before deciding which approach to implement. +This documentation will be kept even if we decide not to implement this so that +we can document the reasons for not choosing this approach. + +# Cells: User Profile + +The existing User Profiles will initially be scoped to an Organization. Long-term, we should consider aggregating parts of the User activity across Organizations to enable Users a global view of their contributions. + +## 1. Definition + +Each GitLab account has a [User Profile](../../../user/profile/index.md), which contains information about the User and their GitLab activity. + +## 2. Data flow + +## 3. Proposal + +User Profiles will be scoped to an Organization. + +- Users can set a Home Organization as their main Organization. +- Users who do not exist in the database at all display a 404 not found error when trying to access their User Profile. +- User who haven't contributed to an Organization display their User Profile with an empty state. +- When displaying a User Profile empty state, if the profile has a Home Organization set to another Organization, we display a call-to-action allowing navigation to the main Organization. +- User Profile URLs will not reference the Organization and remain as: `/<username>`. We follow the same pattern as is used for `Your Work`, meaning that profiles are always seen in the context of an Organization. +- Breadcrumbs on the User Profile will present as `[Organization Name] / [Username]`. + +See [issue #411931](https://gitlab.com/gitlab-org/gitlab/-/issues/411931) for design proposals. + +## 4. Evaluation + +We expect the [majority of Users to perform most of their activity in one single Organization](../organization/index.md#data-exploration). +This is why we deem it acceptable to scope the User Profile to an Organization at first. +More discovery is necessary to understand which aspects of the current User Profile are relevant to showcase contributions in a global context. + +## 4.1. Pros + +- Viewing a User Profile scoped to an Organization allows you to focus on contributions that are most relevant to your Organization, filtering out the User's other activities. +- Existing User Profile URLs do not break. + +## 4.2. Cons + +- Users will lose the ability to display their entire activity, which may lessen the effectiveness of using their User Profile as a resume of achievements when working across multiple Organizations. diff --git a/doc/architecture/blueprints/cells/cells-feature-your-work.md b/doc/architecture/blueprints/cells/cells-feature-your-work.md new file mode 100644 index 00000000000..08bb0bed709 --- /dev/null +++ b/doc/architecture/blueprints/cells/cells-feature-your-work.md @@ -0,0 +1,58 @@ +--- +stage: enablement +group: Tenant Scale +description: 'Cells: Your Work' +--- + +<!-- vale gitlab.FutureTense = NO --> + +This document is a work-in-progress and represents a very early state of the +Cells design. Significant aspects are not documented, though we expect to add +them in the future. This is one possible architecture for Cells, and we intend to +contrast this with alternatives before deciding which approach to implement. +This documentation will be kept even if we decide not to implement this so that +we can document the reasons for not choosing this approach. + +# Cells: Your Work + +Your Work will be scoped to an Organization. +Counts presented in the individual dashboards will relate to the selected Organization. + +## 1. Definition + +When accessing `gitlab.com/dashboard/`, users can find a [focused view of items that they have access to](../../../tutorials/left_sidebar/index.md#use-a-more-focused-view). +This overview contains dashboards relating to: + +- Projects +- Groups +- Issues +- Merge requests +- To-Do list +- Milestones +- Snippets +- Activity +- Workspaces +- Environments +- Operations +- Security + +## 2. Data flow + +## 3. Proposal + +Your Work will be scoped to an Organization, giving the user an overview of all the items they can access in the Organization they are currently viewing. + +- Issue, Merge request and To-Do list counts will refer to the selected Organization. + +## 4. Evaluation + +Scoping Your Work to an Organization makes sense in the context of the [proposed Organization navigation](https://gitlab.com/gitlab-org/gitlab/-/issues/417778). +Considering that [we expect most users to work in a single Organization](../organization/index.md#data-exploration), we deem this impact acceptable. + +## 4.1. Pros + +- Viewing Your Work scoped to an Organization allows Users to focus on content that is most relevant to their currently selected Organization. + +## 4.2. Cons + +- Users working across multiple Organizations will have to navigate to each Organization to access all of their work items. diff --git a/doc/architecture/blueprints/cells/diagrams/cells-and-fulfillment.drawio.png b/doc/architecture/blueprints/cells/diagrams/cells-and-fulfillment.drawio.png Binary files differnew file mode 100644 index 00000000000..c5fff9dbca5 --- /dev/null +++ b/doc/architecture/blueprints/cells/diagrams/cells-and-fulfillment.drawio.png diff --git a/doc/architecture/blueprints/cells/diagrams/index.md b/doc/architecture/blueprints/cells/diagrams/index.md new file mode 100644 index 00000000000..77d12612819 --- /dev/null +++ b/doc/architecture/blueprints/cells/diagrams/index.md @@ -0,0 +1,35 @@ +--- +stage: enablement +group: Tenant Scale +description: 'Cells: Diagrams' +--- + +# Diagrams + +Diagrams used in Cells are created with [draw.io](https://draw.io). + +## Edit existing diagrams + +Load the `.drawio.png` or `.drawio.svg` file directly into **draw.io**, which you can use in several ways: + +- Best: Use the [draw.io integration in VSCode](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio). +- Good: Install on MacOS with `brew install drawio` or download the [draw.io desktop](https://github.com/jgraph/drawio-desktop/releases). +- Good: Install on Linux by downloading the [draw.io desktop](https://github.com/jgraph/drawio-desktop/releases). +- Discouraged: Use the [draw.io website](https://draw.io) to load and save files. + +## Create a diagram + +To create a diagram from a file: + +1. Copy existing file and rename it. Ensure that the extension is `.drawio.png` or `.drawio.svg`. +1. Edit the diagram. +1. Save the file. + +To create a diagram from scratch using [draw.io desktop](https://github.com/jgraph/drawio-desktop/releases): + +1. In **File > New > Create new diagram**, select **Blank diagram**. +1. In **File > Save As**, select **Editable Bitmap .png**, and save with `.drawio.png` extension. +1. To improve image quality, in **File > Properties**, set **Zoom** to **400%**. +1. To save the file with the new zoom setting, select **File > Save**. + +DO NOT use the **File > Export** function. The diagram should be embedded into `.png` for easy editing. diff --git a/doc/architecture/blueprints/cells/diagrams/term-cell.drawio.png b/doc/architecture/blueprints/cells/diagrams/term-cell.drawio.png Binary files differnew file mode 100644 index 00000000000..84a6d6d1745 --- /dev/null +++ b/doc/architecture/blueprints/cells/diagrams/term-cell.drawio.png diff --git a/doc/architecture/blueprints/cells/diagrams/term-cluster.drawio.png b/doc/architecture/blueprints/cells/diagrams/term-cluster.drawio.png Binary files differnew file mode 100644 index 00000000000..a6fd790ba5e --- /dev/null +++ b/doc/architecture/blueprints/cells/diagrams/term-cluster.drawio.png diff --git a/doc/architecture/blueprints/cells/diagrams/term-organization.drawio.png b/doc/architecture/blueprints/cells/diagrams/term-organization.drawio.png Binary files differnew file mode 100644 index 00000000000..f1cb7cd92fe --- /dev/null +++ b/doc/architecture/blueprints/cells/diagrams/term-organization.drawio.png diff --git a/doc/architecture/blueprints/cells/diagrams/term-top-level-group.drawio.png b/doc/architecture/blueprints/cells/diagrams/term-top-level-group.drawio.png Binary files differnew file mode 100644 index 00000000000..f5535409945 --- /dev/null +++ b/doc/architecture/blueprints/cells/diagrams/term-top-level-group.drawio.png diff --git a/doc/architecture/blueprints/cells/glossary.md b/doc/architecture/blueprints/cells/glossary.md index c3ec5fd12e4..11a1fc5acc9 100644 --- a/doc/architecture/blueprints/cells/glossary.md +++ b/doc/architecture/blueprints/cells/glossary.md @@ -14,7 +14,7 @@ We use the following terms to describe components and properties of the Cells ar A Cell is a set of infrastructure components that contains multiple top-level groups that belong to different organizations. The components include both datastores (PostgreSQL, Redis etc.) and stateless services (web etc.). The infrastructure components provided within a Cell are shared among organizations and their top-level groups but not shared with other Cells. This isolation of infrastructure components means that Cells are independent from each other. -<img src="images/term-cell.png" height="200"> +<img src="diagrams/term-cell.drawio.png" height="200"> ### Cell properties @@ -32,7 +32,7 @@ Discouraged synonyms: GitLab instance, cluster, shard A cluster is a collection of Cells. -<img src="images/term-cluster.png" height="300"> +<img src="diagrams/term-cluster.drawio.png" height="300"> ### Cluster properties @@ -56,7 +56,7 @@ Organizations work under the following assumptions: 1. Users understand that the majority of pages they view are only scoped to a single organization at a time. 1. Organizations are located on a single cell. - + ### Organization properties @@ -83,7 +83,7 @@ Over time there won't be a distinction between a top-level group and a group. Al Discouraged synonyms: Root-level namespace - + ### Top-level group properties diff --git a/doc/architecture/blueprints/cells/goals.md b/doc/architecture/blueprints/cells/goals.md index 67dc25625c7..3f3923aa255 100644 --- a/doc/architecture/blueprints/cells/goals.md +++ b/doc/architecture/blueprints/cells/goals.md @@ -8,7 +8,11 @@ description: 'Cells: Goals' ## Scalability -The main goal of this new shared-infrastructure architecture is to provide additional scalability for our SaaS Platform. GitLab.com is largely monolithic and we have estimated (internal) that the current architecture has scalability limitations, even when database partitioning and decomposition are taken into account. +The main goal of this new shared-infrastructure architecture is to provide additional scalability for our SaaS Platform. +GitLab.com is largely monolithic and we have estimated (internally) that the current architecture has scalability limitations, +particularly for the [PostgreSQL database](https://gitlab-com.gitlab.io/gl-infra/tamland/patroni.html), and +[Redis](https://gitlab-com.gitlab.io/gl-infra/tamland/redis.html) non-horizontally scalable resources, +even when database partitioning and decomposition are taken into account. Cells provide a horizontally scalable solution because additional Cells can be created based on demand. Cells can be provisioned and tuned as needed for optimal scalability. diff --git a/doc/architecture/blueprints/cells/images/pods-and-fulfillment.png b/doc/architecture/blueprints/cells/images/pods-and-fulfillment.png Binary files differdeleted file mode 100644 index fea32d1800e..00000000000 --- a/doc/architecture/blueprints/cells/images/pods-and-fulfillment.png +++ /dev/null diff --git a/doc/architecture/blueprints/cells/images/term-cell.png b/doc/architecture/blueprints/cells/images/term-cell.png Binary files differdeleted file mode 100644 index 799b2eccd95..00000000000 --- a/doc/architecture/blueprints/cells/images/term-cell.png +++ /dev/null diff --git a/doc/architecture/blueprints/cells/images/term-cluster.png b/doc/architecture/blueprints/cells/images/term-cluster.png Binary files differdeleted file mode 100644 index 03c92850b64..00000000000 --- a/doc/architecture/blueprints/cells/images/term-cluster.png +++ /dev/null diff --git a/doc/architecture/blueprints/cells/images/term-organization.png b/doc/architecture/blueprints/cells/images/term-organization.png Binary files differdeleted file mode 100644 index dd6367ad84a..00000000000 --- a/doc/architecture/blueprints/cells/images/term-organization.png +++ /dev/null diff --git a/doc/architecture/blueprints/cells/images/term-top-level-group.png b/doc/architecture/blueprints/cells/images/term-top-level-group.png Binary files differdeleted file mode 100644 index 4af2468f50d..00000000000 --- a/doc/architecture/blueprints/cells/images/term-top-level-group.png +++ /dev/null diff --git a/doc/architecture/blueprints/cells/impact.md b/doc/architecture/blueprints/cells/impact.md index 878af4d1a5e..30c70dca0cc 100644 --- a/doc/architecture/blueprints/cells/impact.md +++ b/doc/architecture/blueprints/cells/impact.md @@ -51,7 +51,7 @@ We synced with Fulfillment ([recording](https://youtu.be/FkQF3uF7vTY)) to discus A rough representation of this is: - + ### Potential conflicts with Cells diff --git a/doc/architecture/blueprints/cells/index.md b/doc/architecture/blueprints/cells/index.md index dcd28707890..0e93b9d5d3b 100644 --- a/doc/architecture/blueprints/cells/index.md +++ b/doc/architecture/blueprints/cells/index.md @@ -1,7 +1,7 @@ --- status: accepted creation-date: "2022-09-07" -authors: [ "@ayufan", "@fzimmer", "@DylanGriffith", "@lohrc" ] +authors: [ "@ayufan", "@fzimmer", "@DylanGriffith", "@lohrc", "@tkuah" ] coach: "@ayufan" approvers: [ "@lohrc" ] owning-stage: "~devops::enablement" @@ -14,7 +14,7 @@ participating-stages: [] This document is a work-in-progress and represents a very early state of the Cells design. Significant aspects are not documented, though we expect to add them in the future. -Cells is a new architecture for our Software as a Service platform. This architecture is horizontally-scalable, resilient, and provides a more consistent user experience. It may also provide additional features in the future, such as data residency control (regions) and federated features. +Cells is a new architecture for our software as a service platform. This architecture is horizontally scalable, resilient, and provides a more consistent user experience. It may also provide additional features in the future, such as data residency control (regions) and federated features. For more information about Cells, see also: @@ -28,8 +28,7 @@ We can't ship the entire Cells architecture in one go - it is too large. Instead, we are defining key work streams required by the project. Not all objectives need to be fulfilled to reach production readiness. -It is expected that some objectives will not be completed for General Availability (GA), -but will be enough to run Cells in production. +It is expected that some objectives will not be completed for General Availability (GA), but will be enough to run Cells in production. ### 1. Data access layer @@ -45,8 +44,7 @@ Under this objective the following steps are expected: 1. **Allow to share cluster-wide data with database-level data access layer.** - Cells can connect to a database containing shared data. For example: - application settings, users, or routing information. + Cells can connect to a database containing shared data. For example: application settings, users, or routing information. 1. **Evaluate the efficiency of database-level access vs. API-oriented access layer.** @@ -54,7 +52,7 @@ Under this objective the following steps are expected: 1. **Cluster-unique identifiers** - Every object has a unique identifier that can be used to access data across the cluster. The IDs for allocated projects, issues and any other objects are cluster-unique. + Every object has a unique identifier that can be used to access data across the cluster. The IDs for allocated Projects, issues and any other objects are cluster-unique. 1. **Cluster-wide deletions** @@ -62,7 +60,7 @@ Under this objective the following steps are expected: 1. **Data access layer** - Ensure that a stable data-access (versioned) layer that allows to share cluster-wide data is implemented. + Ensure that a stable data access (versioned) layer is implemented that allows to share cluster-wide data. 1. **Database migration** @@ -70,48 +68,38 @@ Under this objective the following steps are expected: ### 2. Essential workflows -To make Cells viable we require to define and support -essential workflows before we can consider the Cells -to be of Beta quality. Essential workflows are meant -to cover the majority of application functionality -that makes the product mostly useable, but with some caveats. +To make Cells viable we require to define and support essential workflows before we can consider the Cells to be of Beta quality. +Essential workflows are meant to cover the majority of application functionality that makes the product mostly useable, but with some caveats. The current approach is to define workflows from top to bottom. The order defines the presumed priority of the items. -This list is not exhaustive as we would be expecting -other teams to help and fix their workflows after -the initial phase, in which we fix the fundamental ones. - -To consider a project ready for the Beta phase, it is expected -that all features defined below are supported by Cells. -In the cases listed below, the workflows define a set of tables -to be properly attributed to the feature. In some cases, -a table with an ambiguous usage has to be broken down. -For example: `uploads` are used to store user avatars, -as well as uploaded attachments for comments. It would be expected -that `uploads` is split into `uploads` (describing group/project-level attachments) -and `global_uploads` (describing, for example, user avatars). - -Except for initial 2-3 quarters this work is highly parallel. -It would be expected that **group::tenant scale** would help other -teams to fix their feature set to work with Cells. The first 2-3 quarters -would be required to define a general split of data and build required tooling. +This list is not exhaustive as we would be expecting other teams to help and fix their workflows after the initial phase, in which we fix the fundamental ones. + +To consider a project ready for the Beta phase, it is expected that all features defined below are supported by Cells. +In the cases listed below, the workflows define a set of tables to be properly attributed to the feature. +In some cases, a table with an ambiguous usage has to be broken down. +For example: `uploads` are used to store user avatars, as well as uploaded attachments for comments. +It would be expected that `uploads` is split into `uploads` (describing Group/Project-level attachments) and `global_uploads` (describing, for example, user avatars). + +Except for the initial 2-3 quarters this work is highly parallel. +It is expected that **group::tenant scale** will help other teams to fix their feature set to work with Cells. +The first 2-3 quarters are required to define a general split of data and build the required tooling. 1. **Instance-wide settings are shared across cluster.** - The Admin Area section for most part is shared across a cluster. + The Admin Area section for the most part is shared across a cluster. 1. **User accounts are shared across cluster.** The purpose is to make `users` cluster-wide. -1. **User can create group.** +1. **User can create Group.** - The purpose is to perform a targeted decomposition of `users` and `namespaces`, because the `namespaces` will be stored locally in the Cell. + The purpose is to perform a targeted decomposition of `users` and `namespaces`, because `namespaces` will be stored locally in the Cell. -1. **User can create project.** +1. **User can create Project.** - The purpose is to perform a targeted decomposition of `users` and `projects`, because the `projects` will be stored locally in the Cell. + The purpose is to perform a targeted decomposition of `users` and `projects`, because `projects` will be stored locally in the Cell. 1. **User can change profile avatar that is shared in cluster.** @@ -119,8 +107,7 @@ would be required to define a general split of data and build required tooling. 1. **User can push to Git repository.** - The purpose is to ensure that essential joins from the projects table are properly attributed to be - Cell-local, and as a result the essential Git workflow is supported. + The purpose is to ensure that essential joins from the Projects table are properly attributed to be Cell-local, and as a result the essential Git workflow is supported. 1. **User can run CI pipeline.** @@ -130,26 +117,26 @@ would be required to define a general split of data and build required tooling. The purpose is to ensure that `issues` and `merge requests` are properly attributed to be `Cell-local`. -1. **User can manage group and project members.** +1. **User can manage Group and Project members.** The `members` table is properly attributed to be either `Cell-local` or `cluster-wide`. 1. **User can manage instance-wide runners.** - The purpose is to scope all CI Runners to be Cell-local. Instance-wide runners in fact become Cell-local runners. The expectation is to provide a user interface view and manage all runners per Cell, instead of per cluster. + The purpose is to scope all CI runners to be Cell-local. Instance-wide runners in fact become Cell-local runners. The expectation is to provide a user interface view and manage all runners per Cell, instead of per cluster. -1. **User is part of organization and can only see information from the organization.** +1. **User is part of Organization and can only see information from the Organization.** - The purpose is to have many organizations per Cell, but never have a single organization spanning across many Cells. This is required to ensure that information shown within an organization is isolated, and does not require fetching information from other Cells. + The purpose is to have many Organizations per Cell, but never have a single Organization spanning across many Cells. This is required to ensure that information shown within an Organization is isolated, and does not require fetching information from other Cells. ### 3. Additional workflows Some of these additional workflows might need to be supported, depending on the group decision. This list is not exhaustive of work needed to be done. -1. **User can use all group-level features.** -1. **User can use all project-level features.** -1. **User can share groups with other groups in an organization.** +1. **User can use all Group-level features.** +1. **User can use all Project-level features.** +1. **User can share Groups with other Groups in an Organization.** 1. **User can create system webhook.** 1. **User can upload and manage packages.** 1. **User can manage security detection features.** @@ -158,13 +145,11 @@ This list is not exhaustive of work needed to be done. ### 4. Routing layer -The routing layer is meant to offer a consistent user experience where all Cells are presented -under a single domain (for example, `gitlab.com`), instead of -having to navigate to separate domains. +The routing layer is meant to offer a consistent user experience where all Cells are presented under a single domain (for example, `gitlab.com`), instead of having to navigate to separate domains. -The user will able to use `https://gitlab.com` to access Cell-enabled GitLab. Depending -on the URL access, it will be transparently proxied to the correct Cell that can serve this particular -information. For example: +The user will be able to use `https://gitlab.com` to access Cell-enabled GitLab. +Depending on the URL access, it will be transparently proxied to the correct Cell that can serve this particular information. +For example: - All requests going to `https://gitlab.com/users/sign_in` are randomly distributed to all Cells. - All requests going to `https://gitlab.com/gitlab-org/gitlab/-/tree/master` are always directed to Cell 5, for example. @@ -173,9 +158,8 @@ information. For example: 1. **Technology.** We decide what technology the routing service is written in. - The choice is dependent on the best performing language, and the expected way - and place of deployment of the routing layer. If it is required to make - the service multi-cloud it might be required to deploy it to the CDN provider. + The choice is dependent on the best performing language, and the expected way and place of deployment of the routing layer. + If it is required to make the service multi-cloud it might be required to deploy it to the CDN provider. Then the service needs to be written using a technology compatible with the CDN provider. 1. **Cell discovery.** @@ -184,35 +168,29 @@ information. For example: 1. **Router endpoints classification.** - The stateless routing service will fetch and cache information about endpoints - from one of the Cells. We need to implement a protocol that will allow us to - accurately describe the incoming request (its fingerprint), so it can be classified - by one of the Cells, and the results of that can be cached. We also need to implement - a mechanism for negative cache and cache eviction. + The stateless routing service will fetch and cache information about endpoints from one of the Cells. + We need to implement a protocol that will allow us to accurately describe the incoming request (its fingerprint), so it can be classified by one of the Cells, and the results of that can be cached. + We also need to implement a mechanism for negative cache and cache eviction. 1. **GraphQL and other ambiguous endpoints.** - Most endpoints have a unique sharding key: the organization, which directly - or indirectly (via a group or project) can be used to classify endpoints. - Some endpoints are ambiguous in their usage (they don't encode the sharding key), - or the sharding key is stored deep in the payload. In these cases, we need to decide how to handle endpoints like `/api/graphql`. + Most endpoints have a unique sharding key: the Organization, which directly or indirectly (via a Group or Project) can be used to classify endpoints. + Some endpoints are ambiguous in their usage (they don't encode the sharding key), or the sharding key is stored deep in the payload. + In these cases, we need to decide how to handle endpoints like `/api/graphql`. ### 5. Cell deployment -We will run many Cells. To manage them easier, we need to have consistent -deployment procedures for Cells, including a way to deploy, manage, migrate, -and monitor. +We will run many Cells. +To manage them easier, we need to have consistent deployment procedures for Cells, including a way to deploy, manage, migrate, and monitor. -We are very likely to use tooling made for [GitLab Dedicated](https://about.gitlab.com/dedicated/) -with its control planes. +We are very likely to use tooling made for [GitLab Dedicated](https://about.gitlab.com/dedicated/) with its control planes. 1. **Extend GitLab Dedicated to support GCP.** 1. TBD ### 6. Migration -When we reach production and are able to store new organizations on new Cells, we need -to be able to divide big Cells into many smaller ones. +When we reach production and are able to store new Organizations on new Cells, we need to be able to divide big Cells into many smaller ones. 1. **Use GitLab Geo to clone Cells.** @@ -220,14 +198,13 @@ to be able to divide big Cells into many smaller ones. 1. **Split Cells by cloning them.** - Once Cell is cloned we change routing information for organizations. - Organization will encode `cell_id`. When we update `cell_id` it will automatically - make the given Cell to be authoritative to handle the traffic for the given organization. + Once a Cell is cloned we change the routing information for Organizations. + Organizations will encode a `cell_id`. + When we update the `cell_id` it will automatically make the given Cell authoritative to handle traffic for the given Organization. 1. **Delete redundant data from previous Cells.** - Since the organization is now stored on many Cells, once we change `cell_id` - we will have to remove data from all other Cells based on `organization_id`. + Since the Organization is now stored on many Cells, once we change `cell_id` we will have to remove data from all other Cells based on `organization_id`. ## Availability of the feature @@ -237,11 +214,10 @@ We are following the [Support for Experiment, Beta, and Generally Available feat Expectations: -- We can deploy a Cell on staging or another testing environment by using a separate domain (ex. `cell2.staging.gitlab.com`) - using [Cell deployment](#5-cell-deployment) tooling. -- User can create organization, group and project, and run some of the [essential workflows](#2-essential-workflows). +- We can deploy a Cell on staging or another testing environment by using a separate domain (for example `cell2.staging.gitlab.com`) using [Cell deployment](#5-cell-deployment) tooling. +- User can create Organization, Group and Project, and run some of the [essential workflows](#2-essential-workflows). - It is not expected to be able to run a router to serve all requests under a single domain. -- We expect data-loss of data stored on additional Cells. +- We expect data loss of data stored on additional Cells. - We expect to tear down and create many new Cells to validate tooling. ### 2. Beta @@ -250,7 +226,7 @@ Expectations: - We can run many Cells under a single domain (ex. `staging.gitlab.com`). - All features defined in [essential workflows](#2-essential-workflows) are supported. -- Not all aspects of [Routing layer](#4-routing-layer) are finalized. +- Not all aspects of the [routing layer](#4-routing-layer) are finalized. - We expect additional Cells to be stable with minimal data loss. ### 3. GA @@ -259,119 +235,137 @@ Expectations: - We can run many Cells under a single domain (for example, `staging.gitlab.com`). - All features defined in [essential workflows](#2-essential-workflows) are supported. -- All features of [routing layer](#4-routing-layer) are supported. -- Most of [additional workflows](#3-additional-workflows) are supported. -- We don't expect to support any of [migration](#6-migration) aspects. +- All features of the [routing layer](#4-routing-layer) are supported. +- Most of the [additional workflows](#3-additional-workflows) are supported. +- We don't expect to support any of the [migration](#6-migration) aspects. ### 4. Post GA Expectations: - We support all [additional workflows](#3-additional-workflows). -- We can [migrate](#6-migration) existing organizations onto new Cells. +- We can [migrate](#6-migration) existing Organizations onto new Cells. ## Iteration plan -The delivered iterations will focus on solving particular steps of a given -key work stream. - -It is expected that initial iterations will rather -be slow, because they require substantially more -changes to prepare the codebase for data split. +The delivered iterations will focus on solving particular steps of a given key work stream. +It is expected that initial iterations will be rather slow, because they require substantially more changes to prepare the codebase for data split. One iteration describes one quarter's worth of work. -1. [Iteration 1](https://gitlab.com/groups/gitlab-org/-/epics/9667) - FY24Q1 +1. [Iteration 1](https://gitlab.com/groups/gitlab-org/-/epics/9667) - FY24Q1 - Complete - Data access layer: Initial Admin Area settings are shared across cluster. - Essential workflows: Allow to share cluster-wide data with database-level data access layer -1. [Iteration 2](https://gitlab.com/groups/gitlab-org/-/epics/9813) - FY24Q2 +1. [Iteration 2](https://gitlab.com/groups/gitlab-org/-/epics/9813) - FY24Q2 - In progress - Essential workflows: User accounts are shared across cluster. - - Essential workflows: User can create group. + - Essential workflows: User can create Group. -1. [Iteration 3](https://gitlab.com/groups/gitlab-org/-/epics/10997) - FY24Q3 +1. [Iteration 3](https://gitlab.com/groups/gitlab-org/-/epics/10997) - FY24Q3 - Planned - - Essential workflows: User can create project. - - Essential workflows: User can push to Git repository. - - Cell deployment: Extend GitLab Dedicated to support GCP + - Essential workflows: User can create Project. - Routing: Technology. + - Data access layer: Evaluate the efficiency of database-level access vs. API-oriented access layer 1. [Iteration 4](https://gitlab.com/groups/gitlab-org/-/epics/10998) - FY24Q4 - - Essential workflows: User can run CI pipeline. + - Essential workflows: User can push to Git repository. - Essential workflows: User can create issue, merge request, and merge it after it is green. - - Data access layer: Evaluate the efficiency of database-level access vs. API-oriented access layer - Data access layer: Cluster-unique identifiers. - Routing: Cell discovery. - Routing: Router endpoints classification. + - Cell deployment: Extend GitLab Dedicated to support GCP 1. Iteration 5 - FY25Q1 + - Essential workflows: User can run CI pipeline. + - Essential workflows: Instance-wide settings are shared across cluster. + - Essential workflows: User can change profile avatar that is shared in cluster. + - Essential workflows: User can create issue, merge request, and merge it after it is green. + - Essential workflows: User can manage Group and Project members. + - Essential workflows: User can manage instance-wide runners. + - Essential workflows: User is part of Organization and can only see information from the Organization. + - Routing: GraphQL and other ambiguous endpoints. + - Data access layer: Allow to share cluster-wide data with database-level data access layer. + - Data access layer: Cluster-wide deletions. + - Data access layer: Data access layer. + - Data access layer: Database migrations. + +1. Iteration 6 - FY25Q2 + - TBD + +1. Iteration 7 - FY25Q3 + - TBD + +1. Iteration 8 - FY25Q4 - TBD ## Technical Proposals -The Cells architecture do have long lasting implications to data processing, location, scalability and the GitLab architecture. +The Cells architecture has long lasting implications to data processing, location, scalability and the GitLab architecture. This section links all different technical proposals that are being evaluated. - [Stateless Router That Uses a Cache to Pick Cell and Is Redirected When Wrong Cell Is Reached](proposal-stateless-router-with-buffering-requests.md) - - [Stateless Router That Uses a Cache to Pick Cell and pre-flight `/api/v4/cells/learn`](proposal-stateless-router-with-routes-learning.md) ## Impacted features The Cells architecture will impact many features requiring some of them to be rewritten, or changed significantly. -This is the list of known affected features with the proposed solutions. +Below is a list of known affected features with preliminary proposed solutions. -- [Cells: Git Access](cells-feature-git-access.md) -- [Cells: Data Migration](cells-feature-data-migration.md) -- [Cells: Database Sequences](cells-feature-database-sequences.md) -- [Cells: GraphQL](cells-feature-graphql.md) -- [Cells: Organizations](cells-feature-organizations.md) -- [Cells: Router Endpoints Classification](cells-feature-router-endpoints-classification.md) -- [Cells: Schema changes (Postgres and Elasticsearch migrations)](cells-feature-schema-changes.md) +- [Cells: Admin Area](cells-feature-admin-area.md) - [Cells: Backups](cells-feature-backups.md) -- [Cells: Global Search](cells-feature-global-search.md) - [Cells: CI Runners](cells-feature-ci-runners.md) -- [Cells: Admin Area](cells-feature-admin-area.md) -- [Cells: Secrets](cells-feature-secrets.md) - [Cells: Container Registry](cells-feature-container-registry.md) - [Cells: Contributions: Forks](cells-feature-contributions-forks.md) -- [Cells: Personal Namespaces](cells-feature-personal-namespaces.md) -- [Cells: Dashboard: Projects, Todos, Issues, Merge Requests, Activity, ...](cells-feature-dashboard.md) +- [Cells: Database Sequences](cells-feature-database-sequences.md) +- [Cells: Data Migration](cells-feature-data-migration.md) +- [Cells: Explore](cells-feature-explore.md) +- [Cells: Git Access](cells-feature-git-access.md) +- [Cells: Global Search](cells-feature-global-search.md) +- [Cells: GraphQL](cells-feature-graphql.md) +- [Cells: Organizations](cells-feature-organizations.md) +- [Cells: Secrets](cells-feature-secrets.md) - [Cells: Snippets](cells-feature-snippets.md) -- [Cells: Uploads](cells-feature-uploads.md) -- [Cells: GitLab Pages](cells-feature-gitlab-pages.md) +- [Cells: User Profile](cells-feature-user-profile.md) +- [Cells: Your Work](cells-feature-your-work.md) + +### Impacted features: Placeholders + +The following list of impacted features only represents placeholders that still require work to estimate the impact of Cells and develop solution proposals. + - [Cells: Agent for Kubernetes](cells-feature-agent-for-kubernetes.md) +- [Cells: GitLab Pages](cells-feature-gitlab-pages.md) +- [Cells: Personal Access Tokens](cells-feature-personal-access-tokens.md) +- [Cells: Personal Namespaces](cells-feature-personal-namespaces.md) +- [Cells: Router Endpoints Classification](cells-feature-router-endpoints-classification.md) +- [Cells: Schema changes (Postgres and Elasticsearch migrations)](cells-feature-schema-changes.md) +- [Cells: Uploads](cells-feature-uploads.md) +- ... ## Frequently Asked Questions ### What's the difference between Cells architecture and GitLab Dedicated? -The new Cells architecture is meant to scale GitLab.com. And the way to achieve this is by moving -organizations into cells, but different organizations can still share each other server resources, even -if the application provides isolation from other organizations. But all of them still operate under the -existing GitLab SaaS domain name `gitlab.com`. Also, cells still share some common data, like `users`, and -routing information of groups and projects. For example, no two users can have the same username -even if they belong to different organizations that exist on different cells. +The new Cells architecture is meant to scale GitLab.com. +The way to achieve this is by moving Organizations into Cells, but different Organizations can still share server resources, even if the application provides isolation from other Organizations. +But all of them still operate under the existing GitLab SaaS domain name `gitlab.com`. +Also, Cells still share some common data, like `users`, and routing information of Groups and Projects. +For example, no two users can have the same username even if they belong to different Organizations that exist on different Cells. -With the aforementioned differences, GitLab Dedicated is still offered at higher costs due to the fact -that it's provisioned via dedicated server resources for each customer, while Cells use shared resources. Which -makes GitLab Dedicated more suited for bigger customers, and GitLab Cells more suitable for small to mid size -companies that are starting on GitLab.com. +With the aforementioned differences, [GitLab Dedicated](https://about.gitlab.com/dedicated/) is still offered at higher costs due to the fact that it's provisioned via dedicated server resources for each customer, while Cells use shared resources. +This makes GitLab Dedicated more suited for bigger customers, and GitLab Cells more suitable for small to mid-size companies that are starting on GitLab.com. -On the other hand, [GitLab Dedicated](https://about.gitlab.com/dedicated/) is meant to provide completely -isolated GitLab instance for any organization. Where this instance is running on its own custom domain name, and -totally isolated from any other GitLab instance, including GitLab SaaS. For example, users on GitLab dedicated -don't have to have a different and unique username that was already taken on GitLab.com. +On the other hand, GitLab Dedicated is meant to provide a completely isolated GitLab instance for any Organization. +This instance is running on its own custom domain name, and is totally isolated from any other GitLab instance, including GitLab SaaS. +For example, users on GitLab Dedicated don't have to have a different and unique username that was already taken on GitLab.com. -### Can different cells communicate with each other? +### Can different Cells communicate with each other? -Up until iteration 3, cells communicate with each other only via a shared database that contains common -data. In iteration 4 we are going to evaluate the option of cells calling each other via API to provide more -isolation and reliability. +Up until iteration 3, Cells communicate with each other only via a shared database that contains common data. +In iteration 4 we are going to evaluate the option of Cells calling each other via API to provide more isolation and reliability. ## Decision log @@ -380,8 +374,7 @@ isolation and reliability. ## Links - [Internal Pods presentation](https://docs.google.com/presentation/d/1x1uIiN8FR9fhL7pzFh9juHOVcSxEY7d2_q4uiKKGD44/edit#slide=id.ge7acbdc97a_0_155) -- [Internal link to all diagrams](https://drive.google.com/file/d/13NHzbTrmhUM-z_Bf0RjatUEGw5jWHSLt/view?usp=sharing) - [Cells Epic](https://gitlab.com/groups/gitlab-org/-/epics/7582) -- [Database Group investigation](https://about.gitlab.com/handbook/engineering/development/enablement/data_stores/database/doc/root-namespace-sharding.html) +- [Database group investigation](https://about.gitlab.com/handbook/engineering/development/enablement/data_stores/database/doc/root-namespace-sharding.html) - [Shopify Pods architecture](https://shopify.engineering/a-pods-architecture-to-allow-shopify-to-scale) - [Opstrace architecture](https://gitlab.com/gitlab-org/opstrace/opstrace/-/blob/main/docs/architecture/overview.md) diff --git a/doc/architecture/blueprints/ci_builds_runner_fleet_metrics/index.md b/doc/architecture/blueprints/ci_builds_runner_fleet_metrics/index.md new file mode 100644 index 00000000000..29b2bd0fd28 --- /dev/null +++ b/doc/architecture/blueprints/ci_builds_runner_fleet_metrics/index.md @@ -0,0 +1,132 @@ +--- +status: proposed +creation-date: "2023-01-25" +authors: [ "@pedropombeiro", "@vshushlin"] +coach: "@grzesiek" +approvers: [ ] +stage: Verify +group: Runner +participating-stages: [] +--- + +# CI Builds and Runner Fleet metrics database architecture + +The CI section envisions new value-added features in GitLab for CI Builds and Runner Fleet focused on observability and automation. However, implementing these features and delivering on the product vision of observability, automation, and AI optimization using the current database architecture in PostgreSQL is very hard because: + +- CI-related transactional tables are huge, so any modification to them can increase the load on the database and subsequently cause incidents. +- PostgreSQL is not optimized for running aggregation queries. +- We also want to add more information from the build environment, making CI tables even larger. +- We also need a data model to aggregate data sets for the GitLab CI efficiency machine learning models - the basis of the Runner Fleet AI solution + +We want to create a new flexible database architecture which: + +- will support known reporting requirements for CI builds and Runner Fleet. +- can be used to ingest data from the CI build environment. + +We may also use this database architecture to facilitate development of AI features in the future. + +Our recent usability research on navigation and other areas suggests that the GitLab UI is overloaded with information and navigational elements. +This results from trying to add as much information as possible and attempting to place features in the most discoverable places. +Therefore, while developing these new observability features, we will rely on the jobs to be done research, and solution validation, to ensure that the features deliver the most value. + +## Runner Fleet + +### Metrics - MVC + +#### What is the estimated wait time in queue for an instance runner? + +The following customer problems should be solved when addressing this question. Most of them are quotes from our usability research + +**UI** + +- "There is no visibility for expected Runner queue wait times." +- "I got here looking for a view that makes it more obvious if I have a bottleneck on my specific runner." + +**Types of metrics** + +- "Is it possible to get metrics out of GitLab to check for the runners availability & pipeline wait times? + Goal - we need the data to evaluate the data to determine if to scale up the Runner fleet so that there is no waiting times for developer’s pipelines." +- "What is the estimated time in the Runner queue before a job can start?" + +**Interpreting metrics** + +- "What metrics for Runner queue performance should I look at and how do I interpret the metrics and take action?" +- "I want to be able to analyze data on Runner queue performance over time so that I can determine if the reports are from developers are really just rare cases regarding availability." + +#### What is the estimated wait time in queue on a group runner? + +#### What is the mean estimated wait time in queue for all instance runners? + +#### What is the mean estimated wait time in queue for all group runners? + +#### Which runners have failures in the past hour? + +## Implementation + +The current implementation plan is based on a +[Proof of Concept](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126863). +For an up to date status, see [epic 10682](https://gitlab.com/groups/gitlab-org/-/epics/10682). + +### Database selection + +In FY23, ClickHouse [was selected as GitLab standard datastore](https://about.gitlab.com/company/team/structure/working-groups/clickhouse-datastore/#context) +for features with big data and insert-heavy requirements. +So we have chosen it for our CI analytics as well. + +### Scope of data + +We're starting with the denormalized version of the `ci_builds` table in the main database, +which will include fields from some other tables. For example, `ci_runners` and `ci_runner_machines`. + +[Immutability is a key constraint in ClickHouse](../../../development/database/clickhouse/index.md#how-it-differs-from-postgresql), +so we only use `finished` builds. + +### Developing behind feature flags + +It's hard to fully test data ingestion and query performance in development/staging environments. +That's why we plan to deliver those features to production behing feature flags and test the performance on real data. +Feature flags for data ingestion and API's will be separate. + +### Data ingestion + +A background worker will push `ci_builds` sorted by `(finished_at, id)` from Posgres to ClickHouse. +Every time the worker starts, it will find the most recently inserted build and continue from there. + +At some point we most likely will need to +[parallelize this worker because of the number of processed builds](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126863#note_1494922639). + +We will start with most recent builds and will not upload all historical data. + +### "Raw data", materialized views and queries + +Ingested data will go to the "raw data" table in ClickHouse. +This table will use `ReplacingMergeTree` engine to deduplicate rows in case data ingestion mechanism accidentally submits the same batch twice. + +Raw data can be used directly do execute queries, but most of the time we will create specialized materialized views +using `AggregatingMergeTree` engine. +This will allow us to read significantly less data when performing queries. + +### Limitations and open questions + +The topics below require further investigation. + +#### Efficient way of querying data for namespaces + +We start with the PoC available only for administrators, +but very soon we will need to implement features on the group level. + +We can't just put denormalized "path" in the source table because it can be changed when groups or projects are moved. + +The simplest way of solving this is to always filter builds by `project_id`, +but this may be inefficient and require reading a significant portion of all data because ClickHouse stores data in big batches. + +#### Keeping the database schema up to date + +Right now we don't have any mechanism equivalent to migrations we use for PostgreSQL. +While developing our first features we will maintain database schema by hand and +continue developing mechanisms for migrations. + +#### Re-uploading data after changing the schema + +If we need to modify database schema, old data maybe incomplete. +In that case we can simply truncate the ClickHouse tables and reupload (part of) the data. diff --git a/doc/architecture/blueprints/ci_pipeline_processing/index.md b/doc/architecture/blueprints/ci_pipeline_processing/index.md new file mode 100644 index 00000000000..a1e3092905c --- /dev/null +++ b/doc/architecture/blueprints/ci_pipeline_processing/index.md @@ -0,0 +1,448 @@ +--- +status: proposed +creation-date: "2023-05-15" +authors: [ "@furkanayhan" ] +coach: "@ayufan" +approvers: [ "@jreporter", "@cheryl.li" ] +owning-stage: "~devops::verify" +participating-stages: [] +--- + +# Future of CI Pipeline Processing + +## Summary + +GitLab CI is one of the oldest and most complex features in GitLab. +Over the years its YAML syntax has considerably grown in size and complexity. +In order to keep the syntax highly stable over the years, we have primarily been making additive changes +on top of the existing design and patterns. +Our user base has grown exponentially over the past years. With that, the need to support +their use cases and customization of the workflows. + +While delivering huge value over the years, the various additive changes to the syntax have also caused +some surprising behaviors in the pipeline processing logic. +Some keywords accumulated a number of responsibilities, and some ambiguous overlaps were discovered among +keywords and subtle differences in behavior were introduced over time. +The current implementation and YAML syntax also make it challenging to implement new features. + +In this design document, we will discuss the problems and propose +a new architecture for pipeline processing. Most of these problems have been discussed before in the +["Restructure CI job when keyword"](https://gitlab.com/groups/gitlab-org/-/epics/6788) epic. + +## Goals + +- We want to make the pipeline processing more understandable, predictable and consistent. +- We want to unify the behaviors of DAG and STAGE. STAGE can be written as DAG and vice versa. +- We want to decouple the manual jobs' blocking behavior from the `allow_failure` keyword. +- We want to clarify the responsibilities of the `when` keyword. + +## Non-Goals + +We will not discuss how to avoid breaking changes for now. + +## Motivation + +The list of problems is the main motivation for this design document. + +### Problem 1: The responsibility of the `when` keyword + +Right now, the [`when`](../../../ci/yaml/index.md#when) keyword has many responsibilities; + +> - `on_success` (default): Run the job only when no jobs in earlier stages fail or have `allow_failure: true`. +> - `on_failure`: Run the job only when at least one job in an earlier stage fails. A job in an earlier stage +> with `allow_failure: true` is always considered successful. +> - `never`: Don't run the job regardless of the status of jobs in earlier stages. +> Can only be used in a [`rules`](../../../ci/yaml/index.md#rules) section or `workflow: rules`. +> - `always`: Run the job regardless of the status of jobs in earlier stages. Can also be used in `workflow:rules`. +> - `manual`: Run the job only when [triggered manually](../../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually). +> - `delayed`: [Delay the execution of a job](../../../ci/jobs/job_control.md#run-a-job-after-a-delay) +> for a specified duration. + +It answers three questions; + +- What's required to run? => `on_success`, `on_failure`, `always` +- How to run? => `manual`, `delayed` +- Add to the pipeline? => `never` + +As a result, for example; we cannot create a `manual` job with `when: on_failure`. +This can be useful when persona wants to create a job that is only available on failure, but needs to be manually played. +For example; publishing failures to dedicated page or dedicated external service. + +### Problem 2: Abuse of the `allow_failure` keyword + +We control the blocker behavior of a manual job by the [`allow_failure`](../../../ci/yaml/index.md#allow_failure) keyword. +Actually, it has other responsibilities; _"determine whether a pipeline should continue running when a job fails"_. + +Currently, a [manual job](../../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually); + +- is not a blocker when it has `allow_failure: true` (by default) +- a blocker when it has `allow_failure: false`. + +As a result, for example; we cannot create a `manual` job that is `allow_failure: false` and not a blocker. + +```yaml +job1: + stage: test + when: manual + allow_failure: true # default + +job2: + stage: deploy +``` + +Currently; + +- `job1` is skipped. +- `job2` runs because `job1` is ignored since it has `allow_failure: true`. +- When we run/play `job1`; + - if it fails, it's marked as "success with warning". + +#### `allow_failure` with `rules` + +`allow_failure` becomes more confusing when using `rules`. + +From [docs](../../../ci/yaml/index.md#when): + +> The default behavior of `allow_failure` changes to true with `when: manual`. +> However, if you use `when: manual` with `rules`, `allow_failure` defaults to `false`. + +From [docs](../../../ci/yaml/index.md#allow_failure): + +> The default value for `allow_failure` is: +> +> - `true` for manual jobs. +> - `false` for jobs that use `when: manual` inside `rules`. +> - `false` in all other cases. + +For example; + +```yaml +job1: + script: ls + when: manual + +job2: + script: ls + rules: + - if: $ALWAYS_TRUE + when: manual +``` + +`job1` and `job2` behave differently; + +- `job1` is not a blocker because it has `allow_failure: true` by default. +- `job2` is a blocker `rules: when: manual` does not return `allow_failure: true` by default. + +### Problem 3: Different behaviors in DAG/needs + +The main behavioral difference between DAG and STAGE is about the "skipped" and "ignored" states. + +**Background information:** + +- skipped: + - When a job is `when: on_success` and its previous status is failed, it's skipped. + - When a job is `when: on_failure` and its previous status is not "failed", it's skipped. +- ignored: + - When a job is `when: manual` with `allow_failure: true`, it's ignored. + +**Problem:** + +The `skipped` and `ignored` states are considered successful in the STAGE processing but not in the DAG processing. + +#### Problem 3.1. Handling of ignored status with manual jobs + +**Example 1:** + +```yaml +build: + stage: build + script: exit 0 + when: manual + allow_failure: true # by default + +test: + stage: test + script: exit 0 + needs: [build] +``` + +- `build` is ignored (skipped) because it's `when: manual` with `allow_failure: true`. +- `test` is skipped because "ignored" is not a successful state in the DAG processing. + +**Example 2:** + +```yaml +build: + stage: build + script: exit 0 + when: manual + allow_failure: true # by default + +test: + stage: test + script: exit 0 +``` + +- `build` is ignored (skipped) because it's `when: manual` with `allow_failure: true`. +- `test2` runs and succeeds. + +#### Problem 3.2. Handling of skipped status with when: on_failure + +**Example 1:** + +```yaml +build_job: + stage: build + script: exit 1 + +test_job: + stage: test + script: exit 0 + +rollback_job: + stage: deploy + needs: [build_job, test_job] + script: exit 0 + when: on_failure +``` + +- `build_job` runs and fails. +- `test_job` is skipped. +- Even though `rollback_job` is `when: on_failure` and there is a failed job, it is skipped because the `needs` list has a "skipped" job. + +**Example 2:** + +```yaml +build_job: + stage: build + script: exit 1 + +test_job: + stage: test + script: exit 0 + +rollback_job: + stage: deploy + script: exit 0 + when: on_failure +``` + +- `build_job` runs and fails. +- `test_job` is skipped. +- `rollback_job` runs because there is a failed job before. + +### Problem 4: The skipped and ignored states + +Let's assume that we solved the problem 3 and the "skipped" and "ignored" states are not different in DAG and STAGE. +How should they behave in general? Are they successful or not? Should "skipped" and "ignored" be different? +Let's examine some examples; + +**Example 4.1. The ignored status with manual jobs** + +```yaml +build: + stage: build + script: exit 0 + when: manual + allow_failure: true # by default + +test: + stage: test + script: exit 0 +``` + +- `build` is in the "manual" state but considered as "skipped" (ignored) for the pipeline processing. +- `test` runs because "skipped" is a successful state. + +Alternatively; + +```yaml +build1: + stage: build + script: exit 0 + when: manual + allow_failure: true # by default + +build2: + stage: build + script: exit 0 + +test: + stage: test + script: exit 0 +``` + +- `build1` is in the "manual" state but considered as "skipped" (ignored) for the pipeline processing. +- `build2` runs and succeeds. +- `test` runs because "success" + "skipped" is a successful state. + +**Example 4.2. The skipped status with when: on_failure** + +```yaml +build: + stage: build + script: exit 0 + when: on_failure + +test: + stage: test + script: exit 0 +``` + +- `build` is skipped because it's `when: on_failure` and its previous status is not "failed". +- `test` runs because "skipped" is a successful state. + +Alternatively; + +```yaml +build1: + stage: build + script: exit 0 + when: on_failure + +build2: + stage: build + script: exit 0 + +test: + stage: test + script: exit 0 +``` + +- `build1` is skipped because it's `when: on_failure` and its previous status is not "failed". +- `build2` runs and succeeds. +- `test` runs because "success" + "skipped" is a successful state. + +### Problem 5: The `dependencies` keyword + +The [`dependencies`](../../../ci/yaml/index.md#dependencies) keyword is used to define a list of jobs to fetch +[artifacts](../../../ci/yaml/index.md#artifacts) from. It is a shared responsibility with the `needs` keyword. +Moreover, they can be used together in the same job. We may not need to discuss all possible scenarios but this example +is enough to show the confusion; + +```yaml +test2: + script: exit 0 + dependencies: [test1] + needs: + - job: test1 + artifacts: false +``` + +### Information 1: Canceled jobs + +Are a canceled job and a failed job the same? They have many differences so we could easily say "no". +However, they have one similarity; they can be "allowed to fail". + +Let's define their differences first; + +- A canceled job; + - It is not a finished job. + - Canceled is a user requested interruption of the job. The intent is to abort the job or stop pipeline processing as soon as possible. + - We don't know the result, there is no artifacts, etc. + - Since it's never run, the `after_script` is not run. + - Its eventual state is "canceled" so no job can run after it. + - There is no `when: on_canceled`. + - Even `when: always` is not run. +- A failed job; + - It is a machine response of the CI system to executing the job content. It indicates that execution failed for some reason. + - It is equal answer of the system to success. The fact that something is failed is relative, + and might be desired outcome of CI execution, like in when executing tests that some are failing. + - We know the result and [there can be artifacts](../../../ci/yaml/index.md#artifactswhen). + - `after_script` is run. + - Its eventual state is "failed" so subsequent jobs can run depending on their `when` values. + - `when: on_failure` and `when: always` are run. + +**The one similarity is; they can be "allowed to fail".** + +```yaml +build: + stage: build + script: sleep 10 + allow_failure: true + +test: + stage: test + script: exit 0 + when: on_success +``` + +- If `build` runs and gets `canceled`, then `test` runs. +- If `build` runs and gets `failed`, then `test` runs. + +#### An idea on using `canceled` instead of `failed` for some cases + +There is another aspect. We often drop jobs with a `failure_reason` before they get executed, +for example when the namespace ran out of Compute Credits (CI minutes) or when limits are exceeded. +Dropping jobs in the `failed` state has been handy because we could communicate to the user the `failure_reason` +for better feedback. When canceling jobs for various reasons we don't have a way to indicate that. +We cancel jobs because the user ran out of Compute Credits while the pipeline was running, +or because the pipeline is auto-canceled by another pipeline or other reasons. +If we had a `stop_reason` instead of `failure_reason` we could use that for both cancelled and failed jobs +and we could also use the `canceled` status more appropriately. + +### Information 2: Empty state + +We [recently updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117856) the documentation of +[the `when` keyword](../../../ci/yaml/index.md#when) for clarification; + +> - `on_success`: Run the job only when no jobs in earlier stages fail or have `allow_failure: true`. +> - `on_failure`: Run the job only when at least one job in an earlier stage fails. + +For example; + +```yaml +test1: + when: on_success + script: exit 0 + # needs: [] would lead to the same result + +test2: + when: on_failure + script: exit 0 + # needs: [] would lead to the same result +``` + +- `test1` runs because there is no job failed in the previous stages. +- `test2` does not run because there is no job failed in the previous stages. + +The `on_success` means that "nothing failed", it does not mean that everything succeeded. +The same goes to `on_failure`, it does not mean that everything failed, but does mean that "something failed". +This semantic goes by a expectation that your pipeline succeeds, and this is happy path. +Not that your pipeline fails, because then it requires user intervention to fix it. + +## Technical expectations + +All proposals or future decisions must follow these goals; + +1. The `allow_failure` keyword must only responsible for marking **failed** jobs as "success with warning". + - Why: It should not have another responsibility, such as determining a manual job is a blocker or not. + - How: Another keyword will be introduced to control the blocker behavior of a manual job. +1. With `allow_failure`, **canceled** jobs must not be marked as "success with warning". + - Why: "canceled" is a different state than "failed". + - How: Canceled with `allow_failure: true` jobs will not be marked as "success with warning". +1. The `when` keyword must only answer the question "What's required to run?". And it must be the only source of truth + for deciding if a job should run or not. +1. The `when` keyword must not control if a job is added to the pipeline or not. + - Why: It is not its responsibility. + - How: Another keyword will be introduced to control if a job is added to the pipeline or not. +1. The "skipped" and "ignored" states must be reconsidered. + - TODO: We need to discuss this more. +1. A new keyword structure must be introduced to specify if a job is an "automatic", "manual", or "delayed" job. + - Why: It is not the responsibility of the `when` keyword. + - How: A new keyword will be introduced to control the behavior of a job. +1. The `needs` keyword must only control the order of the jobs. It must not be used to control the behavior of the jobs + or to decide if a job should run or not. The DAG and STAGE behaviors must be the same. + - Why: It leads to different behaviors and confuses users. + - How: The `needs` keyword will only define previous jobs, like stage does. +1. The `needs` and `dependencies` keywords must not be used together in the same job. + - Why: It is confusing. + - How: The `needs` and `dependencies` keywords will be mutually exclusive. + +## Proposal + +N/A + +## Design and implementation details + +N/A diff --git a/doc/architecture/blueprints/container_registry_metadata_database/index.md b/doc/architecture/blueprints/container_registry_metadata_database/index.md index a538910f553..243270afdb2 100644 --- a/doc/architecture/blueprints/container_registry_metadata_database/index.md +++ b/doc/architecture/blueprints/container_registry_metadata_database/index.md @@ -174,7 +174,7 @@ The diagram below illustrates the architecture of the database cluster: [Rate](https://gitlab.com/gitlab-org/container-registry/-/issues/94) and [size](https://gitlab.com/gitlab-org/container-registry/-/issues/61#note_446609886) requirements for the GitLab.com database were extrapolated based on the `dev.gitlab.org` registry and are available in the linked issues. -#### Self-Managed Instances +#### Self-managed instances By default, for self-managed instances, the registry will have a separate logical database in the same PostgreSQL instance/cluster as the GitLab database. However, it will be possible to configure the registry to use a separate instance/cluster if needed. diff --git a/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/index.md b/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/index.md index a73f6335218..0987b317af8 100644 --- a/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/index.md +++ b/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/index.md @@ -135,7 +135,7 @@ drivers, we could have the importer retry more time and for more errors. There's a risk we would retry several times on non-retryable errors, but since no writes are being made to object storage, this should not ultimately be harmful. -Additionally, implementing [Validate Self-Managed Imports](https://gitlab.com/gitlab-org/container-registry/-/issues/938) +Additionally, implementing [Validate self-managed imports](https://gitlab.com/gitlab-org/container-registry/-/issues/938) would perform a consistency check against a sample of images before and after import which would lead to greater consistency across all storage driver implementations. diff --git a/doc/architecture/blueprints/git_data_offloading/index.md b/doc/architecture/blueprints/git_data_offloading/index.md new file mode 100644 index 00000000000..44df2c9a09d --- /dev/null +++ b/doc/architecture/blueprints/git_data_offloading/index.md @@ -0,0 +1,221 @@ +--- +status: proposed +creation-date: "2023-05-19" +authors: [ "@jcai-gitlab", "@toon" ] +coach: [ ] +approvers: [ ] +owning-stage: "~devops::systems" +--- + +# Offload data to cheaper storage + +## Summary + +Managing Git data storage costs is a critical part of our business. Offloading +Git data to cheaper storage can save on storage cost. + +## Motivation + +At GitLab, we keep most Git data stored on SSDs to keep data access fast. This +makes sense for data that we frequently need to access. However, given that +storage costs scale with data growth, we can be a lot smarter about what kinds +of data we keep on SSDs and what kinds of data we can afford to offload to +cheaper storage. + +For example, large files (or in Git nomenclature, "blobs") are not frequently +modified since they are usually non-text files (images, videos, binaries, etc). +Often, [Git LFS](https://git-lfs.com/) is used for repositories that contain +these large blobs in order to avoid having to push a large file onto the Git +server. However, this relies on client side setup. + +Or, if a project is "stale" and hasn't been accessed in a long time, there is no +need to keep paying for fast storage for that project. + +Instead, we can choose to put **all** blobs of that stale project onto cheaper +storage. This way, the application still has access to the commit history and +trees so the project browsing experience is not affected, but all files are on +slower storage since they are rarely accessed. + +If we had a way to separate Git data into different categories, we could then +offload certain data to a secondary location that is cheaper. For example, we +could separate large files that may not be accessed as frequently from the rest +of the Git data and save it to an HDD rather than an SDD mount. + +## Requirements + +There are a set of requirements and invariants that must be given for any +particular solution. + +### Saves storage cost + +Ultimately, this solution needs to save on storage cost. Separating out certain +Git data for cheaper storage can go towards this savings. + +We need to evaluate the solution's added cost against the projected savings from +offloading data to cheaper storage. Here are some criteria to consider: + +- How much money would we save if all large blobs larger than X were put on HDD? +- How much money would we save if all stale projects had their blobs on HDD? +- What's the operational overhead for running the offloading mechanism in terms + of additional CPU/Memory cost? +- What's the network overhead? e.g. is there an extra roundtrip to a different + node via the network to retrieve large blobs. +- Access cost, e.g. when blobs would be stored in an object store. + +### Opaque to downstream consumers of Gitaly + +This feature is purely storage optimization and, except for potential +performance slowdown, shouldn't affect downstream consumers of Gitaly. For +example, the GitLab application should not have to change any of its logic in +order to support this feature. + +This feature should be completely invisible to any callers of Gitaly. Rails or +any consumer should not need to know about this or manage it in any way. + +### Operationally Simple + +When working with Git data, we want to keep things as simple as possible to +minimize risk of repository corruption. Keep things operationally simple and +keep moving pieces outside of Git itself to a minimum. Any logic that modifies +repository data should be upstreamed in Git itself. + +## Proposal + +We will maintain a separate object database for each repository connected +through the [Git alternates mechansim](https://git-scm.com/docs/gitrepository-layout#Documentation/gitrepository-layout.txt-objects). +We can choose to filter out certain Git objects for this secondary object +database (ODB). + +Place Git data into this secondary ODB based on a filter. We have +options based on [filters in Git](https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---filterltfilter-specgt). + +We can choose to place large blobs based on some limit into a secondary ODB, or +we can choose to place all blobs onto the secondary ODB. + +## Design and implementation details + +### Git + +We need to add a feature to `git-repack(1)` that will allow us to segment +different kinds of blobs into different object databases. We're tracking this +effort in [this issue](https://gitlab.com/gitlab-org/git/-/issues/159). + +### Gitaly + +During Gitaly housekeeping, we can do the following: + +1. Use `git-repack(1)` to write packfiles into both the main repository's object + database, and a secondary object database. Each repository has its own + secondary object database for offloading blobs based on some criteria. +1. Ensure the `.git/objects/info/alternates` file points to the secondary + object database from step (1). + +### Criteria + +Whether objects are offloaded to another object database can be determined based +on one or many of the following criteria. + +#### By Tier + +Free projects might have many blobs offloaded to cheaper storage, while Ultimate +projects have all their objects placed on the fastest storage. + +#### By history + +If a blob was added a long time ago and is not referred by any recent commit it +can get offloaded, while new blobs remain on the main ODB. + +#### By size + +Large blobs are a quick win to reduce the expensive storage size, so they might +get prioritized to move to cheaper storage. + +#### Frequency of Access + +Frequently used project might remain fully on fast storage, while inactive +projects might have their blob offloaded. + +### Open Questions + +#### How do we delete objects? + +When we want to delete an unreachable object, the repack would need to be aware +of both ODBs and be able to evict unreachable objects regardless of whether +the objects are in the main ODB or in the secondary ODB. This picture is +complicated if the main ODB also has an [object pool](https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/object_pools.md) +ODB, since we wouldn't ever want to delete an object from the pool ODB. + +#### Potential Solution: Modify Git to delete an object from alternates + +We would need to modify repack to give it the ability to delete unreachable +objects in alternate ODBs. We could add repack configs `repack.alternates.*` +that tell it how to behave with alternate directories. For example, we could +have `repack.alternates.explodeUnreachable`, which indicates to repack that it +should behave like `-A` in any alternate ODB it is linked to. + +#### How does this work with object pools? + +When we use alternates, how does this interact with object pools? Does the +object pool also offload data to secondary storage? Does the object pool member? +In the most complex case this means that a single repository has four different +object databases, which may increase complexity. + +Possibly we can mark some packfiles as "keep", using the +[--keep-pack](https://git-scm.com/docs/git-pack-objects#Documentation/git-pack-objects.txt---keep-packltpack-namegt) +and +[--honor-pack-keep](https://git-scm.com/docs/git-pack-objects#Documentation/git-pack-objects.txt---honor-pack-keep) +options. + +#### Potential Solution: Do not allow object pools to offload their blobs + +For the sake of not adding too much complexity, we could decide that object +pools will not offload their blobs. Instead, we can design housekeeping to +offload blobs from the repository before deduplicating with the object pool. +Theoretically, this means that offloaded blobs will not end up in the object +pool. + +#### How will this work with Raft + WAL? + +How will this mechanism interact with Raft and the write-ahead log? + +The WAL uses hard-links and copy-free moves, to avoid slow copy operations. But +that does not work across different file systems. At some point repacks and such +will likely also go through the log. Transferring data between file systems can +lead to delays in transaction processing. + +Ideally we keep the use of an alternate internal to the node and not have to +leak this complexity to the rest of the cluster. This is a challenge, given we +have to consider available space when making placement decisions. It's possible +to keep this internal by only showing the lower capacity of the two storages, +but that could also lead to inefficient storage use. + +## Problems with the design + +### Added complexity + +The fact that we are adding another object pool to the mix adds complexity to +the system, and especially with repository replication since we are adding yet +another place to replicate data to. + +### Possible change in cost over time + +The cost of the different storage types might change over time. To anticipate +for this, it should be easy to adapt to such changes. + +### More points of failure + +Having some blobs on a separate storage device adds one more failure scenario +where the device hosting the large blobs may fail. + +## Alternative Solutions + +### Placing entire projects onto cheaper storage + +Instead of placing Git data onto cheaper storage, the Rails application could +choose to move a project in its entirety to a mounted HDD drive. + +#### Possible optimization + +Giving these machines with cheaper storage extra RAM might help to deal with the +slow read/write speeds due to the use of page cache. It's not sure though this +will turn out to be cheaper overall. diff --git a/doc/architecture/blueprints/gitaly_adaptive_concurrency_limit/adaptive_concurrency_limit_flow.png b/doc/architecture/blueprints/gitaly_adaptive_concurrency_limit/adaptive_concurrency_limit_flow.png Binary files differnew file mode 100644 index 00000000000..0475a32e933 --- /dev/null +++ b/doc/architecture/blueprints/gitaly_adaptive_concurrency_limit/adaptive_concurrency_limit_flow.png diff --git a/doc/architecture/blueprints/gitaly_adaptive_concurrency_limit/index.md b/doc/architecture/blueprints/gitaly_adaptive_concurrency_limit/index.md new file mode 100644 index 00000000000..89606cdc8fa --- /dev/null +++ b/doc/architecture/blueprints/gitaly_adaptive_concurrency_limit/index.md @@ -0,0 +1,372 @@ +--- +status: proposed +creation-date: "2023-05-30" +authors: [ "@qmnguyen0711" ] +approvers: [ ] +owning-stage: "~devops::enablement" +--- + +# Gitaly Adaptive Concurrency Limit + +## Summary + +Gitaly, a Git server, needs to push back on its clients to reduce the risk of +incidents. In the past, we introduced per-RPC concurrency limit and pack-objects +concurrency limit. Both systems were successful, but the configurations were +static, leading to some serious drawbacks. This blueprint proposes an adaptive +concurrency limit system to overcome the drawbacks of static limits. The +algorithm primarily uses the [Additive Increase/Multiplicative Decrease](https://en.wikipedia.org/wiki/Additive_increase/multiplicative_decrease) +approach to gradually increase the limit during normal processing but quickly +reduce it during an incident. The algorithm focuses on lack of resources and +serious latency degradation as criteria for determining when Gitaly is in +trouble. + +## Motivation + +To reduce the risk of incidents and protect itself, Gitaly should be able to +push back on its clients when it determines some limits have been reached. In +the [prior attempt](https://Gitlab.com/groups/Gitlab-org/-/epics/7891), we laid +out some foundations for [backpressure](https://Gitlab.com/Gitlab-org/Gitaly/-/blob/382d1e57b2cf02763d3d65e31ff4d38f467b797c/doc/backpressure.md) +by introducing two systems: per-RPC concurrency limits and pack-objects +concurrency limits. + +Per-RPC concurrency limits allows us to configure a maximum amount of in-flight +requests simultaneously. It scopes the limit by RPC and repository. Pack-objects +concurrency limit restricts the concurrent Git data transfer request by IP. One +note, the pack-objects concurrency limit is applied on cache misses, only. If +this limit is exceeded, the request is either put in a queue or rejected if the +queue is full. If the request remains in the queue for too long, it will also be +rejected. + +Although both of them yielded promising results on GitLab.com, the +configurations, especially the value of the concurrency limit, are static. There +are some drawbacks to this: + +- It's tedious to maintain a sane value for the concurrency limit. Looking at +this [production configuration](https://gitlab.com/gitlab-com/gl-infra/chef-repo/-/blob/db11ef95859e42d656bb116c817402635e946a32/roles/gprd-base-stor-gitaly-common.json), +each limit is heavily calibrated based on clues from different sources. When the +overall scene changes, we need to tweak them again. +- Static limits are not good for all usage patterns. It's not feasible to pick a +fit-them-all value. If the limit is too low, big users will be affected. If the +value is too loose, the protection effect is lost. +- A request may be rejected even though the server is idle as the rate is not +necessarily an indicator of the load induced on the server. + +To overcome all of those drawbacks while keeping the benefits of concurrency +limiting, one promising solution is to make the concurrency limit adaptive to +the currently available processing capacity of the node. We call this proposed +new mode "Adaptive Concurrency Limit". + +## Goals + +- Make Gitaly smarter in push-back traffic when it's under heavy load, thus enhancing the reliability and resiliency of Gitaly. +- Minimize the occurrences of Gitaly saturation incidents. +- Decrease the possibility of clients inaccurately reaching the concurrency limit, thereby reducing the ResourceExhausted error rate. +- Facilitate seamless or fully automated calibration of the concurrency limit. + +## Non-goals + +- Increase the workload or complexity of the system for users or administrators. The adaptiveness proposed here aims for the opposite. + +## Proposal + +The proposed Adaptive Concurrency Limit algorithm primarily uses the Additive +Increase/Multiplicative Decrease ([AIMD](https://en.wikipedia.org/wiki/Additive_increase/multiplicative_decrease)) +approach. This method involves gradually increasing the limit during normal +process functioning but quickly reducing it when an issue (backoff event) +occurs. There are various criteria for determining whether Gitaly is in trouble. +In this proposal, we focus on two things: + +- Lack of resources, particularly memory and CPU, which are essential for +handling Git processes. +- Serious latency degradation. + +The proposed solution is heavily inspired by many materials about this subject +shared by folks from other companies in the industry, especially the following: + +- TCP Congestion Control ([RFC-2581](https://www.rfc-editor.org/rfc/rfc2581), [RFC-5681](https://www.rfc-editor.org/rfc/rfc5681), +[RFC-9293](https://www.rfc-editor.org/rfc/rfc9293.html#name-tcp-congestion-control), [Computer Networks: A Systems Approach](https://book.systemsapproach.org/congestion/tcpcc.html)). +- Netflix adaptive concurrency limit ([blog post](https://tech.olx.com/load-shedding-with-nginx-using-adaptive-concurrency-control-part-1-e59c7da6a6df) +and [implementation](https://github.com/Netflix/concurrency-limits)) +- Envoy Adaptive Concurrency +([doc](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/adaptive_concurrency_filter#config-http-filters-adaptive-concurrency)) + +We cannot blindly apply a solution without careful consideration and expect it +to function flawlessly. The suggested approach considers Gitaly's specific +constraints and distinguishing features, including cgroup utilization and +upload-pack RPC, among others. + +The proposed solution does not aim to replace the existing [Gitaly concurrency +limit][Gitlay-backpressure], but automatically tweak its parameters. This means +that other aspects, such as queuing, in-queue timeout, queue length, +partitioning, and scoping, will remain unchanged. The proposed solution only +focuses on modifying the current **value** of the concurrency limit. + +## Design and implementation details + +### AIMD Algorithm + +The Adaptive Concurrency Limit algorithm primarily uses the Additive +Increase/Multiplicative Decrease ([AIMD](https://en.wikipedia.org/wiki/Additive_increase/multiplicative_decrease)) +approach. This method involves gradually increasing the limit during normal +process functioning but quickly reducing it when an issue occurs. + +During initialization, we configure the following parameters: + +- `initialLimit`: Concurrency limit to start with. This value is essentially +equal to the current static concurrency limit. +- `maxLimit`: Maximum concurrency limit. +- `minLimit`: Minimum concurrency limit so that the process is considered as +functioning. If it's equal to 0, it rejects all upcoming requests. +- `backoffFactor`: how fast the limit decreases when a backoff event occurs (`0 +< backoff < 1`, default to `0.75`) + +When the Gitaly process starts, it sets `limit = initialLimit`, in which `limit` +is the maximum in-flight requests allowed at a time. + +Periodically, maybe once per 15 seconds, the value of the `limit` is +re-calibrated: + +- `limit = limit + 1` if there is no backoff event since the last +calibration. The new limit cannot exceed `maxLimit`. +- `limit = limit * backoffFactor` otherwise. The new limit cannot be lower than +`minLimit`. + +When a process can no longer handle requests or will not be able to handle them +soon, it is referred to as a back-off event. Ideally, we would love to see the +efficient state as long as possible. It's the state where Gitaly is at its +maximum capacity. + + + +Ideally, min/max values are safeguards that aren't ever meant to be hit during +operation, even overload. In fact, hitting either probably means that something +is wrong and the dynamic algorithms aren't working well enough. + +### How requests are handled + +The concurrency limit restricts the total number of in-flight requests (IFR) at +a time. + +- When `IFR < limit`, Gitaly handles new requests without waiting. After an +increment, Gitaly immediately handles the subsequent request in the queue, if +any. +- When `IFR = limit`, it means the limit is reached. Subsequent requests are +queued, waiting for their turn. If the queue length reaches a configured limit, +Gitaly rejects new requests immediately. When a request stays in the queue long +enough, it is also automatically dropped by Gitaly. +- When `IRF > limit`, it's appropriately a consequence of backoff events. It +means Gitaly handles more requests than the newly appointed limits. In addition +to queueing upcoming requests similarly to the above case, Gitaly may start +load-shedding in-flight requests if this situation is not resolved long enough. + +At several points in time we have discussed whether we want to change queueing +semantics. Right now we admit queued processes from the head of the queue +(FIFO), whereas it was proposed several times that it might be preferable to +admit processes from the back (LIFO). + +Regardless of the rejection reason, the client received a `ResourceExhausted` +response code as a signal that they would back off and retry later. Since most +direct clients of Gitaly are internal, especially GitLab Shell and Workhorse, +the actual users received some friendly messages. Gitaly can attach +[exponential pushback headers](https://Gitlab.com/Gitlab-org/Gitaly/-/issues/5023) +to force internal clients to back off. However, that's a bit brutal and may lead +to unexpected results. We can consider that later. + +### Backoff events + +Each system has its own set of signals, and in the case of Gitaly, there are two +aspects to consider: + +- Lack of resources, particularly memory and CPU, which are essential for +handling Git processes like `git-pack-objects(1)`. When these resources are limited +or depleted, it doesn't make sense for Gitaly to accept more requests. Doing so +would worsen the saturation, and Gitaly addresses this issue by applying cgroups +extensively. The following section outlines how accounting can be carried out +using cgroup. +- Serious latency degradation. Gitaly offers various RPCs for different purposes +besides serving Git data that is hard to reason about latencies. A significant +overall latency decline is an indication that Gitaly should not accept more +requests. Another section below describes how to assert latency degradation +reasonably. + +Apart from the above signals, we can consider adding more signals in the future +to make the system smarter. Some examples are Go garbage collector statistics, +networking stats, file descriptors, etc. Some companies have clever tricks, such +as [using time drifting to estimate CPU saturation](https://engineering.linkedin.com/blog/2022/hodor--detecting-and-addressing-overload-in-linkedin-microservic). + +#### Backoff events of Upload Pack RPCs + +Upload Pack RPCs and their siblings PackObjects RPC are unique to Gitaly. They +are for the heaviest operations: transferring large volumes of Git data. Each +operation may take minutes or even hours to finish. The time span of each +operation depends on multiple factors, most notably the number of requested +objects and the internet speed of clients. + +Thus, latency is a poor signal for determining the backoff event. This type of +RPC should only depend on resource accounting at this stage. + +#### Backoff events of other RPCs + +As stated above, Gitaly serves various RPCs for different purposes. They can +also vary in terms of acceptable latency as well as when to recognize latency +degradation. Fortunately, the current RPC concurrency limits implementation +scopes the configuration by RPC and repository individually. The latency signal +makes sense in this setting. + +Apart from latency, resource usage also plays an important role. Hence, other +RPCs should use both latency measurement and resource accounting signals. + +### Resource accounting with cgroup + +The issue with saturation is typically not caused by Gitaly, itself but rather by the +spawned Git processes that handle most of the work. These processes are contained +within a [cgroup](https://Gitlab.com/Gitlab-org/Gitaly/-/blob/382d1e57b2cf02763d3d65e31ff4d38f467b797c/doc/cgroups.md), +and the algorithm for bucketing cgroup can be +found [here](https://Gitlab.com/Gitlab-org/Gitaly/-/blob/382d1e57b2cf02763d3d65e31ff4d38f467b797c/internal/cgroups/v1_linux.go#L166-166). +Typically, Gitaly selects the appropriate cgroup for a request based on the +target repository. There is also a parent cgroup to which all repository-level +cgroups belong to. + +Cgroup statistics are widely accessible. Gitaly can trivially fetch both +resource capacity and current resource consumption via the following information +in [cgroup control file](https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt): + +- `memory.limit_in_bytes` +- `memory.usage_in_bytes` +- `cpu.cfs_period_us` +- `cpu.cfs_quota_us` +- `cpuacct.usage` + +Fetching those statistics may imply some overheads. It's not necessary to keep +them updated in real-time. Thus, they can be processed periodically in the limit +adjustment cycle. + +In the past, cgroup has been reliable in preventing spawned processes from +exceeding their limits. It is generally safe to trust cgroup and allow processes +to run without interference. However, when the limits set by cgroup are reached +(at 100%), overloading can occur. This often leads to a range of issues such as +an increase in page faults, slow system calls, memory allocation problems, and +even out-of-memory kills. The consequences of such incidents are +highlighted in +[this example](https://Gitlab.com/Gitlab-com/gl-infra/production/-/issues/8713#note_1352403481). Inflight requests are significantly impacted, resulting in unacceptable delays, +timeouts, and even cancellations. + +Besides, through various observations in the past, some Git processes such as +`git-pack-objects(1)` build up memory over time. When a wave of `git-pull(1)` +requests comes, the node can be easily filled up with various memory-hungry +processes. It's much better to stop this accumulation in the first place. + +As a result, to avoid overloading, Gitaly employs a set of soft limits, such as +utilizing only 75% of memory capacity and 90% of CPU capacity instead of relying +on hard limits. Once these soft limits are reached, the concurrency adjuster +reduces the concurrency limit in a multiplicative manner. This strategy ensures +that the node has enough headroom to handle potential overloading events. + +In theory, the cgroup hierarchy allows us to determine the overloading status +individually. Thus, Gitaly can adjust the concurrency limit for each repository +separately. However, this approach would be unnecessarily complicated in +practice. In contrast, it may lead to confusion for operators later. + +As a good start, Gitaly recognizes an overloading event in _either_ condition: + +- Soft limits of the parent cgroup are reached. +- Soft limits of **any** of the repository cgroup are reached + +It is logical for the second condition to be in place since a repository's +capacity limit can be significant to the parent cgroup's capacity. This means +that when the repository cgroup reaches its limit, fewer resources are available +for other cgroups. As a result, reducing the concurrency limit delays the +occurrence of overloading. + +#### Latency measurement + +When re-calibrate the concurrency limit, latency is taken into account for RPCs +other than Upload Pack. Two things to consider when measuring latencies: + +- How to record latencies +- How to recognize a latency degradation + +It is clear that a powerful gRPC server such as Gitaly has the capability to +manage numerous requests per second per node. A production server can serve up +to thousands of requests per second. Keeping track and storing response times in +a precise manner is not practical. + +The heuristic determining whether the process is facing latency degradation is +interesting. The most naive solution is to pre-define a static latency +threshold. Each RPC may have a different threshold. Unfortunately, similar to +static concurrency limiting, it's challenging and tedious to pick a reasonable +up-to-date value. + +Fortunately, there are some famous algorithms for this line of problems, mainly +applied in the world of TCP Congestion Control: + +- Vegas Algorithm ([CN: ASA - Chapter 6.4](https://book.systemsapproach.org/congestion/avoidance.html), [Reference implementation](https://Github.com/Netflix/concurrency-limits/blob/master/concurrency-limits-core/src/main/java/com/netflix/concurrency/limits/limit/VegasLimit.java)) +- Gradient Algorithm ([Paper](https://link.springer.com/chapter/10.1007/978-3-642-20798-3_25), [Reference implementation](https://Github.com/Netflix/concurrency-limits/blob/master/concurrency-limits-core/src/main/java/com/netflix/concurrency/limits/limit/Gradient2Limit.java)) + +The two algorithms are capable of automatically determining the latency +threshold without any pre-defined configuration. They are highly efficient and +statistically reliable for real-world scenarios. In my opinion, both algorithms +are equally suitable for our specific use case. + +### Load-shedding + +Gitaly being stuck in the overloaded situation for too long can be denoted by +two signs: + +- A certain amount of consecutive backoff events +- More in-flight requests than concurrency limit for a certain amount of them + +In such cases, a particular cgroup or the whole Gitaly node may become +unavailable temporarily. In-flight requests are likely to either be canceled or +timeout. On GitLab.com production, an incident is triggered and called for human +intervention. We can improve this situation by load-shedding. + +This mechanism deliberately starts to kill in-flight requests selectively. The +main purpose is to prevent cascading failure of all inflight requests. +Hopefully, after some of them are dropped, the cgroup/node can recover back to +the normal situation fast without human intervention. As a result, it leads to +net availability and resilience improvement. + +Picking which request to kill is tricky. In many systems, request criticality is +considered. A request from downstream is assigned with a criticality point. +Requests with lower points are targeted first. Unfortunately, GitLab doesn't +have a similar system. We have an +[Urgency system](https://docs.Gitlab.com/ee/development/application_slis/rails_request.html), +but it is used for response time committing rather than criticality. + +As a replacement, we can prioritize requests harming the system the most. Some +criteria to consider: + +- Requests consuming a significant percentage of memory +- Requests consuming a significant of CPU over time +- Slow clients +- Requests from IPs dominating the traffic recently +- In-queue requests/requests at an early stage. We don’t want to reject requests that are almost finished. + +To get started, we can pick the first two criteria first. The list can be +reinforced when learning from production later. + +## References + +- Linkedin HODOR system + - [https://www.youtube.com/watch?v=-haM4ZpYNko](https://www.youtube.com/watch?v=-haM4ZpYNko) + - [https://engineering.linkedin.com/blog/2022/hodor--detecting-and-addressing-overload-in-linkedin-microservic](https://engineering.linkedin.com/blog/2022/hodor--detecting-and-addressing-overload-in-linkedin-microservic) +- [https://engineering.linkedin.com/blog/2023/hodor--overload-scenarios-and-the-evolution-of-their-detection-a](https://engineering.linkedin.com/blog/2023/hodor--overload-scenarios-and-the-evolution-of-their-detection-a) +- Google SRE chapters about load balancing and overload: + - [https://sre.google/sre-book/load-balancing-frontend/](https://sre.google/sre-book/load-balancing-frontend/) + - [https://sre.google/sre-book/load-balancing-datacenter/](https://sre.google/sre-book/load-balancing-datacenter/) + - [https://sre.google/sre-book/handling-overload/](https://sre.google/sre-book/handling-overload/) + - [https://sre.google/sre-book/addressing-cascading-failures/](https://sre.google/sre-book/addressing-cascading-failures/) + - [https://sre.google/workbook/managing-load/](https://sre.google/workbook/managing-load/) +- [Netflix Performance Under Load](https://netflixtechblog.medium.com/performance-under-load-3e6fa9a60581) +- [Netflix Adaptive Concurrency Limit](https://Github.com/Netflix/concurrency-limits) +- [Load Shedding with NGINX using adaptive concurrency control](https://tech.olx.com/load-shedding-with-nginx-using-adaptive-concurrency-control-part-1-e59c7da6a6df) +- [Overload Control for Scaling WeChat Microservices](http://web1.cs.columbia.edu/~junfeng/papers/dagor-socc18.pdf) +- [ReactiveConf 2019 - Jay Phelps: Backpressure: Resistance is NOT Futile](https://www.youtube.com/watch?v=I6eZ4ZyI1Zg) +- [AWS re:Invent 2021 - Keeping Netflix reliable using prioritized load shedding](https://www.youtube.com/watch?v=TmNiHbh-6Wg) +- [AWS Using load shedding to avoid overload](https://aws.amazon.com/builders-library/using-load-shedding-to-avoid-overload/) +- ["Stop Rate Limiting! Capacity Management Done Right" by Jon Moore](https://www.youtube.com/watch?v=m64SWl9bfvk) +- [Using load shedding to survive a success disaster—CRE life lessons](https://cloud.google.com/blog/products/gcp/using-load-shedding-to-survive-a-success-disaster-cre-life-lessons) +- [Load Shedding in Web Services](https://medium.com/helpshift-engineering/load-shedding-in-web-services-9fa8cfa1ffe4) +- [Load Shedding in Distributed Systems](https://blog.sofwancoder.com/load-shedding-in-distributed-systems) diff --git a/doc/architecture/blueprints/gitlab_ci_events/index.md b/doc/architecture/blueprints/gitlab_ci_events/index.md index fb78c0f5d9d..51d65869dfb 100644 --- a/doc/architecture/blueprints/gitlab_ci_events/index.md +++ b/doc/architecture/blueprints/gitlab_ci_events/index.md @@ -44,7 +44,37 @@ Events" blueprint is about making it possible to: 1. Describe technology required to match subscriptions with events at GitLab.com scale and beyond. 1. Describe technology we could use to reduce the cost of running automation jobs significantly. -## Proposals +## Proposal + +### Requirements + +Any accepted proposal should take in consideration the following requirements and characteristics: + +1. Defining events should be done in separate files. + - If we define all events in a single file, then the single file gets too complicated and hard to + maintain for users. Then, users need to separate their configs with the `include` keyword again and we end up + with the same solution. + - The structure of the pipelines, the personas and the jobs will be different depending on the events being + subscribed to and the goals of the subscription. +1. A single subscription configuration file should define a single pipeline that is created when an event is triggered. + - The pipeline config can include other files with the `include` keyword. + - The pipeline can have many jobs and trigger child pipelines or multi-project pipelines. +1. The events and handling syntax should use the existing CI config syntax where it is pragmatic to do so. + - It'll be easier for users to adapt. It'll require less work to implement. +1. The event subscription and emiting events should be performant, scalable, and non blocking. + - Reading from the database is usually faster than reading from files. + - A CI event can potentially have many subscriptions. + This also includes evaluating the right YAML files to create pipelines. + - The main business logic (e.g. creating an issue) should not be affected + by any subscriptions to the given CI event (e.g. issue created). +1. The CI events design should be implemented in a maintainable and extensible way. + - If there is a `issues/create` event, then any new event (`merge_request/created`) can be added without + much effort. + - We expect that many events will be added. It should be trivial for developers to + register domain events (e.g. 'issue closed') as GitLab-defined CI events. + - Also, we should consider the opportunity of supporting user-defined CI events long term (e.g. 'order shipped'). + +### Options For now, we have technical 5 proposals; diff --git a/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md b/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md index 6ac67dd0f18..6b1b4d452c9 100644 --- a/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md +++ b/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md @@ -8,7 +8,7 @@ owning-stage: "~devops::configure" participating-stages: [] --- -# GitLab to Kubernetes communication **(FREE)** +# GitLab to Kubernetes communication **(FREE ALL)** The goal of this document is to define how GitLab can communicate with Kubernetes and in-cluster services through the GitLab agent. diff --git a/doc/architecture/blueprints/modular_monolith/proof_of_concepts.md b/doc/architecture/blueprints/modular_monolith/proof_of_concepts.md index c215ffafbe4..7169e12a7b5 100644 --- a/doc/architecture/blueprints/modular_monolith/proof_of_concepts.md +++ b/doc/architecture/blueprints/modular_monolith/proof_of_concepts.md @@ -36,7 +36,7 @@ gRPC would carry messages between modules. ## Use Packwerk to enforce module boundaries Packwerk is a static analyzer that helps defining and enforcing module boundaries -in Ruby. +in Ruby. [In this PoC merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98801) we demonstrate a possible directory structure of the monolith broken down into separate diff --git a/doc/architecture/blueprints/observability_tracing/index.md b/doc/architecture/blueprints/observability_tracing/index.md index 4291683f83f..71e03d81bcf 100644 --- a/doc/architecture/blueprints/observability_tracing/index.md +++ b/doc/architecture/blueprints/observability_tracing/index.md @@ -135,7 +135,7 @@ All requests from GitLab.com will then include the GOB session cookie for observ The new UI will be built using the Pajamas Design System in accordance with GitLab UX design standards. The UI will interact with the GOB query service directly from vue.js (see architecture diagram above) by sending a fetch to the subdomain `observe.gitLab.com/v1/query` with `{withCredentials: true}`. See the Authentication and Authorization section above for more details on how this is enabled. -[**TODO Figma UI designs and commentary**] +**TODO Figma UI designs and commentary** ## Iterations diff --git a/doc/architecture/blueprints/organization/index.md b/doc/architecture/blueprints/organization/index.md index 2cfaf33ff50..09448d6d90c 100644 --- a/doc/architecture/blueprints/organization/index.md +++ b/doc/architecture/blueprints/organization/index.md @@ -34,7 +34,7 @@ Organizations solve the following problems: 1. Allows integration with Cells. Isolating Organizations makes it possible to allocate and distribute them across different Cells. 1. Removes the need to define hierarchies. An Organization is a container that could be filled with whatever hierarchy/entity set makes sense (Organization, top-level Groups, etc.) 1. Enables centralized control of user profiles. With an Organization-specific user profile, administrators can control the user's role in a company, enforce user emails, or show a graphical indicator that a user as part of the Organization. An example could be adding a "GitLab employee" stamp on comments. -1. Organizations bring an on-premise-like experience to SaaS (GitLab.com). The Organization admin will have access to instance-equivalent Admin Area settings with most of the configuration controlled on Organization level. +1. Organizations bring an on-premise-like experience to SaaS (GitLab.com). The Organization admin will have access to instance-equivalent Admin Area settings with most of the configuration controlled at the Organization level. ## Motivation @@ -68,13 +68,13 @@ graph TD ns[Namespace] -. has many .- ns[Namespace] ``` -Self-managed instances would set a default Organization. +All instances would set a default Organization. ### Benefits - No changes to URL's for Groups moving under an Organization, which makes moving around top-level Groups very easy. - Low risk rollout strategy, as there is no conversion process for existing top-level Groups. -- Organization becomes the key for identifying what is part of an Organization, which is likely on its own table for performance and clarity. +- Organization becomes the key for identifying what is part of an Organization, which is on its own table for performance and clarity. ### Drawbacks @@ -93,7 +93,7 @@ From an initial [data exploration](https://gitlab.com/gitlab-data/analytics/-/is - Most top-level Groups that are matched to organizations with more than one top-level Group are assumed to be intended to be combined into a single organization (82%). - Most top-level Groups that are matched to organizations with more than one top-level Group are using only a single pricing tier (59%). - Most of the current top-level Groups are set to public visibility (85%). -- Less than 0.5% of top-level Groups share Groups with another top-level Group. However, this means we could potentially break 76,000 links between top-level Groups by introducing the Organization. +- Less than 0.5% of top-level Groups share Groups with another top-level Group. However, this means we could potentially break 76,000 existing links between top-level Groups by introducing the Organization. Based on this analysis we expect to see similar behavior when rolling out Organizations. @@ -104,15 +104,15 @@ Based on this analysis we expect to see similar behavior when rolling out Organi The Organization MVC will contain the following functionality: - Instance setting to allow the creation of multiple Organizations. This will be enabled by default on GitLab.com, and disabled for self-managed GitLab. -- Every instance will have a default organization. Initially, all Users will be managed by this default Organization. +- Every instance will have a default Organization named `Default Organization`. Initially, all Users will be managed by this default Organization. - Organization Owner. The creation of an Organization appoints that User as the Organization Owner. Once established, the Organization Owner can appoint other Organization Owners. - Organization Users. A User is managed by one Organization, but can be part of multiple Organizations. Users are able to navigate between the different Organizations they are part of. - Setup settings. Containing the Organization name, ID, description, and avatar. Settings are editable by the Organization Owner. -- Setup flow. Users are able to build an Organization on top of an existing top-level Group. New Users are able to create an Organization from scratch and to start building top-level Groups from there. -- Visibility. Options will be `public` and `private`. A Non-User of a specific Organization will not see private Organizations in the explore section. Visibility is editable by the Organization Owner. +- Setup flow. Users are able to build new Organizations and transfer existing top-level Groups into them. They can also create new top-level Groups in an Organization. +- Visibility. Initially, Organizations can only be `public`. Public Organizations can be seen by everyone. They can contain public and private Groups and Projects. - Organization settings page with the added ability to remove an Organization. Deletion of the default Organization is prevented. -- Groups. This includes the ability to create, edit, and delete Groups, as well as a Groups overview that can be accessed by the Organization Owner. -- Projects. This includes the ability to create, edit, and delete Projects, as well as a Projects overview that can be accessed by the Organization Owner. +- Groups. This includes the ability to create, edit, and delete Groups, as well as a Groups overview that can be accessed by the Organization Owner and Users. +- Projects. This includes the ability to create, edit, and delete Projects, as well as a Projects overview that can be accessed by the Organization Owner and Users. ### Organization Access @@ -127,7 +127,7 @@ Organization Users can get access to Groups and Projects as: Organization Users can be managed in the following ways: - As [Enterprise Users](../../../user/enterprise_user/index.md), managed by the Organization. This includes control over their User account and the ability to block the User. -- As Non-Enterprise Users, managed by the Default Organization. Non-Enterprise Users can be removed from an Organization, but the User keeps ownership of their User account. +- As Non-Enterprise Users, managed by the default Organization. Non-Enterprise Users can be removed from an Organization, but the User keeps ownership of their User account. Enterprise Users are only available to Organizations with a Premium or Ultimate subscription. Organizations on the free tier will only be able to host Non-Enterprise Users. @@ -141,10 +141,33 @@ Users are visible across all Organizations. This allows Users to move between Or - Being invited by email address - Requesting access. This requires visibility of the Organization and Namespace and must be accepted by the owner of the Namespace. Access cannot be requested to private Groups or Projects. -1. Becoming an Enterprise Users of an Organization. Bringing Enterprise Users to the Organization level is planned post MVC. +1. Becoming an Enterprise User of an Organization. Bringing Enterprise Users to the Organization level is planned post MVC. For the Organization MVC Enterprise Users will remain at the top-level Group. + +The creator of an Organization automatically becomes the Organization Owner. It is not necessary to become a User of a specific Organization to comment on or create public issues, for example. All existing Users can create and comment on all public issues. ##### When can Users see an Organization? +For the MVC, an Organization can only be public. Public Organizations can be seen by everyone. They can contain public and private Groups and Projects. + +In the future, Organizations will get an additional internal visibility setting for Groups and Projects. This will allow us to introduce internal Organizations that can only be seen by the Users it contains. This would mean that only Users that are part of the Organization will see: + +- The Organization front page, instead of a 404 when navigating the Organization URL +- Name of the organization +- Description of the organization +- Organization pages, such as the Activity page, Groups, Projects and Users overview + +Content of these pages will be determined by each User's access to specific Groups and Projects. For instance, private Projects would only be seen by the members of this Project in the Project overview. + +As an end goal, we plan to offer the following scenarios: + +| Organization visibility | Group/Project visibility | Who sees the Organization? | Who sees Groups/Projects? | +| ------ | ------ | ------ | ------ | +| public | public | Everyone | Everyone | +| public | internal | Everyone | Organization Users | +| public | private | Everyone | Group/Project members | +| internal | internal | Organization Users | Organization Users | +| internal | private | Organization Users | Group/Project members | + ##### What can Users see in an Organization? Users can see the things that they have access to in an Organization. For instance, an Organization User would be able to access only the private Groups and Projects that they are a Member of, but could see all public Groups and Projects. Actionable items such as issues, merge requests and the to-do list are seen in the context of the Organization. This means that a User might see 10 merge requests they created in `Organization A`, and 7 in `Organization B`, when in total they have created 17 merge requests across both Organizations. @@ -176,9 +199,9 @@ graph TD F[ProjectMember] <-.type of.- D G -.has many.-> E -.belongs to.-> A - GGL[GroupGroupLink<br/> See note 1] -.belongs_to.->A - PGL[ProjectGroupLink<br/> See note 2] -.belongs_to.->A - PGL -.belongs_to.->C + GGL[GroupGroupLink] -.belongs to.->A + PGL[ProjectGroupLink] -.belongs to.->A + PGL -.belongs to.->C ``` GroupGroupLink is the join table between two Group records, indicating that one Group has invited the other. @@ -207,43 +230,72 @@ Actions such as banning and deleting a User will be added to the Organization at Non-Users are external to the Organization and can only access the public resources of an Organization, such as public Projects. +### Roles and Permissions + +Organizations will have an Owner role. Compared to Users, they can perform the following actions: + +| Action | Owner | User | +| ------ | ------ | ----- | +| View Organization settings | ✓ | | +| Edit Organization settings | ✓ | | +| Delete Organization | ✓ | | +| Remove Users | ✓ | | +| View Organization front page | ✓ | ✓ | +| View Groups overview | ✓ | ✓ (1) | +| View Projects overview | ✓ | ✓ (1) | +| View Users overview | ✓ | ✓ (2) | +| Transfer top-level Group into Organization if Owner of both | ✓ | | + +(1) Users can only see what they have access to. +(2) Users can only see Users from Groups and Projects they have access to. + +[Roles](../../../user/permissions.md) at the Group and Project level remain as they currently are. + ### Routing Today only Users, Projects, Namespaces and container images are considered routable entities which require global uniqueness on `https://gitlab.com/<path>/-/`. Initially, Organization routes will be [unscoped](../../../development/routing.md). Organizations will follow the path `https://gitlab.com/-/organizations/org-name/` as one of the design goals is that the addition of Organizations should not change existing Group and Project paths. ### Impact of the Organization on Other Features -We want a minimal amount of infrequently written tables in the shared database. If we have high write volume or large amounts of data in the shared database then this can become a single bottleneck for scaling and we lose the horizontal scalability objective of Cells. +We want a minimal amount of infrequently written tables in the shared database. If we have high write volume or large amounts of data in the shared database then this can become a single bottleneck for scaling and we lose the horizontal scalability objective of Cells. With isolation being one of the main requirements to make Cells work, this means that existing features will mostly be scoped to an Organization rather than work across Organizations. One exception to this are Users, which are stored in the cluster-wide shared database. For a deeper exploration of the impact on select features, see the [list of features impacted by Cells](../cells/index.md#impacted-features). ## Iteration Plan The following iteration plan outlines how we intend to arrive at the Organization MVC. We are following the guidelines for [Experiment, Beta, and Generally Available features](../../../policy/experiment-beta-support.md). -### Iteration 1: Organization Prototype (FY24Q2) +### Iteration 1: Organization Prototype (FY24Q3) -In iteration 1, we introduce the concept of an Organization as a way to Group top-level Groups together. Support for Organizations does not require any [Cells](../cells/index.md) work, but having them will make all subsequent iterations of Cells simpler. The goal of iteration 1 will be to generate a prototype that can be used by GitLab teams to test moving functionality to the Organization. It contains everything that is necessary to move an Organization to a Cell: +In iteration 1, we introduce the concept of an Organization as a way to group top-level Groups together. Support for Organizations does not require any [Cells](../cells/index.md) work, but having them will make all subsequent iterations of Cells simpler. The goal of iteration 1 will be to generate a prototype that can be used by GitLab teams to test basic functionality within an Organization. The prototype contains the following functionality: -- The Organization can be named, has an ID and an avatar. -- Only a Non-Enterprise User can be part of an Organization. +- A new Organization can be created. +- The Organization contains a name, ID, description and avatar. +- The creator of the Organization is assigned as the Organization Owner. +- Groups can be created in an Organization. Groups are listed in the Groups overview. Every Organization User can access the Groups overview and see the Groups they have access to. +- Projects can be created in a Group. Projects are listed in the Projects overview. Every Organization User can access the Projects overview and see the Projects they have access to. +- Both Enterprise and Non-Enterprise Users can be part of an Organization. +- Enterprise Users are still managed by top-level Groups. - A User can be part of multiple Organizations. -- A single Organization Owner can be assigned. -- Groups can be created in an Organization. Groups are listed in the Groups overview. -- Projects can be created in a Group. Projects are listed in the Projects overview. +- Users can navigate between the different Organizations they are part of. +- Any User within or outside of an Organization can be invited to Groups and Projects contained by the Organization. -### Iteration 2: Organization MVC Experiment (FY24Q3) +### Iteration 2: Organization MVC Experiment (FY24Q4) -In iteration 2, an Organization MVC Experiment will be released. We will test the functionality with a select set of customers and improve the MVC based on these learnings. Users will be able to build an Organization on top of their existing top-level Group. +In iteration 2, an Organization MVC Experiment will be released. We will test the functionality with a select set of customers and improve the MVC based on these learnings. The MVC Experiment contains the following functionality: -- The Organization has a description. +- Users are listed in the User overview. Every Organization User can access the User overview and see Users that are part of the Groups and Projects they have access to. - Organizations can be deleted. -- Users can navigate between the different Organizations they are part of. +- Forking across Organizations will be defined. ### Iteration 3: Organization MVC Beta (FY24Q4) -In iteration 3, the Organization MVC Beta will be released. +In iteration 3, the Organization MVC Beta will be released. Users will be able to transfer existing top-level Groups into an Organization. - Multiple Organization Owners can be assigned. -- Organization Owners can change the visibility of an organization between `public` and `private`. A Non-User of a specific Organization will not see private Organizations in the explore section. +- Organization avatars can be changed in the Organization settings. +- Organization Owners can create, edit and delete Groups from the Groups overview. +- Organization Owners can create, edit and delete Projects from the Projects overview. +- Top-level Groups can be transferred into an Organization. +- The Organization URL path can be changed. ### Iteration 4: Organization MVC GA (FY25Q1) @@ -253,7 +305,9 @@ In iteration 4, the Organization MVC will be rolled out. After the initial rollout of Organizations, the following functionality will be added to address customer needs relating to their implementation of GitLab: +1. [Organizations can invite Users](https://gitlab.com/gitlab-org/gitlab/-/issues/420166). 1. Internal visibility will be made available on Organizations that are part of GitLab.com. +1. Restrict inviting Users outside of the Organization. 1. Enterprise Users will be made available at the Organization level. 1. Organizations are able to ban and delete Users. 1. Projects can be created from the Organization-level Projects overview. @@ -270,6 +324,21 @@ After the initial rollout of Organizations, the following functionality will be ## Organization Rollout +We propose the following steps to successfully roll out Organizations: + +- Phase 1: Rollout + - Organizations will be rolled out using the concept of a `default Organization`. All existing top-level groups on GitLab.com are already part of this `default Organization`. The Organization UI is feature flagged and can be enabled for a specific set of users initially, and the global user pool at the end of this phase. This way, users will already become familiar with the concept of an Organization and the Organization UI. No features would be impacted by enabling the `default Organization`. See issue [#418225](https://gitlab.com/gitlab-org/gitlab/-/issues/418225) for more details. +- Phase 2: Migrations + - GitLab, the organization, will be the first one to bud off into a separate Organization. We move all top-level groups that belong to GitLab into the new GitLab Organization, including the `gitLab-org` and `gitLab-com` top-level Groups. See issue [#418228](https://gitlab.com/gitlab-org/gitlab/-/issues/418228) for more details. + - Existing customers can create their own Organization. Creation of an Organization remains optional. +- Phase 3: Onboarding changes + - New customers will only have the option to start their journey by creating an Organization. +- Phase 4: Targeted efforts + - Organizations are promoted, e.g. via a banner message, targeted conversations with large customers via the CSMs. Creating a separate Organization will remain a voluntary action. + - We increase the value proposition of the Organization, for instance by moving billing to the Organization level to provide incentives for more customers to move to a separate Organization. Adoption will be monitored. + +A force-option will only be considered if the we do not achieve the load distribution we are aiming for with Cells. + ## Alternative Solutions An alternative approach to building Organizations is to convert top-level Groups into Organizations. The main advantage of this approach is that features could be built on top of the Namespace framework and therewith leverage functionality that is already available at the Group level. We would avoid building the same feature multiple times. However, Organizations have been identified as a critical driver of Cells. Due to the urgency of delivering Cells, we decided to opt for the quickest and most straightforward solution to deliver an Organization, which is the lightweight design described above. More details on comparing the two Organization proposals can be found [here](https://gitlab.com/gitlab-org/tenant-scale-group/group-tasks/-/issues/56). @@ -282,5 +351,8 @@ An alternative approach to building Organizations is to convert top-level Groups ## Links - [Organization epic](https://gitlab.com/groups/gitlab-org/-/epics/9265) +- [Organization MVC design](https://gitlab.com/groups/gitlab-org/-/epics/10068) - [Enterprise Users](../../../user/enterprise_user/index.md) - [Cells blueprint](../cells/index.md) +- [Cells epic](https://gitlab.com/groups/gitlab-org/-/epics/7582) +- [Namespaces](../../../user/namespace/index.md) diff --git a/doc/architecture/blueprints/rate_limiting/index.md b/doc/architecture/blueprints/rate_limiting/index.md index f42a70aa97a..7af50097e97 100644 --- a/doc/architecture/blueprints/rate_limiting/index.md +++ b/doc/architecture/blueprints/rate_limiting/index.md @@ -186,6 +186,24 @@ Things we want to build and support by default: 1. Logging that will expose limits applied in Kibana. 1. An automatically generated documentation page describing all the limits. +### Support rate limits based on resources used + +One of the problems of our rate limiting system is that values are static +(e.g. 100 requests per minutes) and irrespective of the complexity or resources +used by the operation. For example: + +- Firing 100 requests per minute to fetch a simple resource can have very different + implications than creating a CI pipeline. +- Each pipeline creation action can perform very differently depending on the + pipeline being created (small MR pipeline VS large scheduled pipeline). +- Paginating resources after an offset of 1000 starts to become expensive on the database. + +We should allow some rate limits to be defiened as `computing score / period` where for +computing score we calculate the milliseconds accumulated (for all requests executed +and inflight) within a given period (for example: 1 minute). + +This way if a user is sending expensive requests they are likely to hit the rate limit earlier. + ### API to expose limits and policies Once we have an established a consistent way to define application limits we diff --git a/doc/architecture/blueprints/remote_development/index.md b/doc/architecture/blueprints/remote_development/index.md index ce55f23f828..c7d1ec29add 100644 --- a/doc/architecture/blueprints/remote_development/index.md +++ b/doc/architecture/blueprints/remote_development/index.md @@ -483,6 +483,40 @@ RestartRequested : User has requested a workspace restart.\n**desired_state** wi RestartRequested -left-> Running : status=Running ``` +## Injecting environment variables and files into a workspace + +Like CI, there is a need to inject environment variables and files into a workspace. These environment variables and files will be frozen in time during workspace creation to ensure the same values are injected into the workspace every time it starts/restarts. Thus, a new database table, on the lines of `ci_job_variables` will be required. This table will contain the following columns - + +- `key` - To store the name of the environment variable or the file. +- `encrypted_value` - To store the encrypted value of the environment variable or the file. +- `encrypted_value_iv` - To store the initialization vector used for encryption. +- `workspace_id` - To reference the workspace the environment variable or the file is to be injected into. +- `variable_type` - To store whether this data is to be injected as an environment variable or a file. + +To perform the encryption, a secret key would be required. This would be uniquely generated for each workpsace upon creation. +Having a unique secret key which is used for encrypting the corresponding workspace's environment variable and file data in the workspace, improves the security profile. + +Because of the nature of reconciliation loop between Agent and Rails, it is not scalable to decrypt these values at Rails side for each request. +Instead, the `key`, `encrypted_value` and `encrypted_value_iv` of each environment variable of the workspace are sent to the Agent along with the workspace's `secret_key` +for the Agent to decrypt them in place. + +To optimize this further, the data about the environment variables and files along with the secret key will only be sent when required i.e. + +- When new workspace creation request has been received from the user and an Agent initiates a Partial Reonciliation request +- When an Agent initiates a Full Reconciliation request + +When a workspace is created from a project, it will inherit all the variables from the group/subgroup/project hierarchy which are defined under +[`Settings > CI/CD > Variables`](../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui). This aspect will be generalized to allow for defining `Variables` +which will be inherited in both CI/CD and Workspaces. + +A user will also be able to define, at a user level, environment variables and files to be injected into each workspace created by them. + +When a new workspace is created, a new personal access token associated to the user who created the workspace will be generated. +This personal access token will be tied to the lifecycle of the workspace and will be injected into the workspace as an environment variable or a file +to allow for cloning private projects and supporting transparent Git operations from within the workspace out-of-the-box among other things. + +More details about the implementation details can be found in this [epic](https://gitlab.com/groups/gitlab-org/-/epics/10882). + ## Workspace user traffic authentication and authorization We need to only allow certain users to access workspaces. Currently, we are restricting this to the creator/owner of the workspace. After the workspace is created, it needs to be exposed to the network so that the user can connect to it. diff --git a/doc/architecture/blueprints/runner_admission_controller/index.md b/doc/architecture/blueprints/runner_admission_controller/index.md index d73ffb21ef3..92c824527ec 100644 --- a/doc/architecture/blueprints/runner_admission_controller/index.md +++ b/doc/architecture/blueprints/runner_admission_controller/index.md @@ -229,7 +229,7 @@ be rare in typical circumstances. ### Implementation Details -1. [placeholder for steps required to code the admissions controller MVC] +1. _placeholder for steps required to code the admissions controller MVC_ ## Technical issues to resolve diff --git a/doc/architecture/blueprints/ssh_certificates/index.md b/doc/architecture/blueprints/ssh_certificates/index.md new file mode 100644 index 00000000000..3cbe6711028 --- /dev/null +++ b/doc/architecture/blueprints/ssh_certificates/index.md @@ -0,0 +1,211 @@ +--- +status: ongoing +creation-date: "2023-07-28" +authors: [ "@igor.drozdov" ] +coach: "@stanhu" +approvers: [ ] +owning-stage: "~devops::create" +--- + +# SSH certificates + +## Summary + +On GitLab.com customers obtain their own top-level group (later organization). In comparison to self-managed, they have to manage organization-wide settings at this level. + +Currently, the provided Git access control options on SaaS (SSH, HTTPS) rely on credentials (access tokens, SSH keys) setup in the user profile. As the user profile is out of control of the organization, there is no way for a customer to assess whether the key is kept confidential or whether the expiry date is meeting policies. Also, there's very little that can be done for damage control in case the keys are leaked as well as a customer cannot enforce MFA on Git access flows. + +Customers may have processes in place, where developers on a daily basis can, via MFA, request a temporary SSH certificate which gives them access to internal systems. To enable the same way of working on SaaS, we would need a way to share public Certificate Authority (`CA`) files with GitLab.com SaaS for the purpose of Git access control. + +## Motivation + +- Enable users to share public Certificate Authority (`CA`) files with GitLab.com SaaS for the purpose of Git access control. +- Fill the product gap between GitLab and competitive products that already support authentication via SSH certificates. + +### Goals + +This document proposes an architectural design to implement functionality to satisfy the following requirements: + +- The public key of the `CA` file (`CA.pub`) that is used to issue certificates can be added to a group. +- A certificate issued by the `CA` can be used to get Git access to projects of the group and its ancestors. +- The certificate cannot be used to get Git access to projects outside the group and its ancestors. + +### Non-goals + +This document focuses on providing core functionality for supporting authentication via SSH certificates. The potential improvements are described in [Follow Ups](#follow-ups). + +## Proposal + +### MVC + +A group admin generates an SSH key pair to be used as a Certified Authority file (`ssh-keygen -f CA`): + +- The private key is used to issue user certificates +- The public key is added to a group in order to grant access to the group via the user certificates + +#### User certificate + +A group admin issues user certificates using `CA` private key and specifies either a GitLab username or a user's primary email as the key identity: + +```shell +ssh-keygen -s CA -I user@example.com -V +1d user-key.pub +``` + +As a result, a user certificate of the following structure is generated: + +```shell +ssh-keygen -L -f ssh_host_ed25519_key-cert.pub + +ssh_host_ed25519_key-cert.pub: + Type: ssh-ed25519-cert-v01@openssh.com user certificate + Public key: ED25519-CERT SHA256:dRVV49XJHt85X1seqr9xXyxyuuGTbtFV6Lbwlrx6BIQ + Signing CA: RSA SHA256:UAcgUeGoXrs8WOT/N+bmqY2vB9145Mc5NaN1Y977NCI (using rsa-sha2-512) + Key ID: "user@example.com" + Serial: 1 + Valid: from 2023-07-31T18:20:00 to 2023-08-01T18:21:34 + Principals: (none) + Critical Options: (none) + Extensions: + permit-X11-forwarding + permit-agent-forwarding + permit-port-forwarding + permit-pty + permit-user-rc +``` + +- `Type` is the type of the user certificate. Only user certificates are accepted by GitLab Shell, all other types are rejected. +- `Public Key` is the public key of the user. +- `Signing CA` is the public key of `CA`. Its fingerprint is used to find a group associated with the user certificate. +- `Key ID` is a user's username or primary email. It is used to associate a GitLab user with the user certificate. +- `Serial` is a serial number of the user certificate. It can be used to distinguish between different certificates created by the same `CA`. +- `Valid` indicates the period of validity. This value is validated by GitLab Shell: expired and not yet valid user certificates are rejected. +- `Principals`, `Critical Options` and `Extensions` are used to embed additional information into the user certificate. This fields can be potentially used in future iterations to apply additional restrictions on a user certificated. + +#### Application behavior + +[GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell) is the project responsible for handling [commands](../../../development/gitlab_shell/features.md) sent to GitLab instance via SSH. +When a user tries to establish an SSH connection and authenticate via a public key, GitLab Shell sends an internal API request to `/authorized_keys` endpoint to detect whether the key is associated with a GitLab user. If a certificate is used for authentication, GitLab Shell can recognize it and perform a request to `/authorized_certs` instead. + +1. A group admin adds `CA.pub` file to a group. +1. A user tries to authenticate using a certificate signed by the `CA`. +1. GitLab Shell sends to `/authorized_certs` the fingerprint of the `CA` and the user identity (either GitLab username or the primary email). +1. GitLab Rails finds a group that has a `CA.pub` with the fingerprint added and the user. The `CA.pub` is unique for an instance by fingerprint which defines the one-to-one relationship between `CA` and a group. +1. GitLab Shell remembers the namespace full path for the established connection. +1. GitLab Shell sends a request to `/allowed` endpoint every time a check whether a user has access to a particular project is needed. The namespace full path is passed to `/allowed` endpoint. +1. GitLab Rails checks whether the namespace matches the project namespace or one of its ancestors in order to determine whether a user has access to this project via the certificate. +1. If all the checks above are successful, the user gets access to the project. + +```mermaid +sequenceDiagram + User->>+GitLab Shell: Auth using SSH Certificate + GitLab Shell->>+GitLab Rails: /authorized_certs?key=fingerprint-of-signing-key&user_identity=username-or-primary-email + GitLab Rails-->>-GitLab Shell: responds with the namespace that configures the CA and the username of the user + GitLab Shell-->>User: Authenticated successfully + User->>+GitLab Shell: Git command to a specific project + GitLab Shell->>+GitLab Rails: /allowed [namespace=namespace] + GitLab Rails-->>-GitLab Shell: responds that the user is allowed to access a project in this namespace + GitLab Shell-->>User: success +``` + +#### Examples + +1. Access a project outside the group that configures `CA.pub`. + + Given there is the following hierarchy of groups + + ```plaintext + a/b/c/d/e/f + | + └/g/h/i + ``` + + - A group admin adds `CA.pub` to `d` and a user is authenticated using a certificate signed by the `CA`. + - When a user clones `a/b/c/d/e/f/project`, we send `a/b/c/d/e/project` project full path and `a/b/c/d` namespace full path: the user is allowed to clone the project because `d` is an ancestor of the project's namespace. + - When a user clones `a/b/c/g/h/i/project`, the user is not allowed to clone the project because `d` is not in a list of its ancestors. + +1. A group that configures `CA.pub` is transferred to a different namespace. + +The existing certificates are still valid because the namespace full path is stored per connection. When a user reconnects, another request to `/authorized_certs` is sent and the new full path of the namespace is returned. + +## Open questions + +### Multiple SSH certificates to different projects + +A user may have different SSH certificates to access different projects. +When the user establishes an SSH connection, the SSH client will iterate over a number of potential +options in order to find the one that authenticates successfully. +With the current architecture, the first certificate that provides access to a namespace is accepted, +even if the user is meant to get access to a different project. + +For example: + +1. A user has valid certificates for `a` and `b` groups. +1. The user is successfully authenticated using `a`. +1. The user tries to clone `b/project` and fails. + +A workaround for this scenario is to configure Git to use a particular certificate during an SSH +connection. Add the following to your `.gitconfig` file: + +```plaintext +[core] + sshCommand = ssh git@gitlab.com -i cert.pub +``` + +### A single certificate cannot be revoked + +Revocation of a single user certificate is out of the scope of this MVC. It is possible to implement this feature but the feasibility should be discussed. + +Supporting it will complicate the implementation and UI/UX. However, the risk of a compromised certificate can be significantly reduced by the following actions: + +- Expiration date of a user certificate. It should be highly recommended in the docs. +- Rotation of the CA which revokes all the current user certificates. +- Implementing `source-address` feature that allows restricting IP address(es) from which the user certificate can be used. + +### A certificate can be used across multiple GitLab instances + +The information about GitLab instance is not embedded into a user certificate. It means that it can be used across multiple GitLab instances as long as the `KeyId` value is recognized in those instances. + +Potential solution: + +- An optional field that restricts usage of a user certificate to a particular instance can be implemented using `Extensions` in a follow-up. Specifying `extension:login@gitlab.com=username` is a more secure and flexible option, but we can support both. + +### CA cannot be reused by multiple groups + +The `CA.pub` fingerprint must be unique and cannot be reused by multiple groups. The one-to-one relationship is chosen by design to be able to find a single group that a user has access to. + +Another option is to embed the namespace into the user certificate using `Extensions` or `Critical Options`. + +Pros: + +- `CA` can be reused by multiple groups. +- A user certificate _tells_ which group to get access to rather than _asks_ which group it can get access to. + +Cons: + +- Requires a custom requirement to the user certificate format. +- If some other group adds `CA.pub`, a user may unintentionally get access to that group. + +Potential solution: + +- An optional field that restricts usage of a user certificate to a particular group can be implemented using `Extensions` or `Critical Options` in a follow-up. `CA` still cannot be reused but a user certificate cannot be used for some other group. + +## Iteration plan + +| Component | Milestone | Group | Changes | +|--------------|-----------------------|----------------------------------|---------| +| GitLab Shell | `16.3` | Source Code | [Implement](https://gitlab.com/gitlab-org/gitlab-shell/-/merge_requests/812) authentication using SSH certificates in GitLab Shell | +| GitLab Rails | `16.4` | Source Code | Implement the internal GitLab Rails API endpoint `authorized_certs` to find a group that configures the `CA.pub` | +| GitLab Rails | `16.4` | Source Code | Implement a GitLab Rails API endpoint for groups to add/remove a `CA.pub` | +| GitLab Rails | `Next 2-3 milestones` | Authentication and Authorization | Implement Group Settings UX to add/remove `CA.pub` | +| GitLab Rails | `Next 2-3 milestones` | Authentication and Authorization | Implement an option to enforce using SSH certificates only for authentication and forbid personal SSH keys and access tokens | + +## Follow-ups + +The functionality that is related to the topic but out of the scope of this blueprint: + +- Enforce using SSH certificates only for authentication by disabling Git over HTTPS for an instance or a Group: a must-have functionality. +- Enforce using Group-level SSH keys only by forbidding the use of personal SSH keys for an instance or a Group: a must-have functionality. +- Specifying `source-address` `Critical Option` that restricts usage of a user certificate to a set of IP addresses: a nice-to-have functionality. +- Specifying `login@hostname=username` `Extensions` that restrict usage of a user certificate to a set of instances: a nice-to-have functionality. +- Signing commits using SSH certificates: a nice-to-have functionality. +- Revoke a single user certificate. It requires complex UI/UX while the risk can be significantly mitigated by using other features. diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index d14c9563642..be5112251a4 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -4,7 +4,7 @@ group: Pipeline Authoring 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 --- -# Caching in GitLab CI/CD **(FREE)** +# Caching in GitLab CI/CD **(FREE ALL)** A cache is one or more files a job downloads and saves. Subsequent jobs that use the same cache don't have to download the files again, so they execute more quickly. diff --git a/doc/ci/chatops/index.md b/doc/ci/chatops/index.md index 09f2758113f..10276df6291 100644 --- a/doc/ci/chatops/index.md +++ b/doc/ci/chatops/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, concepts, howto --- -# GitLab ChatOps **(FREE)** +# GitLab ChatOps **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in GitLab Ultimate 10.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to GitLab Free in 11.9. diff --git a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md index 5494e5fad1c..7164fae10a1 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Using GitLab CI/CD with a Bitbucket Cloud repository **(PREMIUM)** +# Using GitLab CI/CD with a Bitbucket Cloud repository **(PREMIUM ALL)** GitLab CI/CD can be used with Bitbucket Cloud by: diff --git a/doc/ci/ci_cd_for_external_repos/github_integration.md b/doc/ci/ci_cd_for_external_repos/github_integration.md index feb01a0fc4a..1fad7ad5a53 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Using GitLab CI/CD with a GitHub repository **(PREMIUM)** +# Using GitLab CI/CD with a GitHub repository **(PREMIUM ALL)** GitLab CI/CD can be used with **GitHub.com** and **GitHub Enterprise** by creating a [CI/CD project](index.md) to connect your GitHub repository to diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index 7f454cabcf4..a9093632a8c 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, howto --- -# GitLab CI/CD for external repositories **(PREMIUM)** +# GitLab CI/CD for external repositories **(PREMIUM ALL)** >[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4642) in GitLab 10.6. @@ -103,3 +103,8 @@ references an open Pull Request, both contribute to the status of the Pull Reque via GitHub integration. If you want to exclusively run pipelines on external pull requests and not on branches you can add `except: [branches]` to the job specs. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/24089#workaround). + +## Troubleshooting + +- [Pull mirroring is not triggering pipelines](../../user/project/repository/mirror/troubleshooting.md#pull-mirroring-is-not-triggering-pipelines). +- [Fix hard failures when mirroring](../../user/project/repository/mirror/pull.md#fix-hard-failures-when-mirroring). diff --git a/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md b/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md index f7604689b78..f50b7be855a 100644 --- a/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md +++ b/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Deploy to Amazon Elastic Container Service **(FREE)** +# Deploy to Amazon Elastic Container Service **(FREE ALL)** This step-by-step guide helps you deploy a project hosted on GitLab.com to the Amazon [Elastic Container Service (ECS)](https://aws.amazon.com/ecs/). @@ -217,14 +217,14 @@ These variables are injected into the pipeline jobs and can access the ECS API. 1. Go to **Settings > CI/CD > Variables**. 1. Select **Add Variable** and set the following key-value pairs. - |Key|Value|Note| - |---|---|---| - |`AWS_ACCESS_KEY_ID`|`<Access key ID of the deployer>`| For authenticating `aws` CLI. | - |`AWS_SECRET_ACCESS_KEY`|`<Secret access key of the deployer>`| For authenticating `aws` CLI. | - |`AWS_DEFAULT_REGION`|`us-east-2`| For authenticating `aws` CLI. | - |`CI_AWS_ECS_CLUSTER`|`ecs-demo`| The ECS cluster is accessed by `production_ecs` job. | - |`CI_AWS_ECS_SERVICE`|`ecs_demo`| The ECS service of the cluster is updated by `production_ecs` job. Ensure that this variable is scoped to the appropriate environment (`production`, `staging`, `review/*`). | - |`CI_AWS_ECS_TASK_DEFINITION`|`ecs_demo`| The ECS task definition is updated by `production_ecs` job. | + | Key | Value | Note | + |------------------------------|---------------------------------------|------| + | `AWS_ACCESS_KEY_ID` | `<Access key ID of the deployer>` | For authenticating `aws` CLI. | + | `AWS_SECRET_ACCESS_KEY` | `<Secret access key of the deployer>` | For authenticating `aws` CLI. | + | `AWS_DEFAULT_REGION` | `us-east-2` | For authenticating `aws` CLI. | + | `CI_AWS_ECS_CLUSTER` | `ecs-demo` | The ECS cluster is accessed by `production_ecs` job. | + | `CI_AWS_ECS_SERVICE` | `ecs_demo` | The ECS service of the cluster is updated by `production_ecs` job. Ensure that this variable is scoped to the appropriate environment (`production`, `staging`, `review/*`). | + | `CI_AWS_ECS_TASK_DEFINITION` | `ecs_demo` | The ECS task definition is updated by `production_ecs` job. | ### Make a change to the demo application diff --git a/doc/ci/cloud_deployment/index.md b/doc/ci/cloud_deployment/index.md index 3e77e8c6c25..16bfced9c34 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Deploy to AWS from GitLab CI/CD **(FREE)** +# Deploy to AWS from GitLab CI/CD **(FREE ALL)** GitLab provides Docker images with the libraries and tools you need to deploy to AWS. You can reference these images in your CI/CD pipeline. diff --git a/doc/ci/cloud_services/aws/index.md b/doc/ci/cloud_services/aws/index.md index b1148d3a258..f0183fc7ba2 100644 --- a/doc/ci/cloud_services/aws/index.md +++ b/doc/ci/cloud_services/aws/index.md @@ -4,7 +4,7 @@ group: Pipeline Security 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 --- -# Configure OpenID Connect in AWS to retrieve temporary credentials **(FREE)** +# Configure OpenID Connect in AWS to retrieve temporary credentials **(FREE ALL)** WARNING: `CI_JOB_JWT_V2` was [deprecated in GitLab 15.9](../../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) diff --git a/doc/ci/cloud_services/azure/index.md b/doc/ci/cloud_services/azure/index.md index b921dabc4e2..fa8ff506dd0 100644 --- a/doc/ci/cloud_services/azure/index.md +++ b/doc/ci/cloud_services/azure/index.md @@ -4,7 +4,7 @@ group: Pipeline Security 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 --- -# Configure OpenID Connect in Azure to retrieve temporary credentials **(FREE)** +# Configure OpenID Connect in Azure to retrieve temporary credentials **(FREE ALL)** WARNING: `CI_JOB_JWT_V2` was [deprecated in GitLab 15.9](../../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) diff --git a/doc/ci/cloud_services/google_cloud/index.md b/doc/ci/cloud_services/google_cloud/index.md index d99b50b5013..f2318b818d8 100644 --- a/doc/ci/cloud_services/google_cloud/index.md +++ b/doc/ci/cloud_services/google_cloud/index.md @@ -4,7 +4,7 @@ group: Pipeline Security 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 --- -# Configure OpenID Connect with GCP Workload Identity Federation **(FREE)** +# Configure OpenID Connect with GCP Workload Identity Federation **(FREE ALL)** WARNING: `CI_JOB_JWT_V2` was [deprecated in GitLab 15.9](../../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) diff --git a/doc/ci/cloud_services/index.md b/doc/ci/cloud_services/index.md index eadf0656d48..6896fffcce7 100644 --- a/doc/ci/cloud_services/index.md +++ b/doc/ci/cloud_services/index.md @@ -4,7 +4,7 @@ group: Pipeline Security 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 --- -# Connect to cloud services **(FREE)** +# Connect to cloud services **(FREE ALL)** > - `CI_JOB_JWT` variable for reading secrets from Vault [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207125) in GitLab 12.10. > - `CI_JOB_JWT_V2` variable to support additional OIDC providers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346737) in GitLab 14.7. @@ -95,9 +95,9 @@ The condition is validated against the JWT to create a trust specifically agains - Subject or `sub`: A concatenation of metadata describing the GitLab CI/CD workflow including the group, project, branch, and tag. The `sub` field is in the following format: - `project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}` -| Filter type | Example | -| ------------------------------------ | ------------------------------------------------------------ | -| Filter to main branch | `project_path:mygroup/myproject:ref_type:branch:ref:main` | +| Filter type | Example | +|--------------------------------------|---------| +| Filter to main branch | `project_path:mygroup/myproject:ref_type:branch:ref:main` | | Filter to any branch | Wildcard supported. `project_path:mygroup/myproject:ref_type:branch:ref:*` | | Filter to specific project | `project_path:mygroup/myproject:ref_type:branch:ref:main` | | Filter to all projects under a group | Wildcard supported. `project_path:mygroup/*:ref_type:branch:ref:main` | diff --git a/doc/ci/components/index.md b/doc/ci/components/index.md index ae35b3779c3..4a739bdfcf6 100644 --- a/doc/ci/components/index.md +++ b/doc/ci/components/index.md @@ -7,12 +7,9 @@ type: reference # CI/CD Components (Experimental) -> Introduced in GitLab 16.0 as an [experimental feature](../../policy/experiment-beta-support.md). - -FLAG: -On self-managed GitLab, by default this feature is not available. -To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `ci_namespace_catalog_experimental`. -On GitLab.com, this feature is not available. This feature is not ready for production use. +> - Introduced as an [experimental feature](../../policy/experiment-beta-support.md) in GitLab 16.0, [with a flag](../../administration/feature_flags.md) named `ci_namespace_catalog_experimental`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/groups/gitlab-org/-/epics/9897) in GitLab 16.2. +> - [Feature flag `ci_namespace_catalog_experimental` removed.](https://gitlab.com/gitlab-org/gitlab/-/issues/394772) in GitLab 16.3. This feature is an experimental feature and [an epic exists](https://gitlab.com/groups/gitlab-org/-/epics/9897) to track future work. Tell us about your use case by leaving comments in the epic. @@ -339,7 +336,7 @@ We recommend adopting at least the `MAJOR.MINOR` format. For example: `2.1`, `1.0.0`, `1.0.0-alpha`, `2.1.3`, `3.0.0-rc.1`. -## CI/CD Catalog +## CI/CD Catalog **(PREMIUM ALL)** The CI/CD Catalog is a list of [components repositories](#components-repository), each containing resources that you can add to your CI/CD pipelines. @@ -367,7 +364,7 @@ This action is not reversible. Any existing CI template, that you share with other projects via `include:` syntax, can be converted to a CI component. -1. Decide whether you want the component to be part of an existing [components repository](#components-repository), +1. Decide whether you want the component to be part of an existing [components repository](#components-repository), if you want to logically group components together. Create and setup a [components repository](#components-repository) otherwise. 1. Create a YAML file in the components repository according to the expected [directory structure](#directory-structure). 1. Copy the content of the template YAML file into the new component YAML file. diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index e3bbe5b66c7..a1163a3acff 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Directed Acyclic Graph **(FREE)** +# Directed Acyclic Graph **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47063) in GitLab 12.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/206902) in GitLab 12.10. @@ -36,8 +36,8 @@ Consider a monorepo as follows: It has a pipeline that looks like the following: -| build | test | deploy | -| ----- | ---- | ------ | +| build | test | deploy | +|-----------|----------|--------| | `build_a` | `test_a` | `deploy_a` | | `build_b` | `test_b` | `deploy_b` | | `build_c` | `test_c` | `deploy_c` | diff --git a/doc/ci/docker/index.md b/doc/ci/docker/index.md index 162d67286ad..49a9e1f8eea 100644 --- a/doc/ci/docker/index.md +++ b/doc/ci/docker/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index --- -# Docker integration **(FREE)** +# Docker integration **(FREE ALL)** There are two primary ways to incorporate [Docker](https://www.docker.com) into your CI/CD workflow: diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 5e8f2b36620..fb38de0f7de 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Use Docker to build Docker images **(FREE)** +# Use Docker to build Docker images **(FREE ALL)** You can use GitLab CI/CD with Docker to create Docker images. For example, you can create a Docker image of your application, @@ -37,7 +37,7 @@ the Docker commands, but needs permission to do so. ```shell sudo gitlab-runner register -n \ - --url https://gitlab.com/ \ + --url "https://gitlab.com/" \ --registration-token REGISTRATION_TOKEN \ --executor shell \ --description "My Runner" @@ -91,7 +91,7 @@ You should use Docker-in-Docker with TLS enabled, which is supported by [GitLab.com shared runners](../runners/index.md). You should always pin a specific version of the image, like `docker:20.10.16`. -If you use a tag like `docker:stable`, you have no control over which version is used. +If you use a tag like `docker:latest`, you have no control over which version is used. This can cause incompatibility problems when new versions are released. #### Use the Docker executor with Docker-in-Docker @@ -117,7 +117,7 @@ To use Docker-in-Docker with TLS enabled: ```shell sudo gitlab-runner register -n \ - --url https://gitlab.com/ \ + --url "https://gitlab.com/" \ --registration-token REGISTRATION_TOKEN \ --executor docker \ --description "My Docker Runner" \ @@ -381,7 +381,7 @@ To mount `/var/run/docker.sock` while registering your runner, include the follo ```shell sudo gitlab-runner register -n \ - --url https://gitlab.com/ \ + --url "https://gitlab.com/" \ --registration-token REGISTRATION_TOKEN \ --executor docker \ --description "My Docker Runner" \ diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index d3a2f4ece06..455731f6c65 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Run your CI/CD jobs in Docker containers **(FREE)** +# Run your CI/CD jobs in Docker containers **(FREE ALL)** You can run your CI/CD jobs in separate, isolated Docker containers. diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index b7affe28984..568f4977c2f 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Use kaniko to build Docker images **(FREE)** +# Use kaniko to build Docker images **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45512) in GitLab 11.2. Requires GitLab Runner 11.2 and above. @@ -73,9 +73,11 @@ If you authenticate against the [Dependency Proxy](../../user/packages/dependenc you must add the corresponding CI/CD variables for authentication to the `config.json` file: ```yaml -- echo "{\"auths\":{\"${CI_REGISTRY}\":{\"auth\":\"$(printf "%s:%s" "${CI_REGISTRY_USER}" "${CI_REGISTRY_PASSWORD}" | base64 | tr -d '\n')\"},\"$CI_DEPENDENCY_PROXY_SERVER\":{\"auth\":\"$(printf "%s:%s" ${CI_DEPENDENCY_PROXY_USER} "${CI_DEPENDENCY_PROXY_PASSWORD}" | base64 | tr -d '\n')\"}}}" > /kaniko/.docker/config.json +- echo "{\"auths\":{\"${CI_REGISTRY}\":{\"auth\":\"$(printf "%s:%s" "${CI_REGISTRY_USER}" "${CI_REGISTRY_PASSWORD}" | base64 | tr -d '\n')\"},\"$(echo -n $CI_DEPENDENCY_PROXY_SERVER | awk -F[:] '{print $1}')\":{\"auth\":\"$(printf "%s:%s" ${CI_DEPENDENCY_PROXY_USER} "${CI_DEPENDENCY_PROXY_PASSWORD}" | base64 | tr -d '\n')\"}}}" > /kaniko/.docker/config.json ``` +This command strips the port, for example `:443`, from `CI_DEPENDENCY_PROXY_SERVER`, so you don't have to include it when referencing images. + ### Building an image with kaniko behind a proxy If you use a custom GitLab Runner behind an http(s) proxy, kaniko needs to be set diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index e332b040fbc..395a07f48c8 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Disabling GitLab CI/CD **(FREE)** +# Disabling GitLab CI/CD **(FREE ALL)** GitLab CI/CD is enabled by default on all new projects. If you use an external CI/CD server like Jenkins or Drone CI, you can diff --git a/doc/ci/environments/deployment_approvals.md b/doc/ci/environments/deployment_approvals.md index 2a9b381c517..2933b25e09b 100644 --- a/doc/ci/environments/deployment_approvals.md +++ b/doc/ci/environments/deployment_approvals.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: Require approvals prior to deploying to a Protected Environment --- -# Deployment approvals **(PREMIUM)** +# Deployment approvals **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343864) in GitLab 14.7 with a flag named `deployment_approvals`. Disabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/347342) in GitLab 14.8. diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index e15e09b27c1..b34fc61ba66 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Deployment safety **(FREE)** +# Deployment safety **(FREE ALL)** [Deployment jobs](../jobs/index.md#deployment-jobs) are a specific kind of CI/CD job. They can be more sensitive than other jobs in a pipeline, @@ -93,15 +93,17 @@ When an older deployment job is manual, the play button is disabled with a messa Job age is determined by the job start time, not the commit time, so a newer commit can be prevented in some circumstances. -### How to rollback to an outdated deployment +### Job retries for rollback deployments -> In GitLab 15.6, [rollback via job retry was introduced back](https://gitlab.com/gitlab-org/gitlab/-/issues/378359). +> - Rollback via job retry [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378359) in GitLab 15.6. +> - Job retries for rollback deployments checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/410427) in GitLab 16.3. -In some cases, you need to rollback to an outdated deployment. -This feature explicitly allows rollback via [Environment Rollback](index.md#environment-rollback), -so that you can quickly rollback in an urgent case. +You might need to quickly roll back to a stable, outdated deployment. +By default, pipeline job retries for [deployment rollback](index.md#environment-rollback) are enabled. -Alternatively, you can run a new pipeline with a previous commit. It contains newer deployment jobs than the latest deployment. +To disable pipeline retries, clear the **Allow job retries for rollback deployments** checkbox. You should disable pipeline retries in sensitive projects. + +When a rollback is required, you must run a new pipeline with a previous commit. ### Example diff --git a/doc/ci/environments/environments_dashboard.md b/doc/ci/environments/environments_dashboard.md index ce219e5d746..e98205f45b9 100644 --- a/doc/ci/environments/environments_dashboard.md +++ b/doc/ci/environments/environments_dashboard.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Environments Dashboard **(PREMIUM)** +# Environments Dashboard **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3713) in GitLab 12.5. diff --git a/doc/ci/environments/external_deployment_tools.md b/doc/ci/environments/external_deployment_tools.md index 37c4cf05f13..ac31d196887 100644 --- a/doc/ci/environments/external_deployment_tools.md +++ b/doc/ci/environments/external_deployment_tools.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Track deployments of an external deployment tool **(FREE)** +# Track deployments of an external deployment tool **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22513) in GitLab 12.5. diff --git a/doc/ci/environments/incremental_rollouts.md b/doc/ci/environments/incremental_rollouts.md index c032ae3be60..a498e525b54 100644 --- a/doc/ci/environments/incremental_rollouts.md +++ b/doc/ci/environments/incremental_rollouts.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Incremental rollouts with GitLab CI/CD **(FREE)** +# Incremental rollouts with GitLab CI/CD **(FREE ALL)** When rolling out changes to your application, it is possible to release production changes to only a portion of your Kubernetes pods as a risk mitigation strategy. By releasing diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 689f92723ee..c91018980f0 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Environments and deployments **(FREE)** +# Environments and deployments **(FREE ALL)** Environments describe where code is deployed. @@ -343,7 +343,7 @@ the job's `script`. If there is a problem with a deployment, you can retry it or roll it back. -To retry or rollback a deployment: +To retry or roll back a deployment: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Operate > Environments**. @@ -355,7 +355,7 @@ To retry or rollback a deployment: NOTE: If you have [prevented outdated deployment jobs](deployment_safety.md#prevent-outdated-deployment-jobs) in your project, the rollback buttons might be hidden or disabled. -In this case, see [how to rollback to an outdated deployment](deployment_safety.md#how-to-rollback-to-an-outdated-deployment). +In this case, see [job retries for rollback deployments](deployment_safety.md#job-retries-for-rollback-deployments). ### Environment URL @@ -729,7 +729,7 @@ or human error can cause major issues with an environment. Things like: You can use [incident management](../../operations/incident_management/index.md) to get alerts when there are critical issues that need immediate attention. -#### View the latest alerts for environments **(ULTIMATE)** +#### View the latest alerts for environments **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214634) in GitLab 13.4. @@ -745,7 +745,7 @@ longer visible on the environments page. If the alert requires a [rollback](#retry-or-roll-back-a-deployment), you can select the deployment tab from the environment page and select which deployment to roll back to. -#### Auto Rollback **(ULTIMATE)** +#### Auto Rollback **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35404) in GitLab 13.7. diff --git a/doc/ci/environments/kubernetes_dashboard.md b/doc/ci/environments/kubernetes_dashboard.md index ee16294e654..98b6731e469 100644 --- a/doc/ci/environments/kubernetes_dashboard.md +++ b/doc/ci/environments/kubernetes_dashboard.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Dashboard for Kubernetes (Beta) **(FREE)** +# Dashboard for Kubernetes (Beta) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390769) in GitLab 16.1, with [flags](../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`. This feature is in [Beta](../../policy/experiment-beta-support.md#beta). > - Feature flag `environment_settings_to_graphql` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124177) in GitLab 16.2. @@ -20,6 +20,13 @@ For Flux users, the synchronization status of a given environment is not display ## Configure a dashboard +> - Filtering resources by namespace [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/403618) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `kubernetes_namespace_for_environment`. Disabled by default. +> - Filtering resources by namespace [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127043) in GitLab 16.3. Feature flag `kubernetes_namespace_for_environment` removed. +> - Selecting the related Flux resource [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128857) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `flux_resource_for_environment`. Disabled by default. + +FLAG: +On self-managed GitLab, by default selecting a Flux resource is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `flux_resource_for_environment`. On GitLab.com, this feature is not available. + Configure a dashboard to use it for a given environment. You can configure dashboard for an environment that already exists, or add one when you create an environment. @@ -36,6 +43,8 @@ Prerequisites: 1. Select the environment to be associated with the Kubernetes. 1. Select **Edit**. 1. Select a GitLab agent for Kubernetes. +1. Optional. From the **Kubernetes namespace** dropdown list, select a namespace. +1. Optional. From the **Flux resource** dropdown list, select a Flux resource. 1. Select **Save**. ### The environment doesn't exist @@ -45,6 +54,8 @@ Prerequisites: 1. Select **New environment**. 1. Complete the **Name** field. 1. Select a GitLab agent for Kubernetes. +1. Optional. From the **Kubernetes namespace** dropdown list, select a namespace. +1. Optional. From the **Flux resource** dropdown list, select a Flux resource. 1. Select **Save**. ## View a dashboard @@ -56,6 +67,27 @@ To view a configured dashboard: 1. Expand the environment associated with GitLab agent for Kubernetes. 1. Expand **Kubernetes overview**. +### Flux sync status + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391581) in GitLab 16.3. +> - Customizing the name of the Flux resource [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128857) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `flux_resource_for_environment`. Disabled by default. + +A dashboard displays the sync status of your Flux deployments. + +| Status | Description | +|---------|-------------| +| **Reconciled** | The deployment successfully reconciled with its environment. | +| **Reconciling** | A reconciliation is in progress. | +| **Stalled** | A reconciliation is stuck because of an error that cannot be resolved without human intervention. | +| **Failed** | The deployment couldn't reconcile because of an unrecoverable error. | +| **Unknown** | The sync status of the deployment couldn't be retrieved. | +| **Unavailable** | The `Kustomization` or `HelmRelease` resource couldn't be retrieved. | + +Deployments rely on Flux `Kustomization` and `HelmRelease` resources to gather +the status of a given environment, which requires a namespace to be configured for the environment. +By default, GitLab searches the `Kustomization` and `HelmRelease` resources for the name of the project slug. +You can customize the name GitLab looks for in the environment settings. + ## Troubleshooting When working with the Dashboard for Kubernetes, you might encounter the following issues. diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index 61b59ceedb2..fd789ea798d 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Protected environments **(PREMIUM)** +# Protected environments **(PREMIUM ALL)** [Environments](../environments/index.md) can be used for both testing and production reasons. @@ -33,6 +33,7 @@ To protect an environment: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > CI/CD**. 1. Expand **Protected environments**. +1. Select **Protect an environment**. 1. From the **Environment** list, select the environment you want to protect. 1. In the **Allowed to deploy** list, select the role, users, or groups you want to give deploy access to. Keep in mind that: @@ -50,7 +51,7 @@ To protect an environment: - **Developers**: Allows access to all of the project's users with the Maintainer and Developer role. - You can select groups that are already associated with the project only. - Users must have at least the Developer role to appear in - the **Allowed to deploy** list. + the **Approvers** list. 1. In the **Approval rules** section: diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md index f45c60bdd1f..737c95cf747 100644 --- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md +++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md @@ -5,13 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# Authenticating and reading secrets with HashiCorp Vault (Deprecated) **(PREMIUM)** +# Authenticating and reading secrets with HashiCorp Vault **(PREMIUM ALL)** WARNING: -Authenticating with HashiCorp Vault by using `CI_JOB_JWT` was [deprecated in GitLab 15.9](../../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) -and the token is scheduled to be removed in GitLab 16.5. This change is a breaking change. -Use [ID tokens to authenticate with HashiCorp Vault](../../secrets/id_token_authentication.md#automatic-id-token-authentication-with-hashicorp-vault) -instead. +Authenticating with `CI_JOB_JWT` was [deprecated in GitLab 15.9](../../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) +and the token is scheduled to be removed in GitLab 16.5. Use +[ID tokens to authenticate with HashiCorp Vault](../../secrets/id_token_authentication.md#automatic-id-token-authentication-with-hashicorp-vault) +instead, as demonstrated on this page. This tutorial demonstrates how to authenticate, configure, and read secrets with HashiCorp's Vault from GitLab CI/CD. @@ -33,30 +33,30 @@ ID tokens are JSON Web Tokens (JWTs) used for OIDC authentication with third-par The following fields are included in the JWT: -| Field | When | Description | -|-------------------------|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `jti` | Always | Unique identifier for this token | -| `iss` | Always | Issuer, the domain of your GitLab instance | -| `iat` | Always | Issued at | -| `nbf` | Always | Not valid before | -| `exp` | Always | Expires at | -| `sub` | Always | Subject (job ID) | -| `namespace_id` | Always | Use this to scope to group or user level namespace by ID | -| `namespace_path` | Always | Use this to scope to group or user level namespace by path | -| `project_id` | Always | Use this to scope to project by ID | -| `project_path` | Always | Use this to scope to project by path | -| `user_id` | Always | ID of the user executing the job | -| `user_login` | Always | Username of the user executing the job | -| `user_email` | Always | Email of the user executing the job | -| `pipeline_id` | Always | ID of this pipeline | -| `pipeline_source` | Always | [Pipeline source](../../jobs/job_control.md#common-if-clauses-for-rules) | -| `job_id` | Always | ID of this job | -| `ref` | Always | Git ref for this job | -| `ref_type` | Always | Git ref type, either `branch` or `tag` | +| Field | When | Description | +|-------------------------|------------------------------|-------------| +| `jti` | Always | Unique identifier for this token | +| `iss` | Always | Issuer, the domain of your GitLab instance | +| `iat` | Always | Issued at | +| `nbf` | Always | Not valid before | +| `exp` | Always | Expires at | +| `sub` | Always | Subject (job ID) | +| `namespace_id` | Always | Use this to scope to group or user level namespace by ID | +| `namespace_path` | Always | Use this to scope to group or user level namespace by path | +| `project_id` | Always | Use this to scope to project by ID | +| `project_path` | Always | Use this to scope to project by path | +| `user_id` | Always | ID of the user executing the job | +| `user_login` | Always | Username of the user executing the job | +| `user_email` | Always | Email of the user executing the job | +| `pipeline_id` | Always | ID of this pipeline | +| `pipeline_source` | Always | [Pipeline source](../../jobs/job_control.md#common-if-clauses-for-rules) | +| `job_id` | Always | ID of this job | +| `ref` | Always | Git ref for this job | +| `ref_type` | Always | Git ref type, either `branch` or `tag` | | `ref_path` | Always | Fully qualified ref for the job. For example, `refs/heads/main`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119075) in GitLab 16.0. | -| `ref_protected` | Always | `true` if this Git ref is protected, `false` otherwise | -| `environment` | Job specifies an environment | Environment this job specifies ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9) | -| `environment_protected` | Job specifies an environment | `true` if specified environment is protected, `false` otherwise ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9) | +| `ref_protected` | Always | `true` if this Git ref is protected, `false` otherwise | +| `environment` | Job specifies an environment | Environment this job specifies ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9) | +| `environment_protected` | Job specifies an environment | `true` if specified environment is protected, `false` otherwise ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9) | | `deployment_tier` | Job specifies an environment | [Deployment tier](../../environments/index.md#deployment-tier-of-environments) of environment this job specifies ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363590) in GitLab 15.2) | Example JWT payload: @@ -249,7 +249,7 @@ Now, configure the JWT Authentication method: ```shell $ vault write auth/jwt/config \ jwks_url="https://gitlab.example.com/-/jwks" \ - bound_issuer="gitlab.example.com" + bound_issuer="https://gitlab.example.com" ``` [`bound_issuer`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#bound_issuer) specifies that only a JWT with the issuer (that is, the `iss` claim) set to `gitlab.example.com` can use this method to authenticate, and that the JWKS endpoint (`https://gitlab.example.com/-/jwks`) should be used to validate the token. diff --git a/doc/ci/examples/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md index 5d1ae0048af..dfdaa1866c3 100644 --- a/doc/ci/examples/deployment/composer-npm-deploy.md +++ b/doc/ci/examples/deployment/composer-npm-deploy.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# Running Composer and npm scripts with deployment via SCP in GitLab CI/CD **(FREE)** +# Running Composer and npm scripts with deployment via SCP in GitLab CI/CD **(FREE ALL)** This guide covers the building of dependencies of a PHP project while compiling assets via an npm script using [GitLab CI/CD](../../index.md). diff --git a/doc/ci/examples/deployment/index.md b/doc/ci/examples/deployment/index.md index 793e60d517c..f9360faedac 100644 --- a/doc/ci/examples/deployment/index.md +++ b/doc/ci/examples/deployment/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# Using Dpl as a deployment tool **(FREE)** +# Using Dpl as a deployment tool **(FREE ALL)** [Dpl](https://github.com/travis-ci/dpl) (pronounced like the letters D-P-L) is a deploy tool made for continuous deployment that's developed and used by Travis CI, but can also be diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/index.md b/doc/ci/examples/end_to_end_testing_webdriverio/index.md index ee8b6bb30b6..10ec18a6147 100644 --- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -9,7 +9,7 @@ description: 'Confidence checking your entire app every time a new feature is ad <!-- vale off --> -# End-to-end testing with GitLab CI/CD and WebdriverIO **(FREE)** +# End-to-end testing with GitLab CI/CD and WebdriverIO **(FREE ALL)** [Review Apps](../../review_apps/index.md) are great: for every merge request (or branch, for that matter), the new code can be copied and deployed to a fresh production-like live @@ -154,7 +154,7 @@ to interact with your application, so we need to install and run them. Furthermore, WebdriverIO uses Selenium as a common interface to control different browsers, so we need to install and run Selenium as well. Luckily, the Selenium project provides the Docker images for Firefox [standalone-firefox](https://hub.docker.com/r/selenium/standalone-firefox/) and -and for Chrome [standalone-chrome](https://hub.docker.com/r/selenium/standalone-chrome/). +and for Chrome [standalone-chrome](https://hub.docker.com/r/selenium/standalone-chrome/). (Since Safari and Internet Explorer/Edge are not open source and not available for Linux, we are unfortunately unable to use those in GitLab CI/CD). diff --git a/doc/ci/examples/index.md b/doc/ci/examples/index.md index 514817adc91..aa3be8f2ab0 100644 --- a/doc/ci/examples/index.md +++ b/doc/ci/examples/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index --- -# GitLab CI/CD Examples **(FREE)** +# GitLab CI/CD examples **(FREE ALL)** This page contains links to a variety of examples that can help you understand how to implement [GitLab CI/CD](../index.md) for your specific use case. diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index 14d8e0fc72f..ea936b66d31 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -8,7 +8,7 @@ author_gitlab: mehranrasulian <!-- vale off --> -# Test and deploy Laravel applications with GitLab CI/CD and Envoy **(FREE)** +# Test and deploy Laravel applications with GitLab CI/CD and Envoy **(FREE ALL)** ## Introduction @@ -66,7 +66,7 @@ This test will be used later for continuously testing our app with GitLab CI/CD. ### Push to GitLab Since we have our app up and running locally, it's time to push the codebase to our remote repository. -Let's create [a new project](../../../user/project/index.md#create-a-project) in GitLab named `laravel-sample`. +Let's create [a new project](../../../user/project/index.md) in GitLab named `laravel-sample`. After that, follow the command line instructions displayed on the project's homepage to initiate the repository on our machine and push the first commit. ```shell @@ -376,7 +376,7 @@ These are persistent data and will be shared to every new release. Now, we would need to deploy our app by running `envoy run deploy`, but it won't be necessary since GitLab can handle that for us with CI's [environments](../../environments/index.md), which will be described [later](#setting-up-gitlab-cicd) in this tutorial. Now it's time to commit [Envoy.blade.php](https://gitlab.com/mehranrasulian/laravel-sample/blob/master/Envoy.blade.php) and push it to the `main` branch. -To keep things simple, we commit directly to `main`, without using [feature-branches](../../../topics/gitlab_flow.md#github-flow-as-a-simpler-alternative) since collaboration is beyond the scope of this tutorial. +To keep things simple, we commit directly to `main`, without using feature branches, since collaboration is beyond the scope of this tutorial. In a real world project, teams may use [Issue Tracker](../../../user/project/issues/index.md) and [merge requests](../../../user/project/merge_requests/index.md) to move their code across branches: ```shell diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index 244c1e379da..0e0d40f12f6 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# Testing PHP projects **(FREE)** +# Testing PHP projects **(FREE ALL)** This guide covers basic building instructions for PHP projects. diff --git a/doc/ci/examples/semantic-release.md b/doc/ci/examples/semantic-release.md index 00260199179..b284e2b2dc1 100644 --- a/doc/ci/examples/semantic-release.md +++ b/doc/ci/examples/semantic-release.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Publish npm packages to the GitLab Package Registry using semantic-release **(FREE)** +# Publish npm packages to the GitLab Package Registry using semantic-release **(FREE ALL)** This guide demonstrates how to automatically publish npm packages to the [GitLab Package Registry](../../user/packages/npm_registry/index.md) by using [semantic-release](https://github.com/semantic-release/semantic-release). diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index 31cb6bc9946..2561ab6465e 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Using Git submodules with GitLab CI/CD **(FREE)** +# Using Git submodules with GitLab CI/CD **(FREE ALL)** Use [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to keep a Git repository as a subdirectory of another Git repository. You can clone another @@ -116,7 +116,7 @@ To make submodules work correctly in CI/CD jobs: If you use the [`CI_JOB_TOKEN`](jobs/ci_job_token.md) to clone a submodule in a pipeline job, the user executing the job must be assigned to a role that has [permission](../user/permissions.md#gitlab-cicd-permissions) to trigger a pipeline -in the upstream submodule project. +in the upstream submodule project. Additionally, [CI/CD job token access](jobs/ci_job_token.md#configure-cicd-job-token-access) must be properly configured in the upstream submodule project. ## Troubleshooting diff --git a/doc/ci/index.md b/doc/ci/index.md index a3106a2475c..21fe122f503 100644 --- a/doc/ci/index.md +++ b/doc/ci/index.md @@ -6,7 +6,7 @@ description: "Learn how to use GitLab CI/CD, the GitLab built-in Continuous Inte type: index --- -# GitLab CI/CD **(FREE)** +# GitLab CI/CD **(FREE ALL)** GitLab CI/CD is a tool for software development using the continuous methodologies: @@ -104,7 +104,7 @@ GitLab CI/CD features, grouped by DevOps stage, include: | [Dynamic Application Security Testing](../user/application_security/dast/index.md) | Test your application's runtime behavior for vulnerabilities. | | [Dependency Scanning](../user/application_security/dependency_scanning/index.md) | Analyze your dependencies for known vulnerabilities. | | [Infrastructure as Code scanning](../user/application_security/iac_scanning/index.md) | Scan your IaC configuration files for known vulnerabilities. | -| [License Compliance](../user/compliance/license_compliance/index.md) | Search your project dependencies for their licenses. | +| [License Scanning](../user/compliance/license_scanning_of_cyclonedx_files/index.md) | Search your project dependencies for their licenses. | Search your project dependencies for their licenses. | | [Secret Detection](../user/application_security/secret_detection/index.md) | Search your application's source code for secrets. | | [Static Application Security Testing](../user/application_security/sast/index.md) | Test your application's source code for known vulnerabilities. | | [Web API fuzz testing](../user/application_security/api_fuzzing/index.md) | Test your application's API behavior by providing randomized input. | diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index a7923cb84a0..1125061d830 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Interactive web terminals **(FREE)** +# Interactive web terminals **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/50144) in GitLab 11.3. @@ -61,7 +61,7 @@ improving this behavior. Sometimes, when a job is running, things don't go as you would expect, and it would be helpful if one can have a shell to aid debugging. When a job is running, on the right panel you can see a button `debug` that opens the terminal -for the current job. +for the current job. Only the person who started a job can debug it.  diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index 895aa8551d7..35692ed7b7e 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/index.md @@ -6,7 +6,7 @@ description: "An overview of Continuous Integration, Continuous Delivery, and Co type: concepts --- -# CI/CD concepts **(FREE)** +# CI/CD concepts **(FREE ALL)** With the continuous method of software development, you continuously build, test, and deploy iterative code changes. This iterative process helps reduce diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index c2fe3071b52..dee078c21e0 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -4,7 +4,7 @@ group: Pipeline Security 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 --- -# GitLab CI/CD job token **(FREE)** +# GitLab CI/CD job token **(FREE ALL)** When a pipeline job is about to run, GitLab generates a unique token and injects it as the [`CI_JOB_TOKEN` predefined variable](../variables/predefined_variables.md). @@ -105,6 +105,8 @@ access is needed. ### Disable the job token scope allowlist +> **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3. + WARNING: It is a security risk to disable the allowlist. A malicious user could try to compromise a pipeline created in an unauthorized project. If the pipeline was created by one of @@ -122,28 +124,30 @@ To disable the job token scope allowlist: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > CI/CD**. 1. Expand **Token Access**. -1. Toggle **Allow access to this project with a CI_JOB_TOKEN** to disabled. +1. Toggle **Limit access _to_ this project** to disabled. Enabled by default in new projects. You can also disable the allowlist [with the API](../../api/graphql/reference/index.md#mutationprojectcicdsettingsupdate). ### Add a project to the job token scope allowlist +> **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3. + You can add projects to the allowlist for a project. Projects added to the allowlist can make API calls from running pipelines by using the CI/CD job token. Prerequisite: -- You must have at least the Maintainer role in the current project and at least - the Guest role in the allowed project. -- You must not have more than 100 projects added to the allowlist. +- You must have at least the Maintainer role in the current project. If the allowed project + is internal or private, you must have at least the Guest role in that project. +- You must not have more than 200 projects added to the allowlist. To add a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > CI/CD**. 1. Expand **Token Access**. -1. Verify **Allow access to this project with a CI_JOB_TOKEN** is enabled. +1. Verify **Limit access _to_ this project** is enabled. 1. Under **Allow CI job tokens from the following projects to access this project**, add projects to the allowlist. @@ -176,20 +180,22 @@ If project `B` is public or internal, you do not need to add ### Configure the job token scope +> **Limit CI_JOB_TOKEN access** setting [renamed to **Limit access _from_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3. + Prerequisite: -- You must not have more than 100 projects added to the token's scope. +- You must not have more than 200 projects added to the token's scope. To configure the job token scope: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > CI/CD**. 1. Expand **Token Access**. -1. Toggle **Limit CI_JOB_TOKEN access** to enabled. +1. Toggle **Limit access _from_ this project** to enabled. 1. Optional. Add existing projects to the token's access scope. The user adding a project must have the Maintainer role in both projects. -## Download an artifact from a different pipeline **(PREMIUM)** +## Download an artifact from a different pipeline **(PREMIUM ALL)** > `CI_JOB_TOKEN` for artifacts download with the API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in GitLab 9.5. diff --git a/doc/ci/jobs/index.md b/doc/ci/jobs/index.md index a0c0fc43502..762fb717505 100644 --- a/doc/ci/jobs/index.md +++ b/doc/ci/jobs/index.md @@ -4,7 +4,7 @@ group: Pipeline Authoring 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 --- -# Jobs **(FREE)** +# Jobs **(FREE ALL)** Pipeline configuration begins with jobs. Jobs are the most fundamental element of a `.gitlab-ci.yml` file. diff --git a/doc/ci/jobs/job_artifacts.md b/doc/ci/jobs/job_artifacts.md index 3dd43a9760c..b080a4fd1e9 100644 --- a/doc/ci/jobs/job_artifacts.md +++ b/doc/ci/jobs/job_artifacts.md @@ -4,7 +4,7 @@ group: Pipeline Security 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 --- -# Job artifacts **(FREE)** +# Job artifacts **(FREE ALL)** Jobs can output an archive of files and directories. This output is known as a job artifact. diff --git a/doc/ci/jobs/job_artifacts_troubleshooting.md b/doc/ci/jobs/job_artifacts_troubleshooting.md index f5951350085..ebed347e966 100644 --- a/doc/ci/jobs/job_artifacts_troubleshooting.md +++ b/doc/ci/jobs/job_artifacts_troubleshooting.md @@ -23,7 +23,7 @@ the keyword reference for information on how to fetch artifacts with these keywo ## Job artifacts use too much disk space If job artifacts are using too much disk space, see the -[job artifacts administration documentation](../../administration/job_artifacts.md#job-artifacts-using-too-much-disk-space). +[job artifacts administration documentation](../../administration/job_artifacts_troubleshooting.md#job-artifacts-using-too-much-disk-space). ## Error message `No files to upload` diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md index 09c7500a883..770e1d38297 100644 --- a/doc/ci/jobs/job_control.md +++ b/doc/ci/jobs/job_control.md @@ -4,7 +4,7 @@ group: Pipeline Authoring 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 --- -# Choose when to run jobs **(FREE)** +# Choose when to run jobs **(FREE ALL)** When a new pipeline starts, GitLab checks the pipeline configuration to determine which jobs should run in that pipeline. You can configure jobs to run depending on @@ -259,20 +259,20 @@ runs in all cases except merge requests. For behavior similar to the [`only`/`except` keywords](../yaml/index.md#only--except), you can check the value of the `$CI_PIPELINE_SOURCE` variable: -| Value | Description | -|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `api` | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). | -| `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/index.md) command. | -| `external` | When you use CI services other than GitLab. | -| `external_pull_request_event` | When an external pull request on GitHub is created or updated. See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). | +| Value | Description | +|-------------------------------|-------------| +| `api` | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). | +| `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/index.md) command. | +| `external` | When you use CI services other than GitLab. | +| `external_pull_request_event` | When an external pull request on GitHub is created or updated. See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). | | `merge_request_event` | For pipelines created when a merge request is created or updated. Required to enable [merge request pipelines](../pipelines/merge_request_pipelines.md), [merged results pipelines](../pipelines/merged_results_pipelines.md), and [merge trains](../pipelines/merge_trains.md). | -| `parent_pipeline` | For pipelines triggered by a [parent/child pipeline](../pipelines/downstream_pipelines.md#parent-child-pipelines) with `rules`. Use this pipeline source in the child pipeline configuration so that it can be triggered by the parent pipeline. | +| `parent_pipeline` | For pipelines triggered by a [parent/child pipeline](../pipelines/downstream_pipelines.md#parent-child-pipelines) with `rules`. Use this pipeline source in the child pipeline configuration so that it can be triggered by the parent pipeline. | | `pipeline` | For [multi-project pipelines](../pipelines/downstream_pipelines.md#multi-project-pipelines) created by [using the API with `CI_JOB_TOKEN`](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api), or the [`trigger`](../yaml/index.md#trigger) keyword. | -| `push` | For pipelines triggered by a `git push` event, including for branches and tags. | -| `schedule` | For [scheduled pipelines](../pipelines/schedules.md). | -| `trigger` | For pipelines created by using a [trigger token](../triggers/index.md#configure-cicd-jobs-to-run-in-triggered-pipelines). | -| `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **Build > Pipelines** section. | -| `webide` | For pipelines created by using the [WebIDE](../../user/project/web_ide/index.md). | +| `push` | For pipelines triggered by a `git push` event, including for branches and tags. | +| `schedule` | For [scheduled pipelines](../pipelines/schedules.md). | +| `trigger` | For pipelines created by using a [trigger token](../triggers/index.md#configure-cicd-jobs-to-run-in-triggered-pipelines). | +| `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **Build > Pipelines** section. | +| `webide` | For pipelines created by using the [WebIDE](../../user/project/web_ide/index.md). | The following example runs the job as a manual job in scheduled pipelines or in push pipelines (to branches or tags), with `when: on_success` (default). It does not @@ -617,7 +617,7 @@ To run a manual job, you must have permission to merge to the assigned branch: You can also [add custom CI/CD variables when running a manual job](index.md#specifying-variables-when-running-manual-jobs). -### Protect manual jobs **(PREMIUM)** +### Protect manual jobs **(PREMIUM ALL)** Use [protected environments](../environments/protected_environments.md) to define a list of users authorized to run a manual job. You can authorize only @@ -832,6 +832,83 @@ deploy: Quotes around the `dependencies` entry are required. +## Specify a parallelized job using needs with multiple parallelized jobs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254821) in GitLab 16.3. + +You can use variables defined in [`needs:parallel:matrix`](../yaml/index.md#needsparallelmatrix) with multiple parallelized jobs. + +For example: + +```yaml +linux:build: + stage: build + script: echo "Building linux..." + parallel: + matrix: + - PROVIDER: aws + STACK: + - monitoring + - app1 + - app2 + +mac:build: + stage: build + script: echo "Building mac..." + parallel: + matrix: + - PROVIDER: [gcp, vultr] + STACK: [data, processing] + +linux:rspec: + stage: test + needs: + - job: linux:build + parallel: + matrix: + - PROVIDER: aws + - STACK: app1 + script: echo "Running rspec on linux..." + +mac:rspec: + stage: test + needs: + - job: mac:build + parallel: + matrix: + - PROVIDER: [gcp, vultr] + - STACK: [data] + script: echo "Running rspec on mac..." + +production: + stage: deploy + script: echo "Running production..." + environment: production +``` + +This example generates several jobs. The parallel jobs each have different values +for `PROVIDER` and `STACK`. + +- 3 parallel `linux:build` jobs: + - `linux:build: [aws, monitoring]` + - `linux:build: [aws, app1]` + - `linux:build: [aws, app2]` +- 4 parallel `mac:build` jobs: + - `mac:build: [gcp, data]` + - `mac:build: [gcp, processing]` + - `mac:build: [vultr, data]` + - `mac:build: [vultr, processing]` +- A `linux:rspec` job. +- A `production` job. + +The jobs have three paths of execution: + +- Linux path: The `linux:rspec` job runs as soon as the `linux:build: [aws, app1]` + job finishes, without waiting for `mac:build` to finish. +- macOS path: The `mac:rspec` job runs as soon as the `mac:build: [gcp, data]` and + `mac:build: [vultr, data]` jobs finish, without waiting for `linux:build` to finish. +- The `production` job runs as soon as all previous jobs finish. + ## Use predefined CI/CD variables to run jobs only in specific pipeline types You can use [predefined CI/CD variables](../variables/predefined_variables.md) to choose diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md index 4b17f3354aa..da5ebe21341 100644 --- a/doc/ci/large_repositories/index.md +++ b/doc/ci/large_repositories/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Optimize GitLab for large repositories **(FREE)** +# Optimize GitLab for large repositories **(FREE ALL)** Large repositories consisting of more than 50k files in a worktree may require more optimizations beyond @@ -234,7 +234,6 @@ concurrent = 4 cache_dir = "/cache" environment = [ - "GIT_DEPTH=10", "GIT_CLONE_PATH=$CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_NAME" ] diff --git a/doc/ci/lint.md b/doc/ci/lint.md index f4c8a377c31..0ca0469f5e9 100644 --- a/doc/ci/lint.md +++ b/doc/ci/lint.md @@ -4,7 +4,7 @@ group: Pipeline Authoring 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 --- -# Validate GitLab CI/CD configuration **(FREE)** +# Validate GitLab CI/CD configuration **(FREE ALL)** Use the CI Lint tool to check the validity of GitLab CI/CD configuration. You can validate the syntax from a `.gitlab-ci.yml` file or any other sample CI/CD configuration. diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md index a05fe87013c..d70794639d1 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, howto --- -# Migrating from CircleCI **(FREE)** +# Migrating from CircleCI **(FREE ALL)** If you are currently using CircleCI, you can migrate your CI/CD pipelines to [GitLab CI/CD](../introduction/index.md), and start making use of all its powerful features. Check out our diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index f3f14da037f..54ea3812029 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, howto --- -# Migrating from Jenkins **(FREE)** +# Migrating from Jenkins **(FREE ALL)** A lot of GitLab users have successfully migrated to GitLab CI/CD from Jenkins. We've collected several resources here that you might find informative if you're just getting started. diff --git a/doc/ci/mobile_devops.md b/doc/ci/mobile_devops.md index a85de5e2a51..6969b3d4ef4 100644 --- a/doc/ci/mobile_devops.md +++ b/doc/ci/mobile_devops.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Mobile DevOps (Experimental) +# Mobile DevOps (Experiment) Use GitLab Mobile DevOps to quickly build, sign, and release native and cross-platform mobile apps for Android and iOS using GitLab CI/CD. Mobile DevOps is an experimental feature developed by @@ -41,10 +41,9 @@ test: ### iOS build environments -[GitLab SaaS runners on macOS](../ci/runners/saas/macos_saas_runner.md) are currently available in beta. +[GitLab SaaS runners on macOS](../ci/runners/saas/macos_saas_runner.md) are in Beta. -After you are granted access to the beta macOS runners, [choose an image](../ci/runners/saas/macos_saas_runner.md#supported-macos-images) -and add it to your `.gitlab-ci.yml` file. +[Choose an image](../ci/runners/saas/macos_saas_runner.md#supported-macos-images) to run a job on a macOS GitLab SaaS runner and add it to your `.gitlab-ci.yml` file. For example: @@ -89,7 +88,7 @@ For an overview, see [How to build and release an Android app to Google Play wit Run the following command to generate a keystore file if you don't already have one: ```shell -keytool -genkey -v -keystore release-keystore.jks -storepass password -alias release -keypass password -keyalg RSA -keysize 2048 -validity 10000 +keytool -genkey -v -keystore release-keystore.jks -storepass password -alias release -keypass password -keyalg RSA -keysize 2048 -validity 10000 ``` Next, put the keystore configuration in a file called `release-keystore.properties`, @@ -122,7 +121,7 @@ The next step is to configure Gradle to use the newly created keystore. In the a } ``` -1. Anywhere within the `android` block, add: +1. Anywhere in the `android` block, add: ```gradle signingConfigs { @@ -243,7 +242,7 @@ For example: ```ruby default_platform(:ios) - + platform :ios do desc "Build and sign the application for development" lane :build do @@ -299,7 +298,7 @@ to build and release Android apps. To enable the integration: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Google Play**. -1. In **Enable integration**, select the **Active** checkbox. +1. Under **Enable integration**, select the **Active** checkbox. 1. In **Package name**, enter the package name of the app. For example, `com.gitlab.app_name`. 1. In **Service account key (.JSON)** drag or upload your key file. 1. Select **Save changes**. @@ -356,7 +355,7 @@ to build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. To enable t 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Apple App Store**. -1. Turn on the **Active** toggle under **Enable Integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Provide the Apple App Store Connect configuration information: - **Issuer ID**: You can find the Apple App Store Connect Issuer ID in the **Keys** section under **Users and Access** in the Apple App Store Connect portal. - **Key ID**: The key ID of the new private key that was just generated. diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md index b6f30627b7e..5291a8abb49 100644 --- a/doc/ci/pipeline_editor/index.md +++ b/doc/ci/pipeline_editor/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Pipeline Editor **(FREE)** +# Pipeline Editor **(FREE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4540) in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/270059) in GitLab 13.10. diff --git a/doc/ci/pipelines/cicd_minutes.md b/doc/ci/pipelines/cicd_minutes.md index 6c7b00c827a..4e822cf3edd 100644 --- a/doc/ci/pipelines/cicd_minutes.md +++ b/doc/ci/pipelines/cicd_minutes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Compute quota **(PREMIUM)** +# Compute quota **(PREMIUM ALL)** > [Renamed](https://gitlab.com/groups/gitlab-com/-/epics/2150) from "CI/CD minutes" to "compute quota" or "compute minutes" in GitLab 16.1. @@ -152,7 +152,7 @@ For example, with a GitLab SaaS Premium license: If you use `13,000` compute minutes during the month, the next month your additional compute minutes become `2,000`. If you use `9,000` compute minutes during the month, your additional compute minutes remain the same. -If you bought additional compute minutes while on a trial subscription, those compute minutes are available after the trial ends or you upgrade to a paid plan. +Additional compute minutes bought on a trial subscription are available after the trial ends or upgrading to a paid plan. You can find pricing for additional compute minutes on the [GitLab Pricing page](https://about.gitlab.com/pricing/). @@ -269,8 +269,10 @@ GitLab SaaS runners have different cost factors, depending on the runner type (L | Linux OS amd64 | small | 1 | | Linux OS amd64 | medium | 2 | | Linux OS amd64 | large | 3 | +| Linux OS amd64 | xlarge | 6 | +| Linux OS amd64 | 2xlarge | 12 | | Linux OS amd64 + GPU-enabled | medium, GPU standard | 7 | -| macOS M1 | Medium | 6 | +| macOS M1 | medium | 6 (Beta) | | Windows Server | - | 1 (Beta) | ### Monthly reset of compute usage diff --git a/doc/ci/pipelines/downstream_pipelines.md b/doc/ci/pipelines/downstream_pipelines.md index 686020fc17a..fca6e8407ef 100644 --- a/doc/ci/pipelines/downstream_pipelines.md +++ b/doc/ci/pipelines/downstream_pipelines.md @@ -4,7 +4,7 @@ group: Pipeline Authoring 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 --- -# Downstream pipelines **(FREE)** +# Downstream pipelines **(FREE ALL)** A downstream pipeline is any GitLab CI/CD pipeline triggered by another pipeline. Downstream pipelines run independently and concurrently to the upstream pipeline @@ -209,8 +209,9 @@ To trigger a child pipeline from a dynamically generated configuration file: - generated-config.yml ``` -1. Configure the trigger job to run after the job that generated the configuration file, - and set `include: artifact` to the generated artifact: +1. Configure the trigger job to run after the job that generated the configuration file. + Set `include: artifact` to the generated artifact, and set `include: job` to + the job that created the artifact: ```yaml child-pipeline: @@ -381,7 +382,7 @@ trigger_job: ::EndTabs -### View multi-project pipelines in pipeline graphs **(PREMIUM)** +### View multi-project pipelines in pipeline graphs **(PREMIUM ALL)** After you trigger a multi-project pipeline, the downstream pipeline displays to the right of the [pipeline graph](index.md#visualize-pipelines). @@ -389,7 +390,51 @@ to the right of the [pipeline graph](index.md#visualize-pipelines). In [pipeline mini graphs](index.md#pipeline-mini-graphs), the downstream pipeline displays to the right of the mini graph. -## Fetch artifacts from an upstream pipeline **(PREMIUM)** +## Fetch artifacts from an upstream pipeline **(PREMIUM ALL)** + +::Tabs + +:::TabTitle Parent-child pipeline + +Use [`needs:pipeline:job`](../yaml/index.md#needspipelinejob) to fetch artifacts from an +upstream pipeline: + +1. In the upstream pipeline, save the artifacts in a job with the [`artifacts`](../yaml/index.md#artifacts) + keyword, then trigger the downstream pipeline with a trigger job: + + ```yaml + build_artifacts: + stage: build + script: + - echo "This is a test artifact!" >> artifact.txt + artifacts: + paths: + - artifact.txt + + deploy: + stage: deploy + trigger: + include: + - local: path/to/child-pipeline.yml + variables: + PARENT_PIPELINE_ID: $CI_PIPELINE_ID + ``` + +1. Use `needs:pipeline:job` in a job in the downstream pipeline to fetch the artifacts. + + ```yaml + test: + stage: test + script: + - cat artifact.txt + needs: + - pipeline: $PARENT_PIPELINE_ID + job: build_artifacts + ``` + + Set `job` to the job in the upstream pipeline that created the artifacts. + +:::TabTitle Multi-project pipeline Use [`needs:project`](../yaml/index.md#needsproject) to fetch artifacts from an upstream pipeline: @@ -408,7 +453,7 @@ upstream pipeline: deploy: stage: deploy - trigger: my/downstream_project + trigger: my/downstream_project # Path to the project to trigger a pipeline in ``` 1. Use `needs:project` in a job in the downstream pipeline to fetch the artifacts. @@ -431,6 +476,8 @@ upstream pipeline: - `ref` to the branch. - `artifacts` to `true`. +::EndTabs + ### Fetch artifacts from an upstream merge request pipeline When you use `needs:project` to [pass artifacts to a downstream pipeline](#fetch-artifacts-from-an-upstream-pipeline), @@ -623,7 +670,7 @@ Upstream pipelines take precedence over downstream ones. If there are two variables with the same name defined in both upstream and downstream projects, the ones defined in the upstream project take precedence. -### Pass dotenv variables created in a job **(PREMIUM)** +### Pass dotenv variables created in a job **(PREMIUM ALL)** You can pass variables to a downstream job with [`dotenv` variable inheritance](../variables/index.md#pass-an-environment-variable-to-another-job) and [`needs:project`](../yaml/index.md#needsproject). These variables are only available in diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 45af40a4cea..7cde8b50524 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# CI/CD pipelines **(FREE)** +# CI/CD pipelines **(FREE ALL)** NOTE: Watch the @@ -84,11 +84,11 @@ project repository. This table lists the refspecs injected for each pipeline type: -| Pipeline type | Refspecs | -|--------------- |---------------------------------------- | -| pipeline for branches | `+<sha>:refs/pipelines/<id>` and `+refs/heads/<name>:refs/remotes/origin/<name>` | -| pipeline for tags | `+<sha>:refs/pipelines/<id>` and `+refs/tags/<name>:refs/tags/<name>` | -| [merge request pipeline](../pipelines/merge_request_pipelines.md) | `+refs/pipelines/<id>:refs/pipelines/<id>` | +| Pipeline type | Refspecs | +|-------------------------------------------------------------------|----------| +| pipeline for branches | `+<sha>:refs/pipelines/<id>` and `+refs/heads/<name>:refs/remotes/origin/<name>` | +| pipeline for tags | `+<sha>:refs/pipelines/<id>` and `+refs/tags/<name>:refs/tags/<name>` | +| [merge request pipeline](../pipelines/merge_request_pipelines.md) | `+refs/pipelines/<id>:refs/pipelines/<id>` | The refs `refs/heads/<name>` and `refs/tags/<name>` exist in your project repository. GitLab generates the special ref `refs/pipelines/<id>` during a @@ -334,7 +334,7 @@ runners do not use regular runners, they must be tagged accordingly. Review the [deployment safety](../environments/deployment_safety.md) page for additional security recommendations for securing your pipelines. -## Trigger a pipeline when an upstream project is rebuilt **(PREMIUM)** +## Trigger a pipeline when an upstream project is rebuilt **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9045) in GitLab 12.8. @@ -352,6 +352,7 @@ To trigger the pipeline when the upstream project is rebuilt: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > CI/CD**. 1. Expand **Pipeline subscriptions**. +1. Select **Add project**. 1. Enter the project you want to subscribe to, in the format `<namespace>/<project>`. For example, if the project is `https://gitlab.com/gitlab-org/gitlab`, use `gitlab-org/gitlab`. 1. Select **Subscribe**. diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md index 045fa8dc16c..356b97aacc0 100644 --- a/doc/ci/pipelines/merge_request_pipelines.md +++ b/doc/ci/pipelines/merge_request_pipelines.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w --- -# Merge request pipelines **(FREE)** +# Merge request pipelines **(FREE ALL)** > [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/351192) from `pipelines for merge requests` to `merge request pipelines` in GitLab 14.8. @@ -67,7 +67,7 @@ To use merge request pipelines: ## Use `rules` to add jobs -You can use the [`rules`](../yaml/index.md#rules) keyword to configure jobs to run in +Use the [`rules`](../yaml/index.md#rules) keyword to configure jobs to run in merge request pipelines. For example: ```yaml @@ -95,10 +95,21 @@ job2: - echo "This job also runs in merge request pipelines" ``` +A common `workflow` configuration is to have pipelines run for merge requests, tags, and the default branch. For example: + +```yaml +workflow: + rules: + - if: $CI_PIPELINE_SOURCE == 'merge_request_event' + - if: $CI_COMMIT_TAG + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH +``` + ## Use `only` to add jobs -You can use the [`only`](../yaml/index.md#onlyrefs--exceptrefs) keyword with `merge_requests` -to configure jobs to run in merge request pipelines. +[`rules`](#use-rules-to-add-jobs) is the preferred method, but you can also use +the [`only`](../yaml/index.md#onlyrefs--exceptrefs) keyword with `merge_requests` +to configure jobs to run in merge request pipelines. For example: ```yaml job1: @@ -125,7 +136,7 @@ Pipelines for forks display with the **fork** badge in the parent project:  -### Run pipelines in the parent project **(PREMIUM)** +### Run pipelines in the parent project **(PREMIUM ALL)** Project members in the parent project can trigger a merge request pipeline for a merge request submitted from a fork project. This pipeline: diff --git a/doc/ci/pipelines/merge_trains.md b/doc/ci/pipelines/merge_trains.md index c2fdbe3f6e5..c2bf9743e4f 100644 --- a/doc/ci/pipelines/merge_trains.md +++ b/doc/ci/pipelines/merge_trains.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Merge trains **(PREMIUM)** +# Merge trains **(PREMIUM ALL)** NOTE: [In GitLab 16.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/359057), the **Start merge train** diff --git a/doc/ci/pipelines/merged_results_pipelines.md b/doc/ci/pipelines/merged_results_pipelines.md index 16120924f37..51678e64b10 100644 --- a/doc/ci/pipelines/merged_results_pipelines.md +++ b/doc/ci/pipelines/merged_results_pipelines.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Merged results pipelines **(PREMIUM)** +# Merged results pipelines **(PREMIUM ALL)** > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/351192) from `pipelines for merged results` to `merged results pipelines` in GitLab 14.8. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91849) in GitLab 15.1, merged results pipelines also run on [Draft merge requests](../../user/project/merge_requests/drafts.md). diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md index ac4c8c1a731..d0324f16ffb 100644 --- a/doc/ci/pipelines/pipeline_architectures.md +++ b/doc/ci/pipelines/pipeline_architectures.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Pipeline architecture **(FREE)** +# Pipeline architecture **(FREE ALL)** Pipelines are the fundamental building blocks for CI/CD in GitLab. This page documents some of the important concepts related to them. diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index c0c8d60b9d6..1d7d6c3289a 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Pipeline efficiency **(FREE)** +# Pipeline efficiency **(FREE ALL)** [CI/CD Pipelines](index.md) are the fundamental building blocks for [GitLab CI/CD](../index.md). Making pipelines more efficient helps you save developer time, which: diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md index 49b129f11aa..75a7d373203 100644 --- a/doc/ci/pipelines/schedules.md +++ b/doc/ci/pipelines/schedules.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Scheduled pipelines **(FREE)** +# Scheduled pipelines **(FREE ALL)** Use scheduled pipelines to run GitLab CI/CD [pipelines](index.md) at regular intervals. @@ -67,6 +67,9 @@ the next scheduled time: You can manually run scheduled pipelines once per minute. +When you run a scheduled pipeline manually, the pipeline runs with the +permissions of the user who triggered it, not the permissions of the schedule owner. + ## Take ownership Scheduled pipelines execute with the permissions of the user diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index fe6c88c9c4d..b9c95c63098 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Customize pipeline configuration **(FREE)** +# Customize pipeline configuration **(FREE ALL)** You can customize how pipelines run for your project. @@ -98,6 +98,7 @@ To avoid this scenario: 1. Select **Settings > CI/CD**. 1. Expand **General pipelines**. 1. Select the **Prevent outdated deployment jobs** checkbox. +1. Optional. Clear the **Allow job retries for rollback deployments** checkbox. 1. Select **Save changes**. For more information, see [Deployment safety](../environments/deployment_safety.md#prevent-outdated-deployment-jobs). diff --git a/doc/ci/quick_start/index.md b/doc/ci/quick_start/index.md index 80bb9f63413..8e6fa965aa4 100644 --- a/doc/ci/quick_start/index.md +++ b/doc/ci/quick_start/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Tutorial: Create and run your first GitLab CI/CD pipeline **(FREE)** +# Tutorial: Create and run your first GitLab CI/CD pipeline **(FREE ALL)** This tutorial shows you how to configure and run your first CI/CD pipeline in GitLab. diff --git a/doc/ci/resource_groups/index.md b/doc/ci/resource_groups/index.md index 74e3e493adb..cf29ab62240 100644 --- a/doc/ci/resource_groups/index.md +++ b/doc/ci/resource_groups/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: Control the job concurrency in GitLab CI/CD --- -# Resource group **(FREE)** +# Resource group **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) in GitLab 12.7. @@ -314,4 +314,4 @@ To get job information from the GraphQL API: } ``` - If the status is not `running` or `pending`, open a new issue. + If the status is not `running` or `pending`, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and [contact support](https://about.gitlab.com/support/#contact-support) so they can apply the correct labels to the issue. diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index e1be6118bab..d05861818e2 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Review apps **(FREE)** +# Review apps **(FREE ALL)** Review apps are a collaboration tool that provide an environment to showcase product changes. @@ -191,7 +191,7 @@ After you have the route mapping set up, it takes effect in the following locati - In the blob file view, by selecting **View** (**{external-link}**) next to the file. <!--- start_remove The following content will be removed on remove_date: '2024-05-22' --> -## Visual Reviews (deprecated) **(PREMIUM)** +## Visual Reviews (deprecated) **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10761) in GitLab 12.0. > - [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9. diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index 9424f8ea846..3e26c120f74 100644 --- a/doc/ci/runners/configure_runners.md +++ b/doc/ci/runners/configure_runners.md @@ -4,7 +4,7 @@ group: Runner 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 --- -# Configuring runners **(FREE)** +# Configuring runners **(FREE ALL)** If you have installed your own runners, you can configure and secure them in GitLab. @@ -57,60 +57,53 @@ How this feature works: 1. You start a job 1. The job, if running longer, times out after **30 minutes** -## Be careful with sensitive information +## Protecting sensitive information -With some [runner executors](https://docs.gitlab.com/runner/executors/), -if you can run a job on the runner, you can get full access to the file system, -and thus any code it runs as well as the token of the runner. With shared runners, this means that anyone -that runs jobs on the runner, can access another user's code that runs on the -runner. +To avoid exposing sensitive information, you can restrict the usage +of shared runners on large GitLab instances. This ensures that you +control access to your GitLab instances and secure [runner executors](https://docs.gitlab.com/runner/executors/). -In addition, because you can get access to the runner token, it is possible -to create a clone of a runner and submit false jobs, for example. - -The above is easily avoided by restricting the usage of shared runners -on large public GitLab instances, controlling access to your GitLab instance, -and using more secure [runner executors](https://docs.gitlab.com/runner/executors/). +If certain executors run a job, the file system, the code the runner executes, +and the runner token may be exposed. This means that anyone that runs jobs +on a _shared runner_ can access another user's code that runs on the runner. +Users with access to the runner token can use it to create a clone of +a runner and submit false jobs in a vector attack. For more information, see [Security Considerations](https://docs.gitlab.com/runner/security/). ### Prevent runners from revealing sensitive information -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13194) in GitLab 10.0. - -You can protect runners so they don't reveal sensitive information. -When a runner is protected, the runner picks jobs created on -[protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md) only, -and ignores other jobs. +To ensure runners don't reveal sensitive information, you can configure them to only run jobs +on [protected branches](../../user/project/protected_branches.md), or jobs that have [protected tags](../../user/project/protected_tags.md). -To protect or unprotect a runner: +To prevent runners from revealing sensitive information: -1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. -1. Find the runner you want to protect or unprotect. Make sure it's enabled. -1. Select the pencil button. -1. Check the **Protected** option. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > CI/CD**. +1. Expand **Runners**. +1. Find the runner you want to protect or unprotect. Make sure the runner is enabled. +1. Select **Edit** (**{pencil}**). +1. Select the **Protected** checkbox. 1. Select **Save changes**. - - -### Forks +### Using shared runners in forked projects -Whenever a project is forked, it copies the settings of the jobs that relate -to it. This means that if you have shared runners set up for a project and -someone forks that project, the shared runners serve jobs of this project. +When a project is forked, the job settings related to jobs are copied. If you have shared runners +configured for a project and a user forks that project, the shared runners serve jobs of this project. -Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/364303), you might encounter the message `An error occurred while forking the project. Please try again.` if the runner settings of the project you are forking does not match the new project namespace. +Due to a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/364303), if the runner settings +of the forked project does not match the new project namespace, the following message displays: +`An error occurred while forking the project. Please try again.`. -To work around this issue, you should make sure that the shared runner settings are consistent in the forked project and the new namespace. +To work around this issue, ensure that the shared runner settings are consistent in the forked project and the new namespace. - If shared runners are **enabled** on the forked project, then this should also be **enabled** on the new namespace. - If shared runners are **disabled** on the forked project, then this should also be **disabled** on the new namespace. -### Attack vectors in runners +### Reset the runner registration token for a project (deprecated) -Mentioned briefly earlier, but the following things of runners can be exploited. -We're always looking for contributions that can mitigate these -[Security Considerations](https://docs.gitlab.com/runner/security/). - -### Reset the runner registration token for a project +WARNING: +The ability to pass a runner registration token, and support for certain configuration arguments was +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 17.0. Authentication tokens +should be used instead. For more information, see [Migrating to the new runner registration workflow](new_creation_workflow.md). If you think that a registration token for a project was revealed, you should reset it. A registration token can be used to register another runner for the project. @@ -118,43 +111,42 @@ That new runner may then be used to obtain the values of secret variables or to To reset the registration token: -1. Go to the project's **Settings > CI/CD**. -1. Expand the **General pipelines settings** section. -1. Find the **Runner token** form field and select **Reveal value**. -1. Delete the value and save the form. -1. After the page is refreshed, expand the **Runners settings** section - and check the registration token - it should be changed. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > CI/CD**. +1. Expand **Runners**. +1. To the right of **New project runner**, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **Reset registration token**. +1. Select **Reset token**. -From now on the old token is no longer valid and does not register -any new runners to the project. If you are using any tools to provision and -register new runners, the tokens used in those tools should be updated to reflect the -value of the new token. +After you reset the registration token, it is no longer valid and does not register +any new runners to the project. You should also update the registration token in tools +you use to provision and register new values. ### Reset the runner authentication token -If you think that an authentication token for a runner was revealed, you should -reset it. An attacker could use the token to [clone a runner](https://docs.gitlab.com/runner/security/#cloning-a-runner). +If an authentication token is revealed, an attacker could use the token to [clone a runner](https://docs.gitlab.com/runner/security/#cloning-a-runner). -To reset the authentication token, [unregister the runner](https://docs.gitlab.com/runner/commands/#gitlab-runner-unregister) -and then [register](https://docs.gitlab.com/runner/commands/#gitlab-runner-register) it again. +To reset the authentication token: -To verify that the previous authentication token has been revoked, use the [Runners API](../../api/runners.md#verify-authentication-for-a-registered-runner). +1. Delete the runner: + - [Delete a shared runner](runners_scope.md#delete-shared-runners). + - [Delete a group runner](runners_scope.md#delete-a-group-runner). + - [Delete a project runner](runners_scope.md#delete-a-project-runner). +1. Create a new runner so that it is assigned a new authentication token: + - [Create a shared runner](runners_scope.md#create-a-shared-runner-with-an-authentication-token). + - [Create a group runner](runners_scope.md#create-a-group-runner-with-an-authentication-token). + - [Create a project runner](runners_scope.md#create-a-project-runner-with-an-authentication-token). +1. Optional. To verify that the previous authentication token has been revoked, use the [Runners API](../../api/runners.md#verify-authentication-for-a-registered-runner). ## Use tags to control which jobs a runner can run -You must set up a runner to be able to run all the different types of jobs -that it may encounter on the projects it's shared over. This would be -problematic for large amounts of projects, if it weren't for tags. +You can use [tags](../yaml/index.md#tags) to ensure that runners only run the jobs they are equipped +to run. For example, you can specify the `rails` tag for runners that have the dependencies to run +Rails test suites. -GitLab CI/CD tags are not the same as Git tags. GitLab CI/CD tags are associated with runners. +GitLab CI/CD tags are different to Git tags. GitLab CI/CD tags are associated with runners. Git tags are associated with commits. -By tagging a runner for the types of jobs it can handle, you can make sure -shared runners will [only run the jobs they are equipped to run](../yaml/index.md#tags). - -For instance, at GitLab we have runners tagged with `rails` if they contain -the appropriate dependencies to run Rails test suites. - ### Set a runner to run untagged jobs When you [register a runner](https://docs.gitlab.com/runner/register/), its default behavior is to **only pick** @@ -302,9 +294,6 @@ When using the Kubernetes executor, you can use variables to ### Git strategy -> - Introduced in GitLab 8.9 as an experimental feature. -> - `GIT_STRATEGY=none` requires GitLab Runner v1.7+. - You can set the `GIT_STRATEGY` used to fetch the repository content, either globally or per-job in the [`variables`](../yaml/index.md#variables) section: @@ -341,8 +330,6 @@ rely on files brought into the local working copy from cache or artifacts. ### Git submodule strategy -> Requires GitLab Runner v1.10+. - The `GIT_SUBMODULE_STRATEGY` variable is used to control if / how Git submodules are included when fetching the code before a build. You can set them globally or per-job in the [`variables`](../yaml/index.md#variables) section. @@ -381,8 +368,6 @@ You can provide additional flags to control advanced behavior using [`GIT_SUBMOD ### Git checkout -> Introduced in GitLab Runner 9.3. - The `GIT_CHECKOUT` variable can be used when the `GIT_STRATEGY` is set to either `clone` or `fetch` to specify whether a `git checkout` should be run. If not specified, it defaults to true. You can set them globally or per-job in the @@ -410,8 +395,6 @@ script: ### Git clean flags -> Introduced in GitLab Runner 11.10 - The `GIT_CLEAN_FLAGS` variable is used to control the default behavior of `git clean` after checking out the sources. You can set it globally or per-job in the [`variables`](../yaml/index.md#variables) section. @@ -437,8 +420,6 @@ script: ### Git fetch extra flags -> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4142) in GitLab Runner 13.1. - Use the `GIT_FETCH_EXTRA_FLAGS` variable to control the behavior of `git fetch`. You can set it globally or per-job in the [`variables`](../yaml/index.md#variables) section. @@ -503,8 +484,6 @@ to wrap the string in single quotes so the YAML can be parsed successfully. ### Git submodule update flags -> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3192) in GitLab Runner 14.8. - Use the `GIT_SUBMODULE_UPDATE_FLAGS` variable to control the behavior of `git submodule update` when [`GIT_SUBMODULE_STRATEGY`](#git-submodule-strategy) is set to either `normal` or `recursive`. You can set it globally or per-job in the [`variables`](../yaml/index.md#variables) section. @@ -561,8 +540,6 @@ the permissions of the user executing the job, and does not require SSH credenti ### Shallow cloning -> Introduced in GitLab 8.9 as an experimental feature. - You can specify the depth of fetching and cloning using `GIT_DEPTH`. `GIT_DEPTH` does a shallow clone of the repository and can significantly speed up cloning. It can be helpful for repositories with a large number of commits or old, large binaries. The value is @@ -613,8 +590,6 @@ variables: ### Custom build directories -> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2211) in GitLab Runner 11.10. - By default, GitLab Runner clones the repository in a unique subpath of the `$CI_BUILDS_DIR` directory. However, your project might require the code in a specific directory (Go projects, for example). In that case, you can specify @@ -696,8 +671,6 @@ because `$CI_BUILDS_DIR` is not expanded. ### Job stages attempts -> Introduced in GitLab, it requires GitLab Runner v1.9+. - You can set the number of attempts that the running job tries to execute the following stages: @@ -725,8 +698,6 @@ GitLab.com shared runners run on CoreOS. This means that you cannot use some sys ## Artifact and cache settings -> Introduced in GitLab Runner 13.9. - Artifact and cache settings control the compression ratio of artifacts and caches. Use these settings to specify the size of the archive produced by a job. diff --git a/doc/ci/runners/img/protected_runners_check_box_v14_1.png b/doc/ci/runners/img/protected_runners_check_box_v14_1.png Binary files differdeleted file mode 100644 index d67085d83f9..00000000000 --- a/doc/ci/runners/img/protected_runners_check_box_v14_1.png +++ /dev/null diff --git a/doc/ci/runners/new_creation_workflow.md b/doc/ci/runners/new_creation_workflow.md index fce4b57b2a1..55ff5165ff7 100644 --- a/doc/ci/runners/new_creation_workflow.md +++ b/doc/ci/runners/new_creation_workflow.md @@ -4,7 +4,7 @@ group: Runner 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 --- -# Migrating to the new runner registration workflow **(FREE)** +# Migrating to the new runner registration workflow **(FREE ALL)** DISCLAIMER: This page contains information related to upcoming products, features, and functionality. diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index 840eb7fe93b..fff695eb606 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.md @@ -40,7 +40,7 @@ If you are using GitLab.com: > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/389269) in GitLab 16.0. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415447) in GitLab 16.2. Feature flag `create_runner_workflow_for_admin` removed. -Prerequisites: +Prerequisite: - You must be an administrator. @@ -69,7 +69,7 @@ The ability to pass a runner registration token, and support for certain configu [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 17.0. Authentication tokens should be used instead. For more information, see [Migrating to the new runner registration workflow](new_creation_workflow.md). -Prerequisites: +Prerequisite: - You must be an administrator. @@ -82,6 +82,44 @@ To create a shared runner: 1. Copy the registration token. 1. [Register the runner](https://docs.gitlab.com/runner/register/). +### Pause or resume a shared runner + +Prerequisite: + +- You must be an administrator. + +You can pause a runner so that it does not accept jobs from groups and projects in the GitLab instance. + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **CI/CD > Runners**. +1. In the search box, enter the runner description or filter the runner list. +1. In the runner list, to the right of the runner: + - To pause the runner, select **Pause** (**{pause}**). + - To resume the runner, select **Resume** (**{play}**). + +### Delete shared runners + +Prerequisite: + +- You must be an administrator. + +When you delete a shared runner, it is permanently deleted from the GitLab instance and can +no longer be used by groups and projects. If you want to temporarily stop the runner from accepting +jobs, you can [pause](#pause-or-resume-a-shared-runner) the runner instead. + +To delete a single or multiple shared runners: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **CI/CD > Runners**. +1. In the search box, enter the runner description or filter the list of runners. +1. Delete the shared runner: + - To delete a single runner, next to the runner, select **Delete runner** (**{remove}**). + - To delete multiple shared runners, select the checkbox for each runner and select **Delete selected**. + - To delete all runners, select the checkbox at the top of the runner list and select **Delete selected**. +1. Select **Permanently delete runner**. + ### Enable shared runners for a project On GitLab.com, [shared runners](index.md) are enabled in all projects by @@ -182,7 +220,7 @@ When only one job runs at a time, the fair usage algorithm assigns jobs in this Use _group runners_ when you want all projects in a group to have access to a set of runners. -Group runners process jobs by using a first in, first out ([FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))) queue. +Group runners process jobs by using a first in, first out queue. ### Create a group runner with an authentication token @@ -237,8 +275,6 @@ how to [register a runner](https://docs.gitlab.com/runner/register/). ### View and manage group runners -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/37366/) in GitLab 13.2. - You can view and manage all runners for a group, its subgroups, and projects. You can do this for your self-managed GitLab instance or for GitLab.com. You must have the Owner role for the group. @@ -248,25 +284,6 @@ You must have the Owner role for the group. From this page, you can edit, pause, and remove runners from the group, its subgroups, and projects. -#### Delete multiple group runners - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361721/) in GitLab 15.6 - -Prerequisites: - -- You must have either: - - Owner role for the group. - - Access to delete any runners in the group. - -To delete multiple runners in a single action in the group list: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. Select **Build > Runners**. -1. To delete multiple runners, you can either: - - Select the checkbox next to the runner. - - Select the checkbox at the top of the runner list to select all runners in the list. -1. To delete the runners, select **Delete selected**. - #### Filter group runners to show only inherited > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337838/) in GitLab 15.5. @@ -284,20 +301,46 @@ those in other groups: 1. Select **Build > Runners**. 1. Above the list, turn off the **Show only inherited** toggle. -### Pause or remove a group runner +### Pause or resume a group runner -You can pause or remove a group runner for your self-managed GitLab instance or for GitLab.com. -You must have the Owner role for the group. +Prerequisite: + +- You must be an administrator or have the Owner role for the group. + +You can pause a runner so that it does not accept jobs from subgroups and projects in the GitLab +instance. If you pause a group runner that is used by multiple projects, the runner pauses for all projects. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Build > Runners**. +1. In the search box, enter the runner description or filter the runner list. +1. In the runner list, to the right of the runner: + - To pause the runner, select **Pause** (**{pause}**). + - To resume the runner, select **Resume** (**{play}**). + +### Delete a group runner + +> Multiple runner deletion [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361721/) in GitLab 15.6. + +Prerequisite: + +- You must be an administrator or have the Owner role for the group. + +When you delete a group runner, it is permanently deleted from the GitLab instance and can +no longer be used by subgroups and projects. If you want to temporarily stop the runner from accepting +jobs, you can [pause](#pause-or-resume-a-group-runner) the runner instead. + +To delete a single or multiple group runners: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. Select **Build > Runners**. -1. Select **Pause** or **Remove runner**. - - If you pause a group runner that is used by multiple projects, the runner pauses for all projects. - - From the group view, you cannot remove a runner that is assigned to more than one project. - You must remove it from each project first. -1. On the confirmation dialog, select **OK**. +1. In the search box, enter the runner description or filter the list of runners. +1. Delete the group runner: + - To delete a single runner, next to the runner, select **Delete runner** (**{remove}**). + - To delete multiple shared runners, select the checkbox for each runner and select **Delete selected**. + - To delete all runners, select the checkbox at the top of the runner list and select **Delete selected**. +1. Select **Permanently delete runner**. -### Clean up stale group runners **(ULTIMATE)** +### Clean up stale group runners **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363012) in GitLab 15.1. @@ -407,6 +450,43 @@ To create a project runner: The runner is now enabled for the project. +### Pause or resume a project runner + +Prerequisite: + +- You must be an administrator, or have the Maintainer role for the project. + +You can pause a project runner so that it does not accept jobs from projects it's assigned to +in the GitLab instance. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to + find the project where you want to enable the runner. +1. Select **Settings > CI/CD**. +1. Expand **Runners**. +1. In the **Assigned project runners** section, find the runner. +1. To the right of the runner: + - To pause the runner, select **Pause** (**{pause}**), then select **Pause**. + - To resume the runner, select **Resume** (**{play}**). + +### Delete a project runner + +Prerequisites: + +- You must be an administrator, or have the Maintainer role for the project. +- You cannot delete a project runner that is assigned to more than one project. Before you can delete the runner, you must [disable](#enable-a-project-runner-for-a-different-project) it in all projects where it is enabled. + +When you delete a project runner, it is permanently deleted from the GitLab instance and can +no longer be used by projects. If you want to temporarily stop the runner from accepting +jobs, you can [pause](#pause-or-resume-a-project-runner) the runner instead. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to + find the project where you want to enable the runner. +1. Select **Settings > CI/CD**. +1. Expand **Runners**. +1. In the **Assigned project runners** section, find the runner. +1. To the right of the runner, select **Remove runner**. +1. To delete the runner, select **Remove**. + ### Enable a project runner for a different project After a project runner is created, you can enable it for other projects. @@ -460,26 +540,25 @@ A runner can have one of the following statuses. | `stale` | The runner has not contacted GitLab in more than 3 months. If the runner was created more than 3 months ago, but it never contacted the instance, it is also considered **stale**. | | `never_contacted` | The runner has never contacted GitLab. To make the runner contact GitLab, run `gitlab-runner run`. | -## View statistics for runner performance **(ULTIMATE)** +## View statistics for runner performance **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377963) in GitLab 15.8. As an administrator, you can view runner statistics to learn about the performance of your runner fleet. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. On the left sidebar, select **CI/CD > Runners**. -1. Select **View metrics**. - -The **Median job queued time** value is calculated by sampling the queue duration of the +- The **Median job queued time** value is calculated by sampling the queue duration of the most recent 100 jobs that were run by Instance runners. Jobs from only the latest 5000 runners are considered. - -The median is a value that falls into the 50th percentile: half of the jobs +- The median is a value that falls into the 50th percentile: half of the jobs queued for longer than the median value, and half of the jobs queued for less than the median value. -## Determine which runners need to be upgraded **(ULTIMATE)** +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **CI/CD > Runners**. +1. Select **View metrics**. + +## Determine which runners need to be upgraded **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365078) in GitLab 15.3. diff --git a/doc/ci/runners/saas/gpu_saas_runner.md b/doc/ci/runners/saas/gpu_saas_runner.md index a05b162ac84..6dc9d8c9534 100644 --- a/doc/ci/runners/saas/gpu_saas_runner.md +++ b/doc/ci/runners/saas/gpu_saas_runner.md @@ -44,3 +44,10 @@ gpu-job: ``` If you don't want to install larger libraries such as Tensorflow or XGBoost each time you run a job, you can create your own image with all the required components pre-installed. +Watch this demo to learn how to leverage GPU-enabled SaaS runners to train an XGBoost model: +<div class="video-fallback"> + Video demonstration of GitLab GPU-Enabled SaaS runners: <a href="https://youtu.be/tElegG4NCZ0">Train XGboost models with GitLab</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/tElegG4NCZ0" frameborder="0" allowfullscreen> </iframe> +</figure> diff --git a/doc/ci/runners/saas/linux_saas_runner.md b/doc/ci/runners/saas/linux_saas_runner.md index 95917bbc300..dd5381f3cd6 100644 --- a/doc/ci/runners/saas/linux_saas_runner.md +++ b/doc/ci/runners/saas/linux_saas_runner.md @@ -20,8 +20,10 @@ For Free, Premium, and Ultimate plan customers, jobs on these instances consume | Runner Tag | vCPUs | Memory | Storage | |-----------------------------------------------|-------|--------|---------| | `saas-linux-small-amd64` | 2 | 8 GB | 25 GB | -| `saas-linux-medium-amd64` **(PREMIUM SAAS)** | 4 | 16 GB | 50 GB | -| `saas-linux-large-amd64` **(PREMIUM SAAS)** | 8 | 32 GB | 100 GB | +| `saas-linux-medium-amd64` | 4 | 16 GB | 50 GB | +| `saas-linux-large-amd64` **(PREMIUM SAAS)** | 8 | 32 GB | 100 GB | +| `saas-linux-xlarge-amd64` **(PREMIUM SAAS)** | 16 | 64 GB | 200 GB | +| `saas-linux-2xlarge-amd64` **(PREMIUM SAAS)** | 32 | 128 GB | 200 GB | The `small` machine type is set as default. If no [tag](../../yaml/index.md#tags) keyword in your `.gitlab-ci.yml` file is specified, the jobs will run on this default runner. diff --git a/doc/ci/runners/saas/macos_saas_runner.md b/doc/ci/runners/saas/macos_saas_runner.md index a559fc7d53e..44f99ed6ccc 100644 --- a/doc/ci/runners/saas/macos_saas_runner.md +++ b/doc/ci/runners/saas/macos_saas_runner.md @@ -117,6 +117,51 @@ variables: HOMEBREW_NO_AUTO_UPDATE: 1 ``` +## Optimizing Cocoapods + +If you use Cocoapods in a project, you should consider the following optimizations to improve CI performance. + +**Cocoapods CDN** + +You can use content delivery network (CDN) access to download packages from the CDN instead of having to clone an entire +project repository. CDN access is available in Cocoapods 1.8 or later and is supported by all GitLab SaaS runners on macOS. + +To enable CDN access, ensure your Podfile starts with: + +```ruby +source 'https://cdn.cocoapods.org/' +``` + +**Use GitLab caching** + +Use caching in Cocoapods packages in GitLab to only run `pod install` +when pods change, which can improve build performance. + +To [configure caching](../../../ci/caching/index.md) for your project: + +1. Add the `cache` configuration to your `.gitlab-ci.yml` file: + + ```yaml + cache: + key: + files: + - Podfile.lock + paths: + - Pods + ``` + +1. Add the [`cocoapods-check`](https://guides.cocoapods.org/plugins/optimising-ci-times.html) plugin to your project. +1. Update the job script to check for installed dependencies before it calls `pod install`: + + ```shell + bundle exec pod check || bundle exec pod install + ``` + +**Include pods in source control** + +You can also [include the pods directory in source control](https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control). This eliminates the need to install pods as part of the CI job, +but it does increase the overall size of your project's repository. + ## Known issues and usage constraints - If the VM image does not include the specific software version you need for your job, the required software must be fetched and installed. This causes an increase in job execution time. diff --git a/doc/ci/secrets/azure_key_vault.md b/doc/ci/secrets/azure_key_vault.md new file mode 100644 index 00000000000..645ab5db0d1 --- /dev/null +++ b/doc/ci/secrets/azure_key_vault.md @@ -0,0 +1,49 @@ +--- +stage: Verify +group: Pipeline Security +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 +type: concepts, howto +--- + +# Use Azure Key Vault secrets in GitLab CI/CD **(PREMIUM ALL)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271271) in GitLab and GitLab Runner 16.3. + +You can use secrets stored in the [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault/) +in your GitLab CI/CD pipelines. + +Prerequisites: + +- Have a key vault on Azure. +- Have an application with key vault permissions. +- [Configure OpenID Connect in Azure to retrieve temporary credentials](../../ci/cloud_services/azure/index.md). +- Add [CI/CD variables to your project](../variables/index.md#for-a-project) to provide details about your Vault server: + - `AZURE_KEY_VAULT_SERVER_URL`: The URL of your Azure Key Vault server, such as `https://vault.example.com`. + - `AZURE_CLIENT_ID`: The client ID of the Azure application. + - `AZURE_TENANT_ID`: The tenant ID of the Azure application. + +## Use Azure Key Vault secrets in a CI/CD job + +You can use a secret stored in your Azure Key Vault in a job by defining it with the +[`azure_key_vault`](../yaml/index.md#secretsazure_key_vault) keyword: + +```yaml +job: + id_tokens: + AZURE_JWT: + aud: 'azure' + secrets: + DATABASE_PASSWORD: + token: AZURE_JWT + azure_key_vault: + name: 'test' + version: 'test' +``` + +In this example: + +- `name` is the name of the secret. +- `version` is the version of the secret. +- GitLab fetches the secret from Azure Key Vault and stores the value in a temporary file. + The path to this file is stored in a `DATABASE_PASSWORD` CI/CD variable, similar to + [file type CI/CD variables](../variables/index.md#use-file-type-cicd-variables). diff --git a/doc/ci/secrets/convert-to-id-tokens.md b/doc/ci/secrets/convert-to-id-tokens.md index e9f0d0ef5b0..18803d4de72 100644 --- a/doc/ci/secrets/convert-to-id-tokens.md +++ b/doc/ci/secrets/convert-to-id-tokens.md @@ -5,9 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# Tutorial: Update HashiCorp Vault configuration to use ID Tokens **(PREMIUM)** +# Tutorial: Update HashiCorp Vault configuration to use ID Tokens **(PREMIUM ALL)** -This tutorial demonstrates how to convert your existing CI/CI secrets configuration to use [ID Tokens](../secrets/id_token_authentication.md). +This tutorial demonstrates how to convert your existing CI/CD secrets configuration to use [ID Tokens](../secrets/id_token_authentication.md). The `CI_JOB_JWT` variables are deprecated, but updating to ID tokens requires some important configuration changes to work with Vault. If you have more than a handful of jobs, converting everything at once is a daunting task. @@ -20,10 +20,15 @@ Jobs that don't use `secrets:vault` can still use `CI_JOB_JWT` tokens. This tutorial will focus on v16 onwards, if you are running a slightly older version you will need to toggle the `Limit JSON Web Token (JWT) access` setting as appropriate. -To update your vault configuration to use ID tokens: +There isn't one standard method to migrate to [ID tokens](../secrets/id_token_authentication.md), so this tutorial includes two variations for how to convert your existing CI/CD secrets. Choose the method that is most appropriate for your use case: -1. [Create a second JWT authentication path in Vault](#create-a-second-jwt-authentication-path-in-vault) -1. [Recreate roles to use the new authentication path](#recreate-roles-to-use-the-new-authentication-path) +1. Update your Vault configuration: + - Method A: Migrate JWT roles to the new Vault auth method + 1. [Create a second JWT authentication path in Vault](#create-a-second-jwt-authentication-path-in-vault) + 1. [Recreate roles to use the new authentication path](#recreate-roles-to-use-the-new-authentication-path) + - Method B: Move `iss` claim to roles for the migration window + 1. [Add `bound_issuers` claim map to each role](#add-bound_issuers-claim-map-to-each-role) + 1. [Remove `bound_issuers` claim from auth method](#remove-bound_issuers-claim-from-auth-method) 1. [Update your CI/CD Jobs](#update-your-cicd-jobs) ## Prerequisites @@ -36,10 +41,17 @@ To follow along, you must have: - A Vault server that you are already using. - CI/CD jobs retrieving secrets from Vault with `CI_JOB_JWT`. -In the examples below, replace `vault.example.com` with the URL of your Vault server, -and `gitlab.example.com` with the URL of your GitLab instance. +In the examples below, replace: -## Create a second JWT authentication path in Vault +- `vault.example.com` with the URL of your Vault server. +- `gitlab.example.com` with the URL of your GitLab instance. +- `jwt` or `jwt_v2` with your auth method names. + +## Method A: Migrate JWT roles to the new Vault auth method + +This method creates a second JWT auth method in parallel to the existing one in use. Afterwards all Vault roles used for the GitLab integration are recreated in this new auth method. + +### Create a second JWT authentication path in Vault As part of the transition from `CI_JOB_JWT` to ID tokens, you must update the `bound_issuer` in Vault to include `https://`: @@ -69,7 +81,7 @@ You can create multiple authentication paths in Vault, which enable you to trans bound_issuer="https://gitlab.example.com" ``` -## Recreate roles to use the new authentication path +### Recreate roles to use the new authentication path Roles are bound to a specific authentication path so you need to add new roles for each job. @@ -113,6 +125,63 @@ Roles are bound to a specific authentication path so you need to add new roles f You only need to update `jwt` to `jwt_v2` in the `vault` command, do not change the `role_type` inside the role. +## Method B: Move `iss` claim to roles for migration window + +This method doesn't require Vault administrators to create a second JWT auth method and recreate all GitLab related roles. + +### Add `bound_issuers` claim map to each role + +Vault doesn't allow multiple `iss` claims on the JWT auth method level, as the [`bound_issuer`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#bound_issuer) +directive on this level only accepts a single value. However, multiple claims can be configured +on the role level by using the [`bound_claims`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#bound_claims) +map configuration directive. + +With this method you can provide Vault with multiple options for the `iss` claim validation. This supports the `https://` prefixed GitLab instance hostname claim that comes with the `id_tokens`, as well as the old non-prefixed claim. + +To add the [`bound_claims`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#bound_claims) configuration to the required roles, run: + +```shell +$ vault write auth/jwt/role/myproject-staging - <<EOF +{ + "role_type": "jwt", + "policies": ["myproject-staging"], + "token_explicit_max_ttl": 60, + "user_claim": "user_email", + "bound_claims": { + "iss": [ + "https://gitlab.example.com", + "gitlab.example.com" + ], + "project_id": "22", + "ref": "master", + "ref_type": "branch" + } +} +EOF +``` + +You do not need to alter any existing role configurations except for the `bound_claims` section +Make sure to add the `iss` configuration as shown above to ensure Vault accepts +the prefixed and non-prefixed `iss` claim for this role. + +You must apply this change to all JWT roles used for the GitLab integration before moving on to the next step. + +You can revert the migration of the `iss` claim validation from the auth method to the roles if desired, +after all projects have been migrated and you no longer need parallel support for `CI_JOB_JWT` and ID tokens. + +### Remove `bound_issuers` claim from auth method + +After all roles have been updated with the `bound_claims.iss` claims, you can remove the auth method level configuration for this validation: + +```shell +$ vault write auth/jwt/config \ + jwks_url="https://gitlab.example.com/-/jwks" \ + bound_issuer="" +``` + +Setting the `bound_issuer` directive to an empty string removes the issuer validation on the auth method level. +However, as we have moved this validation to the role level, this configuration is still secure. + ## Update your CI/CD Jobs Vault has two different [KV Secrets Engines](https://developer.hashicorp.com/vault/docs/secrets/kv) and the version you are using impacts how you define secrets in CI/CD. @@ -124,7 +193,12 @@ Also, if needed you can review the CI/CD documentation for: - [`secrets:`](../yaml/index.md#secrets) - [`id_tokens:`](../yaml/index.md#id_tokens) -The following examples show how to obtain the staging database password written to the `password` field in `secret/myproject/staging/db` +The following examples show how to obtain the staging database password written to the `password` field in `secret/myproject/staging/db`. + +The value for the `VAULT_AUTH_PATH` variable depends on the migration method you used: + +- Method A (Migrate JWT roles to the new Vault auth method): Use `jwt_v2`. +- Method B (Move `iss` claim to roles for migration window): Use `jwt`. ### KV Secrets Engine v1 @@ -134,7 +208,7 @@ The [`secrets:vault`](../yaml/index.md#secretsvault) keyword defaults to v2 of t job: variables: VAULT_SERVER_URL: https://vault.example.com - VAULT_AUTH_PATH: jwt_v2 + VAULT_AUTH_PATH: jwt_v2 # or "jwt" if you used method B VAULT_AUTH_ROLE: myproject-staging id_tokens: VAULT_ID_TOKEN: @@ -165,7 +239,7 @@ Long format: job: variables: VAULT_SERVER_URL: https://vault.example.com - VAULT_AUTH_PATH: jwt_v2 + VAULT_AUTH_PATH: jwt_v2 # or "jwt" if you used method B VAULT_AUTH_ROLE: myproject-staging id_tokens: VAULT_ID_TOKEN: @@ -189,7 +263,7 @@ You can also use a short format: job: variables: VAULT_SERVER_URL: https://vault.example.com - VAULT_AUTH_PATH: jwt_v2 + VAULT_AUTH_PATH: jwt_v2 # or "jwt" if you used method B VAULT_AUTH_ROLE: myproject-staging id_tokens: VAULT_ID_TOKEN: @@ -201,3 +275,5 @@ job: ``` After you commit the updated CI/CD configuration, your jobs will be fetching secrets with ID Tokens, congratulations! + +If you have migrated all projects to fetch secrets with ID Tokens and used method B for the migration, it is now possible to move the `iss` claim validation back to the auth method configuration if you desire. diff --git a/doc/ci/secrets/id_token_authentication.md b/doc/ci/secrets/id_token_authentication.md index 509bb6f07cf..22a260e4bb6 100644 --- a/doc/ci/secrets/id_token_authentication.md +++ b/doc/ci/secrets/id_token_authentication.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# OpenID Connect (OIDC) Authentication Using ID Tokens **(FREE)** +# OpenID Connect (OIDC) Authentication Using ID Tokens **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356986) in GitLab 15.7. @@ -76,6 +76,7 @@ The token also includes custom claims provided by GitLab: | `sha` | Always | The commit SHA for the job. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404722) in GitLab 16.0. | | `ci_config_ref_uri` | Always | The ref path to the top-level pipeline definition, for example, `gitlab.example.com/my-group/my-project//.gitlab-ci.yml@refs/heads/main`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404722) in GitLab 16.2. This claim is `null` unless the pipeline definition is located in the same project. | | `ci_config_sha` | Always | Git commit SHA for the `ci_config_ref_uri`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404722) in GitLab 16.2. This claim is `null` unless the pipeline definition is located in the same project. | +| `project_visibility` | Always | The [visibility](../../user/public_access.md) of the project where the pipeline is running. Can be `internal`, `private`, or `public`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418810) in GitLab 16.3. | ```json { @@ -103,6 +104,7 @@ The token also includes custom claims provided by GitLab: "runner_id": 1, "runner_environment": "self-hosted", "sha": "714a629c0b401fdce83e847fc9589983fc6f46bc", + "project_visibility": "public", "ci_config_ref_uri": "gitlab.example.com/my-group/my-project//.gitlab-ci.yml@refs/heads/main", "ci_config_sha": "714a629c0b401fdce83e847fc9589983fc6f46bc", "jti": "235b3a54-b797-45c7-ae9a-f72d7bc6ef5b", @@ -136,7 +138,7 @@ manual_authentication: - my-authentication-script.sh $VAULT_TOKEN $PASSWORD ``` -## Automatic ID Token authentication with HashiCorp Vault **(PREMIUM)** +## Automatic ID Token authentication with HashiCorp Vault **(PREMIUM ALL)** You can use ID tokens to automatically fetch secrets from HashiCorp Vault with the [`secrets`](../yaml/index.md#secrets) keyword. diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md index db9f36f295a..c184102d948 100644 --- a/doc/ci/secrets/index.md +++ b/doc/ci/secrets/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Using external secrets in CI **(FREE)** +# Using external secrets in CI **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218746) in GitLab 13.4 and GitLab Runner 13.4. > - `file` setting [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250695) in GitLab 14.1 and GitLab Runner 14.1. @@ -97,7 +97,7 @@ To configure your Vault server: NOTE: Support for providing these values in the user interface [is tracked in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/218677). -## Use Vault secrets in a CI job **(PREMIUM)** +## Use Vault secrets in a CI job **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in GitLab 13.4 and GitLab Runner 13.4. diff --git a/doc/ci/secure_files/index.md b/doc/ci/secure_files/index.md index b3ccf071996..37c453a5b9d 100644 --- a/doc/ci/secure_files/index.md +++ b/doc/ci/secure_files/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Project-level Secure Files **(FREE)** +# Project-level Secure Files **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78227) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `ci_secure_files`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350748) in GitLab 15.7. Feature flag `ci_secure_files` removed. diff --git a/doc/ci/services/gitlab.md b/doc/ci/services/gitlab.md index bd31f1b8e91..54fc664ef12 100644 --- a/doc/ci/services/gitlab.md +++ b/doc/ci/services/gitlab.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Use GitLab as a microservice **(FREE)** +# Use GitLab as a microservice **(FREE ALL)** Many applications need to access JSON APIs, so application tests might need access to APIs too. The following example shows how to use GitLab as a microservice to give diff --git a/doc/ci/services/index.md b/doc/ci/services/index.md index f4c90934e06..f92c50fcf3f 100644 --- a/doc/ci/services/index.md +++ b/doc/ci/services/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index --- -# Services **(FREE)** +# Services **(FREE ALL)** When you configure CI/CD, you specify an image, which is used to create the container where your jobs run. To specify this image, you use the `image` keyword. @@ -48,7 +48,7 @@ socket or `localhost`. Read more in [accessing the services](#accessing-the-serv ## How the health check of services works Services are designed to provide additional features which are **network accessible**. -They may be a database like MySQL, or Redis, and even `docker:stable-dind` which +They may be a database like MySQL, or Redis, and even `docker:dind` which allows you to use Docker-in-Docker. It can be practically anything that's required for the CI/CD job to proceed, and is accessed by network. diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index e795c4ffc5f..d02df1faf55 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Using MySQL **(FREE)** +# Using MySQL **(FREE ALL)** Many applications depend on MySQL as their database, and you may need it for your tests to run. diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index ab38d2ce934..b491786b4a1 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Using PostgreSQL **(FREE)** +# Using PostgreSQL **(FREE ALL)** As many applications depend on PostgreSQL as their database, you eventually need it in order for your tests to run. Below you are guided how to diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md index a7a28116aa4..d86ffdfabd6 100644 --- a/doc/ci/services/redis.md +++ b/doc/ci/services/redis.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Using Redis **(FREE)** +# Using Redis **(FREE ALL)** As many applications depend on Redis as their key-value store, you eventually need it in order for your tests to run. Below you are guided how to diff --git a/doc/ci/ssh_keys/index.md b/doc/ci/ssh_keys/index.md index 15b731f88c8..ad45345fa38 100644 --- a/doc/ci/ssh_keys/index.md +++ b/doc/ci/ssh_keys/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# Using SSH keys with GitLab CI/CD **(FREE)** +# Using SSH keys with GitLab CI/CD **(FREE ALL)** GitLab currently doesn't have built-in support for managing SSH keys in a build environment (where the GitLab Runner runs). diff --git a/doc/ci/test_cases/index.md b/doc/ci/test_cases/index.md index 9667daf7501..0bc9ae7776e 100644 --- a/doc/ci/test_cases/index.md +++ b/doc/ci/test_cases/index.md @@ -6,7 +6,7 @@ description: Test cases in GitLab can help your teams create testing scenarios i type: reference --- -# Test cases **(ULTIMATE)** +# Test cases **(ULTIMATE ALL)** Test cases in GitLab can help your teams create testing scenarios in their existing development platform. diff --git a/doc/ci/testing/accessibility_testing.md b/doc/ci/testing/accessibility_testing.md index f6d0468c876..783e787f8a7 100644 --- a/doc/ci/testing/accessibility_testing.md +++ b/doc/ci/testing/accessibility_testing.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Accessibility testing **(FREE)** +# Accessibility testing **(FREE ALL)** If your application offers a web interface, you can use [GitLab CI/CD](../index.md) to determine the accessibility diff --git a/doc/ci/testing/browser_performance_testing.md b/doc/ci/testing/browser_performance_testing.md index 059cd637f9e..9e81f243e50 100644 --- a/doc/ci/testing/browser_performance_testing.md +++ b/doc/ci/testing/browser_performance_testing.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Browser Performance Testing **(PREMIUM)** +# Browser Performance Testing **(PREMIUM ALL)** If your application offers a web interface and you're using [GitLab CI/CD](../index.md), you can quickly determine the rendering performance diff --git a/doc/ci/testing/code_coverage.md b/doc/ci/testing/code_coverage.md index 8ffd2cfb727..90a07314083 100644 --- a/doc/ci/testing/code_coverage.md +++ b/doc/ci/testing/code_coverage.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Code coverage **(FREE)** +# Code coverage **(FREE ALL)** Use code coverage to provide insights on what source code is being validated by a test suite. Code coverage is one of many test metrics that can determine software performance and quality. @@ -81,7 +81,7 @@ To view a CSV file of the data, select **Download raw data (`.csv`)**.  -### View history of group code coverage **(PREMIUM)** +### View history of group code coverage **(PREMIUM ALL)** To see the all the project's code coverage under a group over time, you can find view [group repository analytics](../../user/group/repositories_analytics/index.md). @@ -92,7 +92,7 @@ To see the all the project's code coverage under a group over time, you can find You can use [pipeline badges](../../user/project/badges.md#test-coverage-report-badges) to indicate the pipeline status and test coverage of your projects. These badges are determined by the latest successful pipeline. -## Coverage check approval rule **(PREMIUM)** +## Coverage check approval rule **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15765) in GitLab 14.0. > - [Made configurable in Project Settings](https://gitlab.com/gitlab-org/gitlab/-/issues/331001) in GitLab 14.1. diff --git a/doc/ci/testing/code_quality.md b/doc/ci/testing/code_quality.md index fcb5a23742a..1d857b8f543 100644 --- a/doc/ci/testing/code_quality.md +++ b/doc/ci/testing/code_quality.md @@ -4,7 +4,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Code Quality **(FREE)** +# Code Quality **(FREE ALL)** > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. @@ -56,7 +56,7 @@ were introduced by the changes made in the merge request.  -### Merge request changes view **(ULTIMATE)** +### Merge request changes view **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in GitLab 13.11, disabled by default behind the `codequality_mr_diff` [feature flag](../../administration/feature_flags.md). > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12. @@ -68,7 +68,7 @@ issues are marked by an indicator beside the gutter. Hover over the marker for d  -### Pipeline details view **(PREMIUM)** +### Pipeline details view **(PREMIUM ALL)** The full list of Code Quality violations generated by a pipeline is shown in the **Code Quality** tab of the pipeline's details page. The pipeline details view displays all Code Quality findings @@ -76,7 +76,7 @@ that were found on the branch it was run on.  -### Project quality view **(ULTIMATE)** +### Project quality view **(ULTIMATE ALL)** The project quality view displays an overview of the code quality findings. The view can be found under **Analyze > CI/CD analytics**, and requires [`project_quality_summary_page`](../../user/feature_flags.md) feature flag to be enabled for this particular project. @@ -136,7 +136,7 @@ To use private runners: ```shell $ gitlab-runner register --executor "docker" \ - --docker-image="docker:stable" \ + --docker-image="docker:latest" \ --url "https://gitlab.com/" \ --description "cq-sans-dind" \ --tag-list "cq-sans-dind" \ @@ -171,7 +171,7 @@ To use private runners: builds_dir = "/tmp/builds" [runners.docker] tls_verify = false - image = "docker:stable" + image = "docker:latest" privileged = false disable_entrypoint_overwrite = false oom_kill_disable = false @@ -454,13 +454,13 @@ You can integrate a custom tool into GitLab to provide Code Quality reports. The Code Quality report artifact JSON file must contain an array of objects with the following properties: -| Name | Description | -| ---------------------- | ----------------------------------------------------------------------------------------- | -| `description` | A description of the code quality violation. | -| `check_name` | A unique name representing the static analysis check that emitted this issue. | -| `fingerprint` | A unique fingerprint to identify the code quality violation. For example, an MD5 hash. | -| `severity` | A severity string (can be `info`, `minor`, `major`, `critical`, or `blocker`). | -| `location.path` | The relative path to the file containing the code quality violation. | +| Name | Description | +|-----------------------------------------------------------|-------------| +| `description` | A description of the code quality violation. | +| `check_name` | A unique name representing the static analysis check that emitted this issue. | +| `fingerprint` | A unique fingerprint to identify the code quality violation. For example, an MD5 hash. | +| `severity` | A severity string (can be `info`, `minor`, `major`, `critical`, or `blocker`). | +| `location.path` | The relative path to the file containing the code quality violation. | | `location.lines.begin` or `location.positions.begin.line` | The line on which the code quality violation occurred. | NOTE: @@ -630,8 +630,9 @@ To work around this problem, set `TIMEOUT_SECONDS` to a higher value in your `.g For example: ```yaml -variables: - TIMEOUT_SECONDS: 3600 +code_quality: + variables: + TIMEOUT_SECONDS: 3600 ``` ### Using Code Quality with Kubernetes CI executor diff --git a/doc/ci/testing/fail_fast_testing.md b/doc/ci/testing/fail_fast_testing.md index 6b1ed4a594d..733c190616c 100644 --- a/doc/ci/testing/fail_fast_testing.md +++ b/doc/ci/testing/fail_fast_testing.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Fail Fast Testing **(PREMIUM)** +# Fail Fast Testing **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198550) in GitLab 13.1. diff --git a/doc/ci/testing/index.md b/doc/ci/testing/index.md index a8fb6d688d7..dadbc3821cc 100644 --- a/doc/ci/testing/index.md +++ b/doc/ci/testing/index.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Test with GitLab CI/CD and generate reports in merge requests **(FREE)** +# Test with GitLab CI/CD and generate reports in merge requests **(FREE ALL)** Use GitLab CI/CD to test the changes included in a feature branch. You can also display reports or link to important information directly from [merge requests](../../user/project/merge_requests/index.md). @@ -18,12 +18,12 @@ display reports or link to important information directly from [merge requests]( | [Code Quality](code_quality.md) | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | | [Display arbitrary job artifacts](../yaml/index.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../jobs/job_artifacts.md) in merge requests. | | [Unit test reports](unit_test_reports.md) | Configure your CI jobs to use Unit test reports, and let GitLab display a report on the merge request so that it's easier and faster to identify the failure without having to check the entire job log. | -| [License Compliance](../../user/compliance/license_compliance/index.md) | Manage the licenses of your dependencies. | +| [License Scanning](../../user/compliance/license_scanning_of_cyclonedx_files/index.md) | Manage the licenses of your dependencies. | | [Metrics Reports](metrics_reports.md) | Display the Metrics Report on the merge request so that it's fast and easier to identify changes to important metrics. | | [Test Coverage visualization](test_coverage_visualization.md) | See test coverage results for merge requests, in the file diff. | | [Fail fast testing](fail_fast_testing.md) | Run a subset of your RSpec test suite, so failed tests stop the pipeline before the full suite of tests run, saving resources. | -## Security Reports **(ULTIMATE)** +## Security Reports **(ULTIMATE ALL)** In addition to the reports listed above, GitLab can do many types of [Security reports](../../user/application_security/index.md), generated by scanning and reporting any vulnerabilities found in your project: diff --git a/doc/ci/testing/load_performance_testing.md b/doc/ci/testing/load_performance_testing.md index dac4dd555b0..549aa10287e 100644 --- a/doc/ci/testing/load_performance_testing.md +++ b/doc/ci/testing/load_performance_testing.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Load Performance Testing **(PREMIUM)** +# Load Performance Testing **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10683) in GitLab 13.2. diff --git a/doc/ci/testing/metrics_reports.md b/doc/ci/testing/metrics_reports.md index 9257ba8990e..0f1eaedfb78 100644 --- a/doc/ci/testing/metrics_reports.md +++ b/doc/ci/testing/metrics_reports.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Metrics Reports **(PREMIUM)** +# Metrics Reports **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9788) in GitLab 11.10. Requires GitLab Runner 11.10 and above. diff --git a/doc/ci/testing/test_coverage_visualization.md b/doc/ci/testing/test_coverage_visualization.md index 669157daa21..62b757a93c3 100644 --- a/doc/ci/testing/test_coverage_visualization.md +++ b/doc/ci/testing/test_coverage_visualization.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Test coverage visualization **(FREE)** +# Test coverage visualization **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) in GitLab 12.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/249811) in GitLab 13.5. @@ -19,7 +19,7 @@ MR is merged. ## How test coverage visualization works -Collecting the coverage information is done via GitLab CI/CD's +Collecting the coverage information is done by using the GitLab CI/CD [artifacts reports feature](../yaml/index.md#artifactsreports). You can specify one or more coverage reports to collect, including wildcard paths. GitLab then takes the coverage information in all the files and combines it @@ -41,8 +41,7 @@ Other coverage analysis frameworks support the format out of the box, for exampl - [Coverage.py](https://coverage.readthedocs.io/en/coverage-5.0.4/cmd.html#xml-reporting) (Python) - [PHPUnit](https://github.com/sebastianbergmann/phpunit-documentation-english/blob/master/src/textui.rst#command-line-options) (PHP) -Once configured, if you create a merge request that triggers a pipeline which collects -coverage reports, the coverage is shown in the diff view. This includes reports +After configuration, if your merge request triggers a pipeline that collects coverage reports, the coverage information is displayed in the diff view. This includes reports from any job in any stage in the pipeline. The coverage displays for each line: - `covered` (green): lines which have been checked at least once by tests @@ -431,6 +430,7 @@ the coverage report itself and verify that: to match the files in your repository. - The pipeline has completed. If the pipeline is [blocked on a manual job](../jobs/job_control.md#types-of-manual-jobs), the pipeline is not considered complete. +- The coverage report file does not exceed the [limits](#limits). Report artifacts are not downloadable by default. If you want the report to be downloadable from the job details page, add your coverage report to the artifact `paths`: diff --git a/doc/ci/testing/unit_test_report_examples.md b/doc/ci/testing/unit_test_report_examples.md index 8527d0b712d..fb11467cd7d 100644 --- a/doc/ci/testing/unit_test_report_examples.md +++ b/doc/ci/testing/unit_test_report_examples.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Unit test report examples **(FREE)** +# Unit test report examples **(FREE ALL)** [Unit test reports](unit_test_reports.md) can be generated for many languages and packages. Use these examples as guidelines for configuring your pipeline to generate unit test reports diff --git a/doc/ci/testing/unit_test_reports.md b/doc/ci/testing/unit_test_reports.md index 88a5d90d30e..a8b4c36db7f 100644 --- a/doc/ci/testing/unit_test_reports.md +++ b/doc/ci/testing/unit_test_reports.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Unit test reports **(FREE)** +# Unit test reports **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45318) in GitLab 11.2. Requires GitLab Runner 11.2 and above. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39737) from JUnit test reports to Unit test reports in GitLab 13.4. diff --git a/doc/ci/triggers/index.md b/doc/ci/triggers/index.md index a47eaaf0381..506f6fb2106 100644 --- a/doc/ci/triggers/index.md +++ b/doc/ci/triggers/index.md @@ -5,19 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# Trigger pipelines by using the API **(FREE)** +# Trigger pipelines by using the API **(FREE ALL)** To trigger a pipeline for a specific branch or tag, you can use an API call to the [pipeline triggers API endpoint](../../api/pipeline_triggers.md). When authenticating with the API, you can use: -- A [trigger token](#create-a-trigger-token) to trigger a branch or tag pipeline. +- A [pipeline trigger token](#create-a-pipeline-trigger-token) to trigger a branch or tag pipeline. - A [CI/CD job token](../jobs/ci_job_token.md) to [trigger a multi-project pipeline](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api). -## Create a trigger token +## Create a pipeline trigger token -You can trigger a pipeline for a branch or tag by generating a trigger token and using it +You can trigger a pipeline for a branch or tag by generating a pipeline trigger token and using it to authenticate an API call. The token impersonates a user's project access and permissions. Prerequisite: @@ -28,8 +28,9 @@ To create a trigger token: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > CI/CD**. -1. Expand **Pipeline triggers**. -1. Enter a description and select **Add trigger**. +1. Expand **Pipeline trigger tokens**. +1. Select **Add new token** +1. Enter a description and select **Create pipeline trigger token**. - You can view and copy the full token for all triggers you have created. - You can only see the first 4 characters for tokens created by other project members. @@ -41,12 +42,12 @@ to improve the security of trigger tokens. ## Trigger a pipeline -After you [create a trigger token](#create-a-trigger-token), you can use it to trigger +After you [create a pipeline trigger token](#create-a-pipeline-trigger-token), you can use it to trigger pipelines with a tool that can access the API, or a webhook. ### Use cURL -You can use cURL to trigger pipelines with the [pipeline triggers API endpoint](../../api/pipeline_triggers.md). +You can use cURL to trigger pipelines with the [pipeline trigger token API endpoint](../../api/pipeline_triggers.md). For example: - Use a multiline cURL command: @@ -62,7 +63,7 @@ For example: ```shell curl --request POST \ - "https://gitlab.example.com/api/v4/projects/<project_id>/trigger/pipeline?token=<token>&ref=<ref_name>" + "https://gitlab.example.com/api/v4/projects/<project_id>/trigger/pipeline?token=<token>&ref=<ref_name>" ``` In each example, replace: @@ -75,7 +76,7 @@ In each example, replace: ### Use a CI/CD job -You can use a CI/CD job with a triggers token to trigger pipelines when another pipeline +You can use a CI/CD job with a pipeline triggers token to trigger pipelines when another pipeline runs. For example, to trigger a pipeline on the `main` branch of `project-B` when a tag @@ -116,9 +117,9 @@ Replace: - `<ref_name>` with a branch or tag name, like `main`. This value takes precedence over the `ref_name` in the webhook payload. The payload's `ref` is the branch that fired the trigger in the source repository. You must URL-encode the `ref_name` if it contains slashes. -- `<token>` with your trigger token. +- `<token>` with your pipeline trigger token. -#### Use a webhook payload +#### Access webhook payload > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31197) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321027) in GitLab 13.11. @@ -138,10 +139,10 @@ The parameter is of the form `variables[key]=value`, for example: ```shell curl --request POST \ - --form token=TOKEN \ - --form ref=main \ - --form "variables[UPLOAD_TO_S3]=true" \ - "https://gitlab.example.com/api/v4/projects/123456/trigger/pipeline" + --form token=TOKEN \ + --form ref=main \ + --form variables[UPLOAD_TO_S3]="true" \ + "https://gitlab.example.com/api/v4/projects/123456/trigger/pipeline" ``` CI/CD variables in triggered pipelines display on each job's page, but only @@ -149,9 +150,9 @@ users with the Owner and Maintainer role can view the values.  -## Revoke a trigger token +## Revoke a pipeline trigger token -To revoke a trigger token: +To revoke a pipeline trigger token: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > CI/CD**. @@ -162,23 +163,24 @@ A revoked trigger token cannot be added back. ## Configure CI/CD jobs to run in triggered pipelines -To [configure when to run jobs](../jobs/job_control.md) in triggered pipelines: +To [configure when to run jobs](../jobs/job_control.md) in triggered pipelines, you can: - Use [`rules`](../yaml/index.md#rules) with the `$CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md). -- Use [`only`/`except`](../yaml/index.md#onlyrefs--exceptrefs) keywords. +- Use [`only`/`except`](../yaml/index.md#onlyrefs--exceptrefs) keywords, though `rules` + is the preferred keyword. | `$CI_PIPELINE_SOURCE` value | `only`/`except` keywords | Trigger method | |-----------------------------|--------------------------|---------------------| -| `trigger` | `triggers` | In pipelines triggered with the [pipeline triggers API](../../api/pipeline_triggers.md) by using a [trigger token](#create-a-trigger-token). | +| `trigger` | `triggers` | In pipelines triggered with the [pipeline triggers API](../../api/pipeline_triggers.md) by using a [trigger token](#create-a-pipeline-trigger-token). | | `pipeline` | `pipelines` | In [multi-project pipelines](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api) triggered with the [pipeline triggers API](../../api/pipeline_triggers.md) by using the [`$CI_JOB_TOKEN`](../jobs/ci_job_token.md), or by using the [`trigger`](../yaml/index.md#trigger) keyword in the CI/CD configuration file. | Additionally, the `$CI_PIPELINE_TRIGGERED` predefined CI/CD variable is set to `true` -in pipelines triggered with a trigger token. +in pipelines triggered with a pipeline trigger token. -## See which trigger token was used +## See which pipeline trigger token was used -You can see which trigger caused a job to run by visiting the single job page. -A part of the trigger's token displays on the right of the page, under the job details: +You can see which pipeline trigger token caused a job to run by visiting the single job page. +A part of the trigger token displays on the right of the page, under the job details:  @@ -196,7 +198,7 @@ To avoid trigger loops, do not use [pipeline events](../../user/project/integrat A response of `{"message":"404 Not Found"}` when triggering a pipeline might be caused by using a [personal access token](../../user/profile/personal_access_tokens.md) -instead of a trigger token. [Create a new trigger token](#create-a-trigger-token) +instead of a pipeline trigger token. [Create a new trigger token](#create-a-pipeline-trigger-token) and use it instead of the personal access token. ### `The requested URL returned error: 400` when triggering a pipeline diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md index 623589e2cbc..3d5bcc64889 100644 --- a/doc/ci/troubleshooting.md +++ b/doc/ci/troubleshooting.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Troubleshooting CI/CD **(FREE)** +# Troubleshooting CI/CD **(FREE ALL)** GitLab provides several tools to help make troubleshooting your pipelines easier. @@ -283,6 +283,36 @@ If the merge train pipeline was canceled before the merge request was merged, wi - Add it to the train again. +### Merge request rules widget shows a scan result policy is invalid or duplicated **(ULTIMATE SELF)** + +On GitLab self-managed 15.0 and later, the most likely cause is that the project was exported from a +group and imported into another, and had scan result policy rules. These rules are stored in a +separate project to the one that was exported. As a result, the project contains policy rules that +reference entities that don't exist in the imported project's group. The result is policy rules that +are invalid, duplicated, or both. + +To remove all invalid scan result policy rules from a GitLab instance, an administrator can run +the following script in the [Rails console](../administration/operations/rails_console.md). + +```ruby +Project.joins(:approval_rules).where(approval_rules: { report_type: %i[scan_finding license_scanning] }).where.not(approval_rules: { security_orchestration_policy_configuration_id: nil }).find_in_batches.flat_map do |batch| + batch.map do |project| + # Get projects and their configuration_ids for applicable project rules + [project, project.approval_rules.where(report_type: %i[scan_finding license_scanning]).pluck(:security_orchestration_policy_configuration_id).uniq] + end.uniq.map do |project, configuration_ids| # We take only unique combinations of project + configuration_ids + # If we find more configurations than what is available for the project, we take records with the extra configurations + [project, configuration_ids - project.all_security_orchestration_policy_configurations.pluck(:id)] + end.select { |_project, configuration_ids| configuration_ids.any? } +end.each do |project, configuration_ids| + # For each found pair project + ghost configuration, we remove these rules for a given project + Security::OrchestrationPolicyConfiguration.where(id: configuration_ids).each do |configuration| + configuration.delete_scan_finding_rules_for_project(project.id) + end + # Ensure we sync any potential rules from new group's policy + Security::ScanResultPolicies::SyncProjectWorker.perform_async(project.id) +end +``` + ### Project `group/project` not found or access denied This message is shown if configuration is added with [`include`](yaml/index.md#include) and one of the following: @@ -330,6 +360,8 @@ start a new pipeline to use the new configuration. ### Unable to pull image from another project +> **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3. + When a runner tries to pull an image from a private project, the job could fail with the following error: ```shell @@ -338,7 +370,7 @@ WARNING: Failed to pull image with policy "always": Error response from daemon: This error can happen if the following are both true: -- The **Allow access to this project with a CI_JOB_TOKEN** option is enabled in the private project +- The **Limit access _to_ this project** option is enabled in the private project hosting the image. - The job attempting to fetch the image is running for a project that is not listed in the private project's allowlist. diff --git a/doc/ci/variables/index.md b/doc/ci/variables/index.md index bd066797ada..6280c9080ab 100644 --- a/doc/ci/variables/index.md +++ b/doc/ci/variables/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab CI/CD variables **(FREE)** +# GitLab CI/CD variables **(FREE ALL)** CI/CD variables are a type of environment variable. You can use them to: diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 73aaafe46c0..6acb254e76f 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Predefined variables reference **(FREE)** +# Predefined variables reference **(FREE ALL)** Predefined [CI/CD variables](index.md) are available in every GitLab CI/CD pipeline. @@ -59,12 +59,12 @@ as it can cause the pipeline to behave unexpectedly. | `CI_DEPLOY_USER` | 10.8 | all | The authentication username of the [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token), if the project has one. | | `CI_DISPOSABLE_ENVIRONMENT` | all | 10.1 | Only available if the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). `true` when available. | | `CI_ENVIRONMENT_NAME` | 8.15 | all | The name of the environment for this job. Available if [`environment:name`](../yaml/index.md#environmentname) is set. | -| `CI_ENVIRONMENT_SLUG` | 8.15 | all | The simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, and so on. Available if [`environment:name`](../yaml/index.md#environmentname) is set. The slug is [truncated to 24 characters](https://gitlab.com/gitlab-org/gitlab/-/issues/20941). | +| `CI_ENVIRONMENT_SLUG` | 8.15 | all | The simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, and so on. Available if [`environment:name`](../yaml/index.md#environmentname) is set. The slug is [truncated to 24 characters](https://gitlab.com/gitlab-org/gitlab/-/issues/20941). A random suffix is automatically added to [uppercase environment names](https://gitlab.com/gitlab-org/gitlab/-/issues/415526). | | `CI_ENVIRONMENT_URL` | 9.3 | all | The URL of the environment for this job. Available if [`environment:url`](../yaml/index.md#environmenturl) is set. | | `CI_ENVIRONMENT_ACTION` | 13.11 | all | The action annotation specified for this job's environment. Available if [`environment:action`](../yaml/index.md#environmentaction) is set. Can be `start`, `prepare`, or `stop`. | | `CI_ENVIRONMENT_TIER` | 14.0 | all | The [deployment tier of the environment](../environments/index.md#deployment-tier-of-environments) for this job. | | `CI_RELEASE_DESCRIPTION` | 15.5 | all | The description of the release. Available only on pipelines for tags. Description length is limited to first 1024 characters.| -| `CI_GITLAB_FIPS_MODE` | 14.10 | all | The configuration setting for whether FIPS mode is enabled in the GitLab instance. | +| `CI_GITLAB_FIPS_MODE` | 14.10 | all | Only available if [FIPS mode](../../development/fips_compliance.md) is enabled in the GitLab instance. `true` when available. | | `CI_HAS_OPEN_REQUIREMENTS` | 13.1 | all | Only available if the pipeline's project has an open [requirement](../../user/project/requirements/index.md). `true` when available. | | `CI_JOB_ID` | 9.0 | all | The internal ID of the job, unique across all jobs in the GitLab instance. | | `CI_JOB_IMAGE` | 12.9 | 12.9 | The name of the Docker image running the job. | @@ -76,7 +76,7 @@ as it can cause the pipeline to behave unexpectedly. | `CI_JOB_NAME_SLUG` | 15.4 | all | `CI_JOB_NAME_SLUG` in lowercase, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in paths. | | `CI_JOB_STAGE` | 9.0 | 0.5 | The name of the job's stage. | | `CI_JOB_STATUS` | all | 13.5 | The status of the job as each runner stage is executed. Use with [`after_script`](../yaml/index.md#after_script). Can be `success`, `failed`, or `canceled`. | -| `CI_JOB_TIMEOUT` | 15.7 | 15.7 | The job timeout value. | +| `CI_JOB_TIMEOUT` | 15.7 | 15.7 | The job timeout, in seconds. | | `CI_JOB_TOKEN` | 9.0 | 1.2 | A token to authenticate with [certain API endpoints](../jobs/ci_job_token.md). The token is valid as long as the job is running. | | `CI_JOB_URL` | 11.1 | 0.5 | The job details URL. | | `CI_JOB_STARTED_AT` | 13.10 | all | The UTC datetime when a job started, in [ISO 8601](https://www.rfc-editor.org/rfc/rfc3339#appendix-A) format. | @@ -92,6 +92,7 @@ as it can cause the pipeline to behave unexpectedly. | `CI_PIPELINE_TRIGGERED` | all | all | `true` if the job was [triggered](../triggers/index.md). | | `CI_PIPELINE_URL` | 11.1 | 0.5 | The URL for the pipeline details. | | `CI_PIPELINE_CREATED_AT` | 13.10 | all | The UTC datetime when the pipeline was created, in [ISO 8601](https://www.rfc-editor.org/rfc/rfc3339#appendix-A) format. | +| `CI_PIPELINE_NAME` | 16.3 | all | The pipeline name defined in [`workflow:name`](../yaml/index.md#workflowname) | | `CI_PROJECT_DIR` | all | all | The full path the repository is cloned to, and where the job runs from. If the GitLab Runner `builds_dir` parameter is set, this variable is set relative to the value of `builds_dir`. For more information, see the [Advanced GitLab Runner configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | | `CI_PROJECT_ID` | all | all | The ID of the current project. This ID is unique across all projects on the GitLab instance. | | `CI_PROJECT_NAME` | 8.10 | 0.5 | The name of the directory for the project. For example if the project URL is `gitlab.example.com/group-name/project-1`, `CI_PROJECT_NAME` is `project-1`. | @@ -143,7 +144,7 @@ as it can cause the pipeline to behave unexpectedly. | `GITLAB_USER_LOGIN` | 10.0 | all | The username of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the username of the user who started the job. | | `GITLAB_USER_NAME` | 10.0 | all | The name of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the name of the user who started the job. | | `KUBECONFIG` | 14.2 | all | The path to the `kubeconfig` file with contexts for every shared agent connection. Only available when a [GitLab agent is authorized to access the project](../../user/clusters/agent/ci_cd_workflow.md#authorize-the-agent). | -| `TRIGGER_PAYLOAD` | 13.9 | all | The webhook payload. Only available when a pipeline is [triggered with a webhook](../triggers/index.md#use-a-webhook-payload). | +| `TRIGGER_PAYLOAD` | 13.9 | all | The webhook payload. Only available when a pipeline is [triggered with a webhook](../triggers/index.md#access-webhook-payload). | ## Predefined variables for merge request pipelines diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 14dfc5dd551..52edeb67f0e 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Where variables can be used **(FREE)** +# Where variables can be used **(FREE ALL)** As it's described in the [CI/CD variables](index.md) documentation, you can define many different variables. Some of them can be used for all GitLab CI/CD diff --git a/doc/ci/yaml/artifacts_reports.md b/doc/ci/yaml/artifacts_reports.md index 37cb7efdf94..fa7e941ffe5 100644 --- a/doc/ci/yaml/artifacts_reports.md +++ b/doc/ci/yaml/artifacts_reports.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# GitLab CI/CD artifacts reports types **(FREE)** +# GitLab CI/CD artifacts reports types **(FREE ALL)** Use [`artifacts:reports`](index.md#artifactsreports) to: @@ -40,7 +40,7 @@ GitLab can display the results of one or more reports in the merge request For more information, see [Accessibility testing](../testing/accessibility_testing.md). -## `artifacts:reports:api_fuzzing` **(ULTIMATE)** +## `artifacts:reports:api_fuzzing` **(ULTIMATE ALL)** > - Introduced in GitLab 13.4. > - Requires GitLab Runner 13.4 or later. @@ -55,7 +55,7 @@ GitLab can display the results of one or more reports in: - The pipeline [**Security** tab](../../user/application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline). - The [security dashboard](../../user/application_security/api_fuzzing/index.md#security-dashboard). -## `artifacts:reports:browser_performance` **(PREMIUM)** +## `artifacts:reports:browser_performance` **(PREMIUM ALL)** > [Name changed](https://gitlab.com/gitlab-org/gitlab/-/issues/225914) from `artifacts:reports:performance` in GitLab 14.0. @@ -106,7 +106,7 @@ GitLab can display the results of one or more reports in: - The merge request [diff annotations](../testing/code_quality.md#merge-request-changes-view). - The [full report](../testing/metrics_reports.md). -## `artifacts:reports:container_scanning` **(ULTIMATE)** +## `artifacts:reports:container_scanning` **(ULTIMATE ALL)** The `container_scanning` report collects [Container Scanning vulnerabilities](../../user/application_security/container_scanning/index.md). The collected Container Scanning report uploads to GitLab as an artifact. @@ -118,7 +118,7 @@ GitLab can display the results of one or more reports in: - The [security dashboard](../../user/application_security/security_dashboard/index.md). - The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). -## `artifacts:reports:coverage_fuzzing` **(ULTIMATE)** +## `artifacts:reports:coverage_fuzzing` **(ULTIMATE ALL)** > - Introduced in GitLab 13.4. > - Requires GitLab Runner 13.4 or later. @@ -157,7 +157,7 @@ artifacts: - gl-sbom-bundler-gem.cdx.json ``` -## `artifacts:reports:dast` **(ULTIMATE)** +## `artifacts:reports:dast` **(ULTIMATE ALL)** The `dast` report collects [DAST vulnerabilities](../../user/application_security/dast/index.md). The collected DAST report uploads to GitLab as an artifact. @@ -169,7 +169,7 @@ GitLab can display the results of one or more reports in: - The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). - The [security dashboard](../../user/application_security/security_dashboard/index.md). -## `artifacts:reports:dependency_scanning` **(ULTIMATE)** +## `artifacts:reports:dependency_scanning` **(ULTIMATE ALL)** The `dependency_scanning` report collects [Dependency Scanning vulnerabilities](../../user/application_security/dependency_scanning/index.md). The collected Dependency Scanning report uploads to GitLab as an artifact. @@ -245,19 +245,20 @@ concatenate them into a single file. Use either: - A combination of both (`junit: [rspec.xml, test-results/TEST-*.xml]`). - Directories are not supported(`junit: test-results`, `junit: test-results/**`). -## `artifacts:reports:license_scanning` **(ULTIMATE)** +<!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> -> Introduced in GitLab 12.8. +## `artifacts:reports:license_scanning` **(ULTIMATE ALL)** -The License Compliance report collects [Licenses](../../user/compliance/license_compliance/index.md). The License -Compliance report uploads to GitLab as an artifact. +> Introduced in GitLab 12.8. -GitLab can display the results of one or more reports in: +The license scanning report was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) +in GitLab 15.9 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/421363) in GitLab 16.3. +You should instead migrate to use [License approval policies](../../user/compliance/license_approval_policies.md) and +the [new method of license scanning](../../user/compliance/license_scanning_of_cyclonedx_files/index.md). -- The merge request [license compliance widget](../../user/compliance/license_compliance/index.md). -- The [license list](../../user/compliance/license_list.md). +<!--- end_remove --> -## `artifacts:reports:load_performance` **(PREMIUM)** +## `artifacts:reports:load_performance` **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35260) in GitLab 13.2. > - Requires GitLab Runner 11.5 and above. @@ -270,7 +271,7 @@ GitLab can display the results of only one report in the merge request GitLab cannot display the combined results of multiple `load_performance` reports. -## `artifacts:reports:metrics` **(PREMIUM)** +## `artifacts:reports:metrics` **(PREMIUM ALL)** The `metrics` report collects [Metrics](../testing/metrics_reports.md). The collected Metrics report uploads to GitLab as an artifact. @@ -278,7 +279,7 @@ artifact. GitLab can display the results of one or more reports in the merge request [metrics reports widget](../testing/metrics_reports.md#metrics-reports). -## `artifacts:reports:requirements` **(ULTIMATE)** +## `artifacts:reports:requirements` **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in GitLab 13.1. @@ -297,7 +298,7 @@ report uploads to GitLab as an artifact. GitLab can display the results of one or more reports in: -- The merge request [SAST widget](../../user/application_security/sast/index.md#static-application-security-testing-sast). +- The merge request [SAST widget](../../user/application_security/sast/index.md). - The [security dashboard](../../user/application_security/security_dashboard/index.md). ## `artifacts:reports:secret_detection` diff --git a/doc/ci/yaml/gitlab_ci_yaml.md b/doc/ci/yaml/gitlab_ci_yaml.md index 7b4834b3719..920abf50546 100644 --- a/doc/ci/yaml/gitlab_ci_yaml.md +++ b/doc/ci/yaml/gitlab_ci_yaml.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# The `.gitlab-ci.yml` file **(FREE)** +# The `.gitlab-ci.yml` file **(FREE ALL)** To use GitLab CI/CD, you need: diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index 3b6419dbff2..79eb42fd781 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Use CI/CD configuration from other files **(FREE)** +# Use CI/CD configuration from other files **(FREE ALL)** You can use [`include`](index.md#include) to include external YAML files in your CI/CD jobs. @@ -589,6 +589,60 @@ In this example: - `user` is optional. If not defined, the value is `test-user`. - `flags` is optional. If not defined, it has no value. +### Specify functions to manipulate input values + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409462) in GitLab 16.3. + +You can specify predefined functions in the interpolation block to manipulate the input value. +The format supported is the following: + +```yaml +$[[ input.input-id | <function1> | <function2> | ... <functionN> ]] +``` + +Details: + +- Only [predefined interpolation functions](#predefined-interpolation-functions) are permitted. +- A maximum of 3 functions may be specified in a single interpolation block. +- The functions are executed in the sequence they are specified. + +```yaml +spec: + inputs: + test: + default: '0123456789' +--- + +test-job: + script: echo $[[ inputs.test | truncate(1,3) ]] +``` + +In this example: + +- The function [`truncate`](#truncate) applies to the value of `inputs.test`. +- Assuming the value of `inputs.test` is `0123456789`, then the output of `script` would be `echo 123`. + +### Predefined interpolation functions + +#### Truncate + +Use `truncate` to shorten the interpolated value. For example: + +- `truncate(<offset>,<length>)` + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `offset` | Integer | Number of characters to offset by. | +| `length` | Integer | Number of characters to return after the offset. | + +Example: + +```yaml +$[[ inputs.test | truncate(3,5) ]] +``` + +Assuming the value of `inputs.test` is `0123456789`, then the output would be `34567`. + ### Set input parameter values with `include:inputs` > `include:with` [renamed to `include:inputs`](https://gitlab.com/gitlab-org/gitlab/-/issues/406780) in GitLab 16.0. diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index 9a060c35721..c4f7e6d6e01 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# `.gitlab-ci.yml` keyword reference **(FREE)** +# `.gitlab-ci.yml` keyword reference **(FREE ALL)** This document lists the configuration options for your GitLab `.gitlab-ci.yml` file. @@ -179,7 +179,7 @@ The time limit to resolve all files is 30 seconds. #### `include:local` -Use `include:local` to include a file that is in the same repository as the configuration file containing the `include` keyword. +Use `include:local` to include a file that is in the same repository and branch as the configuration file containing the `include` keyword. Use `include:local` instead of symbolic links. **Keyword type**: Global keyword. @@ -291,8 +291,8 @@ include: **Additional details**: -- All [nested includes](includes.md#use-nested-includes) execute without context as a public user, - so you can only include public projects or templates. +- All [nested includes](includes.md#use-nested-includes) are executed without context as a public user, + so you can only include public projects or templates. No variables are available in the `include` section of nested includes. - Be careful when including a remote CI/CD configuration file. No pipelines or notifications trigger when external CI/CD configuration files change. From a security perspective, this is similar to pulling a third-party dependency. @@ -330,8 +330,8 @@ include: **Additional details**: -- All [nested includes](includes.md#use-nested-includes) are executed only with the permission of the user, - so it's possible to use `project`, `remote`, or `template` includes. +- All [nested includes](includes.md#use-nested-includes) are executed without context as a public user, + so you can only include public projects or templates. No variables are available in the `include` section of nested includes. ### `stages` @@ -1554,7 +1554,7 @@ In this example: is not recorded or displayed. Check [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/280818) for more details. -### `dast_configuration` **(ULTIMATE)** +### `dast_configuration` **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5981) in GitLab 14.1. @@ -2389,6 +2389,8 @@ This example creates four paths of execution: it depends on all jobs created in parallel, not just one job. It also downloads artifacts from all the parallel jobs by default. If the artifacts have the same name, they overwrite each other and only the last one downloaded is saved. + - To have `needs` refer to a subset of parallelized jobs (and not all of the parallelized jobs), + use the [`needs:parallel:matrix`](#needsparallelmatrix) keyword. - In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) you can refer to jobs in the same stage as the job you are configuring. This feature is enabled on GitLab.com and ready for production use. On self-managed [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) @@ -2454,7 +2456,7 @@ In this example: - In GitLab 12.6 and later, you can't combine the [`dependencies`](#dependencies) keyword with `needs`. -#### `needs:project` **(PREMIUM)** +#### `needs:project` **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.7. @@ -2679,6 +2681,61 @@ upstream_status: - If you add the `job` keyword to `needs:pipeline`, the job no longer mirrors the pipeline status. The behavior changes to [`needs:pipeline:job`](#needspipelinejob). +#### `needs:parallel:matrix` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254821) in GitLab 16.3. + +Jobs can use [`parallel:matrix`](#parallelmatrix) to run a job multiple times in parallel in a single pipeline, +but with different variable values for each instance of the job. + +Use `needs:parallel:matrix` to execute jobs out-of-order depending on parallelized jobs. + +**Keyword type**: Job keyword. You can use it only as part of a job. Must be used with `needs:job`. + +**Possible inputs**: An array of hashes of variables: + +- The variables and values must be selected from the variables and values defined in the `parallel:matrix` job. + +**Example of `needs:parallel:matrix`**: + +```yaml +linux:build: + stage: build + script: echo "Building linux..." + parallel: + matrix: + - PROVIDER: aws + STACK: + - monitoring + - app1 + - app2 + +linux:rspec: + stage: test + needs: + - job: linux:build + parallel: + matrix: + - PROVIDER: aws + - STACK: app1 + script: echo "Running rspec on linux..." +``` + +The above example generates the following jobs: + +```plaintext +linux:build: [aws, monitoring] +linux:build: [aws, app1] +linux:build: [aws, app2] +linux:rspec +``` + +The `linux:rspec` job runs as soon as the `linux:build: [aws, app1]` job finishes. + +**Related topics**: + +- [Specify a parallelized job using needs with multiple parallelized jobs](../jobs/job_control.md#specify-a-parallelized-job-using-needs-with-multiple-parallelized-jobs). + ### `only` / `except` NOTE: @@ -3858,7 +3915,7 @@ job2: - [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections) to simplify job log output. -### `secrets` **(PREMIUM)** +### `secrets` **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33014) in GitLab 13.4. @@ -3868,8 +3925,6 @@ Use `secrets` to specify [CI/CD secrets](../secrets/index.md) to: - Make available in the job as [CI/CD variables](../variables/index.md) ([`file` type](../variables/index.md#use-file-type-cicd-variables) by default). -This keyword must be used with `secrets:vault`. - #### `secrets:vault` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in GitLab 13.4 and GitLab Runner 13.4. @@ -3920,6 +3975,34 @@ job: vault: production/db/password@ops # Translates to secret: `ops/data/production/db`, field: `password` ``` +#### `secrets:azure_key_vault` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271271) in GitLab 16.3 and GitLab Runner 16.3. + +Use `secrets:azure_key_vault` to specify secrets provided by a [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault/). + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: + +- `name`: Name of the secret. +- `version`: Version of the secret. + +**Example of `secrets:azure_key_vault`**: + +```yaml +job: + secrets: + DATABASE_PASSWORD: + azure_key_vault: + name: 'test' + version: 'test' +``` + +**Related topics**: + +- [Use Azure Key Vault secrets in GitLab CI/CD](../secrets/azure_key_vault.md). + #### `secrets:file` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250695) in GitLab 14.1 and GitLab Runner 14.1. diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md index 1c31191c2f4..71b9e9fbe0b 100644 --- a/doc/ci/yaml/script.md +++ b/doc/ci/yaml/script.md @@ -4,7 +4,7 @@ group: Pipeline Authoring 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 --- -# Format scripts and job logs **(FREE)** +# Format scripts and job logs **(FREE ALL)** You can use special syntax in [`script`](index.md#script) sections to: diff --git a/doc/ci/yaml/signing_examples.md b/doc/ci/yaml/signing_examples.md index 5609bd2374e..72e007a749f 100644 --- a/doc/ci/yaml/signing_examples.md +++ b/doc/ci/yaml/signing_examples.md @@ -21,26 +21,38 @@ For details on the mapping between GitLab OIDC claims and Fulcio certificate ext - You must be using GitLab.com. - Your project's CI/CD configuration must be located in the project. -- You must use a version of Cosign that is `>= 2.0.1`. -## Container images +## Sign or verify container images and build artifacts by using Cosign + +You can use Cosign to sign and verify container images and build artifacts. -### Sign a container image with Cosign +**Requirements:** -GitLab [ID tokens](../secrets/id_token_authentication.md) can be used by Cosign for -[keyless signing](https://docs.sigstore.dev/cosign/overview/#example-working-with-containers). The token must have `sigstore` set as the -[`aud`](../secrets/id_token_authentication.md#token-payload) claim. The token can be used by Cosign automatically when -it is set in the `SIGSTORE_ID_TOKEN` environment variable. +- You must use a version of Cosign that is `>= 2.0.1`. **Best practices**: -- Build and sign a container image in the same job to prevent the image from being tampered with before it is - signed. +- Build and sign an image/artifact in the same job to prevent it from being tampered with before it is signed. +- When signing container images, sign the digest (which is immutable) instead of the tag. + +GitLab [ID tokens](../secrets/id_token_authentication.md#id-tokens) can be used by Cosign for +[keyless signing](https://docs.sigstore.dev/cosign/overview/). The token must have +`sigstore` set as the [`aud`](../secrets/id_token_authentication.md#token-payload) claim. The token can be used by Cosign automatically when it is set in the +`SIGSTORE_ID_TOKEN` environment variable. + +To learn more about how to install Cosign, see [Cosign Installation documentation](https://docs.sigstore.dev/cosign/installation/). -See [Cosign documentation](https://docs.sigstore.dev/cosign/signing_with_containers/) to learn more about signing. +### Signing + +#### Container images + +The example below demonstrates how to sign a container image in GitLab CI. The signature is automatically stored in the +same container repository as the image. + +To learn more about signing containers, see [Cosign Signing Containers documentation](https://docs.sigstore.dev/cosign/signing_with_containers/). ```yaml -build_and_sign: +build_and_sign_image: stage: build image: docker:latest services: @@ -60,10 +72,52 @@ build_and_sign: - cosign sign $IMAGE_DIGEST ``` -### Verify a container image with Cosign +#### Build artifacts + +The example below demonstrates how to sign a build artifact in GitLab CI. You should save the `cosign.bundle` file +produced by `cosign sign-blob`, which is used for signature verification. + +To learn more about signing artifacts, see [Cosign Signing Blobs documentation](https://docs.sigstore.dev/cosign/signing_with_blobs/#keyless-signing-of-blobs-and-files). + +```yaml +build_and_sign_artifact: + stage: build + image: alpine:latest + variables: + COSIGN_YES: "true" + id_tokens: + SIGSTORE_ID_TOKEN: + aud: sigstore + before_script: + - apk add --update cosign + script: + - echo "This is a build artifact" > artifact.txt + - cosign sign-blob artifact.txt --bundle cosign.bundle + artifacts: + paths: + - artifact.txt + - cosign.bundle +``` + +### Verification + +**Command-line arguments** + +| Name | Value | +|-----------------------------|-------| +| `--certificate-identity` | The SAN of the signing certificate issued by Fulcio. Can be constructed with the following information from the project where the image/artifact was signed: GitLab instance URL + project path + `//` + CI config path + `@` + ref path. | +| `--certificate-oidc-issuer` | The GitLab instance URL where the image/artifact was signed. For example, `https://gitlab.com`. | +| `--bundle` | The `bundle` file produced by `cosign sign-blob`. Only used for verifying build artifacts. | + +To learn more about verifying signed images/artifacts, see [Cosign Verifying documentation](https://docs.sigstore.dev/cosign/verify/#keyless-verification-using-openid-connect). + +#### Container images + +The example below demonstrates how to verify a signed container image in GitLab CI. The command-line arguments are +described [above](#verification). ```yaml -verify: +verify_image: image: alpine:3.18 stage: verify before_script: @@ -73,6 +127,22 @@ verify: - cosign verify "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" --certificate-identity "https://gitlab.com/my-group/my-project//path/to/.gitlab-ci.yml@refs/heads/main" --certificate-oidc-issuer "https://gitlab.com" ``` +#### Build artifacts + +The example below demonstrates how to verify a signed build artifact in GitLab CI. Verifying an artifact requires both +the artifact itself and the `cosign.bundle` file produced by `cosign sign-blob`. The command-line arguments are +described [above](#verification). + +```yaml +verify_artifact: + stage: verify + image: alpine:latest + before_script: + - apk add --update cosign + script: + - cosign verify-blob artifact.txt --bundle cosign.bundle --certificate-identity "https://gitlab.com/my-group/my-project//path/to/.gitlab-ci.yml@refs/heads/main" --certificate-oidc-issuer "https://gitlab.com" +``` + ## Use Sigstore and npm to generate keyless provenance You can use Sigstore and npm, together with GitLab CI/CD, to digitally sign build artifacts without the overhead of key management. @@ -253,58 +323,3 @@ predicate: digest: sha1: 6e02e901e936bfac3d4691984dff8c505410cbc3 ``` - -## Build artifacts - -You can use Cosign to both sign build artifacts and verify artifacts that were signed with Cosign. - -### Sign a build artifact with Cosign - -GitLab [ID tokens](../secrets/id_token_authentication.md) can be used by Cosign for keyless signing of build artifacts. -The token must have `sigstore` set as the [`aud`](../secrets/id_token_authentication.md#token-payload) claim. The token can be used by Cosign automatically when -it is set in the `SIGSTORE_ID_TOKEN` environment variable. - -**Best practices**: - -- Build and sign an artifact in the same job to prevent the artifact from being tampered with before it is - signed. - -To learn more about signing artifacts, see [Cosign documentation](https://docs.sigstore.dev/cosign/signing_with_blobs/#keyless-signing-of-blobs-and-files). - -```yaml -sign_artifact: - stage: build - image: alpine:latest - variables: - COSIGN_YES: "true" - id_tokens: - SIGSTORE_ID_TOKEN: - aud: sigstore - before_script: - - apk add --update cosign - script: - - echo "This is a build artifact" > artifact.txt - - cosign sign-blob artifact.txt --bundle cosign.bundle - artifacts: - paths: - - artifact.txt - - cosign.bundle -``` - -### Verify a build artifact with Cosign - -Verifying an artifact requires both the artifact itself and the `cosign.bundle` file produced by `cosign sign-blob`. -The `--certificate-identity` option should reference the project and branch where the artifact was signed. The -`--certificate-oidc-issuer` option should reference the GitLab instance where the artifact was signed. - -To learn more about verifying signed artifacts, see [Cosign documentation](https://docs.sigstore.dev/cosign/verify/). - -```yaml -verify_artifact: - stage: verify - image: alpine:latest - before_script: - - apk add --update cosign - script: - - cosign verify-blob artifact.txt --bundle cosign.bundle --certificate-identity "https://gitlab.com/my-group/my-project//path/to/.gitlab-ci.yml@refs/heads/main" --certificate-oidc-issuer "https://gitlab.com" -``` diff --git a/doc/ci/yaml/workflow.md b/doc/ci/yaml/workflow.md index e88a96ae1f5..af275a15f9c 100644 --- a/doc/ci/yaml/workflow.md +++ b/doc/ci/yaml/workflow.md @@ -4,7 +4,7 @@ group: Pipeline Authoring 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 --- -# GitLab CI/CD `workflow` keyword **(FREE)** +# GitLab CI/CD `workflow` keyword **(FREE ALL)** Use the [`workflow`](index.md#workflow) keyword to control when pipelines are created. @@ -15,12 +15,12 @@ for tags, but the workflow prevents tag pipelines, the job never runs. Some example `if` clauses for `workflow: rules`: -| Example rules | Details | -|------------------------------------------------------|-----------------------------------------------------------| -| `if: '$CI_PIPELINE_SOURCE == "merge_request_event"'` | Control when merge request pipelines run. | +| Example rules | Details | +|------------------------------------------------------|---------| +| `if: '$CI_PIPELINE_SOURCE == "merge_request_event"'` | Control when merge request pipelines run. | | `if: '$CI_PIPELINE_SOURCE == "push"'` | Control when both branch pipelines and tag pipelines run. | -| `if: $CI_COMMIT_TAG` | Control when tag pipelines run. | -| `if: $CI_COMMIT_BRANCH` | Control when branch pipelines run. | +| `if: $CI_COMMIT_TAG` | Control when tag pipelines run. | +| `if: $CI_COMMIT_BRANCH` | Control when branch pipelines run. | See the [common `if` clauses for `rules`](../jobs/job_control.md#common-if-clauses-for-rules) for more examples. @@ -117,8 +117,8 @@ does not block triggered pipelines. ### Git Flow with merge request pipelines -You can use `workflow: rules` as part of [Git Flow or similar strategies](../../topics/gitlab_flow.md) -with merge request pipelines. With these rules, you can use [merge request pipeline features](../pipelines/merge_request_pipelines.md) +You can use `workflow: rules` with merge request pipelines. With these rules, +you can use [merge request pipeline features](../pipelines/merge_request_pipelines.md) with feature branches, while keeping long-lived branches to support multiple versions of your software. diff --git a/doc/ci/yaml/yaml_optimization.md b/doc/ci/yaml/yaml_optimization.md index 2cfda1116fe..84be9c85676 100644 --- a/doc/ci/yaml/yaml_optimization.md +++ b/doc/ci/yaml/yaml_optimization.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Optimize GitLab CI/CD configuration files **(FREE)** +# Optimize GitLab CI/CD configuration files **(FREE ALL)** You can reduce complexity and duplicated configuration in your GitLab CI/CD configuration files by using: diff --git a/doc/cloud_seed/index.md b/doc/cloud_seed/index.md index 7ac38ef2c15..a5067215ebb 100644 --- a/doc/cloud_seed/index.md +++ b/doc/cloud_seed/index.md @@ -4,7 +4,7 @@ group: Incubation info: Cloud Seed (formerly 5mp) is a GitLab Incubation Engineering program. No technical writer assigned to this group. --- -# Cloud Seed **(FREE)** +# Cloud Seed **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371332) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `google_cloud`. Disabled by default. > - [Enabled on self-managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100545) in GitLab 15.5. diff --git a/doc/development/adding_service_component.md b/doc/development/adding_service_component.md index 314065ffc10..6e47d2991dc 100644 --- a/doc/development/adding_service_component.md +++ b/doc/development/adding_service_component.md @@ -70,7 +70,7 @@ New services to be bundled with GitLab need to be available in the following env The first step of bundling a new service is to provide it in the development environment to engage in collaboration and feedback. - [Include in the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) -- [Include in the source install instructions](../install/installation.md) +- [Include in the self-compiled installation instructions](../install/installation.md) **Standard install methods** diff --git a/doc/development/advanced_search.md b/doc/development/advanced_search.md index 30e1874f1ed..805459cb4ee 100644 --- a/doc/development/advanced_search.md +++ b/doc/development/advanced_search.md @@ -52,9 +52,9 @@ during indexing and searching operations. Some of the benefits and tradeoffs to - Routing is not used if too many shards would be hit for global and group scoped searches. - Shard size imbalance might occur. -## Existing Analyzers/Tokenizers/Filters +## Existing analyzers and tokenizers -These are all defined in [`ee/lib/elastic/latest/config.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/elastic/latest/config.rb) +The following analyzers and tokenizers are defined in [`ee/lib/elastic/latest/config.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/elastic/latest/config.rb). ### Analyzers @@ -72,7 +72,7 @@ Please see the `sha_tokenizer` explanation later below for an example. #### `code_analyzer` -Used when indexing a blob's filename and content. Uses the `whitespace` tokenizer and the filters: [`code`](#code), `lowercase`, and `asciifolding` +Used when indexing a blob's filename and content. Uses the `whitespace` tokenizer and the [`word_delimiter_graph`](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-word-delimiter-graph-tokenfilter.html), `lowercase`, and `asciifolding` filters. The `whitespace` tokenizer was selected to have more control over how tokens are split. For example the string `Foo::bar(4)` needs to generate tokens like `Foo` and `bar(4)` to be properly searched. @@ -81,10 +81,6 @@ Please see the `code` filter for an explanation on how tokens are split. NOTE: The [Elasticsearch `code_analyzer` doesn't account for all code cases](../integration/advanced_search/elasticsearch_troubleshooting.md#elasticsearch-code_analyzer-doesnt-account-for-all-code-cases). -#### `code_search_analyzer` - -Not directly used for indexing, but rather used to transform a search input. Uses the `whitespace` tokenizer and the `lowercase` and `asciifolding` filters. - ### Tokenizers #### `sha_tokenizer` @@ -115,27 +111,10 @@ Example: - `'path/application.js'` - `'application.js'` -### Filters - -#### `code` - -Uses a [Pattern Capture token filter](https://www.elastic.co/guide/en/elasticsearch/reference/5.5/analysis-pattern-capture-tokenfilter.html) to split tokens into more easily searched versions of themselves. - -Patterns: - -- `"(\\p{Ll}+|\\p{Lu}\\p{Ll}+|\\p{Lu}+)"`: captures CamelCase and lowerCamelCase strings as separate tokens -- `"(\\d+)"`: extracts digits -- `"(?=([\\p{Lu}]+[\\p{L}]+))"`: captures CamelCase strings recursively. For example: `ThisIsATest` => `[ThisIsATest, IsATest, ATest, Test]` -- `'"((?:\\"|[^"]|\\")*)"'`: captures terms inside quotes, removing the quotes -- `"'((?:\\'|[^']|\\')*)'"`: same as above, for single-quotes -- `'\.([^.]+)(?=\.|\s|\Z)'`: separate terms with periods in-between -- `'([\p{L}_.-]+)'`: some common chars in file names to keep the whole filename intact (for example `my_file-ñame.txt`) -- `'([\p{L}\d_]+)'`: letters, numbers and underscores are the most common tokens in programming. Always capture them greedily regardless of context. - ## Gotchas -- Searches can have their own analyzers. Remember to check when editing analyzers -- `Character` filters (as opposed to token filters) always replace the original character, so they're not a good choice as they can hinder exact searches +- Searches can have their own analyzers. Remember to check when editing analyzers. +- `Character` filters (as opposed to token filters) always replace the original character. These filters can hinder exact searches. ## Zero downtime reindexing with multiple indices diff --git a/doc/development/ai_architecture.md b/doc/development/ai_architecture.md index f497047ccce..84a2635b13c 100644 --- a/doc/development/ai_architecture.md +++ b/doc/development/ai_architecture.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# AI Architecture (Experiment) +# AI Architecture GitLab has created a common set of tools to support our product groups and their utilization of AI. Our goals with this common architecture are: @@ -13,79 +13,20 @@ GitLab has created a common set of tools to support our product groups and their AI is moving very quickly, and we need to be able to keep pace with changes in the area. We have built an [abstraction layer](../../ee/development/ai_features.md) to do this, allowing us to take a more "pluggable" approach to the underlying models, data stores, and other technologies. -The following diagram shows a simplified view of how the different components in GitLab interact. The abstraction layer helps avoid code duplication within the REST APIs within the `AI API` block. - -```plantuml -@startuml -skin rose - -package "Code Suggestions" { - node "Model Gateway" - node "Triton Inference Server" as Triton -} - -package "Code Suggestions Models" as CSM { - node "codegen" - node "PaLM" -} - -package "Suggested Reviewers" { - node "Model Gateway (SR)" - node "Extractor" - node "Serving Model" -} - -package "AI API" as AIF { - node "OpenAI" - node "Vertex AI" -} - -package GitLab { - node "Web IDE" - - package "Web" { - node "REST API" - node "GraphQL" - } - - package "Jobs" { - node "Sidekiq" - } -} - -package Databases { - node "Vector Database" - node "PostgreSQL" -} - -node "VSCode" - -"Model Gateway" --> Triton -Triton --> CSM -GitLab --> Databases -VSCode --> "Model Gateway" -"Web IDE" --> "Model Gateway" -"Web IDE" --> "GraphQL" -"Web IDE" --> "REST API" -"Model Gateway" -[#blue]--> "REST API": user authorized? - -"Sidekiq" --> AIF -Web --> AIF - -"Model Gateway (SR)" --> "REST API" -"Model Gateway (SR)" --> "Serving Model" -"Extractor" --> "GraphQL" -"Sidekiq" --> "Model Gateway (SR)" - -@enduml -``` +The following diagram from the [architecture blueprint](../architecture/blueprints/ai_gateway/index.md) shows a simplified view of how the different components in GitLab interact. The abstraction layer helps avoid code duplication within the REST APIs within the `AI API` block. + + ## SaaS-based AI abstraction layer -GitLab currently operates a cloud-hosted AI architecture. We are exploring how self-managed instances integrate with it. +GitLab currently operates a cloud-hosted AI architecture. We will allow access to it for licensed self managed instances using the AI-gateway. Please see [the blueprint](../architecture/blueprints/ai_gateway) for details There are two primary reasons for this: the best AI models are cloud-based as they often depend on specialized hardware designed for this purpose, and operating self-managed infrastructure capable of AI at-scale and with appropriate performance is a significant undertaking. We are actively [tracking self-managed customers interested in AI](https://gitlab.com/gitlab-org/gitlab/-/issues/409183). +## AI Gateway + +The AI Gateway (formerly the [model gateway](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist)) is a standalone-service that will give access to AI features to all users of GitLab, no matter which instance they are using: self-managed, dedicated or GitLab.com. The SaaS-based AI abstraction layer will transition to connecting to this gateway, rather than accessing cloud-based providers directly. + ## Supported technologies As part of the AI working group, we have been investigating various technologies and vetting them. Below is a list of the tools which have been reviewed and already approved for use within the GitLab application. @@ -127,3 +68,38 @@ For optimal `probes` and `lists` values: - Use `lists` equal to `rows / 1000` for tables with up to 1 million rows and `sqrt(rows)` for larger datasets. - For `probes` start with `lists / 10` for tables up to 1 million rows and `sqrt(lists)` for larger datasets. + +### Code Suggestions + +Code Suggestions is being integrated as part of the GitLab-Rails repository which will unify the architectures between Code Suggestions and AI features that use the abstraction layer, along with offering self-managed support for the other AI features. + +The following table documents functionality that Code Suggestions offers today, and what those changes will look like as part of the unification: + +| Topic | Details | Where this happens today | Where this will happen going forward | +| ----- | ------ | -------------- | ------------------ | +| Request processing | | | | +| | Receives requests from IDEs (VSCode, GitLab WebIDE, MS Visual Studio, IntelliJ, JetBrains, VIM, Emacs, Sublime), including code before and after the cursor | AI Gateway | Abstraction Layer | +| | Authentication the current user, verifies they are authorized to use Code Suggestions for this project | AI Gateway | Abstraction layer | +| | Preprocesses the request to add context, such as including imports via TreeSitter | AI Gateway | Undecided | +| | Routes the request to the AI Provider | AI Gateway | AI Gateway | +| | Returns the response to the IDE | AI Gateway | Abstraction Layer | +| | Logs the request, including timestamp, response time, model, etc | AI Gateway | Both | +| Telemetry | | | | +| | User acceptance or rejection in the IDE | AI Gateway | [Both](https://gitlab.com/gitlab-org/gitlab/-/issues/418282) | +| | Number of unique users per day | [Abstraction Layer](https://app.periscopedata.com/app/gitlab/1143612/Code-Suggestions-Usage) | Undecided | +| | Error rate, model usage, response time, IDE usage | [AI Gateway](https://log.gprd.gitlab.net/app/dashboards#/view/6c947f80-7c07-11ed-9f43-e3784d7fe3ca?_g=(refreshInterval:(pause:!t,value:0),time:(from:now-6h,to:now))) | Both | +| | Suggestions per language | AI Gateway |[Both](https://gitlab.com/groups/gitlab-org/-/epics/11017) | +| Monitoring | | Both | Both | +| | | | | +| Model Routing | | | | +| | Currently we are not using this functionality, but Code Suggestions is able to support routing to multiple models based on a percentage of traffic | AI Gateway | Both | +| Internal Models | | | | +| | Currently unmaintained, the ability to run models in our own instance, running them inside Triton, and routing requests to our own models | AI Gateway | AI Gateway | + +#### Code Suggestions Latency + +Code Suggestions acceptance rates are _highly_ sensitive to latency. While writing code with an AI assistant, a user will pause only for a short duration before continuing on with manually typing out a block of code. As soon as the user has pressed a subsequent keypress, the existing suggestion will be invalidated and a new request will need to be issued to the code suggestions endpoint. In turn, this request will also be highly sensitive to latency. + +In a worst case with sufficient latency, the IDE could be issuing a string of requests, each of which is then ignored as the user proceeds without waiting for the response. This adds no value for the user, while still putting load on our services. + +See our discussions [here](https://gitlab.com/gitlab-org/gitlab/-/issues/418955) around how we plan to iterate on latency for this feature. diff --git a/doc/development/ai_features.md b/doc/development/ai_features.md index 52dc37caec3..ffe151f3876 100644 --- a/doc/development/ai_features.md +++ b/doc/development/ai_features.md @@ -1,6 +1,6 @@ --- -stage: none -group: none +stage: AI-powered +group: AI Framework 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 --- @@ -52,6 +52,9 @@ All AI features are experimental. ## Test AI features locally +NOTE: +Use [this snippet](https://gitlab.com/gitlab-org/gitlab/-/snippets/2554994) for help automating the following section. + 1. Enable the required general feature flags: ```ruby @@ -74,6 +77,9 @@ All AI features are experimental. ### Set up the embedding database +NOTE: +Use [this snippet](https://gitlab.com/gitlab-org/gitlab/-/snippets/2554994) for help automating the following section. + For features that use the embedding database, additional setup is needed. 1. Enable [pgvector](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/pgvector.md#enable-pgvector-in-the-gdk) in GDK @@ -88,6 +94,9 @@ For features that use the embedding database, additional setup is needed. ### Set up GitLab Duo Chat +NOTE: +Use [this snippet](https://gitlab.com/gitlab-org/gitlab/-/snippets/2554994) for help automating the following section. + 1. [Enable Anthropic API features](#configure-anthropic-access). 1. [Enable OpenAI support](#configure-openai-access). 1. [Ensure the embedding database is configured](#set-up-the-embedding-database). @@ -123,6 +132,14 @@ index 5fa7ae8a2bc1..5fe996ba0345 100644 def valid? ``` +### Working with GitLab Duo Chat + +Prompts are the most vital part of GitLab Duo Chat system. Prompts are the instructions sent to the Large Language Model to perform certain tasks. + +The state of the prompts is the result of weeks of iteration. If you want to change any prompt in the current tool, you must put it behind a feature flag. + +If you have any new or updated prompts, ask members of AI Framework team to review, because they have significant experience with them. + ### Setup for GitLab documentation chat (legacy chat) To populate the embedding database for GitLab chat: @@ -130,12 +147,63 @@ To populate the embedding database for GitLab chat: 1. Open a rails console 1. Run [this script](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/10588#note_1373586079) to populate the embedding database +### Contributing to GitLab Duo Chat + +The Chat feature uses a [zero-shot agent](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/gitlab/llm/chain/agents/zero_shot/executor.rb) that includes a system prompt explaining how the large language model should interpret the question and provide an +answer. The system prompt defines available tools that can be used to gather +information to answer the user's question. + +The zero-shot agent receives the user's question and decides which tools to use to gather information to answer it. +It then makes a request to the large language model, which decides if it can answer directly or if it needs to use one +of the defined tools. + +The tools each have their own prompt that provides instructions to the large language model on how to use that tool to +gather information. The tools are designed to be self-sufficient and avoid multiple requests back and forth to +the large language model. + +After the tools have gathered the required information, it is returned to the zero-shot agent, which asks the large language +model if enough information has been gathered to provide the final answer to the user's question. + +#### Adding a new tool + +To add a new tool: + +1. Create files for the tool in the `ee/lib/gitlab/llm/chain/tools/` folder. Use existing tools like `issue_identifier` or +`resource_reader` as a template. + +1. Write a class for the tool that includes: + + - Name and description of what the tool does + - Example questions that would use this tool + - Instructions for the large language model on how to use the tool to gather information - so the main prompts that + this tool is using. + +1. Test and iterate on the prompt using RSpec tests that make real requests to the large language model. + - Prompts require trial and error, the non-deterministic nature of working with LLM can be surprising. + - Anthropic provides good [guide](https://docs.anthropic.com/claude/docs/introduction-to-prompt-design) on working on prompts. + +1. Implement code in the tool to parse the response from the large language model and return it to the zero-shot agent. + +1. Add the new tool name to the `tools` array in `ee/lib/gitlab/llm/completions/chat.rb` so the zero-shot agent knows about it. + +1. Add tests by adding questions to the test-suite for which the new tool should respond to. Iterate on the prompts as needed. + +The key things to keep in mind are properly instructing the large language model through prompts and tool descriptions, +keeping tools self-sufficient, and returning responses to the zero-shot agent. With some trial and error on prompts, +adding new tools can expand the capabilities of the chat feature. + +There are available short [videos](https://www.youtube.com/playlist?list=PL05JrBw4t0KoOK-bm_bwfHaOv-1cveh8i) covering this topic. + ### Debugging To gather more insights about the full request, use the `Gitlab::Llm::Logger` file to debug logs. +The default logging level on production is `INFO` and **must not** be used to log any data that could contain personal identifying information. + To follow the debugging messages related to the AI requests on the abstraction layer, you can use: ```shell +export LLM_DEBUG=1 +gdk start tail -f log/llm.log ``` @@ -143,7 +211,7 @@ tail -f log/llm.log In order to obtain a GCP service key for local development, please follow the steps below: -- Create a sandbox GCP environment by visiting [this page](https://about.gitlab.com/handbook/infrastructure-standards/#individual-environment) and following the instructions, or by requesting access to our existing group environment by using [this template](https://gitlab.com/gitlab-com/it/infra/issue-tracker/-/issues/new?issuable_template=gcp_group_account_iam_update_request). At this time, access to any endpoints outside of `text-bison` or `chat-bison` must be made through the group environment. +- Create a sandbox GCP environment by visiting [this page](https://about.gitlab.com/handbook/infrastructure-standards/#individual-environment) and following the instructions, or by requesting access to our existing group environment by using [this template](https://gitlab.com/gitlab-com/it/infra/issue-tracker/-/issues/new?issuable_template=gcp_group_account_iam_update_request). - In the GCP console, go to `IAM & Admin` > `Service Accounts` and click on the "Create new service account" button - Name the service account something specific to what you're using it for. Select Create and Continue. Under `Grant this service account access to project`, select the role `Vertex AI User`. Select `Continue` then `Done` - Select your new service account and `Manage keys` > `Add Key` > `Create new key`. This will download the **private** JSON credentials for your service account. @@ -174,18 +242,47 @@ Gitlab::CurrentSettings.update!(anthropic_api_key: <insert API key>) ### Testing GitLab Duo Chat with predefined questions -Because success of answers to user questions in GitLab Duo Chat heavily depends on toolchain and prompts of each tool, it's common that even a minor change in a prompt or a tool impacts processing of some questions. To make sure that a change in the toolchain doesn't break existing functionality, you can use following commands to validate answers to some predefined questions: - -1. Rake task which iterates through questions defined in CSV file and checks tools used for evaluating each question. +Because success of answers to user questions in GitLab Duo Chat heavily depends on toolchain and prompts of each tool, it's common that even a minor change in a prompt or a tool impacts processing of some questions. To make sure that a change in the toolchain doesn't break existing functionality, you can use the following rspecs to validate answers to some predefined questions: ```ruby -rake gitlab:llm:zero_shot:test:questions[<issue_url>] +export OPENAI_API_KEY='<key>' +export ANTHROPIC_API_KEY='<key>' +REAL_AI_REQUEST=1 rspec ee/spec/lib/gitlab/llm/chain/agents/zero_shot/executor_spec.rb ``` -1. RSpec which iterates through resource-specific questions on predefined resources: +When you need to update the test questions that require documentation embeddings, +make sure a new fixture is generated and committed together with the change. + +#### Populating embeddings and using embeddings fixture + +To seed your development database with the embeddings for GitLab Documentation, +you may use the pre-generated embeddings and a Rake test. + +```shell +RAILS_ENV=development bundle exec rake gitlab:llm:embeddings:seed_pre_generated +``` + +The DBCleaner gem we use clear the database tables before each test runs. +Instead of fully populating the table `tanuki_bot_mvc` where we store embeddings for the documentations, +we can add a few selected embeddings to the table from a pre-generated fixture. + +For instance, to test that the question "How can I reset my password" is correctly +retrieving the relevant embeddings and answered, we can extract the top N closet embeddings +to the question into a fixture and only restore a small number of embeddings quickly. +To faciliate an extraction process, a Rake task been written. +You can add or remove the questions needed to be tested in the Rake task and run the task to generate a new fixture. + +```shell +RAILS_ENV=development bundle exec rake gitlab:llm:embeddings:extract_embeddings +``` + +In the specs where you need to use the embeddings, +use the RSpec config hook `:ai_embedding_fixtures` on a context. ```ruby -ANTHROPIC_API_KEY='<key>' REAL_AI_REQUEST=1 rspec ee/spec/lib/gitlab/llm/chain/agents/zero_shot/executor_spec.rb +context 'when asking about how to use GitLab', :ai_embedding_fixtures do + # ...examples +end ``` ## Experimental REST API @@ -409,6 +506,52 @@ module EE end ``` +### Pairing requests with responses + +Because multiple users' requests can be processed in parallel, when receiving responses, +it can be difficult to pair a response with its original request. The `requestId` +field can be used for this purpose, because both the request and response are assured +to have the same `requestId` UUID. + +### Caching + +AI requests and responses can be cached. Cached conversation is being used to +display user interaction with AI features. In the current implementation, this cache +is not used to skip consecutive calls to the AI service when a user repeats +their requests. + +```graphql +query { + aiMessages { + nodes { + id + requestId + content + role + errors + timestamp + } + } +} +``` + +This cache is especially useful for chat functionality. For other services, +caching is disabled. (It can be enabled for a service by using `cache_response: true` +option.) + +Caching has following limitations: + +- Messages are stored in Redis stream. +- There is a single stream of messages per user. This means that all services + currently share the same cache. If needed, this could be extended to multiple + streams per user (after checking with the infrastructure team that Redis can handle + the estimated amount of messages). +- Only the last 50 messages (requests + responses) are kept. +- Expiration time of the stream is 3 days since adding last message. +- User can access only their own messages. There is no authorization on the caching + level, and any authorization (if accessed by not current user) is expected on + the service layer. + ### Check if feature is allowed for this resource based on namespace settings There are two settings allowed on root namespace level that restrict the use of AI features: diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 9bc62ed7095..440068d55c2 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -47,6 +47,11 @@ The GraphQL framework has some specific gotchas to be aware of, and domain exper If you are asked to review a merge request that modifies any GraphQL files or adds an endpoint, please have a look at [our GraphQL review guide](graphql_guide/reviewing.md). +## Reading GraphQL logs + +See the [Reading GraphQL logs](graphql_guide/monitoring.md) guide for tips on how to inspect logs +of GraphQL requests and monitor the performance of your GraphQL queries. + ## Authentication Authentication happens through the `GraphqlController`, right now this @@ -2045,8 +2050,8 @@ full stack: - An [argument's `default_value`](https://graphql-ruby.org/fields/arguments.html) applies correctly. - Objects resolve successfully, and there are no N+1 issues. -When adding a query, you can use the `a working graphql query` shared example to test if the query -renders valid results. +When adding a query, you can use the `a working graphql query that returns data` and +`a working graphql query that returns no data` shared examples to test if the query renders valid results. You can construct a query including all available fields using the `GraphqlHelpers#all_graphql_fields_for` helper. This makes it more straightforward to add a test rendering all possible fields for a query. @@ -2404,7 +2409,3 @@ elimination of laziness, where needed. For dealing with lazy values without forcing them, use `Gitlab::Graphql::Lazy.with_value`. - -## Monitoring GraphQL - -See the [Monitoring GraphQL](graphql_guide/monitoring.md) guide for tips on how to inspect logs of GraphQL requests and monitor the performance of your GraphQL queries. diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index 2ed4d934022..45568c700c7 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -44,16 +44,16 @@ A good example is as follows: ```ruby desc 'Get all broadcast messages' do detail 'This feature was introduced in GitLab 8.12.' - success Entities::BroadcastMessage + success Entities::System::BroadcastMessage end params do optional :page, type: Integer, desc: 'Current page number' optional :per_page, type: Integer, desc: 'Number of messages per page' end get do - messages = BroadcastMessage.all + messages = System::BroadcastMessage.all - present paginate(messages), with: Entities::BroadcastMessage + present paginate(messages), with: Entities::System::BroadcastMessage end ``` diff --git a/doc/development/application_secrets.md b/doc/development/application_secrets.md index 5b0755e97e3..33bba2b3285 100644 --- a/doc/development/application_secrets.md +++ b/doc/development/application_secrets.md @@ -23,9 +23,9 @@ This page is a development guide for application secrets. |Installation type |Location | |--- |--- | -|Omnibus |[`/etc/gitlab/gitlab-secrets.json`](https://docs.gitlab.com/omnibus/settings/backups.html#backup-and-restore-omnibus-gitlab-configuration) | -|Cloud Native GitLab Charts |[Kubernetes Secrets](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/f65c3d37fc8cf09a7987544680413552fb666aac/doc/installation/secrets.md#gitlab-rails-secret)| -|Source |`<path-to-gitlab-rails>/config/secrets.yml` (Automatically generated by [01_secret_token.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/initializers/01_secret_token.rb)) | +| Linux package |[`/etc/gitlab/gitlab-secrets.json`](https://docs.gitlab.com/omnibus/settings/backups.html#backup-and-restore-omnibus-gitlab-configuration) | +| Cloud Native GitLab Charts |[Kubernetes Secrets](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/f65c3d37fc8cf09a7987544680413552fb666aac/doc/installation/secrets.md#gitlab-rails-secret)| +| Self-compiled |`<path-to-gitlab-rails>/config/secrets.yml` (Automatically generated by [01_secret_token.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/initializers/01_secret_token.rb)) | ## Warning: Before you add a new secret to application secrets @@ -38,9 +38,9 @@ GitLab.com environments prior to changing this file. **Examples** -- [Change for source installation](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27581) -- [Change for omnibus installation](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/3267) -- [Change for omnibus installation](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4158) +- [Change for self-compiled installation](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27581) +- [Change for Linux package installation](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/3267) +- [Change for Linux package installation](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4158) - [Change for Cloud Native installation](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/1318) ## Further iteration diff --git a/doc/development/application_slis/index.md b/doc/development/application_slis/index.md index f48088a6e08..30bd6011a67 100644 --- a/doc/development/application_slis/index.md +++ b/doc/development/application_slis/index.md @@ -14,40 +14,40 @@ and their success close to the implementation and allows the people building features to easily define how these features should be monitored. -Defining an SLI causes 2 -[Prometheus counters](https://prometheus.io/docs/concepts/metric_types/#counter) -to be emitted from the rails application: - -- `gitlab_sli:<sli name>:total`: incremented for each operation. -- `gitlab_sli:<sli_name>:success_total`: incremented for successful - operations. - ## Existing SLIs 1. [`rails_request`](rails_request.md) 1. `global_search_apdex` 1. `global_search_error_rate` 1. `global_search_indexing_apdex` +1. [`sidekiq_execution`](sidekiq_execution.md) ## Defining a new SLI -An SLI can be defined using the `Gitlab::Metrics::Sli::Apdex` or -`Gitlab::Metrics::Sli::ErrorRate` class. These work in broadly the same way, but -for clarity, they define different metric names: +An SLI can be defined with the `Gitlab::Metrics::Sli::Apdex` or +`Gitlab::Metrics::Sli::ErrorRate` class. When you define an SLI, two +[Prometheus counters](https://prometheus.io/docs/concepts/metric_types/#counter) +are emitted from the Rails application. Both counters work in broadly the same way and contain a total operation count. `Apdex` uses a success rate to calculate a success ratio, and `ErrorRate` uses an error rate to calculate an error ratio. -1. `Gitlab::Metrics::Sli::Apdex.new('foo')` defines: - 1. `gitlab_sli:foo_apdex:total` for the total number of measurements. - 1. `gitlab_sli:foo_apdex:success_total` for the number of successful +The following metrics are defined: + +- `Gitlab::Metrics::Sli::Apdex.new('foo')` defines: + - `gitlab_sli_foo_apdex_total` for the total number of measurements. + - `gitlab_sli_foo_apdex_success_total` for the number of successful measurements. -1. `Gitlab::Metrics::Sli::ErrorRate.new('foo')` defines: - 1. `gitlab_sli:foo:total` for the total number of measurements. - 1. `gitlab_sli:foo:error_total` for the number of error - measurements - as this is an error rate, it's more natural to talk about - errors divided by the total. +- `Gitlab::Metrics::Sli::ErrorRate.new('foo')` defines: + - `gitlab_sli_foo_total` for the total number of measurements. + - `gitlab_sli_foo_error_total` for the number of error + measurements. Because this metric is an error rate, + errors are divided by the total number. As shown in this example, they can share a base name (`foo` in this example). We recommend this when they refer to the same operation. +You should use `Apdex` to measure the performance of successful operations. You don't have to measure the performance of a failing request because that performance should be tracked with `ErrorRate`. For example, you can measure whether a request is performing within a specified latency threshold. + +You should use `ErrorRate` to measure the rate of unsuccessful operations. For example, you can measure whether a failed request returns an HTTP status greater than or equal to `500`. + Before the first scrape, it is important to have [initialized the SLI with all possible label-combinations](https://prometheus.io/docs/practices/instrumentation/#avoid-missing-metrics). This avoid confusing results when using these counters in calculations. diff --git a/doc/development/application_slis/rails_request.md b/doc/development/application_slis/rails_request.md index b3ee326aa87..e5a02c20472 100644 --- a/doc/development/application_slis/rails_request.md +++ b/doc/development/application_slis/rails_request.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: This SLI is used for service monitoring. But not for [error budgets for stage groups](../stage_group_observability/index.md#error-budget) -by default. You can [opt in](#error-budget-attribution-and-ownership). +by default. The request Apdex SLI and the error rate SLI are [SLIs defined in the application](index.md). diff --git a/doc/development/application_slis/sidekiq_execution.md b/doc/development/application_slis/sidekiq_execution.md new file mode 100644 index 00000000000..dfe7f3864d5 --- /dev/null +++ b/doc/development/application_slis/sidekiq_execution.md @@ -0,0 +1,74 @@ +--- +stage: Platforms +group: Scalability +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 +--- + +# Sidekiq execution SLIs (service level indicators) + +> [Introduced](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/700) in GitLab 16.0. This version of Sidekiq execution SLIs replaces the old version of the SLI where you can now drill down by workers in the [Application SLI Violations dashboard](https://dashboards.gitlab.net/d/general-application-sli-violations/general-application-sli-violations?orgId=1&var-PROMETHEUS_DS=Global&var-environment=gprd&var-stage=main&var-product_stage=All&var-stage_group=All&var-component=sidekiq_execution) for stage groups. + +NOTE: +This SLI is used for service monitoring. But not for [error budgets for stage groups](../stage_group_observability/index.md#error-budget) +by default. + +The Sidekiq execution Apdex measures the duration of successful jobs completion as an indicator for +application performance. + +The error rate measures unsuccessful jobs completion when exception occurs as an indicator for +server misbehavior. + +- `gitlab_sli_sidekiq_execution_apdex_total`: This counter gets + incremented for every successful job execution that does not result in an exception. It ensures slow jobs are not + counted twice, because the job is already counted in the error SLI. + +- `gitlab_sli_sidekiq_execution_apdex_success_total`: This counter gets + incremented for every successful job that performed faster than + the [defined target duration depending on the job urgency](../sidekiq/worker_attributes.md#job-urgency). + +- `gitlab_sli_sidekiq_execution_error_total`: This counter gets + incremented for every job that encountered an exception. + +- `gitlab_sli_sidekiq_execution_total`: This counter gets + incremented for every job execution. + +These counters are labeled with: + +- `worker`: The identification of the worker. + +- `feature_category`: The feature category specified for that worker. + +- `urgency`: The urgency attribute specified for that worker. + +- `external_dependencies`: The boolean value `yes` or `no` based on the [external dependencies attribute](../sidekiq/worker_attributes.md#jobs-with-external-dependencies). + +- `queue`: The queue in which the job is running. + +For more information about these SLIs, see the [Sidekiq SLIs documentation](https://gitlab.com/gitlab-com/runbooks/-/blob/master/docs/sidekiq/sidekiq-slis.md) in runbooks. + +## Adjusting job urgency + +Not all workers perform the same type of work, so it is possible to +define different urgency levels for different jobs. A job with a +lower urgency can have a longer execution duration than jobs with high urgency. + +For more information on the execution latency requirement and how to set a job's urgency, see the [Sidekiq worker attributes page](../sidekiq/worker_attributes.md#job-urgency). + +### Error budget attribution and ownership + +This SLI is used for service level monitoring. It feeds into the +[error budget for stage groups](../stage_group_observability/index.md#error-budget). + +The workers for the SLI feed into a group's error budget based on the +[feature category declared on it](../feature_categorization/index.md). + +To know which workers are included for your group, see the +Sidekiq Completion Rate panel on the +[group dashboard for your group](https://dashboards.gitlab.net/dashboards/f/stage-groups/stage-groups). +In the **Budget Attribution** row, the **Sidekiq Execution Apdex** log link shows you +how many jobs are not meeting the 10 second or 300 second target. + +## Jobs with external dependencies + +Jobs with [external dependencies](../sidekiq/worker_attributes.md#jobs-with-external-dependencies) are excluded from +the Apdex and error ratio calculation. diff --git a/doc/development/audit_event_guide/index.md b/doc/development/audit_event_guide/index.md index c49d3a243c0..b8af1341919 100644 --- a/doc/development/audit_event_guide/index.md +++ b/doc/development/audit_event_guide/index.md @@ -29,14 +29,14 @@ If you have any questions, please reach out to `@gitlab-org/govern/compliance` t To instrument an audit event, the following attributes should be provided: -| Attribute | Type | Required? | Description | -|:-------------|:---------------------|:----------|:------------------------------------------------------------------| -| `name` | String | false | Action name to be audited. Represents the [type of the event](#event-type-definitions). Used for error tracking | -| `author` | User | true | User who authors the change. Can be an [internal user](../internal_users.md). For example, [inactive project deletion](../../administration/inactive_project_deletion.md) audit events are authored by `GitLab-Admin-Bot`. | -| `scope` | User, Project, Group | true | Scope which the audit event belongs to | -| `target` | Object | true | Target object being audited | -| `message` | String | true | Message describing the action ([not translated](#i18n-and-the-audit-event-message-attribute)) | -| `created_at` | DateTime | false | The time when the action occurred. Defaults to `DateTime.current` | +| Attribute | Type | Required? | Description | +|:-------------|:------------------------------------|:----------|:------------------------------------------------------------------| +| `name` | String | false | Action name to be audited. Represents the [type of the event](#event-type-definitions). Used for error tracking | +| `author` | User | true | User who authors the change. Can be an [internal user](../internal_users.md). For example, [inactive project deletion](../../administration/inactive_project_deletion.md) audit events are authored by `GitLab-Admin-Bot`. | +| `scope` | User, Project, Group, or InstanceScope | true | Scope which the audit event belongs to | +| `target` | Object | true | Target object being audited | +| `message` | String | true | Message describing the action ([not translated](#i18n-and-the-audit-event-message-attribute)) | +| `created_at` | DateTime | false | The time when the action occurred. Defaults to `DateTime.current` | ## How to instrument new Audit Events diff --git a/doc/development/backend/ruby_style_guide.md b/doc/development/backend/ruby_style_guide.md index 714c8571d20..d6e2f7a48d2 100644 --- a/doc/development/backend/ruby_style_guide.md +++ b/doc/development/backend/ruby_style_guide.md @@ -161,6 +161,145 @@ def method end ``` +## Avoid ActiveRecord callbacks + +[ActiveRecord callbacks](https://guides.rubyonrails.org/active_record_callbacks.html) allow +you to "trigger logic before or after an alteration of an object's state." + +Use callbacks when no superior alternative exists, but employ them only if you +thoroughly understand the reasons for doing so. + +When adding new lifecycle events for ActiveRecord objects, it is preferable to +add the logic to a service class instead of a callback. + +## Why callbacks shoud be avoided + +In general, callbacks should be avoided because: + +- Callbacks are hard to reason about because invocation order is not obvious and + they break code narrative. +- Callbacks are harder to locate and navigate because they rely on reflection to + trigger rather than being ordinary method calls. +- Callbacks make it difficult to apply changes selectively to an object's state + because changes always trigger the entire callback chain. +- Callbacks trap logic in the ActiveRecord class. This tight coupling encourages + fat models that contain too much business logic, which could instead live in + service objects that are more reusable, composable, and are easier to test. +- Illegal state transitions of an object can be better enforced through + attribute validations. +- Heavy use of callbacks affects factory creation speed. With some classes + having hundreds of callbacks, creating an instance of that object for + an automated test can be a very slow operation, resulting in slow specs. + +Some of these examples are discussed in this [video from thoughtbot](https://www.youtube.com/watch?v=GLBMfB8N1G8). + +The GitLab codebase relies heavily on callbacks and it is hard to refactor them +once added due to invisible dependencies. As a result, this guideline does not +call for removing all existing callbacks. + +### When to use callbacks + +Callbacks can be used in special cases. Some examples of cases where adding a +callback makes sense: + +- A dependency uses callbacks and we would like to override the callback + behavior. +- Incrementing cache counts. +- Data normalization that only relates to data on the current model. + +### Example of moving from a callback to a service + +There is a project with the following basic data model: + +```ruby +class Project + has_one :repository +end + +class Repository + belongs_to :project +end +``` + +Say we want to create a repository after a project is created and use the +project name as the repository name. A developer familiar with Rails might +immediately think: sounds like a job for an ActiveRecord callback! And add this +code: + +```ruby +class Project + has_one :repository + + after_initialize :create_random_name + after_create :create_repository + + def create_random_name + SecureRandom.alphanumeric + end + + def create_repository + Repository.create!(project: self) + end +end + +class Repository + after_initialize :set_name + + def set_name + name = project.name + end +end + +class ProjectsController + def create + Project.create! # also creates a repository and names it + end +end +``` + +While this seems pretty harmless for a baby Rails app, adding this type of logic +via callbacks has many downsides once your Rails app becomes large and complex +(all of which are listed in this documentation). Instead, we can add this +logic to a service class: + +```ruby +class Project + has_one :repository +end + +class Repository + belongs_to :project +end + +class ProjectCreator + def self.execute + ApplicationRecord.transaction do + name = SecureRandom.alphanumeric + project = Project.create!(name: name) + Repository.create!(project: project, name: name) + end + end +end + +class ProjectsController + def create + ProjectCreator.execute + end +end +``` + +With an application this simple, it can be hard to see the benefits of the second +approach. But we already some benefits: + +- Can test `Repository` creation logic separate from `Project` creation logic. Code + no longer violates law of demeter (`Repository` class doesn't need to know + `project.name`). +- Clarity of invocation order. +- Open to change: if we decide there are some scenarios where we do not want a + repository created for a project, we can create a new service class rather + than needing to refactor to `Project` and `Repository` classes. +- Each instance of a `Project` factory does not create a second (`Repository`) object. + ## Styles we have no opinion on If a RuboCop rule is proposed and we choose not to add it, we should document that decision in this guide so it is more discoverable and link the relevant discussion as a reference. diff --git a/doc/development/changelog.md b/doc/development/changelog.md index 56b5fa8c976..486808f25e7 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -94,7 +94,7 @@ EE: true uses system fonts for all text." - Any client-facing change to our REST and GraphQL APIs **must** have a changelog entry. See the [complete list what comprises a GraphQL breaking change](api_graphql_styleguide.md#breaking-changes). -- Any change that introduces an [advanced search migration](search/advanced_search_migration_styleguide.md#creating-a-new-advanced-search-migration) +- Any change that introduces an [advanced search migration](search/advanced_search_migration_styleguide.md#create-a-new-advanced-search-migration) **must** have a changelog entry. - A fix for a regression introduced and then fixed in the same release (such as fixing a bug introduced during a monthly release candidate) **should not** diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index dceb2da5951..41ae4fe14b4 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -109,6 +109,7 @@ A job with the `created` state isn't seen by the runner yet. To make it possible 1. The job required a manual start and it has been triggered. 1. All jobs from the previous stage have completed successfully. In this case we transition all jobs from the next stage to `pending`. 1. The job specifies DAG dependencies using `needs:` and all the dependent jobs are completed. +1. The job has not been [dropped](#dropping-stuck-builds) because of its not-runnable state by [`Ci::PipelineCreation::DropNotRunnableBuildsService`](https://gitlab.com/gitlab-org/gitlab/-/blob/v16.0.4-ee/ee/app/services/ci/pipeline_creation/drop_not_runnable_builds_service.rb). When the runner is connected, it requests the next `pending` job to run by polling the server continuously. @@ -119,11 +120,6 @@ After the server receives the request it selects a `pending` job based on the [` Once all jobs are completed for the current stage, the server "unlocks" all the jobs from the next stage by changing their state to `pending`. These can now be picked by the scheduling algorithm when the runner requests new jobs, and continues like this until all stages are completed. -If a job is not picked up by a runner in 24 hours it is automatically removed from -the processing queue after that time. If a pending job is stuck, when there is no -runner available that can process it, it is removed from the queue after 1 hour. -In both cases the job's status is changed to `failed` with an appropriate failure reason. - ### Communication between runner and GitLab server After the runner is [registered](https://docs.gitlab.com/runner/register/) using the registration token, the server knows what type of jobs it can execute. This depends on: @@ -163,6 +159,47 @@ At this point we loop through remaining `pending` jobs and we try to assign the As we increase the number of runners in the pool we also increase the chances of conflicts which would arise if assigning the same job to different runners. To prevent that we gracefully rescue conflict errors and assign the next job in the list. +### Dropping stuck builds + +There are two ways of marking builds as "stuck" and drop them. + +1. When a build is created, [`Ci::PipelineCreation::DropNotRunnableBuildsService`](https://gitlab.com/gitlab-org/gitlab/-/blob/v16.0.4-ee/ee/app/services/ci/pipeline_creation/drop_not_runnable_builds_service.rb) checks for upfront known conditions that would make jobs not executable: + - If there is not enough [CI/CD Minutes](#compute-quota) to run the build, then the build is immediately dropped with `ci_quota_exceeded`. + - [In the future](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121761), if the project is not on the plan that available runners for the build require via `allowed_plans`, then the build is immediately dropped with `no_matching_runner`. +1. If there is no available Runner to pick up a build, it is dropped after 1 hour by [`Ci::StuckBuilds::DropPendingService`](https://gitlab.com/gitlab-org/gitlab/-/blob/v16.0.4-ee/app/services/ci/stuck_builds/drop_pending_service.rb). + - If a job is not picked up by a runner in 24 hours it is automatically removed from + the processing queue after that time. + - If a pending job is **stuck**, when there is no + runner available that can process it, it is removed from the queue after 1 hour. + - In both cases the job's status is changed to `failed` with an appropriate failure reason. + +#### The reason behind this difference + +CI Minutes quota mechanism is handled early when the job is created because it is a constant decision for most of the time. +Once a project exceeds the limit, every next job matching it will be applicable for it until next month starts. +Of course, the project owner can buy additional minutes, but that is a manual action that the project need to take. + +The same mechanism will be used for `allowed_plans` [soon](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121761). +If the project is not on the required plan and a job is targeting such runner, +it will be failing constantly until the project owner changes the configuration or upgrades the namespace to the required plan. + +These two mechanisms are also very SaaS specific and at the same time are quite compute expensive when we consider SaaS' scale. +Doing the check before the job is even transitioned to pending and failing early makes a lot of sense here. + +Why we don't handle other cases for pending and drop jobs early? +In some cases, a job is in pending only because the runner is slow on taking up jobs. +This is not something that you can know at GitLab level. +Depending on the runner's configuration and capacity and the size of the queue in GitLab, a job may be taken immediately, or may need to wait. + +There may be also other reasons: + +- you are handling runner maintenance and it's not available for a while at all, +- you are updating configuration and by mistake, you've messed up the tagging and/or protected flag (or in the case of our SaaS instance runners; you've assigned a wrong cost factor or `allowed_plans` configuration). + +All of that are problems that may be temporary and mostly are not expected to happen and are expected to be detected and fixed early. +We definitely don't want to drop jobs immediately when one of these conditions is happening. +Dropping a job only because a runner is at capacity or because there is a temporary unavailability/configuration mistake would be very harmful to users. + ## The definition of "Job" in GitLab CI/CD "Job" in GitLab CI context refers a task to drive Continuous Integration, Delivery and Deployment. diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 6aedb18c15d..a8c527ad30e 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -201,7 +201,8 @@ by a reviewer before passing it to a maintainer as described in the on the line of code in question with the SQL queries so they can give their advice. 1. User-facing changes include both visual changes (regardless of how minor), and changes to the rendered DOM which impact how a screen reader may announce - the content. + the content. Groups that do not have dedicated Product + Designers do not require a Product Designer to approve feature changes, unless the changes are community contributions. 1. End-to-end changes include all files in the `qa` directory. #### Acceptance checklist @@ -605,7 +606,7 @@ When ready to merge: WARNING: **If the merge request is from a fork, also check the [additional guidelines for community contributions](#community-contributions).** -- Consider using the [Squash and merge](../user/project/merge_requests/squash_and_merge.md#squash-and-merge) +- Consider using the [Squash and merge](../user/project/merge_requests/squash_and_merge.md) feature when the merge request has a lot of commits. When merging code, a maintainer should only use the squash feature if the author has already set this option, or if the merge request clearly contains a @@ -624,7 +625,7 @@ WARNING: enough to `main`. - When you set the MR to auto-merge, you should take over subsequent revisions for anything that would be spotted after that. -- For merge requests that have had [Squash and merge](../user/project/merge_requests/squash_and_merge.md#squash-and-merge) set, +- For merge requests that have had [Squash and merge](../user/project/merge_requests/squash_and_merge.md) set, the squashed commit's default commit message is taken from the merge request title. You're encouraged to [select a commit with a more informative commit message](../user/project/merge_requests/squash_and_merge.md) before merging. diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index 58ec0de6074..59e35e658e7 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -61,7 +61,7 @@ Check these aspects both when _designing_ and _reviewing_ UI changes. ### Visual design -Check visual design properties using your browser's _elements inspector_ ([Chrome](https://developer.chrome.com/docs/devtools/css/), +Check visual design properties using your browser's elements inspector ([Chrome](https://developer.chrome.com/docs/devtools/css/), [Firefox](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/open_the_inspector/index.html)). - Use recommended [colors](https://design.gitlab.com/product-foundations/color) @@ -71,9 +71,11 @@ Check visual design properties using your browser's _elements inspector_ ([Chrom or propose new ones according to [iconography](https://design.gitlab.com/product-foundations/iconography/) and [illustration](https://design.gitlab.com/product-foundations/illustration/) guidelines. -- _Optionally_ consider [dark mode](../../user/profile/preferences.md#dark-mode). [^1] +- Optional: Consider dark mode. For more information, see [Change the syntax highlighting theme](../../user/profile/preferences.md#change-the-syntax-highlighting-theme). - [^1]: You're not required to design for [dark mode](../../user/profile/preferences.md#dark-mode) while the feature is an [Experiment](../../policy/experiment-beta-support.md#experiment). The [UX Foundations team](https://about.gitlab.com/direction/manage/foundations/) plans to improve the dark mode in the future. Until we integrate [Pajamas](https://design.gitlab.com/) components into the product and the underlying design strategy is in place to support dark mode, we cannot guarantee that we won't introduce bugs and debt to this mode. At your discretion, evaluate the need to create dark mode patches. +### Dark Mode + +You're not required to design for dark mode while the feature is an [Experiment](../../policy/experiment-beta-support.md#experiment). The [UX Foundations team](https://about.gitlab.com/direction/manage/foundations/) plans to improve the dark mode in the future. Until we integrate [Pajamas](https://design.gitlab.com/) components into the product and the underlying design strategy is in place to support dark mode, we cannot guarantee that we won't introduce bugs and debt to this mode. At your discretion, evaluate the need to create dark mode patches. ### States diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index b929a5c0f04..d2063a6836d 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -54,7 +54,7 @@ To write and test your code, you will use the GitLab Development Kit. - To run the development environment locally, download and set up the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit). See the [GDK README](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/README.md) for setup instructions - and [Troubleshooting](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/troubleshooting.md) if you get stuck. + and [Troubleshooting](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/troubleshooting/index.md) if you get stuck. - GDK is heavy. If you need to build something fast, by trial and error, consider doing so with an empty rails app and port it to GDK after. diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 50e87fc5341..228e7507777 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -7,6 +7,35 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Issues workflow +## Finding issues to work on + +GitLab has over 75,000 issues that you can work on. +You can use [labels](../../user/project/labels.md) to filter and find suitable issues to work on. +New contributors can look for [issues with the `quick win` label](https://gitlab.com/groups/gitlab-org/-/issues/?sort=created_asc&state=opened&label_name%5B%5D=quick%20win&first_page_size=20). + +The `frontend` and `backend` labels are also a good choice to refine the issue list. + +## Clarifying/validating an issue + +Many issues have not been visited or validated recently. +Before trying to solve an issue, take the following steps: + +- Ask the author if the issue is still relevant. +- Ask the community if the issue is still relevant. +- Attempt to validate whether: + - A merge request has already been created (see the related merge requests section). + Sometimes the issue is not closed/updated. + - The `type::bug` still exists (by recreating it). + - The `type::feature` has not already been implemented (by trying it). + +## Working on the issue + +Leave a note to indicate you wish to work on the issue and would like to be assigned +(mention the author and/or `@gitlab-org/coaches`). + +If you are stuck or did not properly understand the issue you can ask the author or +the community for help. + **Before you submit an issue, [search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues)** for similar entries. Someone else might have already had the same bug or feature proposal. If you find an existing issue, show your support with an emoji reaction and add your notes to the discussion. diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 7a0269e551d..12862cb0993 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -110,7 +110,7 @@ Commit messages should follow the guidelines below, for reasons explained by Chr **Important notes:** - If the guidelines are not met, the MR may not pass the [Danger checks](https://gitlab.com/gitlab-org/gitlab/-/blob/master/danger/commit_messages/Dangerfile). -- Consider enabling [Squash and merge](../../user/project/merge_requests/squash_and_merge.md#squash-and-merge) +- Consider enabling [Squash and merge](../../user/project/merge_requests/squash_and_merge.md) if your merge request includes "Applied suggestion to X files" commits, so that Danger can ignore those. - The prefixes in the form of `[prefix]` and `prefix:` are allowed (they can be all lowercase, as long as the message itself is capitalized). For instance, `danger: Improve Danger behavior` and @@ -172,7 +172,7 @@ the contribution acceptance criteria below: restarting the failing CI job, rebasing on top of target branch to bring in updates that may resolve the failure, or if it has not been fixed yet, ask a developer to help you fix the test. -1. The MR contains a few logically organized commits, or has [squashing commits enabled](../../user/project/merge_requests/squash_and_merge.md#squash-and-merge). +1. The MR contains a few logically organized commits, or has [squashing commits enabled](../../user/project/merge_requests/squash_and_merge.md). 1. The changes can merge without problems. If not, you should rebase if you're the only one working on your feature branch, otherwise merge the default branch into the MR branch. 1. Only one specific issue is fixed or one specific feature is implemented. Do not diff --git a/doc/development/database/avoiding_downtime_in_migrations.md b/doc/development/database/avoiding_downtime_in_migrations.md index 6a819e9f6cd..371df5b45ff 100644 --- a/doc/development/database/avoiding_downtime_in_migrations.md +++ b/doc/development/database/avoiding_downtime_in_migrations.md @@ -29,22 +29,23 @@ and upgrade processes for self-managed installations that lump together any of t ### Ignoring the column (release M) -The first step is to ignore the column in the application code. This step is -necessary because Rails caches the columns and re-uses this cache in various -places. This can be done by defining the columns to ignore. For example, to ignore +The first step is to ignore the column in the application code and remove all code references to it including +model validations. +This step is necessary because Rails caches the columns and re-uses this cache in various +places. This can be done by defining the columns to ignore. For example, in release `12.5`, to ignore `updated_at` in the User model you'd use the following: ```ruby class User < ApplicationRecord include IgnorableColumns - ignore_column :updated_at, remove_with: '12.7', remove_after: '2020-01-22' + ignore_column :updated_at, remove_with: '12.7', remove_after: '2019-12-22' end ``` Multiple columns can be ignored, too: ```ruby -ignore_columns %i[updated_at created_at], remove_with: '12.7', remove_after: '2020-01-22' +ignore_columns %i[updated_at created_at], remove_with: '12.7', remove_after: '2019-12-22' ``` If the model exists in CE and EE, the column has to be ignored in the CE model. If the @@ -52,21 +53,21 @@ model only exists in EE, then it has to be added there. We require indication of when it is safe to remove the column ignore rule with: -- `remove_with`: set to a GitLab release typically two releases (M+2) after adding the +- `remove_with`: set to a GitLab release typically two releases (M+2) (`12.7` in our example) after adding the column ignore. - `remove_after`: set to a date after which we consider it safe to remove the column - ignore, typically after the M+1 release date, during the M+2 development cycle. + ignore, typically after the M+1 release date, during the M+2 development cycle. For example, since the development cycle of `12.7` is between `2019-12-18` and `2020-01-17`, and `12.6` is the release to [drop the column](#dropping-the-column-release-m1), it's safe to set the date to the release date of `12.6` as `2019-12-22`. This information allows us to reason better about column ignores and makes sure we don't remove column ignores too early for both regular releases and deployments to GitLab.com. For example, this avoids a situation where we deploy a bulk of changes that include both changes to ignore the column and subsequently remove the column ignore (which would result in a downtime). -In this example, the change to ignore the column went into release 12.5. +In this example, the change to ignore the column went into release `12.5`. ### Dropping the column (release M+1) -Continuing our example, dropping the column goes into a _post-deployment_ migration in release 12.6: +Continuing our example, dropping the column goes into a _post-deployment_ migration in release `12.6`: Start by creating the **post-deployment migration**: @@ -135,7 +136,7 @@ for more information about database migrations. ### Removing the ignore rule (release M+2) -With the next release, in this example 12.7, we set up another merge request to remove the ignore rule. +With the next release, in this example `12.7`, we set up another merge request to remove the ignore rule. This removes the `ignore_column` line and - if not needed anymore - also the inclusion of `IgnoreableColumns`. This should only get merged with the release indicated with `remove_with` and once @@ -195,7 +196,7 @@ This step is similar to [the first step when column is dropped](#ignoring-the-co ```ruby class User < ApplicationRecord include IgnorableColumns - ignore_column :updated_at, remove_with: '12.7', remove_after: '2020-01-22' + ignore_column :updated_at, remove_with: '12.7', remove_after: '2019-12-22' end ``` diff --git a/doc/development/database/batched_background_migrations.md b/doc/development/database/batched_background_migrations.md index 1bdd24afcad..10490df7b5e 100644 --- a/doc/development/database/batched_background_migrations.md +++ b/doc/development/database/batched_background_migrations.md @@ -13,6 +13,13 @@ in our guidelines. For example, you can use batched background migrations to migrate data that's stored in a single JSON column to a separate table instead. +NOTE: +Batched background migrations replaced the legacy background migrations framework. +Check that documentation in reference to any changes involving that framework. + +NOTE: +The batched background migrations framework has ChatOps support. Using ChatOps, GitLab engineers can interact with the batched background migrations present in the system. + ## When to use batched background migrations Use a batched background migration when you migrate _data_ in tables containing @@ -201,6 +208,13 @@ models defined in `app/models` except the `ApplicationRecord` classes). Because these migrations can take a long time to run, it's possible for new versions to deploy while the migrations are still running. +### Depending on migrated data + +Unlike a regular or a post migration, waiting for the next release is not enough to guarantee that the data was fully migrated. +That means that you shouldn't depend on the data until the BBM is finished. If having 100% of the data migrated is a requirement, +then, the `ensure_batched_background_migration_is_finished` helper can be used to guarantee that the migration was finished and the +data fully migrated. ([See an example](https://gitlab.com/gitlab-org/gitlab/-/blob/41fbe34a4725a4e357a83fda66afb382828767b2/db/post_migrate/20210707210916_finalize_ci_stages_bigint_conversion.rb#L13-18)). + ## How to ### Generate a batched background migration @@ -538,6 +552,107 @@ Bumping the [import/export version](../../user/project/settings/import_export.md be required, if importing a project from a prior version of GitLab requires the data to be in the new format. +### Add indexes to support batched background migrations + +Sometimes it is necessary to add a new or temporary index to support a batched background migration. +To do this, create the index in a post-deployment migration that precedes the post-deployment +migration that queues the background migration. + +See the documentation for [adding database indexes](adding_database_indexes.md#analyzing-a-new-index-before-a-batched-background-migration) +for additional information about some cases that require special attention to allow the index to be used directly after +creation. + +### Execute a particular batch on the database testing pipeline + +NOTE: +Only [database maintainers](https://gitlab.com/groups/gitlab-org/maintainers/database/-/group_members?with_inherited_permissions=exclude) can view the database testing pipeline artifacts. Ask one for help if you need to use this method. + +Let's assume that a batched background migration failed on a particular batch on GitLab.com and you want to figure out which query failed and why. At the moment, we don't have a good way to retrieve query information (especially the query parameters) and rerunning the entire migration with more logging would be a long process. + +Fortunately you can leverage our [database migration pipeline](database_migration_pipeline.md) to rerun a particular batch with additional logging and/or fix to see if it solves the problem. + +For an example see [Draft: `Test PG::CardinalityViolation` fix](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110910) but make sure to read the entire section. + +To do that, you need to: + +1. [Find the batch `start_id` and `end_id`](#find-the-batch-start_id-and-end_id) +1. [Create a regular migration](#create-a-regular-migration) +1. [Apply a workaround for our migration helpers](#apply-a-workaround-for-our-migration-helpers-optional) (optional) +1. [Start the database migration pipeline](#start-the-database-migration-pipeline) + +#### Find the batch `start_id` and `end_id` + +You should be able to find those in [Kibana](#viewing-failure-error-logs). + +#### Create a regular migration + +Schedule the batch in the `up` block of a regular migration: + +```ruby +def up + instance = Gitlab::BackgroundMigration::YourBackgroundMigrationClass.new( + start_id: <batch start_id>, + end_id: <batch end_id>, + batch_table: <table name>, + batch_column: <batching column>, + sub_batch_size: <sub batch size>, + pause_ms: <miliseconds between batches>, + job_arguments: <job arguments if any>, + connection: connection + ) + + instance.perform +end + +def down + # no-op +end +``` + +#### Apply a workaround for our migration helpers (optional) + +If your batched background migration touches tables from a schema other than the one you specified by using `restrict_gitlab_migration` helper (example: the scheduling migration has `restrict_gitlab_migration gitlab_schema: :gitlab_main` but the background job uses tables from the `:gitlab_ci` schema) then the migration will fail. To prevent that from happening you must to monkey patch database helpers so they don't fail the testing pipeline job: + +1. Add the schema names to [`RestrictGitlabSchema`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/migration_helpers/restrict_gitlab_schema.rb#L57) + +```diff +diff --git a/lib/gitlab/database/migration_helpers/restrict_gitlab_schema.rb b/lib/gitlab/database/migration_helpers/restrict_gitlab_schema.rb +index b8d1d21a0d2d2a23d9e8c8a0a17db98ed1ed40b7..912e20659a6919f771045178c66828563cb5a4a1 100644 +--- a/lib/gitlab/database/migration_helpers/restrict_gitlab_schema.rb ++++ b/lib/gitlab/database/migration_helpers/restrict_gitlab_schema.rb +@@ -55,7 +55,7 @@ def unmatched_schemas + end + + def allowed_schemas_for_connection +- Gitlab::Database.gitlab_schemas_for_connection(connection) ++ Gitlab::Database.gitlab_schemas_for_connection(connection) << :gitlab_ci + end + end + end +``` + +1. Add the schema names to [`RestrictAllowedSchemas`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb#L82) + +```diff +diff --git a/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb b/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb +index 4ae3622479f0800c0553959e132143ec9051898e..d556ec7f55adae9d46a56665ce02de782cb09f2d 100644 +--- a/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb ++++ b/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb +@@ -79,7 +79,7 @@ def restrict_to_dml_only(parsed) + tables = self.dml_tables(parsed) + schemas = self.dml_schemas(tables) + +- if (schemas - self.allowed_gitlab_schemas).any? ++ if (schemas - (self.allowed_gitlab_schemas << :gitlab_ci)).any? + raise DMLAccessDeniedError, \ + "Select/DML queries (SELECT/UPDATE/DELETE) do access '#{tables}' (#{schemas.to_a}) " \ + "which is outside of list of allowed schemas: '#{self.allowed_gitlab_schemas}'. " \ +``` + +#### Start the database migration pipeline + +Create a Draft merge request with your changes and trigger the manual `db:gitlabcom-database-testing` job. + ## Managing NOTE: @@ -683,22 +798,109 @@ migration is scheduled in the GitLab FOSS context. You can use the [generator](#generate-a-batched-background-migration) to generate an EE-only migration scaffold by passing `--ee-only` flag when generating a new batched background migration. -## Throttling batched migrations +## Debug + +### Viewing failure error logs -Because batched migrations are update-heavy and there were few incidents in the past because of the heavy load from migrations while the database was underperforming, a throttling mechanism exists to mitigate them. +You can view failures in two ways: -These database indicators are checked to throttle a migration. On getting a -stop signal, the migration is paused for a set time (10 minutes): +- Via GitLab logs: + 1. After running a batched background migration, if any jobs fail, + view the logs in [Kibana](https://log.gprd.gitlab.net/goto/4cb43f40-f861-11ec-b86b-d963a1a6788e). + View the production Sidekiq log and filter for: -- WAL queue pending archival crossing a threshold. -- Active autovacuum on the tables on which the migration works on. -- Patroni apdex SLI dropping below the SLO. + - `json.new_state: failed` + - `json.job_class_name: <Batched Background Migration job class name>` + - `json.job_arguments: <Batched Background Migration job class arguments>` -It's an ongoing effort to add more indicators to further enhance the -database health check framework. For more details, see -[epic 7594](https://gitlab.com/groups/gitlab-org/-/epics/7594). + 1. Review the `json.exception_class` and `json.exception_message` values to help + understand why the jobs failed. + + 1. Remember the retry mechanism. Having a failure does not mean the job failed. + Always check the last status of the job. + +- Via database: + + 1. Get the batched background migration `CLASS_NAME`. + 1. Execute the following query in the PostgreSQL console: + + ```sql + SELECT migration.id, migration.job_class_name, transition_logs.exception_class, transition_logs.exception_message + FROM batched_background_migrations as migration + INNER JOIN batched_background_migration_jobs as jobs + ON jobs.batched_background_migration_id = migration.id + INNER JOIN batched_background_migration_job_transition_logs as transition_logs + ON transition_logs.batched_background_migration_job_id = jobs.id + WHERE transition_logs.next_status = '2' AND migration.job_class_name = "CLASS_NAME"; + ``` + +## Testing + +Writing tests is required for: + +- The batched background migrations' queueing migration. +- The batched background migration itself. +- A cleanup migration. + +The `:migration` and `schema: :latest` RSpec tags are automatically set for +background migration specs. Refer to the +[Testing Rails migrations](../testing_guide/testing_migrations_guide.md#testing-a-non-activerecordmigration-class) +style guide. + +Remember that `before` and `after` RSpec hooks +migrate your database down and up. These hooks can result in other batched background +migrations being called. Using `spy` test doubles with +`have_received` is encouraged, instead of using regular test doubles, because +your expectations defined in a `it` block can conflict with what is +called in RSpec hooks. Refer to [issue #35351](https://gitlab.com/gitlab-org/gitlab/-/issues/18839) +for more details. + +## Best practices + +1. Know how much data you're dealing with. +1. Make sure the batched background migration jobs are idempotent. +1. Confirm the tests you write are not false positives. +1. If the data being migrated is critical and cannot be lost, the + clean-up migration must also check the final state of the data before completing. +1. Discuss the numbers with a database specialist. The migration may add + more pressure on DB than you expect. Measure on staging, + or ask someone to measure on production. +1. Know how much time is required to run the batched background migration. +1. Be careful when silently rescuing exceptions inside job classes. This may lead to + jobs being marked as successful, even in a failure scenario. + + ```ruby + # good + def perform + each_sub_batch do |sub_batch| + sub_batch.update_all(name: 'My Name') + end + end + + # acceptable + def perform + each_sub_batch do |sub_batch| + sub_batch.update_all(name: 'My Name') + rescue Exception => error + logger.error(message: error.message, class: error.class) + + raise + end + end + + # bad + def perform + each_sub_batch do |sub_batch| + sub_batch.update_all(name: 'My Name') + rescue Exception => error + logger.error(message: error.message, class: self.class.name) + end + end + ``` + +## Examples -## Example +### Routes use-case The `routes` table has a `source_type` field that's used for a polymorphic relationship. As part of a database redesign, we're removing the polymorphic relationship. One step of @@ -867,216 +1069,3 @@ background migration. After the batched migration is completed, you can safely depend on the data in `routes.namespace_id` being populated. - -## Testing - -Writing tests is required for: - -- The batched background migrations' queueing migration. -- The batched background migration itself. -- A cleanup migration. - -The `:migration` and `schema: :latest` RSpec tags are automatically set for -background migration specs. Refer to the -[Testing Rails migrations](../testing_guide/testing_migrations_guide.md#testing-a-non-activerecordmigration-class) -style guide. - -Remember that `before` and `after` RSpec hooks -migrate your database down and up. These hooks can result in other batched background -migrations being called. Using `spy` test doubles with -`have_received` is encouraged, instead of using regular test doubles, because -your expectations defined in a `it` block can conflict with what is -called in RSpec hooks. Refer to [issue #35351](https://gitlab.com/gitlab-org/gitlab/-/issues/18839) -for more details. - -## Best practices - -1. Know how much data you're dealing with. -1. Make sure the batched background migration jobs are idempotent. -1. Confirm the tests you write are not false positives. -1. If the data being migrated is critical and cannot be lost, the - clean-up migration must also check the final state of the data before completing. -1. Discuss the numbers with a database specialist. The migration may add - more pressure on DB than you expect. Measure on staging, - or ask someone to measure on production. -1. Know how much time is required to run the batched background migration. -1. Be careful when silently rescuing exceptions inside job classes. This may lead to - jobs being marked as successful, even in a failure scenario. - - ```ruby - # good - def perform - each_sub_batch do |sub_batch| - sub_batch.update_all(name: 'My Name') - end - end - - # acceptable - def perform - each_sub_batch do |sub_batch| - sub_batch.update_all(name: 'My Name') - rescue Exception => error - logger.error(message: error.message, class: error.class) - - raise - end - end - - # bad - def perform - each_sub_batch do |sub_batch| - sub_batch.update_all(name: 'My Name') - rescue Exception => error - logger.error(message: error.message, class: self.class.name) - end - end - ``` - -## Additional tips and strategies - -### ChatOps integration - -The batched background migrations framework has ChatOps support. Using ChatOps, GitLab engineers can interact with the batched background migrations present in the system. - -### Viewing failure error logs - -You can view failures in two ways: - -- Via GitLab logs: - 1. After running a batched background migration, if any jobs fail, - view the logs in [Kibana](https://log.gprd.gitlab.net/goto/4cb43f40-f861-11ec-b86b-d963a1a6788e). - View the production Sidekiq log and filter for: - - - `json.new_state: failed` - - `json.job_class_name: <Batched Background Migration job class name>` - - `json.job_arguments: <Batched Background Migration job class arguments>` - - 1. Review the `json.exception_class` and `json.exception_message` values to help - understand why the jobs failed. - - 1. Remember the retry mechanism. Having a failure does not mean the job failed. - Always check the last status of the job. - -- Via database: - - 1. Get the batched background migration `CLASS_NAME`. - 1. Execute the following query in the PostgreSQL console: - - ```sql - SELECT migration.id, migration.job_class_name, transition_logs.exception_class, transition_logs.exception_message - FROM batched_background_migrations as migration - INNER JOIN batched_background_migration_jobs as jobs - ON jobs.batched_background_migration_id = migration.id - INNER JOIN batched_background_migration_job_transition_logs as transition_logs - ON transition_logs.batched_background_migration_job_id = jobs.id - WHERE transition_logs.next_status = '2' AND migration.job_class_name = "CLASS_NAME"; - ``` - -### Executing a particular batch on the database testing pipeline - -NOTE: -Only [database maintainers](https://gitlab.com/groups/gitlab-org/maintainers/database/-/group_members?with_inherited_permissions=exclude) can view the database testing pipeline artifacts. Ask one for help if you need to use this method. - -Let's assume that a batched background migration failed on a particular batch on GitLab.com and you want to figure out which query failed and why. At the moment, we don't have a good way to retrieve query information (especially the query parameters) and rerunning the entire migration with more logging would be a long process. - -Fortunately you can leverage our [database migration pipeline](database_migration_pipeline.md) to rerun a particular batch with additional logging and/or fix to see if it solves the problem. - -<!-- vale gitlab.Substitutions = NO --> - -For an example see [Draft: Test PG::CardinalityViolation fix](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110910) but make sure to read the entire section. - -To do that, you need to: - -1. Find the batch `start_id` and `end_id` -1. Create a regular migration -1. Apply a workaround for our migration helpers (optional) -1. Start the database migration pipeline - -#### 1. Find the batch `start_id` and `end_id` - -You should be able to find those in [Kibana](#viewing-failure-error-logs). - -#### 2. Create a regular migration - -Schedule the batch in the `up` block of a regular migration: - -```ruby -def up - instance = Gitlab::BackgroundMigration::YourBackgroundMigrationClass.new( - start_id: <batch start_id>, - end_id: <batch end_id>, - batch_table: <table name>, - batch_column: <batching column>, - sub_batch_size: <sub batch size>, - pause_ms: <miliseconds between batches>, - job_arguments: <job arguments if any>, - connection: connection - ) - - instance.perform -end - - -def down - # no-op -end -``` - -#### 3. Apply a workaround for our migration helpers (optional) - -If your batched background migration touches tables from a schema other than the one you specified by using `restrict_gitlab_migration` helper (example: the scheduling migration has `restrict_gitlab_migration gitlab_schema: :gitlab_main` but the background job uses tables from the `:gitlab_ci` schema) then the migration will fail. To prevent that from happening you must to monkey patch database helpers so they don't fail the testing pipeline job: - -1. Add the schema names to [`RestrictGitlabSchema`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/migration_helpers/restrict_gitlab_schema.rb#L57) - -```diff -diff --git a/lib/gitlab/database/migration_helpers/restrict_gitlab_schema.rb b/lib/gitlab/database/migration_helpers/restrict_gitlab_schema.rb -index b8d1d21a0d2d2a23d9e8c8a0a17db98ed1ed40b7..912e20659a6919f771045178c66828563cb5a4a1 100644 ---- a/lib/gitlab/database/migration_helpers/restrict_gitlab_schema.rb -+++ b/lib/gitlab/database/migration_helpers/restrict_gitlab_schema.rb -@@ -55,7 +55,7 @@ def unmatched_schemas - end - - def allowed_schemas_for_connection -- Gitlab::Database.gitlab_schemas_for_connection(connection) -+ Gitlab::Database.gitlab_schemas_for_connection(connection) << :gitlab_ci - end - end - end -``` - -1. Add the schema names to [`RestrictAllowedSchemas`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb#L82) - -```diff -diff --git a/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb b/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb -index 4ae3622479f0800c0553959e132143ec9051898e..d556ec7f55adae9d46a56665ce02de782cb09f2d 100644 ---- a/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb -+++ b/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb -@@ -79,7 +79,7 @@ def restrict_to_dml_only(parsed) - tables = self.dml_tables(parsed) - schemas = self.dml_schemas(tables) - -- if (schemas - self.allowed_gitlab_schemas).any? -+ if (schemas - (self.allowed_gitlab_schemas << :gitlab_ci)).any? - raise DMLAccessDeniedError, \ - "Select/DML queries (SELECT/UPDATE/DELETE) do access '#{tables}' (#{schemas.to_a}) " \ - "which is outside of list of allowed schemas: '#{self.allowed_gitlab_schemas}'. " \ -``` - -#### 4. Start the database migration pipeline - -Create a Draft merge request with your changes and trigger the manual `db:gitlabcom-database-testing` job. - -### Adding indexes to support batched background migrations - -Sometimes it is necessary to add a new or temporary index to support a batched background migration. -To do this, create the index in a post-deployment migration that precedes the post-deployment -migration that queues the background migration. - -See the documentation for [adding database indexes](adding_database_indexes.md#analyzing-a-new-index-before-a-batched-background-migration) -for additional information about some cases that require special attention to allow the index to be used directly after -creation. - -## Legacy background migrations - -Batched background migrations replaced the legacy background migrations framework. -Check that documentation in reference to any changes involving that framework. diff --git a/doc/development/database/database_lab.md b/doc/development/database/database_lab.md index 357133d8bca..7edb8ab4de5 100644 --- a/doc/development/database/database_lab.md +++ b/doc/development/database/database_lab.md @@ -146,13 +146,13 @@ the `pgai` Gem: 1. To get started, you need to gather some values from the [Postgres.ai instances page](https://console.postgres.ai/gitlab/instances): - 1. Navigate to the instance that you want to configure and the on right side of the screen. + 1. Go to the instance that you want to configure and the on right side of the screen. 1. Under **Connection**, select **Connect**. The menu might be collapsed. - A pop-up with everything that's needed for configuration appears, using this format: + A dialog with everything that's needed for configuration appears, using this format: ```shell - dblab init --url http://127.0.0.1:1234 --token TOKEN --environment-id <environment-id> + dblab init --url "http://127.0.0.1:1234" --token TOKEN --environment-id <environment-id> ``` ```shell diff --git a/doc/development/database/database_migration_pipeline.md b/doc/development/database/database_migration_pipeline.md index a9d525e2a41..280254d90b0 100644 --- a/doc/development/database/database_migration_pipeline.md +++ b/doc/development/database/database_migration_pipeline.md @@ -44,6 +44,13 @@ The next section of the comment contains detailed information for each migration calls, timings, and the number of the changed rows. - **Runtime histogram** - Indicates the distribution of query times for the migration. +### Database size increase + +Occasionally, a migration shows a +8.00 KiB size increase, even if the migration was not +expected to result in a size increase. Completing any migration adds a row to the +`schema_migrations` table, which may require a new disk page to be created. +If a new disk page is created, the size of the database will grow by exactly 8 KiB. + ## Background migration details The next section of the comment contains detailed information about each batched background migration, including: diff --git a/doc/development/database/database_reviewer_guidelines.md b/doc/development/database/database_reviewer_guidelines.md index c297c90918f..c75503c503b 100644 --- a/doc/development/database/database_reviewer_guidelines.md +++ b/doc/development/database/database_reviewer_guidelines.md @@ -68,8 +68,8 @@ The following guides provide a quick introduction and links to follow on more ad - Guide on [understanding EXPLAIN plans](understanding_explain_plans.md). - [Explaining the unexplainable series in `depesz`](https://www.depesz.com/tag/unexplainable/). -We also have licensed access to The Art of PostgreSQL. If you are interested in getting access, check out the -[issue (confidential)](https://gitlab.com/gitlab-org/database-team/team-tasks/-/issues/23). +We also have licensed access to The Art of PostgreSQL. If you are interested in getting access, GitLab team +members can check out the issue here: `https://gitlab.com/gitlab-org/database-team/team-tasks/-/issues/23`. Finally, you can find various guides in the [Database guides](index.md) page that cover more specific topics and use cases. The most frequently required during database reviewing are the following: diff --git a/doc/development/database/efficient_in_operator_queries.md b/doc/development/database/efficient_in_operator_queries.md index a0c71f49e2d..87976df5711 100644 --- a/doc/development/database/efficient_in_operator_queries.md +++ b/doc/development/database/efficient_in_operator_queries.md @@ -228,9 +228,6 @@ Gitlab::Pagination::Keyset::InOperatorOptimization::QueryBuilder.new( If it's not given, the `IN` operator optimization only makes the `ORDER BY` columns available to the end-user and not the full database row. - If it's not given, the `IN` operator optimization only makes the `ORDER BY` columns available to - the end-user and not the full database row. - The following database index on the `issues` table must be present to make the query execute efficiently: diff --git a/doc/development/database/iterating_tables_in_batches.md b/doc/development/database/iterating_tables_in_batches.md index a927242e8d8..84b82b16255 100644 --- a/doc/development/database/iterating_tables_in_batches.md +++ b/doc/development/database/iterating_tables_in_batches.md @@ -135,11 +135,24 @@ Let's consider that we want to iterate over the `users` table and print the `Use standard output. The `users` table contains millions of records, thus running one query to fetch the users likely times out. - - -This is a simplified version of the `users` table which contains several rows. We have a few +This table is a simplified version of the `users` table which contains several rows. We have a few smaller gaps in the `id` column to make the example a bit more realistic (a few records were -already deleted). Currently, we have one index on the `id` field. +already deleted). One index exists on the `id` field: + +| `ID` | `sign_in_count` | `created_at` | +| -- | :-------------: | ------------ | +| 1 | 1 | 2020-01-01 +| 2 | 4 | 2020-01-01 +| 9 | 1 | 2020-01-03 +| 300 | 5 | 2020-01-03 +| 301 | 9 | 2020-01-03 +| 302 | 8 | 2020-01-03 +| 303 | 2 | 2020-01-03 +| 350 | 1 | 2020-01-03 +| 351 | 3 | 2020-01-04 +| 352 | 0 | 2020-01-05 +| 353 | 9 | 2020-01-11 +| 354 | 3 | 2020-01-12 Loading all users into memory (avoid): diff --git a/doc/development/database/multiple_databases.md b/doc/development/database/multiple_databases.md index 7c6b94144b4..7037ab22983 100644 --- a/doc/development/database/multiple_databases.md +++ b/doc/development/database/multiple_databases.md @@ -163,6 +163,92 @@ allows you to avoid the join, while still avoiding the N+1 query. You can see a real example of this solution being used in <https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67655>. +##### Remove a redundant join + +Sometimes there are cases where a query is doing excess (or redundant) joins. + +A common example occurs where a query is joining from `A` to `C`, via some +table with both foreign keys, `B`. +When you only care about counting how +many rows there are in `C` and if there are foreign keys and `NOT NULL` constraints +on the foreign keys in `B`, then it might be enough to count those rows. +For example, in +[MR 71811](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71811), it was +previously doing `project.runners.count`, which would produce a query like: + +```sql +select count(*) from projects +inner join ci_runner_projects on ci_runner_projects.project_id = projects.id +where ci_runner_projects.runner_id IN (1, 2, 3) +``` + +This was changed to avoid the cross-join by changing the code to +`project.runner_projects.count`. It produces the same response with the +following query: + +```sql +select count(*) from ci_runner_projects +where ci_runner_projects.runner_id IN (1, 2, 3) +``` + +Another common redundant join is joining all the way to another table, +then filtering by primary key when you could have instead filtered on a foreign +key. See an example in +[MR 71614](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71614). The previous +code was `joins(scan: :build).where(ci_builds: { id: build_ids })`, which +generated a query like: + +```sql +select ... +inner join security_scans +inner join ci_builds on security_scans.build_id = ci_builds.id +where ci_builds.id IN (1, 2, 3) +``` + +However, as `security_scans` already has a foreign key `build_id`, the code +can be changed to `joins(:scan).where(security_scans: { build_id: build_ids })`, +which produces the same response with the following query: + +```sql +select ... +inner join security_scans +where security_scans.build_id IN (1, 2, 3) +``` + +Both of these examples of removing redundant joins remove the cross-joins, +but they have the added benefit of producing simpler and faster +queries. + +##### Limited pluck followed by a find + +Using `pluck` or `pick` to get an array of `id`s is not advisable unless the returned +array is guaranteed to be bounded in size. Usually this is a good pattern where +you know the result will be at most 1, or in cases where you have a list of in +memory ids (or usernames) that need to be mapped to another list of equal size. +It would not be suitable when mapping a list of ids in a one-to-many +relationship as the result will be unbounded. We can then use the +returned `id`s to obtain the related record: + +```ruby +allowed_user_id = board_user_finder + .where(user_id: params['assignee_id']) + .pick(:user_id) + +User.find_by(id: allowed_user_id) +``` + +You can see an example where this was used in +<https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126856> + +Sometimes it might seem easy to convert a join into a `pluck` but often this +results in loading an unbounded amount of ids into memory and then +re-serializing those in a following query back to Postgres. These cases do not +scale and we recommend attempting one of the other options. It might seem like a +good idea to just apply some `limit` to the plucked data to have bounded memory +but this introduces unpredictable results for users and often is most +problematic for our largest customers (including ourselves), and as such we +advise against it. + ##### De-normalize some foreign key to the table De-normalization refers to adding redundant precomputed (duplicated) data to @@ -263,62 +349,6 @@ logic to delete these rows if or whenever necessary in your domain. Finally, this de-normalization and new query also improves performance because it does less joins and needs less filtering. -##### Remove a redundant join - -Sometimes there are cases where a query is doing excess (or redundant) joins. - -A common example occurs where a query is joining from `A` to `C`, via some -table with both foreign keys, `B`. -When you only care about counting how -many rows there are in `C` and if there are foreign keys and `NOT NULL` constraints -on the foreign keys in `B`, then it might be enough to count those rows. -For example, in -[MR 71811](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71811), it was -previously doing `project.runners.count`, which would produce a query like: - -```sql -select count(*) from projects -inner join ci_runner_projects on ci_runner_projects.project_id = projects.id -where ci_runner_projects.runner_id IN (1, 2, 3) -``` - -This was changed to avoid the cross-join by changing the code to -`project.runner_projects.count`. It produces the same response with the -following query: - -```sql -select count(*) from ci_runner_projects -where ci_runner_projects.runner_id IN (1, 2, 3) -``` - -Another common redundant join is joining all the way to another table, -then filtering by primary key when you could have instead filtered on a foreign -key. See an example in -[MR 71614](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71614). The previous -code was `joins(scan: :build).where(ci_builds: { id: build_ids })`, which -generated a query like: - -```sql -select ... -inner join security_scans -inner join ci_builds on security_scans.build_id = ci_builds.id -where ci_builds.id IN (1, 2, 3) -``` - -However, as `security_scans` already has a foreign key `build_id`, the code -can be changed to `joins(:scan).where(security_scans: { build_id: build_ids })`, -which produces the same response with the following query: - -```sql -select ... -inner join security_scans -where security_scans.build_id IN (1, 2, 3) -``` - -Both of these examples of removing redundant joins remove the cross-joins, -but they have the added benefit of producing simpler and faster -queries. - ##### Use `disable_joins` for `has_one` or `has_many` `through:` relations Sometimes a join query is caused by using `has_one ... through:` or `has_many @@ -628,3 +658,56 @@ If this task was run against a GitLab setup that uses only a single database for both `gitlab_main` and `gitlab_ci` tables, then no tables will be locked. To undo the operation, run the opposite Rake task: `gitlab:db:unlock_writes`. + +## Truncating tables + +When the databases `main` and `ci` are fully split, we can free up disk +space by truncating tables. This results in a smaller data set: For example, +the data in `users` table on CI database is no longer read and also no +longer updated. So this data can be removed by truncating the tables. + +For this purpose, GitLab provides two Rake tasks, one for each database: + +- `gitlab:db:truncate_legacy_tables:main` will truncate the CI tables in Main database. +- `gitlab:db:truncate_legacy_tables:ci` will truncate the Main tables in CI database. + +NOTE: +These tasks can only be run when the tables in the database are +[locked for writes](#locking-writes-on-the-tables-that-dont-belong-to-the-database-schemas). + +WARNING: +The examples in this section use `DRY_RUN=true`. This ensures no data is actually +truncated. GitLab highly recommends to have a backup available before you run any of +these tasks without `DRY_RUN=true`. + +These tasks have the option to see what they do without actually changing the +data: + +```shell +$ sudo DRY_RUN=true gitlab-rake gitlab:db:truncate_legacy_tables:main +I, [2023-07-14T17:08:06.665151 #92505] INFO -- : DRY RUN: +I, [2023-07-14T17:08:06.761586 #92505] INFO -- : Truncating legacy tables for the database main +I, [2023-07-14T17:08:06.761709 #92505] INFO -- : SELECT set_config('lock_writes.ci_build_needs', 'false', false) +I, [2023-07-14T17:08:06.765272 #92505] INFO -- : SELECT set_config('lock_writes.ci_build_pending_states', 'false', false) +I, [2023-07-14T17:08:06.768220 #92505] INFO -- : SELECT set_config('lock_writes.ci_build_report_results', 'false', false) +[...] +I, [2023-07-14T17:08:06.957294 #92505] INFO -- : TRUNCATE TABLE ci_build_needs, ci_build_pending_states, ci_build_report_results, ci_build_trace_chunks, ci_build_trace_metadata, ci_builds, ci_builds_metadata, ci_builds_runner_session, ci_cost_settings, ci_daily_build_group_report_results, ci_deleted_objects, ci_editor_ai_conversation_messages, ci_freeze_periods, ci_group_variables, ci_instance_variables, ci_job_artifact_states, ci_job_artifacts, ci_job_token_project_scope_links, ci_job_variables, ci_minutes_additional_packs, ci_namespace_mirrors, ci_namespace_monthly_usages, ci_partitions, ci_pending_builds, ci_pipeline_artifacts, ci_pipeline_chat_data, ci_pipeline_messages, ci_pipeline_metadata, ci_pipeline_schedule_variables, ci_pipeline_schedules, ci_pipeline_variables, ci_pipelines, ci_pipelines_config, ci_platform_metrics, ci_project_mirrors, ci_project_monthly_usages, ci_refs, ci_resource_groups, ci_resources, ci_runner_machines, ci_runner_namespaces, ci_runner_projects, ci_runner_versions, ci_runners, ci_running_builds, ci_secure_file_states, ci_secure_files, ci_sources_pipelines, ci_sources_projects, ci_stages, ci_subscriptions_projects, ci_trigger_requests, ci_triggers, ci_unit_test_failures, ci_unit_tests, ci_variables, external_pull_requests, p_ci_builds, p_ci_builds_metadata, p_ci_job_annotations, p_ci_runner_machine_builds, taggings, tags RESTRICT +``` + +The tasks will first find out the tables that need to be truncated. Truncation will +happen in stages because we need to limit the amount of data removed in one database +transaction. The tables are processed in a specific order depending on the definition +of the foreign keys. The number of tables processed in one stage can be changed by +adding a number when invoking the task. The default value is 5: + +```shell +sudo DRY_RUN=true gitlab-rake gitlab:db:truncate_legacy_tables:main\[10\] +``` + +It is also possible to limit the number of tables to be truncated by setting the `UNTIL_TABLE` +variable. For example in this case, the process will stop when `ci_unit_test_failures` has been +truncated: + +```shell +sudo DRY_RUN=true UNTIL_TABLE=ci_unit_test_failures gitlab-rake gitlab:db:truncate_legacy_tables:main +``` diff --git a/doc/development/database/not_null_constraints.md b/doc/development/database/not_null_constraints.md index 2b10e440799..e1b6868c68e 100644 --- a/doc/development/database/not_null_constraints.md +++ b/doc/development/database/not_null_constraints.md @@ -63,9 +63,10 @@ The steps required are: 1. Release `N.M` (current release) - - Ensure the constraint is enforced at the application level (that is, add a model validation). - - Add a post-deployment migration to add the `NOT NULL` constraint with `validate: false`. - - Add a post-deployment migration to fix the existing records. + 1. Ensure $ATTRIBUTE value is being set at the application level. + 1. If the attribute has a default value, add the default value to the model so the default value is set for new records. + 1. Update all places in the code where the attribute is being set to `nil`, if any, for new and existing records. + 1. Add a post-deployment migration to fix the existing records. NOTE: Depending on the size of the table, a background migration for cleanup could be required in the next release. @@ -75,22 +76,16 @@ The steps required are: 1. Release `N.M+1` (next release) - - Validate the `NOT NULL` constraint using a post-deployment migration. + 1. Make sure all existing records on GitLab.com have attribute set. If not, go back to step 1 from Release `N.M`. + 1. If step 1 seems fine and the backfill from Release `N.M` was done via a batched background migration then add a + post-deployment migration to + [finalize the background migration](batched_background_migrations.md#depending-on-migrated-data). + 1. Add a validation for the attribute in the model to prevent records with `nil` attribute as now all existing and new records should be valid. + 1. Add a post-deployment migration to add the `NOT NULL` constraint. ### Example -Considering a given release milestone, such as 13.0, a model validation has been added into `epic.rb` -to require a description: - -```ruby -class Epic < ApplicationRecord - validates :description, presence: true -end -``` - -The same constraint should be added at the database level for consistency purposes. -We only want to enforce the `NOT NULL` constraint without setting a default, as we have decided -that all epics should have a user-generated description. +Considering a given release milestone, such as 13.0. After checking our production database, we know that there are `epics` with `NULL` descriptions, so we cannot add and validate the constraint in one step. @@ -101,33 +96,16 @@ such records, so we would follow the same process either way. #### Prevent new invalid records (current release) -We first add the `NOT NULL` constraint with a `NOT VALID` parameter, which enforces consistency -when new records are inserted or current records are updated. - -In the example above, the existing epics with a `NULL` description are not affected and you are -still able to update records in the `epics` table. However, when you try to update or insert -an epic without providing a description, the constraint causes a database error. - -Adding or removing a `NOT NULL` clause requires that any application changes are deployed _first_. -Thus, adding a `NOT NULL` constraint to an existing column should happen in a post-deployment migration. +Update all the code paths where the attribute is being set to `nil`, if any, to set the attribute to non-nil value +for new and existing records. -Still in our example, for the 13.0 milestone example (current), we add the `NOT NULL` constraint -with `validate: false` in a post-deployment migration, -`db/post_migrate/20200501000001_add_not_null_constraint_to_epics_description.rb`: +An attribute with default using the +[Rails attributes API](https://api.rubyonrails.org/classes/ActiveRecord/Attributes/ClassMethods.html) has been added in +`epic.rb` so that default value is set for new records: ```ruby -class AddNotNullConstraintToEpicsDescription < Gitlab::Database::Migration[2.1] - disable_ddl_transaction! - - def up - # This will add the `NOT NULL` constraint WITHOUT validating it - add_not_null_constraint :epics, :description, validate: false - end - - def down - # Down is required as `add_not_null_constraint` is not reversible - remove_not_null_constraint :epics, :description - end +class Epic < ApplicationRecord + attribute :description, default: 'No description' end ``` @@ -176,24 +154,47 @@ class CleanupEpicsWithNullDescription < Gitlab::Database::Migration[2.1] end ``` -#### Validate the `NOT NULL` constraint (next release) +#### Check if all records are fixed (next release) + +Use postgres.ai to [create a thin clone](https://about.gitlab.com/handbook/engineering/development/enablement/data_stores/database/doc/gitlab-com-database.html#use-postgresai-to-work-with-a-thin-clone-of-the-database-includes-direct-psql-access-to-the-thin-clone) +of the production database and check if all records on GitLab.com have the attribute set. +If not go back to [Prevent new invalid records](#prevent-new-invalid-records-current-release) step and figure out where +in the code the attribute is explicitly set to `nil`. Fix the code path then reschedule the migration to fix the existing +records and wait for the next release to do the following steps. + +#### Finalize the background migration (next release) + +If the migration was done using a background migration then [finalize the migration](batched_background_migrations.md#depending-on-migrated-data). -Validating the `NOT NULL` constraint scans the whole table and make sure that each record is correct. +#### Add validation to the model (next release) -Still in our example, for the 13.1 milestone (next), we run the `validate_not_null_constraint` -migration helper in a final post-deployment migration, -`db/post_migrate/20200601000001_validate_not_null_constraint_on_epics_description.rb`: +Add a validation for the attribute to the model to prevent records with `nil` attribute as now all existing and new records should be valid. ```ruby -class ValidateNotNullConstraintOnEpicsDescription < Gitlab::Database::Migration[2.1] +class Epic < ApplicationRecord + validates :description, presence: true +end +``` + +#### Add the `NOT NULL` constraint (next release) + +Adding the `NOT NULL` constraint scans the whole table and make sure that each record is correct. + +Still in our example, for the 13.1 milestone (next), we run the `add_not_null_constraint` +migration helper in a final post-deployment migration: + +```ruby +class AddNotNullConstraintToEpicsDescription < Gitlab::Database::Migration[2.1] disable_ddl_transaction! def up - validate_not_null_constraint :epics, :description + # This will add the `NOT NULL` constraint and validate it + add_not_null_constraint :epics, :description end def down - # no-op + # Down is required as `add_not_null_constraint` is not reversible + remove_not_null_constraint :epics, :description end end ``` diff --git a/doc/development/database/pagination_guidelines.md b/doc/development/database/pagination_guidelines.md index d6550d0a515..8b07dcada05 100644 --- a/doc/development/database/pagination_guidelines.md +++ b/doc/development/database/pagination_guidelines.md @@ -218,7 +218,9 @@ We can argue that a typical user does not visit these pages, however, API users ### Keyset pagination -Keyset pagination addresses the performance concerns of "skipping" previous rows when requesting a large page, however, it's not a drop-in replacement for offset-based pagination. Keyset pagination is used only in the [GraphQL API](../graphql_guide/pagination.md) +Keyset pagination addresses the performance concerns of "skipping" previous rows when requesting a large page, however, it's not a drop-in replacement for offset-based pagination. When moving an API endpoint from offset-based pagination to keyset-based pagination, both must be supported. Removing one type of pagination entirely is a [breaking changes](../../update/terminology.md#breaking-change). + +Keyset pagination used in both the [GraphQL API](../graphql_guide/pagination.md#keyset-pagination) and the [REST API](../../api/rest/index.md#keyset-based-pagination). Consider the following `issues` table: diff --git a/doc/development/database/query_recorder.md b/doc/development/database/query_recorder.md index bae211c1618..39d54954268 100644 --- a/doc/development/database/query_recorder.md +++ b/doc/development/database/query_recorder.md @@ -20,7 +20,7 @@ This style of test works by counting the number of SQL queries executed by Activ it "avoids N+1 database queries" do control = ActiveRecord::QueryRecorder.new { visit_some_page } create_list(:issue, 5) - expect { visit_some_page }.not_to exceed_query_limit(control) + expect { visit_some_page }.to issue_same_number_of_queries_as(control) end ``` @@ -33,13 +33,15 @@ it "avoids N+1 database queries" do create_list(:issue, 5) action = ActiveRecord::QueryRecorder.new { visit_some_page } - expect(action).not_to exceed_query_limit(control) + expect(action).to issue_same_number_of_queries_as(control) end ``` As an example you might create 5 issues in between counts, which would cause the query count to increase by 5 if an N+1 problem exists. -In some cases, the query count might change slightly between runs for unrelated reasons. In this case you might need to test `exceed_query_limit(control_count + acceptable_change)`, but this should be avoided if possible. +In some cases, the query count might change slightly between runs for unrelated reasons. +In this case you might need to test `issue_same_number_of_queries_as(control_count + acceptable_change)`, +but this should be avoided if possible. If this test fails, and the control was passed as a `QueryRecorder`, then the failure message indicates where the extra queries are by matching queries on @@ -50,18 +52,45 @@ warm the cache, second one to establish a control, third one to validate that there are no N+1 queries. Rather than make an extra request to warm the cache, prefer two requests (control and test) and configure your test to ignore [cached queries](#cached-queries) in N+1 specs. +```ruby +it "avoids N+1 database queries" do + # warm up + visit_some_page + + control = ActiveRecord::QueryRecorder.new(skip_cached: true) { visit_some_page } + create_list(:issue, 5) + expect { visit_some_page }.to issue_same_number_of_queries_as(control) +end +``` + ## Cached queries -By default, QueryRecorder ignores [cached queries](../merge_request_concepts/performance.md#cached-queries) in the count. However, it may be better to count -all queries to avoid introducing an N+1 query that may be masked by the statement cache. +By default, QueryRecorder ignores [cached queries](../merge_request_concepts/performance.md#cached-queries) in the count. +However, it may be better to count all queries to avoid introducing an N+1 query that may be masked by the statement cache. To do this, this requires the `:use_sql_query_cache` flag to be set. -You should pass the `skip_cached` variable to `QueryRecorder` and use the `exceed_all_query_limit` matcher: +You should pass the `skip_cached` variable to `QueryRecorder` and use the `issue_same_number_of_queries_as` matcher: ```ruby it "avoids N+1 database queries", :use_sql_query_cache do control = ActiveRecord::QueryRecorder.new(skip_cached: false) { visit_some_page } create_list(:issue, 5) - expect { visit_some_page }.not_to exceed_all_query_limit(control) + expect { visit_some_page }.to issue_same_number_of_queries_as(control) +end +``` + +## Using RequestStore + +[`RequestStore` / `Gitlab::SafeRequestStore`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/gems/gitlab-safe_request_store/README.md) +helps us to avoid N+1 queries by caching data in memory for the duration of a request. However, it is disabled by default in tests +and can lead to false negatives when testing for N+1 queries. + +To enable `RequestStore` in tests, use the `request_store` helper when needed: + +```ruby +it "avoids N+1 database queries", :request_store do + control = ActiveRecord::QueryRecorder.new(skip_cached: true) { visit_some_page } + create_list(:issue, 5) + expect { visit_some_page }.to issue_same_number_of_queries_as(control) end ``` @@ -72,6 +101,11 @@ Use a [request spec](https://gitlab.com/gitlab-org/gitlab/-/tree/master/spec/req Controller specs should not be used to write N+1 tests as the controller is only initialized once per example. This could lead to false successes where subsequent "requests" could have queries reduced (for example, because of memoization). +## Never trust a test you haven't seen fail + +Before you add a test for N+1 queries, you should first verify that the test fails without your change. +This is because the test may be broken, or the test may be passing for the wrong reasons. + ## Finding the source of the query There are multiple ways to find the source of queries. diff --git a/doc/development/database/single_table_inheritance.md b/doc/development/database/single_table_inheritance.md index dcf696b85bc..40b608bd110 100644 --- a/doc/development/database/single_table_inheritance.md +++ b/doc/development/database/single_table_inheritance.md @@ -6,22 +6,58 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Single Table Inheritance -**Summary:** don't use Single Table Inheritance (STI), use separate tables -instead. +**Summary:** Don't design new tables using Single Table Inheritance (STI). For existing tables that use STI as a pattern, avoid adding new types, and consider splitting them into separate tables. -Rails makes it possible to have multiple models stored in the same table and map -these rows to the correct models using a `type` column. This can be used to for -example store two different types of SSH keys in the same table. +STI is a database design pattern where a single table stores +different types of records. These records have a subset of shared columns and another column +that instructs the application which object that record should be represented by. +This can be used to for example store two different types of SSH keys in the same +table. ActiveRecord makes use of it and provides some features that make STI usage +more convenient. -While tempting to use one should avoid this at all costs for the same reasons as -outlined in the document ["Polymorphic Associations"](polymorphic_associations.md). +We no longer allow new STI tables because they: -## Solution +- Lead to tables with large number of rows, when we should strive to keep tables small. +- Need additional indexes, increasing our usage of lightweight locks, whose saturation can cause incidents. +- Add overhead by having to filter all of the data by a value, leading to more page accesses on read. +- Use the `class_name` to load the correct class for an object, but storing + the class name is costly and unnecessary. -The solution is very simple: just use a separate table for every type you'd -otherwise store in the same table. For example, instead of having a `keys` table -with `type` set to either `Key` or `DeployKey` you'd have two separate tables: -`keys` and `deploy_keys`. +Instead of using STI, consider the following alternatives: + +- Use a different table for each type. +- Avoid adding `*_type` columns. This is a code smell that might indicate that new types will be added in the future, and refactoring in the future will be much harder. +- If you already have a table that is effectively an STI on a `_type` column, consider: + - Splitting the existent data into multiple tables. + - Refactoring so that new types can be added as new tables while keeping existing ones (for example, move logic of the base class into a concern). + +If, **after considering all of the above downsides and alternatives**, STI +is the only solution for the problem at hand, we can at least avoid the +issues with saving the class name in the record by using an enum type +instead and the `EnumInheritance` concern: + +```ruby +class Animal < ActiveRecord::Base + include EnumInheritance + + enum species: { + dog: 1, + cat: 2 + } + + def self.inheritance_column_to_class_map = { + dog: 'Dog', + cat: 'Cat' + } + + def self.inheritance_column = 'species' +end + +class Dog < Animal; end +class Cat < Animal; end +``` + +If your table already has a `*_type`, new classes for the different types can be added as needed. ## In migrations diff --git a/doc/development/database/strings_and_the_text_data_type.md b/doc/development/database/strings_and_the_text_data_type.md index 54bdeaa7b28..adb715e219d 100644 --- a/doc/development/database/strings_and_the_text_data_type.md +++ b/doc/development/database/strings_and_the_text_data_type.md @@ -129,8 +129,6 @@ class AddExtendedTitleToSprints < Gitlab::Database::Migration[2.1] end def down - remove_text_limit :sprints, :extended_title - with_lock_retries do remove_column :sprints, :extended_title, if_exists: true end diff --git a/doc/development/database_review.md b/doc/development/database_review.md index 42021a5ae95..bb0bfbc759b 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -29,6 +29,8 @@ A database review is required for: These metrics could have complex queries over large tables. See the [Analytics Instrumentation Guide](https://about.gitlab.com/handbook/product/analytics-instrumentation-guide/) for implementation details. +- Changes that use [`update`, `delete`, `update_all`, `delete_all` or `destroy_all`](#preparation-when-using-update-delete-update_all-delete_all-or-destroy_all) + methods on an ActiveRecord object. A database reviewer is expected to look out for overly complex queries in the change and review those closer. If the author does not @@ -216,6 +218,16 @@ Include in the MR description: - If you're adding a composite index, another index might become redundant, so remove that in the same migration. For example adding `index(column_A, column_B, column_C)` makes the indexes `index(column_A, column_B)` and `index(column_A)` redundant. +#### Preparation when using `update`, `delete`, `update_all`, `delete_all` or `destroy_all` + +Using these ActiveRecord methods requires extra care because they modify data and can perform poorly, or they +can destroy data if improperly scoped. These methods are also +[incompatible with Common Table Expression (CTE) statements](sql.md#when-to-use-common-table-expressions). +Danger will comment on a Merge Request Diff when these methods are used. + +Follow documentation for [preparation when adding or modifying queries](#preparation-when-adding-or-modifying-queries) +to add the raw SQL query and query plan to the Merge Request description, and request a database review. + ### How to review for database - Check migrations diff --git a/doc/development/deprecation_guidelines/index.md b/doc/development/deprecation_guidelines/index.md index af89da5ec65..d586f25ffbf 100644 --- a/doc/development/deprecation_guidelines/index.md +++ b/doc/development/deprecation_guidelines/index.md @@ -45,7 +45,7 @@ For versioning and upgrade details, see our [Release and Maintenance policy](../ GitLab self-managed packages are semantically versioned and follow our [maintenance policy](../../policy/maintenance.md). This process applies to features and APIs that are generally available, not beta or experimental. -This maintenance policy is in place to allow our customers to prepare for disruptive changes by establishing a clear and predictable pattern that is widely used in the software industry. For many of our customers, GitLab is a business-critical application and surprising changes can cause damages and erode trust. +This maintenance policy is in place to allow our customers to prepare for disruptive changes by establishing a clear and predictable pattern that is widely used in the software industry. For many of our customers, GitLab is a business-critical application and surprising changes can cause damages and erode trust. Introducing breaking changes in minor releases is against policy because it can disrupt our customers and introduces an element of randomness that requires customers to check for breaking changes every minor release to ensure that their business is not impacted. This does not align with our goal [to make it as easy as possible for customers to do business with GitLab](https://about.gitlab.com/company/yearlies/#fy24-yearlies) and is strongly discouraged. diff --git a/doc/development/documentation/contribute.md b/doc/development/documentation/contribute.md index b6573665f8d..2b166266ddb 100644 --- a/doc/development/documentation/contribute.md +++ b/doc/development/documentation/contribute.md @@ -1,81 +1,11 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'index.md' +remove_date: '2023-10-27' --- -# Contribute to the GitLab documentation +This document was moved to [another location](index.md). -Everyone is welcome to update the GitLab documentation. - -## Work without an issue - -You don't need an issue to update the documentation. - -On [https://docs.gitlab.com](https://docs.gitlab.com), at the bottom of any page, -you can select **View page source** or **Edit in Web IDE** and [get started with a merge request](#open-your-merge-request). - -You can alternately: - -- Choose a page [in the `/doc` directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) - and edit it from there. -- Try installing and running the [Vale linting tool](testing.md#vale) - and fixing the resulting issues. - -When you're developing code, the workflow for updating docs is slightly different. -For details, see the [merge request workflow](../contributing/merge_request_workflow.md). - -## Search available issues - -If you're looking for an open issue, you can -[review the list of documentation issues curated specifically for new contributors](https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=created_date&state=opened&label_name%5B%5D=documentation&label_name%5B%5D=docs-only&label_name%5B%5D=Seeking%20community%20contributions&first_page_size=20). - -When you find an issue you'd like to work on: - -- If the issue is already assigned to someone, pick a different one. -- If the issue is unassigned, add a comment and ask to work on the issue. For a Hackathon, use `@docs-hackathon`. Otherwise, use `@gl-docsteam`. For example: - - ```plaintext - @docs-hackathon I would like to work on this issue - ``` - -- Do not ask for more than three issues at a time. - -## Open your merge request - -When you are ready to update the documentation: - -1. Go to the [GitLab repository](https://gitlab.com/gitlab-org/gitlab). -1. In the upper-right corner, select **Fork**. Forking makes a copy of the repository on GitLab.com. -1. In your fork, find the documentation page in the `\doc` directory. -1. If you know Git, make your changes and open a merge request. - If not, follow these steps: - 1. In the upper right, select **Edit > Edit single file**. - 1. In the **Commit message** text box, enter a commit message. - Use 3-5 words, start with a capital letter, and do not end with a period. - 1. Select **Commit changes**. - 1. On the left sidebar, select **Code > Merge requests**. - 1. Select **New merge request**. - 1. For the source branch, select your fork and branch. If you did not create a branch, select `master`. - For the target branch, select the [GitLab repository](https://gitlab.com/gitlab-org/gitlab) `master` branch. - 1. Select **Compare branches and continue**. A new merge request opens. - 1. Select the **Documentation** template. In the description, write a brief summary of the changes and link to the related issue, if there is one. - 1. Select **Create merge request**. - -## Ask for help - -Ask for help from the Technical Writing team if you: - -- Need help to choose the correct place for documentation. -- Want to discuss a documentation idea or outline. -- Want to request any other help. - -To identify someone who can help you: - -1. Locate the Technical Writer for the relevant - [DevOps stage group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). -1. Either: - - If urgent help is required, directly assign the Technical Writer in the issue or in the merge request. - - If non-urgent help is required, ping the Technical Writer in the issue or merge request. - -If you are a member of the GitLab Slack workspace, you can request help in the `#docs` channel. +<!-- This redirect file can be deleted after <2023-10-27>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md index 1bd8b37ff5f..79fcfc7e3f0 100644 --- a/doc/development/documentation/graphql_styleguide.md +++ b/doc/development/documentation/graphql_styleguide.md @@ -9,7 +9,7 @@ description: "Writing styles, markup, formatting, and other standards for GraphQ # Creating a GraphQL example page GraphQL APIs are different from [RESTful APIs](restful_api_styleguide.md). Reference -information is generated in our [GraphQL reference](../../api/graphql/reference/index.md). +information is generated in our [GraphQL API resources](../../api/graphql/reference/index.md) page. However, it's helpful to include examples on how to use GraphQL for different *use cases*, with samples that readers can use directly in the diff --git a/doc/development/documentation/help.md b/doc/development/documentation/help.md new file mode 100644 index 00000000000..fb730aca6f0 --- /dev/null +++ b/doc/development/documentation/help.md @@ -0,0 +1,125 @@ +--- +stage: none +group: Documentation Guidelines +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 +--- + +# GitLab /help + +Every GitLab instance includes documentation at `/help` (`https://gitlab.example.com/help`) +that matches the version of the instance. For example, <https://gitlab.com/help>. + +The documentation available online at <https://docs.gitlab.com> is deployed every +hour from the default branch of GitLab, Omnibus, Runner, Charts, and Operator. +After a merge request that updates documentation is merged, it is available online +in an hour or less. + +However, it's only available at `/help` on self-managed instances in the next released +version. The date an update is merged can impact which self-managed release the update +is present in. + +For example: + +1. A merge request in `gitlab` updates documentation. It has a milestone of 14.4, + with an expected release date of 2021-10-22. +1. It is merged on 2021-10-19 and available online the same day at <https://docs.gitlab.com>. +1. GitLab 14.4 is released on 2021-10-22, based on the `gitlab` codebase from 2021-10-18 + (one day *before* the update was merged). +1. The change shows up in the 14.5 self-managed release, due to missing the release cutoff + for 14.4. + +The exact cutoff date for each release is flexible, and can be sooner or later +than expected due to holidays, weekends or other events. In general, MRs merged +by the 17th should be present in the release on the 22nd, though it is not guaranteed. +If it is important that a documentation update is present in that month's release, +merge it as early as possible. + +## Linking to `/help` + +When you're building a new feature, you may need to link to the documentation +from the GitLab application. This is usually done in files inside the +`app/views/` directory, with the help of the `help_page_path` helper method. + +The `help_page_path` contains the path to the document you want to link to, +with the following conventions: + +- It's relative to the `doc/` directory in the GitLab repository. +- It omits the `.md` extension. +- It doesn't end with a forward slash (`/`). + +The help text follows the [Pajamas guidelines](https://design.gitlab.com/usability/contextual-help#formatting-help-content). + +### Linking to `/help` in HAML + +Use the following special cases depending on the context, ensuring all link text +is inside `_()` so it can be translated: + +- Linking to a doc page. In its most basic form, the HAML code to generate a + link to the `/help` page is: + + ```haml + = link_to _('Learn more.'), help_page_path('user/permissions'), target: '_blank', rel: 'noopener noreferrer' + ``` + +- Linking to an anchor link. Use `anchor` as part of the `help_page_path` + method: + + ```haml + = link_to _('Learn more.'), help_page_path('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer' + ``` + +- Using links inline of some text. First, define the link, and then use it. In + this example, `link_start` is the name of the variable that contains the + link: + + ```haml + - link = link_to('', help_page_path('user/permissions'), target: '_blank', rel: 'noopener noreferrer') + %p= safe_format(_("This is a text describing the option/feature in a sentence. %{link_start}Learn more.%{link_end}"), tag_pair(link, :link_start, :link_end)) + ``` + +- Using a button link. Useful in places where text would be out of context with + the rest of the page layout: + + ```haml + = link_to _('Learn more.'), help_page_path('user/permissions'), class: 'btn btn-info', target: '_blank', rel: 'noopener noreferrer' + ``` + +### Linking to `/help` in JavaScript + +To link to the documentation from a JavaScript or a Vue component, use the `helpPagePath` function from [`help_page_helper.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/helpers/help_page_helper.js): + +```javascript +import { helpPagePath } from '~/helpers/help_page_helper'; + +helpPagePath('user/permissions', { anchor: 'anchor-link' }) +// evaluates to '/help/user/permissions#anchor-link' for GitLab.com +``` + +This is preferred over static paths, as the helper also works on instances installed under a [relative URL](../../install/relative_url.md). + +### Linking to `/help` in Ruby + +To link to the documentation from within Ruby code, use the following code block as a guide, ensuring all link text is inside `_()` so it can +be translated: + +```ruby +docs_link = link_to _('Learn more.'), help_page_url('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer' +safe_format(_('This is a text describing the option/feature in a sentence. %{docs_link}'), docs_link: docs_link) +``` + +In cases where you need to generate a link from outside of views/helpers, where the `link_to` and `help_page_url` methods are not available, use the following code block +as a guide where the methods are fully qualified: + +```ruby +docs_link = ActionController::Base.helpers.link_to _('Learn more.'), Rails.application.routes.url_helpers.help_page_url('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer' +safe_format(_('This is a text describing the option/feature in a sentence. %{docs_link}'), docs_link: docs_link) +``` + +Do not use `include ActionView::Helpers::UrlHelper` just to make the `link_to` method available as you might see in some existing code. Read more in +[issue 340567](https://gitlab.com/gitlab-org/gitlab/-/issues/340567). + +## `/help` tests + +Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/features/help_pages_spec.rb) +are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../index.md) works correctly from `/help`. +For example, [GitLab.com's `/help`](https://gitlab.com/help). diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 3f26a5a7f4e..c06a396b378 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -2,417 +2,97 @@ stage: none group: Documentation Guidelines 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 -description: Learn how to contribute to GitLab Documentation. --- # Contribute to the GitLab documentation -The GitLab documentation is [intended as the single source of truth (SSOT)](https://about.gitlab.com/handbook/documentation/) for information about how to configure, use, and troubleshoot GitLab. The documentation contains use cases and usage instructions for every GitLab feature, organized by product area and subject. This includes topics and workflows that span multiple GitLab features and the use of GitLab with other applications. +The GitLab documentation is the single source of truth (SSOT) +for information about how to configure, use, and troubleshoot GitLab. +Everyone is welcome to contribute to the GitLab documentation. -In addition to this page, the following resources can help you craft and contribute to documentation: +## Work without an issue -- [Style Guide](styleguide/index.md) - What belongs in the docs, language guidelines, Markdown standards to follow, links, and more. -- [Topic types](topic_types/index.md) - Learn about the different types of topics. -- [Documentation process](workflow.md). -- [Markdown Guide](../../user/markdown.md) - A reference for all Markdown syntax supported by GitLab. -- [Site architecture](site_architecture/index.md) - How <https://docs.gitlab.com> is built. -- [Documentation for feature flags](feature_flags.md) - How to write and update documentation for GitLab features deployed behind feature flags. +You don't need an issue to update the documentation. -## Source files and rendered web locations +On <https://docs.gitlab.com>, at the bottom of any page, +you can select **View page source** or **Edit in Web IDE** and [get started with a merge request](#open-your-merge-request). -Documentation for GitLab, GitLab Runner, GitLab Operator, Omnibus GitLab, and Charts is published to <https://docs.gitlab.com>. Documentation for GitLab is also published within the application at `/help` on the domain of the GitLab instance. -At `/help`, only help for your current edition and version is included. Help for other versions is available at <https://docs.gitlab.com/archives/>. +You can alternately: -The source of the documentation exists within the codebase of each GitLab application in the following repository locations: +- Choose a page [in the `/doc` directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) + and edit it from there. +- Try installing and running the [Vale linting tool](testing.md#vale) + and fixing the resulting issues. -| Project | Path | -| --- | --- | -| [GitLab](https://gitlab.com/gitlab-org/gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) | -| [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs) | -| [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc) | -| [Charts](https://gitlab.com/gitlab-org/charts/gitlab) | [`/doc`](https://gitlab.com/gitlab-org/charts/gitlab/tree/master/doc) | -| [GitLab Operator](https://gitlab.com/gitlab-org/cloud-native/gitlab-operator) | [`/doc`](https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/tree/master/doc) | +When you're developing code, the workflow for updating docs is slightly different. +For details, see the [merge request workflow](../contributing/merge_request_workflow.md). -Documentation issues and merge requests are part of their respective repositories and all have the label `Documentation`. +## Search available issues -### Branch naming +If you're looking for an open issue, you can +[review the list of documentation issues curated specifically for new contributors](https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=created_date&state=opened&label_name%5B%5D=documentation&label_name%5B%5D=docs-only&label_name%5B%5D=Seeking%20community%20contributions&first_page_size=20). -The [CI pipeline for the main GitLab project](../pipelines/index.md) is configured to automatically -run only the jobs that match the type of contribution. If your contribution contains -**only** documentation changes, then only documentation-related jobs run, and -the pipeline completes much faster than a code contribution. +When you find an issue you'd like to work on: -If you are submitting documentation-only changes to Omnibus, Charts, or Operator, -the fast pipeline is not determined automatically. Instead, create branches for -docs-only merge requests using the following guide: - -| Branch name | Valid example | -|:----------------------|:-----------------------------| -| Starting with `docs/` | `docs/update-api-issues` | -| Starting with `docs-` | `docs-update-api-issues` | -| Ending in `-docs` | `123-update-api-issues-docs` | - -## Contributing to docs - -[Contributions to GitLab docs](workflow.md) are welcome from the entire GitLab community. - -To ensure that the GitLab docs are current, there are special processes and responsibilities for all [feature changes](workflow.md), that is development work that impacts the appearance, usage, or administration of a feature. - -However, anyone can contribute [documentation improvements](workflow.md) that are not associated with a feature change. For example, adding a new document on how to accomplish a use case that's already possible with GitLab or with third-party tools and GitLab. - -## Markdown and styles - -[GitLab docs](https://gitlab.com/gitlab-org/gitlab-docs) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown) -as its Markdown rendering engine. See the [GitLab Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) for a complete Kramdown reference. - -Adhere to the [Documentation Style Guide](styleguide/index.md). If a style standard is missing, you are welcome to suggest one via a merge request. - -## Folder structure and files - -See the [Folder structure](site_architecture/folder_structure.md) page. - -## Metadata - -To provide additional directives or useful information, we add metadata in YAML -format to the beginning of each product documentation page (YAML front matter). -All values are treated as strings and are only used for the -[docs website](site_architecture/index.md). - -### Stage and group metadata - -Each page should ideally have metadata related to the stage and group it -belongs to, as well as an information block as described below: - -- `stage`: The [Stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) - to which the majority of the page's content belongs. -- `group`: The [Group](https://about.gitlab.com/company/team/structure/#product-groups) - to which the majority of the page's content belongs. -- `info`: The following line, which provides direction to contributors regarding - how to contact the Technical Writer associated with the page's stage and - group: +- If the issue is already assigned to someone, pick a different one. +- If the issue is unassigned, add a comment and ask to work on the issue. For a Hackathon, use `@docs-hackathon`. Otherwise, use `@gl-docsteam`. For example: ```plaintext - 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 + @docs-hackathon I would like to work on this issue ``` -For example: - -```yaml ---- -stage: Example Stage -group: Example Group -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 ---- -``` - -### Redirection metadata - -The following metadata should be added when a page is moved to another location: - -- `redirect_to`: The relative path and filename (with an `.md` extension) of the - location to which visitors should be redirected for a moved page. - [Learn more](redirects.md). - -### Additional page metadata +- Do not ask for more than three issues at a time. -Each page can have additional, optional metadata (set in the -[default.html](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fc3577921343173d589dfa43d837b4307e4e620f/layouts/default.html#L30-52) -Nanoc layout), which is displayed at the top of the page if defined. +## Open your merge request -### Deprecated metadata +When you are ready to update the documentation: -The `type` metadata parameter is deprecated but still exists in documentation -pages. You can safely remove the `type` metadata parameter and its values. +1. Go to the [GitLab repository](https://gitlab.com/gitlab-org/gitlab). +1. In the upper-right corner, select **Fork**. Forking makes a copy of the repository on GitLab.com. +1. In your fork, find the documentation page in the `\doc` directory. +1. If you know Git, make your changes and open a merge request. + If not, follow these steps: + 1. In the upper right, select **Edit > Edit single file**. + 1. Make your changes. + 1. When you're ready to submit your changes, in the **Commit message** text box, enter a commit message. + Use 3-5 words, start with a capital letter, and do not end with a period. + 1. Select **Commit changes**. + 1. On the left sidebar, select **Code > Merge requests**. + 1. Select **New merge request**. + 1. For the source branch, select your fork and branch. If you did not create a branch, select `master`. + For the target branch, select the [GitLab repository](https://gitlab.com/gitlab-org/gitlab) `master` branch. + 1. Select **Compare branches and continue**. A new merge request opens. + 1. Select the **Documentation** template. In the description, write a brief summary of the changes and link to the related issue, if there is one. + 1. Select **Create merge request**. -### Batch updates for TW metadata +## Ask for help -The [`CODEOWNERS`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/CODEOWNERS) -file contains a list of files and the associated technical writers. +Ask for help from the Technical Writing team if you: -When a merge request contains documentation, the information in the `CODEOWNERS` file determines: +- Need help to choose the correct place for documentation. +- Want to discuss a documentation idea or outline. +- Want to request any other help. -- The list of users in the **Approvers** section. -- The technical writer that the GitLab Bot pings for community contributions. +To identify someone who can help you: -You can use a Rake task to update the `CODEOWNERS` file. +1. Locate the Technical Writer for the relevant + [DevOps stage group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). +1. Either: + - If urgent help is required, directly assign the Technical Writer in the issue or in the merge request. + - If non-urgent help is required, ping the Technical Writer in the issue or merge request. -#### Update the `CODEOWNERS` file +If you are a member of the GitLab Slack workspace, you can request help in the `#docs` channel. -When groups or [TW assignments](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) -change, you must update the `CODEOWNERS` file: +## Branch naming -1. Update the [stage and group metadata](#stage-and-group-metadata) for any affected doc pages, if necessary. If there are many changes, you can do this step in a separate MR. -1. Update the [`codeowners.rake`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/tw/codeowners.rake) file with the changes. -1. Go to the root of the `gitlab` repository. -1. Run the Rake task with this command: `bundle exec rake tw:codeowners` -1. Review the changes in the `CODEOWNERS` file. -1. Add and commit all your changes and push your branch up to `origin`. -1. Create a merge request and assign it to a technical writing manager for review. +The [CI/CD pipeline for the main GitLab project](../pipelines/index.md) is configured to +run shorter, faster pipelines on merge requests that contain only documentation changes. -When updating the `codeowners.rake` file: - -- To specify multiple writers for a single group, use a space between writer names: - - ```plaintext - CodeOwnerRule.new('Group Name', '@writer1 @writer2'), - ``` +If you submit documentation-only changes to Omnibus, Charts, or Operator, +to make the shorter pipeline run, you must follow these guidelines when naming your branch: -- For a group that does not have an assigned writer, include the group name in the file and comment out the line: - - ```plaintext - # CodeOwnerRule.new('Group Name', ''), - ``` - -## Move, rename, or delete a page - -See [redirects](redirects.md). - -## Merge requests for GitLab documentation - -Before getting started, make sure you read the introductory section -"[contributing to docs](#contributing-to-docs)" above and the -[documentation workflow](workflow.md). - -- Use the current [merge request description template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Documentation.md) -- Label the MR `Documentation` (can only be done by people with `developer` access, for example, GitLab team members) -- Assign the correct milestone per note below (can only be done by people with `developer` access, for example, GitLab team members) - -Documentation is merged if it is an improvement on existing content, -represents a good-faith effort to follow the template and style standards, -and is believed to be accurate. - -Further needs for what would make the doc even better should be immediately addressed -in a follow-up merge request or issue. - -If the release version you want to add the documentation to has already been -released, follow the [patch release runbook](https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/patch/engineers.md) -to get it merged into the current version. - -## GitLab `/help` - -Every GitLab instance includes documentation at `/help` (`https://gitlab.example.com/help`) -that matches the version of the instance. For example, <https://gitlab.com/help>. - -The documentation available online at <https://docs.gitlab.com> is deployed every -hour from the default branch of [GitLab, Omnibus, Runner, and Charts](#source-files-and-rendered-web-locations). -After a merge request that updates documentation is merged, it is available online -in an hour or less. - -However, it's only available at `/help` on self-managed instances in the next released -version. The date an update is merged can impact which self-managed release the update -is present in. - -For example: - -1. A merge request in `gitlab` updates documentation. It has a milestone of 14.4, - with an expected release date of 2021-10-22. -1. It is merged on 2021-10-19 and available online the same day at <https://docs.gitlab.com>. -1. GitLab 14.4 is released on 2021-10-22, based on the `gitlab` codebase from 2021-10-18 - (one day *before* the update was merged). -1. The change shows up in the 14.5 self-managed release, due to missing the release cutoff - for 14.4. - -The exact cutoff date for each release is flexible, and can be sooner or later -than expected due to holidays, weekends or other events. In general, MRs merged -by the 17th should be present in the release on the 22nd, though it is not guaranteed. -If it is important that a documentation update is present in that month's release, -merge it as early as possible. - -### Linking to `/help` - -When you're building a new feature, you may need to link to the documentation -from the GitLab application. This is usually done in files inside the -`app/views/` directory, with the help of the `help_page_path` helper method. - -The `help_page_path` contains the path to the document you want to link to, -with the following conventions: - -- It's relative to the `doc/` directory in the GitLab repository. -- It omits the `.md` extension. -- It doesn't end with a forward slash (`/`). - -The help text follows the [Pajamas guidelines](https://design.gitlab.com/usability/contextual-help#formatting-help-content). - -#### Linking to `/help` in HAML - -Use the following special cases depending on the context, ensuring all link text -is inside `_()` so it can be translated: - -- Linking to a doc page. In its most basic form, the HAML code to generate a - link to the `/help` page is: - - ```haml - = link_to _('Learn more.'), help_page_path('user/permissions'), target: '_blank', rel: 'noopener noreferrer' - ``` - -- Linking to an anchor link. Use `anchor` as part of the `help_page_path` - method: - - ```haml - = link_to _('Learn more.'), help_page_path('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer' - ``` - -- Using links inline of some text. First, define the link, and then use it. In - this example, `link_start` is the name of the variable that contains the - link: - - ```haml - - link = link_to('', help_page_path('user/permissions'), target: '_blank', rel: 'noopener noreferrer') - %p= safe_format(_("This is a text describing the option/feature in a sentence. %{link_start}Learn more.%{link_end}"), tag_pair(link, :link_start, :link_end)) - ``` - -- Using a button link. Useful in places where text would be out of context with - the rest of the page layout: - - ```haml - = link_to _('Learn more.'), help_page_path('user/permissions'), class: 'btn btn-info', target: '_blank', rel: 'noopener noreferrer' - ``` - -#### Linking to `/help` in JavaScript - -To link to the documentation from a JavaScript or a Vue component, use the `helpPagePath` function from [`help_page_helper.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/helpers/help_page_helper.js): - -```javascript -import { helpPagePath } from '~/helpers/help_page_helper'; - -helpPagePath('user/permissions', { anchor: 'anchor-link' }) -// evaluates to '/help/user/permissions#anchor-link' for GitLab.com -``` - -This is preferred over static paths, as the helper also works on instances installed under a [relative URL](../../install/relative_url.md). - -#### Linking to `/help` in Ruby - -To link to the documentation from within Ruby code, use the following code block as a guide, ensuring all link text is inside `_()` so it can -be translated: - -```ruby -docs_link = link_to _('Learn more.'), help_page_url('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer' -safe_format(_('This is a text describing the option/feature in a sentence. %{docs_link}'), docs_link: docs_link) -``` - -In cases where you need to generate a link from outside of views/helpers, where the `link_to` and `help_page_url` methods are not available, use the following code block -as a guide where the methods are fully qualified: - -```ruby -docs_link = ActionController::Base.helpers.link_to _('Learn more.'), Rails.application.routes.url_helpers.help_page_url('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer' -safe_format(_('This is a text describing the option/feature in a sentence. %{docs_link}'), docs_link: docs_link) -``` - -Do not use `include ActionView::Helpers::UrlHelper` just to make the `link_to` method available as you might see in some existing code. Read more in -[issue 340567](https://gitlab.com/gitlab-org/gitlab/-/issues/340567). - -### GitLab `/help` tests - -Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/features/help_pages_spec.rb) -are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../index.md) works correctly from `/help`. -For example, [GitLab.com's `/help`](https://gitlab.com/help). - -## Docs site architecture - -For information on how we build and deploy <https://docs.gitlab.com>, see [Docs site architecture](site_architecture/index.md). - -### Global navigation - -See the [Global navigation](site_architecture/global_nav.md) doc for information -on how the left-side navigation menu is built and updated. - -## Previewing the changes live - -See how you can use review apps to [preview your changes live](review_apps.md). - -## Testing - -For more information about documentation testing, see the [Documentation testing](testing.md) -guide. - -## Danger Bot - -GitLab uses [Danger](https://github.com/danger/danger) for some elements in -code review. For docs changes in merge requests, whenever a change to files under `/doc` -is made, Danger Bot leaves a comment with further instructions about the documentation -process. This is configured in the `Dangerfile` in the GitLab repository under -[/danger/documentation/](https://gitlab.com/gitlab-org/gitlab/-/tree/master/danger/documentation). - -## Help and feedback section - -This section ([introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/319) in GitLab 11.4) -is displayed at the end of each document and can be omitted by adding a key into -the front matter: - -```yaml ---- -feedback: false ---- -``` - -The default is to leave it there. If you want to omit it from a document, you -must check with a technical writer before doing so. - -The click events in the feedback section are tracked with Google Tag Manager. -The conversions can be viewed on Google Analytics by navigating to -**Behavior > Events > Top events > docs**. - -## Automatic screenshot generator - -You can now set up an automatic screenshot generator to take and compress screenshots with the -help of a configuration file known as **screenshot generator**. - -### Use the tool - -To run the tool on an existing screenshot generator, take the following steps: - -1. Set up the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md). -1. Navigate to the subdirectory with your cloned GitLab repository, typically `gdk/gitlab`. -1. Make sure that your GDK database is fully migrated: `bin/rake db:migrate RAILS_ENV=development`. -1. Install `pngquant`, see the tool website for more information: [`pngquant`](https://pngquant.org/) -1. Run `scripts/docs_screenshots.rb spec/docs_screenshots/<name_of_screenshot_generator>.rb <milestone-version>`. -1. Identify the location of the screenshots, based on the `gitlab/doc` location defined by the `it` parameter in your script. -1. Commit the newly created screenshots. - -### Extending the tool - -To add an additional **screenshot generator**, take the following steps: - -- Locate the `spec/docs_screenshots` directory. -- Add a new file with a `_docs.rb` extension. -- Be sure to include the following bits in the file: - -```ruby -require 'spec_helper' - -RSpec.describe '<What I am taking screenshots of>', :js do - include DocsScreenshotHelpers # Helper that enables the screenshots taking mechanism - - before do - page.driver.browser.manage.window.resize_to(1366, 1024) # length and width of the page - end -``` - -- In addition, every `it` block must include the path where the screenshot is saved - -```ruby - it 'user/packages/container_registry/img/project_image_repositories_list' -``` - -#### Full page screenshots - -To take a full page screenshot, `visit the page` and perform any expectation on real content (to have capybara wait till the page is ready and not take a white screenshot). - -#### Element screenshot - -To have the screenshot focuses few more steps are needed: - -- **find the area**: `screenshot_area = find('#js-registry-policies')` -- **scroll the area in focus**: `scroll_to screenshot_area` -- **wait for the content**: `expect(screenshot_area).to have_content 'Expiration interval'` -- **set the crop area**: `set_crop_data(screenshot_area, 20)` - -In particular, `set_crop_data` accepts as arguments: a `DOM` element and a -padding. The padding is added around the element, enlarging the screenshot area. - -#### Live example - -Please use `spec/docs_screenshots/container_registry_docs.rb` as a guide and as an example to create your own scripts. +| Branch name | Valid example | +|:----------------------|:-----------------------------| +| Starting with `docs/` | `docs/update-api-issues` | +| Starting with `docs-` | `docs-update-api-issues` | +| Ending in `-docs` | `123-update-api-issues-docs` | diff --git a/doc/development/documentation/site_architecture/folder_structure.md b/doc/development/documentation/site_architecture/folder_structure.md index 1c9fc1441c4..d4a3c856e0a 100644 --- a/doc/development/documentation/site_architecture/folder_structure.md +++ b/doc/development/documentation/site_architecture/folder_structure.md @@ -75,7 +75,7 @@ place for it. ## Avoid duplication Do not include the same information in multiple places. -[Link to a single source of truth instead.](../styleguide/index.md#link-instead-of-repeating-text) +Link to a single source of truth instead. For example, if you have code in a repository other than the [primary repositories](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/architecture.md), and documentation in the same repository, you can keep the documentation in that repository. diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 849308f3086..822c7992222 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -14,6 +14,35 @@ static site generator. View the [`gitlab-docs` architecture page](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/architecture.md) for more information. +## Source files + +The documentation source files are in the same repositories as the product code. + +| Project | Path | +| --- | --- | +| [GitLab](https://gitlab.com/gitlab-org/gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) | +| [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs) | +| [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc) | +| [Charts](https://gitlab.com/gitlab-org/charts/gitlab) | [`/doc`](https://gitlab.com/gitlab-org/charts/gitlab/tree/master/doc) | +| [GitLab Operator](https://gitlab.com/gitlab-org/cloud-native/gitlab-operator) | [`/doc`](https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/tree/master/doc) | + +Documentation issues and merge requests are part of their respective repositories and all have the label `Documentation`. + +## Publication + +Documentation for GitLab, GitLab Runner, GitLab Operator, Omnibus GitLab, and Charts is published to <https://docs.gitlab.com>. + +The same documentation is included in the application. To view the in-product help, +go to the URL and add `/help` at the end. +Only help for your current edition and version is included. + +Help for other versions is available at <https://docs.gitlab.com/archives/>. + +## Updating older versions + +If you need to add or edit documentation for a GitLab version that has already been +released, follow the [patch release runbook](https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/patch/engineers.md). + ## Documentation in other repositories If you have code and documentation in a repository other than the [primary repositories](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/architecture.md), @@ -41,7 +70,10 @@ Then you can use one of these approaches: The docs website supports versions and each month we add the latest one to the list. For more information, read about the [monthly release process](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md). -## Review Apps for documentation merge requests +## Danger Bot -If you are contributing to GitLab docs read how to -[create a Review App with each merge request](../index.md#previewing-the-changes-live). +GitLab uses [Danger](https://github.com/danger/danger) for some elements in +code review. For docs changes in merge requests, whenever a change to files under `/doc` +is made, Danger Bot leaves a comment with further instructions about the documentation +process. This is configured in the `Dangerfile` in the GitLab repository under +[/danger/documentation/](https://gitlab.com/gitlab-org/gitlab/-/tree/master/danger/documentation). diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index bd4ded8ca11..94bc6bba240 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -7,23 +7,12 @@ description: 'Writing styles, markup, formatting, and other standards for GitLab # Documentation Style Guide -This document defines the standards for GitLab documentation, including grammar, formatting, word use, and more. +This document defines the standards for GitLab documentation, including grammar, formatting, and more. +For guidelines on specific words, see [the word list](word_list.md). For style questions, mention `@tw-style` in an issue or merge request. If you have access to the GitLab Slack workspace, use the `#docs-processes` channel. -In addition to this page, the following resources can help you craft and contribute to documentation: - -- [Doc contribution guidelines](../index.md) -- [Recommended word list](word_list.md) -- [Doc style and consistency testing](../testing.md) -- [Guidelines for UI error messages](https://design.gitlab.com/content/voice-and-tone#clear-error-messages) -- [Documentation global navigation](../site_architecture/global_nav.md) -- [GitLab Handbook style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) -- [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) -- [Google Developer Documentation Style Guide](https://developers.google.com/style) -- [Recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix) - ## The GitLab voice The GitLab brand guidelines define the @@ -34,108 +23,43 @@ direct, and precise. The goal is to provide information that's easy to search an The voice in the documentation should be conversational but brief, friendly but succinct. -## Documentation is the single source of truth (SSOT) +## Documentation is the single source of truth (SSoT) -The GitLab documentation is the SSOT for all -information related to GitLab implementation, usage, and troubleshooting. It evolves -continuously, in keeping with new products and features, and with improvements -for clarity, accuracy, and completeness. +The GitLab documentation is the SSoT for all information related to implementation, +use, and troubleshooting. The documentation evolves continuously. It is updated with +new products and features, and with improvements for clarity, accuracy, and completeness. This policy prevents information silos, making it easier to find information -about GitLab products. - -It also informs decisions about the kinds of content we include in our -documentation. - -### The documentation includes all information - -Include problem-solving actions that may address rare cases or be considered -risky, but provide proper context through fully detailed -warnings and caveats. This kind of content should be included as it could be -helpful to others and, when properly explained, its benefits outweigh the risks. -If you think you have found an exception to this rule, contact the -Technical Writing team. - -GitLab adds all troubleshooting information to the documentation, no matter how -unlikely a user is to encounter a situation. - -GitLab Support maintains their own -[troubleshooting content](../../../administration/troubleshooting/index.md) -in the GitLab documentation. - -### The documentation includes all media types +about GitLab products. It also informs decisions about the kinds of content that +is included in the documentation. -Include any media types/sources if the content is relevant to readers. You can -freely include or link presentations, diagrams, and videos. No matter who -it was originally composed for, if it is helpful to any of our audiences, we can -include it. +## Topic types -- If you use an image that has a separate source file (for example, a vector or - diagram format), link the image to the source file so that anyone can update or reuse it. -- Do not copy and paste content from other sources unless it is a limited - quotation with the source cited. Typically it is better to either rephrase - relevant information in your own words or link out to the other source. +GitLab uses [topic types](../topic_types/index.md) to organize the product documentation. -### Topic types +Topic types help users digest information more quickly. They also help address these issues: -In the software industry, it is a best practice to organize documentation in -different types. For example: - -- Concepts -- Tasks -- Reference -- Troubleshooting - -At GitLab, we have not traditionally used topic types. However, we are starting to -move in this direction, so we can address these issues: - -- **Content is hard to find.** Our docs are comprehensive and include a large amount of - useful information. Topic types create repeatable patterns that make our content easier +- **Content is hard to find.** The GitLab docs are comprehensive and include a large amount of + useful information. Topic types create repeatable patterns that make the content easier to scan and parse. -- **Content is often written from the contributor's point of view.** Our docs - are written by contributors. Topic types (tasks specifically) help put +- **Content is often written from the contributor's point of view.** The GitLab docs + are written by a variety of contributors. Topic types (tasks, specifically) help put information into a format that is geared toward helping others, rather than documenting how a feature was implemented. -GitLab uses these [topic types](../topic_types/index.md). - -### Link instead of repeating text +## Docs-first methodology -Rather than repeating information from another topic, link to the single source -of truth and explain why it is important. - -### Docs-first methodology - -We employ a documentation-first methodology. This method ensures the documentation -remains a complete and trusted resource, and makes communicating about the use -of GitLab more efficient. +The product documentation should be a complete and trusted resource. - If the answer to a question exists in documentation, share the link to the documentation instead of rephrasing the information. -- When you encounter new information not available in GitLab documentation (for - example, when working on a support case or testing a feature), your first step - should be to create a merge request (MR) to add this information to the - documentation. You can then share the MR to communicate this information. - -New information that would be useful toward the future usage or troubleshooting -of GitLab should not be written directly in a forum or other messaging system, -but added to a documentation MR and then referenced, as described above. +- When you encounter information that's not available in GitLab documentation, + create a merge request (MR) to add the information to the + documentation. Then share the MR to communicate the information. The more we reflexively add information to the documentation, the more the documentation helps others efficiently accomplish tasks and solve problems. -If you have questions when considering, authoring, or editing documentation, ask -the Technical Writing team. They're available on Slack in `#docs` or in GitLab by -mentioning [the writer for](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) -the applicable [DevOps stage or group](https://about.gitlab.com/handbook/product/categories/#devops-stages). -Otherwise, forge ahead with your best effort. It does not need to be perfect; -the team is happy to review and improve upon your content. Review the -[Documentation guidelines](index.md) before you begin your first documentation MR. - -Maintaining a knowledge base separate from the documentation would -be against the documentation-first methodology because the content would overlap with -the documentation. - ## Writing for localization The GitLab documentation is not localized, but we follow guidelines that @@ -155,13 +79,18 @@ also aid in consistency, which is important for localization. ## Markdown -All GitLab documentation is written using [Markdown](https://en.wikipedia.org/wiki/Markdown). +All GitLab documentation is written in [Markdown](https://en.wikipedia.org/wiki/Markdown). -The [documentation website](https://docs.gitlab.com) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown), +The [documentation website](https://docs.gitlab.com) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/ruby/gems/gitlab_kramdown), a "flavored" Kramdown engine to render pages from Markdown to HTML. The use of Kramdown features is limited by our linters, so, use regular Markdown and follow the rules in the linked style guide. You can't use Kramdown-specific markup (for example, `{:.class}`). +For a complete Kramdown reference, see the +[GitLab Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/). + +The Markdown format is [tested](../testing.md) by using markdownlint and Vale. + ### HTML in Markdown Hard-coded HTML is valid, although it's discouraged from being used. HTML is permitted if: @@ -193,43 +122,92 @@ Use backticks for: - Commands, parameters, and filenames. - Values. For example: "In the **Name** text box, type `test`." -### Markdown Rules +## Metadata + +Each documentation Markdown page contains YAML front matter. +All values in the metadata are treated as strings and are used for the +docs website only. + +### Stage and group metadata + +Each page should have metadata related to the stage and group it +belongs to, as well as an information block. For example: + +```yaml +--- +stage: Example Stage +group: Example Group +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 +--- +``` + +To populate the metadata, include this information: + +- `stage`: The [Stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) + that the majority of the page's content belongs to. +- `group`: The [Group](https://about.gitlab.com/company/team/structure/#product-groups) + that the majority of the page's content belongs to. +- `info`: How to find the Technical Writer associated with the page's stage and + group. + +### Additional metadata + +Each page can have additional, optional metadata (set in the +[default.html](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fc3577921343173d589dfa43d837b4307e4e620f/layouts/default.html#L30-52) +Nanoc layout), which is displayed at the top of the page if defined. + +### Deprecated metadata -GitLab ensures that the Markdown used across all documentation is consistent, as -well as easy to review and maintain, by [testing documentation changes](../testing.md) -with [markdownlint](../testing.md#markdownlint). This lint test fails when any -document has an issue with Markdown formatting that may cause the page to render -incorrectly in GitLab. It also fails when a document has -non-standard Markdown (which may render correctly, but is not the current -standard for GitLab documentation). +The `type` metadata parameter is deprecated but still exists in documentation +pages. You can remove the `type` metadata parameter and its values. -#### Markdown rule `MD044/proper-names` (capitalization) +### Batch updates for TW metadata -A rule that could cause confusion is `MD044/proper-names`, as it might not be -immediately clear what caused markdownlint to fail, or how to correct the -failure. This rule checks a list of known words, listed in the `.markdownlint.yml` -file in each project, to verify proper use of capitalization and backticks. -Words in backticks are ignored by markdownlint. +The [`CODEOWNERS`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/CODEOWNERS) +file contains a list of files and the associated technical writers. -In general, product names should follow the exact capitalization of the official -names of the products, protocols, and so on. +When a merge request contains documentation, the information in the `CODEOWNERS` file determines: -Some examples fail if incorrect capitalization is used: +- The list of users in the **Approvers** section. +- The technical writer that the GitLab Bot pings for community contributions. -- MinIO (needs capital `IO`) -- NGINX (needs all capitals) -- runit (needs lowercase `r`) +You can use a Rake task to update the `CODEOWNERS` file. -Additionally, commands, parameters, values, filenames, and so on must be -included in backticks. For example: +#### Update the `CODEOWNERS` file -- "Change the `needs` keyword in your `.gitlab-ci.yml`..." - - `needs` is a parameter, and `.gitlab-ci.yml` is a file, so both need backticks. - Additionally, `.gitlab-ci.yml` without backticks fails markdownlint because it - does not have capital G or L. -- "Run `git clone` to clone a Git repository..." - - `git clone` is a command, so it must be lowercase, while Git is the product, - so it must have a capital G. +When groups or [TW assignments](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) +change, you must update the `CODEOWNERS` file: + +1. Update the [stage and group metadata](#stage-and-group-metadata) for any affected doc pages, if necessary. If there are many changes, you can do this step in a separate MR. +1. Update the [`codeowners.rake`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/tw/codeowners.rake) file with the changes. +1. Go to the root of the `gitlab` repository. +1. Run the Rake task with this command: `bundle exec rake tw:codeowners` +1. Review the changes in the `CODEOWNERS` file. +1. Add and commit all your changes and push your branch up to `origin`. +1. Create a merge request and assign it to a technical writing manager for review. + +When you update the `codeowners.rake` file: + +- To specify multiple writers for a single group, use a space between writer names. Files are assigned to both writers. + + ```ruby + CodeOwnerRule.new('Group Name', '@writer1 @writer2'), + ``` + + - To assign different writers within a group to docs in different directories, use the `path` parameter to specify a directory: + + ```ruby + CodeOwnerRule.new('Group Name', ->(path) { path.start_with?('/doc/user') ? '@writer1' : '@writer2' }), + ``` + + In this example, `writer1` is a code owner for files related to this group that are in `/doc/user`. + For everything else, `writer2` is made code owner. For an example, see [MR 127903](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127903). + +- For a group that does not have an assigned writer, include the group name in the file and comment out the line: + + ```ruby + # CodeOwnerRule.new('Group Name', ''), + ``` ## Language @@ -386,8 +364,6 @@ For numbers in text, spell out zero through nine and use numbers for 10 and grea ## Text - [Write in Markdown](#markdown). -- Splitting long lines (preferably up to 100 characters) can make it easier to - provide feedback on small chunks of text. - Insert an empty line for new paragraphs. - Insert an empty line between different markups (for example, after every paragraph, header, list, and so on). Example: @@ -401,6 +377,14 @@ For numbers in text, spell out zero through nine and use numbers for 10 and grea - List item 2 ``` +### Line length + +To make the source content easy to read, and to more easily compare diffs, +follow these best practices when possible. + +- Split long lines at approximately 100 characters. +- Start each new sentence on a new line. + ### Comments To embed comments within Markdown, use standard HTML comments that are not rendered @@ -453,7 +437,7 @@ Do not use these punctuation characters: ### Placeholder text -You might want to provide a command or configuration that +In a code block, you might want to provide a command or configuration that uses specific values. In these cases, use [`<` and `>`](https://en.wikipedia.org/wiki/Usage_message#Pattern) @@ -465,6 +449,13 @@ For example: cp <your_source_directory> <your_destination_directory> ``` +If the placeholder is not in a code block, use [`<` and `>`] and wrap the placeholder +in a single backtick. For example: + +```plaintext +Select **Grant admin consent for `<application_name>`**. +``` + ### Keyboard commands Use the HTML `<kbd>` tag when referring to keystroke presses. For example: @@ -477,17 +468,23 @@ When the docs are generated, the output is: To stop the command, press <kbd>Control</kbd>+<kbd>C</kbd>. +### Buttons in the UI + +For elements with a visible label, use the label in bold with matching case. + +For example: `Select **Cancel**.` + ### Text entered in the UI If you want the user to type something in the UI, use backticks. For example: ```plaintext -In the **Commit message** box, type `This is my merge request`. +In the **Commit message** text box, type `This is my merge request`. ``` Backticks are more precise than quotes. For example, in this string: -- In the **Commit message** box, type "This is my merge request." +- In the **Commit message** text box, type "This is my merge request." It's not clear whether the user should include the period in the string. @@ -652,10 +649,10 @@ To help keep tables easier to maintain, you can: - Add additional spaces to make the column widths consistent. For example: ```markdown - | App name | Description | Requirements | - |----------|---------------------|----------------| - | App 1 | Description text 1. | Requirements 1 | - | App 2 | Description text 2. | None | + | App name | Description | Requirements | + |----------|---------------------|--------------| + | App 1 | Description text 1. | A, B, and C. | + | App 2 | Description text 2. | None | ``` - Skip the additional spaces in the rightmost column for tables that are very wide. @@ -669,11 +666,32 @@ To help keep tables easier to maintain, you can: | Setting 3 | `0` | Another short description. | ``` -Consider installing a plugin or extension in your editor for formatting tables: +### Editor extensions for table formatting + +To ensure consistent table formatting across all Markdown files, consider formatting your tables +with the VS Code [Markdown Table Formatter](https://github.com/fcrespo82/vscode-markdown-table-formatter). +To configure this extension to follow the guidelines above, enable the **Follow header row length** setting. +To enable the setting: + +- In the UI: + + 1. In the VS Code menu, go to **Code > Settings > Settings**. + 1. Search for `Limit Last Column Length`. + 1. In the **Limit Last Column Length** dropdown list, select **Follow header row length**. -- [Markdown Table Prettifier](https://marketplace.visualstudio.com/items?itemName=darkriszty.markdown-table-prettify) for Visual Studio Code -- [Markdown Table Formatter](https://packagecontrol.io/packages/Markdown%20Table%20Formatter) for Sublime Text -- [Markdown Table Formatter](https://atom.io/packages/markdown-table-formatter) for Atom +- In your VS Code `settings.json`, add a new line with: + + ```json + { + "markdown-table-formatter.limitLastColumnLength": "Follow header row length" + } + ``` + +To format a table with this extension, select the entire table, right-click the selection, +and select **Format selection**. + +Alternatively, if you use Sublime Text you can try the [Markdown Table Formatter](https://packagecontrol.io/packages/Markdown%20Table%20Formatter) +plugin, but it does not have a **Follow header row length** setting. ### Updates to existing tables @@ -706,31 +724,44 @@ Instead, follow the [API topic template](../restful_api_styleguide.md#api-topic- ### Footnotes To indicate a footnote, use the HTML tag `<sup>` with a number. -Put the tag at the end of the sentence or term. - -For the footnotes below the table, use a bold number followed by a sentence. - -For example: +Put the tag at the end of the sentence or term. For example: ```markdown | App name | Description | |:---------|:-------------------------------| | App A | Description text. <sup>1</sup> | | App B | Description text. <sup>2</sup> | +``` + +For the footnotes below the table, use the HTML tags `<small>`, `<ol>` and `<li>`. +For example: -1. This is the footnote. -1. This is the other footnote. +```html +<html> +<small>Footnotes + <ol> + <li>This is the footnote.</li> + <li>This is the other footnote.</li> + </ol> +</small> +</html> ``` -This text renders this output: +This text renders as this output: | App name | Description | |:---------|:-------------------------------| | App A | Description text. <sup>1</sup> | | App B | Description text. <sup>2</sup> | -1. This is the footnote. -1. This is the other footnote. +<html> +<small>Footnotes + <ol> + <li>This is the footnote.</li> + <li>This is the other footnote.</li> + </ol> +</small> +</html> ## Quotes @@ -785,7 +816,7 @@ but do not use it. Link to the page instead. If a topic title has a [product tier badge](#product-tier-badges), do not include it in the anchor link. For example, for the topic -`## This is an example **(FREE)**`, use the anchor `#this-is-an-example`. +`## This is an example **(FREE ALL)**`, use the anchor `#this-is-an-example`. With Kramdown, you can add a custom ID to an HTML element, but these IDs don't work in `/help`, so you should not use them. @@ -866,11 +897,12 @@ Sometimes they are more precise and will be maintained more actively. For each external link you add, weigh the customer benefit with the maintenance difficulties. -### Links that require permissions +### Confidential or restricted access links Don't link directly to: - [Confidential issues](../../../user/project/issues/confidential_issues.md). +- Internal handbook pages. - Project features that require [special permissions](../../../user/permissions.md) to view. @@ -881,8 +913,8 @@ These links fail for: If you must use one of these links: -- If the link is to a confidential issue, mention that the issue is visible only to GitLab team members, as in the first example. -- If the link requires a specific role or permissions, mention that information, as in the second example. +- If the link is to a confidential issue or internal handbook page, mention that the issue or page is visible only to GitLab team members. +- If the link requires a specific role or permissions, mention that information. - Put the link in backticks so that it does not cause link checkers to fail. Examples: @@ -892,6 +924,9 @@ GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/<issue_number>` ``` +GitLab team members can view more information in this internal handbook page: +`https://internal.gitlab.com/handbook/<link>` + ```markdown Users with the Maintainer role for the project can use the pipeline editor: `https://gitlab.com/gitlab-org/gitlab/-/ci/editor` @@ -1201,6 +1236,61 @@ include a visual representation to help readers understand it, you can: an area of the screen. - Create a short video of the interaction and link to it. +### Automatic screenshot generator + +You can use an automatic screenshot generator to take and compress screenshots. + +1. Set up the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md). +1. Navigate to the subdirectory with your cloned GitLab repository, typically `gdk/gitlab`. +1. Make sure that your GDK database is fully migrated: `bin/rake db:migrate RAILS_ENV=development`. +1. Install `pngquant`, see the tool website for more information: [`pngquant`](https://pngquant.org/) +1. Run `scripts/docs_screenshots.rb spec/docs_screenshots/<name_of_screenshot_generator>.rb <milestone-version>`. +1. Identify the location of the screenshots, based on the `gitlab/doc` location defined by the `it` parameter in your script. +1. Commit the newly created screenshots. + +#### Extending the tool + +To add an additional **screenshot generator**, complete the following steps: + +1. Locate the `spec/docs_screenshots` directory. +1. Add a new file with a `_docs.rb` extension. +1. Be sure to include the following information in the file: + + ```ruby + require 'spec_helper' + + RSpec.describe '<What I am taking screenshots of>', :js do + include DocsScreenshotHelpers # Helper that enables the screenshots taking mechanism + + before do + page.driver.browser.manage.window.resize_to(1366, 1024) # length and width of the page + end + ``` + +1. In addition, every `it` block must include the path where the screenshot is saved: + + ```ruby + it 'user/packages/container_registry/img/project_image_repositories_list' + ``` + +##### Full page screenshots + +To take a full page screenshot, `visit the page` and perform any expectation on real content (to have capybara wait till the page is ready and not take a white screenshot). + +##### Element screenshot + +To have the screenshot focuses few more steps are needed: + +- **find the area**: `screenshot_area = find('#js-registry-policies')` +- **scroll the area in focus**: `scroll_to screenshot_area` +- **wait for the content**: `expect(screenshot_area).to have_content 'Expiration interval'` +- **set the crop area**: `set_crop_data(screenshot_area, 20)` + +In particular, `set_crop_data` accepts as arguments: a `DOM` element and a +padding. The padding is added around the element, enlarging the screenshot area. + +Use `spec/docs_screenshots/container_registry_docs.rb` as a guide and as an example to create your own scripts. + ## Emoji Don't use the Markdown emoji format, for example `:smile:`, for any purpose. Use @@ -1522,19 +1612,11 @@ Until we implement automated testing for broken links to tabs ([Issue 1355](http See [Pajamas](https://design.gitlab.com/components/tabs/#guidelines) for more details on tabs. -## Terms - -To maintain consistency through GitLab documentation, use these styles and terms. +## Plagiarism -### Describe UI elements - -Follow these styles when you're describing user interface elements in an -application: - -- For elements with a visible label, use that label in bold with matching case. - For example, `Select **Cancel**`. -- For elements with a tooltip or hover label, use that label in bold with - matching case. For example, `Select **Add status emoji**`. +Do not copy and paste content from other sources unless it is a limited +quotation with the source cited. Typically it is better to rephrase +relevant information in your own words or link out to the other source. ## Products and features @@ -1548,8 +1630,7 @@ When names change, it is more complicated to search or grep text that has line b ### Product tier badges -Tier badges are displayed as orange text next to a topic title. These badges link to the GitLab -pricing page. +Tier badges provide information about a feature and are displayed next to the topic title. You should assign a tier badge: @@ -1558,37 +1639,59 @@ You should assign a tier badge: The H1 tier badge should be the badge that applies to the lowest tier for the features on the page. -Some pages won't have a tier badge, because no obvious tier badge applies. For example: +#### Available product tier badges -- Tutorials. -- Pages that compare features from different tiers. +Tier badges must include two components, in this order: a subscription tier and an offering. +These components are surrounded by bold and parentheses, for example `**(ULTIMATE SAAS)**`. + +Subscription tiers: + +- `FREE` - Applies to all tiers. +- `PREMIUM` - Applies to Premium and Ultimate tiers. +- `ULTIMATE` - Applies to Ultimate tier only. + +Offerings: + +- `SELF` +- `SAAS` +- `ALL` - Applies to both self-managed and SaaS. + +You can also add a third component for the feature's status: + +- `EXPERIMENT` +- `BETA` #### Add a tier badge -To add a tier badge to a topic title, add the relevant tier badge -after the title text. For example: +To add a tier badge to a topic title, add the two relevant components +after the title text. You must include the subscription tier first, and then the offering. +For example: + +```markdown +# Topic title **(FREE ALL)** +``` + +Optionally, you can add the feature status as the last part of the badge: ```markdown -# Topic title **(FREE)** +# Topic title **(FREE ALL EXPERIMENT)** ``` +##### Inline tier badges + Do not add tier badges inline with other text, except for [API attributes](../restful_api_styleguide.md). The single source of truth for a feature should be the topic where the functionality is described. -#### Available product tier badges +##### Pages that don't need a tier badge -| Where feature is available | Tier badge | -|:-----------------------------------------------------------------------------------------|:----------------------| -| On GitLab self-managed and GitLab SaaS, available in all tiers. | `**(FREE)**` | -| On GitLab self-managed and GitLab SaaS, available in Premium and Ultimate. | `**(PREMIUM)**` | -| On GitLab self-managed and GitLab SaaS, available in Ultimate. | `**(ULTIMATE)**` | -| On GitLab self-managed, available in all tiers. Not available on GitLab SaaS. | `**(FREE SELF)**` | -| On GitLab self-managed, available in Premium and Ultimate. Not available on GitLab SaaS. | `**(PREMIUM SELF)**` | -| On GitLab self-managed, available in Ultimate. Not available on GitLab SaaS. | `**(ULTIMATE SELF)**` | -| On GitLab SaaS, available in all tiers. Not available on self-managed. | `**(FREE SAAS)**` | -| On GitLab SaaS, available in Premium and Ultimate. Not available on self-managed. | `**(PREMIUM SAAS)**` | -| On GitLab SaaS, available in Ultimate. Not available on self-managed. | `**(ULTIMATE SAAS)**` | +Some pages won't have a tier badge, because no obvious tier badge applies. For example: + +- Tutorials. +- Pages that compare features from different tiers. +- Pages in the `/development` folder. These pages are automatically assigned a `Contribute` badge. + +##### Administrator documentation tier badges Topics that are only for instance administrators should be badged `<TIER> SELF`. Instance administrator documentation often includes sections that mention: @@ -1605,6 +1708,25 @@ instance administrator. Certain styles should be applied to specific sections. Styles for specific sections are outlined in this section. +### Help and feedback section + +This section ([introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/319) in GitLab 11.4) +is displayed at the end of each document and can be omitted by adding a key into +the front matter: + +```yaml +--- +feedback: false +--- +``` + +The default is to leave it there. If you want to omit it from a document, you +must check with a technical writer before doing so. + +The click events in the feedback section are tracked with Google Tag Manager. +The conversions can be viewed on Google Analytics by navigating to +**Behavior > Events > Top events > docs**. + ### GitLab restart When a restart or reconfigure of GitLab is required, avoid duplication by linking @@ -1822,8 +1944,3 @@ It renders as: ``` ::EndTabs - -## Feature flags - -Learn how to [document features deployed behind flags](../feature_flags.md). For -guidance on developing GitLab with feature flags, see [Feature flags in development of GitLab](../../feature_flags/index.md). diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 84ab2ecc4e9..d65df0b56c8 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -188,6 +188,10 @@ Instead of: - As none of the endpoints return an ID... +## as well as + +Instead of **as well as**, use **and**. + ## associate Do not use **associate** when describing adding issues to epics, or users to issues, merge requests, @@ -255,6 +259,10 @@ Use **cannot** instead of **can not**. See also [contractions](index.md#contractions). +## Chat, GitLab Duo Chat + +Use **Chat** with a capital `c` for **Chat** or **GitLab Duo Chat**. + ## checkbox Use one word for **checkbox**. Do not use **check box**. @@ -617,6 +625,14 @@ Use title case for **Geo**. Do not make **GitLab** possessive (GitLab's). This guidance follows [GitLab Trademark Guidelines](https://about.gitlab.com/handbook/marketing/brand-and-product-marketing/brand/brand-activation/trademark-guidelines/). +## GitLab Dedicated + +Do not use **Dedicated** by itself. Always use **GitLab Dedicated**. + +## GitLab Duo + +Do not use **Duo** by itself. Always use **GitLab Duo**. + ## GitLab Flavored Markdown When possible, spell out [**GitLab Flavored Markdown**](../../../user/markdown.md). @@ -1154,7 +1170,10 @@ Use lowercase for **personal access token**. ## please -Do not use **please**. For more information, see the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). +Do not use **please** in the product documentation. + +In UI text, use **please** when we've inconvenienced the user. For more information, +see the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). ## Premium @@ -1279,6 +1298,12 @@ Use lowercase for **runner managers**. These are a type of runner that can creat Use lowercase for **runner workers**. This is the process created by the runner on the host computing platform to run jobs. See also [GitLab Runner](#gitlab-runner). +## runner authentication token + +Use **runner authentication token** instead of variations like **runner token**, **authentication token**, or **token**. +Runners are assigned runner authentication tokens when they are created, and use them to authenticate with GitLab when +they execute jobs. + ## (s) Do not use **(s)** to make a word optionally plural. It can slow down comprehension. For example: @@ -1399,6 +1424,17 @@ Instead of **and/or**, use **or** or re-write the sentence. This rule also appli Do not use **slave**. Another option is **secondary**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) +## storages + +In the context of: + +- Gitaly, storage is physical and must be called a **storage**. +- Gitaly Cluster, storage can be either: + - Virtual and must be called a **virtual storage**. + - Physical and must be called a **physical storage**. + +Gitaly storages have physical paths and virtual storages have virtual paths. + ## subgroup Use **subgroup** (no hyphen) instead of **sub-group**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index ab0fe7b20a9..0c65e008436 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -33,7 +33,7 @@ We also run some documentation tests in the: ## Run tests locally -Similar to [previewing your changes locally](index.md#previewing-the-changes-live), you can also +Similar to [previewing your changes locally](review_apps.md), you can also run these tests on your local computer. This has the advantage of: - Speeding up the feedback loop. You can know of any problems with the changes in your branch @@ -274,6 +274,34 @@ You can use markdownlint: - [In a code editor](#configure-editors). - [In a `pre-push` hook](#configure-pre-push-hooks). +#### Markdown rule `MD044/proper-names` (capitalization) + +A rule that can cause confusion is `MD044/proper-names`. The failure, or +how to correct it, might not be immediately clear. +This rule checks a list of known words, listed in the `.markdownlint.yml` +file in each project, to verify proper use of capitalization and backticks. +Words in backticks are ignored by markdownlint. + +In general, product names should follow the exact capitalization of the official +names of the products, protocols, and so on. + +Some examples fail if incorrect capitalization is used: + +- MinIO (needs capital `IO`) +- NGINX (needs all capitals) +- runit (needs lowercase `r`) + +Additionally, commands, parameters, values, filenames, and so on must be +included in backticks. For example: + +- "Change the `needs` keyword in your `.gitlab-ci.yml`..." + - `needs` is a parameter, and `.gitlab-ci.yml` is a file, so both need backticks. + Additionally, `.gitlab-ci.yml` without backticks fails markdownlint because it + does not have capital G or L. +- "Run `git clone` to clone a Git repository..." + - `git clone` is a command, so it must be lowercase, while Git is the product, + so it must have a capital G. + ### Vale [Vale](https://vale.sh/) is a grammar, style, and word usage linter for the @@ -395,6 +423,8 @@ In general, follow these guidelines: At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in build pipelines. +These tools can be [integrated with your code editor](#configure-editors). + #### Install markdownlint You can install either `markdownlint-cli` or `markdownlint-cli2` to run `markdownlint`. @@ -417,30 +447,43 @@ the `image:docs-lint-markdown`. #### Install Vale -To install Install [`vale`](https://github.com/errata-ai/vale/releases) for: +Install [`vale`](https://github.com/errata-ai/vale/releases) using either: -- macOS using `brew`, run: `brew install vale`. -- Linux, use your distribution's package manager or a [released binary](https://github.com/errata-ai/vale/releases). +- The [`asdf-vale` plugin](https://github.com/pdemagny/asdf-vale) if using [`asdf`](https://asdf-vm.com). In a checkout + of a GitLab project with a `.tool-versions` file ([example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.tool-versions)), + run: -These tools can be [integrated with your code editor](#configure-editors). + ```shell + asdf plugin add vale && asdf install vale + ``` + +- A package manager: + - macOS using `brew`, run: `brew install vale`. + - Linux, use your distribution's package manager or a [released binary](https://github.com/errata-ai/vale/releases). ### Update linters -It's important to use linter versions that are the same or newer than those run in -CI/CD. This provides access to new features and possible bug fixes. +It's preferable to use linter versions that are the same as those used in our CI/CD pipelines for maximum compatibility +with the linting rules we use. + +To match the versions of `markdownlint-cli` (or `markdownlint-cli2`) and `vale` used in the GitLab projects, refer to: + +- For projects managed with `asdf`, the `.tool-versions` file in the project. For example, the + [`.tool-versions` file in the `gitlab` project](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.tool-versions). +- The [versions used (see `variables:` section)](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml) + when building the `image:docs-lint-markdown` Docker image containing these tools for CI/CD. -To match the versions of `markdownlint-cli` (or `markdownlint-cli2`) and `vale` used in the GitLab projects, refer to the -[versions used (see `variables:` section)](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml) -when building the `image:docs-lint-markdown` Docker image containing these tools for CI/CD. +Versions set in these two locations should be the same. | Tool | Version | Command | Additional information | |:--------------------|:---------|:------------------------------------------|:---------------------------------------------------------------------------------------------| | `markdownlint-cli` | Latest | `yarn global add markdownlint-cli` | None. | | `markdownlint-cli2` | Latest | `yarn global add markdownlint-cli2` | None. | -| `markdownlint-cli` | Specific | `yarn global add markdownlint-cli@0.23.2` | The `@` indicates a specific version, and this example updates the tool to version `0.23.2`. | -| `markdownlint-cli` | Specific | `yarn global add markdownlint-cli@0.6.0` | The `@` indicates a specific version, and this example updates the tool to version `0.6.0`. | -| Vale | Latest | `brew update && brew upgrade vale` | This command is for macOS only. | -| Vale | Specific | Not applicable. | Binaries can be [directly downloaded](https://github.com/errata-ai/vale/releases). | +| `markdownlint-cli` | Specific | `yarn global add markdownlint-cli@0.35.0` | The `@` indicates a specific version, and this example updates the tool to version `0.35.0`. | +| `markdownlint-cli2` | Specific | `yarn global add markdownlint-cli2@0.8.1` | The `@` indicates a specific version, and this example updates the tool to version `0.8.1`. | +| Vale (using `asdf`) | Specific | `asdf install` | Installs the version of Vale set in `.tool-versions` file in a project. | +| Vale (other) | Specific | Not applicable. | Binaries can be [directly downloaded](https://github.com/errata-ai/vale/releases). | +| Vale (using `brew`) | Latest | `brew update && brew upgrade vale` | This command is for macOS only. | ### Configure editors @@ -465,7 +508,7 @@ To configure markdownlint in your editor, install one of the following as approp To configure Vale in your editor, install one of the following as appropriate: - Sublime Text [`SublimeLinter-vale` package](https://packagecontrol.io/packages/SublimeLinter-vale). -- Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). +- Visual Studio Code [`ChrisChinchilla.vale-vscode` extension](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode). You can configure the plugin to [display only a subset of alerts](#show-subset-of-vale-alerts). - Vim [ALE plugin](https://github.com/dense-analysis/ale). - JetBrains IDEs - No plugin exists, but diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md index 381f70914c6..40039ca5b1a 100644 --- a/doc/development/documentation/topic_types/index.md +++ b/doc/development/documentation/topic_types/index.md @@ -44,9 +44,11 @@ In general, for topic titles: - Be clear and direct. Make every word count. - Use articles and prepositions. -- Follow [capitalization](../styleguide/index.md#capitalization) guidelines. +- Follow [capitalization](../styleguide/index.md#topic-titles) guidelines. - Do not repeat text from earlier topic titles. For example, if the page is about merge requests, instead of `Troubleshooting merge requests`, use only `Troubleshooting`. +- Avoid using hyphens to separate information. + For example, instead of `Internal analytics - Architecture`, use `Internal analytics architecture` or `Architecture of internal analytics`. See also [guidelines for heading levels in Markdown](../styleguide/index.md#heading-levels-in-markdown). diff --git a/doc/development/documentation/topic_types/troubleshooting.md b/doc/development/documentation/topic_types/troubleshooting.md index 70475eb0ccf..4b23117acdb 100644 --- a/doc/development/documentation/topic_types/troubleshooting.md +++ b/doc/development/documentation/topic_types/troubleshooting.md @@ -11,9 +11,25 @@ Troubleshooting topics should be the final topics on a page. If a page has more than five troubleshooting topics, put the content on a separate page that has troubleshooting information exclusively. Name the page `Troubleshooting <feature>` and in the left nav, use the word `Troubleshooting` only. -Troubleshooting can be one of three types. +## What type of troubleshooting information to include -## An introductory topic +Troubleshooting information includes: + +- Problem-solving information that might be considered risky. +- Information about rare cases. All troubleshooting information + is included, no matter how unlikely a user is to encounter a situation. + +This kind of content can be helpful to others, and the benefits outweigh the risks. +If you think you have an exception to this rule, contact the Technical Writing team. + +GitLab Support maintains their own +[troubleshooting content](../../../administration/troubleshooting/index.md). + +## Troubleshooting topic types + +Troubleshooting can be one of three types: introductory, task, or reference. + +### An introductory topic This topic introduces the troubleshooting section of a page. For example: @@ -24,12 +40,12 @@ For example: When working with <x feature>, you might encounter the following issues. ``` -## Troubleshooting task +### Troubleshooting task The title should be similar to a [standard task](task.md). For example, "Run debug tools" or "Verify syntax." -## Troubleshooting reference +### Troubleshooting reference This topic includes the error message. For example: diff --git a/doc/development/export_csv.md b/doc/development/export_csv.md index 971159e83b9..9b0205166bf 100644 --- a/doc/development/export_csv.md +++ b/doc/development/export_csv.md @@ -8,14 +8,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w This document lists the different implementations of CSV export in GitLab codebase. -| Export type | How it works | Advantages | Disadvantages | Existing examples | -|---|---|---|---|---| -| Streaming | - Query and yield data in batches to a response stream.<br>- Download starts immediately. | - Report available immediately. | - No progress indicator.<br>- Requires a reliable connection. | [Export Audit Event Log](../administration/audit_events.md#export-to-csv) | -| Downloading | - Query and write data in batches to a temporary file.<br>- Loads the file into memory.<br>- Sends the file to the client. | - Report available immediately. | - Large amount of data might cause request timeout.<br>- Memory intensive.<br>- Request expires when user navigates to a different page. | - [Export Chain of Custody Report](../user/compliance/compliance_report/index.md#chain-of-custody-report)<br>- [Export License Usage File](../subscriptions/self_managed/index.md#export-your-license-usage) | -| As email attachment | - Asynchronously process the query with background job.<br>- Email uses the export as an attachment. | - Asynchronous processing. | - Requires users use a different app (email) to download the CSV.<br>- Email providers may limit attachment size. | - [Export issues](../user/project/issues/csv_export.md)<br>- [Export merge requests](../user/project/merge_requests/csv_export.md) | -| As downloadable link in email (*) | - Asynchronously process the query with background job.<br>- Email uses an export link. | - Asynchronous processing.<br>- Bypasses email provider attachment size limit. | - Requires users use a different app (email).<br>- Requires additional storage and cleanup. | [Export User Permissions](https://gitlab.com/gitlab-org/gitlab/-/issues/1772) | -| Polling (non-persistent state) | - Asynchronously processes the query with the background job.<br>- Frontend(FE) polls every few seconds to check if CSV file is ready. | - Asynchronous processing.<br>- Automatically downloads to local machine on completion.<br>- In-app solution. | - Non-persistable request - request expires when user navigates to a different page.<br>- API is processed for each polling request. | [Export Vulnerabilities](../user/application_security/vulnerability_report/index.md#export-vulnerability-details) | -| Polling (persistent state) (*) | - Asynchronously processes the query with background job.<br>- Backend (BE) maintains the export state<br>- FE polls every few seconds to check status.<br>- FE shows 'Download link' when export is ready.<br>- User can download or regenerate a new report. | - Asynchronous processing.<br>- No database calls made during the polling requests (HTTP 304 status is returned until export status changes).<br>- Does not require user to stay on page until export is complete.<br>- In-app solution.<br>- Can be expanded into a generic CSV feature (such as dashboard / CSV API). | - Requires to maintain export states in DB.<br>- Does not automatically download the CSV export to local machine, requires users to select 'Download'. | [Export Merge Commits Report](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43055) | +| Export type | How it works | Advantages | Disadvantages | Existing examples | +|---|---|---|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Streaming | - Query and yield data in batches to a response stream.<br>- Download starts immediately. | - Report available immediately. | - No progress indicator.<br>- Requires a reliable connection. | [Export Audit Event Log](../administration/audit_events.md#export-to-csv) | +| Downloading | - Query and write data in batches to a temporary file.<br>- Loads the file into memory.<br>- Sends the file to the client. | - Report available immediately. | - Large amount of data might cause request timeout.<br>- Memory intensive.<br>- Request expires when user navigates to a different page. | - [Export Chain of Custody Report](../user/compliance/compliance_center/index.md#chain-of-custody-report)<br>- [Export License Usage File](../subscriptions/self_managed/index.md#export-your-license-usage) | +| As email attachment | - Asynchronously process the query with background job.<br>- Email uses the export as an attachment. | - Asynchronous processing. | - Requires users use a different app (email) to download the CSV.<br>- Email providers may limit attachment size. | - [Export issues](../user/project/issues/csv_export.md)<br>- [Export merge requests](../user/project/merge_requests/csv_export.md) | +| As downloadable link in email (*) | - Asynchronously process the query with background job.<br>- Email uses an export link. | - Asynchronous processing.<br>- Bypasses email provider attachment size limit. | - Requires users use a different app (email).<br>- Requires additional storage and cleanup. | [Export User Permissions](https://gitlab.com/gitlab-org/gitlab/-/issues/1772) | +| Polling (non-persistent state) | - Asynchronously processes the query with the background job.<br>- Frontend(FE) polls every few seconds to check if CSV file is ready. | - Asynchronous processing.<br>- Automatically downloads to local machine on completion.<br>- In-app solution. | - Non-persistable request - request expires when user navigates to a different page.<br>- API is processed for each polling request. | [Export Vulnerabilities](../user/application_security/vulnerability_report/index.md#export-vulnerability-details) | +| Polling (persistent state) (*) | - Asynchronously processes the query with background job.<br>- Backend (BE) maintains the export state<br>- FE polls every few seconds to check status.<br>- FE shows 'Download link' when export is ready.<br>- User can download or regenerate a new report. | - Asynchronous processing.<br>- No database calls made during the polling requests (HTTP 304 status is returned until export status changes).<br>- Does not require user to stay on page until export is complete.<br>- In-app solution.<br>- Can be expanded into a generic CSV feature (such as dashboard / CSV API). | - Requires to maintain export states in DB.<br>- Does not automatically download the CSV export to local machine, requires users to select 'Download'. | [Export Merge Commits Report](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43055) | NOTE: Export types marked as * are currently work in progress. diff --git a/doc/development/fe_guide/accessibility.md b/doc/development/fe_guide/accessibility.md index b00131b12f3..65b50bedb0c 100644 --- a/doc/development/fe_guide/accessibility.md +++ b/doc/development/fe_guide/accessibility.md @@ -518,9 +518,26 @@ Proper research and testing should be done to ensure compliance with [WCAG](http ## Automated accessibility testing with axe -You can use [axe-core](https://github.com/dequelabs/axe-core) [gems](https://github.com/dequelabs/axe-core-gems) +We use [axe-core](https://github.com/dequelabs/axe-core) [gems](https://github.com/dequelabs/axe-core-gems) to run automated accessibility tests in feature tests. +[We aim to conform to level AA of the World Wide Web Consortium (W3C) Web Content Accessibility Guidelines 2.1](https://design.gitlab.com/accessibility/a11y). + +### When to add accessibility tests + +When adding a new view to the application, make sure to include the accessibility check in your feature test. +We aim to have full coverage for all the views. + +One of the advantages of testing in feature tests is that we can check different states, not only +single components in isolation. + +Make sure to add assertions, when the view you are working on: + +- Has an empty state, +- Has significant changes in page structure, for example an alert is shown, or a new section is rendered. + +### How to add accessibility tests + Axe provides the custom matcher `be_axe_clean`, which can be used like the following: ```ruby @@ -530,10 +547,12 @@ it 'passes axe automated accessibility testing', :js do wait_for_requests # ensures page is fully loaded - expect(page).to be_axe_clean + expect(page).to be_axe_clean.according_to :wcag21aa end ``` +Make sure to specify the accessibility standard as `:wcag21aa`. + If needed, you can scope testing to a specific area of the page by using `within`. Axe also provides specific [clauses](https://github.com/dequelabs/axe-core-gems/blob/develop/packages/axe-core-rspec/README.md#clauses), @@ -543,20 +562,22 @@ for example: expect(page).to be_axe_clean.within '[data-testid="element"]' # run only WCAG 2.0 Level AA rules -expect(page).to be_axe_clean.according_to :wcag2aa +expect(page).to be_axe_clean.according_to :wcag21aa # specifies which rule to skip expect(page).to be_axe_clean.skipping :'link-in-text-block' # clauses can be chained expect(page).to be_axe_clean.within('[data-testid="element"]') - .according_to(:wcag2aa) + .according_to(:wcag21aa) ``` Axe does not test hidden regions, such as inactive menus or modal windows. To test hidden regions for accessibility, write tests that activate or render the regions visible and run the matcher again. +You can run accessibility tests locally in the same way as you [run any feature tests](../testing_guide/frontend_testing.md#how-to-run-a-feature-test). + ### Known accessibility violations This section documents violations where a recommendation differs with the [design system](https://design.gitlab.com/): diff --git a/doc/development/fe_guide/dark_mode.md b/doc/development/fe_guide/dark_mode.md index 55181edd64c..5e8f844172a 100644 --- a/doc/development/fe_guide/dark_mode.md +++ b/doc/development/fe_guide/dark_mode.md @@ -5,8 +5,7 @@ group: Development 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 --- -This page is about developing dark mode for GitLab. We also have documentation on how -[to enable dark mode](../../user/profile/preferences.md#dark-mode). +This page is about developing dark mode for GitLab. For more information on how to enable dark mode, see [Change the syntax highlighting theme]](../../user/profile/preferences.md#change-the-syntax-highlighting-theme). # How dark mode works diff --git a/doc/development/fe_guide/frontend_goals.md b/doc/development/fe_guide/frontend_goals.md new file mode 100644 index 00000000000..05e9b0df389 --- /dev/null +++ b/doc/development/fe_guide/frontend_goals.md @@ -0,0 +1,31 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Frontend Goals + +This section defined the _desired state_ of the GitLab frontend how we see it over the next few years. + +## Cluster SPAs + +Currently, GitLab mostly follows Rails architecture and Rails routing which means every single time we're changing route, we have page reload. This results in long loading times because we are: + +- rendering HAML page; +- mounting Vue applications if we have any; +- fetching data for these applications + +Ideally, we should reduce the number of times user needs to go through this long process. This would be possible with converting GitLab into a single-page application but this would require significant refactoring and is not an achieavable short/mid-term goal. + +The realistic goal is to move to _multiple SPAs_ experience where we define the _clusters_ of pages that form the user flow, and move this cluster from Rails routing to a single-page application with client-side routing. This way, we can load all the relevant context from HAML only once, and fetch all the additional data from the API depending on the route. An example of a cluster could be the following pages: + +- issues list +- issue boards +- issue details page +- new issue +- editing an issue + +All of them have the same context (project path, current user etc.), we could easily fetch more data with issue-specific parameter (issue `iid`) and store the results on the client (so that opening the same issue won't require more API calls). This leads to a smooth user experience for navigating through issues. + +For navigation between clusters, we can still rely on Rails routing. These cases should be relatively more scarce than navigation within clusters. diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index 00c7bb5d6c8..62183c7b349 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -416,7 +416,11 @@ Read more about local state management with Apollo in the [Vue Apollo documentat ### Using with Vuex -We do not recommend creating new applications with Vuex and Apollo Client combined +We do not recommend creating new applications with Vuex and Apollo Client combined. There are a few reasons: + +- VueX and Apollo are both **global stores**, which means sharing responsibilities and having two sources of truth. +- Keeping VueX and Apollo in sync can be high maintenance. +- Bugs that would come from the communication between Apollo and VueX would be subtle and hard to debug. ### Working on GraphQL-based features when frontend and backend are not in sync diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index 8675866fce6..405e830406e 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -26,6 +26,13 @@ modern ECMAScript standards supported through [Babel](https://babeljs.io/) and E When making API calls, we use [GraphQL](graphql.md) as [the first choice](../../api/graphql/index.md#vision). There are still instances where GitLab REST API is used such as when creating new simple HAML pages or in legacy part of the codebase, but we should always default to GraphQL when possible. +We use [Apollo](https://www.apollographql.com/) as our global state manager and [GraphQL client](graphql.md). +[VueX](vuex.md) is still in use across the codebase, but it is no longer the recommended global state manager. +You should **not** [use VueX and Apollo together](graphql.md#using-with-vuex), +and should [avoid adding new VueX stores](migrating_from_vuex.md) whenever possible. + +For copy strings and translations, we have frontend utilities available. Please see the JavaScript section of [Preparing a page for translation](../i18n/externalization.md#javascript-files) for more information. + Working with our frontend assets requires Node (v12.22.1 or greater) and Yarn (v1.10.0 or greater). You can find information on how to install these on our [installation guide](../../install/installation.md#5-node). @@ -56,7 +63,7 @@ GitLab is now a large, enterprise-grade software and it often requires complex c - Building tools that solve commonly-faced problems and making them easily discoverable. - Writing better documentation on how we solve our problems. -- Writing loosly coupled components that can be easily added or removed from our codebase. +- Writing loosely coupled components that can be easily added or removed from our codebase. - Remove older technologies or pattern that we deem are no longer acceptable. By focusing on these aspects, we aim to allow engineers to contain complexity in well defined boundaries and quickly share them with their peers. @@ -67,9 +74,9 @@ Now that our values have been defined, we can base our goals on these values and - Lowest possible FID, LCP and cross-page navigation times - Minimal page reloads when interacting with the UI -- Have as little Vue applications per page as possible -- Leverage Ruby ViewComponents for simple pages and avoid Vue overhead when possible -- Migrate existing VueX stores to Apollo, but more urgently **stop using both together** +- [Have as little Vue applications per page as possible](vue.md#avoid-multiple-vue-applications-on-the-page) +- Leverage [Ruby ViewComponents](view_component.md) for simple pages and avoid Vue overhead when possible +- [Migrate away from VueX](migrating_from_vuex.md), but more urgently **stop using Apollo and VueX together** - Remove jQuery from our codebase - Add a visual testing framework - Reduce CSS bundle size to a minimum @@ -77,9 +84,11 @@ Now that our values have been defined, we can base our goals on these values and - Improve our pipelines speed - Build a better set of shared components with documentation +We have detailed description on how we see GitLab frontend in the future in [Frontend Goals](frontend_goals.md) section + ### Frontend onboarding course -The [Frontend onboarding course](onboarding_course/index.md) provides a 6-week structured curriculum to learn how to contribute to the GitLab frontend. +The [Frontend onboarding course](onboarding_course/index.md) provides a 6-week structured curriculum to learn how to contribute to the GitLab frontend. ### Browser Support diff --git a/doc/development/fe_guide/merge_request_widget_extensions.md b/doc/development/fe_guide/merge_request_widget_extensions.md index f5bf9049db1..99206d99590 100644 --- a/doc/development/fe_guide/merge_request_widget_extensions.md +++ b/doc/development/fe_guide/merge_request_widget_extensions.md @@ -351,10 +351,7 @@ To generate these known events for a single widget: ``` 1. Repeat step 6, but change the `data_source` to `redis_hll`. -1. Add each of the HLL metrics to `lib/gitlab/usage_data_counters/known_events/code_review_events.yml`: - 1. `name` = (the event) - 1. `category` = `code_review` - 1. `aggregation` = `weekly` + 1. Add each event (those listed in the command in step 7, replacing `test_reports` with the appropriate name slug) to the aggregate files: 1. `config/metrics/counts_7d/{timestamp}_code_review_category_monthly_active_users.yml` diff --git a/doc/development/fe_guide/migrating_from_vuex.md b/doc/development/fe_guide/migrating_from_vuex.md new file mode 100644 index 00000000000..8dca744e192 --- /dev/null +++ b/doc/development/fe_guide/migrating_from_vuex.md @@ -0,0 +1,318 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Migrating from Vuex + +## Why? + +We have defined [GraphQL as our primary API](../../api/graphql/index.md#vision) for all user-facing features, +so we can safely assume that whenever GraphQL is present, so will the Apollo Client. +We [do not want to use Vuex with Apollo](graphql.md#using-with-vuex), so the VueX stores count +will naturally decline over time as we move from the REST API to GraphQL. + +This section gives guidelines and methods to translate an existing VueX store to +pure Vue and Apollo, or how to rely less on VueX. + +## How? + +### Overview + +As a whole, we want to understand how complex our change will be. Sometimes, we only have a few properties that are truly worth being stored in a global state and sometimes they can safely all be extracted to pure `Vue`. `VueX` properties generally fall into one of these categories: + +- Static properties +- Reactive mutable properties +- Getters +- API data + +Therefore, the first step is to read the current VueX state and determine the category of each property. + +At a high level, we could map each category with an equivalent non-VueX code pattern: + +- Static properties: Provide/Inject from Vue API. +- Reactive mutable properties: Vue events and props, Apollo Client. +- Getters: Utils functions, Apollo `update` hook, computed properties. +- API data: Apollo Client. + +Let's go through an example. In each section we refer to this state and slowly go through migrating it fully: + +```javascript +// state.js AKA our store +export default ({ blobPath = '', summaryEndpoint = '', suiteEndpoint = '' }) => ({ + blobPath, + summaryEndpoint, + suiteEndpoint, + testReports: {}, + selectedSuiteIndex: null, + isLoading: false, + errorMessage: null, + limit : 10, + pageInfo: { + page: 1, + perPage: 20, + }, +}); +``` + +### How to migrate static values + +The easiest type of values to migrate are static values, either: + +- Client-side constants: If the static value is a client-side constant, it may have been implemented + in the store for easy access by other state properties or methods. However, it is generally + a better practice to add such values to a `constants.js` file and import it when needed. +- Rails-injected dataset: These are values that we may need to provide to our Vue apps. + They are static, so adding them to the VueX store is not necessary and it could instead + be done easily through the `provide/inject` Vue API, which would be equivalent but without the VueX overhead. This should **only** be injected inside the top-most JS file that mounts our component. + +If we take a look at our example above, we can already see that two properties contain `Endpoint` in their name, which probably means that these come from our Rails dataset. To confirm this, we would search the codebase for these properties and see where they are defined, which is the case in our example. Additionally, `blobPath` is also a static property, and a little less obvious here is that `pageInfo` is actually a constant! It is never modified and is only used as a default value that we use inside our getter: + +```javascript +// state.js AKA our store +export default ({ blobPath = '', summaryEndpoint = '', suiteEndpoint = '' }) => ({ + limit + blobPath, // Static - Dataset + summaryEndpoint, // Static - Dataset + suiteEndpoint, // Static - Dataset + testReports: {}, + selectedSuiteIndex: null, + isLoading: false, + errorMessage: null, + pageInfo: { // Static - Constant + page: 1, // Static - Constant + perPage: 20, // Static - Constant + }, +}); +``` + +### How to migrate reactive mutable values + +These values are especially useful when used by a lot of different components, so we can first evaluate how many reads and writes each property gets, and how far apart these are from each other. The fewer reads there are and the closer together they live, the easier it will be to remove these properties in favor of native Vue props and events. + +#### Simple read/write values + +If we go back to our example, `selectedSuiteIndex` is only used by **one component** and also **once inside a getter**. Additionally, this getter is only used once itself! It would be quite easy to translate this logic to Vue because this could become a `data` property on the component instance. For the getter, we can use a computed property instead, or a method on the component that returns the right item because we will have access to the index there as well. This is a perfect example of how the VueX store here complicates the application by adding a lot of abstractions when really everything could live inside the same component. + +Luckily, in our example all properties could live inside the same component. However, there are cases where it will not be possible. When this happens, we can use Vue events and props to communicate between sibling components. Store the data in question inside a parent component that should know about the state, and when a child component wants to write to the component, it can `$emit` an event with the new value and let the parent update. Then, by cascading props down to all of its children, all instances of the sibling components will share the same data. + +Sometimes, it can feel that events and props are cumbersome, especially in very deep component trees. However, it is quite important to be aware that this is mostly an inconvenience issue and not an architectural flaw or problem to fix. Passing down props, even deeply nested, is a very acceptable pattern for cross-components communication. + +#### Shared read/write values + +Let's assume that we have a property in the store that is used by multiple components for read and writes that are either so numerous or far apart that Vue props and events seem like a bad solution. Instead, we use Apollo client-side resolvers. This section requires knowledge of [Apollo Client](graphql.md), so feel free to check the apollo details as needed. + +First we need to set up our Vue app to use `VueApollo`. Then when creating our store, we pass the `resolvers` and `typedefs` (defined later) to the Apollo Client: + +```javascript +import { resolvers } from "./graphql/settings.js" +import typeDefs from './graphql/typedefs.graphql'; + +... +const apolloProvider = new VueApollo({ + defaultClient: createDefaultClient({ + resolvers, // To be written soon + { typeDefs }, // We are going to create this in a sec + }), +}); +``` + +For our example, let's call our field `app.status`, and we need is to define queries and mutations that use the `@client` directives. Let's create them right now: + +```javascript +// get_app_status.query.graphql +query getAppStatus { + app @client { + status + } +} +``` + +```javascript +// update_app_status.mutation.graphql +mutation updateAppStatus($appStatus: String) { + updateAppStatus(appStatus: $appStatus) @client +} +``` + +For fields that **do not exist in our schema**, we need to set up `typeDefs`. For example: + +```javascript +// typedefs.graphql + +type TestReportApp { + status: String! +} + +extend type Query { + app: TestReportApp +} +``` + +Now we can write our resolvers so that we can update the field with our mutation: + +```javascript +// settings.js +export const resolvers = { + Mutation: { + // appStatus is the argument to our mutation + updateAppStatus: (_, { appStatus }, { cache }) => { + cache.writeQuery({ + query: getAppStatus, + data: { + app: { + __typename: 'TestReportApp', + status: appStatus, + }, + }, + }); + }, + } +} +``` + +For querying, this works without any additional instructions because it behaves like any `Object`, because querying for `app { status }` is equivalent to `app.status`. However, we need to write either a "default" `writeQuery` (to define the very first value our field will have) or we can set up the [`typePolicies` for our `cacheConfig`](graphql.md#local-state-with-apollo) to provide this default value. + +So now when we want to read from this value, we can use our local query. When we need to update it, we can call the mutation and pass the new value as an argument. + +#### Network-related values + +There are values like `isLoading` and `errorMessage` which are tied to the network request state. These are read/write properties, but will easily be replaced later with Apollo Client's own capabilities without us doing any extra work: + +```javascript +// state.js AKA our store +export default ({ blobPath = '', summaryEndpoint = '', suiteEndpoint = '' }) => ({ + blobPath, // Static - Dataset + summaryEndpoint, // Static - Dataset + suiteEndpoint, // Static - Dataset + testReports: {}, + selectedSuiteIndex: null, // Mutable -> data property + isLoading: false, // Mutable -> tied to network + errorMessage: null, // Mutable -> tied to network + pageInfo: { // Static - Constant + page: 1, // Static - Constant + perPage: 20, // Static - Constant + }, +}); +``` + +### How to migrate getters + +Getters have to be reviewed case-by-case, but a general guideline is that it is highly possible to write a pure JavaScript util function that takes as an argument the state values we used to use inside the getter, and then return whatever value we want. Consider the following getter: + +```javascript +// getters.js +export const getSelectedSuite = (state) => + state.testReports?.test_suites?.[state.selectedSuiteIndex] || {}; +``` + +All that we do here is reference two state values, which can both become arguments to a function: + +```javascript +//new_utils.js +export const getSelectedSuite = (testReports, selectedSuiteIndex) => + testReports?.test_suites?.[selectedSuiteIndex] || {}; +``` + +This new util can then be imported and used as it previously was, but directly inside the component. Also, most of the specs for the getters can be ported to the utils quite easily because the logic is preserved. + +### How to migrate API data + +Our last property is called `testReports` and it is fetched via an `axios` call to the API. We assume that we are in a pure REST application and that GraphQL data is not yet available: + +```javascript +// actions.js +export const fetchSummary = ({ state, commit, dispatch }) => { + dispatch('toggleLoading'); + + return axios + .get(state.summaryEndpoint) + .then(({ data }) => { + commit(types.SET_SUMMARY, data); + }) + .catch(() => { + createAlert({ + message: s__('TestReports|There was an error fetching the summary.'), + }); + }) + .finally(() => { + dispatch('toggleLoading'); + }); +}; +``` + +We have two options here. If this action is only used once, there is nothing preventing us from just moving all of this code from the `actions.js` file to the component that does the fetching. Then, it would be easy to remove all the state related code in favor of `data` properties. In that case, `isLoading` and `errorMessages` would both live along with it because it's only used once. + +If we are reusing this function multiple time (or plan to), then that Apollo Client can be leveraged to do what it does best: network calls and caching. In this section, we assume Apollo Client knowledge and that you know how to set it up, but feel free to read through [the GraphQL documentation](graphql.md). + +We can use a local GraphQL query (with an `@client` directive) to structure how we want to receive the data, and then use a client-side resolver to tell Apollo Client how to resolve that query. We can take a look at our REST call in the browser network tab and determine which structure suits the use case. In our example, we could write our query like: + +```graphql +query getTestReportSummary($fullPath: ID!, $iid: ID!, endpoint: String!) { + project(fullPath: $fullPath){ + id, + pipeline(iid: $iid){ + id, + testReportSummary(endpoint: $endpoint) @client { + testSuites{ + nodes{ + name + totalTime, + # There are more fields here, but they aren't needed for our example + } + } + } + } + } +} +``` + +The structure here is arbitrary in the sense that we could write this however we want. It might be tempting to skip the `project.pipeline.testReportSummary` because this is not how the REST call is structured. However, by making the query structure compliant with the `GraphQL` API, we will not need to modify our query if we do decide to transition to `GraphQL` later, and can simply remove the `@client` directive. This also gives us **caching for free** because if we try to fetch the summary again for the same pipeline, Apollo Client knows that we already have the result! + +Additionally, we are passing an `endpoint` argument to our field `testReportSummary`. This would not be necessary in pure `GraphQL`, but our resolver is going to need that information to make the `REST` call later. + +Now we need to write a client-side resolver. When we mark a field with an `@client` directive, it is **not sent to the server**, and Apollo Client instead expects us to [define our own code to resolve the value](graphql.md#using-client-side-resolvers). We can write a client-side resolver for `testReportSummary` inside the `cacheConfig` object that we pass to Apollo Client. We want this resolver to make the Axios call and return whatever data structure we want. That this is also the perfect place to transfer a getter if it was always used when accessing the API data or massaging the data structure: + +```javascript +// graphql_config.js +export const resolvers = { + Query: { + testReportSummary(_, { summaryEndpoint }): { + return axios.get(summaryEndpoint).then(({ data }) => { + return data // we could format/massage our data here instead of using a getter + } + } +} +``` + +Any time we make a call to the `testReportSummary @client` field, this resolver is executed and returns the result of the operation, which is essentially doing the same job as the `VueX` action did. + +If we assume that our GraphQL call is stored inside a data property called `testReportSummary`, we can replace `isLoading` with `this.$apollo.queries.testReportSummary.lodaing` in any component that fires this query. Errors can be handled inside the `error` hook of the Query. + +### Migration strategy + +Now that we have gone through each type of data, let's review how to plan for the transition between a VueX-based store and one without. We are trying to avoid VueX and Apollo coexisting, so the less time where both stores are available in the same context the better. To minimize this overlap, we should start our migration by removing from the store all that does not involve adding an Apollo store. Each of the following point could be its own MR: + +1. Migrate away from Static values, both `Rails` dataset and client-side constants and use `provide/inject` and `constants.js` files instead. +1. Replace simple read/write operations with either: + - `data` properties and `methods` if in a single component. + - `props` and `emits` if shared across a localized group of components. +1. Replace shared read/write operations with Apollo Client `@client` directives. +1. Replace network data with Apollo Client, either with actual GraphQL calls when available or by using client-side resolvers to make REST calls. + +If it is impossible to quickly replace shared read/write operations or network data (for example in one or two milestones), consider making a different Vue component behind a feature flag that is exclusively functional with Apollo Client, and rename the current component that uses VueX with a `legacy-` prefix. The newer component might not be able to implement all functionality right away, but we can progressively add them as we make MRs. This way, our legacy component is exclusively using VueX as a store and the new one is only Apollo. After the new component has re-implemented all the logic, we can turn the Feature Flag on and ensure that it behaves as expected. + +## FAQ + +### What if I need a global store without any network call? + +This is a rare occurrence and should suggest the following question: "Do I **really** need a global store then?" (the answer is probably no!) If the answer is yes, then you can use the [shared read/write technique with Apollo](#how-to-migrate-reactive-mutable-values) described above. It is perfectly acceptable to use Apollo Client for client-side exclusive stores. + +### Are we going to use Pinia? + +The short answer is: we don't know, but it is unlikely. It would still mean having two global store libraries, which has the same downsides as VueX and Apollo Client coexisting. Reducing the size of our global stores is positive regardless of whether we end up using Pinia though! + +### Apollo client is really verbose for client directives. Can I mix and match with VueX? + +Mixing and matching is not recommended. There are a lot of reasons why, but think of how codebases grow organically with what is available. Even if you were really good at separating your network state and your client-side state, other developers might not share the same dedication or simply not understand how to choose what lives in which store. Over time, you will also nearly inevitably need to communicate between your VueX store and Apollo Client, which can only result in problems. diff --git a/doc/development/fe_guide/tooling.md b/doc/development/fe_guide/tooling.md index 762ef852d74..c1084ab4453 100644 --- a/doc/development/fe_guide/tooling.md +++ b/doc/development/fe_guide/tooling.md @@ -155,6 +155,19 @@ $ grep "eslint-disable.*import/no-deprecated" -r . ./app/assets/javascripts/issuable_form.js: // eslint-disable-next-line import/no-deprecated ``` +### `vue/multi-word-component-names` is disabled in my file + +Single name components are discouraged by the +[Vue style guide](https://vuejs.org/style-guide/rules-essential.html#use-multi-word-component-names). + +They are problematic because they can be confused with other HTML components: We could name a +component `<table>` and it would stop rendering an HTML `<table>`. + +To solve this, you should rename the `.vue` file and its references to use at least two words, +for example: + +- `user/table.vue` could be renamed to `user/users_table.vue` and be imported as `UsersTable` and used with `<users-table />`. + ### GraphQL schema and operations validation We use [`@graphql-eslint/eslint-plugin`](https://www.npmjs.com/package/@graphql-eslint/eslint-plugin) diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index e096d25f2d9..06d7070b855 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vuex -[Vuex](https://vuex.vuejs.org) should no longer be considered a preferred path to store management and is currently in its legacy phase. This means it is acceptable to add upon existing `Vuex` stores, but we strongly recommend reducing store sizes over time and eventually migrating fully to [Apollo](https://www.apollographql.com/) whenever it's possible. Before adding any new `Vuex` store to an application, first ensure that the `Vue` application you plan to add it into **does not use** `Apollo`. `Vuex` and `Apollo` should not be combined unless absolutely necessary. Please consider reading through [our GraphQL documentation](../fe_guide/graphql.md) for more guidelines on how you can build `Apollo` based applications. +[Vuex](https://vuex.vuejs.org) should no longer be considered a preferred path to store management and is currently in its legacy phase. This means it is acceptable to add upon existing `Vuex` stores, but we strongly recommend reducing store sizes over time and eventually [migrating away from VueX entirely](migrating_from_vuex.md). Before adding any new `Vuex` store to an application, first ensure that the `Vue` application you plan to add it into **does not use** `Apollo`. `Vuex` and `Apollo` should not be combined unless absolutely necessary. Please consider reading through [our GraphQL documentation](../fe_guide/graphql.md) for more guidelines on how you can build `Apollo` based applications. The information included in this page is explained in more detail in the official [Vuex documentation](https://vuex.vuejs.org). @@ -40,6 +40,7 @@ applications stored in this [repository](https://gitlab.com/gitlab-org/gitlab/-/ This is the entry point for our store. You can use the following as a guide: ```javascript +// eslint-disable-next-line no-restricted-imports import Vuex from 'vuex'; import * as actions from './actions'; import * as getters from './getters'; @@ -287,6 +288,7 @@ function when mounting your Vue component: // in the Vue app's initialization script (for example, mount_show.js) import Vue from 'vue'; +// eslint-disable-next-line no-restricted-imports import Vuex from 'vuex'; import { createStore } from './stores'; import AwesomeVueApp from './components/awesome_vue_app.vue' @@ -372,6 +374,7 @@ when [providing data to a Vue app](vue.md#providing-data-from-haml-to-javascript ```javascript <script> +// eslint-disable-next-line no-restricted-imports import { mapActions, mapState, mapGetters } from 'vuex'; export default { @@ -433,6 +436,7 @@ components, we need to include the store and provide the correct state: ```javascript //component_spec.js import Vue from 'vue'; +// eslint-disable-next-line no-restricted-imports import Vuex from 'vuex'; import { mount } from '@vue/test-utils'; import { createStore } from './store'; diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index d9eb29a7b7f..8c0f7faab28 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -199,7 +199,7 @@ Only feature flags that have a YAML definition file can be used when running the ```shell $ bin/feature-flag my_feature_flag ->> Specify the group introducing the feature flag, like `group::apm`: +>> Specify the group introducing the feature flag, like `group::project management`: ?> group::application performance >> URL of the MR introducing the feature flag (enter to skip): @@ -231,6 +231,20 @@ the feature flag is set to enabled. If the feature contains any database migrati NOTE: To create a feature flag that is only used in EE, add the `--ee` flag: `bin/feature-flag --ee` +### Naming new flags + +When choosing a name for a new feature flag, consider the following guidelines: + +- A long, descriptive name is better than a short but confusing one. +- Write the name in snake case (`my_cool_feature_flag`). +- Avoid using `disable` in the name to avoid having to think (or [document](../documentation/feature_flags.md)) + with double negatives. Consider starting the name with `hide_`, `remove_`, or `disallow_`. + + In software engineering this problem is known as + ["negative names for boolean variables"](https://www.serendipidata.com/posts/naming-guidelines-for-boolean-variables). + But we can't forbid negative words altogether, to be able to introduce flags as + [disabled by default](#feature-flags-in-gitlab-development), use them to remove a feature by moving it behind a flag, or to [selectively disable a flag by actor](controls.md#selectively-disable-by-actor). + ### Risk of a broken master (main) branch WARNING: @@ -543,6 +557,8 @@ to ensure the feature works properly. If automated tests are not included for bo with the untested code path should be manually tested before deployment to production. When using the testing environment, all feature flags are enabled by default. +Flags can be disabled by default in the [`spec/spec_helper.rb` file](https://gitlab.com/gitlab-org/gitlab/-/blob/b61fba42eea2cf5bb1ca64e80c067a07ed5d1921/spec/spec_helper.rb#L274). +Please add a comment inline to explain why the flag needs to be disabled. You can also attach the issue URL for reference if possible. WARNING: This does not apply to end-to-end (QA) tests, which [do not enable feature flags by default](#end-to-end-qa-tests). There is a different [process for using feature flags in end-to-end tests](../testing_guide/end_to_end/feature_flags.md). @@ -557,6 +573,25 @@ stub_feature_flags(ci_live_trace: false) Feature.enabled?(:ci_live_trace) # => false ``` +A common pattern of testing both paths looks like: + +```ruby +it 'ci_live_trace works' do + # tests assuming ci_live_trace is enabled in tests by default + Feature.enabled?(:ci_live_trace) # => true +end + +context 'when ci_live_trace is disabled' do + before do + stub_feature_flags(ci_live_trace: false) + end + + it 'ci_live_trace does not work' do + Feature.enabled?(:ci_live_trace) # => false + end +end +``` + If you wish to set up a test where a feature flag is enabled only for some actors and not others, you can specify this in options passed to the helper. For example, to enable the `ci_live_trace` diff --git a/doc/development/features_inside_dot_gitlab.md b/doc/development/features_inside_dot_gitlab.md index f55d7e52fbc..a1f5111d6f4 100644 --- a/doc/development/features_inside_dot_gitlab.md +++ b/doc/development/features_inside_dot_gitlab.md @@ -16,4 +16,6 @@ When implementing new features, please refer to these existing features to avoid - [Route Maps](../ci/review_apps/index.md#route-maps): `.gitlab/route-map.yml`. - [Customize Auto DevOps Helm Values](../topics/autodevops/customize.md#customize-helm-chart-values): `.gitlab/auto-deploy-values.yaml`. - [Insights](../user/project/insights/index.md#configure-project-insights): `.gitlab/insights.yml`. -- [Service Desk Templates](../user/project/service_desk.md#customize-emails-sent-to-the-requester): `.gitlab/service_desk_templates/`. +- [Service Desk Templates](../user/project/service_desk/index.md#customize-emails-sent-to-the-requester): `.gitlab/service_desk_templates/`. +- [Secret Detection Custom Rulesets](../user/application_security/secret_detection/index.md#disable-predefined-analyzer-rules): `.gitlab/secret-detection-ruleset.toml` +- [Static Analysis Custom Rulesets](../user/application_security/sast/customize_rulesets.md#create-the-configuration-file): `.gitlab/sast-ruleset.toml` diff --git a/doc/development/fips_compliance.md b/doc/development/fips_compliance.md index bab4d7705f9..4f6a9feb191 100644 --- a/doc/development/fips_compliance.md +++ b/doc/development/fips_compliance.md @@ -60,7 +60,6 @@ listed here that also do not work properly in FIPS mode: - [Code Quality](../ci/testing/code_quality.md) does not support operating in FIPS-compliant mode. - [Dependency scanning](../user/application_security/dependency_scanning/index.md) support for Gradle. - [Dynamic Application Security Testing (DAST)](../user/application_security/dast/proxy-based.md) supports a reduced set of analyzers. The proxy-based analyzer is not available in FIPS mode today, however browser-based DAST, DAST API, and DAST API Fuzzing images are available. -- [License compliance](../user/compliance/license_compliance/index.md). - [Solutions for vulnerabilities](../user/application_security/vulnerabilities/index.md#resolve-a-vulnerability) for yarn projects. - [Static Application Security Testing (SAST)](../user/application_security/sast/index.md) @@ -118,48 +117,8 @@ for more details. The following instructions build on the Quick Start and are al ##### Terraform: Use a FIPS AMI -1. Follow the guide to set up Terraform and Ansible. -1. After [step 2b](https://gitlab.com/gitlab-org/gitlab-environment-toolkit/-/blob/main/docs/environment_quick_start_guide.md#2b-setup-config), - create a `data.tf` in your environment (for example, `gitlab-environment-toolkit/terraform/environments/gitlab-10k/inventory/data.tf`): - - ```tf - data "aws_ami" "ubuntu_20_04_fips" { - count = 1 - - most_recent = true - - filter { - name = "name" - values = ["ubuntu-pro-fips-server/images/hvm-ssd/ubuntu-focal-20.04-amd64-pro-fips-server-*"] - } - - filter { - name = "virtualization-type" - values = ["hvm"] - } - - owners = ["aws-marketplace"] - } - ``` - -1. Add the custom `ami_id` to use this AMI in `environment.tf`. For - example, in `gitlab-environment-toolkit/terraform/environments/gitlab-10k/inventory/environment.tf`: - - ```tf - module "gitlab_ref_arch_aws" { - source = "../../modules/gitlab_ref_arch_aws" - - prefix = var.prefix - ami_id = data.aws_ami.ubuntu_20_04_fips[0].id - ... - ``` - -NOTE: -GET does not allow the AMI to change on EC2 instances after it has -been deployed via `terraform apply`. Since an AMI change would tear down -an instance, this would result in data loss: not only would disks be -destroyed, but also GitLab secrets would be lost. There is a [Terraform lifecycle rule](https://gitlab.com/gitlab-org/gitlab-environment-toolkit/blob/2aaeaff8ac8067f23cd7b6bb5bf131061649089d/terraform/modules/gitlab_aws_instance/main.tf#L40) -to ignore AMI changes. +GitLab team members can view more information in this internal handbook page on how to use FIPS AMI: +`https://internal.gitlab.com/handbook/engineering/fedramp-compliance/get-configure/#terraform---use-fips-ami` ##### Ansible: Specify the FIPS Omnibus builds @@ -167,17 +126,10 @@ The standard Omnibus GitLab releases build their own OpenSSL library, which is not FIPS-validated. However, we have nightly builds that create Omnibus packages that link against the operating system's OpenSSL library. To use this package, update the `gitlab_edition` and `gitlab_repo_script_url` fields in the Ansible -`vars.yml`. For example, you might modify -`gitlab-environment-toolkit/ansible/environments/gitlab-10k/inventory/vars.yml` -in this way: +`vars.yml`. -```yaml -all: - vars: - ... - gitlab_repo_script_url: "https://packages.gitlab.com/install/repositories/gitlab/gitlab-fips/script.deb.sh" - gitlab_edition: "gitlab-fips" -``` +GitLab team members can view more information in this internal handbook page on Ansible (AWS): +`https://internal.gitlab.com/handbook/engineering/fedramp-compliance/get-configure/#ansible-aws` #### Cloud Native Hybrid @@ -231,39 +183,16 @@ be different. Building a RHEL-based system with FIPS enabled should be possible, but there is [an outstanding issue preventing the Packer build from completing](https://github.com/aws-samples/amazon-eks-custom-amis/issues/51). -##### Terraform: Use a custom EKS AMI - -Now you can set the custom EKS AMI. - -1. In `environment.tf`, add `eks_ami_id = var.eks_ami_id` so you can pass this variable to the - AWS reference architecture module. For example, in - `gitlab-environment-toolkit/terraform/environments/gitlab-10k/inventory/environment.tf`: +Because this builds a custom AMI based on a specific version of an image, you must periodically rebuild the custom AMI to keep current with the latest security patches and upgrades. - ```tf - module "gitlab_ref_arch_aws" { - source = "../../modules/gitlab_ref_arch_aws" - - prefix = var.prefix - ami_id = data.aws_ami.ubuntu_20_04_fips[0].id - eks_ami_id = var.eks_ami_id - .... - ``` - -1. In `variables.tf`, define a `eks_ami_id` with the AMI ID in the - previous step: +##### Terraform: Use a custom EKS AMI - ```tf - variable "eks_ami_id" { - default = "ami-0a25e760cd00b027e" - } - ``` +GitLab team members can view more information in this internal handbook page on how to use a custom EKS AMI: +`https://internal.gitlab.com/handbook/engineering/fedramp-compliance/get-configure/#terraform---use-a-custom-eks-ami` ##### Ansible: Use UBI images -CNG uses a Helm Chart to manage which container images to deploy. By default, GET -deploys the latest released versions that use Debian-based containers. - -To switch to UBI-based containers, edit the Ansible `vars.yml` to use custom +CNG uses a Helm Chart to manage which container images to deploy. To use UBI-based containers, edit the Ansible `vars.yml` to use custom Charts variables: ```yaml diff --git a/doc/development/gems.md b/doc/development/gems.md index 57acac7287b..c061b33b5e4 100644 --- a/doc/development/gems.md +++ b/doc/development/gems.md @@ -13,7 +13,7 @@ We extract libraries from our codebase when their functionality is highly isolated and we want to use them in other applications ourselves or we think it would benefit the wider community. -Extracting code to a gem also ensures that the gem does not contain any hidden +Extracting code to a gem also ensures that the gem does not contain any hidden dependencies on our application code. Gems should always be used when implementing functionality that can be considered isolated, @@ -36,7 +36,7 @@ You can always start by creating a new Gem [in the same repo](#in-the-same-repo) to be used by a wider community. WARNING: -To prevent malicious actors from name-squatting the extracted Gems, follow the instructions +To prevent malicious actors from name-squatting the extracted Gems, follow the instructions to [reserve a gem name](#reserve-a-gem-name). ## Advantages of using Gems @@ -81,7 +81,7 @@ and prevents complexity (coordinating changes across repos, new permissions, mul Gems stored in the same repo should be referenced in `Gemfile` with the `path:` syntax. WARNING: -To prevent malicious actors from name-squatting the extracted Gems, follow the instructions +To prevent malicious actors from name-squatting the extracted Gems, follow the instructions to [reserve a gem name](#reserve-a-gem-name). ### Create and use a new Gem @@ -236,37 +236,61 @@ The project for a new Gem should always be created in [`gitlab-org/ruby/gems` na 1. Determine a suitable name for the gem. If it's a GitLab-owned gem, prefix the gem name with `gitlab-`. For example, `gitlab-sidekiq-fetcher`. -1. Create the gem or fork as necessary. -1. Ensure the `gitlab_rubygems` group is an owner of the new gem by running: +1. Locally create the gem or fork as necessary. +1. [Publish an empty `0.0.1` version of the gem to rubygems.org](https://guides.rubygems.org/publishing/#publishing-to-rubygemsorg) to ensure the gem name is reserved. +1. Add the [`gitlab_rubygems`](https://rubygems.org/profiles/gitlab_rubygems) and [`gitlab-qa`](https://rubygems.org/profiles/gitlab-qa) users as owners of the new gem by running: ```shell gem owner <gem-name> --add gitlab_rubygems + gem owner <gem-name> --add gitlab-qa ``` -1. [Publish the gem to rubygems.org](https://guides.rubygems.org/publishing/#publishing-to-rubygemsorg) -1. Visit `https://rubygems.org/gems/<gem-name>` and verify that the gem published - successfully and `gitlab_rubygems` is also an owner. -1. Create a project in [`gitlab-org/ruby/gems` namespace](https://gitlab.com/gitlab-org/ruby/gems/). - - - To create this project: - 1. Follow the [instructions for new projects](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#creating-a-new-project). - 1. Follow the instructions for setting up a [CI/CD configuration](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#cicd-configuration). - 1. Follow the instructions for [publishing a project](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#publishing-a-project). - - See [issue #325463](https://gitlab.com/gitlab-org/gitlab/-/issues/325463) - for an example. - - In some cases we may want to move a gem to its own namespace. Some - examples might be that it will naturally have more than one project - (say, something that has plugins as separate libraries), or that we - expect users outside GitLab to be maintainers on this project as - well as GitLab team members. - - The latter situation (maintainers from outside GitLab) could also - apply if someone who currently works at GitLab wants to maintain - the gem beyond their time working at GitLab. - -When publishing a gem to RubyGems.org, also note the section on -[gem owners](https://about.gitlab.com/handbook/developer-onboarding/#ruby-gems) -in the handbook. +1. Optional. Add some or all of the following users as co-owners: + - [Marin Jankovski](https://rubygems.org/profiles/marinjankovski) + - [Rémy Coutable](https://rubygems.org/profiles/rymai) + - [Stan Hu](https://rubygems.org/profiles/stanhu) +1. Optional. Add any other relevant developers as co-owners. +1. Visit `https://rubygems.org/gems/<gem-name>` and verify that the gem was published + successfully and `gitlab_rubygems` & `gitlab-qa` are also owners. +1. Create a project in the [`gitlab-org/ruby/gems` group](https://gitlab.com/gitlab-org/ruby/gems/). To create this project: + 1. Follow the [instructions for new projects](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#creating-a-new-project). + 1. Follow the instructions for setting up a [CI/CD configuration](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#cicd-configuration). + 1. Use the [shared CI/CD config](https://gitlab.com/gitlab-org/quality/pipeline-common/-/blob/master/ci/gem-release.yml) + to release and publish new gem versions by adding the following to their `.gitlab-ci.yml`: + + ```yaml + include: + - project: 'gitlab-org/quality/pipeline-common' + file: '/ci/gem-release.yml' + ``` + + This job will handle building and publishing the gem (it uses a `gilab-qa` Rubygems.org + API token inherited from the `gitlab-org/ruby/gems` group, in order to publish the gem + package), as well as creating the tag, release and populating its release notes by + using the + [Generate changelog data](../api/repositories.md#generate-changelog-data) + API endpoint. + + For instructions for when and how to generate a changelog entry file, see the + dedicated [Changelog entries](changelog.md) + page. + [To be consistent with the GitLab project](changelog.md), + Gem projects could also define a changelog YAML configuration file at + `.gitlab/changelog_config.yml` with the same content + as [in the `gitlab-styles` gem](https://gitlab.com/gitlab-org/ruby/gems/gitlab-styles/-/blob/master/.gitlab/changelog_config.yml). + 1. To ease the release process, you could also create a `.gitlab/merge_request_templates/Release.md` MR template with the same content + as [in the `gitlab-styles` gem](https://gitlab.com/gitlab-org/ruby/gems/gitlab-styles/-/raw/master/.gitlab/merge_request_templates/Release.md) + (make sure to replace `gitlab-styles` with the actual gem name). + 1. Follow the instructions for [publishing a project](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#publishing-a-project). + +Notes: In some cases we may want to move a gem to its own namespace. Some +examples might be that it will naturally have more than one project +(say, something that has plugins as separate libraries), or that we +expect users outside GitLab to be maintainers on this project as +well as GitLab team members. +The latter situation (maintainers from outside GitLab) could also +apply if someone who currently works at GitLab wants to maintain +the gem beyond their time working at GitLab. ## The `vendor/gems/` diff --git a/doc/development/geo.md b/doc/development/geo.md index a39f97f1241..ceaa2dbb056 100644 --- a/doc/development/geo.md +++ b/doc/development/geo.md @@ -48,8 +48,7 @@ for new events and creates background jobs for each specific event type. For example when a repository is updated, the Geo **primary** site creates a Geo event with an associated repository updated event. The Geo Log Cursor daemon picks the event up and schedules a `Geo::ProjectSyncWorker` job which -uses the `Geo::RepositorySyncService` to update the repository -and `Geo::WikiSyncService` classes to update the wiki. +uses the `Geo::RepositorySyncService` to update the repository. The Geo Log Cursor daemon can operate in High Availability mode automatically. The daemon tries to acquire a lock from time to time and once acquired, it @@ -680,7 +679,7 @@ on, check out our [self-service framework](geo/framework.md). After triggering a successful [e2e:package-and-test-ee](testing_guide/end_to_end/index.md#using-the-package-and-test-job) pipeline, you can manually trigger a job named `GET:Geo`: -1. In the [GitLab project](https://gitlab.com/gitlab-org/gitlab), select the **Pipelines** tab of a merge request. +1. In the [GitLab project](https://gitlab.com/gitlab-org/gitlab), select the **Pipelines** tab of a merge request. 1. Select the `Stage: qa` stage on the latest pipeline to expand and list all the related jobs. 1. Select `trigger-omnibus` to view the [Omnibus GitLab Mirror](https://gitlab.com/gitlab-org/build/omnibus-gitlab-mirror) pipeline corresponding to the merge request. 1. The `GET:Geo` job can be found and triggered under the `trigger-qa` stage. diff --git a/doc/development/geo/proxying.md b/doc/development/geo/proxying.md index f3136890788..45c60bc370e 100644 --- a/doc/development/geo/proxying.md +++ b/doc/development/geo/proxying.md @@ -88,44 +88,6 @@ Primary-->>Secondary: /group/project logged in response (session on primary crea Secondary-->>Client: proxy full response ``` -### Requests requiring a user session on the secondary - -At the moment, this flow only applies to Project Replication Details and Design Replication Details in the Geo Admin -Area. For more context, see -[View replication data on the primary site](../../administration/geo/index.md#view-replication-data-on-the-primary-site). - -```mermaid -sequenceDiagram -autoNumber -participant Client -participant Secondary -participant Primary - -Client->>Secondary: `admin/geo/replication/projects` request -opt secondary not signed in -Secondary-->>Client: 302 redirect -Client->>Secondary: /users/auth/geo/sign_in -Secondary-->>Client: 302 redirect -Client->>Secondary: /oauth/geo/auth/geo/sign_in -Secondary-->>Client: 302 redirect -Client->>Secondary: /oauth/authorize -Secondary->>Primary: proxy /oauth/authorize -opt primary not signed in -Primary-->>Secondary: 302 redirect -Secondary-->>Client: proxy 302 redirect -Client->>Secondary: /users/sign_in -Secondary->>Primary: proxy /users/sign_in -Note right of Primary: authentication happens, POST to same URL etc -end -Primary-->>Secondary: 302 redirect -Secondary-->>Client: proxy 302 redirect -Client->>Secondary: /oauth/geo/callback -Secondary-->>Client: 302 redirect -Client->>Secondary: admin/geo/replication/projects -end -Secondary-->>Client: admin/geo/replication/projects logged in response (session on both primary and secondary) -``` - ## Git pull For historical reasons, the `push_from_secondary` path is used to forward a Git pull. There is diff --git a/doc/development/github_importer.md b/doc/development/github_importer.md index 4a24279043d..d38be071f39 100644 --- a/doc/development/github_importer.md +++ b/doc/development/github_importer.md @@ -4,25 +4,21 @@ group: unassigned 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 --- -# Working with the GitHub importer +# GitHub importer developer documentation -In GitLab 10.2 a new version of the GitHub importer was introduced. This new -importer performs its work in parallel using Sidekiq, greatly reducing the time -necessary to import GitHub projects into a GitLab instance. +The GitHub importer offers two different types of importers: -The GitHub importer offers two different types of importers: a sequential -importer and a parallel importer. The Rake task `import:github` uses the -sequential importer, and everything else uses the parallel importer. The -difference between these two importers is: +- A sequential importer. Used by the `import:github` Rake task. +- A parallel importer. Used by everything else. + +The difference between these two importers is: - The sequential importer does all the work in a single thread, so it's more suited for debugging purposes or Rake tasks. - The parallel importer uses Sidekiq. ## Prerequisites -- GitLab CE 10.2.0 or newer. -- Sidekiq workers that process the `github_importer` and - `github_importer_advance_stage` queues (this is enabled by default). +- Sidekiq workers that process the `github_importer` and `github_importer_advance_stage` queues (enabled by default). - Octokit (used for interacting with the GitHub API). ## Code structure @@ -221,14 +217,14 @@ long we're still performing work. GitHub has a rate limit of 5,000 API calls per hour. The number of requests necessary to import a project is largely dominated by the number of unique users -involved in a project (for example, issue authors). Other data such as issue pages -and comments typically only requires a few dozen requests to import. This is -because we need the Email address of users to map them to GitLab users. +involved in a project (for example, issue authors), because we need the email address of users to map +them to GitLab users. Other data such as issue pages and comments typically only requires a few dozen requests to import. -We handle this by doing the following: +We handle the rate limit by doing the following: -1. After we hit the rate limit all jobs automatically reschedule themselves - in such a way that they are not executed until the rate limit has been reset. +1. After we hit the rate limit, we either: + - Automatically reschedule jobs in such a way that they are not executed until the rate limit has been reset. + - Move onto another GitHub access token if multiple GitHub access tokens were passed to the API. 1. We cache the mapping of GitHub users to GitLab users in Redis. More information on user caching can be found below. @@ -253,7 +249,7 @@ Redis. For every user looked up we store three keys: - A Redis key mapping a GitHub Email addresses to a GitLab user ID. - A Redis key mapping a GitHub user ID to GitLab user ID. -There are two types of lookups we cache: +We cache two types of lookups: - A positive lookup, meaning we found a GitLab user ID. - A negative lookup, meaning we didn't find a GitLab user ID. Caching this diff --git a/doc/development/gitlab_shell/index.md b/doc/development/gitlab_shell/index.md index ef034761a1f..2cdfb68f84d 100644 --- a/doc/development/gitlab_shell/index.md +++ b/doc/development/gitlab_shell/index.md @@ -28,6 +28,15 @@ and support: - The current stable version. - The previous two major versions. +### Versions + +There are two version files relevent to GitLab Shell: + +- [Stable version](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/main/VERSION) +- [Version deployed in GitLab SaaS](https://gitlab.com/gitlab-org/gitlab/-/blob/master/GITLAB_SHELL_VERSION) + +GitLab team members can also monitor the `#announcements` internal Slack channel. + ## How GitLab Shell works When you access the GitLab server over SSH, GitLab Shell then: diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index e51542649bb..7648e84f5e8 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -146,8 +146,7 @@ Go GitLab linter plugins are maintained in the [`gitlab-org/language-tools/go/li Dependencies should be kept to the minimum. The introduction of a new dependency should be argued in the merge request, as per our [Approval Guidelines](../code_review.md#approval-guidelines). -Both [License Scanning](../../user/compliance/license_compliance/index.md) -and [Dependency Scanning](../../user/application_security/dependency_scanning/index.md) +[Dependency Scanning](../../user/application_security/dependency_scanning/index.md) should be activated on all projects to ensure new dependencies security status and license compatibility. diff --git a/doc/development/graphql_guide/monitoring.md b/doc/development/graphql_guide/monitoring.md index 328cea2648e..f92963dbdee 100644 --- a/doc/development/graphql_guide/monitoring.md +++ b/doc/development/graphql_guide/monitoring.md @@ -4,12 +4,7 @@ group: Import and Integrate 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 --- -# Monitoring GraphQL - -This page gives tips on how to analyze GraphQL data in our monitoring tools. -Please contribute your own tips to improve this document. - -## Kibana +# Reading GraphQL logs We use Kibana to filter GraphQL query logs. Sign in to [Kibana](https://log.gprd.gitlab.net/) with a `@gitlab.com` email address. @@ -20,7 +15,7 @@ In Kibana we can inspect two kinds of GraphQL logs: - Logs of the full request, which due to [query multiplexing](https://graphql-ruby.org/queries/multiplex.html) may have executed multiple queries. -### Logs of each GraphQL query +## Logs of each GraphQL query In a [multiplex query](https://graphql-ruby.org/queries/multiplex.html), each individual query is logged separately. We can use subcomponent filtering to inspect these logs. @@ -49,11 +44,11 @@ which already has a set of Kibana fields selected. Some relevant Kibana fields i | `json.query_analysis.duration_s` | Duration of query execution in seconds. | | `json.query_analysis.complexity` | The [complexity](../api_graphql_styleguide.md#max-complexity) score of the query. | -#### Useful filters +### Useful filters Combine the [subcomponent filter](#logs-of-each-graphql-query) with the following Kibana filters to further interrogate the query logs. -##### Queries that used a particular field +#### Queries that used a particular field Filter logs by queries that used a particular field: @@ -61,16 +56,16 @@ Filter logs by queries that used a particular field: 1. Filter: `json.query_analysis.used_fields` 1. Operator: `is` 1. Value: `Type.myField`, where `Type.myField` is the type name and field name as it - appears in [our GraphQL reference documentation](../../api/graphql/reference/index.md). + appears in [our GraphQL API resources documentation](../../api/graphql/reference/index.md). 1. Select **Refresh**. -##### Queries that used a deprecated field +#### Queries that used a deprecated field Filter logs of queries that used a particular deprecated field by following the [steps above](#queries-that-used-a-particular-field) but use the `json.graphql.used_deprecated_fields` filter instead. -### Logs of the full request +## Logs of the full request The full request logs encompass log data for all [multiplexed queries](https://graphql-ruby.org/queries/multiplex.html) in the request, as well as data from time spent outside of `GraphQLController#execute`. diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index 12ef454d234..f4ace7491eb 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -169,9 +169,9 @@ If you need to translate strings in the Vue component's JavaScript, you can impo To test Vue translations, learn about [manually testing translations from the UI](#manually-test-translations-from-the-ui). -### Test files +### Test files (RSpec) -Test expectations against externalized contents should not be hard coded, +For RSpec tests, expectations against externalized contents should not be hard coded, because we may need to run the tests with non-default locale, and tests with hard coded contents will fail. @@ -194,18 +194,19 @@ click_button _('Submit review') expect(rendered).to have_content(_('Thank you for your feedback!')) ``` -This includes JavaScript tests: +### Test files (Jest) -Bad: - -```javascript -expect(findUpdateIgnoreStatusButton().text()).toBe('Ignore'); -``` +For Frontend Jest tests, expectations do not need to reference externalization methods. Externalization is mocked +in the Frontend test environment, so the expectations are deterministic across locales +([see relevant MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128531)). -Good: +Example: ```javascript -expect(findUpdateIgnoreStatusButton().text()).toBe(__('Ignore')); +// Bad. Not necessary in Frontend environment. +expect(findText()).toBe(__('Lorem ipsum dolar sit')); +// Good. +expect(findText()).toBe('Lorem ipsum dolar sit'); ``` #### Recommendations @@ -228,58 +229,29 @@ If strings are reused throughout a component, it can be useful to define these s </template> ``` -Also consider defining these strings in a `constants.js` file, especially if they need -to be shared across different modules. - -```javascript - javascripts - │ - └───alert_settings - │ │ constants.js - │ └───components - │ │ alert_settings_form.vue - - - // constants.js - - import { s__ } from '~/locale'; - - /* Integration constants */ +If we are reusing the same translated string in multiple components, it is tempting to add them to a `constants.js` file instead and import them across our components. However, there are multiple pitfalls to this approach: - export const MSG_ALERT_SETTINGS_FORM_ERROR = __('Failed to save alert settings.') +- It creates distance between the HTML template and the copy, adding an additional level of complexity while navigating our codebase. +- Copy strings are rarely, if ever, truly the same entity. The benefit of having a reusable variable is to have one easy place to go to update a value, but for copy it is quite common to have similar strings that aren't quite the same. +Another practice to avoid when exporting copy strings is to import them in specs. While it might seem like a much more efficient test (if we change the copy, the test will still pass!) it creates additional problems: - // alert_settings_form.vue +- There is a risk that the value we import is `undefined` and we might get a false-positive in our tests (even more so if we import an `i18n` object, see [export constants as primitives](../fe_guide/style/javascript.md#export-constants-as-primitives)). +- It is harder to know what we are testing (which copy to expect). +- There is a higher risk of typos being missed because we are not re-writing the assertion, but assuming that the value of our constant is the correct one. +- The benefit of this approach is minor. Updating the copy in our component and not updating specs is not a big enough benefit to outweigh the potential issues. - import { - MSG_ALERT_SETTINGS_FORM_ERROR, - } from '../constants'; - - <script> - export default { - MSG_ALERT_SETTINGS_FROM_ERROR, - } - </script> - - <template> - <gl-alert v-if="showAlert"> - {{ $options.MSG_ALERT_SETTINGS_FORM_ERROR }} - </gl-alert> - </template> -``` - -Using either `constants` or `$options.i18n` allows us to reference messages directly in specs: +As an example: ```javascript import { MSG_ALERT_SETTINGS_FORM_ERROR } from 'path/to/constants.js'; -// okay -expect(wrapper.text()).toEqual('this test will fail just from button text changing!'); - -// better -expect(wrapper.text()).toEqual(MyComponent.i18n.buttonLabel); -// also better -expect(wrapper.text()).toEqual(MSG_ALERT_SETTINGS_FORM_ERROR); +// Bad. What is the actual text for `MSG_ALERT_SETTINGS_FORM_ERROR`? If `wrapper.text()` returns undefined, the test may still pass with the wrong values! +expect(wrapper.text()).toBe(MSG_ALERT_SETTINGS_FORM_ERROR); +// Very bad. Same problem as above and we are going through the vm property! +expect(wrapper.text()).toBe(MyComponent.vm.i18n.buttonLabel); +// Good. What we are expecting is very clear and there can be no surprises. +expect(wrapper.text()).toBe('There was an error: Please refresh and hope for the best!'); ``` ### Dynamic translations diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index 74dba53183c..cf50e417278 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -129,6 +129,8 @@ are very appreciative of the work done by translators and proofreaders! - Spanish - Pedro Garcia - [GitLab](https://gitlab.com/pedgarrod), [Crowdin](https://crowdin.com/profile/breaking_pitt) - David Elizondo - [GitLab](https://gitlab.com/daelmo), [Crowdin](https://crowdin.com/profile/daelmo) + - Pablo Reyes - [GitLab](https://gitlab.com/pabloryst9n), [Crowdin](https://crowdin.com/profile/pabloryst9n) + - Swedish - Johannes Nilsson - [GitLab](https://gitlab.com/nlssn), [Crowdin](https://crowdin.com/profile/nlssn) - Turkish diff --git a/doc/development/identity_verification.md b/doc/development/identity_verification.md index a0593905879..6895049958d 100644 --- a/doc/development/identity_verification.md +++ b/doc/development/identity_verification.md @@ -53,11 +53,35 @@ On rows where `json.event` is `Failed Attempt`, you can find valuable debugging | Reason | Description | |---------|-------------| - | `invalid_phone_number` | Either there was a typo in the phone number, or the user used a VOIP number. GitLab does not allow users to sign up with non-mobile phone numbers. | +| `invalid_phone_number` | Either there was a typo in the phone number, or the user used a VOIP number. GitLab does not allow users to sign up with non-mobile phone numbers. | | `invalid_code` | The user entered an incorrect verification code. | | `rate_limited` | The user had 10 or more failed attempts, so they were rate-limited for one hour. | | `related_to_banned_user` | The user tried a phone number already related to a banned user. | +#### View Telesign SMS status update logs + +To view logs of Telesign status updates for an SMS sent to a user: + +1. Get a `telesign_reference_id` value for an SMS sent to a specific user: + + ```plaintext + json.message: "IdentityVerification::Phone" AND json.username:<username>` + ``` + +1. Search for status update logs associated with `telesign_reference_id` value: + + ```plaintext + json.message: "IdentityVerification::Phone" AND json.event: "Telesign transaction status update" AND json.telesign_reference_id:replace_ref_id_value_here` + ``` + +Status update logs include the following fields: + +| Field | Description | +|---------|-------------| +| `telesign_status` | Delivery status of the SMS. See the [Telesign documentation](https://developer.telesign.com/enterprise/reference/smscallbacks#status-codes) for possible status codes and their descriptions. | +| `telesign_status_updated_on` | A timestamp indicating when the SMS delivery status was last updated. | +| `telesign_errors` | Errors that occurred during delivery. See the [Telesign documentation](https://developer.telesign.com/enterprise/reference/smscallbacks#status-codes) for possible error codes and their descriptions. | + ### View logs associated to a user and credit card verification To view logs associated to the [credit card stage](../security/identity_verification.md#credit-card-verification) for a user: diff --git a/doc/development/img/architecture.png b/doc/development/img/architecture.png Binary files differnew file mode 100644 index 00000000000..e63b4ba45d1 --- /dev/null +++ b/doc/development/img/architecture.png diff --git a/doc/development/img/each_batch_users_table_v13_7.png b/doc/development/img/each_batch_users_table_v13_7.png Binary files differdeleted file mode 100644 index 2e8b3fdff80..00000000000 --- a/doc/development/img/each_batch_users_table_v13_7.png +++ /dev/null diff --git a/doc/development/import_export.md b/doc/development/import_export.md index 9a7944ae308..11bddf190fa 100644 --- a/doc/development/import_export.md +++ b/doc/development/import_export.md @@ -12,10 +12,11 @@ General development guidelines and tips for the [Import/Export feature](../user/ ## Security -The Import/Export feature is constantly updated (adding new things to export), however -the code hasn't been refactored in a long time. We should perform a code audit (see -[confidential issue](../user/project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab/-/issues/20720`). +The Import/Export feature is constantly updated (adding new things to export). However, +the code hasn't been refactored in a long time. We should perform a code audit to make sure its dynamic nature does not increase the number of security concerns. +GitLab team members can view more information in this confidential issue: +`https://gitlab.com/gitlab-org/gitlab/-/issues/20720`. ### Security in the code diff --git a/doc/development/integrations/index.md b/doc/development/integrations/index.md index bd672c86b28..dd73256ce11 100644 --- a/doc/development/integrations/index.md +++ b/doc/development/integrations/index.md @@ -123,6 +123,23 @@ module Integrations end ``` +### Security enhancement features + +#### Masking channel values + +Integrations that [inherit from `Integrations::BaseChatNotification`](#define-the-integration) can hide the +values of their channel input fields. Integrations should hide these values whenever the +fields contain sensitive information such as auth tokens. + +By default, `#mask_configurable_channels?` returns `false`. To mask the channel values, override the `#mask_configurable_channels?` method in the integration to return `true`: + +```ruby +override :mask_configurable_channels? +def mask_configurable_channels? + true +end +``` + ## Define configuration test Optionally, you can define a configuration test of an integration's settings. The test is executed from the integration form's **Test** button, and results are returned to the user. @@ -156,7 +173,7 @@ module Integrations end ``` -### Customize the frontend form +## Customize the frontend form The frontend form is generated dynamically based on metadata defined in the model. @@ -181,27 +198,28 @@ This method should return an array of hashes for each field, where the keys can | `placeholder:` | string | false | | A placeholder for the form field. | `help:` | string | false | | A help text that displays below the form field. | `api_only:` | boolean | false | `false` | Specify if the field should only be available through the API, and excluded from the frontend form. +| `if:` | boolean or lambda | false | `true` | Specify if the field should be available. The value can be a boolean or a lambda. -#### Additional keys for `type: 'checkbox'` +### Additional keys for `type: 'checkbox'` | Key | Type | Required | Default | Description |:------------------|:-------|:---------|:------------------|:-- | `checkbox_label:` | string | false | Value of `title:` | A custom label that displays next to the checkbox. -#### Additional keys for `type: 'select'` +### Additional keys for `type: 'select'` | Key | Type | Required | Default | Description |:-----------|:------|:---------|:--------|:-- | `choices:` | array | true | | A nested array of `[label, value]` tuples. -#### Additional keys for `type: 'password'` +### Additional keys for `type: 'password'` | Key | Type | Required | Default | Description |:----------------------------|:-------|:---------|:------------------|:-- | `non_empty_password_title:` | string | false | Value of `title:` | An alternative label that displays when a value is already stored. | `non_empty_password_help:` | string | false | Value of `help:` | An alternative help text that displays when a value is already stored. -#### Frontend form examples +### Frontend form examples This example defines a required `url` field, and optional `username` and `password` fields: @@ -236,7 +254,7 @@ module Integrations end ``` -### Expose the integration in the REST API +## Expose the integration in the REST API To expose the integration in the [REST API](../../api/integrations.md): diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md index b8815131852..c7fbb73ca36 100644 --- a/doc/development/integrations/jira_connect.md +++ b/doc/development/integrations/jira_connect.md @@ -66,6 +66,12 @@ To avoid external dependencies like Gitpod and a Jira Cloud instance, use the [J 1. Clone the [**Jira-connect-test-tool**](https://gitlab.com/gitlab-org/manage/integrations/jira-connect-test-tool) `git clone git@gitlab.com:gitlab-org/manage/integrations/jira-connect-test-tool.git`. 1. Start the app `bundle exec rackup`. (The app requires your GDK GitLab to be available on `http://127.0.0.1:3000`.). 1. Open `config/gitlab.yml` and uncomment the `jira_connect` config. +1. If running GDK on a domain other than `localhost`, you must add the domain to `additional_iframe_ancestors`. For example: + + ```yaml + additional_iframe_ancestors: ['localhost:*', '127.0.0.1:*', 'gdk.test:*'] + ``` + 1. Restart GDK. 1. Go to `http://127.0.0.1:3000/-/profile/personal_access_tokens`. 1. Create a new token with the `api` scope and copy the token. @@ -79,24 +85,23 @@ To avoid external dependencies like Gitpod and a Jira Cloud instance, use the [J GitLab for Jira users can authenticate with GitLab using GitLab OAuth. -WARNING: -This feature is not ready for production use. The feature flag should only be enabled in development. - The following steps describe setting up an environment to test the GitLab OAuth flow: 1. Start a Gitpod session. 1. On your GitLab instance, go to **Admin > Applications**. 1. Create a new application with the following settings: - - Name: `Jira Connect` + - Name: `GitLab for Jira` - Redirect URI: `YOUR_GITPOD_INSTANCE/-/jira_connect/oauth_callbacks` - - Scopes: `api` - Trusted: **No** - Confidential: **No** -1. Copy the Application ID. + - Scopes: `api` +1. Copy the **Application ID** value. 1. Go to **Admin > Settings > General**. 1. Expand **GitLab for Jira App**. -1. Go to [gitpod.io/variables](https://gitpod.io/variables). -1. Paste the Application ID into the **Jira Connect Application ID** field and select **Save changes**. +1. Paste the **Application ID** value into **Jira Connect Application ID**. +1. In **Jira Connect Proxy URL**, enter `YOUR_GITPOD_INSTANCE` (for example, `https://xxxx.gitpod.io`). +1. Select **Enable public key storage**. +1. Select **Save changes**. ## Troubleshooting diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md index 09778127050..8fda6042fcf 100644 --- a/doc/development/integrations/secure.md +++ b/doc/development/integrations/secure.md @@ -318,8 +318,8 @@ After the deprecation period for a schema version, the file is removed from GitL declare removed versions are rejected, and an error message displays on the corresponding pipeline. If a report uses a `PATCH` version that doesn't match any vendored schema version, it is validated against -the latest vendored `PATCH` version. For example, if a report version is 14.0.23 and the latest vendored -version is 14.0.6, the report is validated against version 14.0.6. +the latest vendored `PATCH` version. For example, if a report version is 15.0.23 and the latest vendored +version is 15.0.6, the report is validated against version 15.0.6. GitLab uses the [`json_schemer`](https://www.rubydoc.info/gems/json_schemer) gem to perform validation. @@ -355,12 +355,12 @@ puts(schema_validation_errors) ``` 1. Download the appropriate schema that matches your report type and declared version. For - example, you can find version `14.0.6` of the `container_scanning` report schema at - `https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/raw/v14.0.6/dist/container-scanning-report-format.json?inline=false`. + example, you can find version `15.0.6` of the `container_scanning` report schema at + `https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/raw/v15.0.6/dist/container-scanning-report-format.json?inline=false`. 1. Save the Ruby script above in a file, for example, `validate.rb`. 1. Run the script, passing the schema and report file names as arguments in order. For example: - 1. Using your local Ruby interpreter: `ruby validate.rb container-scanning-format_14-0-6.json gl-container-scanning-report.json`. - 1. Using Docker: `docker run -it --rm -v $(pwd):/ci ruby:3-slim ruby /ci/validate.rb /ci/container-scanning-format_14-0-6.json /ci/gl-container-scanning-report.json` + 1. Using your local Ruby interpreter: `ruby validate.rb container-scanning-format_15-0-6.json gl-container-scanning-report.json`. + 1. Using Docker: `docker run -it --rm -v $(pwd):/ci ruby:3 ruby /ci/validate.rb /ci/container-scanning-format_15-0-6.json /ci/gl-container-scanning-report.json` 1. Validation errors are shown on the screen. You must resolve these errors before GitLab can ingest your report. ### Report Fields @@ -577,7 +577,7 @@ All other attributes are optional. ##### SAST -The `location` of a SAST vulnerability must have a `file` that gives the path of the affected file and +The `location` of a SAST vulnerability must have a `file` that gives the path of the affected file and a `start_line` field with the affected line number. It may also have an `end_line`, a `class`, and a `method`. diff --git a/doc/development/internal_analytics/index.md b/doc/development/internal_analytics/index.md index 8abea4c2b2f..c7cf907ca92 100644 --- a/doc/development/internal_analytics/index.md +++ b/doc/development/internal_analytics/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Internal analytics -Learn how to implement internal analytics using: +Learn how to instrument your features on GitLab using: - [Service Ping](service_ping/index.md) - [Snowplow](snowplow/index.md) diff --git a/doc/development/internal_analytics/internal_event_tracking/architecture.md b/doc/development/internal_analytics/internal_event_tracking/architecture.md new file mode 100644 index 00000000000..de5672a4895 --- /dev/null +++ b/doc/development/internal_analytics/internal_event_tracking/architecture.md @@ -0,0 +1,11 @@ +--- +stage: Analytics +group: Analytics Instrumentation +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 +--- + +# Internal event tracking architecture + +This page is under construction. It serves as placeholder for the following information. + +- Detailed architecture and other technical details diff --git a/doc/development/internal_analytics/internal_event_tracking/event_definition_guide.md b/doc/development/internal_analytics/internal_event_tracking/event_definition_guide.md new file mode 100644 index 00000000000..7e4222ead2e --- /dev/null +++ b/doc/development/internal_analytics/internal_event_tracking/event_definition_guide.md @@ -0,0 +1,11 @@ +--- +stage: Analytics +group: Analytics Instrumentation +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 +--- + +# Internal event tracking definition guide + +This page is under construction. It serves as placeholder for the following information. + +- Explanation of all parts of an event definition diff --git a/doc/development/internal_analytics/internal_event_tracking/index.md b/doc/development/internal_analytics/internal_event_tracking/index.md new file mode 100644 index 00000000000..73e9e2d1a4c --- /dev/null +++ b/doc/development/internal_analytics/internal_event_tracking/index.md @@ -0,0 +1,17 @@ +--- +stage: Analytics +group: Analytics Instrumentation +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 +--- + +# Internal Event Tracking + +This page provides detailed guidelines on using the Internal Event Tracking system to instrument features on GitLab. + +This page is a work in progress. For any questions or clarifications, reach out to us in the Slack channel [#g_analyze_analytics_instrumentation](https://gitlab.slack.com/archives/CL3A7GFPF). + +- [Introduction to internal event tracking](introduction.md#internal-event-tracking) +- [Quick start guide](quick_start.md#quick-start-for-internal-event-tracking) +- [Event definition guide](event_definition_guide.md#internal-event-tracking-definition-guide) +- [Metrics dictionary guide](../service_ping/metrics_dictionary.md#metrics-dictionary-guide) +- [Architecture](architecture.md#internal-event-tracking-architecture) diff --git a/doc/development/internal_analytics/internal_event_tracking/introduction.md b/doc/development/internal_analytics/internal_event_tracking/introduction.md new file mode 100644 index 00000000000..ebb3caa198a --- /dev/null +++ b/doc/development/internal_analytics/internal_event_tracking/introduction.md @@ -0,0 +1,13 @@ +--- +stage: Analytics +group: Analytics Instrumentation +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 +--- + +# Internal event tracking + +This page is under construction. It serves as placeholder for the following information: + +- High level introduction +- Difference between Events and Metrics +- Basic overview of the architecture diff --git a/doc/development/internal_analytics/internal_event_tracking/quick_start.md b/doc/development/internal_analytics/internal_event_tracking/quick_start.md new file mode 100644 index 00000000000..84926657a3b --- /dev/null +++ b/doc/development/internal_analytics/internal_event_tracking/quick_start.md @@ -0,0 +1,113 @@ +--- +stage: Analytics +group: Analytics Instrumentation +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 +--- + +# Quick start for internal event tracking + +In an effort to provide a more efficient, scalable, and unified tracking API, GitLab is deprecating existing RedisHLL and Snowplow tracking. Instead, we're implementing a new `track_event` method. +With this approach, we can both update RedisHLL counters and send Snowplow events simultaneously, streamlining the tracking process. + +## Create and trigger events + +### Backend tracking + +To trigger an event, call the `Gitlab::InternalEvents.track_event` method with the desired arguments: + +```ruby +Gitlab::InternalEvents.track_event( + "i_code_review_user_apply_suggestion", + user_id: user_id, + namespace_id: namespace_id, + project_id: project_id + ) +``` + +This method automatically increments all RedisHLL metrics relating to the event `i_code_review_user_apply_suggestion`, and sends a corresponding Snowplow event with all named arguments and standard context (SaaS only). + +### Frontend tracking + +#### Vue components + +In Vue components, tracking can be done with [Vue mixin](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/tracking/internal_events.js#L29). + +To implement Vue component tracking: + +1. Import the `InternalEvents` library and call the `mixin` method: + + ```javascript + import { InternalEvents } from '~/tracking'; + const trackingMixin = InternalEvents.mixin(); + ``` + +1. Use the mixin in the component: + + ```javascript + export default { + mixins: [trackingMixin], + + data() { + return { + expanded: false, + }; + }, + }; + ``` + +1. Call the `track_event` method. Tracking options can be passed as the second parameter: + + ```javascript + this.track_event('i_code_review_user_apply_suggestion'); + ``` + + Or use the `track_event` method in the template: + + ```html + <template> + <div> + <button data-testid="toggle" @click="toggle">Toggle</button> + + <div v-if="expanded"> + <p>Hello world!</p> + <button @click="track_event('i_code_review_user_apply_suggestion')">Track another event</button> + </div> + </div> + </template> + ``` + +#### Raw JavaScript + +For tracking events directly from arbitrary frontend JavaScript code, a module for raw JavaScript is provided. This can be used outside of a component context where the Mixin cannot be utilized. + +```javascript +import { InternalEvents } from '~/tracking'; +InternalEvents.track_event('i_code_review_user_apply_suggestion'); +``` + +#### Data-track attribute + +This attribute ensures that if we want to track GitLab internal events for a button, we do not need to write JavaScript code on Click handler. Instead, we can just add a data-event-tracking attribute with event value and it should work. This can also be used with haml views. + +```html + <gl-button + data-event-tracking="i_analytics_dev_ops_adoption" + > + Click Me + </gl-button> +``` + +For Haml + +```haml += render Pajamas::ButtonComponent.new(button_options: { class: 'js-settings-toggle', data: { event_tracking: 'action' }}) do +``` + +#### Internal events on render + +Sometimes we want to send internal events when the component is rendered or loaded. In these cases, we can add the `data-event-tracking-load="true"` attribute: + +```haml += render Pajamas::ButtonComponent.new(button_options: { data: { event_tracking_load: 'true', event_tracking: 'i_devops' } }) do + = _("New project") +``` diff --git a/doc/development/internal_analytics/internal_events/index.md b/doc/development/internal_analytics/internal_events/index.md index cbc7b73a282..d987317a2b0 100644 --- a/doc/development/internal_analytics/internal_events/index.md +++ b/doc/development/internal_analytics/internal_events/index.md @@ -1,98 +1,11 @@ --- -stage: Analytics -group: Analytics Instrumentation -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 +redirect_to: '../internal_event_tracking/quick_start.md' +remove_date: '2023-10-27' --- -# Internal Events development guidelines +This document was moved to [another location](../internal_event_tracking/quick_start.md). -In an effort to provide a more efficient, scalable, and unified tracking API, GitLab is deprecating existing RedisHLL and Snowplow tracking. Instead, we're implementing a new `track_event` method. -With this approach, we can both update RedisHLL counters and send Snowplow events simultaneously, streamlining the tracking process. - -## Create and trigger events - -### Backend tracking - -To trigger an event, call the `Gitlab::InternalEvents.track_event` method with the desired arguments: - -```ruby -Gitlab::InternalEvents.track_event( - "i_code_review_user_apply_suggestion", - user_id: user_id, - namespace_id: namespace_id, - project_id: project_id - ) -``` - -This method automatically increments all RedisHLL metrics relating to the event `i_code_review_user_apply_suggestion`, and sends a corresponding Snowplow event with all named arguments and standard context (SaaS only). - -### Frontend tracking - -#### Vue components - -In Vue components, tracking can be done with [Vue mixin](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/tracking/internal_events.js#L29). - -To implement Vue component tracking: - -1. Import the `InternalEvents` library and call the `mixin` method: - - ```javascript - import { InternalEvents } from '~/tracking'; - const trackingMixin = InternalEvents.mixin(); - ``` - -1. Use the mixin in the component: - - ```javascript - export default { - mixins: [trackingMixin], - - data() { - return { - expanded: false, - }; - }, - }; - ``` - -1. Call the `track_event` method. Tracking options can be passed as the second parameter: - - ```javascript - this.track_event('i_code_review_user_apply_suggestion'); - ``` - - Or use the `track_event` method in the template: - - ```html - <template> - <div> - <button data-testid="toggle" @click="toggle">Toggle</button> - - <div v-if="expanded"> - <p>Hello world!</p> - <button @click="track_event('i_code_review_user_apply_suggestion')">Track another event</button> - </div> - </div> - </template> - ``` - -#### Raw JavaScript - -For tracking events directly from arbitrary frontend JavaScript code, a module for raw JavaScript is provided. This can be used outside of a component context where the Mixin cannot be utilized. - -```javascript -import { InternalEvents } from '~/tracking'; -InternalEvents.track_event('i_code_review_user_apply_suggestion'); -``` - -#### Data-track attribute - -This attribute ensures that if we want to track GitLab internal events for a button, we do not need to write JavaScript code on Click handler. Instead, we can just add a data-event-tracking attribute with event value and it should work. This can also be used with haml views. - -```html - <gl-button - data-event-tracking="i_analytics_dev_ops_adoption" - > - Click Me - </gl-button> -``` +<!-- This redirect file can be deleted after <2023-10-27>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/internal_analytics/service_ping/implement.md b/doc/development/internal_analytics/service_ping/implement.md index 3b8243377a3..9dbfa02854d 100644 --- a/doc/development/internal_analytics/service_ping/implement.md +++ b/doc/development/internal_analytics/service_ping/implement.md @@ -21,7 +21,6 @@ To implement a new metric in Service Ping, follow these steps: 1. [Generate the SQL query](#generate-the-sql-query) 1. [Optimize queries with Database Lab](#optimize-queries-with-database-lab) 1. [Add the metric definition to the Metrics Dictionary](#add-the-metric-definition) -1. [Add the metric to the Versions Application](#add-the-metric-to-the-versions-application) 1. [Create a merge request](#create-a-merge-request) 1. [Verify your metric](#verify-your-metric) 1. [Set up and test Service Ping locally](#set-up-and-test-service-ping-locally) @@ -324,25 +323,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd/) and [P ##### Add new events -1. Define events in [`known_events`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/). - - Example event: - - ```yaml - - name: users_creating_epics - aggregation: weekly - ``` - - Keys: - - - `name`: unique event name. - - Name format for Redis HLL events `{hll_counters}_<name>` - - Example names: `users_creating_epics`, `users_triggering_security_scans`. - - - `aggregation`: may be set to a `:daily` or `:weekly` key. Defines how counting data is stored in Redis. - Aggregation on a `daily` basis does not pull more fine grained data. +1. Add an event to the required metric ([see example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20230210200054_i_ee_code_review_merge_request_widget_license_compliance_expand_weekly.yml#L17-17)) or create a metric. 1. Use one of the following methods to track the event: @@ -447,7 +428,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd/) and [P - Using the JavaScript/Vue API helper, which calls the [`UsageData` API](#usagedata-api). - Example for an existing event already defined in [known events](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/): + Example for an existing event already defined in [metric fields](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20220407125907_p_ci_templates_themekit_monthly.yml#L17-17): ```javascript import api from '~/api'; @@ -485,7 +466,6 @@ Next, get the unique events for the current week. We have the following recommendations for [adding new events](#add-new-events): -- Event aggregation: weekly. - When adding new metrics, use a [feature flag](../../../operations/feature_flags.md) to control the impact. It's recommended to disable the new feature flag by default (set `default_enabled: false`). - Events can be triggered using the `UsageData` API, which helps when there are > 10 events per change @@ -501,7 +481,7 @@ We can disable tracking completely by using the global flag: ##### Known events are added automatically in Service Data payload -Service Ping adds all events [`known_events/*.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events) to Service Data generation under the `redis_hll_counters` key. This column is stored in [version-app as a JSON](https://gitlab.com/gitlab-org/gitlab-services/version.gitlab.com/-/blob/main/db/schema.rb#L213). +Service Ping adds all events to Service Data generation under the `redis_hll_counters` key. This column is stored in [version-app as a JSON](https://gitlab.com/gitlab-org/gitlab-services/version.gitlab.com/-/blob/main/db/schema.rb#L213). For each event we add metrics for the weekly and monthly time frames, and totals for each where applicable: - `#{event_name}_weekly`: Data for 7 days for daily [aggregation](#add-new-events) events and data for the last complete week for weekly [aggregation](#add-new-events) events. @@ -540,8 +520,6 @@ Example: # Redis Counters redis_usage_data(Gitlab::UsageDataCounters::WikiPageCounter) -# Define events in common.yml https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/common.yml - # Tracking events Gitlab::UsageDataCounters::HLLRedisCounter.track_event('users_expanding_vulnerabilities', values: visitor_id) @@ -678,10 +656,6 @@ For more details, see the [database review guide](../../database_review.md#prepa See the [Metrics Dictionary guide](metrics_dictionary.md) for more information. -## Add the metric to the Versions Application - -Check if the new metric must be added to the Versions Application. See the `usage_data` [schema](https://gitlab.com/gitlab-org/gitlab-services/version.gitlab.com/-/blob/main/db/schema.rb#L152) and Service Data [parameters accepted](https://gitlab.com/gitlab-org/gitlab-services/version.gitlab.com/-/blob/main/app/services/usage_ping.rb). Any metrics added under the `counts` key are saved in the `stats` column. - ## Create a merge request Create a merge request for the new Service Ping metric, and do the following: @@ -809,13 +783,7 @@ create metric YAML definition file following [Aggregated metric instrumentation > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45979) in GitLab 13.6. -To declare the aggregate of events collected with [Redis HLL Counters](#redis-hll-counters), -you must fulfill the following requirements: - -1. All events listed at `events` attribute must come from - [`known_events/*.yml`](#known-events-are-added-automatically-in-service-data-payload) files. -1. All events listed at `events` attribute must have the same `aggregation` attribute. -1. `time_frame` does not include `all` value, which is unavailable for Redis sourced aggregated metrics. +To declare the aggregate of events collected with [Redis HLL Counters](#redis-hll-counters), make sure `time_frame` does not include the `all` value, which is unavailable for Redis-sourced aggregated metrics. While it is possible to aggregate EE-only events together with events that occur in all GitLab editions, it's important to remember that doing so may produce high variance between data collected from EE and CE GitLab instances. diff --git a/doc/development/internal_analytics/service_ping/metrics_dictionary.md b/doc/development/internal_analytics/service_ping/metrics_dictionary.md index f56955ed422..8103db5113f 100644 --- a/doc/development/internal_analytics/service_ping/metrics_dictionary.md +++ b/doc/development/internal_analytics/service_ping/metrics_dictionary.md @@ -32,7 +32,6 @@ Each metric is defined in a separate YAML file consisting of a number of fields: | Field | Required | Additional information | |---------------------|----------|----------------------------------------------------------------| | `key_path` | yes | JSON key path for the metric, location in Service Ping payload. | -| `name` (deprecated) | no | Metric name suggestion. Does not have any impact on the Service Ping payload, only serves as documentation. | | `description` | yes | | | `product_section` | yes | The [section](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/sections.yml). | | `product_stage` | yes | The [stage](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) for the metric. | @@ -71,42 +70,6 @@ NOTE: We can't control what the metric's `key_path` is, because some of them are generated dynamically in `usage_data.rb`. For example, see [Redis HLL metrics](implement.md#redis-hll-counters). -### Metric name (deprecated) - -WARNING: -This feature was deprecated in GitLab 16.1 -and is planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/411602) in 16.2. - -To improve metric discoverability by a wider audience, each metric with -instrumentation added at an appointed `key_path` receives a `name` attribute -filled with the name suggestion, corresponding to the metric `data_source` and instrumentation. -Metric name suggestions can contain two types of elements: - -1. **User input prompts**: enclosed by angle brackets (`< >`), these pieces should be replaced or - removed when you create a metrics YAML file. -1. **Fixed suggestion**: plaintext parts generated according to well-defined algorithms. - They are based on underlying instrumentation, and must not be changed. - -For a metric name to be valid, it must not include any prompt, and fixed suggestions -must not be changed. - -#### Generate a metric name suggestion (deprecated) - -WARNING: -This feature was deprecated in GitLab 16.1 -and is planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/411602) in 16.2. - -The metric YAML generator can suggest a metric name for you. -To generate a metric name suggestion, first instrument the metric at the provided `key_path`. -Then, generate the metric's YAML definition and -return to the instrumentation and update it. - -1. Add the metric instrumentation class to `lib/gitlab/usage/metrics/instrumentations/`. -1. Add the metric logic in the instrumentation class. -1. Run the [metrics YAML generator](metrics_dictionary.md#create-a-new-metric-definition). -1. Use the metric name suggestion to select a suitable metric name. -1. Update the metric's YAML definition with the correct `key_path`. - ### Metric statuses Metric definitions can have one of the following statuses: @@ -130,20 +93,16 @@ which has a related schema in `/config/metrics/objects_schemas/topology_schema.j ### Metric `time_frame` A metric's time frame is calculated based on the `time_frame` field and the `data_source` of the metric. -For `redis_hll` metrics, the type of aggregation is also taken into consideration. In this context, the term "aggregation" refers to [chosen events data storage interval](implement.md#add-new-events), and is **NOT** related to the Aggregated Metrics feature. -For more information about the aggregation type of each feature, see the [`common.yml` file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/common.yml). Weeks run from Monday to Sunday. - -| data_source | time_frame | aggregation | Description | -|------------------------|------------|----------------|-------------------------------------------------| -| any | `none` | not applicable | A type of data that's not tracked over time, such as settings and configuration information | -| `database` | `all` | not applicable | The whole time the metric has been active (all-time interval) | -| `database` | `7d` | not applicable | 9 days ago to 2 days ago | -| `database` | `28d` | not applicable | 30 days ago to 2 days ago | -| `redis` | `all` | not applicable | The whole time the metric has been active (all-time interval) | -| `redis_hll` | `7d` | `daily` | Most recent 7 complete days | -| `redis_hll` | `7d` | `weekly` | Most recent complete week | -| `redis_hll` | `28d` | `daily` | Most recent 28 complete days | -| `redis_hll` | `28d` | `weekly` | Most recent 4 complete weeks | + +| data_source | time_frame | Description | +|------------------------|------------|-------------------------------------------------| +| any | `none` | A type of data that's not tracked over time, such as settings and configuration information | +| `database` | `all` | The whole time the metric has been active (all-time interval) | +| `database` | `7d` | 9 days ago to 2 days ago | +| `database` | `28d` | 30 days ago to 2 days ago | +| `redis` | `all` | The whole time the metric has been active (all-time interval) | +| `redis_hll` | `7d` | Most recent complete week | +| `redis_hll` | `28d` | Most recent 4 complete weeks | ### Data category @@ -157,69 +116,6 @@ We use the following categories to classify a metric: An aggregate metric is a metric that is the sum of two or more child metrics. Service Ping uses the data category of the aggregate metric to determine whether or not the data is included in the reported Service Ping payload. -### Metric name suggestion examples (deprecated) - -WARNING: -This feature was deprecated in GitLab 16.1 -and is planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/411602) in 16.2. - -#### Metric with `data_source: database` - -For a metric instrumented with SQL: - -```sql -SELECT COUNT(DISTINCT user_id) FROM clusters WHERE clusters.management_project_id IS NOT NULL -``` - -- **Suggested name**: `count_distinct_user_id_from_<adjective describing: '(clusters.management_project_id IS NOT NULL)'>_clusters` -- **Prompt**: `<adjective describing: '(clusters.management_project_id IS NOT NULL)'>` - should be replaced with an adjective that best represents filter conditions, such as `project_management` -- **Final metric name**: For example, `count_distinct_user_id_from_project_management_clusters` - -For metric instrumented with SQL: - -```sql -SELECT COUNT(DISTINCT clusters.user_id) -FROM clusters_applications_helm -INNER JOIN clusters ON clusters.id = clusters_applications_helm.cluster_id -WHERE clusters_applications_helm.status IN (3, 5) -``` - -- **Suggested name**: `count_distinct_user_id_from_<adjective describing: '(clusters_applications_helm.status IN (3, 5))'>_clusters_<with>_<adjective describing: '(clusters_applications_helm.status IN (3, 5))'>_clusters_applications_helm` -- **Prompt**: `<adjective describing: '(clusters_applications_helm.status IN (3, 5))'>` - should be replaced with an adjective that best represents filter conditions -- **Final metric name**: `count_distinct_user_id_from_clusters_with_available_clusters_applications_helm` - -In the previous example, the prompt is irrelevant, and user can remove it. The second -occurrence corresponds with the `available` scope defined in `Clusters::Concerns::ApplicationStatus`. -It can be used as the right adjective to replace prompt. - -The `<with>` represents a suggested conjunction for the suggested name of the joined relation. -The person documenting the metric can use it by either: - -- Removing the surrounding `<>`. -- Using a different conjunction, such as `having` or `including`. - -#### Metric with `data_source: redis` or `redis_hll` - -For metrics instrumented with a Redis-based counter, the suggested name includes -only the single prompt to be replaced by the person working with metrics YAML. - -- **Prompt**: `<please fill metric name, suggested format is: {subject}_{verb}{ing|ed}_{object} eg: users_creating_epics or merge_requests_viewed_in_single_file_mode>` -- **Final metric name**: We suggest the metric name should follow the format of - `{subject}_{verb}{ing|ed}_{object}`, such as `user_creating_epics`, `users_triggering_security_scans`, - or `merge_requests_viewed_in_single_file_mode` - -#### Metric with `data_source: prometheus` or `system` - -For metrics instrumented with Prometheus or coming from the operating system, -the suggested name includes only the single prompt by person working with metrics YAML. - -- **Prompt**: `<please fill metric name>` -- **Final metric name**: Due to the variety of cases that can apply to this kind of metric, - no naming convention exists. Each person instrumenting a metric should use their - best judgment to come up with a descriptive name. - ### Example YAML metric definition The linked [`uuid`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/license/uuid.yml) diff --git a/doc/development/internal_analytics/service_ping/metrics_lifecycle.md b/doc/development/internal_analytics/service_ping/metrics_lifecycle.md index 7aa0eaa1554..bb3d6797011 100644 --- a/doc/development/internal_analytics/service_ping/metrics_lifecycle.md +++ b/doc/development/internal_analytics/service_ping/metrics_lifecycle.md @@ -103,4 +103,3 @@ To remove a metric: 1. Remove any other records related to the metric: - The feature flag YAML file at [`config/feature_flags/*/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/feature_flags). - - The entry in the known events YAML file at [`lib/gitlab/usage_data_counters/known_events/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/usage_data_counters/known_events). diff --git a/doc/development/internal_analytics/service_ping/review_guidelines.md b/doc/development/internal_analytics/service_ping/review_guidelines.md index 31b6c3f5580..8a46de7086e 100644 --- a/doc/development/internal_analytics/service_ping/review_guidelines.md +++ b/doc/development/internal_analytics/service_ping/review_guidelines.md @@ -51,7 +51,7 @@ are regular backend changes. #### The Analytics Instrumentation **reviewer** should - Perform a first-pass review on the merge request and suggest improvements to the author. -- Check the [metrics location](metrics_dictionary.md#metric-key_path) in +- Check the [metric's location](metrics_dictionary.md#metric-key_path) in the Service Ping JSON payload. - Add the `~database` label and ask for a [database review](../../database_review.md) for metrics that are based on Database. @@ -66,6 +66,7 @@ are regular backend changes. - Check the file location. Consider the time frame, and if the file should be under `ee`. - Check the tiers. - If a metric was changed or removed: Make sure the MR author notified the Customer Success Ops team (`@csops-team`), Analytics Engineers (`@gitlab-data/analytics-engineers`), and Product Analysts (`@gitlab-data/product-analysts`) by `@` mentioning those groups in a comment on the issue for the MR and all of these groups have acknowledged the removal. +- Make sure that the new metric is available in Service Ping payload, by running: `Gitlab::Usage::ServicePingReport.for(output: :all_metrics_values).dig(*'key_path'.split('.'))` with `key_path` substituted by the new metric's key_path. - Metrics instrumentations - Recommend using metrics instrumentation for new metrics, [if possible](metrics_instrumentation.md#support-for-instrumentation-classes). - Approve the MR, and relabel the MR with `~"analytics instrumentation::approved"`. diff --git a/doc/development/internal_analytics/service_ping/troubleshooting.md b/doc/development/internal_analytics/service_ping/troubleshooting.md index 7f7b4099d48..8f5e94506cd 100644 --- a/doc/development/internal_analytics/service_ping/troubleshooting.md +++ b/doc/development/internal_analytics/service_ping/troubleshooting.md @@ -76,7 +76,7 @@ checking the configuration file of your GitLab instance: - `/etc/gitlab/gitlab.rb` for Linux package installations and Docker. - `charts.yaml` for GitLab Helm and cloud-native Kubernetes deployments. - - `gitlab.yml` for GitLab installations from source. + - `gitlab.yml` for self-compiled installations. To check the relevant configuration file for strings that indicate whether Service Ping is disabled, you can use `grep`: diff --git a/doc/development/internal_analytics/snowplow/troubleshooting.md b/doc/development/internal_analytics/snowplow/troubleshooting.md index 2f59543e0f4..b531c6dcd56 100644 --- a/doc/development/internal_analytics/snowplow/troubleshooting.md +++ b/doc/development/internal_analytics/snowplow/troubleshooting.md @@ -21,8 +21,8 @@ You will be alarmed via a [Sisense alert](https://app.periscopedata.com/app/gitl ### Locating the problem First you need to identify at which stage in Snowplow the data pipeline the drop is occurring. -Start at [Snowplow dashboard](https://console.aws.amazon.com/systems-manager/resource-groups/cloudwatch?dashboard=SnowPlow®ion=us-east-1#) on CloudWatch, -if you do not have access to CloudWatch you need to create an [access request issue](https://gitlab.com/gitlab-com/team-member-epics/access-requests/-/issues/9730) first. +Start at [Snowplow dashboard](https://console.aws.amazon.com/systems-manager/resource-groups/cloudwatch?dashboard=SnowPlow®ion=us-east-1#) on CloudWatch. +If you do not have access to CloudWatch, GitLab team members can create an access request issue, similar to this one: `https://gitlab.com/gitlab-com/team-member-epics/access-requests/-/issues/9730`. While on CloudWatch dashboard set time range to last 4 weeks, to get better picture of system characteristics over time. Than visit following charts: 1. `ELB New Flow Count` and `Collector Auto Scaling Group Network In/Out` - they show in order: number of connections to collectors via load balancers and data volume (in bytes) processed by collectors. If there is drop visible there, it means less events were fired from the GitLab application. Proceed to [application layer guide](#troubleshooting-gitlab-application-layer) for more details @@ -42,7 +42,7 @@ or even a result of a public holiday in some regions of the world with a larger 1. Check (via [Grafana explore tab](https://dashboards.gitlab.net/explore) ) following Prometheus counters `gitlab_snowplow_events_total`, `gitlab_snowplow_failed_events_total` and `gitlab_snowplow_successful_events_total` to see how many events were fired correctly from GitLab.com. Example query to use `sum(rate(gitlab_snowplow_successful_events_total{env="gprd"}[5m])) / sum(rate(gitlab_snowplow_events_total{env="gprd"}[5m]))` would chart rate at which number of good events rose in comparison to events sent in total. If number drops from 1 it means that problem might be in communication between GitLab and AWS collectors fleet. 1. Check [logs in Kibana](https://log.gprd.gitlab.net/app/discover#) and filter with `{ "query": { "match_phrase": { "json.message": "failed to be reported to collector at" } } }` if there are some failed events logged -We conducted an investigation into an unexpected drop in snowplow events volume. +We conducted an investigation into an unexpected drop in snowplow events volume. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/335206` diff --git a/doc/development/internal_users.md b/doc/development/internal_users.md index d9f40d6f5d4..1c12e541149 100644 --- a/doc/development/internal_users.md +++ b/doc/development/internal_users.md @@ -43,7 +43,7 @@ Other examples of internal users: - [GitLab Admin Bot](https://gitlab.com/gitlab-org/gitlab/-/blob/278bc9018dd1515a10cbf15b6c6cd55cb5431407/app/models/user.rb#L950-960) - [Alert Bot](../operations/incident_management/alerts.md#trigger-actions-from-alerts) - [Ghost User](../user/profile/account/delete_account.md#associated-records) -- [Support Bot](../user/project/service_desk.md#support-bot-user) +- [Support Bot](../user/project/service_desk/index.md#support-bot-user) - Visual Review Bot - Resource access tokens, including: - [Project access tokens](../user/project/settings/project_access_tokens.md). diff --git a/doc/development/merge_request_concepts/diffs/development.md b/doc/development/merge_request_concepts/diffs/development.md index 75f961e41de..95e6fcc2170 100644 --- a/doc/development/merge_request_concepts/diffs/development.md +++ b/doc/development/merge_request_concepts/diffs/development.md @@ -64,6 +64,7 @@ contents, individual commits, and the files containing changes. external_diff_store: 1, stored_externally: nil, files_count: 9, + patch_id_sha: "d504412d5b6e6739647e752aff8e468dde093f2f", sorted: true, diff_type: "regular", verification_checksum: nil> diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 8cbf18ce9f2..65dc4de30d1 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -420,6 +420,18 @@ minimum acceptable timestamp would be 20230424000000. While the above should be considered a hard rule, it is a best practice to try to keep migration timestamps to within three weeks of the date it is anticipated that the migration will be merged upstream, regardless of how much time has elapsed since the last hard stop. +To update a migration timestamp: + +1. Migrate down the migration for the `ci` and `main` DBs: + + ```ruby + rake db:migrate:down:main VERSION=<timestamp> + rake db:migrate:down:ci VERSION=<timestamp> + ``` + +1. Delete the migration file. +1. Recreate the migration following the [migration style guide](#choose-an-appropriate-migration-type). + ## Migration helpers and versioning > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339115) in GitLab 14.3. @@ -1363,7 +1375,7 @@ end When doing so be sure to explicitly set the model's table name, so it's not derived from the class name or namespace. -Be aware of the limitations [when using models in migrations](#using-models-in-migrations-discouraged). +Be aware of the limitations [when using models in migrations](#using-application-code-in-migrations-discouraged). ### Modifying existing data @@ -1423,13 +1435,25 @@ _namespaces_ that have a `project_id`. The `path` column for these rows are renamed to their previous value followed by an integer. For example: `users` would turn into `users0` -## Using models in migrations (discouraged) - -The use of models in migrations is generally discouraged. As such models are -[contraindicated for batched background migrations](database/batched_background_migrations.md#isolation), -the model needs to be declared in the migration. - -If using a model in the migrations, you should first +## Using application code in migrations (discouraged) + +The use of application code (including models) in migrations is generally +discouraged. This is because the migrations stick around for a long time and +the application code it depends on may change and break the migration in +future. In the past some background migrations needed to use +application code in order to avoid copying hundreds of lines of code spread +across multiple files into the migration. In these rare cases it's critical to +ensure the migration has good tests so that anyone refactoring the code in +future will learn if they break the migration. Using application code is also +[discouraged for batched background migrations](database/batched_background_migrations.md#isolation) +, the model needs to be declared in the migration. + +Usually you can avoid using application code (specifically models) in a +migration by defining a class that inherits from `MigrationRecord` (see +examples below). + +If using are using a model (including defined in the migration), you should +first [clear the column cache](https://api.rubyonrails.org/classes/ActiveRecord/ModelSchema/ClassMethods.html#method-i-reset_column_information) using `reset_column_information`. diff --git a/doc/development/namespaces.md b/doc/development/namespaces.md new file mode 100644 index 00000000000..e25b0f57f08 --- /dev/null +++ b/doc/development/namespaces.md @@ -0,0 +1,302 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Namespaces + +Namespaces are containers for projects and associated resources. A `Namespace` is instantiated through its subclasses of `Group`, `ProjectNamespace`, and `UserNamespace`. + +```mermaid +graph TD + Namespace -.- Group + Namespace -.- ProjectNamespace + Namespace -.- UserNamespace +``` + +A `User` has one `UserNamespace`, and can be a member of many `Namespaces`. + +```mermaid +graph TD + Namespace -.- Group + Namespace -.- ProjectNamespace + Namespace -.- UserNamespace + + User -- has one --- UserNamespace + Namespace --- Member --- User +``` + +`Group` exists in a recursive hierarchical relationship. `Groups` have many `ProjectNamespaces` which parent one `Project`. + +```mermaid +graph TD + Group -- has many --- ProjectNamespace -- has one --- Project + Group -- has many --- Group +``` + +## Querying namespaces + +There is a set of methods provided to query the namespace hierarchy. The methods produce standard Rails `ActiveRecord::Relation` objects. +The methods can be split into two similar halves. One set of methods operate on a Namespace object, while the other set operate as composable Namespace scopes. + +By their nature, the object methods will operate within a single `Namespace` hierarchy, while the scopes can span hierarchies. + +The following is a non-exhaustive list of methods to query `Namespace` hierarchies. + +### Root namespaces + +The root is the top most `Namespace` in the hierarchy. A root has a `nil` `parent_id`. + +```mermaid +graph TD + classDef active fill:#f00,color:#fff + classDef sel fill:#00f,color:#fff + + A --- A.A --- A.A.A + A.A --- A.A.B + A --- A.B --- A.B.A + A.B --- A.B.B + + class A.A.B active + class A sel +``` + +```ruby +Namespace.where(...).roots + +namespace_object.root_ancestor +``` + +### Descendant namespaces + +The descendants of a namespace are its children, their children, and so on. + +```mermaid +graph TD + classDef active fill:#f00,color:#fff + classDef sel fill:#00f,color:#fff + + A --- A.A --- A.A.A + A.A --- A.A.B + A --- A.B --- A.B.A + A.B --- A.B.B + + class A.A active + class A.A.A,A.A.B sel +``` + +We can return ourself and our descendants through `self_and_descendants`. + +```ruby +Namespace.where(...).self_and_descendants + +namespace_object.self_and_descendants +``` + +We can return only our descendants excluding ourselves: + +```ruby +Namespace.where(...).self_and_descendants(include_self: false) + +namespace_object.descendants +``` + +We could not name the scope method `.descendants` because we would override the `Object` method of the same name. + +It can be more efficient to return the descendant IDs instead of the whole record: + +```ruby +Namespace.where(...).self_and_descendant_ids +Namespace.where(...).self_and_descendant_ids(include_self: false) + +namespace_object.self_and_descendant_ids +namespace_object.descendant_ids +``` + +### Ancestor namespaces + +The ancestors of a namespace are its children, their children, and so on. + +```mermaid +graph TD + classDef active fill:#f00,color:#fff + classDef sel fill:#00f,color:#fff + + A --- A.A --- A.A.A + A.A --- A.A.B + A --- A.B --- A.B.A + A.B --- A.B.B + + class A.A active + class A sel +``` + +We can return ourself and our ancestors through `self_and_ancestors`. + +```ruby +Namespace.where(...).self_and_ancestors + +namespace_object.self_and_ancestors +``` + +We can return only our ancestors excluding ourselves: + +```ruby +Namespace.where(...).self_and_ancestors(include_self: false) + +namespace_object.ancestors +``` + +We could not name the scope method `.ancestors` because we would override the `Module` method of the same name. + +It can be more efficient to return the ancestor ids instead of the whole record: + +```ruby +Namespace.where(...).self_and_ancstor_ids +Namespace.where(...).self_and_ancestor_ids(include_self: false) + +namespace_object.self_and_ancestor_ids +namespace_object.ancestor_ids +``` + +### Hierarchies + +A Namespace hierarchy is a `Namespace`, its ancestors, and its descendants. + +```mermaid +graph TD + classDef active fill:#f00,color:#fff + classDef sel fill:#00f,color:#fff + + A --- A.A --- A.A.A + A.A --- A.A.B + A --- A.B --- A.B.A + A.B --- A.B.B + + class A.A active + class A,A.A.A,A.A.B sel +``` + +We can query a namespace hierarchy: + +```ruby +Namespace.where(...).self_and_hierarchy + +namespace_object.self_and_hierarchy +``` + +### Recursive queries + +The queries above are known as the linear queries because they use the `namespaces.traversal_ids` column to perform standard SQL queries instead of recursive CTE queries. + +A set of legacy recursive queries are also accessible if needed: + +```ruby +Namespace.where(...).recursive_self_and_descendants +Namespace.where(...).recursive_self_and_descendants(include_self: false) +Namespace.where(...).recursive_self_and_descendant_ids +Namespace.where(...).recursive_self_and_descendant_ids(include_self: false) +Namespace.where(...).recursive_self_and_ancestors +Namespace.where(...).recursive_self_and_ancestors(include_self: false) +Namespace.where(...).recursive_self_and_ancstor_ids +Namespace.where(...).recursive_self_and_ancestor_ids(include_self: false) +Namespace.where(...).recursive_self_and_hierarchy + +namespace_object.recursive_root_ancestor +namespace_object.recursive_self_and_descendants +namespace_object.recursive_descendants +namespace_object.recursive_self_and_descendant_ids +namespace_object.recursive_descendant_ids +namespace_object.recursive_self_and_ancestors +namespace_object.recursive_ancestors +namespace_object.recursive_self_and_ancestor_ids +namespace_object.recursive_ancestor_ids +namespace_object.recursive_self_and_hierarchy +``` + +## Namespace query implementation + +The linear queries are executed using the `namespaces.traversal_ids` array column. Each array represents an ordered set of `Namespace` IDs from the root `Namespace` to the current `Namespace`. + +Given the scenario: + +```mermaid +graph TD + classDef active fill:#f00,color:#fff + classDef sel fill:#00f,color:#fff + + A --- A.A --- A.A.A + A.A --- A.A.B + A --- A.B --- A.B.A + A.B --- A.B.B + + class A.A.B active +``` + +The `traversal_ids` for `Namespace` `A.A.B` would be `[A, A.A, A.A.B]`. + +The `traversal_ids` have some useful properties to keep in mind if working in this area: + +- The root of every `Namespace` is provided by `traversal_ids[1]`. Note that PostgreSQL array indexes begin at `1`. +- The ID of the current `Namespace` is provided by `traversal_ids[array_length(traversal_ids, 1)]`. +- The `Namespace` ancestors are represented by the `traversal_ids`. +- A `Namespace`'s `traversal_ids` are a subset of their descendants `traversal_ids`. A `Namespace` with `traversal_ids = [1,2,3]` will have descendants that all start with `[1,2,3,...]`. +- PostgreSQL arrays are ordered such that `[1] < [1,1] < [2]`. + +Using these properties we find the `root` and `ancestors` are already provided for by `traversal_ids`. + +With the object descendant queries we lean on the `@>` array operator which will test inclusion of an array inside another array. +The `@>` operator has been found to be quite slow as the search space grows. Another method is used for scope queries which tend to have larger search spaces. +With scope queries we combine comparison operators with the array ordering property. + +All descendants of a `Namespace` with `traversal_ids = [1,2,3]` have `traversal_ids` that are greater than `[1,2,3]` but less than `[1,2,4]`. +In this example `[1,2,3]` and `[1,2,4]` are siblings, and `[1,2,4]` is the next sibling after `[1,2,3]`. A SQL function is provided to find the next sibling of a `traversal_ids` called `next_traversal_ids_sibling`. + +```sql +gitlabhq_development=# select next_traversal_ids_sibling(ARRAY[1,2,3]); + next_traversal_ids_sibling +---------------------------- + {1,2,4} +(1 row) +``` + +We then build descendant linear query scopes using comparison operators: + +```sql +WHERE namespaces.traversal_ids > ARRAY[1,2,3] + AND namespaces.traversal_ids < next_traversal_ids_sibling(ARRAY[1,2,3]) +``` + +### Superset + +`Namespace` queries are prone to returning duplicate results. For example, consider a query to find descendants of `A` and `A.A`: + +```mermaid +graph TD + classDef active fill:#f00,color:#fff + classDef sel fill:#00f,color:#fff + + A --- A.A --- A.A.A + A.A --- A.A.B + A --- A.B --- A.B.A + A.B --- A.B.B + + class A,A.A active + class A.A.A,A.A.B,A.B,A.B.A,A.B.B sel +``` + +```ruby +namespaces = Namespace.where(name: ['A', 'A.A']) + +namespaces.self_and_descendants + +=> A.A, A.A.A, A.A.B, A.B, A.B.A, A.B.B +``` + +Searching for the descendants of both `A` and `A.A` is unnecessary because `A.A` is already a descendant of `A`. +In extreme cases this can create excessive I/O leading to poor performance. + +Redundant `Namespaces` are eliminated from a query if a `Namespace` `ID` in the `traversal_ids` attribute matches an `ID` belonging to another `Namespace` in the set of `Namespaces` being queried. +A match of this condition signifies that an ancestor exists in the set of `Namespaces` being queried, and the current `Namespace` is therefore redundant. +This optimization will result in much better performance of edge cases that would otherwise be very slow. diff --git a/doc/development/packages/new_format_development.md b/doc/development/packages/new_format_development.md index 66e6cb89661..0af0b8ad480 100644 --- a/doc/development/packages/new_format_development.md +++ b/doc/development/packages/new_format_development.md @@ -62,7 +62,7 @@ As an MVC, we recommend beginning with a project-level endpoint. A typical itera - Publish and install in a project - Install from a group -- Publish and install in an Instance (this is for Self-Managed customers) +- Publish and install in an instance (this is for self-managed customers) Using instance-level endpoints requires [stricter naming conventions](#naming-conventions). diff --git a/doc/development/packages/settings.md b/doc/development/packages/settings.md index 33caa064ab3..0fc49c4eb5d 100644 --- a/doc/development/packages/settings.md +++ b/doc/development/packages/settings.md @@ -17,6 +17,7 @@ Setting | Table | Description `npm_package_requests_forwarding` | `application_settings` | Enables or disables npm package forwarding at the instance level. `pypi_package_requests_forwarding` | `application_settings` | Enables or disables PyPI package forwarding at the instance level. `packages_cleanup_package_file_worker_capacity` | `application_settings` | Number of concurrent workers allowed for package file cleanup. +`package_registry_allow_anyone_to_pull_option` | `application_settings` | Enables or disables the `Allow anyone to pull from Package Registry` toggle. `throttle_unauthenticated_packages_api_requests_per_period` | `application_settings` | Request limit for unauthenticated package API requests in the period defined by `throttle_unauthenticated_packages_api_period_in_seconds`. `throttle_unauthenticated_packages_api_period_in_seconds` | `application_settings` | Period in seconds to measure unauthenticated package API requests. `throttle_authenticated_packages_api_requests_per_period` | `application_settings` | Request limit for authenticated package API requests in the period defined by `throttle_authenticated_packages_api_period_in_seconds`. @@ -66,6 +67,8 @@ Setting | Table | Description `maven_duplicate_exception_regex` | `namespace_package_settings` | Regex defining Maven packages that are allowed to be duplicate when duplicates are not allowed. This matches the name and version of the package. `generic_duplicates_allowed` | `namespace_package_settings` | Allow or prevent duplicate generic packages. `generic_duplicate_exception_regex` | `namespace_package_settings` | Regex defining generic packages that are allowed to be duplicate when duplicates are not allowed. +`nuget_duplicates_allowed` | `namespace_package_settings` | Allow or prevent duplicate NuGet packages. +`nuget_duplicate_exception_regex` | `namespace_package_settings` | Regex defining NuGet packages that are allowed to be duplicate when duplicates are not allowed. Dependency Proxy Cleanup Policies - `ttl` | `dependency_proxy_image_ttl_group_policies` | Number of days to retain an unused Dependency Proxy file before it is removed. Dependency Proxy - `enabled` | `dependency_proxy_image_ttl_group_policies` | Enable or disable the Dependency Proxy cleanup policy. diff --git a/doc/development/permissions/custom_roles.md b/doc/development/permissions/custom_roles.md index 9aba4035ec9..337c8f6d96b 100644 --- a/doc/development/permissions/custom_roles.md +++ b/doc/development/permissions/custom_roles.md @@ -6,12 +6,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Custom Roles -Users can create custom roles and define those roles by assigning specific abilities. For example, a user could create an "Engineer" role with `read code` and `admin merge requests` abilities, but without abilities like `admin issues`. +Ultimate customers can create custom roles and define those roles by assigning specific abilities. -In this context: +For example, a user could create an "Engineer" role with `read code` and `admin merge requests` abilities, but without abilities like `admin issues`. -- "Ability" is an action a user can do. -- "Permission" defines the policy classes. +In this context, the terms "permission" and "ability" are often used interchangeably. + +- "Ability" is an action a user can do. These map to [Declarative Policy abilities](https://gitlab.com/gitlab-org/ruby/gems/declarative-policy/-/blob/main/doc/defining-policies.md#rules) and live in Policy classes in `ee/app/policies/*`. +- "Permission" is how we refer to an ability [in user-facing documentation](../../user/permissions.md). The documentation of permissions is manually generated so there is not necessarily a 1:1 mapping of the permissions listed in documentation and the abilities defined in Policy classes. ## Custom roles vs static roles @@ -20,18 +22,21 @@ In GitLab 15.9 and earlier, GitLab only had [static roles](predefined_roles.md) With custom roles, the customers can decide which abilities they want to assign to certain user groups. For example: - In the static role system, reading of vulnerabilities is limited to a Developer role. -- In the custom role system, a customer can assign this ability to a new custom role based on the Reporter role. - -## Technical overview +- In the custom role system, a customer can assign this ability to a new custom role based on any static role. -Individual custom roles are stored in the `member_roles` table (`MemberRole` model) and can be defined only for top-level groups. This table includes individual abilities and a `base_access_level` value. This value defines the minimum access level of: +Like static roles, custom roles are [inherited](../../user/project/members/index.md#inherited-membership) within a group hierarchy. If a user has custom role for a group, that user will also have a custom role for any projects or subgroups within the group. -- Users who can be assigned to the custom role. -- Every ability. - -For example, the `read_vulnerability` ability has a minimum access level of `Reporter`. That means only member role records with `base_access_level = REPORTER` (20) or higher can have the `read_vulnerability` value set to `true`. Also, only users who have at least the Reporter role can be assigned that ability. +## Technical overview -For now, custom role abilities are supported only at project level. +- Individual custom roles are stored in the `member_roles` table (`MemberRole` model). +- A `member_roles` record is associated with top-level groups (not subgroups) via the `namespace_id` foreign key. +- A Group or project membership (`members` record) is associated with a custom role via the `member_role_id` foreign key. +- A Group or project membership can be associated with any custom role that is defined on the root-level group of the group or project. +- The `member_roles` table includes individual permissions and a `base_access_level` value. +- The `base_access_level` must be a [valid access level](../../api/access_requests.md#valid-access-levels). +The `base_access_level` determines which abilities are included in the custom role. For example, if the `base_access_level` is `10`, the custom role will include any abilities that a static Guest role would receive, plus any additional abilities that are enabled by the `member_roles` record by setting an attribute, such as `read_code`, to true. +- A custom role can enable additional abilities for a `base_access_level` but it cannot disable a permission. As a result, custom roles are "additive only". The rationale for this choice is [in this comment](https://gitlab.com/gitlab-org/gitlab/-/issues/352891#note_1059561579). +- For now, custom role abilities are supported only at project level. There is an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/411851) to add support for custom group abilities. ## How to implement a new ability for custom roles @@ -153,6 +158,26 @@ There might be features that require additional abilities but try to minimalize This is also where your work should begin. Take all the abilities for the feature you work on, and consolidate those abilities into `read_`, `admin_`, or additional abilities if necessary. +Many abilities in the `GroupPolicy` and `ProjectPolicy` classes have many +redundant policies. There is an [epic for consolidating these Policy classes](https://gitlab.com/groups/gitlab-org/-/epics/6689). +If you encounter similar permissions in these classes, consider refactoring so +that they have the same name. + +For example, you see in `GroupPolicy` that there is an ability called +`read_group_security_dashboard` and in `ProjectPolicy` has an ability called +`read_project_security_dashboard`. You'd like to make both customizable. Rather +than adding a row to the `member_roles` table for each ability, consider +renaming them to `read_security_dashboard` and adding `read_security_dashboard` +to the `member_roles` table. This is more expected because it means that +enabling `read_security_dashboard` on the parent group will enable the custom +For example, `GroupPolicy` has an ability called `read_group_security_dashboard` and `ProjectPolicy` has an ability +called `read_project_security_dashboard`. If you would like to make both customizable, rather than adding a row to the +`member_roles` table for each ability, consider renaming them to `read_security_dashboard` and adding +`read_security_dashboard` to the `member_roles` table. This convention means that enabling `read_security_dashboard` on +the parent group will allow the custom role to access the group security dashboard and the project security dashboard +for each project in that group. Enabling the same permission on a specific project will allow access to that projects' +security dashboard. + ### Implement a new ability To add a new ability to a custom role: diff --git a/doc/development/pipelines/internals.md b/doc/development/pipelines/internals.md index c0d7bbd3713..1a4e4e738a8 100644 --- a/doc/development/pipelines/internals.md +++ b/doc/development/pipelines/internals.md @@ -294,3 +294,126 @@ qa:selectors-as-if-foss: extends: - .qa:rules:as-if-foss ``` + +### Extend the `.fast-no-clone-job` job + +Downloading the branch for the canonical project takes between 20 and 30 seconds. + +Some jobs only need a limited number of files, which we can download via the GitLab API. + +You can skip a job `git clone`/`git fetch` by adding the following pattern to a job. + +#### Scenario 1: no `before_script` is defined in the job + +This applies to the parent sections the job extends from as well. + +You can just extend the `.fast-no-clone-job`: + +**Before:** + +```yaml + # Note: No `extends:` is present in the job + a-job: + script: + - source scripts/rspec_helpers.sh scripts/slack + - echo "No need for a git clone!" +``` + +**After:** + +```yaml + # Note: No `extends:` is present in the job + a-job: + extends: + - .fast-no-clone-job + variables: + FILES_TO_DOWNLOAD: > + scripts/rspec_helpers.sh + scripts/slack + script: + - source scripts/rspec_helpers.sh scripts/slack + - echo "No need for a git clone!" +``` + +#### Scenario 2: a `before_script` block is already defined in the job (or in jobs it extends) + +For this scenario, you have to: + +1. Extend the `.fast-no-clone-job` as in the first scenario (this will merge the `FILES_TO_DOWNLOAD` variable with the other variables) +1. Make sure the `before_script` section from `.fast-no-clone-job` is referenced in the `before_script` we use for this job. + +**Before:** + +```yaml + .base-job: + before_script: + echo "Hello from .base-job" + + a-job: + extends: + - .base-job + script: + - source scripts/rspec_helpers.sh scripts/slack + - echo "No need for a git clone!" +``` + +**After:** + +```yaml + .base-job: + before_script: + echo "Hello from .base-job" + + a-job: + extends: + - .base-job + - .fast-no-clone-job + variables: + FILES_TO_DOWNLOAD: > + scripts/rspec_helpers.sh + scripts/slack + before_script: + - !reference [".fast-no-clone-job", before_script] + - !reference [".base-job", before_script] + script: + - source scripts/rspec_helpers.sh scripts/slack + - echo "No need for a git clone!" +``` + +#### Caveats + +- This pattern does not work if a script relies on `git` to access the repository, because we don't have the repository without cloning or fetching. +- The job using this pattern needs to have `curl` available. +- If you need to run `bundle install` in the job (even using `BUNDLE_ONLY`), you need to: + - Download the gems that are stored in the `gitlab-org/gitlab` project. + - You can use the `download_local_gems` shell command for that purpose. + - Include the `Gemfile`, `Gemfile.lock` and `Gemfile.checksum` (if applicable) + +#### Where is this pattern used? + +- For now, we use this pattern for the following jobs, and those do not block private repositories: + - `review-build-cng-env` for: + - `GITALY_SERVER_VERSION` + - `GITLAB_ELASTICSEARCH_INDEXER_VERSION` + - `GITLAB_KAS_VERSION` + - `GITLAB_METRICS_EXPORTER_VERSION` + - `GITLAB_PAGES_VERSION` + - `GITLAB_SHELL_VERSION` + - `scripts/trigger-build.rb` + - `VERSION` + - `review-deploy` for: + - `GITALY_SERVER_VERSION` + - `GITLAB_SHELL_VERSION` + - `scripts/review_apps/review-apps.sh` + - `scripts/review_apps/seed-dast-test-data.sh` + - `VERSION` + - `rspec:coverage` for: + - `config/bundler_setup.rb` + - `Gemfile` + - `Gemfile.checksum` + - `Gemfile.lock` + - `scripts/merge-simplecov` + - `spec/simplecov_env_core.rb` + - `spec/simplecov_env.rb` + +Additionally, `scripts/utils.sh` is always downloaded from the API when this pattern is used (this file contains the code for `.fast-no-clone-job`). diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index 0305cbf25b4..b15c4eca5ae 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -46,7 +46,7 @@ bin/rake "gitlab:seed:issues[group-path/project-path]" By default, this seeds an average of 2 issues per week for the last 5 weeks per project. -#### Seeding issues for Insights charts **(ULTIMATE)** +#### Seeding issues for Insights charts **(ULTIMATE ALL)** You can seed issues specifically for working with the [Insights charts](../user/group/insights/index.md) with the @@ -526,7 +526,7 @@ NOTE: This Rake task needs `docker` to be installed. To update generated code for OpenAPI client located in -`vendor/gems/error_tracking_open_api` run the following commands: +`gems/error_tracking_open_api` run the following commands: ```shell # Run rake task @@ -535,7 +535,7 @@ bundle exec rake gems:error_tracking_open_api:generate # Review and test the changes # Commit the changes -git commit -m 'Update ErrorTrackingOpenAPI from OpenAPI definition' vendor/gems/error_tracking_open_api +git commit -m 'Update ErrorTrackingOpenAPI from OpenAPI definition' gems/error_tracking_open_api ``` ## Update banned SSH keys diff --git a/doc/development/redis/new_redis_instance.md b/doc/development/redis/new_redis_instance.md index 00cc102b427..bc58bae45ec 100644 --- a/doc/development/redis/new_redis_instance.md +++ b/doc/development/redis/new_redis_instance.md @@ -30,8 +30,8 @@ Before we can switch any features to using the new instance, we have to support configuring it and referring to it in the codebase. We must support the main installation types: -- Source installs (including development environments) - [example MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62767) -- Omnibus - [example MR](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5316) +- Self-compiled installations (including development environments) - [example MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62767) +- Linux package installations - [example MR](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5316) - Helm charts - [example MR](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/2031) ### Fallback instance diff --git a/doc/development/reusing_abstractions.md b/doc/development/reusing_abstractions.md index bfb568d2fd2..4a964f7d3c9 100644 --- a/doc/development/reusing_abstractions.md +++ b/doc/development/reusing_abstractions.md @@ -38,7 +38,7 @@ projects = if current_user && params[:authorized_only].presence && !current_user_related? current_user.authorized_projects elsif group - finder_options = { include_subgroups: params[:include_subgroups], only_owned: true } + finder_options = { include_subgroups: params[:include_subgroups], exclude_shared: true } GroupProjectsFinder.new(group: group, current_user: current_user, options: finder_options).execute else ProjectsFinder.new(current_user: current_user).execute diff --git a/doc/development/ruby_upgrade.md b/doc/development/ruby_upgrade.md index ccd65b4e7e9..21c19c31b0a 100644 --- a/doc/development/ruby_upgrade.md +++ b/doc/development/ruby_upgrade.md @@ -209,7 +209,7 @@ prudent to skip this step until you have verified that it runs smoothly in produ rollout. In this case, go to the next step first, and then, after the verification period has passed, promote the new Ruby to be the new default. -### Update CNG and Omnibus, merge the GitLab MR +### Update CNG, Omnibus, Self-compiled and merge the GitLab MR The last step is to use the new Ruby in production. This requires updating Omnibus and production Docker images to use the new version. @@ -220,6 +220,7 @@ To use the new Ruby in production, update the following projects: - [Cloud-native GitLab Docker Images (CNG)](https://gitlab.com/gitlab-org/build/CNG) ([example](https://gitlab.com/gitlab-org/build/CNG/-/merge_requests/739)) - [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab) ([example](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5545)) +- [Self-compiled installations](../install/installation.md): update the [Ruby system version check](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/system_check/app/ruby_version_check.rb) If you submit a change management request, coordinate the rollout with infrastructure engineers. When dealing with larger upgrades, involve [Release Managers](https://about.gitlab.com/community/release-managers/) diff --git a/doc/development/search/advanced_search_migration_styleguide.md b/doc/development/search/advanced_search_migration_styleguide.md index d7c0dddee7b..10c4fa3dcc6 100644 --- a/doc/development/search/advanced_search_migration_styleguide.md +++ b/doc/development/search/advanced_search_migration_styleguide.md @@ -6,13 +6,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Advanced search migration style guide -## Creating a new advanced search migration - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/234046) in GitLab 13.6. +## Create a new advanced search migration NOTE: This functionality is only supported for indices created in GitLab 13.0 and later. +### With a script + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414674) in GitLab 16.3. + +Execute `scripts/elastic-migration` and follow the prompts to create: + +- A migration file to define the migration: `ee/elastic/migrate/YYYYMMDDHHMMSS_migration_name.rb` +- A spec file to test the migration: `ee/spec/elastic/migrate/YYYYMMDDHHMMSS_migration_name_spec.rb` +- A dictionary file to identify the migration: `ee/elastic/docs/YYYYMMDDHHMMSS_migration_name.yml` + +### Manually + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/234046) in GitLab 13.6. + In the [`ee/elastic/migrate/`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/elastic/migrate) folder, create a new file with the filename format `YYYYMMDDHHMMSS_migration_name.rb`. This format is the same for Rails database migrations. ```ruby @@ -198,6 +210,27 @@ class MigrationName < Elastic::Migration end ``` +#### `Search::Elastic::MigrationReindexBasedOnSchemaVersion` + +Reindexes all documents in the index that stores the specified document type and updates `schema_version`. + +Requires the `DOCUMENT_TYPE` and `NEW_SCHEMA_VERSION` constants. +The index mapping must have a `schema_version` integer field in a `YYMM` format. + +```ruby +class MigrationName < Elastic::Migration + include Search::Elastic::MigrationReindexBasedOnSchemaVersion + + batched! + batch_size 9_000 + throttle_delay 1.minute + + DOCUMENT_TYPE = WorkItem + NEW_SCHEMA_VERSION = 23_08 + UPDATE_BATCH_SIZE = 100 +end +``` + #### `Elastic::MigrationHelper` Contains methods you can use when a migration doesn't fit the previous examples. diff --git a/doc/development/sec/analyzer_development_guide.md b/doc/development/sec/analyzer_development_guide.md index af8d1758713..c76b7f5e55f 100644 --- a/doc/development/sec/analyzer_development_guide.md +++ b/doc/development/sec/analyzer_development_guide.md @@ -342,7 +342,7 @@ This issue will guide you through the whole release process. In general, you hav - Check the list of supported technologies in GitLab documentation. - [Supported languages in SAST](../../user/application_security/sast/index.md#supported-languages-and-frameworks) - [Supported languages in DS](../../user/application_security/dependency_scanning/index.md#supported-languages-and-package-managers) - - [Supported languages in LM](../../user/compliance/license_compliance/index.md#supported-languages-and-package-managers) + - [Supported languages in LS](../../user/compliance/license_scanning_of_cyclonedx_files/index.md#supported-languages-and-package-managers) - Check that CI **_job definitions are still accurate_** in vendored CI/CD templates and **_all of the ENV vars are propagated_** to the Docker containers upon `docker run` per tool. diff --git a/doc/development/sec/generate_test_vulnerabilities.md b/doc/development/sec/generate_test_vulnerabilities.md new file mode 100644 index 00000000000..75fb7edd68e --- /dev/null +++ b/doc/development/sec/generate_test_vulnerabilities.md @@ -0,0 +1,32 @@ +--- +type: reference, howto +stage: Govern +group: Threat Insights +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 +--- + +# Generate test vulnerabilities + +You can generate test vulnerabilities for the [Vulnerability Report](../../user/application_security/vulnerability_report/index.md) to test GitLab +vulnerability management features without running a pipeline. + +1. Log in to GitLab. +1. Go to `/-/profile/personal_access_tokens` and generate a personal access token with `api` permissions. +1. Go to your project page and find the project ID. You can find the project ID below the project title. +1. [Clone the GitLab repository](../../gitlab-basics/start-using-git.md#clone-a-repository) to your local machine. +1. Open a terminal and go to `gitlab/qa` directory. +1. Run `bundle install` +1. Run the following command: + +```shell +GITLAB_QA_ACCESS_TOKEN=<your_personal_access_token> GITLAB_URL="<address:port>" bundle exec rake vulnerabilities:setup\[<your_project_id>,<vulnerability_count>\] --trace +``` + +Make sure you do the following: + +- Replace `<your_personal_access_token>` with the token you generated in step one. +- Double check the `GITLAB_URL`. It should point to address and port of your GitLab instance, for example `http://localhost:3000` if you are running GDK +- Replace `<your_project_id>` with the ID you obtained in step three above. +- Replace `<vulnerability_count>` with the number of vulnerabilities you'd like to generate. + +The script creates the specified number of placeholder vulnerabilities in the project. diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md index 8d6f36bb189..186239cc547 100644 --- a/doc/development/secure_coding_guidelines.md +++ b/doc/development/secure_coding_guidelines.md @@ -1412,3 +1412,64 @@ If circumstances dictate that local storage is the only option, a couple of prec - Local storage should only be used for the minimal amount of data possible. Consider alternative storage formats. - If you have to store sensitive data using local storage, do so for the minimum time possible, calling `localStorage.removeItem` on the item as soon as we're done with it. Another alternative is to call `localStorage.clear()`. + +## Logging + +Logging is the tracking of events that happen in the system for the purposes of future investigation or processing. + +### Purpose of logging + +Logging helps track events for debugging. Logging also allows the application to generate an audit trail that you can use for security incident identification and analysis. + +### What type of events should be logged + +- Failures + - Login failures + - Input/output validation failures + - Authentication failures + - Authorization failures + - Session management failures + - Timeout errors +- Account lockouts +- Use of invalid access tokens +- Authentication and authorization events + - Access token creation/revocation/expiry + - Configuration changes by administrators + - User creation or modification + - Password change + - User creation + - Email change +- Sensitive operations + - Any operation on sensitive files or resources + - New runner registration + +### What should be captured in the logs + +- The application logs must record attributes of the event, which helps auditors identify the time/date, IP, user ID, and event details. +- To avoid resource depletion, make sure the proper level for logging is used (for example, `information`, `error`, or `fatal`). + +### What should not be captured in the logs + +- Personal data, except for integer-based identifiers and UUIDs, or IP address, which can be logged when necessary. +- Credentials like access tokens or passwords. If credentials must be captured for debugging purposes, log the internal ID of the credential (if available) instead. Never log credentials under any circumstances. + - When [debug logging](../ci/variables/index.md#enable-debug-logging) is enabled, all masked CI/CD variables are visible in job logs. Consider using [protected variables](../ci/variables/index.md#protect-a-cicd-variable) when possible so that sensitive CI/CD variables are only available to pipelines running on protected branches or protected tags. +- Any data supplied by the user without proper validation. +- Any information that might be considered sensitive (for example, credentials, passwords, tokens, keys, or secrets). Here is an [example](https://gitlab.com/gitlab-org/gitlab/-/issues/383142) of sensitive information being leaked through logs. + +### Protecting log files + +- Access to the log files should be restricted so that only the intended party can modify the logs. +- External user input should not be directly captured in the logs without any validation. This could lead to unintended modification of logs through log injection attacks. +- An audit trail for log edits must be available. +- To avoid data loss, logs must be saved on different storage. + +### Who to contact if you have questions + +For general guidance, contact the [Application Security](https://about.gitlab.com/handbook/security/security-engineering/application-security/) team. + +### Related topics + +- [Log system in GitLab](../administration/logs/index.md) +- [Audit event development guidelines](../development/audit_event_guide/index.md)) +- [Security logging overview](https://about.gitlab.com/handbook/security/security-engineering/security-logging/) +- [OWASP logging cheat sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html) diff --git a/doc/development/sidekiq/index.md b/doc/development/sidekiq/index.md index 936388a14fe..1b3b319ef28 100644 --- a/doc/development/sidekiq/index.md +++ b/doc/development/sidekiq/index.md @@ -135,7 +135,7 @@ Sidekiq workers are deferred by two ways, sidekiq_options retry: 3 include ChaosQueue - defer_on_database_health_signal :gitlab_main, 1.minute, [:users] + defer_on_database_health_signal :gitlab_main, [:users], 1.minute def perform(duration_s) Gitlab::Chaos.sleep(duration_s) diff --git a/doc/development/sidekiq/worker_attributes.md b/doc/development/sidekiq/worker_attributes.md index 1e3104c5e86..814b61c746b 100644 --- a/doc/development/sidekiq/worker_attributes.md +++ b/doc/development/sidekiq/worker_attributes.md @@ -16,11 +16,11 @@ have to redefine them if you want to override their values. Jobs can have an `urgency` attribute set, which can be `:high`, `:low`, or `:throttled`. These have the below targets: -| **Urgency** | **Queue Scheduling Target** | **Execution Latency Requirement** | -|--------------|-----------------------------|------------------------------------| -| `:high` | 10 seconds | p50 of 1 second, p99 of 10 seconds | -| `:low` | 1 minute | Maximum run time of 5 minutes | -| `:throttled` | None | Maximum run time of 5 minutes | +| **Urgency** | **Queue Scheduling Target** | **Execution Latency Requirement** | +|--------------- | ----------------------------- | ------------------------------------ | +| `:high` | 10 seconds | 10 seconds | +| `:low` (default) | 1 minute | 5 minutes | +| `:throttled` | None | 5 minutes | To set a job's urgency, use the `urgency` class method: @@ -326,3 +326,42 @@ end For [idempotent jobs](idempotent_jobs.md) that declare either `:sticky` or `:delayed` data consistency, we are [preserving the latest WAL location](idempotent_jobs.md#preserve-the-latest-wal-location-for-idempotent-jobs) while deduplicating, ensuring that we read from the replica that is fully caught up. + +## Job pause control + +With the `pause_control` property, you can conditionally pause job processing. If the strategy is active, the job +is stored in a separate `ZSET` and re-enqueued when the strategy becomes inactive. `PauseControl::ResumeWorker` is a cron +worker that checks if any paused jobs must be restarted. + +To use `pause_control`, you can: + +- Use one of the strategies defined in `lib/gitlab/sidekiq_middleware/pause_control/strategies/`. +- Define a custom strategy in `lib/gitlab/sidekiq_middleware/pause_control/strategies/` and add the strategy to `lib/gitlab/sidekiq_middleware/pause_control/strategies.rb`. + +For example: + +```ruby +module Gitlab + module SidekiqMiddleware + module PauseControl + module Strategies + class CustomStrategy < Base + def should_pause? + ApplicationSetting.current.elasticsearch_pause_indexing? + end + end + end + end + end +end +``` + +```ruby +class PausedWorker + include ApplicationWorker + + pause_control :custom_strategy + + # ... +end +``` diff --git a/doc/development/software_design.md b/doc/development/software_design.md index 33a6dfcb4a7..e2749df372d 100644 --- a/doc/development/software_design.md +++ b/doc/development/software_design.md @@ -140,6 +140,27 @@ end If classes that are defined into a namespace have a lot in common with classes in other namespaces, chances are that these two namespaces are part of the same bounded context. +## Distinguish domain code from generic code + +The [guidelines above](#use-namespaces-to-define-bounded-contexts) refer primarily to the domain code. +For domain code we should put Ruby classes under a namespace that represents a given bounded context +(a cohesive set of features and capabilities). + +The domain code is unique to GitLab product. It describes the business logic, policies and data. +This code should live in the GitLab repository. The domain code is split between `app/` and `lib/` +primarily. + +In an application codebase there is also generic code that allows to perform more infrastructure level +actions. This can be loggers, instrumentation, clients for datastores like Redis, database utilities, etc. + +Although vital for an application to run, generic code doesn't describe any business logic that is +unique to GitLab product. It could be rewritten or replaced by off-the-shelf solutions without impacting +the business logic. +This means that generic code should be separate from the domain code. + +Today a lot of the generic code lives in `lib/` but it's mixed with domain code. +We should extract gems into `gems/` directory instead, as described in our [Gems development guidelines](gems.md). + ## Taming Omniscient classes We must consider not adding new data and behavior to [omniscient classes](https://en.wikipedia.org/wiki/God_object) (also known as god objects). diff --git a/doc/development/sql.md b/doc/development/sql.md index 5dbfd8f3ddb..101ccc239e7 100644 --- a/doc/development/sql.md +++ b/doc/development/sql.md @@ -315,6 +315,30 @@ union = Gitlab::SQL::Union.new([projects, more_projects, ...]) Project.from("(#{union.to_sql}) projects") ``` +The `FromUnion` model concern provides a more convenient method to produce the same result as above: + +```ruby +class Project + include FromUnion + ... +end + +Project.from_union(projects, more_projects, ...) +``` + +`UNION` is common through the codebase, but it's also possible to use the other SQL set operators of `EXCEPT` and `INTERSECT`: + +```ruby +class Project + include FromIntersect + include FromExcept + ... +end + +intersected = Project.from_intersect(all_projects, project_set_1, project_set_2) +excepted = Project.from_except(all_projects, project_set_1, project_set_2) +``` + ### Uneven columns in the `UNION` sub-queries When the `UNION` query has uneven columns in the `SELECT` clauses, the database returns an error. @@ -354,7 +378,10 @@ values (the new column is missing), because the values are cached within the `Ac cache. These values are usually populated when the application boots up. At this point, the only fix would be a full application restart so that the schema cache gets -updated. +updated. Since [GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121957), +the schema cache will be automatically reset so that subsequent queries +will succeed. This reset can be disabled by disabling the `ops` feature +flag `reset_column_information_on_statement_invalid`. The problem can be avoided if we always use `SELECT users.*` or we always explicitly define the columns. @@ -460,6 +487,96 @@ Both methods use subtransactions internally if executed within the context of an existing transaction. This can significantly impact overall performance, especially if more than 64 live subtransactions are being used inside a single transaction. +### Can I use `.safe_find_or_create_by`? + +If your code is generally isolated (for example it's executed in a worker only) and not wrapped with another transaction, then you can use `.safe_find_or_create_by`. However, there is no tooling to catch cases when someone else calls your code within a transaction. Using `.safe_find_or_create_by` will definitely carry some risks that cannot be eliminated completely at the moment. + +Additionally, we have a RuboCop rule `Performance/ActiveRecordSubtransactionMethods` that prevents the usage of `.safe_find_or_create_by`. This rule can be disabled on a case by case basis via `# rubocop:disable Performance/ActiveRecordSubtransactionMethods`. + +## Alternative 1: `UPSERT` + +The [`.upsert`](https://api.rubyonrails.org/v7.0.5/classes/ActiveRecord/Persistence/ClassMethods.html#method-i-upsert) method can be an alternative solution when the table is backed by a unique index. + +Simple usage of the `.upsert` method: + +```ruby +BuildTrace.upsert( + { + build_id: build_id, + title: title + }, + unique_by: :build_id +) +``` + +A few things to be careful about: + +- The sequence for the primary key will be incremented, even if the record was only updated. +- The created record is not returned. The `returning` option only returns data when an `INSERT` happens (new record). +- `ActiveRecord` validations are not executed. + +An example of the `.upsert` method with validations and record loading: + +```ruby +params = { + build_id: build_id, + title: title +} + +build_trace = BuildTrace.new(params) + +unless build_trace.valid? + raise 'notify the user here' +end + +BuildTrace.upsert(params, unique_by: :build_id) + +build_trace = BuildTrace.find_by!(build_id: build_id) + +# do something with build_trace here +``` + +The code snippet above will not work well if there is a model-level uniqueness validation on the `build_id` column because we invoke the validation before calling `.upsert`. + +To work around this, we have two options: + +- Remove the unqueness validation from the `ActiveRecord` model. +- Use the [`on` keyword](https://guides.rubyonrails.org/active_record_validations.html#on) and implement context-specific validation. + +### Alternative 2: Check existence and rescue + +When the chance of concurrently creating the same record is very low, we can use a simpler approach: + +```ruby +def my_create_method + params = { + build_id: build_id, + title: title + } + + build_trace = BuildTrace + .where(build_id: params[:build_id]) + .first + + build_trace = BuildTrace.new(params) if build_trace.blank? + + build_trace.update!(params) + +rescue ActiveRecord::RecordInvalid => invalid + retry if invalid.record&.errors&.of_kind?(:build_id, :taken) +end +``` + +The method does the following: + +1. Look up the model by the unique column. +1. If no record found, build a new one. +1. Persist the record. + +There is a short race condition between the lookup query and the persist query where another process could insert the record and cause an `ActiveRecord::RecordInvalid` exception. + +The code rescues this particular exception and retries the operation. For the second run, the record would be successfully located. For example check [this block of code](https://gitlab.com/gitlab-org/gitlab/-/blob/0b51d7fbb97d4becf5fd40bc3b92f732bece85bd/ee/app/services/compliance_management/standards/gitlab/prevent_approval_by_author_service.rb#L20-30) in `PreventApprovalByAuthorService`. + ## Monitor SQL queries in production GitLab team members can monitor slow or canceled queries on GitLab.com @@ -468,3 +585,129 @@ searchable using Kibana. See [the runbook](https://gitlab.com/gitlab-com/runbooks/-/blob/master/docs/patroni/pg_collect_query_data.md#searching-postgresql-logs-with-kibanaelasticsearch) for more details. + +## When to use common table expressions + +You can use common table expressions (CTEs) to create a temporary result set within a more complex query. +You can also use a recursive CTE to reference the CTE's result set within +the query itself. The following example queries a chain of +`personal access tokens` referencing each other in the +`previous_personal_access_token_id` column. + +```sql +WITH RECURSIVE "personal_access_tokens_cte" AS ( +( + SELECT + "personal_access_tokens".* + FROM + "personal_access_tokens" + WHERE + "personal_access_tokens"."previous_personal_access_token_id" = 15) + UNION ( + SELECT + "personal_access_tokens".* + FROM + "personal_access_tokens", + "personal_access_tokens_cte" + WHERE + "personal_access_tokens"."previous_personal_access_token_id" = "personal_access_tokens_cte"."id")) +SELECT + "personal_access_tokens".* +FROM + "personal_access_tokens_cte" AS "personal_access_tokens" + + id | previous_personal_access_token_id +----+----------------------------------- + 16 | 15 + 17 | 16 + 18 | 17 + 19 | 18 + 20 | 19 + 21 | 20 +(6 rows) +``` + +As CTEs are temporary result sets, you can use them within another `SELECT` +statement. Using CTEs with `UPDATE`, or `DELETE` could lead to unexpected +behavior: + +Consider the following method: + +```ruby +def personal_access_token_chain(token) + cte = Gitlab::SQL::RecursiveCTE.new(:personal_access_tokens_cte) + personal_access_token_table = Arel::Table.new(:personal_access_tokens) + + cte << PersonalAccessToken + .where(personal_access_token_table[:previous_personal_access_token_id].eq(token.id)) + cte << PersonalAccessToken + .from([personal_access_token_table, cte.table]) + .where(personal_access_token_table[:previous_personal_access_token_id].eq(cte.table[:id])) + PersonalAccessToken.with.recursive(cte.to_arel).from(cte.alias_to(personal_access_token_table)) +end +``` + +It works as expected when it is used to query data: + +```sql +> personal_access_token_chain(token) + +WITH RECURSIVE "personal_access_tokens_cte" AS ( +( + SELECT + "personal_access_tokens".* + FROM + "personal_access_tokens" + WHERE + "personal_access_tokens"."previous_personal_access_token_id" = 11) + UNION ( + SELECT + "personal_access_tokens".* + FROM + "personal_access_tokens", + "personal_access_tokens_cte" + WHERE + "personal_access_tokens"."previous_personal_access_token_id" = "personal_access_tokens_cte"."id")) +SELECT + "personal_access_tokens".* +FROM + "personal_access_tokens_cte" AS "personal_access_tokens" +``` + +However, the CTE is dropped when used with `#update_all`. As a result, the method +updates the entire table: + +```sql +> personal_access_token_chain(token).update_all(revoked: true) + +UPDATE + "personal_access_tokens" +SET + "revoked" = TRUE +``` + +To work around this behavior: + +1. Query the `ids` of the records: + + ```ruby + > token_ids = personal_access_token_chain(token).pluck_primary_key + => [16, 17, 18, 19, 20, 21] + ``` + +1. Use this array to scope `PersonalAccessTokens`: + + ```ruby + PersonalAccessToken.where(id: token_ids).update_all(revoked: true) + ``` + +Alternatively, combine these two steps: + +```ruby +PersonalAccessToken + .where(id: personal_access_token_chain(token).pluck_primary_key) + .update_all(revoked: true) +``` + +NOTE: +Avoid updating large volumes of unbounded data. If there are no [application limits](application_limits.md) on the data, or you are unsure about the data volume, you should [update the data in batches](database/iterating_tables_in_batches.md). diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index 5a4ac99f5c5..65787f7a355 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -488,7 +488,9 @@ We collect information about tests duration in [`rspec_profiling_stats`](https:/ With [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/375983) we defined thresholds for tests duration that can act a guide. -For tests that are not meeting the thresholds it is recommended to create issues and improve the tests duration. +For tests that are not meeting the thresholds, we create [issues](https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=created_date&state=opened&label_name%5B%5D=rspec%3Aslow%20test&first_page_size=100) automatically in order to improve them. + +For tests that are slow for a legitimate reason and to skip issue creation, add `allowed_to_be_slow: true`. | Date | Feature tests | Controllers and Requests tests | Unit | Other | Method | | :-: | :-: | :-: | :-: | :-: | :-: | @@ -619,11 +621,11 @@ You can use the `be_axe_clean` matcher to run [axe automated accessibility testi ##### Externalized contents -Test expectations against externalized contents should call the same +For RSpec tests, expectations against externalized contents should call the same externalizing method to match the translation. For example, you should use the `_` -method in Ruby and `__` method in JavaScript. +method in Ruby. -See [Internationalization for GitLab - Test files](../i18n/externalization.md#test-files) for details. +See [Internationalization for GitLab - Test files (RSpec)](../i18n/externalization.md#test-files-rspec) for details. ##### Actions @@ -908,6 +910,9 @@ so we need to set some guidelines for their use going forward: ### Common test setup +NOTE: +`before_all` does not work with the `:delete` strategy. For more information, see [issue 420379](https://gitlab.com/gitlab-org/gitlab/-/issues/420379). + In some cases, there is no need to recreate the same object for tests again for each example. For example, a project and a guest of that project are needed to test issues on the same project, so one project and user are enough for the entire file. @@ -1027,6 +1032,58 @@ after :all do end ``` +#### Timestamp truncation + +Active Record timestamps are [set by the Rails’ `ActiveRecord::Timestamp`](https://github.com/rails/rails/blob/1eb5cc13a2ed8922b47df4ae47faf5f23faf3d35/activerecord/lib/active_record/timestamp.rb#L105) +module [using `Time.now`](https://github.com/rails/rails/blob/1eb5cc13a2ed8922b47df4ae47faf5f23faf3d35/activerecord/lib/active_record/timestamp.rb#L78). +Time precision is [OS-dependent](https://ruby-doc.org/core-2.6.3/Time.html#method-c-new), +and as the docs state, may include fractional seconds. + +When Rails models are saved to the database, +any timestamps they have are stored using a type in PostgreSQL called `timestamp without time zone`, +which has microsecond resolution—i.e., six digits after the decimal. +So if `1577987974.6472975` is sent to PostgreSQL, +it truncates the last digit of the fractional part and instead saves `1577987974.647297`. + +The results of this can be a simple test like: + +```ruby +let_it_be(:contact) { create(:contact) } + +data = Gitlab::HookData::IssueBuilder.new(issue).build + +expect(data).to include('customer_relations_contacts' => [contact.hook_attrs]) +``` + +Failing with an error along the lines of: + +```shell +expected { +"assignee_id" => nil, "...1 +0000 } to include {"customer_relations_contacts" => [{:created_at => "2023-08-04T13:30:20Z", :first_name => "Sidney Jones3" }]} + +Diff: + @@ -1,35 +1,69 @@ + -"customer_relations_contacts" => [{:created_at=>"2023-08-04T13:30:20Z", :first_name=>"Sidney Jones3" }], + +"customer_relations_contacts" => [{"created_at"=>2023-08-04 13:30:20.245964000 +0000, "first_name"=>"Sidney Jones3" }], +``` + +The fix is to ensure we `.reload` the object from the database to get the timestamp with correct precision: + +```ruby +let_it_be(:contact) { create(:contact) } + +data = Gitlab::HookData::IssueBuilder.new(issue).build + +expect(data).to include('customer_relations_contacts' => [contact.reload.hook_attrs]) +``` + +This explanation was taken from [a blog post](https://www.toptal.com/ruby-on-rails/timestamp-truncation-rails-activerecord-tale) +by Maciek Rząsa. + +You can see a [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126530#note_1500580985) +where this problem arose and the [backend pairing session](https://www.youtube.com/watch?v=nMCjEeuYFDA) +where it was discussed. + ### Feature flags in tests This section was moved to [developing with feature flags](../feature_flags/index.md). diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md index adf679c44a2..4e7ef6f29a2 100644 --- a/doc/development/testing_guide/end_to_end/index.md +++ b/doc/development/testing_guide/end_to_end/index.md @@ -18,6 +18,8 @@ together. We use [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab) to build GitLab packages and then we test these packages using the [GitLab QA orchestrator](https://gitlab.com/gitlab-org/gitlab-qa) tool to run the end-to-end tests located in the `qa` directory. +Additionally, we use the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit) (GDK) as a test environment that can be deployed quickly for faster test feedback. + ### Testing nightly builds We run scheduled pipelines each night to test nightly builds created by Omnibus. @@ -43,10 +45,9 @@ Docker image built from your merge request's changes.** Manual action that starts end-to-end tests is also available in [`gitlab-org/omnibus-gitlab` merge requests](https://docs.gitlab.com/omnibus/build/team_member_docs.html#i-have-an-mr-in-the-omnibus-gitlab-project-and-want-a-package-or-docker-image-to-test-it). -#### How does it work? +##### How does it work? -Currently, we are using _multi-project pipeline_-like approach to run end-to-end -pipelines. +Currently, we are using _multi-project pipeline_-like approach to run end-to-end pipelines against Omnibus GitLab. ```mermaid graph TB @@ -98,7 +99,22 @@ work-around was suggested in <https://gitlab.com/gitlab-org/omnibus-gitlab/-/iss A feature proposal to segregate access control regarding running pipelines from ability to push/merge was also created at <https://gitlab.com/gitlab-org/gitlab/-/issues/24585>. For more technical details on CI/CD setup and documentation on adding new test jobs to `e2e:package-and-test` pipeline, see -[`e2e:package_and_test` setup documentation](package_and_test_pipeline.md). +[`e2e:package_and_test` setup documentation](test_pipelines.md). + +#### Using the `test-on-gdk` job + +The `e2e:test-on-gdk` job is run automatically in most merge requests, which triggers a [child-pipeline](../../../ci/pipelines/downstream_pipelines.md#parent-child-pipelines) +that builds and installs a GDK instance from your merge request's changes, and then executes end-to-end tests against that GDK instance. + +##### How does it work? + +In the [`gitlab-org/gitlab` pipeline](https://gitlab.com/gitlab-org/gitlab): + +1. The [`build-gdk-image` job](https://gitlab.com/gitlab-org/gitlab/-/blob/07504c34b28ac656537cd60810992aa15e9e91b8/.gitlab/ci/build-images.gitlab-ci.yml#L32) + uses the code from the merge request to build a Docker image for a GDK instance. +1. The `e2e:test-on-gdk` trigger job creates a child pipeline that executes the end-to-end tests against GDK instances launched from the image built in the previous job. + +For more details, see the [documentation for the `e2e:test-on-gdk` pipeline](test_pipelines.md#e2etest-on-gdk). #### With merged results pipelines diff --git a/doc/development/testing_guide/end_to_end/package_and_test_pipeline.md b/doc/development/testing_guide/end_to_end/package_and_test_pipeline.md index b0257e7b02c..240db2cbfe5 100644 --- a/doc/development/testing_guide/end_to_end/package_and_test_pipeline.md +++ b/doc/development/testing_guide/end_to_end/package_and_test_pipeline.md @@ -1,134 +1,11 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'test_pipelines.md' +remove_date: '2023-11-08' --- -# e2e:package-and-test +This document was moved to [another location](test_pipelines.md). -The `e2e:package-and-test` child pipeline is the main executor of E2E testing for the GitLab platform. The pipeline definition has several dynamic -components to reduce the number of tests being executed in merge request pipelines. - -## Setup - -Pipeline setup consists of: - -- The `e2e-test-pipeline-generate` job in the `prepare` stage of the main GitLab pipeline. -- The `e2e:package-and-test` job in the `qa` stage, which triggers the child pipeline that is responsible for building the `omnibus` package and - running E2E tests. - -### e2e-test-pipeline-generate - -This job consists of two components that implement selective test execution: - -- The [`detect_changes`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/tasks/ci.rake) Rake task determines which e2e specs should be executed - in a particular merge request pipeline. This task analyzes changes in a particular merge request and determines which specs must be executed. - Based on that, a `dry-run` of every [scenario](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa/qa/scenario/test) executes and determines if a - scenario contains any executable tests. Selective test execution uses [these criteria](index.md#selective-test-execution) to determine which specific - tests to execute. -- [`generate-e2e-pipeline`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/generate-e2e-pipeline) is executed, which generates a child - pipeline YAML definition file with appropriate environment variables. - -### e2e:package-and-test - -E2E test execution pipeline consists of several stages which all support execution of E2E tests. - -#### .pre - -This stage is responsible for the following tasks: - -- Fetching `knapsack` reports that support [parallel test execution](index.md#run-tests-in-parallel). -- Triggering downstream pipeline which builds the [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab) Docker image. - -#### test - -This stage runs e2e tests against different types of GitLab configurations. The number of jobs executed is determined dynamically by -[`e2e-test-pipeline-generate`](package_and_test_pipeline.md#e2e-test-pipeline-generate) job. - -#### report - -This stage is responsible for [allure test report](index.md#allure-report) generation. - -## Adding new jobs - -Selective test execution depends on a set of rules present in every job definition. A typical job contains the following attributes: - -```yaml -variables: - QA_SCENARIO: Test::Integration::MyNewJob -rules: - - !reference [.rules:test:qa, rules] - - if: $QA_SUITES =~ /Test::Integration::MyNewJob/ - - !reference [.rules:test:manual, rules] -``` - -In this example: - -- `QA_SCENARIO: Test::Integration::MyNewJob`: name of the scenario class that is passed to the - [`gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md) executor. -- `!reference [.rules:test:qa, rules]`: main rule definition that is matched for pipelines that should execute all tests. For example, when changes to - `qa` framework are present. -- `if: $QA_SUITES =~ /Test::Integration::MyNewJob/`: main rule responsible for selective test execution. `QA_SUITE` is the name of the scenario - abstraction located in [`qa framework`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa/qa/scenario/test). - - `QA_SUITE` is not the same as `QA_SCENARIO`, which is passed to the `gitlab-qa` executor. For consistency, it usually has the same name. `QA_SUITE` - abstraction class usually contains information on what tags to run and optionally some additional setup steps. -- `!reference [.rules:test:manual, rules]`: final rule that is always matched and sets the job to `manual` so it can still be executed on demand, - even if not set to execute by selective test execution. - -Considering example above, perform the following steps to create a new job: - -1. Create new scenario type `my_new_job.rb` in the [`integration`](https://gitlab.com/gitlab-org/gitlab-qa/-/tree/master/lib/gitlab/qa/scenario/test/integration) directory - of the [`gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa) project and release new version so it's generally available. -1. Create new scenario `my_new_job.rb` in [`integration`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa/qa/scenario/test/integration) directory of the - [`qa`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa) framework. In the most simple case, this scenario would define RSpec tags that should be executed: - - ```ruby - module QA - module Scenario - module Test - module Integration - class MyNewJob < Test::Instance::All - tags :some_special_tag - end - end - end - end - end - ``` - -1. Add new job definition in the [`main.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/package-and-test/main.gitlab-ci.yml) pipeline definition: - - ```yaml - ee:my-new-job: - extends: .qa - variables: - QA_SCENARIO: Test::Integration::MyNewJob - rules: - - !reference [.rules:test:qa, rules] - - if: $QA_SUITES =~ /Test::Integration::MyNewJob/ - - !reference [.rules:test:manual, rules] - ``` - -### Parallel jobs - -For selective execution to work correctly with job types that require running multiple parallel jobs, -a job definition typically must be split into parallel and selective variants. Splitting is necessary so that when selective execution -executes only a single spec, multiple unnecessary jobs are not spawned. For example: - -```yaml -ee:my-new-job-selective: - extends: .qa - variables: - QA_SCENARIO: Test::Integration::MyNewJob - rules: - - !reference [.rules:test:qa-selective, rules] - - if: $QA_SUITES =~ /Test::Integration::MyNewJob/ -ee:my-new-job: - extends: - - .parallel - - ee:my-new-job-selective - rules: - - !reference [.rules:test:qa-parallel, rules] - - if: $QA_SUITES =~ /Test::Integration::MyNewJob/ -``` +<!-- This redirect file can be deleted after <2023-11-08>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/testing_guide/end_to_end/resources.md b/doc/development/testing_guide/end_to_end/resources.md index f9e136a86df..becdc375c63 100644 --- a/doc/development/testing_guide/end_to_end/resources.md +++ b/doc/development/testing_guide/end_to_end/resources.md @@ -347,7 +347,7 @@ end ## Creating resources in your tests To create a resource in your tests, you can call the `.fabricate!` method on -the resource class. +the resource class, or use the [factory](#factories) to create it. Note that if the resource class supports API fabrication, this uses this fabrication by default. @@ -390,6 +390,23 @@ end In this case, the result is similar to calling `Resource::Shirt.fabricate!`. +### Factories + +You may also use FactoryBot invocations to create resources within your tests. + +```ruby +# create a project via the API to use in the test +let(:project) { create(:project) } + +# create an issue belonging to a project via the API to use in the test +let(:issue) { create(:issue, project: project) } + +# create a private project via the API with a specific name +let(:project) { create(:project, :private, name: 'my-project-name', add_name_uuid: false) } +``` + +All factories are defined in [`qa/qa/factories`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/qa/factories/). + ### Resources cleanup We have a mechanism to [collect](https://gitlab.com/gitlab-org/gitlab/-/blob/44345381e89d6bbd440f7b4c680d03e8b75b86de/qa/qa/tools/test_resource_data_processor.rb#L32) diff --git a/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md b/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md index f13686981a9..93adc492d5a 100644 --- a/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md +++ b/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md @@ -15,6 +15,7 @@ This is a partial list of the [RSpec metadata](https://rspec.info/features/3-12/ |-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `:elasticsearch` | The test requires an Elasticsearch service. It is used by the [instance-level scenario](https://gitlab.com/gitlab-org/gitlab-qa#definitions) [`Test::Integration::Elasticsearch`](https://gitlab.com/gitlab-org/gitlab/-/blob/72b62b51bdf513e2936301cb6c7c91ec27c35b4d/qa/qa/ee/scenario/test/integration/elasticsearch.rb) to include only tests that require Elasticsearch. | | `:except` | The test is to be run in their typical execution contexts _except_ as specified. See [test execution context selection](execution_context_selection.md) for more information. | +| `:external_api_calls` | The test requires interaction with a network external to the Docker network | | `:feature_flag` | The test uses a feature flag and therefore requires an administrator account to run. When `scope` is set to `:global`, the test will be skipped on all live .com environments. Otherwise, it will be skipped only on Canary, Production, and Pre-production. See [testing with feature flags](../../../development/testing_guide/end_to_end/feature_flags.md) for more details. | | `:framework` | The test makes sanity assertions around the QA framework itself | | `:geo` | The test requires two GitLab Geo instances - a primary and a secondary - to be spun up. | diff --git a/doc/development/testing_guide/end_to_end/test_pipelines.md b/doc/development/testing_guide/end_to_end/test_pipelines.md new file mode 100644 index 00000000000..b47b75e398a --- /dev/null +++ b/doc/development/testing_guide/end_to_end/test_pipelines.md @@ -0,0 +1,190 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# End-to-end test pipelines + +## e2e:package-and-test + +The `e2e:package-and-test` child pipeline is the main executor of E2E testing for the GitLab platform. The pipeline definition has several dynamic +components to reduce the number of tests being executed in merge request pipelines. + +### Setup + +Pipeline setup consists of: + +- The `e2e-test-pipeline-generate` job in the `prepare` stage of the main GitLab pipeline. +- The `e2e:package-and-test` job in the `qa` stage, which triggers the child pipeline that is responsible for building the `omnibus` package and + running E2E tests. + +#### e2e-test-pipeline-generate + +This job consists of two components that implement selective test execution: + +- The [`detect_changes`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/tasks/ci.rake) Rake task determines which e2e specs should be executed + in a particular merge request pipeline. This task analyzes changes in a particular merge request and determines which specs must be executed. + Based on that, a `dry-run` of every [scenario](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa/qa/scenario/test) executes and determines if a + scenario contains any executable tests. Selective test execution uses [these criteria](index.md#selective-test-execution) to determine which specific + tests to execute. +- [`generate-e2e-pipeline`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/generate-e2e-pipeline) is executed, which generates a child + pipeline YAML definition file with appropriate environment variables. + +#### e2e:package-and-test + +E2E test execution pipeline consists of several stages which all support execution of E2E tests. + +##### .pre + +This stage is responsible for the following tasks: + +- Fetching `knapsack` reports that support [parallel test execution](index.md#run-tests-in-parallel). +- Triggering downstream pipeline which builds the [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab) Docker image. + +##### test + +This stage runs e2e tests against different types of GitLab configurations. The number of jobs executed is determined dynamically by +[`e2e-test-pipeline-generate`](test_pipelines.md#e2e-test-pipeline-generate) job. + +##### report + +This stage is responsible for [allure test report](index.md#allure-report) generation. + +### Adding new jobs + +Selective test execution depends on a set of rules present in every job definition. A typical job contains the following attributes: + +```yaml +variables: + QA_SCENARIO: Test::Integration::MyNewJob +rules: + - !reference [.rules:test:qa, rules] + - if: $QA_SUITES =~ /Test::Integration::MyNewJob/ + - !reference [.rules:test:manual, rules] +``` + +In this example: + +- `QA_SCENARIO: Test::Integration::MyNewJob`: name of the scenario class that is passed to the + [`gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md) executor. +- `!reference [.rules:test:qa, rules]`: main rule definition that is matched for pipelines that should execute all tests. For example, when changes to + `qa` framework are present. +- `if: $QA_SUITES =~ /Test::Integration::MyNewJob/`: main rule responsible for selective test execution. `QA_SUITE` is the name of the scenario + abstraction located in [`qa framework`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa/qa/scenario/test). + + `QA_SUITE` is not the same as `QA_SCENARIO`, which is passed to the `gitlab-qa` executor. For consistency, it usually has the same name. `QA_SUITE` + abstraction class usually contains information on what tags to run and optionally some additional setup steps. +- `!reference [.rules:test:manual, rules]`: final rule that is always matched and sets the job to `manual` so it can still be executed on demand, + even if not set to execute by selective test execution. + +Considering example above, perform the following steps to create a new job: + +1. Create new scenario type `my_new_job.rb` in the [`integration`](https://gitlab.com/gitlab-org/gitlab-qa/-/tree/master/lib/gitlab/qa/scenario/test/integration) directory + of the [`gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa) project and release new version so it's generally available. +1. Create new scenario `my_new_job.rb` in [`integration`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa/qa/scenario/test/integration) directory of the + [`qa`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa) framework. In the most simple case, this scenario would define RSpec tags that should be executed: + + ```ruby + module QA + module Scenario + module Test + module Integration + class MyNewJob < Test::Instance::All + tags :some_special_tag + end + end + end + end + end + ``` + +1. Add new job definition in the [`main.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/package-and-test/main.gitlab-ci.yml) pipeline definition: + + ```yaml + ee:my-new-job: + extends: .qa + variables: + QA_SCENARIO: Test::Integration::MyNewJob + rules: + - !reference [.rules:test:qa, rules] + - if: $QA_SUITES =~ /Test::Integration::MyNewJob/ + - !reference [.rules:test:manual, rules] + ``` + +#### Parallel jobs + +For selective execution to work correctly with job types that require running multiple parallel jobs, +a job definition typically must be split into parallel and selective variants. Splitting is necessary so that when selective execution +executes only a single spec, multiple unnecessary jobs are not spawned. For example: + +```yaml +ee:my-new-job-selective: + extends: .qa + variables: + QA_SCENARIO: Test::Integration::MyNewJob + rules: + - !reference [.rules:test:qa-selective, rules] + - if: $QA_SUITES =~ /Test::Integration::MyNewJob/ +ee:my-new-job: + extends: + - .parallel + - ee:my-new-job-selective + rules: + - !reference [.rules:test:qa-parallel, rules] + - if: $QA_SUITES =~ /Test::Integration::MyNewJob/ +``` + +## `e2e:test-on-gdk` + +The `e2e:test-on-gdk` child pipeline supports development of the GitLab platform by providing feedback to engineers on +end-to-end test execution faster than via `e2e:package-and-test` or [Review Apps](../review_apps.md). + +This is achieved by running tests against the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit) (GDK), +which can be built and installed in less time than when testing against [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab). +The trade-off is that Omnibus GitLab can be used to deploy a production installation, whereas the GDK is a development +environment. Tests that run against the GDK might not catch bugs that depend on part of the process of preparing GitLab +to run in a production environment, including pre-compiling assets, assigning configuration defaults as part of an official +installation package, deploying GitLab services to multiple servers, and more. On the other hand, engineers who use the +GDK day-to-day can benefit from automated tests catching bugs that only appear on the GDK. + +### Setup + +The pipeline setup consists of several jobs in the main GitLab pipeline: + +- The [`e2e-test-pipeline-generate` job](https://gitlab.com/gitlab-org/gitlab/-/blob/9456299b995084bfceb8bc6d082229c0198a0f72/.gitlab/ci/setup.gitlab-ci.yml#L158) + in the `prepare` stage. This is the same job as in the [`e2e:package-and-test`](#e2epackage-and-test) pipeline. +- The [`build-gdk-image` job](https://gitlab.com/gitlab-org/gitlab/-/blob/07504c34b28ac656537cd60810992aa15e9e91b8/.gitlab/ci/build-images.gitlab-ci.yml#L32) + in the `build-images` stage. +- The `e2e:test-on-gdk` trigger job in the `qa` stage, which triggers the child pipeline that runs E2E tests. + +#### `build-gdk-image` + +[This job](https://gitlab.com/gitlab-org/gitlab/-/blob/07504c34b28ac656537cd60810992aa15e9e91b8/.gitlab/ci/build-images.gitlab-ci.yml#L32) +uses the code from the merge request to build a Docker image that can be used in test jobs to launch a GDK instance in a container. The image is pushed to the Container Registry. + +The job also runs in pipelines on the default branch to build a base image that includes the GDK and GitLab components. +This avoids building the entire image from scratch in merge requests. However, if the merge request includes changes to +[certain GitLab components or code](https://gitlab.com/gitlab-org/gitlab/-/blob/24109c1a7ae1f29d4f6f1aeba3a13cbd8ea0e8e6/.gitlab/ci/rules.gitlab-ci.yml#L911) +the job will rebuild the base image before building the image that will be used in the test jobs. + +#### `e2e:test-on-gdk` child pipeline + +Like the [`e2e:package-and-test`](#e2epackage-and-test) pipeline, the `e2e:test-on-gdk` pipeline consists of several stages +that support execution of E2E tests. + +##### .pre + +This stage is responsible for fetching `knapsack` reports that support [parallel test execution](index.md#run-tests-in-parallel). + +##### test + +This stage runs e2e tests against different types of GitLab configurations. The number of jobs executed is determined dynamically by the +[`e2e-test-pipeline-generate`](test_pipelines.md#e2e-test-pipeline-generate) job. + +Each job starts a container from the GDK Docker image created in the `build-gdk-image` job, and then executes the end-to-end +tests against the GDK instance running in the container. + +##### report + +This stage is responsible for [allure test report](index.md#allure-report) generation. diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 1b50bd410c2..8da4350074d 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -228,16 +228,13 @@ it('exists', () => { // Bad wrapper.find('.js-foo'); wrapper.find('.btn-primary'); - wrapper.find('.qa-foo-component'); }); ``` -It is recommended to use `kebab-case` for `data-testid` attribute. +You should use `kebab-case` for `data-testid` attribute. It is not recommended that you add `.js-*` classes just for testing purposes. Only do this if there are no other feasible options available. -Do not use `.qa-*` class attributes for any tests other than QA end-to-end testing. - ### Querying for child components When testing Vue components with `@vue/test-utils` another possible approach is querying for child @@ -387,7 +384,7 @@ If your tests require `window.location.href` to take a particular value, use the `setWindowLocation` helper: ```javascript -import setWindowLocation from 'helpers/set_window_location'; +import setWindowLocation from 'helpers/set_window_location_helper'; it('passes', () => { setWindowLocation('https://gitlab.test/foo?bar=true'); diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md index 38fda1bb742..68d30ff6656 100644 --- a/doc/development/testing_guide/index.md +++ b/doc/development/testing_guide/index.md @@ -10,8 +10,8 @@ This document describes various guidelines and best practices for automated testing of the GitLab project. It is meant to be an _extension_ of the -[Thoughtbot testing style guide](https://github.com/thoughtbot/guides/tree/master/testing-rspec). If -this guide defines a rule that contradicts the Thoughtbot guide, this guide +[thoughtbot testing style guide](https://github.com/thoughtbot/guides/tree/master/testing-rspec). If +this guide defines a rule that contradicts the thoughtbot guide, this guide takes precedence. Some guidelines may be repeated verbatim to stress their importance. diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index 480a53bbefe..4e4dc671c03 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -197,16 +197,8 @@ graph RL #### What to mock in component tests -- **DOM**: - Operating on the real DOM is significantly slower than on the virtual DOM. -- **Properties and state of the component under test**: - Similar to testing classes, modifying the properties directly (rather than relying on methods of the component) avoids side effects. -- **Vuex store**: - To avoid side effects and keep component tests simple, Vuex stores are replaced with mocks. -- **All server requests**: - Similar to unit tests, when running component tests, the backend may not be reachable, so all outgoing requests need to be mocked. -- **Asynchronous background operations**: - Similar to unit tests, background operations cannot be stopped or waited on. This means they continue running in the following tests and cause side effects. +- **Side effects**: + Anything that can change external state (for example, a network request) should be mocked. - **Child components**: Every component is tested individually, so child components are mocked. See also [`shallowMount()`](https://v1.test-utils.vuejs.org/api/#shallowmount) @@ -215,8 +207,10 @@ graph RL - **Methods or computed properties of the component under test**: By mocking part of the component under test, the mocks are tested and not the real component. -- **Functions and classes independent from Vue**: - All plain JavaScript code is already covered by unit tests and needs not to be mocked in component tests. +- **Vuex**: + Keep Vuex unmocked to avoid fragile and false-positive tests. + Set the Vuex to a proper state using mutations. + Mock the side-effects, not the Vuex actions. ## Integration tests diff --git a/doc/development/testing_guide/testing_migrations_guide.md b/doc/development/testing_guide/testing_migrations_guide.md index f69f0d1febb..abe04274b72 100644 --- a/doc/development/testing_guide/testing_migrations_guide.md +++ b/doc/development/testing_guide/testing_migrations_guide.md @@ -21,11 +21,15 @@ We don't enforce tests on post migrations that only perform schema changes. ## How does it work? -Adding a `:migration` tag to a test signature enables some custom RSpec +All specs in `(ee/)spec/migrations/` and `spec/lib/(ee/)background_migrations` are automatically +tagged with the `:migration` RSpec tag. This tag enables some custom RSpec `before` and `after` hooks in our [`spec/support/migration.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/f81fa6ab1dd788b70ef44b85aaba1f31ffafae7d/spec/support/migration.rb) to run. If performing a migration against a database schema other than -`:gitlab_main` (for example `:gitlab_ci`), then you must specify it as well: `migration: :gitlab_ci`. See [spec/migrations/change_public_projects_cost_factor_spec.rb](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/migrations/change_public_projects_cost_factor_spec.rb#L6-6) for an example. +`:gitlab_main` (for example `:gitlab_ci`), then you must explicitly specify it +with an RSpec tag like: `migration: :gitlab_ci`. See +[spec/migrations/change_public_projects_cost_factor_spec.rb](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/migrations/change_public_projects_cost_factor_spec.rb#L6-6) +for an example. A `before` hook reverts all migrations to the point that a migration under test is not yet migrated. diff --git a/doc/development/value_stream_analytics.md b/doc/development/value_stream_analytics.md index 30244407e38..955fc88c713 100644 --- a/doc/development/value_stream_analytics.md +++ b/doc/development/value_stream_analytics.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Value stream analytics development guidelines -For information on how to configure value stream analytics (VSA) in GitLab, see our [analytics documentation](../user/analytics/value_stream_analytics.md). +For information on how to configure value stream analytics (VSA) in GitLab, see our [analytics documentation](../user/group/value_stream_analytics/index.md). ## How does Value Stream Analytics work? @@ -290,7 +290,7 @@ considered legacy, which will be phased out at some point. ## Frontend -[Project VSA](../user/analytics/value_stream_analytics.md) is available for all users and: +[Project VSA](../user/group/value_stream_analytics/index.md) is available for all users and: - Includes a mixture of key and DORA metrics based on the tier. - Uses the set of [default stages](#default-stages). diff --git a/doc/development/workhorse/configuration.md b/doc/development/workhorse/configuration.md index 84fb557d9ec..d19e85f3f7a 100644 --- a/doc/development/workhorse/configuration.md +++ b/doc/development/workhorse/configuration.md @@ -189,7 +189,9 @@ You can also set the `GITLAB_WORKHORSE_SENTRY_ENVIRONMENT` environment variable use the Sentry environment feature to separate staging, production and development. -Omnibus GitLab (`/etc/gitlab/gitlab.rb`): +::Tabs + +:::TabTitle Linux package (Omnibus) ```ruby gitlab_workhorse['env'] = { @@ -198,13 +200,15 @@ gitlab_workhorse['env'] = { } ``` -Source installations (`/etc/default/gitlab`): +:::TabTitle Self-compiled (source) ```plaintext export GITLAB_WORKHORSE_SENTRY_DSN='https://foobar' export GITLAB_WORKHORSE_SENTRY_ENVIRONMENT='production' ``` +::EndTabs + ## Distributed tracing Workhorse supports distributed tracing through [LabKit](https://gitlab.com/gitlab-org/labkit/) diff --git a/doc/downgrade_ee_to_ce/index.md b/doc/downgrade_ee_to_ce/index.md index 6a3fcab8bde..e541f67cac7 100644 --- a/doc/downgrade_ee_to_ce/index.md +++ b/doc/downgrade_ee_to_ce/index.md @@ -6,11 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Downgrading from EE to CE -If you ever decide to downgrade your Enterprise Edition back to the -Community Edition, there are a few steps you need to take beforehand. On Omnibus GitLab -installations, these steps are made before installing the CE package on top of -the current EE package. On installations from source, they are done before -you change remotes and fetch the latest CE code. +If you ever decide to downgrade your Enterprise Edition (EE) back to the +Community Edition (CE), there are a few steps you need to take beforehand: + +- For Linux package installations, these steps are done before installing the CE package on top of the current EE + package. +- For self-compiled installations, these steps are done before you change remotes and fetch the latest CE code. ## Disable Enterprise-only features @@ -38,19 +39,23 @@ use another column for that information.) All integrations are created automatically for every project you have. To avoid getting this error, you must remove all records with the type set to -`GithubService` from your database: +`GithubService` from your database. + +::Tabs -- **Omnibus Installation** +:::TabTitle Linux package (Omnibus) - ```shell - sudo gitlab-rails runner "Integration.where(type: ['GithubService']).delete_all" - ``` +```shell +sudo gitlab-rails runner "Integration.where(type: ['GithubService']).delete_all" +``` -- **Source Installation** +:::TabTitle Self-compiled (source) - ```shell - bundle exec rails runner "Integration.where(type: ['GithubService']).delete_all" production - ``` +```shell +bundle exec rails runner "Integration.where(type: ['GithubService']).delete_all" production +``` + +::EndTabs NOTE: If you are running `GitLab =< v13.0` you must also remove `JenkinsDeprecatedService` records @@ -74,25 +79,25 @@ back to EE and restore the behavior if you leave it alone. After performing the above mentioned steps, you are now ready to downgrade your GitLab installation to the Community Edition. -- **Omnibus Installation** +Remember to follow the correct [update guides](../update/index.md) to make sure all dependencies are up to date. + +### Linux package installations + +To downgrade a Linux package installation, you can install the Community Edition package on top of +the currently installed one. You can do this manually, by either: - To downgrade an Omnibus installation, it is sufficient to install the Community - Edition package on top of the currently installed one. You can do this manually, - by directly [downloading the package](https://packages.gitlab.com/gitlab/gitlab-ce) - you need, or by adding our CE package repository and following the - [CE installation instructions](https://about.gitlab.com/install/?version=ce). +- Directly [downloading the package](https://packages.gitlab.com/gitlab/gitlab-ce). +- Adding our CE package repository and following the [CE installation instructions](https://about.gitlab.com/install/?version=ce). -- **Source Installation** +### Self-compiled installations - To downgrade a source installation, you must replace the current remote of - your GitLab installation with the Community Edition's remote. After that, you - can fetch the latest changes, and checkout the latest stable branch: +To downgrade a self-compiled installation: - ```shell - git remote set-url origin git@gitlab.com:gitlab-org/gitlab-foss.git - git fetch --all - git checkout 8-x-stable - ``` +1. Replace the current remote of your GitLab installation with the Community Edition remote. +1. Fetch the latest changes, and check out the latest stable branch: -Remember to follow the correct [update guides](../update/index.md) to make -sure all dependencies are up to date. + ```shell + git remote set-url origin git@gitlab.com:gitlab-org/gitlab-foss.git + git fetch --all + git checkout 8-x-stable + ``` diff --git a/doc/integration/glab/img/glabgettingstarted.gif b/doc/editor_extensions/gitlab_cli/img/glabgettingstarted.gif Binary files differindex cf335294e41..cf335294e41 100644 --- a/doc/integration/glab/img/glabgettingstarted.gif +++ b/doc/editor_extensions/gitlab_cli/img/glabgettingstarted.gif diff --git a/doc/editor_extensions/gitlab_cli/index.md b/doc/editor_extensions/gitlab_cli/index.md new file mode 100644 index 00000000000..5f5bdfe091e --- /dev/null +++ b/doc/editor_extensions/gitlab_cli/index.md @@ -0,0 +1,108 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# GitLab CLI - `glab` **(FREE ALL)** + +GLab is an open source GitLab CLI tool. It brings GitLab to your terminal: +next to where you are already working with Git and your code, without +switching between windows and browser tabs. + +- Work with issues. +- Work with merge requests. +- Watch running pipelines directly from your CLI. + + + +The GitLab CLI uses commands structured like `glab <command> <subcommand> [flags]` +to perform many of the actions you usually do from the GitLab user interface: + +```shell +# Sign in +glab auth login --stdin < token.txt + +# View a list of issues +glab issue list + +# Create merge request for issue 123 +glab mr for 123 + +# Check out the branch for merge request 243 +glab mr checkout 243 + +# Watch the pipeline in progress +glab pipeline ci view + +# View, approve, and merge the merge request +glab mr view +glab mr approve +glab mr merge +``` + +## Core commands + +- [`glab alias`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/alias) +- [`glab api`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/api) +- [`glab auth`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/auth) +- [`glab check-update`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/check-update) +- [`glab ci`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/ci) +- [`glab completion`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/completion) +- [`glab config`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/config) +- [`glab incident`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/incident) +- [`glab issue`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/issue) +- [`glab label`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/label) +- [`glab mr`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/mr) +- [`glab release`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/release) +- [`glab repo`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/repo) +- [`glab schedule`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/schedule) +- [`glab snippet`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/snippet) +- [`glab ssh-key`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/ssh-key) +- [`glab user`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/user) +- [`glab variable`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/variable) + +## Install the CLI + +Installation instructions are available in the GLab +[`README`](https://gitlab.com/gitlab-org/cli/#installation). + +## Authenticate with GitLab + +To authenticate with your GitLab account, run `glab auth login`. +`glab` respects tokens set using `GITLAB_TOKEN`. + +## Report issues + +Open an issue in the [`gitlab-org/cli` repository](https://gitlab.com/gitlab-org/cli/-/issues/new) +to send us feedback. + +## Related topics + +- [Install the CLI](https://gitlab.com/gitlab-org/cli/-/blob/main/README.md#installation) +- [Documentation](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source) +- Extension source code in the [`cli`](https://gitlab.com/gitlab-org/cli/) project + +## Troubleshooting + +### `glab completion` commands fail when using the 1Password shell plugin + +The [1Password shell plugin](https://developer.1password.com/docs/cli/shell-plugins/gitlab/) +adds the alias `glab='op plugin run -- glab'`, which can interfere with the `glab completion` +command. If your `glab completion` commands fail, configure your shell to prevent expanding aliases +before performing completions: + +- For Zsh, edit your `~/.zshrc` file and add this line: + + ```plaintext + setopt completealiases + ``` + +- For Bash, edit your `~/.bashrc` file and add this line: + + ```plaintext + complete -F _functionname glab + ``` + +For more information, see [issue 122](https://github.com/1Password/shell-plugins/issues/122) +for the 1Password shell plugin. diff --git a/doc/editor_extensions/index.md b/doc/editor_extensions/index.md new file mode 100644 index 00000000000..11220bc716c --- /dev/null +++ b/doc/editor_extensions/index.md @@ -0,0 +1,27 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Editor and IDE Extensions + +GitLab has plugins and extensions to extend GitLab functionality to the following editors: + +- [Visual Studio Code](visual_studio_code/index.md) +- [JetBrains IDEs](jetbrains_ide/index.md) +- [Visual Studio](visual_studio/index.md) +- [Neovim](neovim/index.md) + +GitLab also supports developers in their command line interface with [`glab`](gitlab_cli/index.md) the GitLab CLI. + +## Features + +A complete list of the features and capabilities of each extension can be found in the documentation home for each extension. + +## Related topics + +- [How we created a GitLab Workflow Extension for VS Code](https://about.gitlab.com/blog/2020/07/31/use-gitlab-with-vscode/) +- [GitLab for Visual Studio](https://about.gitlab.com/blog/2023/06/29/gitlab-visual-studio-extension/) +- [GitLab for JetBrains and Neovim](https://about.gitlab.com/blog/2023/07/25/gitlab-jetbrains-neovim-plugins/) +- [Put `glab` at your fingertips with the GitLab CLI](https://about.gitlab.com/blog/2022/12/07/introducing-the-gitlab-cli/) diff --git a/doc/editor_extensions/jetbrains_ide/index.md b/doc/editor_extensions/jetbrains_ide/index.md new file mode 100644 index 00000000000..dcf13570b11 --- /dev/null +++ b/doc/editor_extensions/jetbrains_ide/index.md @@ -0,0 +1,52 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# GitLab plugin for JetBrains IDEs + +The [GitLab plugin](https://plugins.jetbrains.com/plugin/22325-gitlab) +integrates GitLab with JetBrains IDEs. The following JetBrains IDEs are supported: + +- IntelliJ IDEA Ultimate — 2023.2 +- AppCode — build 232.7754.73 — 232.* +- Rider — 2023.2-RC1 (rc) +- DataGrip — 2023.2 +- DataSpell — 2023.2 +- GoLand — 2023.2 +- Aqua — 2023.2 (preview) +- Android Studio — build 232.7754.73 — 232.* +- MPS — build 232.7754.73 — 232.* +- RubyMine — 2023.2 +- PhpStorm — 2023.2 (rc) +- PyCharm Community — 2023.2 +- IntelliJ IDEA Community — 2023.2 +- PyCharm Educational — build 232.7754.73 — 232.* +- WebStorm — 2023.2 +- CLion — 2023.2 +- IntelliJ IDEA Educational — build 232.7754.73 — 232.* +- PyCharm Professional — 2023.2 + +## Supported features + +GitLab for JetBrains supports [GitLab Duo Code Suggestions](../../user/project/repository/code_suggestions.md). + +## Download the extension + +Download the extension from the [JetBrains Plugin Marketplace](https://plugins.jetbrains.com/plugin/22325-gitlab). + +## Configure the extension + +Instructions for getting started can be found in the project README under [setup](https://gitlab.com/gitlab-org/editor-extensions/gitlab-jetbrains-plugin#setup). + +## Report issues with the extension + +Report any issues, bugs, or feature requests in the +[`gitlab-jetbrains-plugin` issue queue](https://gitlab.com/gitlab-org/editor-extensions/gitlab-jetbrains-plugin/-/issues). + +## Related topics + +- [Download the plugin](https://plugins.jetbrains.com/plugin/22325-gitlab) +- [Plugin documentation](https://gitlab.com/gitlab-org/editor-extensions/gitlab-jetbrains-plugin/-/blob/main/README.md) +- [View source code](https://gitlab.com/gitlab-org/editor-extensions/gitlab-jetbrains-plugin) diff --git a/doc/editor_extensions/neovim/index.md b/doc/editor_extensions/neovim/index.md new file mode 100644 index 00000000000..e2e410ae82c --- /dev/null +++ b/doc/editor_extensions/neovim/index.md @@ -0,0 +1,30 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# GitLab plugin for Neovim - `gitlab.vim` + +The [GitLab plugin](https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim) +integrates GitLab with Neovim. The following Neovim versions are supported: + +- 0.9+ + +## Supported features + +GitLab for Neovim supports [GitLab Duo Code Suggestions](../../user/project/repository/code_suggestions.md). + +## Install and configure the extension + +Instructions for getting started can be found in the project README under [setup](https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim#setup). + +## Report issues with the extension + +Report any issues, bugs, or feature requests in the +[`gitlab.vim` issue queue](https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim/-/issues). + +## Related topics + +- [Plugin documentation](https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim/-/blob/main/README.md) +- [View source code](https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim) diff --git a/doc/editor_extensions/visual_studio/index.md b/doc/editor_extensions/visual_studio/index.md new file mode 100644 index 00000000000..744f7759bf5 --- /dev/null +++ b/doc/editor_extensions/visual_studio/index.md @@ -0,0 +1,36 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# GitLab extension for Visual Studio + +The [GitLab extension](https://marketplace.visualstudio.com/items?itemName=GitLab.GitLabExtensionForVisualStudio) +integrates GitLab with Visual Studio. The following Visual Studio versions are supported: + +- Visual Studio 2022 (AMD64) +- Visual Studio 2022 (Arm64) + +## Supported features + +GitLab for Visual Studio supports [GitLab Duo Code Suggestions](../../user/project/repository/code_suggestions.md). + +## Download the extension + +Download the extension from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=GitLab.GitLabExtensionForVisualStudio). + +## Configure the extension + +Instructions for getting started can be found in the project README under [setup](https://gitlab.com/gitlab-org/editor-extensions/gitlab-visual-studio-extension/#setup). + +## Report issues with the extension + +Report any issues, bugs, or feature requests in the +[`gitlab-visual-studio-extension` issue queue](https://gitlab.com/gitlab-org/editor-extensions/gitlab-visual-studio-extension/-/issues). + +## Related topics + +- [Download the plugin](https://marketplace.visualstudio.com/items?itemName=GitLab.GitLabExtensionForVisualStudio) +- [Plugin documentation](https://gitlab.com/gitlab-org/editor-extensions/gitlab-visual-studio-extension/-/blob/main/README.md) +- [View source code](https://gitlab.com/gitlab-org/editor-extensions/gitlab-visual-studio-extension) diff --git a/doc/editor_extensions/visual_studio_code/index.md b/doc/editor_extensions/visual_studio_code/index.md new file mode 100644 index 00000000000..7c49879be13 --- /dev/null +++ b/doc/editor_extensions/visual_studio_code/index.md @@ -0,0 +1,49 @@ +--- +stage: Create +group: IDE +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 +--- + +# GitLab Workflow extension for VS Code + +The [GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) +integrates GitLab with Visual Studio Code. You can decrease context switching and +do more day-to-day tasks in Visual Studio Code, such as: + +- [View issues](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-issues-review-mrs). +- Run [common commands](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#commands) + from the Visual Studio Code [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette). +- Create and [review](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#merge-request-reviews) + merge requests directly from Visual Studio Code. +- [Validate your GitLab CI/CD configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-cicd-configuration). +- [View the status of your pipeline](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#information-about-your-branch-pipelines-mr-closing-issue). +- [View the output of CI/CD jobs](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#view-the-job-output). +- [Create](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#create-snippet) + and paste snippets to, and from, your editor. +- [Browse repositories](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-a-repository-without-cloning) + without cloning them. +- [Receive Code Suggestions](../../user/project/repository/code_suggestions.md). + +## Download the extension + +Download the extension from the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). + +## Configure the extension + +After you [download the extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) +you can [configure](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#extension-settings): + +- [Features to display or hide](https://gitlab.com/gitlab-org/gitlab-vscode-extension#extension-settings). +- [Self-signed certificate](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#self-signed-certificates) information. +- [Code Suggestions](../../user/project/repository/code_suggestions.md). + +## Report issues with the extension + +Report any issues, bugs, or feature requests in the +[`gitlab-vscode-extension` issue queue](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/issues). + +## Related topics + +- [Download the extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) +- [Extension documentation](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/README.md) +- [View source code](https://gitlab.com/gitlab-org/gitlab-vscode-extension/) diff --git a/doc/gitlab-basics/add-file.md b/doc/gitlab-basics/add-file.md index b5c4c78ac8e..255d78ab915 100644 --- a/doc/gitlab-basics/add-file.md +++ b/doc/gitlab-basics/add-file.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: howto --- -# Add a file to a repository **(FREE)** +# Add a file to a repository **(FREE ALL)** Adding files to a repository is a small, but key, task. No matter where the code, images, or documents were created, Git tracks them after you add them to your repository. diff --git a/doc/gitlab-basics/feature_branch_workflow.md b/doc/gitlab-basics/feature_branch_workflow.md index ed84d584f81..cbca22c1e55 100644 --- a/doc/gitlab-basics/feature_branch_workflow.md +++ b/doc/gitlab-basics/feature_branch_workflow.md @@ -4,7 +4,7 @@ group: Source Code 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" --- -# Feature branch workflow **(FREE)** +# Feature branch workflow **(FREE ALL)** To merge changes from a local branch to a feature branch, follow this workflow. diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md index c824fc2e44f..91fa91e3a6a 100644 --- a/doc/gitlab-basics/start-using-git.md +++ b/doc/gitlab-basics/start-using-git.md @@ -6,7 +6,7 @@ type: howto, tutorial description: "Introduction to using Git through the command line." --- -# Command line Git **(FREE)** +# Command line Git **(FREE ALL)** [Git](https://git-scm.com/) is an open-source distributed version control system. GitLab is built on top of Git. @@ -211,7 +211,7 @@ The remote tells Git where to push or pull from. To add a remote to your local copy: -1. In GitLab, [create a project](../user/project/index.md#create-a-project) to hold your files. +1. In GitLab, [create a project](../user/project/index.md) to hold your files. 1. Visit this project's homepage, scroll down to **Push an existing folder**, and copy the command that starts with `git remote add`. 1. On your computer, open the terminal in the directory you've initialized, paste the command you copied, and press <kbd>enter</kbd>: diff --git a/doc/install/aws/gitlab_hybrid_on_aws.md b/doc/install/aws/gitlab_hybrid_on_aws.md index b4d55e30ab1..42488becbd6 100644 --- a/doc/install/aws/gitlab_hybrid_on_aws.md +++ b/doc/install/aws/gitlab_hybrid_on_aws.md @@ -14,9 +14,9 @@ Amazon provides a managed Kubernetes service offering known as [Amazon Elastic K ## Tested AWS Bill of Materials by reference architecture size -| GitLab Cloud Native Hybrid Ref Arch | GitLab Baseline Performance Test Results Omnibus on Instances | AWS Bill of Materials (BOM) for CNH | AWS Build Performance Testing Results for [CNH](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/5K/5k-QuickStart-ARM-RDS-Redis_v13-12-3-ee_2021-07-23_140128/5k-QuickStart-ARM-RDS-Redis_v13-12-3-ee_2021-07-23_140128_results.txt) | CNH Cost Estimate 3 AZs* | +| GitLab Cloud Native Hybrid Ref Arch | GitLab Baseline Performance Test Results (using the Linux package on instances) | AWS Bill of Materials (BOM) for CNH | AWS Build Performance Testing Results for [CNH](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/5K/5k-QuickStart-ARM-RDS-Redis_v13-12-3-ee_2021-07-23_140128/5k-QuickStart-ARM-RDS-Redis_v13-12-3-ee_2021-07-23_140128_results.txt) | CNH Cost Estimate 3 AZs* | | ------------------------------------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -| [2K Omnibus](../../administration/reference_architectures/2k_users.md) | [2K Baseline](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/2k) | [2K Cloud Native Hybrid on EKS](#2k-cloud-native-hybrid-on-eks) | GPT Test Results | [1 YR Ec2 Compute Savings + 1 YR RDS & ElastiCache RIs](https://calculator.aws/#/estimate?id=544bcf1162beae6b8130ad257d081cdf9d4504e3)<br />(2 AZ Cost Estimate is in BOM Below) | +| [2K Linux package installation](../../administration/reference_architectures/2k_users.md) | [2K Baseline](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/2k) | [2K Cloud Native Hybrid on EKS](#2k-cloud-native-hybrid-on-eks) | GPT Test Results | [1 YR Ec2 Compute Savings + 1 YR RDS & ElastiCache RIs](https://calculator.aws/#/estimate?id=544bcf1162beae6b8130ad257d081cdf9d4504e3)<br />(2 AZ Cost Estimate is in BOM Below) | | [3K](../../administration/reference_architectures/3k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative) | [3k Baseline](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/3k) | [3K Cloud Native Hybrid on EKS](#3k-cloud-native-hybrid-on-eks) | [3K Full Fixed Scale GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/3K/3k-QuickStart-ARM-RDS-Cache_v13-12-3-ee_2021-07-23_124216/3k-QuickStart-ARM-RDS-Cache_v13-12-3-ee_2021-07-23_124216_results.txt)<br /><br />[3K Elastic Auto Scale GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/3K/3k-QuickStart-AutoScale-ARM-RDS-Cache_v13-12-3-ee_2021-07-23_194200/3k-QuickStart-AutoScale-ARM-RDS-Cache_v13-12-3-ee_2021-07-23_194200_results.txt) | [1 YR Ec2 Compute Savings + 1 YR RDS & ElastiCache RIs](https://calculator.aws/#/estimate?id=f1294fec554e21be999711cddcdab9c5e7f83f14)<br />(2 AZ Cost Estimate is in BOM Below) | | [5K](../../administration/reference_architectures/5k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative) | [5k Baseline](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/5k) | [5K Cloud Native Hybrid on EKS](#5k-cloud-native-hybrid-on-eks) | [5K Full Fixed Scale GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/5K/5k-QuickStart-ARM-RDS-Redis_v13-12-3-ee_2021-07-23_140128/5k-QuickStart-ARM-RDS-Redis_v13-12-3-ee_2021-07-23_140128_results.txt)<br /><br />[5K AutoScale from 25% GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/5K/5k-QuickStart-AutoScale-From-25Percent-ARM-RDS-Redis_v13-12-3-ee_2021-07-24_102717/5k-QuickStart-AutoScale-From-25Percent-ARM-RDS-Redis_v13-12-3-ee_2021-07-24_102717_results.txt) | [1 YR Ec2 Compute Savings + 1 YR RDS & ElastiCache RIs](https://calculator.aws/#/estimate?id=330ee43c5b14662db5df6e52b34898d181a09e16) | | [10K](../../administration/reference_architectures/10k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative) | [10k Baseline](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/10k) | [10K Cloud Native Hybrid on EKS](#10k-cloud-native-hybrid-on-eks) | [10K Full Fixed Scale GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/10K/GL-CloudNative-10k-RDS-Graviton_v13-12-3-ee_2021-07-08_194647/GL-CloudNative-10k-RDS-Graviton_v13-12-3-ee_2021-07-08_194647_results.txt)<br /><br />[10K Elastic Auto Scale GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/10K/GL-CloudNative-10k-AutoScaling-Test_v13-12-3-ee_2021-07-09_115139/GL-CloudNative-10k-AutoScaling-Test_v13-12-3-ee_2021-07-09_115139_results.txt) | [10K 1 YR Ec2 Compute Savings + 1 YR RDS & ElastiCache RIs](https://calculator.aws/#/estimate?id=5ac2e07a22e01c36ee76b5477c5a046cd1bea792) | @@ -32,7 +32,7 @@ Amazon provides a managed Kubernetes service offering known as [Amazon Elastic K ## Available Infrastructure as Code for GitLab Cloud Native Hybrid -The [GitLab Environment Toolkit (GET)](https://gitlab.com/gitlab-org/gitlab-environment-toolkit/-/blob/main/README.md) is an effort made by GitLab to create a multi-cloud, multi-GitLab (Omnibus + Cloud Native Hybrid) toolkit to provision GitLab. GET is developed by GitLab developers and is open to community contributions. GET is where GitLab is investing its resources as the primary option for Infrastructure as Code, and is being actively used in production as a part of [GitLab Dedicated](../../subscriptions/gitlab_dedicated/index.md). +The [GitLab Environment Toolkit (GET)](https://gitlab.com/gitlab-org/gitlab-environment-toolkit/-/blob/main/README.md) is an effort made by GitLab to create a multi-cloud, multi-GitLab (Linux package installation + Cloud Native Hybrid) toolkit to provision GitLab. GET is developed by GitLab developers and is open to community contributions. GET is where GitLab is investing its resources as the primary option for Infrastructure as Code, and is being actively used in production as a part of [GitLab Dedicated](../../subscriptions/gitlab_dedicated/index.md). For more information about the project, see [GitLab Environment Toolkit](https://gitlab.com/gitlab-org/gitlab-environment-toolkit/-/blob/main/README.md). @@ -58,8 +58,8 @@ The Beta version deploys Aurora PostgreSQL, but the release version will deploy | Compatible with AWS Meta-Automation Services (via CloudFormation) | - [AWS Service Catalog](https://aws.amazon.com/servicecatalog/) (Direct Import)<br>- [ServiceNow via an AWS Service Catalog Connector](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/integrations-servicenow.html#integrations-servicenow)<br>- [Jira Service Manager via an AWS Service Catalog Connector](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/integrations-jiraservicedesk.html#integrations-jiraservicedesk)<br>- [AWS Control Tower](https://docs.aws.amazon.com/controltower/) ([Integration](https://aws.amazon.com/blogs/infrastructure-and-automation/deploy-aws-quick-start-to-multiple-accounts-using-aws-control-tower/))<br>- Quick Starts<br>- [AWS SaaS Factory](https://aws.amazon.com/partners/programs/saas-factory/) | No | | Results in a Ready-to-Use instance | Yes | Manual Actions or <br />Supplemental IaC Required | | **<u>Configuration Features</u>** | | | -| Can deploy Omnibus GitLab (non-Kubernetes) | No | Yes | -| Can deploy Single Instance Omnibus GitLab (non-Kubernetes) | No | Yes | +| Can deploy Linux package (non-Kubernetes) | No | Yes | +| Can deploy a single instance by using the Linux package (non-Kubernetes) | No | Yes | | Complete Internal Encryption | 85%, Targeting 100% | Manual | | AWS GovCloud Support | Yes | TBD | | No Code Form-Based Deployment User Experience Available | Yes | No | @@ -94,7 +94,7 @@ The AWS Quick Start for GitLab Cloud Native Hybrid on EKS has been tested with G ## AWS PaaS qualified for all GitLab implementations -For both Omnibus GitLab or Cloud Native Hybrid implementations, the following GitLab Service roles can be performed by AWS Services (PaaS). Any PaaS solutions that require preconfigured sizing based on the scale of your instance will also be listed in the per-instance size Bill of Materials lists. Those PaaS that do not require specific sizing, are not repeated in the BOM lists (for example, AWS Certification Manager). +For both implementations that used the Linux package or Cloud Native Hybrid implementations, the following GitLab Service roles can be performed by AWS Services (PaaS). Any PaaS solutions that require preconfigured sizing based on the scale of your instance will also be listed in the per-instance size Bill of Materials lists. Those PaaS that do not require specific sizing, are not repeated in the BOM lists (for example, AWS Certification Manager). These services have been tested with GitLab. diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index 4dcf2ce0927..febe54a8bb6 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -24,9 +24,9 @@ The following are the currently available implementation patterns for GitLab whe [Provision GitLab Cloud Native Hybrid on AWS EKS (HA)](gitlab_hybrid_on_aws.md). This document includes instructions, patterns, and automation for installing GitLab Cloud Native Hybrid on AWS EKS. It also includes [Bill of Materials](https://en.wikipedia.org/wiki/Bill_of_materials) listings and links to Infrastructure as Code. GitLab Cloud Native Hybrid is the supported way to put as much of GitLab as possible into Kubernetes. -### Patterns to Install Omnibus GitLab on AWS EC2 (HA) +### Patterns to Install GitLab by using the Linux package on AWS EC2 (HA) -[Omnibus GitLab on AWS EC2 (HA)](manual_install_aws.md) - instructions for installing GitLab on EC2 instances. Manual instructions to build a GitLab instance or create your own Infrastructure as Code (IaC). +[Installing a GitLab POC on Amazon Web Services (AWS)](manual_install_aws.md) - instructions for installing GitLab on EC2 instances. Manual instructions to build a GitLab instance or create your own Infrastructure as Code (IaC). ### Patterns for EKS cluster provisioning diff --git a/doc/install/aws/manual_install_aws.md b/doc/install/aws/manual_install_aws.md index 92ef08c2447..a952180674c 100644 --- a/doc/install/aws/manual_install_aws.md +++ b/doc/install/aws/manual_install_aws.md @@ -783,7 +783,7 @@ For GitLab 12.1 and earlier, use `gitlab-rake gitlab:backup:create`. To restore GitLab, first review the [restore documentation](../../administration/backup_restore/index.md#restore-gitlab), and primarily the restore prerequisites. Then, follow the steps under the -[Linux package installations section](../../administration/backup_restore/restore_gitlab.md#restore-for-omnibus-gitlab-installations). +[Linux package installations section](../../administration/backup_restore/restore_gitlab.md#restore-for-linux-package-installations). ## Updating GitLab diff --git a/doc/install/docker.md b/doc/install/docker.md index 925da8a2b4a..ac15b5490ce 100644 --- a/doc/install/docker.md +++ b/doc/install/docker.md @@ -284,7 +284,7 @@ Here's an example that deploys GitLab with four runners as a [stack](https://doc ## Configuration -This container uses the official Omnibus GitLab package, so all configuration +This container uses the official Linux package, so all configuration is done in the unique configuration file `/etc/gitlab/gitlab.rb`. To access the GitLab configuration file, you can start a shell session in the @@ -326,7 +326,7 @@ You can pre-configure the GitLab Docker image by adding the environment variable `gitlab.rb` setting and is evaluated before the loading of the container's `gitlab.rb` file. This behavior allows you to configure the external GitLab URL, and make database configuration or any other option from the -[Omnibus GitLab template](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template). +[Linux package template](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template). The settings contained in `GITLAB_OMNIBUS_CONFIG` aren't written to the `gitlab.rb` configuration file, and are evaluated on load. @@ -544,7 +544,7 @@ To upgrade GitLab that was [installed using Docker Engine](#install-gitlab-using On the first run, GitLab will reconfigure and upgrade itself. Refer to the GitLab [Upgrade recommendations](../policy/maintenance.md#upgrade-recommendations) -when upgrading between major versions. +when upgrading between versions. ### Upgrade GitLab using Docker compose @@ -640,7 +640,7 @@ page. ## Troubleshooting -The following information will help if you encounter problems using Omnibus GitLab and Docker. +The following information will help if you encounter problems with an installation that used the Linux package and Docker. ### Diagnose potential problems @@ -657,8 +657,7 @@ sudo docker exec -it gitlab /bin/bash ``` From within the container you can administer the GitLab container as you would -usually administer an -[Omnibus installation](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md) +usually administer a [Linux package installation](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md). ### 500 Internal Error diff --git a/doc/install/install_methods.md b/doc/install/install_methods.md index 0463c926286..fb48107e81b 100644 --- a/doc/install/install_methods.md +++ b/doc/install/install_methods.md @@ -13,7 +13,7 @@ or use one of the following methods. | Installation method | Description | When to choose | |----------------------------------------------------------------|-------------|----------------| -| [Linux package](https://docs.gitlab.com/omnibus/installation/) | The official deb/rpm packages (also known as Omnibus GitLab). The package has GitLab and dependent components, including PostgreSQL, Redis, and Sidekiq. | Use if you want the most mature, scalable method. This version is also used on GitLab.com. <br>- For additional flexibility and resilience, see the [reference architecture documentation](../administration/reference_architectures/index.md).<br>- Review the [system requirements](requirements.md).<br>- View the [list of supported Linux operating systems](../administration/package_information/supported_os.md#supported-operating-systems). | +| [Linux package](https://docs.gitlab.com/omnibus/installation/) (previously known as Omnibus GitLab) | The official `deb` and `rpm` packages. The Linux package has GitLab and dependent components, including PostgreSQL, Redis, and Sidekiq. | Use if you want the most mature, scalable method. This version is also used on GitLab.com. <br>- For additional flexibility and resilience, see the [reference architecture documentation](../administration/reference_architectures/index.md).<br>- Review the [system requirements](requirements.md).<br>- View the [list of supported Linux operating systems](../administration/package_information/supported_os.md#supported-operating-systems). | | [Helm chart](https://docs.gitlab.com/charts/) | A chart for installing a cloud-native version of GitLab and its components on Kubernetes. | Use if your infrastructure is on Kubernetes and you're familiar with how it works. Management, observability, and some concepts are different than traditional deployments.<br/>- Administration and troubleshooting requires Kubernetes knowledge.<br/>- It can be more expensive for smaller installations. The default installation requires more resources than a single node Linux package deployment, because most services are deployed in a redundant fashion.<br/><br/> | | [Docker](docker.md) | The GitLab packages in a Docker container. | Use if you're familiar with Docker. | | [Source](installation.md) | GitLab and its components from scratch. | Use if none of the previous methods are available for your platform. Can use for unsupported systems like \*BSD.| @@ -29,10 +29,10 @@ or use one of the following methods. - macOS Installation of GitLab on these operating systems is possible, but not supported. -See the [installation from source guide](installation.md) and the [installation guides](https://about.gitlab.com/install/) for more information. +See the [installation guides](https://about.gitlab.com/install/) for more information. -See [OS versions that are no longer supported](../administration/package_information/supported_os.md#os-versions-that-are-no-longer-supported) for Omnibus installs page -for a list of supported and unsupported OS versions as well as the last support GitLab version for that OS. +See [OS versions that are no longer supported](../administration/package_information/supported_os.md#os-versions-that-are-no-longer-supported) +for a list of supported and unsupported OS versions for Linux package installations as well as the last support GitLab version for that OS. ## Microsoft Windows diff --git a/doc/install/installation.md b/doc/install/installation.md index 45c6b398a76..51a3941c5f5 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -48,8 +48,8 @@ If the highest number stable branch is unclear, check the [GitLab blog](https:// | [Ruby](#2-ruby) | `3.0.x` | From GitLab 15.10, Ruby 3.0 is required. You must use the standard MRI implementation of Ruby. We love [JRuby](https://www.jruby.org/) and [Rubinius](https://github.com/rubinius/rubinius#the-rubinius-language-platform), but GitLab needs several Gems that have native extensions. | | [RubyGems](#3-rubygems) | `3.4.x` | A specific RubyGems version is not fully needed, but it's recommended to update so you can enjoy some known performance improvements. | | [Go](#4-go) | `1.19.x` | From GitLab 16.1, Go 1.19 or later is required. | -| [Git](#git) | `2.38.x` | From GitLab 15.8, Git 2.38.x and later is required. It's highly recommended that you use the [Git version provided by Gitaly](#git). | -| [Node.js](#5-node) | `18.16.x` | From GitLab 16.1, Node.js 18.16 or later is required. | +| [Git](#git) | `2.41.x` | From GitLab 16.2, Git 2.41.x and later is required. You should use the [Git version provided by Gitaly](#git). | +| [Node.js](#5-node) | `18.17.x` | From GitLab 16.3, Node.js 18.17 or later is required. | ## GitLab directory structure @@ -260,7 +260,7 @@ GitLab requires the use of Node to compile JavaScript assets, and Yarn to manage JavaScript dependencies. The current minimum requirements for these are: -- `node` 18.x releases (v18.16.1 or later). +- `node` 18.x releases (v18.17.0 or later). [Other LTS versions of Node.js](https://github.com/nodejs/release#release-schedule) might be able to build assets, but we only guarantee Node.js 18.x. - `yarn` = v1.22.x (Yarn 2 is not supported yet) diff --git a/doc/install/migrate/compare_sm_to_saas.md b/doc/install/migrate/compare_sm_to_saas.md index 4cdc849be2c..b2fcbd5578e 100644 --- a/doc/install/migrate/compare_sm_to_saas.md +++ b/doc/install/migrate/compare_sm_to_saas.md @@ -1,124 +1,11 @@ --- -stage: Systems -group: Distribution -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 +redirect_to: '../../subscriptions/choosing_subscription.md' +remove_date: '2023-10-10' --- -# Comparison of GitLab self-managed with GitLab SaaS +This document was moved to [another location](../../subscriptions/choosing_subscription.md). -GitLab SaaS is the largest hosted instance of GitLab in the world, managed by an -[all-remote team](https://about.gitlab.com/company/culture/all-remote/) that knows GitLab best. With GitLab SaaS, updates, maintenance, and patches are all performed by this team. - -Self-managed GitLab gives you a deeper breadth of control over many of the functions and systems of the application. - -## Administration - -In GitLab SaaS, administration tasks are limited compared to a self-managed application. - -In a self-managed instance: - -- You have complete access and administrative control over the application, including the [Admin Area](../../administration/settings/index.md). -- You can impersonate, create, add, and remove users. -- You can assign the [`Auditor`](../../administration/auditor_users.md) user type and `External` role. - -On GitLab SaaS: - -- You have limited administrative control. For example, you cannot impersonate, create, add, or remove users. -- You cannot access the [Admin Area](../../administration/settings/index.md). -- You cannot assign the `Auditor` user type and `External` role. - -## Logs - -Logs give insight into your processes and can help GitLab Support maintain your application and resolve problems. - -In a self-managed instance: - -- You have full access to system logs. - -On GitLab SaaS: - -- You do not have access to system logs because they are at the instance level, and managed by the GitLab [infrastructure team](https://about.gitlab.com/handbook/engineering/infrastructure/). -- You can view [Audit Events](../../administration/audit_events.md) and the [GitLab API](../../api/audit_events.md). -- You must [request audit information](https://about.gitlab.com/handbook/support/workflows/log_requests.html) from the Support team. - -## Runners - -Runners are available for both SaaS and self-managed applications. - -In a self-managed instance, your runner availability and options are broader, but there are more [security concerns](https://docs.gitlab.com/runner/security/#security-for-self-managed-runners) to consider. - -On GitLab SaaS: - -- Private [runners](../../ci/runners/index.md) are available for GitLab SaaS [groups](../../user/group/index.md) and [projects](../../user/project/index.md). -- Shared runners provided by GitLab SaaS are not configurable. Each runner instance is used once for only one job, ensuring any sensitive data left on the system is destroyed after the job is complete. -- Shared runners are subject to usage limits and are [plan specific](https://about.gitlab.com/pricing/). - -## Custom Git hooks - -In a self-managed instance you can use any custom Git hooks. - -On GitLab SaaS: - -- SaaS users do not have access to the file system, and cannot use custom Git hooks. -- You can use [webhooks](../../user/project/integrations/webhooks.md) as an alternative. - -## API and GraphQL - -In a self-managed instance, users can access all API endpoints, including those that require instance `admin` permissions. - -On GitLab SaaS: - -- SaaS users have access to all of the [API endpoints](../../api/rest/index.md) except those that require instance `admin` permissions. -- Only authorized GitLab engineers have administrative access. - -## Authentication - -In a self-managed instance: - -- You can use an internal encryption key for your data store. -- You can view console logs. -- You can enforce jobs on every pipeline across the group or organization. -- You have control over your data backup. -- You can use the [Interactive Web Terminal](../../ci/interactive_web_terminal/index.md#interactive-web-terminals) for shared runners. - -On GitLab SaaS: - -- You cannot use internal encryption key for the data store ([bring-your-own-key](https://about.gitlab.com/handbook/security/threat-management/vulnerability-management/encryption-policy.html#rolling-your-own-crypto)). -- You cannot view console logs. -- You cannot enforce jobs on every pipeline across the group or organization. -- You cannot configure or control data backups. You must use [group](../../api/group_import_export.md) and [project](../../api/project_import_export.md) export. -- The [Interactive Web Terminal](../../ci/interactive_web_terminal/index.md#interactive-web-terminals) is not available for shared runners. - -## Public or private projects - -Project privacy is different when using a self-managed application or GitLab SaaS. - -In a self-managed instance, you control who can view your projects. - -On GitLab SaaS: - -- The GitLab SaaS instance is open to the public. -- When your projects are set as `Public`, they are open to everyone on the public internet. - -## Encryption - -In a self-managed instance, you control the encryption type and configuration. - -On GitLab SaaS: - -- An [Access Management Process](https://about.gitlab.com/handbook/security/#access-management-process) is in place. -- All data on GitLab.com is encrypted at rest by default. Access to encryption keys is strictly managed by GitLab. -- GitLab does not access your tenant data except as part of a verified service request from you. - -## Support - -In a self-managed instance: - -- You can access any of your back-end systems. -- Our Support team can request logs to assist you. - -On GitLab SaaS: - -- For your privacy and security, there is no public access to GitLab back-end systems. -- Support staff work with [Site Reliability Engineers](https://about.gitlab.com/job-families/engineering/infrastructure/site-reliability-engineer/) to support the [infrastructure](https://about.gitlab.com/handbook/engineering/infrastructure/). -- GitLab Support can access instance logs and view projects, as well as impersonate users. The Support Team can access your logs. +<!-- This redirect file can be deleted after <2023-10-10>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/install/openshift_and_gitlab/index.md b/doc/install/openshift_and_gitlab/index.md index 4f3df3ecff8..bb5a9b27cf5 100644 --- a/doc/install/openshift_and_gitlab/index.md +++ b/doc/install/openshift_and_gitlab/index.md @@ -12,40 +12,36 @@ OpenShift - GitLab compatibility can be addressed in three different aspects. Th OpenShift helps you to develop, deploy, and manage container-based applications. It provides you with a self-service platform to create, modify, and deploy applications on demand, thus enabling faster development and release life cycles. -## Use OpenShift to run GitLab Self-Managed +## Use OpenShift to run GitLab self-managed Running GitLab within an OpenShift cluster is officially supported using the GitLab Operator. You can learn more on [setting up GitLab on OpenShift on the GitLab Operator's documentation](https://docs.gitlab.com/charts/installation/operator.html). Some components (documented on the GitLab Operator doc) are not supported yet. -## Deploy to and integrate with OpenShift from GitLab - -Deploying custom or COTS applications on top of OpenShift from GitLab is supported using [the GitLab agent](../../user/clusters/agent/index.md). - ## Use OpenShift to run a GitLab Runner Fleet The GitLab Operator does not include the GitLab Runner. To install and manage a GitLab Runner fleet in an OpenShift cluster, use the [GitLab Runner Operator](https://gitlab.com/gitlab-org/gl-openshift/gitlab-runner-operator). -## Unsupported GitLab features +### Deploy to and integrate with OpenShift from GitLab -### Secure +Deploying custom or COTS applications on top of OpenShift from GitLab is supported using [the GitLab agent](../../user/clusters/agent/index.md). -- [License Compliance via the `License-Scanning.gitlab-ci.yml` CI/CD template](../../user/compliance/license_compliance/index.md). [License scanning of CycloneDX files](../../user/compliance/license_scanning_of_cyclonedx_files/index.md) is supported on OpenShift. -- [Code Quality scanning](../../ci/testing/code_quality.md) -- [Operational Container Scanning](../../user/clusters/agent/vulnerabilities.md) (Note: Pipeline [Container Scanning](../../user/application_security/container_scanning/index.md) is supported) +### Unsupported GitLab features -### Docker-in-Docker +#### Docker-in-Docker When using OpenShift to run a GitLab Runner Fleet, we do not support some GitLab features given OpenShift's security model. Features requiring Docker-in-Docker might not work. For Auto DevOps, the following features are not supported yet: -- Auto Code Quality -- Auto License Compliance +- [Auto Code Quality](../../ci/testing/code_quality.md) +- [License approval policies](../../user/compliance/license_approval_policies.md) +- [License Scanning](../../user/compliance/license_scanning_of_cyclonedx_files/index.md) is supported on OpenShift. - Auto Browser Performance Testing - Auto Build +- [Operational Container Scanning](../../user/clusters/agent/vulnerabilities.md) (Note: Pipeline [Container Scanning](../../user/application_security/container_scanning/index.md) is supported) For Auto Build, there's a [possible workaround using `kaniko`](../../ci/docker/using_kaniko.md). You can check the progress of the implementation in this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/332560). diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md index 6f4221f9e2e..885dcba952e 100644 --- a/doc/install/relative_url.md +++ b/doc/install/relative_url.md @@ -11,7 +11,7 @@ this is not possible due to a variety of reasons. In that case, GitLab can also be installed under a relative URL, for example `https://example.com/gitlab`. This document describes how to run GitLab under a relative URL for installations -from source. If you are using an Omnibus package, +from source. If you are using an official Linux package, [the steps are different](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab). Use this guide along with the [installation guide](installation.md) if you are installing GitLab for the first time. @@ -32,7 +32,7 @@ relative URL is: - `/home/git/gitlab-shell/config.yml` - `/etc/default/gitlab` -After all the changes, you must recompile the assets and [restart GitLab](../administration/restart_gitlab.md#installations-from-source). +After all the changes, you must recompile the assets and [restart GitLab](../administration/restart_gitlab.md#self-compiled-installations). ## Relative URL requirements @@ -115,7 +115,7 @@ Make sure to follow all steps below: If you are using a custom init script, make sure to edit the above GitLab Workhorse setting as needed. -1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect. +1. [Restart GitLab](../administration/restart_gitlab.md#self-compiled-installations) for the changes to take effect. ## Disable relative URL in GitLab diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 5e13628e815..b095f265808 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -14,7 +14,7 @@ This page includes information about the minimum requirements you need to instal The necessary hard drive space largely depends on the size of the repositories you want to store in GitLab but as a *guideline* you should have at least as much free space as all your repositories combined take up. -The Omnibus GitLab package requires about 2.5 GB of storage space for installation. +The Linux package requires about 2.5 GB of storage space for installation. If you want to be flexible about growing your hard drive space in the future consider mounting it using [logical volume management (LVM)](https://en.wikipedia.org/wiki/Logical_volume_management) so you can add more hard drives when you need them. @@ -66,14 +66,13 @@ process, such as PostgreSQL, which can have disastrous consequences. ## Database -PostgreSQL is the only supported database, which is bundled with the Omnibus GitLab package. +PostgreSQL is the only supported database, which is bundled with the Linux package. You can also use an [external PostgreSQL database](https://docs.gitlab.com/omnibus/settings/database.html#using-a-non-packaged-postgresql-database-management-server). -Support for MySQL was removed in [GitLab 12.1](../update/index.md#1210). ### PostgreSQL Requirements The server running PostgreSQL should have _at least_ 5-10 GB of storage -available, though the exact requirements [depend on the number of users](../administration/reference_architectures/index.md). +available, though the exact requirements [depend on the number of users](../administration/reference_architectures/index.md). For Ultimate customers the server should have _at least_ 12 GB of storage available, as 1 GB of vulnerability data needs to be imported. We highly recommend using at least the minimum PostgreSQL versions (as specified in the following table) as these were used for development and testing: @@ -107,10 +106,9 @@ Support for [PostgreSQL 9.6 and 10 was removed in GitLab 13.0](https://about.git #### Additional requirements for GitLab Geo If you're using [GitLab Geo](../administration/geo/index.md), we strongly -recommend running Omnibus GitLab-managed instances, as we actively develop and -test based on those. We try to be compatible with most external (not managed by -Omnibus GitLab) databases (for example, [AWS Relational Database Service (RDS)](https://aws.amazon.com/rds/)), -but we can't guarantee compatibility. +recommend running instances installed by using the Linux package, as we actively develop and +test based on those. We try to be compatible with most external (not managed by a Linux package installation) databases +(for example, [AWS Relational Database Service (RDS)](https://aws.amazon.com/rds/)), but we can't guarantee compatibility. #### Operating system locale compatibility and silent index corruption @@ -249,7 +247,7 @@ Redis stores all user sessions and the background task queue. The requirements for Redis are as follows: -- Redis 6.0 is required from GitLab 16.0 and later. +- Redis 6.x or 7.x is required in GitLab 16.0 and later. - Redis Cluster mode is not supported. Redis Standalone must be used. - Storage requirements for Redis are minimal, about 25 kB per user on average. diff --git a/doc/integration/advanced_search/elasticsearch.md b/doc/integration/advanced_search/elasticsearch.md index cdda85bb259..f23bfa47eba 100644 --- a/doc/integration/advanced_search/elasticsearch.md +++ b/doc/integration/advanced_search/elasticsearch.md @@ -51,8 +51,8 @@ Memory, CPU, and storage resource amounts vary depending on the amount of data y ## Install Elasticsearch -Elasticsearch is *not* included in the Omnibus packages or when you install from -source. You must [install it separately](https://www.elastic.co/guide/en/elasticsearch/reference/7.16/install-elasticsearch.html "Elasticsearch 7.x installation documentation") and ensure you select your version. Detailed information on how to install Elasticsearch is out of the scope of this page. +Elasticsearch is *not* included in the Linux package or when you self-compile your installation. +You must [install it separately](https://www.elastic.co/guide/en/elasticsearch/reference/7.16/install-elasticsearch.html "Elasticsearch 7.x installation documentation") and ensure you select your version. Detailed information on how to install Elasticsearch is out of the scope of this page. You can install Elasticsearch yourself, or use a cloud hosted offering such as [Elasticsearch Service](https://www.elastic.co/elasticsearch/service) (available on AWS, GCP, or Azure) or the [Amazon OpenSearch](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/gsg.html) service. @@ -79,21 +79,14 @@ To index Git repository data, GitLab uses an [indexer written in Go](https://git Depending on your GitLab version, there are different installation procedures for the Go indexer: -- For Omnibus GitLab 11.8 and later, see [Omnibus GitLab](#omnibus-gitlab). -- For installations from source or Omnibus GitLab 11.7 and earlier, - [install the indexer from source](#from-source). +- For Linux package installations, the Go indexer is included. +- For self-compiled installations, see [Install the indexer from source](#install-the-indexer-from-source). - If you're using the GitLab Development Kit, see [Elasticsearch in the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/elasticsearch.md). - If you're running a Helm deployment of GitLab 11.10 and later, [the indexer is already included](https://gitlab.com/gitlab-org/build/CNG/-/merge_requests/213). -### Omnibus GitLab +### Install the indexer from source -Starting with GitLab 11.8, the Go indexer is included in Omnibus GitLab. -The former Ruby-based indexer was removed in [GitLab 12.3](https://gitlab.com/gitlab-org/gitlab/-/issues/6481). - -### From source - -First, we need to install some dependencies, then we build and install -the indexer itself. +You first install some dependencies and then build and install the indexer itself. #### Install dependencies @@ -182,23 +175,26 @@ To enable advanced search: [license](../../administration/license.md). 1. Configure the [advanced search settings](#advanced-search-configuration) for - your Elasticsearch cluster. Do not enable **Search with Elasticsearch enabled** - yet. -1. Enable **Elasticsearch indexing** and select **Save changes**. This creates - an empty index if one does not already exist. -1. Select **Index all projects**. -1. Optional. Select **Check progress** to see the status of background jobs. -1. Personal snippets must be indexed using another Rake task: + your Elasticsearch cluster. Do not select the **Search with Elasticsearch enabled** checkbox yet. +1. Index all data with a Rake task. The task creates an empty index if one does not already exist and + enables Elasticsearch indexing if the indexing is not already enabled: ```shell + # WARNING: THIS WILL DELETE ALL EXISTING INDICES # Omnibus installations - sudo gitlab-rake gitlab:elastic:index_snippets + sudo gitlab-rake gitlab:elastic:index + # WARNING: THIS WILL DELETE ALL EXISTING INDICES # Installations from source - bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production + bundle exec rake gitlab:elastic:index RAILS_ENV=production ``` -1. After indexing completes, enable **Search with Elasticsearch enabled** and select **Save changes**. +1. Optional. Monitor the status of background jobs. + 1. On the left sidebar, select **Monitoring > Background Jobs**. + 1. On the Sidekiq dashboard, select **Queues** and wait for the `elastic_commit_indexer` + and `elastic_wiki_indexer` queues to drop to `0`. + These queues contain jobs to index code and wiki data for groups and projects. +1. After the indexing is complete, select the **Search with Elasticsearch enabled** checkbox, then select **Save changes**. NOTE: When your Elasticsearch cluster is down while Elasticsearch is enabled, @@ -208,6 +204,35 @@ Elasticsearch cluster. For GitLab instances with more than 50 GB of repository data, see [How to index large instances efficiently](#how-to-index-large-instances-efficiently). +### Enable with the **Index all projects** setting + +You can only use the **Index all projects** setting to perform +initial indexing, not to re-create an index from scratch. +To enable advanced search with **Index all projects**: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > Advanced Search**. +1. Select the **Elasticsearch indexing** checkbox, then select **Save changes**. +1. Select **Index all projects**. +1. Optional. Select **Check progress** to see the status of background jobs. + +To index epics, group wikis, personal snippets, and users, you must use Rake tasks: + +```shell +# Omnibus installations +sudo gitlab-rake gitlab:elastic:index_epics +sudo gitlab-rake gitlab:elastic:index_group_wikis +sudo gitlab-rake gitlab:elastic:index_snippets +sudo gitlab-rake gitlab:elastic:index_users + +# Installations from source +bundle exec rake gitlab:elastic:index_epics RAILS_ENV=production +bundle exec rake gitlab:elastic:index_group_wikis RAILS_ENV=production +bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production +bundle exec rake gitlab:elastic:index_users RAILS_ENV=production +``` + ### Advanced search configuration The following Elasticsearch settings are available: @@ -349,14 +374,12 @@ The index pattern `*` requires a few permissions for advanced search to work. ### Limit the number of namespaces and projects that can be indexed -If you check checkbox `Limit the number of namespaces and projects that can be indexed` -under **Elasticsearch indexing restrictions** more options become available. +When you select the **Limit the number of namespaces and projects that can be indexed** +checkbox, you can specify namespaces and projects to index. If the namespace is a group, +any subgroups and projects belonging to those subgroups are also indexed.  -You can select namespaces and projects to index exclusively. If the namespace is a group, it includes -any subgroups and projects belonging to those subgroups to be indexed as well. - Advanced search only provides cross-group code/commit search (global) if all name-spaces are indexed. In this particular scenario where only a subset of namespaces are indexed, a global search does not provide a code or commit scope. This is possible only in the scope of an indexed namespace. There is no way to code/commit search in multiple indexed namespaces (when only a subset of namespaces has been indexed). For example if two groups are indexed, there is no way to run a single code search on both. You can only run a code search on the first group and then on the second. You can filter the selection dropdown list by writing part of the namespace or project name you're interested in. @@ -519,6 +542,20 @@ Sometimes, you might want to abandon the unfinished reindex job and resume the i 1. Expand **Advanced Search**. 1. Clear the **Pause Elasticsearch indexing** checkbox. +## Index integrity + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112369) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `search_index_integrity`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/392981) in GitLab 16.0. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/392981) in GitLab 16.3. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `search_index_integrity`. +On GitLab.com, this feature is available. + +Index integrity detects and fixes missing repository data. +This feature is automatically used when code searches +scoped to a group or project return no results. + ## Advanced search migrations > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/234046) in GitLab 13.6. @@ -527,7 +564,29 @@ With reindex migrations running in the background, there's no need for a manual intervention. This usually happens in situations where new features are added to advanced search, which means adding or changing the way content is indexed. -To confirm that the advanced search migrations ran, you can check with: +### Migration dictionary files + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414674) in GitLab 16.3. + +Every migration has a corresponding dictionary file in the `ee/elastic/docs/` folder with the following information: + +```yaml +name: +version: +description: +group: +milestone: +introduced_by_url: +obsolete: +marked_obsolete_by_url: +marked_obsolete_in_milestone: +``` + +You can use this information, for example, to identify when a migration was introduced or was marked as obsolete. + +### Check for pending migrations + +To check for pending advanced search migrations, run this command: ```shell curl "$CLUSTER_URL/gitlab-production-migrations/_search?q=*" | jq . @@ -566,7 +625,7 @@ This should return something similar to: } ``` -To debug issues with the migrations you can check the [`elasticsearch.log` file](../../administration/logs/index.md#elasticsearchlog). +To debug issues with the migrations, check the [`elasticsearch.log`](../../administration/logs/index.md#elasticsearchlog) file. ### Retry a halted migration @@ -611,10 +670,13 @@ The following are some available Rake tasks: | Task | Description | |:--------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`sudo gitlab-rake gitlab:elastic:info`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Outputs debugging information for the advanced search integration. | -| [`sudo gitlab-rake gitlab:elastic:index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Enables Elasticsearch indexing and run `gitlab:elastic:create_empty_index`, `gitlab:elastic:clear_index_status`, `gitlab:elastic:index_projects`, `gitlab:elastic:index_snippets`, and `gitlab:elastic:index_users`. | +| [`sudo gitlab-rake gitlab:elastic:index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Enables Elasticsearch indexing and runs `gitlab:elastic:recreate_index`, `gitlab:elastic:clear_index_status`, `gitlab:elastic:index_group_entities`, `gitlab:elastic:index_projects`, `gitlab:elastic:index_snippets`, and `gitlab:elastic:index_users`. | | [`sudo gitlab-rake gitlab:elastic:pause_indexing`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Pauses Elasticsearch indexing. Changes are still tracked. Useful for cluster/index migrations. | | [`sudo gitlab-rake gitlab:elastic:resume_indexing`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Resumes Elasticsearch indexing. | | [`sudo gitlab-rake gitlab:elastic:index_projects`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Iterates over all projects, and queues Sidekiq jobs to index them in the background. It can only be used after the index is created. | +| [`sudo gitlab-rake gitlab:elastic:index_group_entities`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Invokes `gitlab:elastic:index_epics` and `gitlab:elastic:index_group_wikis`. +| [`sudo gitlab-rake gitlab:elastic:index_epics`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Indexes all epics from the groups where Elasticsearch is enabled. +| [`sudo gitlab-rake gitlab:elastic:index_group_wikis`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Indexes all wikis from the groups where Elasticsearch is enabled. | [`sudo gitlab-rake gitlab:elastic:index_projects_status`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Determines the overall status of the indexing. It is done by counting the total number of indexed projects, dividing by a count of the total number of projects, then multiplying by 100. | | [`sudo gitlab-rake gitlab:elastic:clear_index_status`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Deletes all instances of IndexStatus for all projects. This command results in a complete wipe of the index, and it should be used with caution. | | [`sudo gitlab-rake gitlab:elastic:create_empty_index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Generates empty indices (the default index and a separate issues index) and assigns an alias for each on the Elasticsearch side only if it doesn't already exist. | @@ -661,7 +723,7 @@ I, [2019-03-04T21:27:05.215266 #3384] INFO -- : Indexing GitLab User / test (ID When performing a search, the GitLab index uses the following scopes: | Scope Name | What it searches | -| ---------------- | ---------------------- | +|------------------|------------------------| | `commits` | Commit data | | `projects` | Project data (default) | | `blobs` | Code | @@ -672,6 +734,7 @@ When performing a search, the GitLab index uses the following scopes: | `snippets` | Snippet data | | `wiki_blobs` | Wiki contents | | `users` | Users | +| `epics` | Epic data | ## Tuning @@ -733,7 +796,7 @@ Make sure to prepare for this task by having a bundle exec rake gitlab:elastic:clear_index_status RAILS_ENV=production ``` -1. [Enable **Elasticsearch indexing**](#enable-advanced-search). +1. [Select the **Elasticsearch indexing** checkbox](#enable-advanced-search). 1. Indexing large Git repositories can take a while. To speed up the process, you can [tune for indexing speed](https://www.elastic.co/guide/en/elasticsearch/reference/current/tune-for-indexing-speed.html#tune-for-indexing-speed): - You can temporarily disable [`refresh`](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-refresh.html), the operation responsible for making changes to an index available to search. @@ -801,14 +864,20 @@ Make sure to prepare for this task by having a indexer to "forget" all progress, so it retries the indexing process from the start. -1. Personal snippets are not associated with a project and need to be indexed separately: +1. Epics, group wikis, personal snippets, and users are not associated with a project and must be indexed separately: ```shell # Omnibus installations + sudo gitlab-rake gitlab:elastic:index_epics + sudo gitlab-rake gitlab:elastic:index_group_wikis sudo gitlab-rake gitlab:elastic:index_snippets + sudo gitlab-rake gitlab:elastic:index_users # Installations from source + bundle exec rake gitlab:elastic:index_epics RAILS_ENV=production + bundle exec rake gitlab:elastic:index_group_wikis RAILS_ENV=production bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production + bundle exec rake gitlab:elastic:index_users RAILS_ENV=production ``` 1. Enable replication and refreshing again after indexing (only if you previously disabled it): @@ -850,7 +919,7 @@ Make sure to prepare for this task by having a } }' ``` -1. After the indexing has completed, enable [**Search with Elasticsearch enabled**](#enable-advanced-search). +1. After the indexing is complete, [select the **Search with Elasticsearch enabled** checkbox](#enable-advanced-search). ### Deleted documents diff --git a/doc/integration/advanced_search/elasticsearch_troubleshooting.md b/doc/integration/advanced_search/elasticsearch_troubleshooting.md index e8634cf5ef9..d13d47a1633 100644 --- a/doc/integration/advanced_search/elasticsearch_troubleshooting.md +++ b/doc/integration/advanced_search/elasticsearch_troubleshooting.md @@ -281,24 +281,26 @@ queue, or the index is somehow in a state where migrations just cannot proceed. It is always best to try to troubleshoot the root cause of the problem by [viewing the logs](#view-logs). -If there are no other options, then you always have the option of recreating the -entire index from scratch. If you have a small GitLab installation, this can -sometimes be a quick way to resolve a problem, but if you have a large GitLab -installation, then this might take a very long time to complete. Until the -index is fully recreated, your index does not serve correct search results, -so you may want to disable **Search with Elasticsearch** while it is running. +As a last resort, you can recreate the index from scratch. For small GitLab installations, +recreating the index can be a quick way to resolve some issues. For large GitLab +installations, however, this method might take a very long time. Your index +does not show correct search results until the indexing is complete. You might +want to clear the **Search with Elasticsearch enabled** checkbox +while the indexing is running. If you are sure you've read the above caveats and want to proceed, then you -should run the following Rake task to recreate the entire index from scratch: +should run the following Rake task to recreate the entire index from scratch. -**For Omnibus installations** +::Tabs + +:::TabTitle Linux package (Omnibus) ```shell # WARNING: DO NOT RUN THIS UNTIL YOU READ THE DESCRIPTION ABOVE sudo gitlab-rake gitlab:elastic:index ``` -**For installations from source** +:::TabTitle Self-compiled (source) ```shell # WARNING: DO NOT RUN THIS UNTIL YOU READ THE DESCRIPTION ABOVE @@ -306,6 +308,8 @@ cd /home/git/gitlab sudo -u git -H bundle exec rake gitlab:elastic:index ``` +::EndTabs + ### Troubleshooting performance Troubleshooting performance can be difficult on Elasticsearch. There is a ton of tuning @@ -403,7 +407,7 @@ There is also an easy way to check it automatically with `sudo gitlab-rake gitla This exception is seen when your Elasticsearch cluster is configured to reject requests above a certain size (10MiB in this case). This corresponds to the `http.max_content_length` setting in `elasticsearch.yml`. Increase it to a larger size and restart your Elasticsearch cluster. -AWS has [fixed limits](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/limits.html#network-limits) for this setting ("Maximum size of HTTP request payloads"), based on the size of the underlying instance. +AWS has [network limits](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/limits.html#network-limits) on the maximum size of HTTP request payloads based on the size of the underlying instance. Set the maximum bulk request size to a value lower than 10 MiB. ## `Faraday::TimeoutError (execution expired)` error when using a proxy diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index a7ab4ec5a84..19c86743eba 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.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 --- -# Akismet **(FREE)** +# Akismet **(FREE ALL)** GitLab uses [Akismet](https://akismet.com/) to prevent the creation of spam issues on public projects. Issues created through the web UI or the API can be submitted to diff --git a/doc/integration/alicloud.md b/doc/integration/alicloud.md index db27cb78173..9054341960f 100644 --- a/doc/integration/alicloud.md +++ b/doc/integration/alicloud.md @@ -4,7 +4,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 --- -# Use AliCloud as an OmniAuth authentication provider **(FREE)** +# Use AliCloud as an OmniAuth authentication provider **(FREE ALL)** You can enable the AliCloud OAuth 2.0 OmniAuth provider and sign in to GitLab using your AliCloud account. @@ -45,13 +45,13 @@ Sign in to the AliCloud platform and create an application on it. AliCloud gener 1. On your GitLab server, open the configuration file. - - **For Omnibus installations** + - For Linux package installations: ```shell sudo editor /etc/gitlab/gitlab.rb ``` - - **For installations from source** + - For self-compiled installations: ```shell cd /home/git/gitlab @@ -66,7 +66,7 @@ Sign in to the AliCloud platform and create an application on it. AliCloud gener 1. Add the provider configuration. Replace `YOUR_APP_ID` with the ID on the application details page and `YOUR_APP_SECRET` with the **SecretValue** you got when you registered the AliCloud application. - - **For Omnibus installations** + - For Linux package installations: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -78,7 +78,7 @@ Sign in to the AliCloud platform and create an application on it. AliCloud gener ] ``` - - **For installations from source** + - For self-compiled installations: ```yaml - { name: 'alicloud', @@ -89,5 +89,5 @@ Sign in to the AliCloud platform and create an application on it. AliCloud gener 1. Save the configuration file. 1. [Reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) - if you installed using the Linux package, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) + if you installed using the Linux package, or [restart GitLab](../administration/restart_gitlab.md#self-compiled-installations) if you installed from source. diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index 03b4980ad66..e6a6853cdef 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -4,7 +4,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 --- -# Auth0 OmniAuth Provider **(FREE SELF)** +# Use Auth0 as an OAuth 2.0 authentication provider **(FREE SELF)** To enable the Auth0 OmniAuth provider, you must create an Auth0 account, and an application. @@ -29,13 +29,13 @@ application. - `https://<your_gitlab_url>` 1. On your GitLab server, open the configuration file. - For Omnibus GitLab: + For Linux package installations: ```shell sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab @@ -85,7 +85,7 @@ application. - If you installed using the Linux package, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). - If you self-compiled your installation, - [restart GitLab](../administration/restart_gitlab.md#installations-from-source). + [restart GitLab](../administration/restart_gitlab.md#self-compiled-installations). On the sign-in page there should now be an Auth0 icon below the regular sign-in form. Select the icon to begin the authentication process. Auth0 asks the diff --git a/doc/integration/azure.md b/doc/integration/azure.md index d49fa8f53f7..08ca19a950b 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -4,7 +4,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 --- -# Use Microsoft Azure as an authentication provider **(FREE SELF)** +# Use Microsoft Azure as an OAuth 2.0 authentication provider **(FREE SELF)** You can enable the Microsoft Azure OAuth 2.0 OmniAuth provider and sign in to GitLab with your Microsoft Azure credentials. You can configure the provider that uses @@ -204,13 +204,13 @@ Alternatively, add the `User.Read.All` application permission. 1. On your GitLab server, open the configuration file. - - **For Omnibus installations** + - For Linux package installations: ```shell sudo editor /etc/gitlab/gitlab.rb ``` - - **For installations from source** + - For self-compiled installations: ```shell cd /home/git/gitlab @@ -225,7 +225,7 @@ Alternatively, add the `User.Read.All` application permission. 1. Add the provider configuration. Replace `<client_id>`, `<client_secret>`, and `<tenant_id>` with the values you got when you registered the Azure application. - - **For Omnibus installations** + - For Linux package installations: For the v1.0 endpoint: @@ -277,7 +277,7 @@ Alternatively, add the `User.Read.All` application permission. ] ``` - - **For installations from source** + - For self-compiled installations: For the v1.0 endpoint: @@ -316,7 +316,7 @@ Alternatively, add the `User.Read.All` application permission. 1. Save the configuration file. 1. [Reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) - if you installed using the Linux package, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) + if you installed using the Linux package, or [restart GitLab](../administration/restart_gitlab.md#self-compiled-installations) if you self-compiled your installation. 1. Refresh the GitLab sign-in page. A Microsoft icon should display below the @@ -326,3 +326,33 @@ Alternatively, add the `User.Read.All` application permission. Read [Enable OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user) for information on how existing GitLab users can connect to their new Azure AD accounts. + +## Troubleshooting + +### User sign in banner message: Extern UID has already been taken + +When signing in, you might get an error that states `Extern UID has already been taken`. + +To resolve this, use the [Rails console](../administration/operations/rails_console.md#starting-a-rails-console-session) to check if there is an existing user tied to the account: + +1. Find the `extern_uid`: + + ```ruby + id = Identity.where(extern_uid: '<extern_uid>') + ``` + +1. Print the content to find the username attached to that `extern_uid`: + + ```ruby + pp id + ``` + +If the `extern_uid` is attached to an account, you can use the username to sign in. + +If the `extern_uid` is not attached to any username, this might be because of a deletion error resulting in a ghost record. + +Run the following command to delete the identity to release the `extern uid`: + +```ruby + Identity.find('<id>').delete +``` diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index 81564e6eaae..7fad67116f3 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -11,12 +11,12 @@ account credentials to sign in to GitLab. You can also import your projects from Bitbucket.org. - To use Bitbucket.org as an OmniAuth provider, follow the - [Bitbucket OmniAuth provider](#bitbucket-omniauth-provider) section. + [Bitbucket OmniAuth provider](#use-bitbucket-as-an-oauth-20-authentication-provider) section. - To import projects from Bitbucket, follow both the - [Bitbucket OmniAuth provider](#bitbucket-omniauth-provider) and + [Bitbucket OmniAuth provider](#use-bitbucket-as-an-oauth-20-authentication-provider) and [Bitbucket project import](#bitbucket-project-import) sections. -## Bitbucket OmniAuth provider +## Use Bitbucket as an OAuth 2.0 authentication provider To enable the Bitbucket OmniAuth provider you must register your application with Bitbucket.org. Bitbucket generates an application ID and secret key for @@ -79,7 +79,7 @@ you to use. 1. Add the Bitbucket provider configuration: - For Omnibus packages: + For Linux package installations: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -93,7 +93,7 @@ you to use. ] ``` - For installations from source: + For self-compiled installations: ```yaml omniauth: @@ -111,7 +111,7 @@ you to use. 1. Save the configuration file. 1. For the changes to take effect, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) - if you installed using the Linux package, or [restart](../administration/restart_gitlab.md#installations-from-source) + if you installed using the Linux package, or [restart](../administration/restart_gitlab.md#self-compiled-installations) if you self-compiled your installation. On the sign-in page there should now be a Bitbucket icon below the regular diff --git a/doc/integration/datadog.md b/doc/integration/datadog.md index affc707f504..5e89cfbe6a0 100644 --- a/doc/integration/datadog.md +++ b/doc/integration/datadog.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Datadog **(FREE)** +# Datadog **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/270123) in GitLab 14.1 diff --git a/doc/integration/ding_talk.md b/doc/integration/ding_talk.md index fd836b80208..005bf0a3244 100644 --- a/doc/integration/ding_talk.md +++ b/doc/integration/ding_talk.md @@ -4,7 +4,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 --- -# DingTalk OAuth 2.0 OmniAuth provider **(FREE SELF)** +# Use DingTalk as an OAuth 2.0 authentication provider **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341898) in GitLab 14.5. > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/390855) in GitLab 15.10. @@ -38,13 +38,13 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene 1. On your GitLab server, open the configuration file. - For Omnibus package: + For Linux package installations: ```shell sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab @@ -56,9 +56,9 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene to add `dingtalk` as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account. -1. Add the provider configuration: +1. Add the provider configuration. - For Omnibus package: + For Linux package installations: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -71,7 +71,7 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene ] ``` - For installations from source: + For self-compiled installations: ```yaml - { name: 'dingtalk', @@ -88,4 +88,4 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene 1. For the changes to take effect, if you: - Installed using the Linux package, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). - - Self-compiled your installation, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). + - Self-compiled your installation, [restart GitLab](../administration/restart_gitlab.md#self-compiled-installations). diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index ef17b56d38f..2d0f0892f30 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# External issue trackers **(FREE)** +# External issue trackers **(FREE ALL)** GitLab has its own [issue tracker](../user/project/issues/index.md), but you can also configure an external issue tracker per GitLab project. diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index 4dd17d71602..0ff640306c3 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -4,7 +4,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 --- -# Facebook OAuth 2.0 OmniAuth Provider **(FREE)** +# Use Facebook as an OAuth 2.0 authentication provider **(FREE ALL)** To enable the Facebook OmniAuth provider you must register your application with Facebook. Facebook generates an app ID and secret key for you to use. @@ -58,13 +58,13 @@ Facebook. Facebook generates an app ID and secret key for you to use. 1. On your GitLab server, open the configuration file. - For Omnibus package: + For Linux package installations: ```shell sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab @@ -76,9 +76,9 @@ Facebook. Facebook generates an app ID and secret key for you to use. to add `facebook` as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account. -1. Add the provider configuration: +1. Add the provider configuration. - For Omnibus package: + For Linux package installations: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -91,7 +91,7 @@ Facebook. Facebook generates an app ID and secret key for you to use. ] ``` - For installations from source: + For self-compiled installations: ```yaml - { name: 'facebook', @@ -108,7 +108,7 @@ Facebook. Facebook generates an app ID and secret key for you to use. 1. For the changes to take effect: - If you installed using the Linux package, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). - - If you self-compiled your installation, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). + - If you self-compiled your installation, [restart GitLab](../administration/restart_gitlab.md#self-compiled-installations). On the sign in page there should now be a Facebook icon below the regular sign in form. Select the icon to begin the authentication process. Facebook asks the diff --git a/doc/integration/github.md b/doc/integration/github.md index 1f7b4f26476..df9a0db961b 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -4,7 +4,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 --- -# Use GitHub as an authentication provider **(FREE SELF)** +# Use GitHub as an OAuth 2.0 authentication provider **(FREE SELF)** You can integrate your GitLab instance with GitHub.com and GitHub Enterprise. You can import projects from GitHub, or sign in to GitLab @@ -47,7 +47,7 @@ your website could enable the covert redirect attack. | Client secret | `YOUR_APP_SECRET` | OAuth 2.0 client secret | | URL | `https://github.example.com/` | GitHub deployment URL | - - **For Omnibus installations** + - For Linux package installations: 1. Open the `/etc/gitlab/gitlab.rb` file. @@ -84,7 +84,7 @@ your website could enable the covert redirect attack. 1. Save the file and [reconfigure](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) GitLab. - - **For installations from source** + - For self-compiled installations: 1. Open the `config/gitlab.yml` file. @@ -110,7 +110,7 @@ your website could enable the covert redirect attack. args: { scope: 'user:email' } } ``` - 1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source) + 1. Save the file and [restart](../administration/restart_gitlab.md#self-compiled-installations) GitLab. 1. Refresh the GitLab sign-in page. A GitHub icon should display below the @@ -129,7 +129,7 @@ To fix this issue, you must disable SSL verification: 1. Set `verify_ssl` to `false` in the configuration file. - - **For Omnibus installations** + - For Linux package installations: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -145,7 +145,7 @@ To fix this issue, you must disable SSL verification: ] ``` - - **For installations from source** + - For self-compiled installations: ```yaml - { name: 'github', @@ -159,7 +159,7 @@ To fix this issue, you must disable SSL verification: 1. Change the global Git `sslVerify` option to `false` on the GitLab server. - - **For Omnibus installations in [GitLab 15.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6800) and later**: + - For Linux package installations running [GitLab 15.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6800) and later: ```ruby gitaly['gitconfig'] = [ @@ -167,13 +167,13 @@ To fix this issue, you must disable SSL verification: ] ``` - - **For Omnibus installations in GitLab 15.2 and earlier (legacy method)**: + - For Linux package installations running GitLab 15.2 and earlier (legacy method): ```ruby omnibus_gitconfig['system'] = { "http" => ["sslVerify = false"] } ``` - - **For installations from source in [GitLab 15.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6800) and later**, edit the Gitaly configuration (`gitaly.toml`): + - For self-compiled installations running [GitLab 15.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6800) and later, edit the Gitaly configuration (`gitaly.toml`): ```toml [[git.config]] @@ -181,14 +181,14 @@ To fix this issue, you must disable SSL verification: value = "false" ``` - - **For installations from source in GitLab 15.2 and earlier (legacy method)**: + - For self-compiled installations running GitLab 15.2 and earlier (legacy method): ```shell git config --global http.sslVerify false ``` 1. [Reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) - if you installed using the Linux package, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) + if you installed using the Linux package, or [restart GitLab](../administration/restart_gitlab.md#self-compiled-installations) if you self-compiled your installation. ### Signing in using GitHub Enterprise returns a 500 error diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 8767d1398ac..92709d974aa 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -37,13 +37,13 @@ GitLab.com generates an application ID and secret key for you to use. configuration. 1. On your GitLab server, open the configuration file. - For Omnibus package: + For Linux package installations: ```shell sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab @@ -56,7 +56,7 @@ GitLab.com generates an application ID and secret key for you to use. account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration: - For Omnibus installations authenticating against **GitLab.com**: + For Linux package installations authenticating against **GitLab.com**: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -70,7 +70,7 @@ GitLab.com generates an application ID and secret key for you to use. ] ``` - Or, for Omnibus installations authenticating against a different GitLab instance: + Or, for Linux package installations authenticating against a different GitLab instance: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -85,7 +85,7 @@ GitLab.com generates an application ID and secret key for you to use. ] ``` - For installations from source authenticating against **GitLab.com**: + For self-compiled installations authenticating against **GitLab.com**: ```yaml - { name: 'gitlab', @@ -94,7 +94,7 @@ GitLab.com generates an application ID and secret key for you to use. app_secret: 'YOUR_APP_SECRET', ``` - Or, for installations from source to authenticate against a different GitLab instance: + Or, for self-compiled installations to authenticate against a different GitLab instance: ```yaml - { name: 'gitlab', @@ -113,7 +113,7 @@ GitLab.com generates an application ID and secret key for you to use. 1. Save the configuration file. 1. Implement these changes by using the appropriate method: - For Linux package installations, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). - - For self-compiled installations, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). + - For self-compiled installations, [restart GitLab](../administration/restart_gitlab.md#self-compiled-installations). On the sign-in page, there should now be a GitLab.com icon following the regular sign-in form. Select the icon to begin the authentication process. diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index f43f4cb4f40..9b431846f2b 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -5,7 +5,7 @@ group: IDE 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" --- -# Gitpod **(FREE)** +# Gitpod **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228893) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/258206) in GitLab 13.8 diff --git a/doc/integration/glab/index.md b/doc/integration/glab/index.md index aae04c36210..29cec231d51 100644 --- a/doc/integration/glab/index.md +++ b/doc/integration/glab/index.md @@ -1,108 +1,11 @@ --- -stage: Create -group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: '../../editor_extensions/gitlab_cli/index.md' +remove_date: '2023-10-31' --- -# GitLab CLI - `glab` +This document was moved to [another location](../../editor_extensions/gitlab_cli/index.md). -GLab is an open source GitLab CLI tool. It brings GitLab to your terminal: -next to where you are already working with Git and your code, without -switching between windows and browser tabs. - -- Work with issues. -- Work with merge requests. -- Watch running pipelines directly from your CLI. - - - -The GitLab CLI uses commands structured like `glab <command> <subcommand> [flags]` -to perform many of the actions you usually do from the GitLab user interface: - -```shell -# Sign in -glab auth login --stdin < token.txt - -# View a list of issues -glab issue list - -# Create merge request for issue 123 -glab mr for 123 - -# Check out the branch for merge request 243 -glab mr checkout 243 - -# Watch the pipeline in progress -glab pipeline ci view - -# View, approve, and merge the merge request -glab mr view -glab mr approve -glab mr merge -``` - -## Core commands - -- [`glab alias`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/alias) -- [`glab api`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/api) -- [`glab auth`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/auth) -- [`glab check-update`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/check-update) -- [`glab ci`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/ci) -- [`glab completion`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/completion) -- [`glab config`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/config) -- [`glab incident`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/incident) -- [`glab issue`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/issue) -- [`glab label`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/label) -- [`glab mr`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/mr) -- [`glab release`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/release) -- [`glab repo`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/repo) -- [`glab schedule`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/schedule) -- [`glab snippet`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/snippet) -- [`glab ssh-key`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/ssh-key) -- [`glab user`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/user) -- [`glab variable`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/variable) - -## Install the CLI - -Installation instructions are available in the GLab -[`README`](https://gitlab.com/gitlab-org/cli/#installation). - -## Authenticate with GitLab - -To authenticate with your GitLab account, run `glab auth login`. -`glab` respects tokens set using `GITLAB_TOKEN`. - -## Report issues - -Open an issue in the [`gitlab-org/cli` repository](https://gitlab.com/gitlab-org/cli/-/issues/new) -to send us feedback. - -## Related topics - -- [Install the CLI](https://gitlab.com/gitlab-org/cli/-/blob/main/README.md#installation) -- [Documentation](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source) -- Extension source code in the [`cli`](https://gitlab.com/gitlab-org/cli/) project - -## Troubleshooting - -### `glab completion` commands fail when using the 1Password shell plugin - -The [1Password shell plugin](https://developer.1password.com/docs/cli/shell-plugins/gitlab/) -adds the alias `glab='op plugin run -- glab'`, which can interfere with the `glab completion` -command. If your `glab completion` commands fail, configure your shell to prevent expanding aliases -before performing completions: - -- For Zsh, edit your `~/.zshrc` file and add this line: - - ```plaintext - setopt completealiases - ``` - -- For Bash, edit your `~/.bashrc` file and add this line: - - ```plaintext - complete -F _functionname glab - ``` - -For more information, see [issue 122](https://github.com/1Password/shell-plugins/issues/122) -for the 1Password shell plugin. +<!-- This redirect file can be deleted after <2023-10-31>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 389d0aeb3f3..68db7d37b93 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Gmail actions **(FREE)** +# Gmail actions **(FREE ALL)** GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview). When you configure this integration, emails that require an action are marked in Gmail. diff --git a/doc/integration/google.md b/doc/integration/google.md index 211c86b557a..5bba50c940a 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -4,7 +4,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 --- -# Google OAuth 2.0 OmniAuth Provider **(FREE SELF)** +# Use Google OAuth 2.0 as an OAuth 2.0 authentication provider **(FREE SELF)** To enable the Google OAuth 2.0 OmniAuth provider you must register your application with Google. Google generates a client ID and secret key for you to use. @@ -63,13 +63,13 @@ To see your new project in the list, refresh the page. 1. Open the configuration file. - For Omnibus GitLab: + For Linux package installations: ```shell sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab @@ -79,9 +79,9 @@ To see your new project in the list, refresh the page. 1. Configure the [common settings](omniauth.md#configure-common-settings) to add `google_oauth2` as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account. -1. Add the provider configuration: +1. Add the provider configuration. - For Omnibus GitLab: + For Linux package installations: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -95,7 +95,7 @@ To see your new project in the list, refresh the page. ] ``` - For installations from source: + For self-compiled installations: ```yaml - { name: 'google_oauth2', @@ -110,13 +110,13 @@ To see your new project in the list, refresh the page. 1. Make sure that you configure GitLab to use a fully-qualified domain name, as Google doesn't accept raw IP addresses. - For Omnibus packages: + For Linux package installations: ```ruby external_url 'https://gitlab.example.com' ``` - For installations from source: + For self-compiled installations: ```yaml gitlab: @@ -126,7 +126,7 @@ To see your new project in the list, refresh the page. 1. Save the configuration file. 1. For the changes to take effect: - If you installed using the Linux package, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). - - If you self-compiled your installation, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). + - If you self-compiled your installation, [restart GitLab](../administration/restart_gitlab.md#self-compiled-installations). On the sign in page there should now be a Google icon below the regular sign in form. Select the icon to begin the authentication process. Google asks the diff --git a/doc/integration/index.md b/doc/integration/index.md index 866c68e6d25..a8aabeefc76 100644 --- a/doc/integration/index.md +++ b/doc/integration/index.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Integrate with GitLab **(FREE)** +# Integrate with GitLab **(FREE ALL)** You can integrate GitLab with external services for enhanced functionality. diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 760488b895f..736f5bc080c 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Jenkins **(FREE)** +# Jenkins **(FREE ALL)** > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/246756) to GitLab Free in 13.7. diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index 9660e091798..8ef7b7bc442 100644 --- a/doc/integration/jira/configure.md +++ b/doc/integration/jira/configure.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Jira issue integration **(FREE)** +# Jira issue integration **(FREE ALL)** The Jira issue integration connects one or more GitLab projects to a Jira instance. You can host the Jira instance yourself or in [Jira Cloud](https://www.atlassian.com/migration/assess/why-cloud). The supported Jira versions are `6.x`, `7.x`, `8.x`, and `9.x`. @@ -29,7 +29,7 @@ To configure your project settings in GitLab: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Jira**. -1. In **Enable integration**, select the **Active** checkbox. +1. Under **Enable integration**, select the **Active** checkbox. 1. Provide connection details: - **Web URL**: Base URL for the Jira instance web interface you're linking to this GitLab project (for example, `https://jira.example.com`). diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index 005069990c4..985f67fdf98 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -4,56 +4,88 @@ group: Import and Integrate 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 --- -# GitLab for Jira Cloud app **(FREE)** +# GitLab for Jira Cloud app **(FREE ALL)** With the [GitLab for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?tab=overview&hosting=cloud) app, you can connect GitLab and Jira Cloud to sync development information in real time. You can view this information in the [Jira development panel](development_panel.md). You can use the GitLab for Jira Cloud app to link top-level groups or subgroups. It's not possible to directly link projects or personal namespaces. +To set up the GitLab for Jira Cloud app: + - **For GitLab.com**: - [Install the GitLab for Jira Cloud app](#install-the-gitlab-for-jira-cloud-app). - **For self-managed GitLab**, do one of the following: - [Connect the GitLab for Jira Cloud app for self-managed instances](#connect-the-gitlab-for-jira-cloud-app-for-self-managed-instances) (GitLab 15.7 and later). - [Install the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually). -If you use Jira Data Center or Jira Server, use the [Jira DVCS connector](dvcs/index.md) instead. +If you use Jira Data Center or Jira Server, use the [Jira DVCS connector](dvcs/index.md) developed and maintained by Atlassian. -## Install the GitLab for Jira Cloud app **(FREE SAAS)** +## GitLab data synced to Jira + +After you link a group, the following GitLab data is synced to Jira for all projects in that group when you [mention a Jira issue ID](development_panel.md#information-displayed-in-the-development-panel): + +- Existing project data (before you linked the group): + - The last 400 merge requests + - The last 400 branches and the last commit to each of those branches (GitLab 15.11 and later) +- New project data (after you linked the group): + - Merge requests + - Branches + - Commits + - Builds + - Deployments + - Feature flags -> Link groups feature [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/331432) from Add namespace in GitLab 16.1. +## Install the GitLab for Jira Cloud app **(FREE SAAS)** Prerequisites: -- You must have at least the Maintainer role for the GitLab group. -- You must have administrator access to the Jira instance. +- You must have [site administrator](https://support.atlassian.com/user-management/docs/give-users-admin-permissions/#Make-someone-a-site-admin) access to the Jira instance. - Your network must allow inbound and outbound connections between GitLab and Jira. To install the GitLab for Jira Cloud app: -1. In Jira, select **Jira Settings > Apps > Find new apps**, and search for GitLab. -1. Select **GitLab for Jira Cloud**, and select **Get it now**. +1. In Jira, on the top bar, select **Apps > Explore more apps** and search for `GitLab for Jira Cloud`. +1. Select **GitLab for Jira Cloud**, then select **Get it now**. - Alternatively, [get the app directly from the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?tab=overview&hosting=cloud). +Alternatively, [get the app directly from the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?tab=overview&hosting=cloud). -1. To go to the configurations page, select **Get started**. - You can always access this page in **Jira Settings > Apps > Manage apps**. -1. For a list of groups to link, select **Link groups**. -1. To link to a group, select **Link**. +You can now [configure the GitLab for Jira Cloud app](#configure-the-gitlab-for-jira-cloud-app). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Configure the GitLab for Jira Cloud app from the Atlassian Marketplace](https://youtu.be/SwR-g1s1zTo). -After you add a group, the following data is synced to Jira for all projects in that group: +## Configure the GitLab for Jira Cloud app **(FREE SAAS)** -- New and existing merge requests. -- New branches and commits. -- Existing branches and commits (GitLab 15.11 and later). You must delete and add any namespaces that were added to the GitLab for Jira Cloud app in GitLab 15.10 and earlier. +> **Add namespace** [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/331432) to **Link groups** in GitLab 16.1. + +Prerequisites: + +- You must have at least the Maintainer role for the GitLab group. +- You must have [site administrator](https://support.atlassian.com/user-management/docs/give-users-admin-permissions/#Make-someone-a-site-admin) access to the Jira instance. + +You can sync data from GitLab to Jira by linking the GitLab for Jira Cloud app to one or more GitLab groups. +To configure the GitLab for Jira Cloud app: + +1. In Jira, on the top bar, select **Apps > Manage your apps**. +1. Expand **GitLab for Jira**. +1. Select **Get started**. +1. Optional. Select **Change GitLab version** to set the GitLab instance to use with Jira. + - Select **GitLab.com (SaaS)** or **GitLab (self-managed)**, then select **Save**. + - For **GitLab (self-managed)**, you must enter your GitLab instance URL. +1. Select **Sign into GitLab**. +1. For a list of groups you can link to, select **Link groups**. +1. To link to a group, select **Link**. + +After you link to a GitLab group, data is synced to Jira for all projects in that group. +The initial data sync happens in batches of 20 projects per minute. +For groups with many projects, the data sync for some projects is delayed. ## Update the GitLab for Jira Cloud app Most updates to the app are automatic. For more information, see the [Atlassian documentation](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/). + If the app requires additional permissions, [you must manually approve the update in Jira](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/#changes-that-require-manual-customer-approval). ## Set up OAuth authentication for self-managed instances **(FREE SELF)** @@ -339,3 +371,28 @@ due to a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/388943). To # If both flags are enabled, disable the `jira_connect_oauth_self_managed` flag. Feature.disable(:jira_connect_oauth_self_managed) ``` + +### `Failed to link group` for self-managed instances + +After you connect the GitLab for Jira Cloud app for self-managed instances, you might get one of these errors: + +```plaintext +Failed to load Jira Connect Application ID. Please try again. +``` + +```plaintext +Failed to link group. Please try again. +``` + +When you check the browser console, you might see the following message: + +```plaintext +Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://gitlab.example.com/-/jira_connect/oauth_application_id. (Reason: CORS header 'Access-Control-Allow-Origin' missing). Status code: 403. +``` + +A `403` status code is returned if: + +- The user information cannot be fetched from Jira. +- The authenticated Jira user does not have [site administrator](https://support.atlassian.com/user-management/docs/give-users-admin-permissions/#Make-someone-a-site-admin) access. + +To resolve this issue, ensure the authenticated user is a Jira site administrator and try again. diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index c444ffe8a3b..8e0bb2bdf9b 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -4,13 +4,13 @@ group: Import and Integrate 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 --- -# Jira development panel **(FREE)** +# Jira development panel **(FREE ALL)** You can use the Jira development panel to view GitLab activity for a Jira issue directly in Jira. To set up the Jira development panel: -- **For Jira Cloud**, use the [GitLab for Jira Cloud app](connect-app.md) developed by GitLab. -- **For Jira Data Center or Jira Server**, use the [Jira DVCS connector](dvcs/index.md) developed by Atlassian. +- **For Jira Cloud**, use the [GitLab for Jira Cloud app](connect-app.md) developed and maintained by GitLab. +- **For Jira Data Center or Jira Server**, use the [Jira DVCS connector](dvcs/index.md) developed and maintained by Atlassian. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Jira development panel integration](https://www.youtube.com/watch?v=VjVTOmMl85M). @@ -25,7 +25,7 @@ This table shows the features available with the Jira DVCS connector and the Git | Sync merge requests | **{check-circle}** Yes | **{check-circle}** Yes | | Sync branches | **{check-circle}** Yes | **{check-circle}** Yes | | Sync commits | **{check-circle}** Yes | **{check-circle}** Yes | -| Sync existing data | **{check-circle}** Yes | **{check-circle}** Yes | +| Sync existing data | **{check-circle}** Yes | **{check-circle}** Yes (partial) <sup>1</sup>| | Sync builds | **{dotted-circle}** No | **{check-circle}** Yes | | Sync deployments | **{dotted-circle}** No | **{check-circle}** Yes | | Sync feature flags | **{dotted-circle}** No | **{check-circle}** Yes | @@ -34,6 +34,8 @@ This table shows the features available with the Jira DVCS connector and the Git | Create merge request from branch | **{check-circle}** Yes | **{check-circle}** Yes | | Create branch from Jira issue | **{dotted-circle}** No | **{check-circle}** Yes ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66032) in GitLab 14.2) | +1. See [GitLab data synced to Jira](connect-app.md#gitlab-data-synced-to-jira). + ## Connected projects in GitLab The Jira development panel connects a Jira instance with all its projects to the following: @@ -49,11 +51,16 @@ depends on where you mention the Jira issue ID in GitLab. | GitLab: where you mention the Jira issue ID | Jira development panel: what information is displayed | |------------------------------------------------|-------------------------------------------------------| -| Merge request title or description | Link to the merge request<br>Link to the deployment<br>Link to the pipeline by title only and by description ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390888) in GitLab 15.10)<br>Link to the branch ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354373) in GitLab 15.11) | +| Merge request title or description | Link to the merge request<br>Link to the deployment<br>Link to the pipeline through merge request title<br>Link to the pipeline through merge request description <sup>1</sup><br>Link to the branch <sup>2</sup> | | Branch name | Link to the branch<br>Link to the deployment | -| Commit message | Link to the commit<br>Link to the deployment from up to 5,000 commits after the last successful deployment to the environment ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300031) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `jira_deployment_issue_keys`. Enabled by default) | +| Commit message | Link to the commit<br>Link to the deployment from up to 5,000 commits after the last successful deployment to the environment <sup>3</sup> <sup>4</sup> | | [Jira Smart Commit](#jira-smart-commits) | Custom comment, logged time, or workflow transition | +1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390888) in GitLab 15.10. +1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354373) in GitLab 15.11. +1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300031) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `jira_deployment_issue_keys`. Enabled by default. +1. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415025) in GitLab 16.3. Feature flag `jira_deployment_issue_keys` removed. + ## Jira Smart Commits Prerequisites: diff --git a/doc/integration/jira/dvcs/index.md b/doc/integration/jira/dvcs/index.md index 3ebbc9a921d..8e624d81b54 100644 --- a/doc/integration/jira/dvcs/index.md +++ b/doc/integration/jira/dvcs/index.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Jira DVCS connector **(FREE)** +# Jira DVCS connector **(FREE ALL)** WARNING: The Jira DVCS connector for Jira Cloud was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/362168) in GitLab 15.1 @@ -13,6 +13,8 @@ The Jira DVCS connector was also deprecated and removed for Jira 8.13 and earlie Use the Jira DVCS (distributed version control system) connector if you self-host your Jira instance with Jira Data Center or Jira Server and want to use the [Jira development panel](../development_panel.md). +The Jira DVCS connector is developed and maintained by Atlassian. For more information, see the +[Atlassian documentation](https://confluence.atlassian.com/adminjiraserver/integrating-with-development-tools-using-dvcs-1047552689.html). If you're on Jira Cloud, migrate to the GitLab for Jira Cloud app. For more information, see [Install the GitLab for Jira Cloud app](../connect-app.md#install-the-gitlab-for-jira-cloud-app). diff --git a/doc/integration/jira/dvcs/troubleshooting.md b/doc/integration/jira/dvcs/troubleshooting.md index 31038526d63..801bdab4139 100644 --- a/doc/integration/jira/dvcs/troubleshooting.md +++ b/doc/integration/jira/dvcs/troubleshooting.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Troubleshooting Jira DVCS connector **(FREE)** +# Troubleshooting Jira DVCS connector **(FREE ALL)** Refer to the items in this section if you're having problems with your Jira DVCS connector. diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md index dbda2e91dee..c7a60ec2ff8 100644 --- a/doc/integration/jira/index.md +++ b/doc/integration/jira/index.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Jira **(FREE)** +# Jira **(FREE ALL)** If your organization uses [Jira](https://www.atlassian.com/software/jira), you can [migrate your issues from Jira to GitLab](../../user/project/import/jira.md). @@ -28,8 +28,8 @@ You can use the [Jira issue integration](configure.md) developed by GitLab with You can use the [Jira development panel](development_panel.md) to [view GitLab activity for an issue](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) including related branches, commits, and merge requests. To configure the Jira development panel: -- **For Jira Cloud**, use the [GitLab for Jira Cloud app](connect-app.md) developed by GitLab. -- **For Jira Data Center or Jira Server**, use the [Jira DVCS connector](dvcs/index.md) developed by Atlassian. +- **For Jira Cloud**, use the [GitLab for Jira Cloud app](connect-app.md) developed and maintained by GitLab. +- **For Jira Data Center or Jira Server**, use the [Jira DVCS connector](dvcs/index.md) developed and maintained by Atlassian. ## Jira integration capabilities diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md index c1b61e2e587..06d64d19db5 100644 --- a/doc/integration/jira/issues.md +++ b/doc/integration/jira/issues.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Jira issue management **(FREE)** +# Jira issue management **(FREE ALL)** You can [manage Jira issues directly in GitLab](configure.md). You can then refer to Jira issues by ID in GitLab commits and merge requests. @@ -47,7 +47,7 @@ create only a single cross-reference back to that merge request in Jira. You can [disable comments](#disable-comments-on-jira-issues) on issues. -### Require associated Jira issue for merge requests to be merged **(ULTIMATE)** +### Require associated Jira issue for merge requests to be merged **(ULTIMATE ALL)** With this integration, you can prevent merge requests from being merged if they do not refer to a Jira issue. To enable this feature: @@ -129,7 +129,7 @@ Consider this example: - GitLab adds a formatted comment to Jira, linking back to the commit that resolved the issue. You can [disable comments](#disable-comments-on-jira-issues). -## View Jira issues **(PREMIUM)** +## View Jira issues **(PREMIUM ALL)** You can view and search issues from a selected Jira project directly in GitLab, provided your GitLab administrator [has configured the integration](configure.md#configure-the-integration). @@ -152,7 +152,7 @@ Issues are grouped into tabs based on their - **Closed** tab: All issues with a Jira status categorized as Done. - **All** tab: All issues of any status. -### Search and filter the issue list **(PREMIUM)** +### Search and filter the issue list **(PREMIUM ALL)** To refine the list of issues, use the search bar to search for any text contained in an issue summary (title) or description. Use any combination diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md deleted file mode 100644 index 83321df0420..00000000000 --- a/doc/integration/jira/jira_cloud_configuration.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'configure.md#create-a-jira-cloud-api-token' -remove_date: '2023-07-07' ---- - -This document was moved to [another location](configure.md#create-a-jira-cloud-api-token). - -<!-- This redirect file can be deleted after <2023-07-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index 373fe137046..7788714b966 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Tutorial: Create Jira credentials **(FREE)** +# Tutorial: Create Jira credentials **(FREE ALL)** This tutorial shows you how to create Jira credentials. You can use your new Jira credentials to configure the [Jira issue integration](configure.md) in GitLab for Jira Data Center or Jira Server. @@ -17,7 +17,7 @@ To create Jira credentials, here's what we're going to do: Prerequisite: -- You must have administrator access to the Jira instance. +- You must have [site administrator](https://support.atlassian.com/user-management/docs/give-users-admin-permissions/#Make-someone-a-site-admin) access to the Jira instance. ## Create a Jira user diff --git a/doc/integration/jira/troubleshooting.md b/doc/integration/jira/troubleshooting.md index 49b5dfba566..70c6a306299 100644 --- a/doc/integration/jira/troubleshooting.md +++ b/doc/integration/jira/troubleshooting.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Troubleshooting Jira **(FREE)** +# Troubleshooting Jira **(FREE ALL)** This page contains a list of common issues you might encounter when working with Jira integrations. diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 5271f60b5dd..c7dbc5caf35 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -4,7 +4,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" --- -# Kerberos integration **(PREMIUM SELF)** +# Use Kerberos as an OAuth 2.0 authentication provider **(PREMIUM SELF)** GitLab can integrate with [Kerberos](https://web.mit.edu/kerberos/) as an authentication mechanism. @@ -41,10 +41,10 @@ sudo chmod 0600 /etc/http.keytab ### Configure GitLab -#### Installations from source +#### Self-compiled installations NOTE: -For source installations, make sure the `kerberos` gem group +For self-compiled installations, make sure the `kerberos` gem group [has been installed](../install/installation.md#install-gems). 1. Edit the `kerberos` section of [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) to enable Kerberos ticket-based @@ -66,9 +66,9 @@ For source installations, make sure the `kerberos` gem group keytab: /etc/http.keytab ``` -1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect. +1. [Restart GitLab](../administration/restart_gitlab.md#self-compiled-installations) for the changes to take effect. -#### Omnibus package installations +#### Linux package installations 1. Edit `/etc/gitlab/gitlab.rb`: @@ -187,7 +187,9 @@ match the domain from the user's LDAP DN. The configuration value must specify all domains that users may be expected to have. Any other domains are ignored and an LDAP identity is not linked. -**For Omnibus installations** +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb`: @@ -198,9 +200,7 @@ ignored and an LDAP identity is not linked. 1. Save the file and [reconfigure](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) GitLab for the changes to take effect. ---- - -**For installations from source** +:::TabTitle Self-compiled (source) 1. Edit `config/gitlab.yml`: @@ -209,9 +209,11 @@ ignored and an LDAP identity is not linked. simple_ldap_linking_allowed_realms: ['example.com','kerberos.example.com'] ``` -1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source) +1. Save the file and [restart](../administration/restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. +::EndTabs + ## HTTP Git access A linked Kerberos account enables you to `git pull` and `git push` using your @@ -247,7 +249,21 @@ NOTE: username and password is passed interactively or through a credentials manager. It fails to fall back when the username and password is passed as part of the URL instead. For example, this can happen in GitLab CI/CD jobs that [authenticate with the CI/CD job token](../ci/jobs/ci_job_token.md). -**For source installations with HTTPS** +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['kerberos_use_dedicated_port'] = true + gitlab_rails['kerberos_port'] = 8443 + gitlab_rails['kerberos_https'] = true + ``` + +1. [Reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. + +:::TabTitle Self-compiled (source) with HTTPS 1. Edit the NGINX configuration file for GitLab (for example, `/etc/nginx/sites-available/gitlab-ssl`) and configure NGINX to @@ -274,19 +290,9 @@ this can happen in GitLab CI/CD jobs that [authenticate with the CI/CD job token https: true ``` -1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source) and NGINX for the changes to take effect. - -**For Omnibus package installations** - -1. Edit `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_rails['kerberos_use_dedicated_port'] = true - gitlab_rails['kerberos_port'] = 8443 - gitlab_rails['kerberos_https'] = true - ``` +1. [Restart GitLab](../administration/restart_gitlab.md#self-compiled-installations) and NGINX for the changes to take effect. -1. [Reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. +::EndTabs After this change, Git remote URLs have to be updated to `https://gitlab.example.com:8443/mygroup/myproject.git` to use @@ -308,7 +314,22 @@ If not, then add the settings [described above](#configuration). To disable password-based Kerberos sign-ins, remove the OmniAuth provider `kerberos` from your `gitlab.yml`/`gitlab.rb` file. -**For installations from source** +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb` and remove the `{ "name" => "kerberos" }` line + under `gitlab_rails['omniauth_providers']`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { "name" => "kerberos" } # <-- remove this entry + ] + ``` + +1. [Reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. + +:::TabTitle Self-compiled (source) 1. Edit [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) and remove the `- { name: 'kerberos' }` line under OmniAuth providers: @@ -321,20 +342,9 @@ To disable password-based Kerberos sign-ins, remove the OmniAuth provider - { name: 'kerberos' } # <-- remove this line ``` -1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect. - -**For Omnibus installations** - -1. Edit `/etc/gitlab/gitlab.rb` and remove the `{ "name" => "kerberos" }` line - under `gitlab_rails['omniauth_providers']`: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { "name" => "kerberos" } # <-- remove this entry - ] - ``` +1. [Restart GitLab](../administration/restart_gitlab.md#self-compiled-installations) for the changes to take effect. -1. [Reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. +::EndTabs NOTE: Removing the `kerberos` OmniAuth provider can also resolve a rare diff --git a/doc/integration/mattermost/index.md b/doc/integration/mattermost/index.md index 7ca4ed8a0e8..fea25a398ba 100644 --- a/doc/integration/mattermost/index.md +++ b/doc/integration/mattermost/index.md @@ -6,11 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Mattermost -NOTE: -This document applies to GitLab 11.0 and later. - You can run a [GitLab Mattermost](https://gitlab.com/gitlab-org/gitlab-mattermost) -service on your GitLab server. Mattermost is not part of the single application that GitLab is. There is a good integration between [Mattermost and GitLab](https://mattermost.com/solutions/mattermost-gitlab/), and our Linux package allows you to easily install it. But it is a separate application from a separate company. +service on your GitLab server. Mattermost is not part of the single application that GitLab is. There is a good integration between [Mattermost and GitLab](https://mattermost.com/solutions/mattermost-gitlab/), and our Linux package allows you to install it. **However, Mattermost is a separate application from a separate company.** GitLab Support cannot help you with Mattermost-specific questions beyond the integration with GitLab. If you need help with Mattermost itself, see the [community support resources](#community-support-resources). ## Prerequisites @@ -254,13 +251,13 @@ For local connections, the `mmctl` binary and Mattermost must be run from the sa sudo gitlab-ctl restart mattermost ``` -You can then use `/opt/gitlab/embedded/bin/mmctl --local` to run `mmctl` commands +You can then use `sudo /opt/gitlab/embedded/bin/mmctl --local` to run `mmctl` commands on your Mattermost instance. For example, to show the list of users: ```shell -$ /opt/gitlab/embedded/bin/mmctl --local user list +$ sudo /opt/gitlab/embedded/bin/mmctl --local user list 13dzo5bmg7fu8rdox347hbfxde: appsbot (appsbot@localhost) tbnkwjdug3dejcoddboo4yuomr: boards (boards@localhost) @@ -272,7 +269,7 @@ There are 4 users on local instance ### Use `mmctl` through a remote connection For remote connections or local connections where the socket cannot be used, -create a non SSO user and give that user administrator privileges. Those credentials +create a non-SSO user and give that user administrator privileges. Those credentials can then be used to authenticate `mmctl`: ```shell @@ -311,57 +308,52 @@ This setting can also be configured in `/var/opt/gitlab/mattermost/config.json`. ## Upgrading GitLab Mattermost -Below is a list of Mattermost versions for GitLab 11.10 and later: - -| GitLab Version | Mattermost Version | -| :------------ |:----------------| -| 11.11 | 5.10 | -| 12.0 | 5.11 | -| 12.1 | 5.12 | -| 12.2 | 5.13 | -| 12.3 | 5.14 | -| 12.4 | 5.15 | -| 12.5 | 5.16 | -| 12.6 | 5.17 | -| 12.7 | 5.17 | -| 12.8 | 5.19 | -| 12.9 | 5.20 | -| 12.10 | 5.21 | -| 13.0 | 5.22 | -| 13.1 | 5.23 | -| 13.2 | 5.24 | -| 13.3 | 5.25 | -| 13.4 | 5.26 | -| 13.5 | 5.27 | -| 13.6 | 5.28 | -| 13.7 | 5.29 | -| 13.8 | 5.30 | -| 13.9 | 5.31 | -| 13.10 | 5.32 | -| 13.11 | 5.33 | -| 13.12 | 5.34 | -| 14.0 | 5.35 | -| 14.1 | 5.36 | -| 14.2 | 5.37 | -| 14.3 | 5.38 | -| 14.4 | 5.39 | -| 14.5 | 5.39 | -| 14.6 | 6.1 | -| 14.7 | 6.2 | - -- GitLab 14.5 remained on Mattermost 5.39 -- GitLab 14.6 updates to Mattermost 6.1 instead of 6.0 +Below is a list of Mattermost versions for GitLab 14.0 and later: + +| GitLab version | Mattermost version | +|:---------------|:-------------------| +| 16.2 | 7.10 | +| 16.1 | 7.10 | +| 16.0 | 7.10 | +| 15.11 | 7.9 | +| 15.10 | 7.8 | +| 15.9 | 7.7 | +| 15.8 | 7.5 | +| 15.7 | 7.5 | +| 15.6 | 7.4 | +| 15.5 | 7.3 | +| 15.4 | 7.2 | +| 15.3 | 7.1 | +| 15.2 | 7.0 | +| 15.1 | 6.7 | +| 15.0 | 6.6 | +| 14.10 | 6.5 | +| 14.9 | 6.4 | +| 14.8 | 6.3 | +| 14.7 | 6.2 | +| 14.6 | 6.1 | +| 14.5 | 5.39 | +| 14.4 | 5.39 | +| 14.3 | 5.38 | +| 14.2 | 5.37 | +| 14.1 | 5.36 | +| 14.0 | 5.35 | + +- GitLab 14.5 remained on Mattermost 5.39. +- GitLab 14.6 updates to Mattermost 6.1 instead of 6.0. +- GitLab 15.8 remained on Mattermost 7.5. +- GitLab 16.1 and 16.2 remained on Mattermost 7.10. NOTE: When upgrading the Mattermost version, it is essential to check the [Important Upgrade Notes](https://docs.mattermost.com/administration/important-upgrade-notes.html) for Mattermost to address any changes or migrations that need to be performed. -Starting with GitLab 11.0, GitLab Mattermost can be upgraded through the regular Linux package update process. When upgrading previous versions of +GitLab Mattermost can be upgraded through the regular Linux package update process. When upgrading previous versions of GitLab, the update process can only be used if Mattermost configuration settings have not been changed outside of GitLab. That is, no changes to the Mattermost `config.json` file have been made - either directly or via the Mattermost **System Console**, which saves changes to `config.json`. -If you are upgrading to at least GitLab 11.0 or have only configured Mattermost using `gitlab.rb`, you can upgrade GitLab using the Linux package and then run `gitlab-ctl reconfigure` to upgrade GitLab Mattermost to the latest version. +If you have only configured Mattermost using `gitlab.rb`, you can upgrade GitLab using the Linux package and then run `gitlab-ctl reconfigure` to upgrade GitLab Mattermost to the latest version. If this is not the case, there are two options: @@ -376,10 +368,6 @@ If this is not the case, there are two options: For a complete list of upgrade notices and special considerations for older versions, see the [Mattermost documentation](https://docs.mattermost.com/administration/important-upgrade-notes.html). -## Upgrading GitLab Mattermost to 15.10 - -GitLab 15.10 ships with Mattermost 7.8. Before upgrading, [connect to the bundled PostgreSQL database](#connecting-to-the-bundled-postgresql-database) to perform the PostgreSQL maintenance described in the [Important Upgrade Notes](https://docs.mattermost.com/administration/important-upgrade-notes.html) provided by Mattermost. - ## Upgrading GitLab Mattermost to 14.6 GitLab 14.6 ships with Mattermost 6.1 including potentially long running database migrations for Mattermost 6.0. For information about upgrading and for ways to reduce the downtime caused by those migrations, read the [Important Upgrade Notes](https://docs.mattermost.com/administration/important-upgrade-notes.html) for both versions. If you need to perform any manual migrations, [connect to the bundled PostgreSQL database](#connecting-to-the-bundled-postgresql-database). @@ -387,111 +375,6 @@ GitLab 14.6 ships with Mattermost 6.1 including potentially long running databas NOTE: The Mattermost upgrade notes refer to different impacts when used with a PostgreSQL versus a MySQL database. The GitLab Mattermost included with the Linux package uses a PostgreSQL database. -## Upgrading GitLab Mattermost from versions prior to 11.0 - -With version 11.0, GitLab introduced breaking changes which affected Mattermost configuration. -In versions prior to GitLab 11.0 all -Mattermost-related settings were configurable from the `gitlab.rb` file, which -generated the Mattermost `config.json` file. However, Mattermost also -permitted configuration via its System Console. This configuration ended up in -the same `config.json` file, which resulted in changes made via the System Console being -overwritten when users ran `gitlab-ctl reconfigure`. - -To resolve this problem, `gitlab.rb` includes only the -configuration necessary for GitLab<=>Mattermost integration in 11.0. GitLab no longer -generates the `config.json` file, and instead passes limited configuration settings via environment variables. - -The settings that continue to be supported in `gitlab.rb` can be found in -[`gitlab.rb.template`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template). - -From GitLab 11.0, other Mattermost settings can be configured through the Mattermost System Console, -by editing `/var/opt/gitlab/mattermost/config.json`, or by using `mattermost['env']` in `gitlab.rb`. - -If you would like to keep configuring Mattermost using `gitlab.rb`, you can take the following actions -in preparation for GitLab 11.0: - -1. Upgrade to version 10.x which supports the new `mattermost['env']` setting. -1. Configure any settings not listed above through the `mattermost['env']` setting. Mattermost requires - environment variables to be provided in `MM_<CATEGORY>SETTINGS_<ATTRIBUTE>` format. Below is an example - of how to convert the old settings syntax to the new one. - -The following settings in `gitlab.rb`: - -```ruby -mattermost['service_maximum_login_attempts'] = 10 -mattermost['team_teammate_name_display'] = "full_name" -mattermost['sql_max_idle_conns'] = 10 -mattermost['log_file_level'] = 'INFO' -mattermost['email_batching_interval'] = 30 -mattermost['file_enable_file_attachments'] = true -mattermost['ratelimit_memory_store_size'] = 10000 -mattermost['support_terms_of_service_link'] = "/static/help/terms.html" -mattermost['privacy_show_email_address'] = true -mattermost['localization_available_locales'] = "en,es,fr,ja,pt-BR" -mattermost['webrtc_enable'] = false -``` - -Would translate to: - -```ruby -mattermost['env'] = { - 'MM_SERVICESETTINGS_MAXIMUMLOGINATTEMPTS' => '10', - 'MM_TEAMSETTINGS_TEAMMATENAMEDISPLAY' => 'full_name', - 'MM_SQLSETTINGS_MAXIDLECONNS' => '10', - 'MM_LOGSETTINGS_FILELEVEL' => 'INFO', - 'MM_EMAILSETTINGS_BATCHINGINTERVAL' => '30', - 'MM_FILESETTINGS_ENABLEFILEATTACHMENTS' => 'true', - 'MM_RATELIMITSETTINGS_MEMORYSTORESIZE' => '10000', - 'MM_SUPPORTSETTINGS_TERMSOFSERVICELINK' => '/static/help/terms.html', - 'MM_PRIVACYSETTINGS_SHOWEMAILADDRESS' => 'true', - 'MM_LOCALIZATIONSETTINGS_AVAILABLELOCALES' => 'en,es,fr,ja,pt-BR', - 'MM_WEBRTCSETTINGS_ENABLE' => 'false' - } -``` - -Refer to the [Mattermost Configuration Settings documentation](https://docs.mattermost.com/administration/config-settings.html) -for details about categories and configuration values. - -There are a few exceptions to this rule: - -1. `ServiceSettings.ListenAddress` configuration of Mattermost is configured - by `mattermost['service_address']` and `mattermost['service_port']` settings. -1. Configuration settings named in an inconsistent way are given in the - following table. Use these mappings when converting them to environment - variables. - -|`gitlab.rb` configuration|Environment variable| -|---|---| -|`mattermost['service_lets_encrypt_cert_cache_file']`|`MM_SERVICESETTINGS_LETSENCRYPTCERTIFICATECACHEFILE`| -|`mattermost['service_user_access_tokens']`|`MM_SERVICESETTINGS_ENABLEUSERACCESSTOKENS`| -|`mattermost['log_console_enable']`|`MM_LOGSETTINGS_ENABLECONSOLE`| -|`mattermost['email_enable_batching']`|`MM_EMAILSETTINGS_ENABLEEMAILBATCHING`| -|`mattermost['email_batching_buffer_size']`|`MM_EMAILSETTINGS_EMAILBATCHINGBUFFERSIZE`| -|`mattermost['email_batching_interval']`|`MM_EMAILSETTINGS_EMAILBATCHINGINTERVAL`| -|`mattermost['email_smtp_auth']`|`MM_EMAILSETTINGS_ENABLESMTPAUTH`| -|`mattermost['email_notification_content_type']`|`MM_EMAILSETTINGS_NOTIFICATIONCONTENTTYPE`| -|`mattermost['ratelimit_enable_ratelimiter']`|`MM_RATELIMITSETTINGS_ENABLE`| -|`mattermost['support_email']`|`MM_SUPPORTSETTINGS_SUPPORTEMAIL`| -|`mattermost['localization_server_locale']`|`MM_LOCALIZATIONSETTINGS_DEFAULTSERVERLOCALE`| -|`mattermost['localization_client_locale']`|`MM_LOCALIZATIONSETTINGS_DEFAULTCLIENTLOCALE`| -|`mattermost['webrtc_gateway_stun_uri']`|`MM_WEBRTCSETTINGS_STUN_URI`| -|`mattermost['webrtc_gateway_turn_uri']`|`MM_WEBRTCSETTINGS_TURN_URI`| -|`mattermost['webrtc_gateway_turn_username']`|`MM_WEBRTCSETTINGS_TURN_USERNAME`| -|`mattermost['webrtc_gateway_turn_sharedkey']`|`MM_WEBRTCSETTINGS_TURN_SHAREDKEY`| - -NOTE: -GitLab 11.0 no longer generates `config.json` file from the configuration specified -in `gitlab.rb`. Users are responsible for managing this file which can be done via the -Mattermost System Console or manually. -If a configuration setting is specified via both the `gitlab.rb` (as an environment variable) -and `config.json` files, the environment variable gets precedence. - -If you encounter any issues [visit the GitLab Mattermost troubleshooting forum](https://forum.mattermost.com/t/upgrading-to-gitlab-mattermost-in-gitlab-8-9/1735) and share any relevant portions of `mattermost.log` along with the step at which you encountered issues. - -### Upgrading GitLab Mattermost outside of GitLab - -If you choose to upgrade Mattermost outside of the Linux package automation, [follow this guide](https://docs.mattermost.com/administration/upgrade.html). - ## OAuth 2.0 sequence diagram The following image is a sequence diagram for how GitLab works as an OAuth 2.0 diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index 79238c78421..00a50489793 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -4,7 +4,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 --- -# Generic OAuth 2.0 provider **(FREE SELF)** +# Use Generic OAuth2 gem as an OAuth 2.0 authentication provider **(FREE SELF)** The [`omniauth-oauth2-generic` gem](https://gitlab.com/satorix/omniauth-oauth2-generic) allows single sign-on (SSO) between GitLab and your OAuth 2.0 provider, or any OAuth 2.0 provider compatible with this gem. diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index dffb45d30a1..fc849adc2b3 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -38,6 +38,7 @@ To create a new application for your user: 1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Applications**. +1. Select **Add new application**. 1. Enter a **Name** and **Redirect URI**. 1. Select OAuth 2 **Scopes** as defined in [Authorized Applications](#view-all-authorized-applications). 1. In the **Redirect URI**, enter the URL where users are sent after they authorize with GitLab. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 01ea6408469..30aa913ab8c 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -177,50 +177,54 @@ choosing the first that exists: You can create GitLab configuration on a per-provider basis, which is supplied to the [provider](#supported-providers) using `args`. If you set the `gitlab_username_claim` variable in `args` for a provider, you can select another claim to use for the GitLab username. The chosen claim must be unique to avoid collisions. -- **For Omnibus installations** +::Tabs - ```ruby - gitlab_rails['omniauth_providers'] = [ - - # The generic pattern for configuring a provider with name PROVIDER_NAME - - gitlab_rails['omniauth_providers'] = { - name: "PROVIDER_NAME" - ... - args: { gitlab_username_claim: 'sub' } # For users signing in with the provider you configure, the GitLab username will be set to the "sub" received from the provider - }, - - # Here are examples using GitHub and Kerberos - - gitlab_rails['omniauth_providers'] = { - name: "github" - ... - args: { gitlab_username_claim: 'name' } # For users signing in with GitHub, the GitLab username will be set to the "name" received from GitHub - }, - { - name: "kerberos" - ... - args: { gitlab_username_claim: 'uid' } # For users signing in with Kerberos, the GitLab username will be set to the "uid" received from Kerberos - }, - ] - ``` +:::TabTitle Linux package (Omnibus) + +```ruby +gitlab_rails['omniauth_providers'] = [ -- **For installations from source** + # The generic pattern for configuring a provider with name PROVIDER_NAME - ```yaml - - { name: 'PROVIDER_NAME', + gitlab_rails['omniauth_providers'] = { + name: "PROVIDER_NAME" ... - args: { gitlab_username_claim: 'sub' } - } - - { name: 'github', + args: { gitlab_username_claim: 'sub' } # For users signing in with the provider you configure, the GitLab username will be set to the "sub" received from the provider + }, + + # Here are examples using GitHub and Kerberos + + gitlab_rails['omniauth_providers'] = { + name: "github" ... - args: { gitlab_username_claim: 'name' } - } - - { name: 'kerberos', + args: { gitlab_username_claim: 'name' } # For users signing in with GitHub, the GitLab username will be set to the "name" received from GitHub + }, + { + name: "kerberos" ... - args: { gitlab_username_claim: 'uid' } - } - ``` + args: { gitlab_username_claim: 'uid' } # For users signing in with Kerberos, the GitLab username will be set to the "uid" received from Kerberos + }, +] +``` + +:::TabTitle Self-compiled (source) + +```yaml +- { name: 'PROVIDER_NAME', + ... + args: { gitlab_username_claim: 'sub' } +} +- { name: 'github', + ... + args: { gitlab_username_claim: 'name' } +} +- { name: 'kerberos', + ... + args: { gitlab_username_claim: 'uid' } +} +``` + +::EndTabs ### Passwords for users created via OmniAuth @@ -265,20 +269,24 @@ OmniAuth is enabled by default. However, OmniAuth only works if providers are configured and [enabled](#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources). If OmniAuth providers are causing problems even when individually disabled, you -can disable the entire OmniAuth subsystem by modifying the configuration file: +can disable the entire OmniAuth subsystem by modifying the configuration file. -- **For Omnibus installations** +::Tabs - ```ruby - gitlab_rails['omniauth_enabled'] = false - ``` +:::TabTitle Linux package (Omnibus) -- **For installations from source** +```ruby +gitlab_rails['omniauth_enabled'] = false +``` - ```yaml - omniauth: - enabled: false - ``` +:::TabTitle Self-compiled (source) + +```yaml +omniauth: + enabled: false +``` + +::EndTabs ## Link existing users to OmniAuth users @@ -289,18 +297,22 @@ You can automatically link OmniAuth users with existing GitLab users if their em The following example enables automatic linking for the OpenID Connect provider and the Twitter OAuth provider. -- **For Omnibus installations** +::Tabs - ```ruby - gitlab_rails['omniauth_auto_link_user'] = ["openid_connect", "twitter"] - ``` +:::TabTitle Linux package (Omnibus) -- **For installations from source** +```ruby +gitlab_rails['omniauth_auto_link_user'] = ["openid_connect", "twitter"] +``` - ```yaml - omniauth: - auto_link_user: ["openid_connect", "twitter"] - ``` +:::TabTitle Self-compiled (source) + +```yaml +omniauth: + auto_link_user: ["openid_connect", "twitter"] +``` + +::EndTabs This method of enabling automatic linking works for all providers [except SAML](https://gitlab.com/gitlab-org/gitlab/-/issues/338293). @@ -320,23 +332,27 @@ If you remove an OmniAuth provider from the external providers list, you must manually update the users that use this sign-in method so their accounts are upgraded to full internal accounts. -- **For Omnibus installations** +::Tabs - ```ruby - gitlab_rails['omniauth_external_providers'] = ['twitter', 'google_oauth2'] - ``` +:::TabTitle Linux package (Omnibus) -- **For installations from source** +```ruby +gitlab_rails['omniauth_external_providers'] = ['twitter', 'google_oauth2'] +``` - ```yaml - omniauth: - external_providers: ['twitter', 'google_oauth2'] - ``` +:::TabTitle Self-compiled (source) + +```yaml +omniauth: + external_providers: ['twitter', 'google_oauth2'] +``` + +::EndTabs ## Use a custom OmniAuth provider NOTE: -The following information only applies to installations from source. +The following information only applies to self-compiled installations. If you have to integrate with an authentication solution other than the [OmniAuth](https://github.com/omniauth/omniauth) providers included with GitLab, you can use a custom OmniAuth provider. @@ -390,20 +406,24 @@ You can sync any combination of the following user attributes: When authenticating using LDAP, the user's name and email are always synced. -- **For Omnibus installations** +::Tabs - ```ruby - gitlab_rails['omniauth_sync_profile_from_provider'] = ['twitter', 'google_oauth2'] - gitlab_rails['omniauth_sync_profile_attributes'] = ['name', 'email', 'location'] - ``` +:::TabTitle Linux package (Omnibus) -- **For installations from source** +```ruby +gitlab_rails['omniauth_sync_profile_from_provider'] = ['twitter', 'google_oauth2'] +gitlab_rails['omniauth_sync_profile_attributes'] = ['name', 'email', 'location'] +``` - ```yaml - omniauth: - sync_profile_from_provider: ['twitter', 'google_oauth2'] - sync_profile_attributes: ['email', 'location'] - ``` +:::TabTitle Self-compiled (source) + +```yaml +omniauth: + sync_profile_from_provider: ['twitter', 'google_oauth2'] + sync_profile_attributes: ['email', 'location'] +``` + +::EndTabs ## Bypass two-factor authentication @@ -424,18 +444,22 @@ This option should be configured only for providers that already have 2FA. The d This configuration doesn't apply to SAML. -- **For Omnibus package** +::Tabs - ```ruby - gitlab_rails['omniauth_allow_bypass_two_factor'] = ['twitter', 'google_oauth2'] - ``` +:::TabTitle Linux package (Omnibus) -- **For installations from source** +```ruby +gitlab_rails['omniauth_allow_bypass_two_factor'] = ['twitter', 'google_oauth2'] +``` - ```yaml - omniauth: - allow_bypass_two_factor: ['twitter', 'google_oauth2'] - ``` +:::TabTitle Self-compiled (source) + +```yaml +omniauth: + allow_bypass_two_factor: ['twitter', 'google_oauth2'] +``` + +::EndTabs ## Sign in with a provider automatically @@ -446,18 +470,22 @@ authentication. This removes the need to select the provider before signing in. For example, to enable automatic sign-in for the [Azure v2 integration](azure.md): -- **For Omnibus package** +::Tabs - ```ruby - gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_activedirectory_v2' - ``` +:::TabTitle Linux package (Omnibus) -- **For installations from source** +```ruby +gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_activedirectory_v2' +``` - ```yaml - omniauth: - auto_sign_in_with_provider: azure_activedirectory_v2 - ``` +:::TabTitle Self-compiled (source) + +```yaml +omniauth: + auto_sign_in_with_provider: azure_activedirectory_v2 +``` + +::EndTabs Keep in mind that every sign-in attempt is redirected to the OmniAuth provider, so you can't sign in using local credentials. Ensure at least diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index ff81ec49a9f..ec3c2d53495 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -4,7 +4,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 --- -# GitLab as OpenID Connect identity provider **(FREE)** +# GitLab as OpenID Connect identity provider **(FREE ALL)** This document is about using GitLab as an OpenID Connect identity provider to sign in to other services. diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 40e1c4616a5..3a90a4570e6 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -4,7 +4,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 --- -# Salesforce OmniAuth Provider **(FREE SELF)** +# Use Salesforce as an OAuth 2.0 authentication provider **(FREE SELF)** You can integrate your GitLab instance with [Salesforce](https://www.salesforce.com/) to enable users to sign in to your GitLab instance with their Salesforce account. @@ -35,13 +35,13 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create 1. On your GitLab server, open the configuration file. - For Omnibus package: + For Linux package installations: ```shell sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab @@ -52,9 +52,9 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create to add `salesforce` as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account. -1. Add the provider configuration: +1. Add the provider configuration. - For Omnibus package: + For Linux package installations: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -67,7 +67,7 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create ] ``` - For installation from source: + For self-compiled installations: ```yaml - { name: 'salesforce', @@ -86,7 +86,7 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create 1. For the changes to take effect: - If you installed using the Linux package, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). - - If you self-compiled your installation, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). + - If you self-compiled your installation, [restart GitLab](../administration/restart_gitlab.md#self-compiled-installations). On the sign in page, there should now be a Salesforce icon below the regular sign in form. Select the icon to begin the authentication process. Salesforce asks the user to sign in and authorize the GitLab application. diff --git a/doc/integration/saml.md b/doc/integration/saml.md index d31f4ff80b3..e4ad8c33aa1 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -735,10 +735,6 @@ For a full list of supported assertions, see the [OmniAuth SAML gem](https://git ## Configure users based on SAML group membership -NOTE: -SAML Group Sync is only supported for the [SAML provider named `saml`](#configure-gitlab-to-use-multiple-saml-idps). -As a result, SAML Group Sync only supports a single SAML provider. For more information, see [issue 366450](https://gitlab.com/gitlab-org/gitlab/-/issues/366450). - You can: - Require users to be members of a certain group. @@ -2979,8 +2975,11 @@ over HTTPS. These users can instead: ## Link SAML identity for an existing user -A user can manually link their SAML identity to an existing GitLab account by following the steps in -[Enable OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user). +An administrator can configure GitLab to automatically link SAML users with existing GitLab users. +For more information, see [Configure SAML support in GitLab](#configure-saml-support-in-gitlab). + +A user can manually link their SAML identity to an existing GitLab account. For more information, +see [Enable OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user). ## Configure group SAML SSO on a self-managed instance **(PREMIUM SELF)** diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index 976f5ca9774..859b5682879 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -4,14 +4,14 @@ group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Shibboleth OmniAuth Provider **(FREE)** +# Use Shibboleth as an OAuth 2.0 authentication provider **(FREE ALL)** NOTE: Use the [GitLab SAML integration](saml.md) to integrate specific Shibboleth identity providers (IdPs). For Shibboleth federation support (Discovery Service), use this document. To enable Shibboleth support in GitLab, use Apache instead of NGINX. Apache uses the `mod_shib2` module for Shibboleth authentication, and can pass attributes as headers to the OmniAuth Shibboleth provider. -You can use the bundled NGINX provided in the Omnibus GitLab package to run a Shibboleth service provider on a different instance using a reverse proxy setup. However if you are not doing this, the bundled NGINX is difficult to configure. +You can use the bundled NGINX provided in the Linux package to run a Shibboleth service provider on a different instance using a reverse proxy setup. However if you are not doing this, the bundled NGINX is difficult to configure. To enable the Shibboleth OmniAuth provider, you must: @@ -86,6 +86,6 @@ To enable Shibboleth: If some of your users appear to be authenticated by Shibboleth and Apache, but GitLab rejects their account with a URI that contains "e-mail is invalid" then your Shibboleth Identity Provider or Attribute Authority may be asserting multiple email addresses. In this instance, consider setting the `multi_values` argument to `first`. 1. For the changes to take effect: - For Linux package installations, [reconfigure](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) GitLab. - - For self-compiled installations, [restart](../administration/restart_gitlab.md#installations-from-source) GitLab. + - For self-compiled installations, [restart](../administration/restart_gitlab.md#self-compiled-installations) GitLab. On the sign in page, there should now be a **Sign in with: Shibboleth** icon below the regular sign-in form. Select the icon to begin the authentication process. You are redirected to the appropriate IdP server for your Shibboleth module configuration. If everything goes well, you are returned to GitLab and signed in. diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 4b0db1ab4b9..076b7f3937e 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, how-to --- -# Sourcegraph **(FREE)** +# Sourcegraph **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16556) in GitLab 12.5 [with a flag](../administration/feature_flags.md) named `sourcegraph`. Disabled by default. > - Enabled on GitLab.com in GitLab 12.5. diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md index 122400e8446..d855091b988 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Trello Power-Ups **(FREE)** +# Trello Power-Ups **(FREE ALL)** You can use Trello Power-Ups for GitLab to attach GitLab merge requests to Trello cards. diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index 3edb0f25938..ed83db0d4eb 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -4,7 +4,14 @@ 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 --- -# Twitter OAuth 1.0a OmniAuth Provider **(FREE SELF)** +# Twitter OAuth 1.0a OmniAuth Provider (deprecated) **(FREE SELF)** + +<!--- start_remove The following content will be removed on remove_date: '2024-05-17' --> + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-com/Product/-/issues/11417) in GitLab 16.3 and is planned for removal in 17.0. Use [another supported OmniAuth provider](omniauth.md#supported-providers) instead. This change is a breaking change. + +<!--- end_remove --> NOTE: Twitter OAuth 2.0 support is [not supported](https://gitlab.com/gitlab-org/gitlab/-/issues/366213). @@ -48,13 +55,13 @@ Twitter. Twitter generates a client ID and secret key for you to use. 1. On your GitLab server, open the configuration file. - For Omnibus package: + For Linux package installations: ```shell sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab @@ -68,7 +75,7 @@ Twitter. Twitter generates a client ID and secret key for you to use. 1. Add the provider configuration. - For Omnibus package: + For Linux package installations: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -81,7 +88,7 @@ Twitter. Twitter generates a client ID and secret key for you to use. ] ``` - For installations from source: + For self-compiled installations: ```yaml - { name: 'twitter', @@ -98,7 +105,7 @@ Twitter. Twitter generates a client ID and secret key for you to use. 1. For the changes to take effect: - For Linux package installations, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). - - For self-compiled installations, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). + - For self-compiled installations, [restart GitLab](../administration/restart_gitlab.md#self-compiled-installations). On the sign-in page, find the Twitter option below the regular sign-in form. Select the option to begin the authentication process. Twitter asks you to sign in and authorize the GitLab application. After authorization, you are returned to GitLab and signed in. diff --git a/doc/integration/vault.md b/doc/integration/vault.md index c93e3e53949..4a5dc578e99 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Vault Authentication with GitLab OpenID Connect **(FREE)** +# Use Vault as a GitLab OpenID Connect authentication provider **(FREE ALL)** [Vault](https://www.vaultproject.io/) is a secrets management application offered by HashiCorp. It allows you to store and manage sensitive information such as secret environment @@ -84,7 +84,7 @@ and scopes given to GitLab when you created the application. Run the following command in the terminal: ```shell -vault write auth/oidc/role/demo -<<EOF +vault write auth/oidc/role/demo - <<EOF { "user_claim": "sub", "allowed_redirect_uris": "<your_vault_instance_redirect_uris>", diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md index c3902a560c0..36c5ed03197 100644 --- a/doc/operations/error_tracking.md +++ b/doc/operations/error_tracking.md @@ -4,7 +4,7 @@ group: Observability 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 --- -# Error Tracking **(FREE)** +# Error Tracking **(FREE ALL)** Error Tracking allows developers to discover and view errors generated by their application. Because error information is surfaced where the code is developed, this increases efficiency and awareness. Users can choose between [GitLab Integrated error tracking](#integrated-error-tracking) and [Sentry based](#sentry-error-tracking) backends. @@ -82,7 +82,7 @@ You can also review the stack trace. ### Supported language SDKs & Sentry types -In the following table, you can see a list of all event types available through Sentry SDK, and whether they are supported by GitLab Error Tracking. +The following table lists all event types available through Sentry SDK, and whether they are supported by GitLab Error Tracking. | Language | Tested SDK client and version | Endpoint | Supported item types | | -------- | ------------------------------- | ---------- | --------------------------------- | @@ -173,7 +173,7 @@ To enable the Sentry integration: `event:write` (for resolving events). 1. In GitLab, enable and configure Error Tracking: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Monitor > Error Tracking**. + 1. Select **Settings > Monitor > Error Tracking**. 1. Under **Enable error tracking**, select the **Active** checkbox. 1. Under **Error tracking backend**, select **Sentry**. 1. Under **Sentry API URL**, enter your Sentry hostname. For example, @@ -201,9 +201,7 @@ to your runner's `config.toml` configuration file, as referenced in If you're asked for the project type while setting up Sentry, select **Go**. -If you see the following error in your GitLab Runner logs, then you should -specify the deprecated -DSN in **Sentry.io > Project Settings > Client Keys (DSN) > Show deprecated DSN**. +To rectify the following error, specify the deprecated DSN in **Sentry.io > Project Settings > Client Keys (DSN) > Show deprecated DSN**. ```plaintext ERROR: Sentry failure builds=0 error=raven: dsn missing private key diff --git a/doc/operations/feature_flags.md b/doc/operations/feature_flags.md index 142bd9d898d..21470f66750 100644 --- a/doc/operations/feature_flags.md +++ b/doc/operations/feature_flags.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Feature flags **(FREE)** +# Feature flags **(FREE ALL)** > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) from GitLab Premium to GitLab Free in 13.5. @@ -167,8 +167,7 @@ target users. See the [Ruby example](#ruby-application-example) below. Enables the feature for lists of users created [in the feature flags UI](#create-a-user-list), or with the [feature flag user list API](../api/feature_flag_user_lists.md). Similar to [User IDs](#user-ids), it uses the Unleash UsersIDs (`userWithId`) activation [strategy](https://docs.getunleash.io/reference/activation-strategies#userids). -It's not possible to *disable* a feature for members of a user list, but you can achieve the same -effect by enabling a feature for a user list that doesn't contain the excluded users. +You can't disable a specific feature for a user, but you can achieve similar results by enabling it for a user list. For example: @@ -217,12 +216,11 @@ To remove users from a user list: 1. Select **Edit** (**{pencil}**) next to the list you want to change. 1. Select **Remove** (**{remove}**) next to the ID you want to remove. -## Search for Code References **(PREMIUM)** +## Search for Code References **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300299) in GitLab 14.4. -Search your project and find any references of a feature flag in your -code so that you can clean it up when it's time to remove the feature flag. +To remove the feature flag from the code during cleanup, find any project references to it. To search for code references of a feature flag: @@ -399,7 +397,7 @@ docker run \ There is a limitation when using the Unleash Proxy where each proxy instance can request flags only for the environment named in `UNLEASH_APP_NAME`. The Proxy sends this to GitLab on behalf of the client, which means the client can't override it. -## Feature flag related issues **(PREMIUM)** +## Feature flag related issues **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36617) in GitLab 13.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/251234) in GitLab 13.5. @@ -413,8 +411,7 @@ This feature is similar to the [linked issues](../user/project/issues/related_is ## Performance factors -In general, GitLab feature flags can be used in any applications, -however, if it's a large application, it could require an additional configuration in advance. +GitLab feature flags can be used in any application. Large applications might require advance configuration. This section explains the performance factors to help your organization to identify what's needed to be done before using the feature. Read [How it works](#how-it-works) section before diving into the details. @@ -431,7 +428,7 @@ The polling rate is configurable in SDKs. Provided that all clients are requesti - Request once per minute ... 500 clients can be supported. - Request once per 15 sec ... 125 clients can be supported. -For applications looking for more scalable solution, we recommend to use [Unleash Proxy](#unleash-proxy-example). +For applications looking for more scalable solution, you should use [Unleash Proxy](#unleash-proxy-example). This proxy server sits between the server and clients. It requests to the server as a behalf of the client groups, so the number of outbound requests can be greatly reduced. @@ -452,7 +449,6 @@ Read the documentation in a SDK project for more information. Functionality-wise, there are no differences. Both SaaS and self-managed behave the same. In terms of scalability, it's up to the spec of the GitLab instance. -For example, GitLab.com runs on HA architecture so that it can handle a lot of requests concurrently, -however, a self-managed instance runs on a low spec machine can't expect the same result. +For example, GitLab.com uses HA architecture so it can handle many concurrent requests. However, self-managed instances on underpowered machines won't deliver comparable performance. See [Reference architectures](../administration/reference_architectures/index.md) for more information. diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index e701fb2e5fb..e558462cad7 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -4,7 +4,7 @@ group: Respond 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 --- -# Alerts **(FREE)** +# Alerts **(FREE ALL)** Alerts are a critical entity in your incident management workflow. They represent a notable event that might indicate a service outage or disruption. GitLab provides a list view for triage and detail view for deeper investigation of what happened. @@ -153,7 +153,7 @@ When you [close an incident](manage_incidents.md#close-an-incident) that is link GitLab [changes the alert's status](#change-an-alerts-status) to **Resolved**. You are then credited with the alert's status change. -#### As an on-call responder **(PREMIUM)** +#### As an on-call responder **(PREMIUM ALL)** On-call responders can respond to [alert pages](paging.md#escalating-an-alert) by changing the alert status. @@ -206,7 +206,7 @@ from an alert, and view it later on your **To-Do List**. To add a to-do item, on the right sidebar, select **Add a to do**. -### Trigger actions from alerts **(ULTIMATE)** +### Trigger actions from alerts **(ULTIMATE ALL)** > - Introduced in GitLab 13.1: incidents are not created automatically by default. > - Mapping common severity values from the alert payload [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50871) in GitLab 13.9. diff --git a/doc/operations/incident_management/escalation_policies.md b/doc/operations/incident_management/escalation_policies.md index 4360fe6243d..0cbbf42372e 100644 --- a/doc/operations/incident_management/escalation_policies.md +++ b/doc/operations/incident_management/escalation_policies.md @@ -4,7 +4,7 @@ group: Respond 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 --- -# Escalation Policies **(PREMIUM)** +# Escalation Policies **(PREMIUM ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4638) in GitLab 14.1. diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md index 4e2be27e424..4aae8809620 100644 --- a/doc/operations/incident_management/incidents.md +++ b/doc/operations/incident_management/incidents.md @@ -4,7 +4,7 @@ group: Respond 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 --- -# Incidents **(FREE)** +# Incidents **(FREE ALL)** An incident is a service disruption or outage that needs to be restored urgently. Incidents are critical in incident management workflows. @@ -97,7 +97,7 @@ Comments are displayed in threads, but can be displayed chronologically When you make changes to an incident, GitLab creates [system notes](../../user/project/system_notes.md) and displays them below the summary. -### Metrics **(PREMIUM)** +### Metrics **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235994) in GitLab 13.8. @@ -130,7 +130,7 @@ during an incident, and the steps that were taken for it to be resolved. Read more about [timeline events](incident_timeline_events.md) and how to enable this feature. -### Recent updates view **(PREMIUM)** +### Recent updates view **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227836) in GitLab 13.5. @@ -138,7 +138,7 @@ To see the latest updates on an incident, select **Turn recent updates view on** (**{history}**) on the comment bar. Comments display un-threaded and chronologically, newest to oldest. -### Service Level Agreement countdown timer **(PREMIUM)** +### Service Level Agreement countdown timer **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241663) in GitLab 13.5. diff --git a/doc/operations/incident_management/index.md b/doc/operations/incident_management/index.md index 9e66ab46692..1cae066ce32 100644 --- a/doc/operations/incident_management/index.md +++ b/doc/operations/incident_management/index.md @@ -4,7 +4,7 @@ group: Respond 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 --- -# Incident management **(FREE)** +# Incident management **(FREE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2877) in GitLab 13.0. diff --git a/doc/operations/incident_management/integrations.md b/doc/operations/incident_management/integrations.md index 5fe7db71fd8..5eed1921168 100644 --- a/doc/operations/incident_management/integrations.md +++ b/doc/operations/incident_management/integrations.md @@ -4,7 +4,7 @@ group: Respond 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 --- -# Integrations **(FREE)** +# Integrations **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13203) in GitLab 12.4. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) from GitLab Ultimate to GitLab Free in 12.8. @@ -42,7 +42,7 @@ receive alert payloads in JSON format. You can always are available in the **View credentials** tab after you save the integration. You must also input the URL and Authorization Key in your external service. -### HTTP Endpoints **(PREMIUM)** +### HTTP Endpoints **(PREMIUM ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4442) in GitLab 13.6. @@ -395,7 +395,7 @@ alert to confirm your integration works properly. GitLab displays an error or success message, depending on the outcome of your test. -## Automatic grouping of identical alerts **(PREMIUM)** +## Automatic grouping of identical alerts **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214557) in GitLab 13.2. @@ -420,7 +420,7 @@ field is `end_time`. With custom mappings, you can select the expected field. You can also configure the associated [incident to be closed automatically](../incident_management/manage_incidents.md#automatically-close-incidents-via-recovery-alerts) when the alert resolves. -## Link to your Opsgenie Alerts **(PREMIUM)** +## Link to your Opsgenie Alerts **(PREMIUM ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.2. diff --git a/doc/operations/incident_management/linked_resources.md b/doc/operations/incident_management/linked_resources.md index e43b08dfd78..15317f61057 100644 --- a/doc/operations/incident_management/linked_resources.md +++ b/doc/operations/incident_management/linked_resources.md @@ -4,7 +4,7 @@ group: Respond 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 --- -# Linked resources in incidents **(PREMIUM)** +# Linked resources in incidents **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230852) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `incident_resource_links_widget`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/364755) in GitLab 15.3. diff --git a/doc/operations/incident_management/manage_incidents.md b/doc/operations/incident_management/manage_incidents.md index bb9dde4b416..f88d9b51891 100644 --- a/doc/operations/incident_management/manage_incidents.md +++ b/doc/operations/incident_management/manage_incidents.md @@ -4,7 +4,7 @@ group: Respond 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 --- -# Manage incidents **(FREE)** +# Manage incidents **(FREE ALL)** This page collects instructions for all the things you can do with [incidents](incidents.md) or in relation to them. @@ -68,7 +68,7 @@ When you [close an incident](#close-an-incident) linked to an alert, GitLab [changes the alert's status](alerts.md#change-an-alerts-status) to **Resolved**. You are then credited with the alert's status change. -### Automatically, when an alert is triggered **(ULTIMATE)** +### Automatically, when an alert is triggered **(ULTIMATE ALL)** In the project settings, you can turn on [creating an incident automatically](alerts.md#trigger-actions-from-alerts) whenever an alert is triggered. @@ -166,7 +166,7 @@ To change the status of an incident: **Triggered** is the default status for new incidents. -### As an on-call responder **(PREMIUM)** +### As an on-call responder **(PREMIUM ALL)** On-call responders can respond to [incident pages](paging.md#escalating-an-incident) by changing the status. @@ -181,7 +181,7 @@ In GitLab 15.1 and earlier, changing the status of an [incident created from an also changes the alert status. In [GitLab 15.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/356057), the alert status is independent and does not change when the incident status changes. -## Change escalation policy **(PREMIUM)** +## Change escalation policy **(PREMIUM ALL)** Prerequisites: @@ -245,7 +245,7 @@ To configure the setting: 1. Select the **Automatically close associated incident** checkbox. 1. Select **Save changes**. -When GitLab receives a recovery alert, it closes the associated incident. +When GitLab receives a [recovery alert](integrations.md#recovery-alerts), it closes the associated incident. This action is recorded as a system note on the incident indicating that it was closed automatically by the GitLab Alert bot. diff --git a/doc/operations/incident_management/oncall_schedules.md b/doc/operations/incident_management/oncall_schedules.md index 8e3318766b4..808dc30581d 100644 --- a/doc/operations/incident_management/oncall_schedules.md +++ b/doc/operations/incident_management/oncall_schedules.md @@ -4,7 +4,7 @@ group: Respond 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 --- -# On-call Schedule Management **(PREMIUM)** +# On-call Schedule Management **(PREMIUM ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4544) in GitLab 13.11. diff --git a/doc/operations/incident_management/paging.md b/doc/operations/incident_management/paging.md index be28e94c148..05cc8c8e221 100644 --- a/doc/operations/incident_management/paging.md +++ b/doc/operations/incident_management/paging.md @@ -4,7 +4,7 @@ group: Respond 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 --- -# Paging and notifications **(FREE)** +# Paging and notifications **(FREE ALL)** When there is a new alert or incident, it is important for a responder to be notified immediately so they can triage and respond to the problem. Responders can receive @@ -35,7 +35,7 @@ a single email notification for new alerts. [Update the alert's status](alerts.md#change-an-alerts-status) to manage email notifications for an alert. -## Paging **(PREMIUM)** +## Paging **(PREMIUM ALL)** In projects that have an [escalation policy](escalation_policies.md) configured, on-call responders can be automatically paged about critical problems through email. diff --git a/doc/operations/incident_management/slack.md b/doc/operations/incident_management/slack.md index aa0d057bfd8..82d5d8b3150 100644 --- a/doc/operations/incident_management/slack.md +++ b/doc/operations/incident_management/slack.md @@ -32,7 +32,7 @@ Prerequisites: 1. Install the [GitLab for Slack app](../../user/project/integrations/gitlab_slack_application.md). This way, you can use slash commands in Slack to create and update GitLab incidents. -1. Enable [Slack notifications](../../user/project/integrations/slack.md). Be sure to enable +1. Enable [Slack notifications](../../user/project/integrations/gitlab_slack_application.md#slack-notifications). Be sure to enable notifications for `Incident` events, and to define a Slack channel to receive the relevant notifications. 1. Authorize GitLab to take actions on behalf of your Slack user. Each user must do this before they can use any of the incident slash commands. diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md index a52790b7f70..374571d225e 100644 --- a/doc/operations/incident_management/status_page.md +++ b/doc/operations/incident_management/status_page.md @@ -4,7 +4,7 @@ group: Respond 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 --- -# Status Page **(ULTIMATE)** +# Status Page **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2479) in GitLab 12.10. diff --git a/doc/operations/index.md b/doc/operations/index.md index 922ec557c4c..73925afb2d8 100644 --- a/doc/operations/index.md +++ b/doc/operations/index.md @@ -4,7 +4,7 @@ group: Respond 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 --- -# Monitor application performance **(FREE)** +# Monitor application performance **(FREE ALL)** GitLab provides a variety of tools to help operate and maintain your applications. diff --git a/doc/operations/metrics/alerts.md b/doc/operations/metrics/alerts.md index 44a257f532b..a5f580ac503 100644 --- a/doc/operations/metrics/alerts.md +++ b/doc/operations/metrics/alerts.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../index.md' --- -# Set up alerts for Prometheus metrics (removed) **(FREE)** +# Set up alerts for Prometheus metrics (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/default.md b/doc/operations/metrics/dashboards/default.md index 28a3adc5051..3eec1272307 100644 --- a/doc/operations/metrics/dashboards/default.md +++ b/doc/operations/metrics/dashboards/default.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../index.md' --- -# GitLab-defined metrics dashboards (removed) **(FREE)** +# GitLab-defined metrics dashboards (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/develop.md b/doc/operations/metrics/dashboards/develop.md index b7912e164d7..c6d4721863a 100644 --- a/doc/operations/metrics/dashboards/develop.md +++ b/doc/operations/metrics/dashboards/develop.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../index.md' --- -# Developing templates for custom dashboards (removed) **(FREE)** +# Developing templates for custom dashboards (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/index.md b/doc/operations/metrics/dashboards/index.md index a4cf12cc64a..df94f979f5f 100644 --- a/doc/operations/metrics/dashboards/index.md +++ b/doc/operations/metrics/dashboards/index.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../index.md' --- -# Custom dashboards (removed) **(FREE)** +# Custom dashboards (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/panel_types.md b/doc/operations/metrics/dashboards/panel_types.md index c789e99052c..8dcf4e6ad28 100644 --- a/doc/operations/metrics/dashboards/panel_types.md +++ b/doc/operations/metrics/dashboards/panel_types.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../index.md' --- -# Panel types for dashboards (removed) **(FREE)** +# Panel types for dashboards (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/settings.md b/doc/operations/metrics/dashboards/settings.md index 5572dfa360f..7abcbf88d59 100644 --- a/doc/operations/metrics/dashboards/settings.md +++ b/doc/operations/metrics/dashboards/settings.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../index.md' --- -# Dashboard settings (removed) **(FREE)** +# Dashboard settings (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/templating_variables.md b/doc/operations/metrics/dashboards/templating_variables.md index a93c559c98c..ceeeb229a81 100644 --- a/doc/operations/metrics/dashboards/templating_variables.md +++ b/doc/operations/metrics/dashboards/templating_variables.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../index.md' --- -# Templating variables for metrics dashboards (removed) **(FREE)** +# Templating variables for metrics dashboards (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/variables.md b/doc/operations/metrics/dashboards/variables.md index 45e13aa731a..b4ea05a0cea 100644 --- a/doc/operations/metrics/dashboards/variables.md +++ b/doc/operations/metrics/dashboards/variables.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../index.md' --- -# Using variables (removed) **(FREE)** +# Using variables (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/yaml.md b/doc/operations/metrics/dashboards/yaml.md index 7807f713773..95c02319b19 100644 --- a/doc/operations/metrics/dashboards/yaml.md +++ b/doc/operations/metrics/dashboards/yaml.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../index.md' --- -# Dashboard YAML properties (removed) **(FREE)** +# Dashboard YAML properties (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/yaml_number_format.md b/doc/operations/metrics/dashboards/yaml_number_format.md index 90e7f67b153..e75beadfab9 100644 --- a/doc/operations/metrics/dashboards/yaml_number_format.md +++ b/doc/operations/metrics/dashboards/yaml_number_format.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../index.md' --- -# Unit formats reference (removed) **(FREE)** +# Unit formats reference (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/embed.md b/doc/operations/metrics/embed.md index 00c145adee3..68f115b66db 100644 --- a/doc/operations/metrics/embed.md +++ b/doc/operations/metrics/embed.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../index.md' --- -# Embedding metric charts within GitLab Flavored Markdown (removed) **(FREE)** +# Embedding metric charts within GitLab Flavored Markdown (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/embed_grafana.md b/doc/operations/metrics/embed_grafana.md index e14b4b5a893..82967aa663f 100644 --- a/doc/operations/metrics/embed_grafana.md +++ b/doc/operations/metrics/embed_grafana.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w remove_date: '2023-08-22' redirect_to: '../index.md' --- -# Embed Grafana panels in Markdown (removed) **(FREE)** +# Embed Grafana panels in Markdown (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/index.md b/doc/operations/metrics/index.md index 98ed9aba0da..65f84c9c825 100644 --- a/doc/operations/metrics/index.md +++ b/doc/operations/metrics/index.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../index.md' --- -# Monitor your environment's metrics (removed) **(FREE)** +# Monitor your environment's metrics (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/policy/experiment-beta-support.md b/doc/policy/experiment-beta-support.md index b6156f9c20f..68cc96f118b 100644 --- a/doc/policy/experiment-beta-support.md +++ b/doc/policy/experiment-beta-support.md @@ -4,7 +4,7 @@ group: Distribution 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 --- -# Support for Experiment, Beta, and Generally Available features **(PREMIUM)** +# Support for Experiment, Beta, and Generally Available features **(PREMIUM ALL)** Some GitLab features are released as Experiment or Beta versions and are [not fully supported](https://about.gitlab.com/support/statement-of-support/#alpha-beta-features). diff --git a/doc/raketasks/index.md b/doc/raketasks/index.md index e998c97a4d7..b50646e4841 100644 --- a/doc/raketasks/index.md +++ b/doc/raketasks/index.md @@ -11,8 +11,8 @@ processes. You can perform GitLab Rake tasks by using: -- `gitlab-rake <raketask>` for [Omnibus GitLab](https://docs.gitlab.com/omnibus/index.html) and [GitLab Helm chart](https://docs.gitlab.com/charts/troubleshooting/kubernetes_cheat_sheet.html#gitlab-specific-kubernetes-information) installations. -- `bundle exec rake <raketask>` for [source](../install/installation.md) installations. +- `gitlab-rake <raketask>` for [Linux package](https://docs.gitlab.com/omnibus/index.html) and [GitLab Helm chart](https://docs.gitlab.com/charts/troubleshooting/kubernetes_cheat_sheet.html#gitlab-specific-kubernetes-information) installations. +- `bundle exec rake <raketask>` for [self-compiled](../install/installation.md) installations. ## Available Rake tasks @@ -37,7 +37,7 @@ The following Rake tasks are available for use with GitLab: | [Sidekiq job migration](../administration/sidekiq/sidekiq_job_migration.md) | Migrate Sidekiq jobs scheduled for future dates to a new queue. | | [Service Desk email](../administration/raketasks/service_desk_email.md) | Service Desk email-related tasks. | | [SMTP maintenance](../administration/raketasks/smtp.md) | SMTP-related tasks. | -| [SPDX license list import](spdx.md) | Import a local copy of the [SPDX license list](https://spdx.org/licenses/) for matching [License Compliance policies](../user/compliance/license_compliance/index.md). | +| [SPDX license list import](spdx.md) | Import a local copy of the [SPDX license list](https://spdx.org/licenses/) for matching [License approval policies](../user/compliance/license_approval_policies.md). | | [Repository storage](../administration/raketasks/storage.md) | List and migrate existing projects and attachments from legacy storage to hashed storage. | | [Reset user passwords](../security/reset_user_password.md#use-a-rake-task) | Reset user passwords using Rake. | | [Uploads migrate](../administration/raketasks/uploads/migrate.md) | Migrate uploads between local storage and object storage. | diff --git a/doc/raketasks/spdx.md b/doc/raketasks/spdx.md index 608139fa404..423bd909982 100644 --- a/doc/raketasks/spdx.md +++ b/doc/raketasks/spdx.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # SPDX license list import Rake task **(ULTIMATE SELF)** GitLab provides a Rake task for uploading a fresh copy of the [SPDX license list](https://spdx.org/licenses/) -to a GitLab instance. This list is needed for matching the names of [License Compliance policies](../user/compliance/license_compliance/index.md). +to a GitLab instance. This list is needed for matching the names of [License approval policies](../user/compliance/license_approval_policies.md). To import a fresh copy of the PDX license list, run: diff --git a/doc/raketasks/x509_signatures.md b/doc/raketasks/x509_signatures.md index 364264ae204..ab35f432fc2 100644 --- a/doc/raketasks/x509_signatures.md +++ b/doc/raketasks/x509_signatures.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # X.509 signatures Rake task **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/122159) in GitLab 12.10. - When [signing commits with X.509](../user/project/repository/x509_signed_commits/index.md), the trust anchor might change and the signatures stored within the database must be updated. @@ -18,14 +16,18 @@ certificate store. To update all X.509 signatures, run: -**Omnibus Installations:** +::Tabs + +:::TabTitle Linux package (Omnibus) ```shell sudo gitlab-rake gitlab:x509:update_signatures ``` -**Source Installations:** +:::TabTitle Self-compiled (source) ```shell sudo -u git -H bundle exec rake gitlab:x509:update_signatures RAILS_ENV=production ``` + +::EndTabs diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md index 39cd8f8e074..fdf3e5055b0 100644 --- a/doc/security/crime_vulnerability.md +++ b/doc/security/crime_vulnerability.md @@ -23,10 +23,10 @@ GitLab supports both Gzip and [SPDY](https://nginx.org/en/docs/http/ngx_http_spd vulnerability by deactivating Gzip when HTTPS is enabled. The sources of the files are here: -- [Source installation NGINX file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/support/nginx/gitlab-ssl) -- [Omnibus installation NGINX file](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/templates/default/nginx-gitlab-http.conf.erb) +- [Self-compiled installation NGINX file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/support/nginx/gitlab-ssl) +- [Linux package installation NGINX file](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/templates/default/nginx-gitlab-http.conf.erb) -Although SPDY is enabled in Omnibus installations, CRIME relies on compression +Although SPDY is enabled in Linux package installations, CRIME relies on compression (the 'C') and the default compression level in the NGINX SPDY module is 0 (no compression). diff --git a/doc/security/email_verification.md b/doc/security/email_verification.md index 4d7dd1ab36f..da844e3a2eb 100644 --- a/doc/security/email_verification.md +++ b/doc/security/email_verification.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 --- -# Account email verification **(FREE)** +# Account email verification **(FREE ALL)** > [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. diff --git a/doc/security/hardening_configuration_recommendations.md b/doc/security/hardening_configuration_recommendations.md index 475ec06835c..1cc3294f68b 100644 --- a/doc/security/hardening_configuration_recommendations.md +++ b/doc/security/hardening_configuration_recommendations.md @@ -23,36 +23,48 @@ NGINX is controlled and integrated into GitLab, modification of the `/etc/gitlab/gitlab.rb` file used for adjustments. Here are a few recommendations for helping to improve the security of NGINX itself: -```shell -# -# Only strong ciphers are used -# -nginx['ssl_ciphers'] = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256" -# -# Follow preferred ciphers and the order listed as preference -# -nginx['ssl_prefer_server_ciphers'] = "on" -# -# Only allow TLSv1.2 and TLSv1.3 -# -nginx['ssl_protocols'] = "TLSv1.2 TLSv1.3" - -##! **Recommended in: https://nginx.org/en/docs/http/ngx_http_ssl_module.html** -nginx['ssl_session_cache'] = "builtin:1000 shared:SSL:10m" - -##! **Default according to https://nginx.org/en/docs/http/ngx_http_ssl_module.html** -nginx['ssl_session_timeout'] = "5m" - -# Should prevent logjam attack etc -# For the example below, run the following first: -# openssl dhparam -out /etc/gitlab/ssl/dhparam.pem 4096 -nginx['ssl_dhparam'] = "/etc/gitlab/ssl/dhparams.pem" # changed from nil - -# Turn off session ticket reuse -nginx['ssl_session_tickets'] = "off" -# Pick our own curve instead of what openssl hands us -nginx['ssl_ecdh_curve'] = "secp384r1" -``` +1. Create the [Diffie-Hellman key](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam): + + ```shell + sudo openssl dhparam -out /etc/gitlab/ssl/dhparam.pem 4096 + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and add the following: + + ```ruby + # + # Only strong ciphers are used + # + nginx['ssl_ciphers'] = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256" + # + # Follow preferred ciphers and the order listed as preference + # + nginx['ssl_prefer_server_ciphers'] = "on" + # + # Only allow TLSv1.2 and TLSv1.3 + # + nginx['ssl_protocols'] = "TLSv1.2 TLSv1.3" + + ##! **Recommended in: https://nginx.org/en/docs/http/ngx_http_ssl_module.html** + nginx['ssl_session_cache'] = "builtin:1000 shared:SSL:10m" + + ##! **Default according to https://nginx.org/en/docs/http/ngx_http_ssl_module.html** + nginx['ssl_session_timeout'] = "5m" + + # Should prevent logjam attack etc + nginx['ssl_dhparam'] = "/etc/gitlab/ssl/dhparams.pem" # changed from nil + + # Turn off session ticket reuse + nginx['ssl_session_tickets'] = "off" + # Pick our own curve instead of what openssl hands us + nginx['ssl_ecdh_curve'] = "secp384r1" + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` ## Consul diff --git a/doc/security/identity_verification.md b/doc/security/identity_verification.md index 761bc114da2..a4f7baad0e2 100644 --- a/doc/security/identity_verification.md +++ b/doc/security/identity_verification.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 --- -# Identity verification **(FREE)** +# Identity verification **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95722) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `identity_verification`. Disabled by default. @@ -20,6 +20,8 @@ three stages of verification to register an account: - **Medium-risk users** - Phone number verification. - **High-risk users** - Credit card verification. +Users created after signing in with [SAML SSO for GitLab.com groups](../user/group/saml_sso/index.md) are exempt from identity verification. + ## Email verification To register an account, you must provide a valid email address. diff --git a/doc/security/img/ssh_keys_restrictions_settings.png b/doc/security/img/ssh_keys_restrictions_settings.png Binary files differindex 1f37a25d19f..1935f964807 100644 --- a/doc/security/img/ssh_keys_restrictions_settings.png +++ b/doc/security/img/ssh_keys_restrictions_settings.png diff --git a/doc/security/index.md b/doc/security/index.md index 1b486ab5feb..5365228537f 100644 --- a/doc/security/index.md +++ b/doc/security/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index --- -# Secure your installation **(FREE)** +# Secure your installation **(FREE ALL)** - [Passwords and OAuth tokens storage](password_storage.md) - [Password length limits](password_length_limits.md) @@ -24,7 +24,7 @@ type: index - [Proxying images](asset_proxy.md) - [CI/CD variables](../ci/variables/index.md#cicd-variable-security) - [Token overview](token_overview.md) -- [Project Import decompressed archive size limits](project_import_decompressed_archive_size_limits.md) +- [Maximum decompressed file size for imported archives](../administration/settings/account_and_limit_settings.md#maximum-decompressed-file-size-for-imported-archives) - [Responding to security incidents](responding_to_security_incidents.md) To harden your GitLab instance and minimize the risk of unwanted user account creation, consider access control features like [Sign up restrictions](../administration/settings/sign_up_restrictions.md) and [Authentication options](../topics/authentication/index.md). For more detailed information, refer to [Hardening](hardening.md). diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md index 16facadd782..21e4ad8b108 100644 --- a/doc/security/information_exclusivity.md +++ b/doc/security/information_exclusivity.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts --- -# Information exclusivity **(FREE)** +# Information exclusivity **(FREE ALL)** Git is a distributed version control system (DVCS). This means that everyone who works with the source code has a local copy of the complete repository. diff --git a/doc/security/password_storage.md b/doc/security/password_storage.md index 67ef161e634..e814f4e5069 100644 --- a/doc/security/password_storage.md +++ b/doc/security/password_storage.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Password and OAuth token storage **(FREE)** +# Password and OAuth token storage **(FREE ALL)** GitLab administrators can configure how passwords and OAuth tokens are stored. diff --git a/doc/security/passwords_for_integrated_authentication_methods.md b/doc/security/passwords_for_integrated_authentication_methods.md index 68fb097ab9a..a141241f97c 100644 --- a/doc/security/passwords_for_integrated_authentication_methods.md +++ b/doc/security/passwords_for_integrated_authentication_methods.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Generated passwords for users created through integrated authentication **(FREE)** +# Generated passwords for users created through integrated authentication **(FREE ALL)** GitLab allows users to set up accounts through integration with external [authentication and authorization providers](../administration/auth/index.md). diff --git a/doc/security/project_import_decompressed_archive_size_limits.md b/doc/security/project_import_decompressed_archive_size_limits.md index 980a084347a..48767740625 100644 --- a/doc/security/project_import_decompressed_archive_size_limits.md +++ b/doc/security/project_import_decompressed_archive_size_limits.md @@ -1,31 +1,11 @@ --- -stage: Manage -group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +redirect_to: '../administration/settings/account_and_limit_settings.md#maximum-decompressed-file-size-for-imported-archives' +remove_date: '2023-11-02' --- -# Project import decompressed archive size limits **(FREE SELF)** +This document was moved to [another location](../administration/settings/account_and_limit_settings.md#maximum-decompressed-file-size-for-imported-archives). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31564) in GitLab 13.2. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63025) in GitLab 14.0. - -When using [Project Import](../user/project/settings/import_export.md), the size of the decompressed project archive is limited to 10 Gb. - -If decompressed size exceeds this limit, `Decompressed archive size validation failed` error is returned. - -## Enable/disable size validation - -If you have a project with decompressed size exceeding this limit, -it is possible to disable the validation by turning off the -`validate_import_decompressed_archive_size` feature flag. - -Start a [Rails console](../administration/operations/rails_console.md#starting-a-rails-console-session). - -```ruby -# Disable -Feature.disable(:validate_import_decompressed_archive_size) - -# Enable -Feature.enable(:validate_import_decompressed_archive_size) -``` +<!-- This redirect file can be deleted after <2023-11-02>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md index 5353c11d2f1..ee10d66a8ad 100644 --- a/doc/security/rate_limits.md +++ b/doc/security/rate_limits.md @@ -133,6 +133,14 @@ There is a rate limit for the GraphQL `aiAction` mutation, which is enforced to The **rate limit** is 160 calls per 8 hours per authenticated user. +### Delete a member using the API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118296) in GitLab 16.0. + +There is a rate limit for [removing project or group members using the API endpoints](../api/members.md#remove-a-member-from-a-group-or-project) `/groups/:id/members` or `/project/:id/members`. + +The **rate limit** is 60 deletions per minute. + ## Troubleshooting ### Rack Attack is denylisting the load balancer diff --git a/doc/security/reset_user_password.md b/doc/security/reset_user_password.md index 7adb6256259..fa15efe7cb7 100644 --- a/doc/security/reset_user_password.md +++ b/doc/security/reset_user_password.md @@ -33,37 +33,45 @@ A confirmation is displayed. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52347) in GitLab 13.9. -Use the following Rake task to reset a user's password: +Use the following Rake task to reset a user's password. -- **For Omnibus installations** +::Tabs - ```shell - sudo gitlab-rake "gitlab:password:reset" - ``` +:::TabTitle Linux package (Omnibus) -- **For installations from source** +```shell +sudo gitlab-rake "gitlab:password:reset" +``` - ```shell - bundle exec rake "gitlab:password:reset" - ``` +:::TabTitle Self-compiled (source) + +```shell +bundle exec rake "gitlab:password:reset" +``` + +::EndTabs GitLab requests a username, a password, and confirmation of the password. When complete, the user's password is updated. The Rake task can take a username as an argument. For example, to reset the password for the user with username `sidneyjones`: -- **For Omnibus installations** +::Tabs + +:::TabTitle Linux package (Omnibus) ```shell sudo gitlab-rake "gitlab:password:reset[sidneyjones]" ``` -- **For installations from source** +:::TabTitle Self-compiled (source) ```shell bundle exec rake "gitlab:password:reset[sidneyjones]" ``` +::EndTabs + ## Use a Rails console If you know the username, user ID, or email address, you can use the Rails console to reset their password: diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md index 1e4a4226138..87cbf12471f 100644 --- a/doc/security/ssh_keys_restrictions.md +++ b/doc/security/ssh_keys_restrictions.md @@ -49,7 +49,7 @@ By default, the GitLab.com and self-managed settings for the - ECDSA_SK SSH keys are allowed (GitLab 14.8 and later). - ED25519_SK SSH keys are allowed (GitLab 14.8 and later). -## Block banned or compromised keys **(FREE)** +## Block banned or compromised keys **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24614) in GitLab 15.1 [with a flag](../administration/feature_flags.md) named `ssh_banned_key`. Enabled by default. > - Generally available in GitLab 15.2. [Feature flag `ssh_banned_key`](https://gitlab.com/gitlab-org/gitlab/-/issues/363410) removed. diff --git a/doc/security/token_overview.md b/doc/security/token_overview.md index fb4fb71356a..cb01c7d5160 100644 --- a/doc/security/token_overview.md +++ b/doc/security/token_overview.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab Token overview **(FREE)** +# GitLab Token overview **(FREE ALL)** This document lists tokens used in GitLab, their purpose and, where applicable, security guidance. @@ -178,7 +178,7 @@ This table shows available scopes per token. Scopes can be limited further on to 1. When creating a scoped token, consider using the most limited scope possible to reduce the impact of accidentally leaking the token. 1. When creating a token, consider setting a token that expires when your task is complete. For example, if performing a one-off import, set the token to expire after a few hours or a day. This reduces the impact of a token that is accidentally leaked because it is useless when it expires. -1. If you are recording a video that might contain a sensitive secret like a personal access token (PAT), feed token, or trigger token, you must mask that secret before uploading the video to GitLab Unfiltered or any other video hosting service. As an additional defense-in-depth security measure, you must revoke those secrets before you share the video publicly. For more information, see [revoking a PAT](../user/profile/personal_access_tokens.md#revoke-a-personal-access-token). +1. If you have set up a demo environment to showcase a project you have been working on and you are recording a video or writing a blog post describing that project, make sure you are not leaking sensitive secrets (for example a personal access token (PAT), feed token or trigger token) during that process. If you have finished the demo, you must revoke all the secrets created during that demo. For more information, see [revoking a PAT](../user/profile/personal_access_tokens.md#revoke-a-personal-access-token). 1. Adding access tokens to URLs is a security risk, especially when cloning or adding a remote because Git then writes the URL to its `.git/config` file in plain text. URLs are also generally logged by proxies and application servers, which makes those credentials visible to system administrators. Instead, pass API calls an access token using headers like [the `Private-Token` header](../api/rest/index.md#personalprojectgroup-access-tokens). @@ -189,7 +189,6 @@ This table shows available scopes per token. Scopes can be limited further on to Consider an approach such as [using external secrets in CI](../ci/secrets/index.md). 1. Do not log credentials in the console logs or artifacts. Consider [protecting](../ci/variables/index.md#protect-a-cicd-variable) and [masking](../ci/variables/index.md#mask-a-cicd-variable) your credentials. -1. If you have set up a demo environment to showcase a project you have been working on and you are recording a video or writing a blog post describing that project, make sure you are not leaking sensitive secrets during that process. If you are done with the demo, you must revoke all the secrets created during that demo. 1. Review all active access tokens of all types on a regular basis and revoke any that are no longer needed. This includes: - Personal, project, and group access tokens. - Feed tokens. diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index 5dd8da72e83..906bf4cd062 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.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 --- -# Enforce two-factor authentication **(FREE)** +# Enforce two-factor authentication **(FREE ALL)** Two-factor authentication (2FA) provides an additional level of security to your users' GitLab account. When enabled, users are prompted for a code generated by an application in @@ -46,7 +46,7 @@ all user can be disabled. Connect to the Rails console and run: Gitlab::CurrentSettings.update!('require_two_factor_authentication': false) ``` -## Enforce 2FA for all users in a group **(FREE)** +## Enforce 2FA for all users in a group **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24965) in GitLab 12.0, 2FA settings for a group are also applied to subgroups. @@ -132,7 +132,7 @@ sudo gitlab-rake gitlab:two_factor:disable_for_all_users sudo -u git -H bundle exec rake gitlab:two_factor:disable_for_all_users RAILS_ENV=production ``` -## 2FA for Git over SSH operations **(PREMIUM)** +## 2FA for Git over SSH operations **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/270554) in GitLab 13.7. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/299088) from GitLab Free to GitLab Premium in 13.9. diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md index f2c0052c2b8..899fed0b584 100644 --- a/doc/security/user_email_confirmation.md +++ b/doc/security/user_email_confirmation.md @@ -21,14 +21,7 @@ they confirm their email address. By default, a user can confirm their account within 24 hours after the confirmation email was sent. After 24 hours, the confirmation token becomes invalid. -<!-- ## Troubleshooting +## Automatically delete unconfirmed users **(PREMIUM SELF)** -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +When email confirmation is turned on, administrators can enable the setting to +[automatically delete unconfirmed users](../administration/moderate_users.md#automatically-delete-unconfirmed-users). diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md index 5895eda8cdd..e0f1342b9c9 100644 --- a/doc/security/user_file_uploads.md +++ b/doc/security/user_file_uploads.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 file uploads **(FREE)** +# User file uploads **(FREE ALL)** Users can upload files to: diff --git a/doc/subscriptions/bronze_starter.md b/doc/subscriptions/bronze_starter.md index 1f84c27d27a..93a68fa0338 100644 --- a/doc/subscriptions/bronze_starter.md +++ b/doc/subscriptions/bronze_starter.md @@ -107,7 +107,7 @@ the tiers are no longer mentioned in GitLab documentation: - [Filtering merge requests](../user/project/merge_requests/index.md#filter-the-list-of-merge-requests) by approvers - [Filtering merge requests](../user/project/merge_requests/index.md#filter-the-list-of-merge-requests) by "approved by" - [Advanced search (Elasticsearch)](../user/search/advanced_search.md) -- [Service Desk](../user/project/service_desk.md) +- [Service Desk](../user/project/service_desk/index.md) - [Storage usage statistics](../user/usage_quotas.md#storage-usage-statistics) The following developer features continue to be available to Starter and diff --git a/doc/subscriptions/choosing_subscription.md b/doc/subscriptions/choosing_subscription.md index ccb68792531..ad42eecc9c1 100644 --- a/doc/subscriptions/choosing_subscription.md +++ b/doc/subscriptions/choosing_subscription.md @@ -30,7 +30,7 @@ A new subscription must be purchased and applied as needed. ## Choose a GitLab tier Pricing is [tier-based](https://about.gitlab.com/pricing/), allowing you to choose -the features that fit your budget. +the features that fit your budget. For more details, see [a comparison of self-managed features available in each tier](https://about.gitlab.com/pricing/feature-comparison/). diff --git a/doc/subscriptions/customers_portal.md b/doc/subscriptions/customers_portal.md index 25f36432f4b..45a4324f45d 100644 --- a/doc/subscriptions/customers_portal.md +++ b/doc/subscriptions/customers_portal.md @@ -25,12 +25,26 @@ To sign in to Customers Portal using your GitLab.com account: 1. Navigate to [Customers Portal](https://customers.gitlab.com/customers/sign_in). 1. Select **Continue with your GitLab.com account**. -To sign in to Customers Portal using your email and password: +To sign in to Customers Portal with your email and to receive a one-time sign-in link: 1. Navigate to [Customers Portal](https://customers.gitlab.com/customers/sign_in). -1. Select **Sign in with your email and password**. -1. Provide the **Email** and **Password** for your Customers Portal account. -1. Select **Sign in**. +1. Select **Sign in with your email**. +1. Provide the **Email** for your Customers Portal account. You will receive + an email with a one-time, sign-in link for your Customers Portal account. +1. In the email you received, select **Sign in**. + +NOTE: +The one-time sign-in link expires in 24 hours and can only be used once. + +## Confirm Customers Portal email address + +The first time you sign in to the Customers Portal with a one-time sign-in link, +you must confirm your email address to maintain access to the Customers Portal. If you sign in +to the Customers Portal through GitLab.com, you don't need to confirm your email address. + +You must also confirm any updates to the account email address. You will receive +an automatic email with instructions about how to confirm, which you can [resend](https://customers.gitlab.com/customers/confirmation/new) +if required. ## Change account owner information @@ -47,7 +61,6 @@ To change account owner information, including name, billing address, and email If you want to transfer ownership of the Customers Portal account to another person, after you enter that person's personal details, you must also: -- [Change the Customers Portal account password](#change-customers-portal-account-password). - [Change the linked GitLab.com account](#change-the-linked-account), if you have one linked. ## Change your company details @@ -111,15 +124,6 @@ To change the GitLab.com account linked to your Customers Portal account: 1. Under **Your GitLab.com account**, select **Change linked account**. 1. Sign in to the [GitLab.com](https://gitlab.com/users/sign_in) account you want to link to the Customers Portal account. -## Change Customers Portal account password - -To change the password for this customers portal account: - -1. Sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). -1. Select the **My account** dropdown list and select **Account details**. -1. Make the required changes to the **Your password** section. -1. Select **Save changes**. - ## Customers that purchased through a reseller If you purchased a subscription through an authorized reseller (including GCP and AWS marketplaces), you have access to the Customers Portal to: diff --git a/doc/subscriptions/gitlab_com/index.md b/doc/subscriptions/gitlab_com/index.md index 8cd5777e4cb..cb2a324bc9b 100644 --- a/doc/subscriptions/gitlab_com/index.md +++ b/doc/subscriptions/gitlab_com/index.md @@ -83,7 +83,7 @@ Every user is included in seat usage, with the following exceptions: - GitLab-created service accounts: - [Ghost User](../../user/profile/account/delete_account.md#associated-records). - Bots such as: - - [Support Bot](../../user/project/service_desk.md#support-bot-user). + - [Support Bot](../../user/project/service_desk/index.md#support-bot-user). - [Bot users for projects](../../user/project/settings/project_access_tokens.md#bot-users-for-projects). - [Bot users for groups](../../user/group/settings/group_access_tokens.md#bot-users-for-groups). @@ -166,7 +166,7 @@ For example, if you purchase a subscription for 10 users: Seats owed = 12 - 10 (Maximum users - users in subscription) -### Free Guest users **(ULTIMATE)** +### Free Guest users **(ULTIMATE ALL)** In the **Ultimate** tier, users who are assigned the Guest role do not consume a seat. The user must not be assigned any other role, anywhere in the instance or in the namespace for GitLab SaaS. diff --git a/doc/subscriptions/gitlab_dedicated/index.md b/doc/subscriptions/gitlab_dedicated/index.md index 75fcdb70161..a2e04812876 100644 --- a/doc/subscriptions/gitlab_dedicated/index.md +++ b/doc/subscriptions/gitlab_dedicated/index.md @@ -123,7 +123,8 @@ The following GitLab application features are not available: - Reply-by email - Service Desk - GitLab-managed runners (hosted runners) -- Any feature [not listed above](#available-features) which must be configured outside of the GitLab user interface. +- GitLab AI capabilities (Refer to our [direction page](https://about.gitlab.com/direction/saas-platforms/dedicated/#supporting-ai-features-on-gitlab-dedicated) for more information) +- Features other than [available features](#available-features) that must be configured outside of the GitLab user interface including those behind feature flags The following features will not be supported: diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md index 0b78704bb4d..8577fdb460d 100644 --- a/doc/subscriptions/index.md +++ b/doc/subscriptions/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Subscribe to GitLab **(PREMIUM)** +# Subscribe to GitLab **(PREMIUM ALL)** Choose and manage the subscription that's right for you and your organization. diff --git a/doc/subscriptions/quarterly_reconciliation.md b/doc/subscriptions/quarterly_reconciliation.md index 16f1828f2c3..7e7cc93e284 100644 --- a/doc/subscriptions/quarterly_reconciliation.md +++ b/doc/subscriptions/quarterly_reconciliation.md @@ -4,7 +4,7 @@ group: Purchase 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 --- -# Quarterly reconciliation and annual true-ups **(PREMIUM)** +# Quarterly reconciliation and annual true-ups **(PREMIUM ALL)** GitLab reviews your seat usage and sends you an invoice for any overages. This review can occur: diff --git a/doc/subscriptions/self_managed/index.md b/doc/subscriptions/self_managed/index.md index e754c2a06a2..fca6ea57a95 100644 --- a/doc/subscriptions/self_managed/index.md +++ b/doc/subscriptions/self_managed/index.md @@ -57,7 +57,7 @@ billable user, with the following exceptions: - GitLab-created service accounts: - [Ghost User](../../user/profile/account/delete_account.md#associated-records). - Bots such as: - - [Support Bot](../../user/project/service_desk.md#support-bot-user). + - [Support Bot](../../user/project/service_desk/index.md#support-bot-user). - [Bot users for projects](../../user/project/settings/project_access_tokens.md#bot-users-for-projects). - [Bot users for groups](../../user/group/settings/group_access_tokens.md#bot-users-for-groups). - Other [internal users](../../development/internal_users.md#internal-users). @@ -87,7 +87,7 @@ If you add more users to your GitLab instance than you are licensed for, payment If you do not add these users during the renewal process, your license key will not work. -### Free Guest users **(ULTIMATE)** +### Free Guest users **(ULTIMATE ALL)** In the **Ultimate** tier, users who are assigned the Guest role do not consume a seat. The user must not be assigned any other role, anywhere in the instance. diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index a7611784284..6137ade4559 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -4,7 +4,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 --- -# Authentication **(FREE)** +# Authentication **(FREE ALL)** This page gathers all the resources for the topic **Authentication** in GitLab. diff --git a/doc/topics/autodevops/cicd_variables.md b/doc/topics/autodevops/cicd_variables.md index dff36727bf2..a5897e0b233 100644 --- a/doc/topics/autodevops/cicd_variables.md +++ b/doc/topics/autodevops/cicd_variables.md @@ -255,7 +255,7 @@ production, GitLab creates a `production_manual` job. You can also enable manual deployment in your [project settings](requirements.md#auto-devops-deployment-strategy). -## Deploy policy for canary environments **(PREMIUM)** +## Deploy policy for canary environments **(PREMIUM ALL)** You can use a [canary environment](../../user/project/canary_deployments.md) before deploying any changes to production. @@ -265,7 +265,7 @@ If you set `CANARY_ENABLED`, GitLab creates two [manual jobs](../../ci/pipelines - `canary` - Deploys the application to the canary environment. - `production_manual` - Deploys the application to production. -## Incremental rollout to production **(PREMIUM)** +## Incremental rollout to production **(PREMIUM ALL)** Use an incremental rollout to continuously deploy your application, starting with only a few pods. You can increase the number of pods @@ -310,7 +310,7 @@ With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and with `STAGING_ENABLED`:  -## Timed incremental rollout to production **(PREMIUM)** +## Timed incremental rollout to production **(PREMIUM ALL)** Use a timed incremental rollout to continuously deploy your application, starting with only a few pods. diff --git a/doc/topics/autodevops/cloud_deployments/auto_devops_with_eks.md b/doc/topics/autodevops/cloud_deployments/auto_devops_with_eks.md index b85b99d1874..d8544f3f382 100644 --- a/doc/topics/autodevops/cloud_deployments/auto_devops_with_eks.md +++ b/doc/topics/autodevops/cloud_deployments/auto_devops_with_eks.md @@ -178,9 +178,6 @@ The jobs are separated into stages: - Jobs suffixed with `-sast` run static analysis on the current code to check for potential security issues, and are allowed to fail ([Auto SAST](../stages.md#auto-sast)) - The `secret-detection` job checks for leaked secrets and is allowed to fail ([Auto Secret Detection](../stages.md#auto-secret-detection)) - - The `license_scanning` job searches the application's dependencies to determine each of their - licenses and is allowed to fail - ([Auto License Compliance](../stages.md#auto-license-compliance)) - **Review** - Pipelines on the default branch include this stage with a `dast_environment_deploy` job. To learn more, see [Dynamic Application Security Testing (DAST)](../../../user/application_security/dast/index.md). @@ -230,8 +227,7 @@ in **Settings > CI/CD > Variables**. ### Work with branches -Following the [GitLab flow](../../gitlab_flow.md#working-with-feature-branches), -you should next create a feature branch to add content to your application: +Next, create a feature branch to add content to your application: 1. In your project's repository, go to the following file: `app/views/welcome/index.html.erb`. This file should only contain a paragraph: `<p>You're on Rails!</p>`. diff --git a/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md b/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md index f6a6c16e010..26902fa1168 100644 --- a/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md +++ b/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Use Auto DevOps to deploy an application to Google Kubernetes Engine **(FREE)** +# Use Auto DevOps to deploy an application to Google Kubernetes Engine **(FREE ALL)** In this tutorial, we'll help you to get started with [Auto DevOps](../index.md) through an example of how to deploy an application to Google Kubernetes Engine (GKE). @@ -182,9 +182,6 @@ The jobs are separated into stages: - Jobs suffixed with `-sast` run static analysis on the current code to check for potential security issues, and are allowed to fail ([Auto SAST](../stages.md#auto-sast)) - The `secret-detection` job checks for leaked secrets and is allowed to fail ([Auto Secret Detection](../stages.md#auto-secret-detection)) - - The `license_scanning` job searches the application's dependencies to determine each of their - licenses and is allowed to fail - ([Auto License Compliance](../stages.md#auto-license-compliance)) - **Review** - Pipelines on the default branch include this stage with a `dast_environment_deploy` job. For more information, see [Dynamic Application Security Testing (DAST)](../../../user/application_security/dast/index.md). @@ -235,8 +232,7 @@ in **Settings > CI/CD > Variables**. ### Work with branches -Following the [GitLab flow](../../gitlab_flow.md#working-with-feature-branches), -you should next create a feature branch to add content to your application: +Next, create a feature branch to add content to your application: 1. In your project's repository, go to the following file: `app/views/welcome/index.html.erb`. This file should only contain a paragraph: `<p>You're on Rails!</p>`. diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index e7fe4ce6e0b..e920ae5e5e1 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Customize Auto DevOps **(FREE)** +# Customize Auto DevOps **(FREE ALL)** You can customize components of Auto DevOps to fit your needs. For example, you can: diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index d5ebd4e9fcb..18b7c825066 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Auto DevOps **(FREE)** +# Auto DevOps **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38366) in GitLab 11.0. > - Support for the GitLab agent was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299350) in GitLab 14.5. @@ -37,7 +37,6 @@ Auto DevOps supports development during each of the [DevOps stages](stages.md). | Test | [Auto Code Intelligence](stages.md#auto-code-intelligence) | | Test | [Auto Code Quality](stages.md#auto-code-quality) | | Test | [Auto Container Scanning](stages.md#auto-container-scanning) | -| Test | [Auto License Compliance](stages.md#auto-license-compliance) | | Deploy | [Auto Review Apps](stages.md#auto-review-apps) | | Deploy | [Auto Deploy](stages.md#auto-deploy) | | Secure | [Auto Dynamic Application Security Testing (DAST)](stages.md#auto-dast) | diff --git a/doc/topics/autodevops/multiple_clusters_auto_devops.md b/doc/topics/autodevops/multiple_clusters_auto_devops.md index 1b6b5bc33c0..2cb748ab2e9 100644 --- a/doc/topics/autodevops/multiple_clusters_auto_devops.md +++ b/doc/topics/autodevops/multiple_clusters_auto_devops.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Multiple Kubernetes clusters for Auto DevOps **(FREE)** +# Multiple Kubernetes clusters for Auto DevOps **(FREE ALL)** When using Auto DevOps, you can deploy different environments to different Kubernetes clusters. diff --git a/doc/topics/autodevops/prepare_deployment.md b/doc/topics/autodevops/prepare_deployment.md index e69c0ca0909..c5a758e5d70 100644 --- a/doc/topics/autodevops/prepare_deployment.md +++ b/doc/topics/autodevops/prepare_deployment.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Prepare Auto DevOps for deployment **(FREE)** +# Prepare Auto DevOps for deployment **(FREE ALL)** If you enable Auto DevOps without setting the base domain and deployment strategy, GitLab can't deploy your application directly. Therefore, we diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index bfb88cf0dc4..47d79fcfc6b 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Requirements for Auto DevOps **(FREE)** +# Requirements for Auto DevOps **(FREE ALL)** Before enabling [Auto DevOps](index.md), we recommend you to prepare it for deployment. If you don't, you can use it to build and test your apps, and diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index 6be8a71cdbc..8d89736b56d 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Stages of Auto DevOps **(FREE)** +# Stages of Auto DevOps **(FREE ALL)** The following sections describe the stages of [Auto DevOps](index.md). Read them carefully to understand how each one works. @@ -227,7 +227,7 @@ warnings on [Ultimate](https://about.gitlab.com/pricing/) licenses. For more information, see [Secret Detection](../../user/application_security/secret_detection/index.md). -## Auto Dependency Scanning **(ULTIMATE)** +## Auto Dependency Scanning **(ULTIMATE ALL)** Dependency Scanning runs analysis on the project's dependencies and checks for potential security issues. The Auto Dependency Scanning stage is skipped on licenses other than @@ -240,20 +240,15 @@ check out. The merge request widget displays any security warnings detected, For more information, see [Dependency Scanning](../../user/application_security/dependency_scanning/index.md). -## Auto License Compliance **(ULTIMATE)** +<!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> -> Introduced in GitLab 11.0. +## Auto License Compliance (removed) **(ULTIMATE ALL)** -License Compliance uses the -[License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/analyzers/license-finder) -to search the project dependencies for their license. The Auto License Compliance stage -is skipped on licenses other than [Ultimate](https://about.gitlab.com/pricing/). +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/421363) in 16.3. +Use Auto Dependency Scanning instead. -After creating the report, it's uploaded as an artifact which you can later download and -check out. The merge request displays any detected licenses. - -For more information, see -[License Compliance](../../user/compliance/license_compliance/index.md). +<!--- end_remove --> ## Auto Container Scanning @@ -304,7 +299,7 @@ deploys with Auto DevOps can undo your changes. Also, if you change something and want to undo it by deploying again, Helm may not detect that anything changed in the first place, and thus not realize that it needs to re-apply the old configuration. -## Auto DAST **(ULTIMATE)** +## Auto DAST **(ULTIMATE ALL)** Dynamic Application Security Testing (DAST) uses the popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy) to analyze the current code @@ -345,7 +340,7 @@ You can disable DAST: - Only on feature branches by setting `REVIEW_DISABLED` variable to `"true"`. This also disables the Review App. -## Auto Browser Performance Testing **(PREMIUM)** +## Auto Browser Performance Testing **(PREMIUM ALL)** > Introduced in GitLab 10.4. @@ -366,7 +361,7 @@ file named `.gitlab-urls.txt` in the root directory, one file per line. For exam Any browser performance differences between the source and target branches are also [shown in the merge request widget](../../ci/testing/browser_performance_testing.md). -## Auto Load Performance Testing **(PREMIUM)** +## Auto Load Performance Testing **(PREMIUM ALL)** > Introduced in GitLab 13.2. diff --git a/doc/topics/autodevops/troubleshooting.md b/doc/topics/autodevops/troubleshooting.md index 21a74cca07a..11b5265b9a3 100644 --- a/doc/topics/autodevops/troubleshooting.md +++ b/doc/topics/autodevops/troubleshooting.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Troubleshooting Auto DevOps **(FREE)** +# Troubleshooting Auto DevOps **(FREE ALL)** The information in this documentation page describes common errors when using Auto DevOps, and any available workarounds. diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index 3426f8dad42..dc18f863844 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Upgrading deployments for newer Auto Deploy dependencies **(FREE)** +# Upgrading deployments for newer Auto Deploy dependencies **(FREE ALL)** [Auto Deploy](stages.md#auto-deploy) is a feature that deploys your application to a Kubernetes cluster. It consists of several dependencies: diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md index ffb72b802f7..d2410da76aa 100644 --- a/doc/topics/autodevops/upgrading_postgresql.md +++ b/doc/topics/autodevops/upgrading_postgresql.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Upgrading PostgreSQL for Auto DevOps **(FREE)** +# Upgrading PostgreSQL for Auto DevOps **(FREE ALL)** When `POSTGRES_ENABLED` is `true`, Auto DevOps provides an [in-cluster PostgreSQL database](customize.md#postgresql-database-support) for your application. diff --git a/doc/topics/build_your_application.md b/doc/topics/build_your_application.md index 48e81e26b02..02335c77b73 100644 --- a/doc/topics/build_your_application.md +++ b/doc/topics/build_your_application.md @@ -4,10 +4,23 @@ group: unassigned 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 --- -# Use CI/CD to build your application **(FREE)** +# Use CI/CD to build your application **(FREE ALL)** Add your source code to a repository, create merge requests to check in code, and use CI/CD to generate your application. Include packages in your app and output it to a variety of environments. -- [CI/CD](../ci/index.md) +- [Getting started](../ci/index.md) +- [`.gitlab-ci.yml reference`](../ci/yaml/index.md) - [Runners](https://docs.gitlab.com/runner/) +- [Pipelines](../ci/pipelines/index.md) +- [Jobs](../ci/jobs/index.md) +- [Variables](../ci/variables/index.md) +- [External secrets](../ci/secrets/index.md) +- [Services](../ci/services/index.md) +- [Auto DevOps](autodevops/index.md) +- [Testing](../ci/testing/index.md) +- [SSH keys](../ci/ssh_keys/index.md) +- [ChatOps](../ci/chatops/index.md) +- [Mobile DevOps](../ci/mobile_devops.md) +- [External repository integrations](../ci/ci_cd_for_external_repos/index.md) +- [Troubleshooting](../ci/troubleshooting.md) diff --git a/doc/topics/data_seeder.md b/doc/topics/data_seeder.md index 19c0e05d8ed..c5cf80c349d 100644 --- a/doc/topics/data_seeder.md +++ b/doc/topics/data_seeder.md @@ -9,8 +9,8 @@ description: Data Seeder test data harness created by the Test Data Working Grou GitLab Data Seeder (GDS) is a test data seeding harness, that can seed test data into a user or group namespace. -The Data Seeder uses FactoryBot in the backend which makes maintenance extremely easy. When a Model is changed, -FactoryBot will already be reflected to account for the change. +The Data Seeder uses FactoryBot in the backend which makes maintenance straightforward. When a Model changes, +FactoryBot already reflects the change. ## Docker Setup @@ -40,7 +40,7 @@ Seeding Data for Administrator #### `:name` -Where `:name` is the file name. (This will reflect relative `.rb`, `.yml`, or `.json` files located in `ee/db/seeds/data_seeder`, or absolute paths to seed files) +Where `:name` is the filename. (This name reflects relative `.rb`, `.yml`, or `.json` files located in `ee/db/seeds/data_seeder`, or absolute paths to seed files.) #### `:namespace_id` @@ -64,18 +64,18 @@ The Data Seeder uses FactoryBot definitions from `spec/factories` which ... Factories reside in `spec/factories/*` and are fixtures for Rails models found in `app/models/*`. For example, For a model named `app/models/issue.rb`, the factory will be named `spec/factories/issues.rb`. For a model named `app/models/project.rb`, the factory will be named `app/models/projects.rb`. -There are currently three parsers that the GitLab Data Seeder supports. Ruby, YAML, and JSON. +There are three parsers that the GitLab Data Seeder supports. Ruby, YAML, and JSON. ### Ruby -All Ruby Seeds must define a `DataSeeder` class with a `#seed` instance method. You may structure your Ruby class as you wish. All FactoryBot [methods](https://www.rubydoc.info/gems/factory_bot/FactoryBot/Syntax/Methods) (`create`, `build`, `create_list`) will be included in the class automatically and may be called. +All Ruby Seeds must define a `DataSeeder` class with a `#seed` instance method. You may structure your Ruby class as you wish. All FactoryBot [methods](https://www.rubydoc.info/gems/factory_bot/FactoryBot/Syntax/Methods) (`create`, `build`, `create_list`) are included in the class automatically and may be called. -The `DataSeeder` class will have the following instance variables defined upon seeding: +The `DataSeeder` class contains the following instance variables defined upon seeding: - `@seed_file` - The `File` object. - `@owner` - The owner of the seed data. -- `@name` - The name of the seed. This will be the seed file name without the extension. -- `@group` - The root group that all seeded data will be created under. +- `@name` - The name of the seed. This is the seed filename without the extension. +- `@group` - The root group that all seeded data is created under. ```ruby # frozen_string_literal: true @@ -138,10 +138,10 @@ Given: `create(:iteration, :with_title, :current, title: 'My Iteration')` ||| |:-|:-| -| **:iteration** | This is the **Name** of the factory. The file name will be the plural form of this **Name** and reside under either `spec/factories/iterations.rb` or `ee/spec/factories/iterations.rb`. | +| **:iteration** | This is the **Name** of the factory. The filename will be the plural form of this **Name** and reside under either `spec/factories/iterations.rb` or `ee/spec/factories/iterations.rb`. | | **:with_title** | This is a **Trait** of the factory. [See how it's defined](https://gitlab.com/gitlab-org/gitlab/-/blob/9c2a1f98483921dd006d70fdaed316e21fc5652f/ee/spec/factories/iterations.rb#L21-23). | | **:current** | This is a **Trait** of the factory. [See how it's defined](https://gitlab.com/gitlab-org/gitlab/-/blob/9c2a1f98483921dd006d70fdaed316e21fc5652f/ee/spec/factories/iterations.rb#L29-31). | -| **title: 'My Iteration'** | This is an **Attribute** of the factory that will be passed to the Model for creation. | +| **title: 'My Iteration'** | This is an **Attribute** of the factory that is passed to the Model for creation. | ### Examples @@ -209,7 +209,7 @@ Examples of invalid IDs: #### ActiveRecord::AssociationTypeMismatch: Model expected, got ... which is an instance of String -This is currently a limitation for the seeder. +This is a limitation for the seeder. See the issue for [allowing parsing of raw Ruby objects](https://gitlab.com/gitlab-org/gitlab/-/issues/403079). @@ -255,7 +255,7 @@ group_milestones: #### Quirks -- You _must_ specify `group:` and have it be empty. This is because the Milestones factory will manipulate the factory in an `after(:build)`. If this is not present, the Milestone will not be associated properly with the Group. +- You _must_ specify `group:` and have it be empty. This is because the Milestones factory manipulates the factory in an `after(:build)`. If this is not present, the Milestone cannot be associated properly with the Group. ### [Epics](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/spec/factories/epics.rb) diff --git a/doc/topics/git/cherry_picking.md b/doc/topics/git/cherry_picking.md index bd589562ed1..7f0da5a594e 100644 --- a/doc/topics/git/cherry_picking.md +++ b/doc/topics/git/cherry_picking.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Cherry-pick a Git commit **(FREE)** +# Cherry-pick a Git commit **(FREE ALL)** In Git, you can *cherry-pick* a commit (a set of changes) from an existing branch, and apply those changes to another branch. Cherry-picks can help you: diff --git a/doc/topics/git/git_add.md b/doc/topics/git/git_add.md index 1089202bbd3..db85e75a6a8 100644 --- a/doc/topics/git/git_add.md +++ b/doc/topics/git/git_add.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Git add **(FREE)** +# Git add **(FREE ALL)** Adds content to the index or staging area. diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md index dd2260b04dc..78275746de5 100644 --- a/doc/topics/git/git_rebase.md +++ b/doc/topics/git/git_rebase.md @@ -6,7 +6,7 @@ type: concepts, howto description: "Introduction to Git rebase and force push, methods to resolve merge conflicts through the command line." --- -# Git rebase and force push **(FREE)** +# Git rebase and force push **(FREE ALL)** This guide helps you to get started with rebases, force pushes, and fixing [merge conflicts](../../user/project/merge_requests/conflicts.md) locally. diff --git a/doc/topics/git/how_to_install_git/index.md b/doc/topics/git/how_to_install_git/index.md index f3031acf35f..40c5147e20b 100644 --- a/doc/topics/git/how_to_install_git/index.md +++ b/doc/topics/git/how_to_install_git/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: 'This article describes how to install Git on macOS, Ubuntu Linux and Windows.' --- -# Installing Git **(FREE)** +# Installing Git **(FREE ALL)** To begin contributing to GitLab projects, you must install the appropriate Git client on your computer. Information about [installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md index d5aa74935f2..05b14b21f20 100644 --- a/doc/topics/git/index.md +++ b/doc/topics/git/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: index --- -# Git **(FREE)** +# Git **(FREE ALL)** Git is a [free and open source](https://git-scm.com/about/free-and-open-source) distributed version control system designed to handle everything from small to @@ -36,7 +36,6 @@ The following resources can help you get started with Git: - Commits: - [Revert a commit](../../user/project/merge_requests/revert_changes.md#revert-a-commit) - [Cherry-picking a commit](../../user/project/merge_requests/cherry_pick_changes.md) - - [Squashing commits](../gitlab_flow.md#squashing-commits-with-rebase) - [Squash-and-merge](../../user/project/merge_requests/squash_and_merge.md) - [Signing commits](../../user/project/repository/gpg_signed_commits/index.md) - [Git stash](stash.md) @@ -82,7 +81,6 @@ If you have problems with Git, the following may help: ## Branching strategies - [Feature branch workflow](../../gitlab-basics/feature_branch_workflow.md) -- [GitLab Flow](../gitlab_flow.md) - [Git Branching - Branches in a Nutshell](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) - [Git Branching - Branching Workflows](https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows) diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 97e729aee55..d9c906ccd81 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/lfs/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Git Large File Storage (LFS) **(FREE)** +# Git Large File Storage (LFS) **(FREE ALL)** Managing large files such as audio, video and graphics files has always been one of the shortcomings of Git. The general recommendation is to not have Git repositories diff --git a/doc/topics/git/numerous_undo_possibilities_in_git/index.md b/doc/topics/git/numerous_undo_possibilities_in_git/index.md index 56223e7bcbd..8c42a394106 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Undo options in Git **(FREE)** +# Undo options in Git **(FREE ALL)** [Nothing in Git is deleted](https://git-scm.com/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery), so when you work in Git, you can undo your work. diff --git a/doc/topics/git/partial_clone.md b/doc/topics/git/partial_clone.md index de0547ae49d..add276ad49d 100644 --- a/doc/topics/git/partial_clone.md +++ b/doc/topics/git/partial_clone.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Partial clone **(FREE)** +# Partial clone **(FREE ALL)** As Git repositories grow in size, they can become cumbersome to work with because of: diff --git a/doc/topics/git/rollback_commits.md b/doc/topics/git/rollback_commits.md index d1f34c7cf9c..b86b7dbfca5 100644 --- a/doc/topics/git/rollback_commits.md +++ b/doc/topics/git/rollback_commits.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Roll back commits **(FREE)** +# Roll back commits **(FREE ALL)** ## Undo Commits diff --git a/doc/topics/git/stash.md b/doc/topics/git/stash.md index 9f621308a1d..84a09385bf6 100644 --- a/doc/topics/git/stash.md +++ b/doc/topics/git/stash.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Git stash **(FREE)** +# Git stash **(FREE ALL)** We use `git stash` to store our changes when they are not ready to be committed, but we must change to a different branch. diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md index 502acf5f7b4..43d5d746539 100644 --- a/doc/topics/git/troubleshooting_git.md +++ b/doc/topics/git/troubleshooting_git.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: howto --- -# Troubleshooting Git **(FREE)** +# Troubleshooting Git **(FREE ALL)** Sometimes things don't work the way they should or as you might expect when you're using Git. Here are some tips on troubleshooting and resolving issues diff --git a/doc/topics/git/unstage.md b/doc/topics/git/unstage.md index 3f509cdacef..028f34b2433 100644 --- a/doc/topics/git/unstage.md +++ b/doc/topics/git/unstage.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Unstage a file in Git **(FREE)** +# Unstage a file in Git **(FREE ALL)** When you _stage_ a file in Git, you instruct Git to track changes to the file in preparation for a commit. To instruct Git to disregard changes to a file, and not diff --git a/doc/topics/git/useful_git_commands.md b/doc/topics/git/useful_git_commands.md index e4c106e3e33..305008e2642 100644 --- a/doc/topics/git/useful_git_commands.md +++ b/doc/topics/git/useful_git_commands.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Frequently used Git commands **(FREE)** +# Frequently used Git commands **(FREE ALL)** The GitLab support team has collected these commands to help you. You may not need them frequently. diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index 7dd35419c76..e9feb75dd5c 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -1,559 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'https://about.gitlab.com/blog/2023/07/27/gitlab-flow-duo/' +remove_date: '2023-10-27' --- -# Introduction to Git workflows **(FREE)** +This document was moved to [another location](https://about.gitlab.com/blog/2023/07/27/gitlab-flow-duo/). -With Git, you can use a variety of branching strategies and workflows. -Having a structured workflow for collaboration in complex projects is -crucial for several reasons: - -- **Code organization**: Keep the codebase organized, prevent - overlapping work, and ensure focused efforts towards a common goal. - -- **Version control**: Allow simultaneous work on different features - without conflicts, maintaining code stability. - -- **Code quality**: A code review and approval process helps maintain high - code quality and adherence to coding standards. - -- **Traceability and accountability**: Enable tracking of changes and their authors, - simplifying issue identification and responsibility assignment. - -- **Easier onboarding**: Help new team members quickly grasp the - development process, and start contributing effectively. - -- **Time and resource management**: Enable better planning, resource - allocation, and meeting deadlines, ensuring an efficient development - process. - -- **CI/CD**: Incorporate automated testing and deployment - processes, streamlining the release cycle and delivering high-quality - software consistently. - -A structured workflow promotes organization, efficiency, and code -quality, leading to a more successful and streamlined development process. - -If the default workflow is not specifically defined, many organizations -end up with workflows that are: - -- Too complicated. -- Not clearly defined. -- Not integrated with their issue tracking systems. - -Your organization can use GitLab with any workflow you choose. - -## Workflow types - -Here are some of the most common Git workflows. - -### Centralized workflow - -Best suited for small teams transitioning from a centralized version -control system like SVN. All team members work on a single branch, -usually `main`, and push their changes directly to the central -repository. - -### Feature branch workflow - -Developers create separate branches for each feature or bugfix, -keeping the 'main' branch stable. When a feature is complete, the -developer submits a merge request to integrate the -changes back into `main` after a code review. - -### Forking workflow - -Commonly used in open-source projects, this workflow allows external -contributors to work without direct access to the main repository. -Developers create a fork (personal copy) of the main repository and -make changes in it. They then submit a merge request to have those changes -integrated into the main repository. - -### Git flow workflow - -This workflow is best for projects with a structured release cycle. -It introduces two long-lived branches: `main` for production-ready -code and `develop` for integrating features. Additional branches like -`feature`, `release`, and `hotfix` are used for specific purposes, -ensuring a strict and organized development process. - -### GitLab/GitHub flow - -A simplified workflow primarily used for web development and -continuous deployment. It combines aspects of the Feature branch -workflow and the Git flow workflow. Developers create feature branches -from `main`, and after the changes are complete, they are merged back -into the `main` branch, which is then immediately deployed. - -Each of these Git workflows has its advantages and is suited to -different project types and team structures. Below the most popular -workflows are reviewed in more details. - -## Git workflow - -Most version control systems have only one step: committing from the working copy to a shared server. - -When you convert to Git, you have to get used to the fact that it takes three steps to share a commit with colleagues. - -In Git, you add files from the working copy to the staging area. After that, you commit them to your local repository. -The third step is pushing to a shared remote repository. - -```mermaid -graph LR - subgraph Git workflow - A[Working copy] --> |git add| B[Index] - B --> |git commit| C[Local repository] - C --> |git push| D[Remote repository] - end -``` - -After getting used to these three steps, the next challenge is the branching model. - -Because many organizations new to Git have no conventions for how to work with it, their repositories can quickly become messy. -The biggest problem is that many long-running branches emerge that all contain part of the changes. -People have a hard time figuring out which branch has the latest code, or which branch to deploy to production. -Frequently, the reaction to this problem is to adopt a standardized pattern such as [Git flow](https://nvie.com/posts/a-successful-git-branching-model/) and [GitHub flow](https://scottchacon.com/2011/08/31/github-flow.html). - -We think there is still room for improvement, and so we've proposed a set of practices called the GitLab Flow. - -For a video introduction of this workflow in GitLab, see [GitLab Flow](https://youtu.be/InKNIvky2KE). - -## Problems with the Git flow - -Git flow was one of the first proposals to use Git branches, and it has received -a lot of attention. It suggests a `main` branch and a separate `develop` branch, -with supporting branches for features, releases, and hotfixes. The development -happens on the `develop` branch, moves to a release branch, and is finally merged -into the `main` branch. - -Git flow is a well-defined standard, but its complexity introduces two problems. -The first problem is that developers must use the `develop` branch and not `main`. `main` is reserved for code that is released to production. -It is a convention to call your default branch `main` and to mostly branch from and merge to this. -Because most tools automatically use the `main` branch as the default, it is annoying to have to switch to another branch. - -The second problem of Git flow is the complexity introduced by the hotfix and release branches. -These branches can be a good idea for some organizations but are overkill for the vast majority of them. -Nowadays, most organizations practice continuous delivery, which means that your default branch can be deployed. -Continuous delivery removes the need for hotfix and release branches, including all the ceremony they introduce. -An example of this ceremony is the merging back of release branches. -Though specialized tools do exist to solve this, they require documentation and add complexity. -Frequently, developers make mistakes such as merging changes only into `main` and not into the `develop` branch. -The reason for these errors is that Git flow is too complicated for most use cases. -For example, many projects do releases but don't need to do hotfixes. - -<!-- vale gitlab.Spelling = NO --> - - - -<!-- vale gitlab.Spelling = YES --> - -## GitHub flow as a simpler alternative - -In reaction to Git flow, GitHub created a simpler alternative. -[GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) has only feature branches and a `main` branch: - -```mermaid -graph TD - subgraph Feature branches in GitHub Flow - A[main branch] ===>B[main branch] - D[nav branch] --> |add navigation| B - B ===> C[main branch] - E[feature-branch] --> |add feature| C - C ==> F[main branch] - end -``` - -This flow is clean and straightforward, and many organizations have adopted it with great success. -Another way to integrate change from one branch to another is [rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing). -Merging everything into the `main` branch and frequently deploying means you minimize the amount of unreleased code. This approach is in line with lean and continuous delivery best practices. -However, this flow still leaves a lot of questions unanswered regarding deployments, environments, releases, and integrations with issues. - -## Introduction to GitLab Flow **(FREE)** - -However, if you are looking for guidance on best practices, you can use -the GitLab Flow. This workflow combines [feature-driven development](https://en.wikipedia.org/wiki/Feature-driven_development) -and [feature branches](https://martinfowler.com/bliki/FeatureBranch.html) with issue tracking. - -While this workflow used at GitLab, you can choose whichever workflow -suits your organization best. - -With GitLab Flow, we offer additional guidance for these questions. - -## Production branch with GitLab Flow - -GitHub flow assumes you can deploy to production every time you merge a feature branch. -While this is possible in some cases, such as SaaS applications, there are some cases where this is not possible, such as: - -- You don't control the timing of a release. For example, an iOS application that - is released when it passes App Store validation. -- You have deployment windows - for example, workdays from 10 AM to 4 PM when the - operations team is at full capacity - but you also merge code at other times. - -In these cases, you can create a production branch that reflects the deployed code. -You can deploy a new version by merging `main` into the `production` branch. -While not shown in the graph below, the work on the `main` branch works just like in GitHub flow: -with feature branches being merged into `main`. - -```mermaid -graph TD - subgraph Production branch in GitLab Flow - A[main branch] ==>B[development] - B ==> C[main branch] - C ==> D[main branch] - - E[production] ====> F[production] - C --> |deployment| F - D ==> G[main branch] - F ==> H[main branch] - end -``` - -If you need to know what code is in production, you can check out the production branch to see. -The approximate time of deployment is visible as the merge commit in the version control system. -This time is pretty accurate if you automatically deploy your production branch. -If you need a more exact time, you can have your deployment script create a tag on each deployment. -This flow prevents the overhead of releasing, tagging, and merging that happens with Git flow. - -## Environment branches with GitLab Flow - -It might be a good idea to have an environment that is automatically updated to the `staging` branch. -Only, in this case, the name of this environment might differ from the branch name. -Suppose you have a staging environment, a pre-production environment, and a production environment: - -```mermaid -graph LR - subgraph Environment branches in GitLab Flow - - A[staging] ==> B[staging] - B ==> C[staging] - C ==> D[staging] - - A --> |deploy to<br>pre-prod| G - - F[pre-prod] ==> G[pre-prod] - G ==> H[pre-prod] - H ==> I[pre-prod] - - C --> |deploy to<br>pre-prod| I - - J[production] ==> K[production] - K ==> L[production] - - G --> |production <br>deployment| K - - end -``` - -In this case, deploy the `staging` branch to your staging environment. -To deploy to pre-production, create a merge request from the `staging` branch to the `pre-prod` branch. -Go live by merging the `pre-prod` branch into the `production` branch. -This workflow, where commits only flow downstream, ensures that everything is tested in all environments. -To cherry-pick a commit with a hotfix, develop it on a feature branch and merge it into `production` with a merge request. -In this case, do not delete the feature branch yet. -If `production` passes automatic testing, you then merge the feature branch into the other branches. -If this is not possible because more manual testing is required, you can send merge requests from the feature branch to the downstream branches. - -## Release branches with GitLab Flow - -You should work with release branches only if you need to release software to -the outside world. In this case, each branch contains a minor version, such as -`2.3-stable` or `2.4-stable`: - -```mermaid -graph LR - A:::main ===> B((main)) - B:::main ==> C((main)) - C:::main ==> D((main)) - D:::main ==> E((main)) - - A((main)) ----> F((2.3-stable)):::first - F --> G((2.3-stable)):::first - C -.-> |cherry-pick| G - D --> H((2.4-stable)):::second - - classDef main fill:#f4f0ff,stroke:#7b58cf - classDef first fill:#e9f3fc,stroke:#1f75cb - classDef second fill:#ecf4ee,stroke:#108548 -``` - -Create stable branches using `main` as a starting point, and branch as late as possible. -By doing this, you minimize the length of time during which you have to apply bug fixes to multiple branches. -After announcing a release branch, only add serious bug fixes to the branch. -If possible, first merge these bug fixes into `main`, and then cherry-pick them into the release branch. -If you initially merged into the release branch and then forgot to cherry-pick to `main`, you'd encounter the same bug in subsequent releases. -Merging into `main` and then cherry-picking into release is called an "upstream first" policy, which is also practiced by [Google](https://www.chromium.org/chromium-os/chromiumos-design-docs/upstream-first/) and [Red Hat](https://www.redhat.com/en/blog/a-community-for-using-openstack-with-red-hat-rdo). -Every time you include a bug fix in a release branch, increase the patch version (to comply with [Semantic Versioning](https://semver.org/)) by setting a new tag. -Some projects also have a stable branch that points to the same commit as the latest released branch. -In this flow, it is not common to have a production branch (or Git flow `main` branch). - -## Merge/pull requests with GitLab Flow - - - -Merge or pull requests are created in a Git management application. They ask an assigned person to merge two branches. -Tools such as GitHub and Bitbucket choose the name "pull request", because the first manual action is to pull the feature branch. -Tools such as GitLab and others choose the name "merge request", because the final action is to merge the feature branch. -This article refers to them as merge requests. - -If you work on a feature branch for more than a few hours, share the intermediate result with the rest of your team. -To do this, create a merge request without assigning it to anyone. -Instead, mention people in the description or a comment, for example, "/cc @mark @susan." -This indicates that the merge request is not ready to be merged yet, but feedback is welcome. -Your team members can comment on the merge request in general or on specific lines with line comments. -The merge request serves as a code review tool, and no separate code review tools should be needed. -If the review reveals shortcomings, anyone can commit and push a fix. -Usually, the person to do this is the creator of the merge request. -The diff in the merge request automatically updates when new commits are pushed to the branch. -In GitLab Flow, you can configure your pipeline to run every time you commit changes to a branch. This type of pipeline is called a branch pipeline. Alternatively, you can configure your pipeline to run every time you make changes to the source branch for a merge request. This type of pipeline is called a [merge request pipeline](../ci/pipelines/merge_request_pipelines.md). In GitLab Flow, you can also take advantage of our [Review Apps](../ci/review_apps/index.md) capability, which are a collaboration tool that provide an environment to showcase product changes. Review Apps provide an automatic live preview of changes made in a feature branch by spinning up a dynamic environment for your merge requests allowing stakeholders to see your changes without needing to check out your branch and run your changes in a sandbox environment. When your changes are merged, Review Apps clean up the dynamic environment and related resources preventing environment sprawl. - -When you are ready to merge your feature branch, assign the merge request to a maintainer for the project. -Also, mention any other people from whom you would like feedback. -After the assigned person feels comfortable with the result, they can merge the branch. -In GitLab Flow, a [merged results pipeline](../ci/pipelines/merged_results_pipelines.md) runs against the results of the source and target branches merged together. -If the assigned person does not feel comfortable, they can request more changes or close the merge request without merging. - -NOTE: -In your pipelines, you can include any automated CI tests for unit, security vulnerabilities, code quality, performance, dependency, etc. Information related to the pipeline runs as well as results of tests are all displayed as widgets in the merge request window, so that you can access and visualize all these from a central location. - -In GitLab, it is common to protect the long-lived branches, such as the `main` branch, so [most developers can't modify them](../user/permissions.md). -So, if you want to merge into a protected branch, assign your merge request to someone with the -Maintainer role. - -After you merge a feature branch, you should remove it from the source control software. -In GitLab, you can do this when merging. -Removing finished branches ensures that the list of branches shows only work in progress. -It also ensures that if someone reopens the issue, they can use the same branch name without causing problems. - -NOTE: -When you reopen an issue you need to create a new merge request. - - - -## Issue tracking with GitLab Flow - -GitLab Flow is a way to make the relation between the code and the issue tracker more transparent. - -Any significant change to the code should start with an issue that describes the goal. -Having a reason for every code change helps to inform the rest of the team and to keep the scope of a feature branch small. -In GitLab, each change to the codebase starts with an issue in the issue tracking system. -If there is no issue yet, create the issue if the change requires more than an hour's work. -In many organizations, raising an issue is part of the development process because they are used in sprint planning. -The issue title should describe the desired state of the system. -For example, the issue title `As an administrator, I want to remove users without receiving an error` -is better than "Administrators can't remove users." - -When you are ready to code, create a branch for the issue from the `main` branch. -This branch is the place for any work related to this change. - -NOTE: -The name of a branch might be dictated by organizational standards. - -When you are done or want to discuss the code, open a merge request. -A merge request is an online place to discuss the change and review the code. - -If you open the merge request but do not assign it to anyone, it is a [draft merge request](../user/project/merge_requests/drafts.md). -Drafts are used to discuss the proposed implementation but are not ready for inclusion in the `main` branch yet. -Start the title of the merge request with `[Draft]`, `Draft:` or `(Draft)` to prevent it from being merged before it's ready. - -When you think the code is ready, assign the merge request to a reviewer. -The reviewer can merge the changes when they think the code is ready for inclusion in the `main` branch. -When they press the merge button, GitLab merges the code and creates a merge commit that makes this event visible later on. -Merge requests always create a merge commit, even when the branch could be merged without one. -This merge strategy is called "no fast-forward" in Git. -After the merge, delete the feature branch, because it is no longer needed. -In GitLab, this deletion is an option when merging. - -Suppose that a branch is merged but a problem occurs and the issue is reopened. -In this case, it is no problem to reuse the same branch name, because the first branch was deleted when it was merged. -At any time, there is at most one branch for every issue. -It is possible that one feature branch solves more than one issue. - -In GitLab Flow, you can create a merge request from the issue itself. When you do it this way, a feature branch and its related merge request are automatically created and associated to each other and the merge request is automatically related to the issue. In addition, when the merge request is merged the issue is automatically closed for you. - -## Linking and closing issues from merge requests - -Link to issues by mentioning them in commit messages or the description of a merge request, for example, "Fixes #16" or "Duck typing is preferred. See #12." -GitLab then creates links to the mentioned issues and creates comments in the issues linking back to the merge request. - -To automatically close linked issues, mention them with the words "fixes" or "closes," for example, "fixes #14" or "closes #67." GitLab closes these issues when the code is merged into the default branch. - -Like mentioned in the previous section, in GitLab Flow, you can create a merge request from the issue itself. When you do it this way, a feature branch and its related merge request are automatically created and associated to each other and the merge request is automatically related to the issue. In addition, when the merge request is merged the issue is automatically closed for you. - -If you have an issue that spans across multiple repositories, create an issue for each repository and link all issues to a parent issue. - -## Squashing commits with rebase - -With Git, you can use an interactive rebase (`rebase -i`) to squash multiple commits into one or reorder them. -This feature helps you replace a couple of small commits with a single commit, or if you want to make the order more logical: - -```shell -pick c6ee4d3 add a new file to the repo -pick c3c130b change readme - -# Rebase 168afa0..c3c130b onto 168afa0 -# -# Commands: -# p, pick = use commit -# r, reword = use commit, but edit the commit message -# e, edit = use commit, but stop for amending -# s, squash = use commit, but meld into previous commit -# f, fixup = like "squash", but discard this commit's log message -# x, exec = run command (the rest of the line) using shell -# -# These lines can be re-ordered; they are executed from top to bottom. -# -# If you remove a line here THAT COMMIT WILL BE LOST. -# -# However, if you remove everything, the rebase will be aborted. -# -# Note that empty commits are commented out -~ -~ -~ -"~/demo/gitlab-ce/.git/rebase-merge/git-rebase-todo" 20L, 673C -``` - -However, you should avoid rebasing commits you have pushed to a remote server if you have other active contributors in the same branch. -Because rebasing creates new commits for all your changes, it can cause confusion because the same change would have multiple identifiers. -It would cause merge errors for anyone working on the same branch because their history would not match with yours. It can be really troublesome for the author or other contributors. -Also, if someone has already reviewed your code, rebasing makes it hard to tell what changed after the last review. - -You should never rebase commits authored by other people unless you've agreed otherwise. -Not only does this rewrite history, but it also loses authorship information. -Rebasing prevents the other authors from being attributed and sharing part of the [`git blame`](https://git-scm.com/docs/git-blame). - -If a merge involves many commits, it may seem more difficult to undo. -You might consider solving this by squashing all the changes into one commit just before merging by using the GitLab [Squash-and-Merge](../user/project/merge_requests/squash_and_merge.md) feature. -Fortunately, you can undo a merge with all its commits. -The way to do this is by reverting the merge commit. -Preserving this ability to revert a merge is a good reason to always use the "no fast-forward" (`--no-ff`) strategy when you merge manually. - -NOTE: -If you revert a merge commit and then change your mind, revert the revert commit to redo the merge. -Git does not allow you to merge the code again otherwise. - -## Reducing merge commits in feature branches - -Having lots of merge commits can make your repository history messy. -Therefore, you should try to avoid merge commits in feature branches. -Often, people avoid merge commits by just using rebase to reorder their commits after the commits on the `main` branch. -Using rebase prevents a merge commit when merging `main` into your feature branch, and it creates a neat linear history. -However, as discussed in [the section about rebasing](#squashing-commits-with-rebase), you should avoid rebasing commits in a feature branch that you're sharing with others. - -Rebasing could create more work, as every time you rebase, you may need to resolve the same conflicts. -Sometimes you can reuse recorded resolutions (`rerere`), but merging is better, because you only have to resolve conflicts once. -The Git documentation has a thorough explanation of the [tradeoffs between merging and rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing#:~:text=Final%20commit%20history-,The,-Perils%20of%20Rebasing). - -A good way to prevent creating many merge commits is to not frequently merge `main` into the feature branch. -Three reasons to merge in `main`: - -1. Utilizing new code. -1. Resolving merge conflicts. -1. Updating long-running branches. - -To use some code that was introduced in `main` after you created the feature branch, cherry-pick a commit. - -If your feature branch has a merge conflict, creating a merge commit is a standard way of solving this. - -NOTE: -Sometimes you can use `.gitattributes` to reduce merge conflicts. -For example, you can set your changelog file to use the [union merge driver](https://git-scm.com/docs/gitattributes#gitattributes-union) so that multiple new entries don't conflict with each other. - -The last reason for creating merge commits is to keep long-running feature branches up-to-date with the latest state of the project. -The solution here is to keep your feature branches short-lived. -Most feature branches should take less than one day of work. -If your feature branches often take more than a day of work, try to split your features into smaller units of work. - -If you need to keep a feature branch open for more than a day, there are a few strategies to keep it up-to-date. -One option is to use continuous integration (CI) to merge in `main` at the start of the day. -Another option is to only merge in from well-defined points in time, for example, a tagged release. -You could also use [feature toggles](https://martinfowler.com/bliki/FeatureToggle.html) or [feature flags](../operations/feature_flags.md) to hide incomplete features so you can still merge back into `main` every day. - -NOTE: -Don't confuse automatic branch testing with continuous integration. -Martin Fowler makes this distinction in [an article about feature branches](https://martinfowler.com/bliki/FeatureBranch.html): -"\[People\] say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit. -That's continuous building, and a Good Thing, but there's no *integration*, so it's not CI." - -In conclusion, you should try to prevent merge commits, but not eliminate them. -Your codebase should be clean, but your history should represent what actually happened. -Developing software happens in small, messy steps, and it is OK to have your history reflect this. -You can use tools to view the network graphs of commits and understand the messy history that created your code. -If you rebase code, the commit history changes. Because of changed commit identifiers, tools can't restore the commit history. - -## Commit often and push frequently - -Another way to make your development work easier is to commit often. -Every time you have a working set of tests and code, you should make a commit. -Splitting up work into individual commits provides context for developers looking at your code later. -Smaller commits make it clear how a feature was developed. They help you roll back to a specific good point in time, or to revert one code change without reverting several unrelated changes. - -Committing often also helps you share your work, which is important so that everyone is aware of what you are working on. -You should push your feature branch frequently, even when it is not yet ready for review. -By sharing your work in a feature branch or [a merge request](#mergepull-requests-with-gitlab-flow), you prevent your team members from duplicating work. -Sharing your work before it's complete also allows for discussion and feedback about the changes. This feedback can help improve the code before it gets to review. - -## How to write a good commit message - -A commit message should reflect your intention, not just the contents of the commit. -You can see the changes in a commit, so the commit message should explain why you made those changes: - -```shell -# This commit message doesn't give enough information -git commit -m 'Improve XML generation' - -# These commit messages clearly state the intent of the commit -git commit -m 'Properly escape special characters in XML generation' -``` - -An example of a good commit message is: "Combine templates to reduce duplicate code in the user views." -The words "change," "improve," "fix," and "refactor" don't add much information to a commit message. -For more information, see Tim Pope's excellent [note about formatting commit messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). - -To add more context to a commit message, consider adding information regarding the -origin of the change, such the GitLab issue URL or Jira issue number. That way, you provide -more information for users who need in-depth context about the change. - -For example: - -```plaintext -Properly escape special characters in XML generation. - -Issue: gitlab.com/gitlab-org/gitlab/-/issues/1 -``` - -## Testing before merging - -In old workflows, the continuous integration (CI) server commonly ran tests on the `main` branch only. -Developers had to ensure their code did not break the `main` branch. -When using GitLab Flow, developers create their branches from this `main` branch, so it is essential that it never breaks. -Therefore, each merge request must be tested before it is accepted. -CI software like GitLab CI/CD shows the build results right in the merge request itself to simplify the process. - -There is one drawback to testing merge requests: the CI server only tests the feature branch itself, not the merged result. -Ideally, the server could also test the `main` branch after each change. -However, retesting on every commit to `main` is computationally expensive and means you are more frequently waiting for test results. -Because feature branches should be short-lived, testing just the branch is an acceptable risk. -If new commits in `main` cause merge conflicts with the feature branch, merge `main` back into the branch to make the CI server re-run the tests. -As said before, if you often have feature branches that last for more than a few days, you should make your issues smaller. - -In GitLab Flow, your can include automated CI tests in your branch or merge request pipelines, which can run when you commit changes to a branch. - -## Working with feature branches - -Some tips for working with feature branches: - -- When you create a feature branch locally, always update your local copy of `main` before - branching off from it. -- When creating a feature branch, always branch from `main` unless you know your work - depends on some other branch. For example, to create `feature-x-update`, branch from - `feature-x` instead of `main`. -- If you merge in another branch after starting, explain the reason in the merge commit. -- If you have not pushed your branch upstream yet, you can still pull in new changes - by rebasing your local feature branch against your local copy of its parent branch. -- Do not merge recent changes from other branches into your local feature branch if your code - can work and merge cleanly without those extra changes. Each time you merge commits into your - feature branch, you add a merge commit to your feature branch. These merge commits - later end up littering the history in your `main` branch. +<!-- This redirect file can be deleted after <2023-10-27>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/topics/img/gitlab_flow_gitdashflow.png b/doc/topics/img/gitlab_flow_gitdashflow.png Binary files differdeleted file mode 100644 index 65900853d84..00000000000 --- a/doc/topics/img/gitlab_flow_gitdashflow.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_mr_inline_comments.png b/doc/topics/img/gitlab_flow_mr_inline_comments.png Binary files differdeleted file mode 100644 index a18801f56e4..00000000000 --- a/doc/topics/img/gitlab_flow_mr_inline_comments.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_remove_checkbox.png b/doc/topics/img/gitlab_flow_remove_checkbox.png Binary files differdeleted file mode 100644 index fb0e792b37b..00000000000 --- a/doc/topics/img/gitlab_flow_remove_checkbox.png +++ /dev/null diff --git a/doc/topics/manage_code.md b/doc/topics/manage_code.md index 136e471d14a..0f1bfc73b27 100644 --- a/doc/topics/manage_code.md +++ b/doc/topics/manage_code.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/product/ux/technical-writing/#assignments --- -# Manage your code **(FREE)** +# Manage your code **(FREE ALL)** -Store your source files in a repository, and make changes to them by using merge requests. +Store your source files in a repository and create merge requests. Write, debug, and compile code hosted on GitLab. - [Repositories](../user/project/repository/index.md) - [Merge requests](../user/project/merge_requests/index.md) +- [Remote development](../user/project/remote_development/index.md) diff --git a/doc/topics/offline/quick_start_guide.md b/doc/topics/offline/quick_start_guide.md index dd739fdaf77..82a88b53dcf 100644 --- a/doc/topics/offline/quick_start_guide.md +++ b/doc/topics/offline/quick_start_guide.md @@ -215,15 +215,22 @@ On offline instances, the [GitLab Geo check Rake task](../../administration/geo/ always fails because it uses `pool.ntp.org`. This error can be ignored but you can [read more about how to work around it](../../administration/geo/replication/troubleshooting.md#message-machine-clock-is-synchronized--exception). -## Enabling the package metadata database +## Enabling the Package Metadata Database -Enabling the package metadata database is required to enable [license scanning of CycloneDX files](../../user/compliance/license_scanning_of_cyclonedx_files). -This process requires usage of the GitLab License Database, which is licensed under the [EE License](https://storage.googleapis.com/prod-export-license-bucket-1a6c642fc4de57d4/v1/LICENSE). -Note the following in relation to use of the License Database: +Enabling the Package Metadata Database is required to enable [license scanning of CycloneDX files](../../user/compliance/license_scanning_of_cyclonedx_files). +This process requires the use of License and/or Advisory Data under what is collectively called the Package Metadata Database, which is licensed under the [EE License](https://storage.googleapis.com/prod-export-license-bucket-1a6c642fc4de57d4/LICENSE). +Note the following in relation to use of the Package Metadata Database: -- We may change or discontinue all or any part of the License Database, at any time and without notice, at our sole discretion. -- The License Database may contain links to third-party websites or resources. We provide these links only as a convenience and are not responsible for any third-party data, content, products, or services from those websites or resources or links displayed on such websites. -- The License Database is based in part on information made available by third parties, and GitLab is not responsible for the accuracy or completeness of content made available. +- We may change or discontinue all or any part of the Package Metadata Database, at any time and without notice, at our sole discretion. +- The Package Metadata Database may contain links to third-party websites or resources. We provide these links only as a convenience and are not responsible for any third-party data, content, products, or services from those websites or resources or links displayed on such websites. +- The Package Metadata Database is based in part on information made available by third parties, and GitLab is not responsible for the accuracy or completeness of content made available. + +Enabling the Package Metadata Database is also required to enable Continuous Vulnerability Scans for Dependency Scanning (see [epic 9534](https://gitlab.com/groups/gitlab-org/-/epics/9534) tracking this work for more info). + +Package metadata is stored in the following Google Cloud Provider (GCP) buckets: + +- License Scanning - prod-export-license-bucket-1a6c642fc4de57d4 +- Dependency Scanning - prod-export-advisory-bucket-1a6c642fc4de57d4 ### Using the gsutil tool to download the package metadata exports @@ -235,34 +242,58 @@ Note the following in relation to use of the License Database: echo $GITLAB_RAILS_ROOT_DIR ``` +1. Set the type of data you wish to sync. + + ```shell + # For License Scanning + export PKG_METADATA_BUCKET=prod-export-license-bucket-1a6c642fc4de57d4 + export DATA_DIR="licenses" + + # For Dependency Scanning + export PKG_METADATA_BUCKET=prod-export-advisory-bucket-1a6c642fc4de57d4 + export DATA_DIR="advisories" + ``` + 1. Download the package metadata exports. ```shell # To download the package metadata exports, an outbound connection to Google Cloud Storage bucket must be allowed. - mkdir $GITLAB_RAILS_ROOT_DIR/vendor/package_metadata_db/ - gsutil -m rsync -r -d gs://prod-export-license-bucket-1a6c642fc4de57d4 $GITLAB_RAILS_ROOT_DIR/vendor/package_metadata_db/ + mkdir -p "$GITLAB_RAILS_ROOT_DIR/vendor/package_metadata/$DATA_DIR" + gsutil -m rsync -r -d gs://$PKG_METADATA_BUCKET "$GITLAB_RAILS_ROOT_DIR/vendor/package_metadata/$DATA_DIR" # Alternatively, if the GitLab instance is not allowed to connect to the Google Cloud Storage bucket, the package metadata # exports can be downloaded using a machine with the allowed access, and then copied to the root of the GitLab Rails directory. - rsync rsync://example_username@gitlab.example.com/package_metadata_db $GITLAB_RAILS_ROOT_DIR/vendor/package_metadata_db/ + rsync rsync://example_username@gitlab.example.com/package_metadata/$DATA_DIR "$GITLAB_RAILS_ROOT_DIR/vendor/package_metadata/$DATA_DIR" ``` ### Using the Google Cloud Storage REST API to download the package metadata exports -The package metadata exports can also be downloaded using the Google Cloud Storage API. The contents are available at [https://storage.googleapis.com/storage/v1/b/prod-export-license-bucket-1a6c642fc4de57d4/o](https://storage.googleapis.com/storage/v1/b/prod-export-license-bucket-1a6c642fc4de57d4/o). The following is an example of how this can be downloaded using [cURL](https://curl.se/) and [jq](https://stedolan.github.io/jq/). +The package metadata exports can also be downloaded using the Google Cloud Storage API. The contents are available at [https://storage.googleapis.com/storage/v1/b/prod-export-license-bucket-1a6c642fc4de57d4/o](https://storage.googleapis.com/storage/v1/b/prod-export-license-bucket-1a6c642fc4de57d4/o) and [https://storage.googleapis.com/storage/v1/b/prod-export-advisory-bucket-1a6c642fc4de57d4/o](https://storage.googleapis.com/storage/v1/b/prod-export-advisory-bucket-1a6c642fc4de57d4/o). The following is an example of how this can be downloaded using [cURL](https://curl.se/) and [jq](https://stedolan.github.io/jq/). ```shell #!/bin/bash set -euo pipefail +DATA_TYPE=$1 + GITLAB_RAILS_ROOT_DIR="$(gitlab-rails runner 'puts Rails.root.to_s')" -PKG_METADATA_DIR="$GITLAB_RAILS_ROOT_DIR/vendor/package_metadata_db" -PKG_METADATA_MANIFEST_OUTPUT_FILE="/tmp/license_db_export_manifest.json" -PKG_METADATA_DOWNLOADS_OUTPUT_FILE="/tmp/license_db_object_links.tsv" + +if [ "$DATA_TYPE" == "license" ]; then + PKG_METADATA_DIR="$GITLAB_RAILS_ROOT_DIR/vendor/package_metadata/licenses" +elif [ "$DATA_TYPE" == "advisory" ]; then + PKG_METADATA_DIR="$GITLAB_RAILS_ROOT_DIR/vendor/package_metadata/advisories" +else + echo "Usage: import_script.sh [licenses|advisories]" + exit 1 +fi + +PKG_METADATA_BUCKET="prod-export-$DATA_TYPE-bucket-1a6c642fc4de57d4" +PKG_METADATA_MANIFEST_OUTPUT_FILE="/tmp/package_metadata_${DATA_TYPE}_export_manifest.json" +PKG_METADATA_DOWNLOADS_OUTPUT_FILE="/tmp/package_metadata_${DATA_TYPE}_object_links.tsv" # Download the contents of the bucket -curl --silent --show-error --request GET "https://storage.googleapis.com/storage/v1/b/prod-export-license-bucket-1a6c642fc4de57d4/o?maxResults=7500" > "$PKG_METADATA_MANIFEST_OUTPUT_FILE" +curl --silent --show-error --request GET "https://storage.googleapis.com/storage/v1/b/$PKG_METADATA_BUCKET/o?maxResults=7500" > "$PKG_METADATA_MANIFEST_OUTPUT_FILE" # Parse the links and names for the bucket objects and output them into a tsv file jq -r '.items[] | [.name, .mediaLink] | @tsv' "$PKG_METADATA_MANIFEST_OUTPUT_FILE" > "$PKG_METADATA_DOWNLOADS_OUTPUT_FILE" @@ -294,9 +325,29 @@ echo "All objects saved to $PKG_METADATA_DIR" ### Automatic synchronization -Your GitLab instance is synchronized [every hour](https://gitlab.com/gitlab-org/gitlab/-/blob/d4331343d26d6e2a81fadd8f7ecd72f7cb74d04d/config/initializers/1_settings.rb#L831-832) with the contents of the `package_metadata_db` directory. +Your GitLab instance is synchronized [regularly](https://gitlab.com/gitlab-org/gitlab/-/blob/63a187d47f6da353ba4514650bbbbeb99c356325/config/initializers/1_settings.rb#L840-842) with the contents of the `package_metadata` directory. To automatically update your local copy with the upstream changes, a cron job can be added to periodically download new exports. For example, the following crontabs can be added to setup a cron job that runs every 30 minutes. +For License Scanning: + +```plaintext +*/30 * * * * gsutil -m rsync -r -d gs://prod-export-license-bucket-1a6c642fc4de57d4 $GITLAB_RAILS_ROOT_DIR/vendor/package_metadata/licenses +``` + +For Dependency Scanning: + ```plaintext -*/30 * * * * gsutil -m rsync -r -d gs://prod-export-license-bucket-1a6c642fc4de57d4 $GITLAB_RAILS_ROOT_DIR/vendor/package_metadata_db/ +*/30 * * * * gsutil -m rsync -r -d gs://prod-export-advisory-bucket-1a6c642fc4de57d4 $GITLAB_RAILS_ROOT_DIR/vendor/package_metadata/advisories ``` + +### Change note + +The directory for package metadata changed with the release of 16.2 from `vendor/package_metadata_db` to `vendor/package_metadata/licenses`. If this directory already exists on the instance and Dependency Scanning needs to be added then you need to take the following steps. + +1. Rename the licenses directory: `mv vendor/package_metadata_db vendor/package_metadata/licenses`. +1. Update any automation scripts or commands saved to change `vendor/package_metadata_db` to `vendor/package_metadata/licenses`. +1. Update any cron entries to change `vendor/package_metadata_db` to `vendor/package_metadata/licenses`. + + ```shell + sed -i '.bckup' -e 's#vendor/package_metadata_db#vendor/package_metadata/licenses#g' [FILE ...] + ``` diff --git a/doc/topics/plan_and_track.md b/doc/topics/plan_and_track.md index 67d5e996837..2ad46799316 100644 --- a/doc/topics/plan_and_track.md +++ b/doc/topics/plan_and_track.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/product/ux/technical-writing/#assignments --- -# Plan and track work **(FREE)** +# Plan and track work **(FREE ALL)** Plan your work by creating requirements, issues, and epics. Schedule work with milestones and track your team's time. Learn how to save time with @@ -54,7 +54,7 @@ Align your work across teams. Use these day-to-day planning features. -- [Your work sidebar](../topics/your_work.md) +- [Your work sidebar](../tutorials/left_sidebar/index.md) - [Keyboard shortcuts](../user/shortcuts.md) - [Quick actions](../user/project/quick_actions.md) - [Markdown](../user/markdown.md) diff --git a/doc/topics/release_your_application.md b/doc/topics/release_your_application.md index 3cc5e9a66b3..e0580d52765 100644 --- a/doc/topics/release_your_application.md +++ b/doc/topics/release_your_application.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Deploy and release your application **(FREE)** +# Deploy and release your application **(FREE ALL)** Deployment is the step of the software delivery process when your application gets deployed to its final, target infrastructure. @@ -28,7 +28,6 @@ release features incrementally. - [Auto Deploy](autodevops/stages.md#auto-deploy) is the DevOps stage dedicated to software deployment using GitLab CI/CD. Auto Deploy has built-in support for EC2 and ECS deployments. - Deploy to Kubernetes clusters by using the [GitLab agent](../user/clusters/agent/install/index.md). -- View an example of [how to structure a GitOps deployment repository](../user/clusters/agent/gitops/example_repository_structure.md). - Use Docker images to run AWS commands from GitLab CI/CD, and a template to facilitate [deployment to AWS](../ci/cloud_deployment). - Use GitLab CI/CD to target any type of infrastructure accessible by GitLab Runner. diff --git a/doc/topics/set_up_organization.md b/doc/topics/set_up_organization.md index cf0a0ae4ab7..a8498ff970c 100644 --- a/doc/topics/set_up_organization.md +++ b/doc/topics/set_up_organization.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Set up your organization **(FREE)** +# Set up your organization **(FREE ALL)** Configure your organization and its users. Determine user roles and give everyone access to the projects they need. diff --git a/doc/topics/your_work.md b/doc/topics/your_work.md deleted file mode 100644 index c57c9b52604..00000000000 --- a/doc/topics/your_work.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../tutorials/left_sidebar/index.md' -remove_date: '2023-08-03' ---- - -This document was moved to [another location](../tutorials/left_sidebar/index.md). - -<!-- This redirect file can be deleted after <2023-08-03>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/tutorials/agile_sprint.md b/doc/tutorials/agile_sprint.md deleted file mode 100644 index 84927fe0a66..00000000000 --- a/doc/tutorials/agile_sprint.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'agile_sprint/index.md' -remove_date: '2023-07-21' ---- - -This document was moved to [another location](agile_sprint/index.md). - -<!-- This redirect file can be deleted after 2023-07-21. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/tutorials/agile_sprint/index.md b/doc/tutorials/agile_sprint/index.md index fe106af2dc2..ea4234b118f 100644 --- a/doc/tutorials/agile_sprint/index.md +++ b/doc/tutorials/agile_sprint/index.md @@ -32,7 +32,7 @@ Membership automatically cascades down to all subgroups and projects. ## Create a project -Now [create one or more projects](../../user/project/index.md#create-a-project) in your group. +Now [create one or more projects](../../user/project/index.md) in your group. There are several different ways to create a project. A project contains your code and pipelines, but also the issues that are used for planning your upcoming code changes. @@ -47,9 +47,7 @@ When creating an iteration cadence, you can decide whether to automatically mana disable the automated scheduling to [manually manage the iterations](../../user/group/iterations/index.md#manual-iteration-management). -Similar to membership, iterations cascade down your group, subgroup, and project hierarchy. If your -team works across many groups, subgroups, and projects, create the iteration cadence in the top-most -group shared by all projects that contain the team's issues as illustrated by the diagram below. +Similar to membership, iterations cascade down your group, subgroup, and project hierarchy. If your team has multiple groups and projects, create the iteration cadence in the top-most shared group: ```mermaid graph TD diff --git a/doc/tutorials/boards_for_teams/index.md b/doc/tutorials/boards_for_teams/index.md index 4e0e50971d3..c316e42d218 100644 --- a/doc/tutorials/boards_for_teams/index.md +++ b/doc/tutorials/boards_for_teams/index.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/product/ux/technical-writing/#assignments --- -# Tutorial: Set up issue boards for team hand-off **(PREMIUM)** +# Tutorial: Set up issue boards for team hand-off **(PREMIUM ALL)** <!-- vale gitlab.FutureTense = NO --> @@ -82,7 +82,8 @@ Prerequisites: To create a blank project: -1. In your group, on the right of the page, select **New project**. +1. In your group, on the left sidebar, at the top, select **Create new** (**{plus}**) and then select + **In this group > New project/repository**. 1. Select **Create blank project**. 1. Enter the project details: - In the **Project name** field, name your project `Paperclip Assistant`. @@ -170,7 +171,7 @@ To create an issue from your board: 1. In the upper-left corner of the issue board page, select the dropdown list with the current board name. 1. Select **UX workflow**. -1. On the `Workflow::Ready for development` list, select **List actions** (**{ellipsis_v}**) **> Create new issue**. +1. On the `Workflow::Ready for development` list, select **Create new issue** (**{plus}**). 1. Complete the fields: 1. Under **Title**, enter `Redesign user profile page`. 1. Under **Projects**, select **Paperclip Software Factory / Paperclip Assistant**. diff --git a/doc/tutorials/build_application.md b/doc/tutorials/build_application.md index 8e53f1ccc6b..c22cba7e0e8 100644 --- a/doc/tutorials/build_application.md +++ b/doc/tutorials/build_application.md @@ -28,6 +28,7 @@ Set up runners to run jobs in a pipeline. | Topic | Description | Good for beginners | |-------|-------------|--------------------| +| [Create, register, and run your own project runner](create_register_first_runner/index.md) | Learn the basics of how to create and register a project runner that runs jobs for your project. | **{star}** | | [Configure GitLab Runner to use the Google Kubernetes Engine](configure_gitlab_runner_to_use_gke/index.md) | Learn how to configure GitLab Runner to use the GKE to run jobs. | | ## Publish a static website @@ -38,4 +39,4 @@ Use GitLab Pages to publish a static website directly from your project. |-------|-------------|--------------------| | [Create a Pages website from a CI/CD template](../user/project/pages/getting_started/pages_ci_cd_template.md) | Quickly generate a Pages website for your project using a CI/CD template for a popular Static Site Generator (SSG). | **{star}** | | [Create a Pages website from scratch](../user/project/pages/getting_started/pages_from_scratch.md) | Create all the components of a Pages website from a blank project. | | -| [Build, test, and deploy your Hugo site with GitLab](/ee/tutorials/hugo/index.md) | Generate your Hugo site using a CI/CD template and GitLab Pages. | **{star}** | +| [Build, test, and deploy your Hugo site with GitLab](../tutorials/hugo/index.md) | Generate your Hugo site using a CI/CD template and GitLab Pages. | **{star}** | diff --git a/doc/tutorials/compliance_pipeline/index.md b/doc/tutorials/compliance_pipeline/index.md index 9cf8148fe40..5396248d05a 100644 --- a/doc/tutorials/compliance_pipeline/index.md +++ b/doc/tutorials/compliance_pipeline/index.md @@ -4,7 +4,7 @@ group: Compliance info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- -# Tutorial: Create a compliance pipeline **(ULTIMATE)** +# Tutorial: Create a compliance pipeline **(ULTIMATE ALL)** You can use [compliance pipelines](../../user/group/compliance_frameworks.md#compliance-pipelines) to ensure specific compliance-related jobs are run on pipelines for all projects in a group. Compliance pipelines are applied diff --git a/doc/tutorials/configure_gitlab_runner_to_use_gke/index.md b/doc/tutorials/configure_gitlab_runner_to_use_gke/index.md index 05340994edf..d9a6dbbb3f0 100644 --- a/doc/tutorials/configure_gitlab_runner_to_use_gke/index.md +++ b/doc/tutorials/configure_gitlab_runner_to_use_gke/index.md @@ -4,7 +4,7 @@ group: Runner 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 --- -# Tutorial: Configure GitLab Runner to use the Google Kubernetes Engine **(FREE)** +# Tutorial: Configure GitLab Runner to use the Google Kubernetes Engine **(FREE ALL)** This tutorial describes how to configure GitLab Runner to use the Google Kubernetes Engine (GKE) to run jobs. @@ -64,7 +64,7 @@ and, for autopilot clusters, to add configurations that specify which jobs to ru 1. Verify that you are connected to the cluster: ```shell - kubectl config view current-context + kubectl config current-context ``` ## Install and configure the Kubernetes Operator @@ -74,7 +74,7 @@ Now that you have a cluster, you're ready to install and configure the Kubernete 1. Install the prerequisites: ```shell - kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.7.1/cert-manager.yaml + kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.7.1/cert-manager.yaml ``` 1. Install the Operator Lifecycle Manager (OLM), a tool that manages the Kubernetes Operators that diff --git a/doc/tutorials/container_scanning/index.md b/doc/tutorials/container_scanning/index.md index 711ed359e89..d1966cbb788 100644 --- a/doc/tutorials/container_scanning/index.md +++ b/doc/tutorials/container_scanning/index.md @@ -4,7 +4,7 @@ group: Composition Analysis info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- -# Tutorial: Scan a Docker container for vulnerabilities **(FREE)** +# Tutorial: Scan a Docker container for vulnerabilities **(FREE ALL)** You can use [container scanning](../../user/application_security/container_scanning/index.md) to check for vulnerabilities in container images stored in the [container registry](../../user/packages/container_registry/index.md). diff --git a/doc/tutorials/convert_personal_namespace_into_group.md b/doc/tutorials/convert_personal_namespace_into_group.md deleted file mode 100644 index c1b3b58efb8..00000000000 --- a/doc/tutorials/convert_personal_namespace_into_group.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'convert_personal_namespace_to_group/index.md' -remove_date: '2023-07-21' ---- - -This document was moved to [another location](convert_personal_namespace_to_group/index.md). - -<!-- This redirect file can be deleted after 2023-07-21. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/tutorials/create_compliance_pipeline.md b/doc/tutorials/create_compliance_pipeline.md deleted file mode 100644 index ac5550ad6a4..00000000000 --- a/doc/tutorials/create_compliance_pipeline.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'compliance_pipeline/index.md' -remove_date: '2023-07-21' ---- - -This document was moved to [another location](compliance_pipeline/index.md). - -<!-- This redirect file can be deleted after 2023-07-21. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/tutorials/create_register_first_runner/index.md b/doc/tutorials/create_register_first_runner/index.md new file mode 100644 index 00000000000..05bf5cd8288 --- /dev/null +++ b/doc/tutorials/create_register_first_runner/index.md @@ -0,0 +1,167 @@ +--- +stage: Verify +group: Runner +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 +--- + +# Tutorial: Create, register, and run your own project runner **(FREE ALL)** + +This tutorial shows you how to configure and run your first runner in GitLab. + +A runner is an agent in the GitLab Runner application that runs jobs in a GitLab CI/CD pipeline. +Jobs are defined in the `.gitlab-ci.yml` file and assigned to available runners. + +GitLab has three types of runners: + +- Shared: Available to all groups and projects in a GitLab instance. +- Group: Available to all projects and subgroups in a group. +- Project: Associated with specific projects. Typically, project runners are used by one project at a time. + +For this tutorial, you'll create a project runner to run jobs defined in a basic pipeline +configuration: + +1. [Create a blank project](#create-a-blank-project) +1. [Create a project pipeline](#create-a-project-pipeline). +1. [Create and register a project runner](#create-and-register-a-project-runner). +1. [Trigger a pipeline to run your runner](#trigger-a-pipeline-to-run-your-runner). + +## Prerequisite + +Before you can create, register, and run a runner, [GitLab Runner](https://docs.gitlab.com/runner/install/) must be installed on a local computer. + +## Create a blank project + +First, create a blank project where you can create your CI/CD pipeline and runner. + +To create a blank project: + +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. +1. Select **Create blank project**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. +1. Select **Create project**. + +## Create a project pipeline + +Next, create a `.gitlab-ci.yml` file for your project. This is a YAML file where you specify instructions for GitLab CI/CD. + +In this file, you define: + +- The structure and order of jobs that the runner should execute. +- The decisions the runner should make when specific conditions are encountered. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Project overview**. +1. Select the plus icon (**{plus}**), then select **New file**. +1. In the **Filename** field, enter `.gitlab-ci.yml`. +1. In the large text box, paste this sample configuration: + + ```yaml + stages: + - build + - test + + job_build: + stage: build + script: + - echo "Building the project" + + job_test: + stage: test + script: + - echo "Running tests" + ``` + + In this configuration there are two jobs that the runner runs: a build job and a test job. +1. Select **Commit changes**. + +## Create and register a project runner + +Next, create a project runner and register it. You must register the runner to link it +to GitLab so that it can pick up jobs from the project pipeline. + +To create a project runner: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > CI/CD**. +1. Expand the **Runners** section. +1. Select **New project runner**. +1. Select your operating system. +1. In the **Tags** section, select the **Run untagged** checkbox. [Tags](../../ci/runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) specify which jobs + the runner can run and are optional. +1. Select **Create runner**. +1. Follow the on-screen instructions to register the runner from the command line. When prompted: + - For `executor`, because your runner will run directly on the host computer, enter `shell`. The [executor](https://docs.gitlab.com/runner/executors/) + is the environment where the runner executes the job. + - For `GitLab instance URL`, use the URL for your GitLab instance. For example, if your project + is hosted on `gitlab.example.com/yourname/yourproject`, then your GitLab instance URL is `https://gitlab.example.com`. + If your project is hosted on GitLab.com, the URL is `https://gitlab.com`. +1. Start your runner: + + ```shell + gitlab-runner run + ``` + +### Check the runner configuration file + +After you register the runner, the configuration and authentication token is saved to your `config.toml`. The runner uses the +token to authenticate with GitLab when picking up jobs from the job queue. + +You can use the `config.toml` to +define more [advanced runner configurations](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). + +Here's what your `config.toml` should look like after you register and start the runner: + +```toml + [[runners]] + name = "my-project-runner1" + url = "http://127.0.0.1:3000" + id = 38 + token = "glrt-TOKEN" + token_obtained_at = 2023-07-05T08:56:33Z + token_expires_at = 0001-01-01T00:00:00Z + executor = "shell" +``` + +## Trigger a pipeline to run your runner + +Next, trigger a pipeline in your project so you can view your runner execute a job. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Build > Pipelines**. +1. Select **Run pipeline**. +1. Select a job to view the job log. The output should look similar to this example, which shows + your runner successfully executing the job: + + ```shell + Running with gitlab-runner 16.2.0 (782e15da) + on my-project-runner TOKEN, system ID: SYSTEM ID + Preparing the "shell" executor + 00:00 + Using Shell (bash) executor... + Preparing environment + 00:00 + /Users/username/.bash_profile: line 9: setopt: command not found + Running on MACHINE-NAME... + Getting source from Git repository + 00:01 + /Users/username/.bash_profile: line 9: setopt: command not found + Fetching changes with git depth set to 20... + Reinitialized existing Git repository in /Users/username/project-repository + Checking out 7226fc70 as detached HEAD (ref is main)... + Skipping object checkout, Git LFS is not installed for this repository. + Consider installing it with 'git lfs install'. + Skipping Git submodules setup + Executing "step_script" stage of the job script + 00:00 + /Users/username/.bash_profile: line 9: setopt: command not found + $ echo "Building the project" + Building the project + Job succeeded + + ``` + +You have now successfully created, registered, and run your first runner! diff --git a/doc/tutorials/fuzz_testing/index.md b/doc/tutorials/fuzz_testing/index.md index f51f7cdb427..e4c494e9b85 100644 --- a/doc/tutorials/fuzz_testing/index.md +++ b/doc/tutorials/fuzz_testing/index.md @@ -4,7 +4,7 @@ group: Dynamic Analysis 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 --- -# Tutorial: Perform fuzz testing in GitLab **(ULTIMATE)** +# Tutorial: Perform fuzz testing in GitLab **(ULTIMATE ALL)** [Coverage-guided fuzz testing](../../user/application_security/coverage_fuzzing/index.md#coverage-guided-fuzz-testing-process) sends unexpected, malformed, or random data to your application, and then monitors your application for unstable behaviors and crashes. diff --git a/doc/tutorials/fuzz_testing_tutorial.md b/doc/tutorials/fuzz_testing_tutorial.md deleted file mode 100644 index 74b24005077..00000000000 --- a/doc/tutorials/fuzz_testing_tutorial.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'fuzz_testing/index.md' -remove_date: '2023-07-21' ---- - -This document was moved to [another location](fuzz_testing/index.md). - -<!-- This redirect file can be deleted after 2023-07-21. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/tutorials/infrastructure.md b/doc/tutorials/infrastructure.md index 688a1a1f7c7..ee4fc748c0e 100644 --- a/doc/tutorials/infrastructure.md +++ b/doc/tutorials/infrastructure.md @@ -13,3 +13,5 @@ configure the infrastructure for your application. |-------|-------------|--------------------| | [Use GitOps with GitLab](https://about.gitlab.com/blog/2022/04/07/the-ultimate-guide-to-gitops-with-gitlab/) | Learn how to provision and manage a base infrastructure, connect to a Kubernetes cluster, deploy third-party applications, and carry out other infrastructure automation tasks. | | | [Set up Flux for GitOps](../user/clusters/agent/gitops/flux_tutorial.md) | Learn how to set up Flux for GitOps in a sample project. | | +| [Deploy a Git repository using Flux](../user/clusters/agent/gitops/example_repository_structure.md) | Learn how to organize a GitLab project for GitOps. | | +| [Deploy an OCI artifact using Flux](../user/clusters/agent/gitops/flux_oci_tutorial.md) | Learn how to package and deploy your Kubernetes manifests as an OCI artifact. | | diff --git a/doc/tutorials/install_gitlab_single_node/index.md b/doc/tutorials/install_gitlab_single_node/index.md new file mode 100644 index 00000000000..5ed98ccbefc --- /dev/null +++ b/doc/tutorials/install_gitlab_single_node/index.md @@ -0,0 +1,435 @@ +--- +stage: Systems +group: Distribution +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 +--- + +# Tutorial: Install and secure a single node GitLab instance **(FREE SELF)** + +In this tutorial you will learn how to install and securely configure a single +node GitLab instance that can accommodate up to +[1,000 users](../../administration/reference_architectures/1k_users.md). + +To install a single node GitLab instance and configure it to be secure: + +1. [Secure the server](#secure-the-server) +1. [Install GitLab](#install-gitlab) +1. [Configure GitLab](#configure-gitlab) +1. [Next steps](#next-steps) + +## Prerequisites + +- A domain name, and a correct [setup of DNS](https://docs.gitlab.com/omnibus/settings/dns.html). +- A Debian-based server with the following minimum specs: + - 8 vCPU + - 7.2 GB memory + - Enough hard drive space for all your repositories. + Read more about the + [storage requirements](../../install/requirements.md). + +## Secure the server + +Before installing GitLab, start by configuring your server to be a bit more secure. + +### Configure the firewall + +You need to open ports 22 (SSH), 80 (HTTP), and 443 (HTTPS). You can do this by +either using your cloud provider's console, or at the server level. + +In this example, you'll configure the firewall using [`ufw`](https://wiki.ubuntu.com/UncomplicatedFirewall). +You'll deny access to all ports, allow ports 80 and 443, and finally, rate limit access to port 22. +`ufw` can deny connections from an IP address that has attempted to initiate 6 or more +connections in the last 30 seconds. + +1. Install `ufw`: + + ```shell + sudo apt install ufw + ``` + +1. Enable and start the `ufw` service: + + ```shell + sudo systemctl enable --now ufw + ``` + +1. Deny all other ports except the required ones: + + ```shell + sudo ufw default deny + sudo ufw allow http + sudo ufw allow https + sudo ufw limit ssh/tcp + ``` + +1. Finally, activate the settings. The following needs to run only once, the first time + you install the package. Answer yes (`y`) when prompted: + + ```shell + sudo ufw enable + ``` + +1. Verify that the rules are present: + + ```shell + $ sudo ufw status + + Status: active + + To Action From + -- ------ ---- + 80/tcp ALLOW Anywhere + 443 ALLOW Anywhere + 22/tcp LIMIT Anywhere + 80/tcp (v6) ALLOW Anywhere (v6) + 443 (v6) ALLOW Anywhere (v6) + 22/tcp (v6) LIMIT Anywhere (v6) + ``` + +### Configure the SSH server + +To further secure your server, configure SSH to accept public key authentication, +and disable some features that are potential security risks. + +1. Open `/etc/ssh/sshd_config` with your editor and make sure the following are present: + + ```plaintext + PubkeyAuthentication yes + PasswordAuthentication yes + UsePAM yes + UseDNS no + AllowTcpForwarding no + X11Forwarding no + PrintMotd no + PermitTunnel no + # Allow client to pass locale environment variables + AcceptEnv LANG LC_* + # override default of no subsystems + Subsystem sftp /usr/lib/openssh/sftp-server + # Protocol adjustments, these would be needed/recommended in a FIPS or + # FedRAMP deployment, and use only strong and proven algorithm choices + Protocol 2 + Ciphers aes128-ctr,aes192-ctr,aes256-ctr + HostKeyAlgorithms ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521 + KexAlgorithms ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521 + Macs hmac-sha2-256,hmac-sha2-512 + ``` + +1. Save the file and restart the SSH server: + + ```shell + sudo systemctl restart ssh + ``` + + If restarting SSH fails, check that you don't have any + duplicate entries in `/etc/ssh/sshd_config`. + +### Ensure only authorized users are using SSH for Git access + +Next, ensure that users cannot pull down projects using SSH unless they have a +valid GitLab account that can perform Git operations over SSH. + +To ensure that only authorized users are using SSH for Git access: + +1. Add the following to your `/etc/ssh/sshd_config` file: + + ```plaintext + # Ensure only authorized users are using Git + AcceptEnv GIT_PROTOCOL + ``` + +1. Save the file and restart the SSH server: + + ```shell + sudo systemctl restart ssh + ``` + +### Make some kernel adjustments + +Kernel adjustments do not completely eliminate the threat of an attack, but +they add an extra layer of security. + +1. Open a new file with your editor under `/etc/sysctl.d`, for example + `/etc/sysctl.d/99-gitlab-hardening.conf`, and add the following. + + NOTE: + The naming and source directory decide the order of processing, which is + important because the last parameter processed might override earlier ones. + + ```plaintext + ## + ## The following help mitigate out of bounds, null pointer dereference, heap and + ## buffer overflow bugs, use-after-free etc from being exploited. It does not 100% + ## fix the issues, but seriously hampers exploitation. + ## + # Default is 65536, 4096 helps mitigate memory issues used in exploitation + vm.mmap_min_addr=4096 + # Default is 0, randomize virtual address space in memory, makes vuln exploitation + # harder + kernel.randomize_va_space=2 + # Restrict kernel pointer access (for example, cat /proc/kallsyms) for exploit assistance + kernel.kptr_restrict=2 + # Restrict verbose kernel errors in dmesg + kernel.dmesg_restrict=1 + # Restrict eBPF + kernel.unprivileged_bpf_disabled=1 + net.core.bpf_jit_harden=2 + # Prevent common use-after-free exploits + vm.unprivileged_userfaultfd=0 + + ## Networking tweaks ## + ## + ## Prevent common attacks at the IP stack layer + ## + # Prevent SYNFLOOD denial of service attacks + net.ipv4.tcp_syncookies=1 + # Prevent time wait assassination attacks + net.ipv4.tcp_rfc1337=1 + # IP spoofing/source routing protection + net.ipv4.conf.all.rp_filter=1 + net.ipv4.conf.default.rp_filter=1 + net.ipv6.conf.all.accept_ra=0 + net.ipv6.conf.default.accept_ra=0 + net.ipv4.conf.all.accept_source_route=0 + net.ipv4.conf.default.accept_source_route=0 + net.ipv6.conf.all.accept_source_route=0 + net.ipv6.conf.default.accept_source_route=0 + # IP redirection protection + net.ipv4.conf.all.accept_redirects=0 + net.ipv4.conf.default.accept_redirects=0 + net.ipv4.conf.all.secure_redirects=0 + net.ipv4.conf.default.secure_redirects=0 + net.ipv6.conf.all.accept_redirects=0 + net.ipv6.conf.default.accept_redirects=0 + net.ipv4.conf.all.send_redirects=0 + net.ipv4.conf.default.send_redirects=0 + ``` + +1. On the next server reboot, the values will be loaded automatically. To load + them immediately: + + ```shell + sudo sysctl --system + ``` + +Great work, you've completed the steps to secure your server! +Now you're ready to install GitLab. + +## Install GitLab + +Now that your server is set up, install GitLab: + +1. Install and configure the necessary dependencies: + + ```shell + sudo apt update + sudo apt install -y curl openssh-server ca-certificates perl locales + ``` + +1. Configure the system language: + + 1. Edit `/etc/locale.gen` and make sure `en_US.UTF-8` is uncommented. + 1. Regenerate the languages: + + ```shell + sudo locale-gen + ``` + +1. Add the GitLab package repository and install the package: + + ```shell + curl "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh" | sudo bash + ``` + + To see the contents of the script, visit <https://packages.gitlab.com/gitlab/gitlab-ee/install>. + +1. Install the GitLab package. Provide a strong password with + `GITLAB_ROOT_PASSWORD` and replace the `EXTERNAL_URL` + with your own. Don't forget to include `https` in the URL, so that a Let's Encrypt + certificate is issued. + + ```shell + sudo GITLAB_ROOT_PASSWORD="strong password" EXTERNAL_URL="https://gitlab.example.com" apt install gitlab-ee + ``` + + To learn more about the Let's Encrypt certificate or even + use your own, read how to [configure GitLab with TLS](https://docs.gitlab.com/omnibus/settings/ssl/). + + If the password you set wasn't picked up, read more about + [resetting the root account password](../../security/reset_user_password.md). + +1. After a few minutes, GitLab is installed. Sign in + using the URL you set up in `EXTERNAL_URL`. Use `root` as the username and + the password you set up in `GITLAB_ROOT_PASSWORD`. + +Now it's time to configure GitLab! + +## Configure GitLab + +GitLab comes with some sane default configuration options. In this section, +we will change them to add more functionality, and make GitLab more secure. + +For some of the options you'll use the Admin Area UI, and for some of them you'll +edit `/etc/gitlab/gitlab.rb`, the GitLab configuration file. + +### Configure NGINX + +NGINX is used to serve up the web interface used to access the GitLab instance. +For more information about configuring NGINX to be more secure, read about +[hardening NGINX](../../security/hardening_configuration_recommendations.md#nginx). + +### Configure emails + +Next, you'll set up and configure an email service. Emails are important for +verifying new sign ups, resetting passwords, and notifying +you of GitLab activity. + +#### Configure SMTP + +In this tutorial, you'll set up an [SMTP](https://docs.gitlab.com/omnibus/settings/smtp.html) +server and use the [Mailgun](https://mailgun.com) SMTP provider. + +First, start by creating an encrypted file that will contain the login +credentials, and then configure SMTP for the Linux package: + +1. Create a YAML file (for example `smtp.yaml`) that contains the credentials + for the SMTP server. + + Your SMTP password must not contain any string delimiters used in + Ruby or YAML (for example, `'`) to avoid unexpected behavior during the + processing of configuration settings. + + ```shell + user_name: '<SMTP user>' + password: '<SMTP password>' + ``` + +1. Encrypt the file: + + ```shell + cat smtp.yaml | sudo gitlab-rake gitlab:smtp:secret:write + ``` + + By default, the encrypted file is stored under + `/var/opt/gitlab/gitlab-rails/shared/encrypted_configuration/smtp.yaml.enc`. + +1. Remove the YAML file: + + ```shell + rm -f smtp.yaml + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and set up the rest of the SMTP settings. + Make sure `gitlab_rails['smtp_user_name']` and `gitlab_rails['smtp_password']` + are **not** present, as we've already set them up as encrypted. + + ```ruby + gitlab_rails['smtp_enable'] = true + gitlab_rails['smtp_address'] = "smtp.mailgun.org" # or smtp.eu.mailgun.org + gitlab_rails['smtp_port'] = 587 + gitlab_rails['smtp_authentication'] = "plain" + gitlab_rails['smtp_enable_starttls_auto'] = true + gitlab_rails['smtp_domain'] = "<mailgun domain>" + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +You should now be able to send emails. To test that the configuration worked: + +1. Enter the Rails console: + + ```shell + sudo gitlab-rails console + ``` + +1. Run the following command at the console prompt to make GitLab send a test email: + + ```irb + Notify.test_email('<email_address>', 'Message Subject', 'Message Body').deliver_now + ``` + +If you're unable to send emails, see the +[SMTP troubleshooting section](https://docs.gitlab.com/omnibus/settings/smtp.html#troubleshooting). + +#### Enable the email verification + +Account email verification provides an additional layer of GitLab account +security. When some conditions are met, for example, if there are three or more +failed sign-in attempts in 24 hours, an account is locked. + +This feature is behind a feature flag. To enable it: + +1. Enter the Rails console: + + ```shell + sudo gitlab-rails console + ``` + +1. Enable the feature flag: + + ```ruby + Feature.enable(:require_email_verification) + ``` + +1. Check if it's enabled (should return `true`): + + ```ruby + Feature.enabled?(:require_email_verification) + ``` + +For more information, read about +[account email verification](../../security/email_verification.md). + +#### Sign outgoing email with S/MIME + +Notification emails sent by GitLab can be signed with +[S/MIME](https://en.wikipedia.org/wiki/S/MIME) for improved security. + +A single pair of key and certificate files must be provided: + +- Both files must be PEM-encoded. +- The key file must be unencrypted so that GitLab can read it without user intervention. +- Only RSA keys are supported. +- Optional. You can provide a bundle of Certificate Authority (CA) certs + (PEM-encoded) to include on each signature. This is typically an + intermediate CA. + +1. Buy your certificate from a CA. +1. Edit `/etc/gitlab/gitlab.rb` and adapt the file paths: + + ```ruby + gitlab_rails['gitlab_email_smime_enabled'] = true + gitlab_rails['gitlab_email_smime_key_file'] = '/etc/gitlab/ssl/gitlab_smime.key' + gitlab_rails['gitlab_email_smime_cert_file'] = '/etc/gitlab/ssl/gitlab_smime.crt' + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +For more information, read about +[signing outgoing email with S/MIME](../../administration/smime_signing_email.md). + +## Next steps + +In this tutorial, you learned how to set up your server to be more secure, how +to install GitLab, and how to configure GitLab to meet some security standards. +Some [other steps](../../security/hardening_application_recommendations.md) you can take to secure GitLab include: + +- Disabling sign ups. By default, a new GitLab instance has sign up enabled by default. If you don't + plan to make your GitLab instance public, you should to disable sign ups. +- Allowing or denying sign ups using specific email domains. +- Setting a minimum password length limit for new users. +- Enforcing two-factor authentication for all users. + +There are many other things you can configure apart from hardening your GitLab +instance, like configuring your own runners to leverage the CI/CD features that +GitLab has to offer, or properly backing up your instance. + +You can read more about the [steps to take after the installation](../../install/next_steps.md). diff --git a/doc/tutorials/issue_triage/img/priority_labels_v16_3.png b/doc/tutorials/issue_triage/img/priority_labels_v16_3.png Binary files differnew file mode 100644 index 00000000000..afcf1752955 --- /dev/null +++ b/doc/tutorials/issue_triage/img/priority_labels_v16_3.png diff --git a/doc/tutorials/issue_triage/img/triage_board_v16_3.png b/doc/tutorials/issue_triage/img/triage_board_v16_3.png Binary files differnew file mode 100644 index 00000000000..c32352a454e --- /dev/null +++ b/doc/tutorials/issue_triage/img/triage_board_v16_3.png diff --git a/doc/tutorials/issue_triage/img/triage_report_v16_3.png b/doc/tutorials/issue_triage/img/triage_report_v16_3.png Binary files differnew file mode 100644 index 00000000000..91548a1a17d --- /dev/null +++ b/doc/tutorials/issue_triage/img/triage_report_v16_3.png diff --git a/doc/tutorials/issue_triage/index.md b/doc/tutorials/issue_triage/index.md new file mode 100644 index 00000000000..38e4285c2ce --- /dev/null +++ b/doc/tutorials/issue_triage/index.md @@ -0,0 +1,232 @@ +--- +stage: Plan +group: Project Management +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 +--- + +# Tutorial: Set up a single project for issue triage **(FREE ALL)** + +<!-- vale gitlab.FutureTense = NO --> + +Issue triage is the process of categorization according to type and severity. +As your project grows and people create more issues, it's worth creating a workflow for how you'll +triage incoming issues. + +In this tutorial, you'll learn how to set up a GitLab project for this. + +To set up GitLab for issue triage in a project: + +1. [Create a project](#create-a-project) +1. [Decide on the criteria for types, severity, and priority](#decide-on-the-criteria-for-types-severity-and-priority) +1. [Document your criteria](#document-your-criteria) +1. [Create scoped labels](#create-scoped-labels) +1. [Prioritize the new labels](#prioritize-the-new-labels) +1. [Create an issue triage board](#create-an-issue-triage-board) +1. [Create issues for features](#create-issues-for-features) + +## Prerequisites + +- If you're using an existing project for this tutorial, make sure you have at least the Reporter role + for the project. +- If you follow the steps below and later decide to create a parent group for your project, to make + best use of labels, you'll have to promote the project labels to group labels. + Consider creating a group first. + +## Create a project + +A project contains the issues that are used for planning your upcoming code changes. + +If you already have a project you're working in, proceed to +[Decide on the criteria for types, severity, and priority](#decide-on-the-criteria-for-types-severity-and-priority). + +To create a blank project: + +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. +1. Select **Create blank project**. +1. Enter the project details. + - For **Project name**, enter `Issue triage tutorial`. +1. Select **Create project**. + +## Decide on the criteria for types, severity, and priority + +Next, you'll need to determine: + +- **Types** of issues you want to recognize. If you need a more granular approach, you + can also create subtypes for each type. Types help categorize work to get an understanding of the + kind of work that is requested of your team. +- Levels of **priorities** and **severities** to define the impact that incoming work has on end + users and to assist in prioritization. + +For this tutorial, suppose you've decided on the following: + +- Type: `Bug`, `Feature`, and `Maintenance` +- Priority: `1`, `2`, `3`, and `4` +- Severity: `1`, `2`, `3`, and `4` + +For inspiration, see how we define these at GitLab: + +- [Types and subtypes](https://about.gitlab.com/handbook/engineering/metrics/#work-type-classification) +- [Priority](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#priority) +- [Severity](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#severity) + +## Document your criteria + +After you agree on all the criteria, write it all down somewhere your team mates can always access. + +For example, add it to a [wiki](../../user/project/wiki/index.md) in your project, or your company +handbook published with [GitLab Pages](../../user/project/pages/index.md). + +<!-- Idea for expanding this tutorial: + Add steps for [creating a wiki page](../../user/project/wiki/index.md#create-a-new-wiki-page). --> + +## Create scoped labels **(PREMIUM ALL)** + +Next, you'll create labels to add to issues to categorize them. + +The best tool for this is [scoped labels](../../user/project/labels.md#scoped-labels), which you +can use to set mutually exclusive attributes. + +Checking with the list of types, severities, and priorities you've assembled +[previously](#decide-on-the-criteria-for-types-severity-and-priority), you'll want to create matching +scoped labels. + +The double colon (`::`) in the name of a scoped label prevents two labels of the same scope being +used together. +For example, if you add the `type::feature` label to an issue that already has `type::bug`, the +previous one is removed. + +NOTE: +Scoped labels are available in the Premium and Ultimate tier. +If you're on the Free tier, you can use regular labels instead. +However, they aren't mutually exclusive. + +To create each label: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. +1. Select **New label**. +1. In the **Title** field, enter the name of the label. Start with `type::bug`. +1. Optional. Select a color by selecting from the available colors, or enter a hex color value for + a specific color in the **Background color** field. +1. Select **Create label**. + +Repeat these steps to create all the labels you'll need: + +- `type::bug` +- `type::feature` +- `type::maintenance` +- `priority::1` +- `priority::2` +- `priority::3` +- `priority::4` +- `severity::1` +- `severity::2` +- `severity::3` +- `severity::4` + +## Prioritize the new labels + +Now, set the new labels as priority labels, which ensures that the most important issues show on top +of the issue list if you sort by priority or label priority. + +To learn what happens when you sort by priority or label priority, see +[Sorting and ordering issue lists](../../user/project/issues/sorting_issue_lists.md). + +To prioritize a label: + +1. On the Labels page, next to a label you want to prioritize, select the star (**{star-o}**). + This label now appears at the top of the label list, under **Prioritized labels**. +1. To change the relative priority of these labels, drag them up and down the list. + The labels higher in the list get higher priority. +1. Prioritize all the labels you created previously. + Make sure that labels of higher priority and severity are higher on the list than the lower values. + + + +## Create an issue triage board + +To prepare for the incoming issue backlog, create an [issue board](../../user/project/issue_board.md) that organizes issues by label. +You'll use it to quickly create issues and add labels to them by dragging cards to various lists. + +To set up your issue board: + +1. Decide on the scope of the board. For example, create one that you'll use to assign + severity to issues. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your + **Issue triage tutorial** project. +1. Select **Plan > Issue boards**. +1. In the upper-left corner of the issue board page, select the dropdown list with the current board name. +1. Select **Create new board**. +1. In the **Title field**, enter `Issue triage (by severity)`. +1. Keep the **Show the Open list** checkbox selected and clear the **Show the Closed list** one. +1. Select **Create board**. You should see an empty board. +1. Create a list for the `severity::1` label: + 1. In the upper-left corner of the issue board page, select **Create list**. + 1. In the column that appears, from the **Value** dropdown list, select the `severity::1` label. + 1. Select **Add to board**. +1. Repeat the previous step for labels `severity::2`, `severity::3`, and `severity::4`. + +For now, the lists in your board should be empty. Next, you'll populate them with some issues. + +## Create issues for features + +To track upcoming features and bugs, you must create some issues. +Issues belong in projects, but you can also create them directly from your issue board. + +Start by creating some issues for planned features. +You can create issues for bugs as you find them (hopefully not too many!). + +To create an issue from your **Issue triage (by severity)** board: + +1. On the **Open** list, select **Create new issue** (**{plus}**). + The **Open** list shows issues that don't fit any other board list. + + If you already know which severity label your issue should have, you can create it directly from that label list. + Each issue created from a label list will be given that label. +1. Complete the fields: + - Under **Title**, enter `User registration`. +1. Select **Create issue**. +1. Repeat these steps to create a few more issues. + + For example, if you're building an app, create the following issues: + + - `User registration` + - `Profile creation` + - `Search functionality` + - `Add to favorites` + - `Push notifications` + - `Social sharing` + - `In-app messaging` + - `Track progress` + - `Feedback and ratings` + - `Settings and preferences` + +Your first triage issue board is ready! +Try it out by dragging some issues from the **Open** list to one of the label lists to add one of +the severity labels. + + + +## Next steps + +Next, you can: + +- Tweak how you use issue boards. Some options include: + - Edit your current issue board to also have lists for priority and type labels. + This way, you'll make the board wider and might require some horizontal scrolling. + - Create separate issue boards named `Issue triage (by priority)` and `Issue triage (by type)`. + This way, you'll keep various types of triage work separate, but will require switching between + boards. + - [Set up issue boards for team hand-off](../boards_for_teams/index.md). +- Browse issues by priority or severity in issue lists, + [filtered by each label](../../user/project/issues/managing_issues.md#filter-the-list-of-issues). + If it's available to you, make use of + [the "is one of" filter operator](../../user/project/issues/managing_issues.md#filter-with-the-or-operator). +- Break the issues down into [tasks](../../user/tasks.md). +- Create policies that help automate issue triage in a project with the [`gitlab-triage` gem](https://gitlab.com/gitlab-org/ruby/gems/gitlab-triage). + Generate summary reports with heatmaps like the following: + +  + +To learn more about issue triage at GitLab, see [Issue Triage](https://about.gitlab.com/handbook/engineering/quality/issue-triage/) +and [Triage Operations](https://about.gitlab.com/handbook/engineering/quality/triage-operations/). diff --git a/doc/tutorials/learn_git.md b/doc/tutorials/learn_git.md index 6df9b3944b7..afc4ef90ffc 100644 --- a/doc/tutorials/learn_git.md +++ b/doc/tutorials/learn_git.md @@ -13,5 +13,6 @@ the most out of GitLab. |-------|-------------|--------------------| | [Make your first Git commit](make_first_git_commit/index.md) | Create a project, edit a file, and commit changes to a Git repository from the command line. | **{star}** | | [Start using Git on the command line](../gitlab-basics/start-using-git.md) | Learn how to set up Git, clone repositories, and work with branches. | **{star}** | -| [Take advantage of Git rebase](https://about.gitlab.com/blog/2022/10/06/take-advantage-of-git-rebase/)| Learn how to use the `rebase` command in your workflow. | | +| [Take advantage of Git rebase](https://about.gitlab.com/blog/2022/10/06/take-advantage-of-git-rebase/) | Learn how to use the `rebase` command in your workflow. | | +| [Update Git commit messages](update_commit_messages/index.md) | Learn how to update commit messages and push the changes to GitLab. | | | [Git cheat sheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf) | Download a PDF of common Git commands. | | diff --git a/doc/tutorials/left_sidebar/index.md b/doc/tutorials/left_sidebar/index.md index 80fbbf2032e..fee10fbe783 100644 --- a/doc/tutorials/left_sidebar/index.md +++ b/doc/tutorials/left_sidebar/index.md @@ -4,7 +4,7 @@ group: Tutorials info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- -# Tutorial: Use the left sidebar to navigate GitLab **(FREE)** +# Tutorial: Use the left sidebar to navigate GitLab **(FREE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9044) in GitLab 16.0. diff --git a/doc/tutorials/make_your_first_git_commit.md b/doc/tutorials/make_your_first_git_commit.md deleted file mode 100644 index 04c66a953af..00000000000 --- a/doc/tutorials/make_your_first_git_commit.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'make_first_git_commit/index.md' -remove_date: '2023-07-21' ---- - -This document was moved to [another location](make_first_git_commit/index.md). - -<!-- This redirect file can be deleted after 2023-07-21. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/tutorials/move_personal_project_to_a_group.md b/doc/tutorials/move_personal_project_to_a_group.md deleted file mode 100644 index 361181fdde6..00000000000 --- a/doc/tutorials/move_personal_project_to_a_group.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'move_personal_project_to_group/index.md' -remove_date: '2023-07-21' ---- - -This document was moved to [another location](move_personal_project_to_group/index.md). - -<!-- This redirect file can be deleted after 2023-07-21. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/tutorials/plan_and_track.md b/doc/tutorials/plan_and_track.md index 657ade465b7..7dcafbd26ce 100644 --- a/doc/tutorials/plan_and_track.md +++ b/doc/tutorials/plan_and_track.md @@ -14,6 +14,8 @@ issues, epics, and more. | [GitLab Agile Project Management](https://levelup.gitlab.com/courses/gitlab-agile-project-management) | Learn how to use planning features to manage your projects in this self-paced course. | **{star}** | | [Create a project from a template](https://gitlab.com/projects/new#create_from_template) | Choose a project template and create a project with files to get you started. | | | [Migrate to GitLab](../user/project/import/index.md) | If you are coming to GitLab from another platform, you can import or convert your projects. | | +| [Build a protected workflow for your project](protected_workflow/index.md) | Set up a workflow for your teams, and enforce protections with approval rules. | | | [Run an agile iteration](agile_sprint/index.md) | Use group, projects, and iterations to run an agile development iteration. | +| [Set up a single project for issue triage](issue_triage/index.md) | Use labels to set up a project for issue triage. | **{star}** | | [Set up issue boards for team hand-off](boards_for_teams/index.md) | Use issue boards and scoped labels to set up collaboration across many teams. | **{star}** | | <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Epics and Issue Boards](https://www.youtube.com/watch?v=I1bFIAQBHB8) | Find out how to use epics and issue boards for project management. | | diff --git a/doc/tutorials/protected_workflow/index.md b/doc/tutorials/protected_workflow/index.md index 5245bdc5ba9..b055faddc75 100644 --- a/doc/tutorials/protected_workflow/index.md +++ b/doc/tutorials/protected_workflow/index.md @@ -6,7 +6,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated <!-- vale gitlab.FutureTense = NO --> -# Tutorial: Build a protected workflow for your project **(FREE)** +# Tutorial: Build a protected workflow for your project **(FREE ALL)** When your team starts a new project, they need a workflow that balances efficiency with appropriate reviews. In GitLab, you can create user groups, combine those diff --git a/doc/tutorials/scan_result_policy.md b/doc/tutorials/scan_result_policy.md deleted file mode 100644 index 9aacd8eff7b..00000000000 --- a/doc/tutorials/scan_result_policy.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'scan_result_policy/index.md' -remove_date: '2023-07-21' ---- - -This document was moved to [another location](scan_result_policy/index.md). - -<!-- This redirect file can be deleted after 2023-07-21. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/tutorials/scan_result_policy/index.md b/doc/tutorials/scan_result_policy/index.md index 89bd2e099b6..1c23d6a36eb 100644 --- a/doc/tutorials/scan_result_policy/index.md +++ b/doc/tutorials/scan_result_policy/index.md @@ -4,7 +4,7 @@ group: Security Policies 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 --- -# Tutorial: Set up a scan result policy **(ULTIMATE)** +# Tutorial: Set up a scan result policy **(ULTIMATE ALL)** This tutorial shows you how to create and configure a [scan result policy](../../user/application_security/policies/scan-result-policies.md). These policies can be set to take action based on scan results. For example, in this tutorial, you'll set up a policy that requires approval from two specified users if a vulnerability is detected in a merge request. diff --git a/doc/tutorials/update_commit_messages/index.md b/doc/tutorials/update_commit_messages/index.md new file mode 100644 index 00000000000..f6d92b5c13f --- /dev/null +++ b/doc/tutorials/update_commit_messages/index.md @@ -0,0 +1,209 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +--- + +# Tutorial: How to update Git commit messages **(FREE ALL)** + +Occasionally, after you've made a few commits to your branch, you realize you need +to update one or more commit messages. Perhaps you found a typo, or some automation warned you +that your commit message didn't completely align with a project's +[commit message guidelines](../../development/contributing/merge_request_workflow.md#commit-messages-guidelines). + +Updating the message can be tricky if you don't have much practice with using Git +from the command line interface (CLI). But don't worry, even if you have only ever worked in +the GitLab UI, we'll walk you through the steps to use the CLI. + +This tutorial explains how to rewrite commit messages in both cases: + +- If you work from just the GitLab UI, start at step 1. +- If you already have your repository cloned locally, you can skip to step 2. + +To rewrite any number of commit messages: + +1. [Clone your project's repository to your local machine](#clone-your-repository-to-your-local-machine). +1. [Fetch and check out your branch locally](#fetch-and-check-out-your-branch). +1. [Update the commit messages](#update-the-commit-messages). +1. [Push the changes up to GitLab](#push-the-changes-up-to-gitlab). + +## Prerequisites + +You must have: + +- A GitLab project with a Git branch containing commits that you want to update. +- Git [installed on your local machine](../../topics/git/how_to_install_git/index.md). +- The ability to get to your local machine's command line interface (CLI). In macOS, + you can use Terminal. In Windows, you can use PowerShell. Linux users are probably + already familiar with their system's CLI. +- Familiarity with your system's default editor. This tutorial assumes your editor is Vim, + but any text editor should work. If you are unfamiliar with Vim, step 1 to 2 of + [Getting started with Vim](https://opensource.com/article/19/3/getting-started-vim) + explains all the commands used later in this tutorial. +- Permission to overwrite the commit messages. If you are working with multiple people in the same branch, + you should first verify with them that it's OK to update the commits. Some organizations might + have rules against rewriting commits, as it is considered a destructive change. + +You need to authenticate with GitLab to overwrite the commit messages in the final step. +If your GitLab account uses basic username and password authentication, you must have +[two factor authentication (2FA)](../../user/profile/account/two_factor_authentication.md) +disabled to authenticate from the CLI. Alternatively, you can [use an SSH key to authenticate with GitLab](../../user/ssh.md). + +## Clone your repository to your local machine + +The first thing you need to do is get the repository on your local machine: + +1. In GitLab, on your project's overview page, on the top right, select **Clone**. +1. In the dropdown list, copy the URL for your repository by selecting **{copy-to-clipboard}** next to: + - **Clone with HTTPS** if your GitLab account uses basic username and password authentication. + - **Clone with SSH** if you use SSH to authenticate with GitLab. +1. Now switch to the CLI (Terminal, PowerShell, or similar) on your local machine, and go to + the directory where you want to clone the repository. For example, `/users/my-username/my-projects/`. +1. Run `git clone` and paste the URL you copied earlier, for example: + + ```shell + git clone https://gitlab.com/my-username/my-awesome-project.git + ``` + + This clones the repository into a new directory called `my-awesome-project/`. + +Now your repository is on your computer, ready for your Git CLI commands! + +## Fetch and check out your branch + +Next we need to check out the branch that contains the commits to update. + +1. Assuming you are still at the same place in the CLI as the previous step, + change to your project directory with `cd`: + + ```shell + cd my-awesome-project + ``` + +1. Optional. If you've just cloned the repository, your branch should already be + on your computer too. But if you've previously cloned the repository and skipped + to this step, you might need to fetch your branch with: + + ```shell + git fetch origin my-branch-name + ``` + +1. Now that you know for sure that the branch is on your local system, switch to it: + + ```shell + git checkout my-branch-name + ``` + +1. Verify that it's the correct branch with `git log` and check that the most recent commits + match the commits in your branch on GitLab. To exit the log, use `q`. + +## Update the commit messages + +Now we are ready to update the commit messages: + +1. In GitLab, see how far back in the commit history you need to go: + + - If you already have a merge request open for your branch, you can check the + **Commits** tab and use the total number of commits. + - If you are working from a branch only: + 1. Go to **Code > Commits**. + 1. Select the dropdown list in the top left and find your branch. + 1. Find the oldest commit you want to update, and count how far back that commit is. + For example, if you want to update the second and fourth commit, the count would be 4. + +1. From the CLI, start an interactive rebase, which is the Git process to update commits. + Add the count of commits from the previous step to the end of `HEAD~`, for example: + + ```shell + git rebase -i HEAD~4 + ``` + + In this example, Git selects the four most recent commits in the branch to update. + +1. Git launches a text editor and lists the selected commits. + For example, it should look similar to: + + ```shell + pick a0cea50 Fix broken link + pick bb84712 Update milestone-plan.md + pick ce11fad Add list of maintainers + pick d211d03 update template.md + + # Rebase 1f5ec88..d211d03 onto 1f5ec88 (4 commands) + # + # Commands: + # p, pick <commit> = use commit + # r, reword <commit> = use commit, but edit the commit message + # e, edit <commit> = use commit, but stop for amending + # s, squash <commit> = use commit, but meld into previous commit + # f, fixup [-C | -c] <commit> = like "squash" but keep only the previous + # commit's log message, unless -C is used, in which case + # [and so on...] + ``` + +1. The `pick` command tells Git to use the commits without change. You must change + the command from `pick` to `reword` for the commits you want to update. + Type `i` to enter `INSERT` mode, and then start editing the text. + + For example, to update the text of the second and fourth commits in the sample above, + edit it to look like: + + ```shell + pick a0cea50 Fix broken link + reword bb84712 Update milestone-plan.md + pick ce11fad Add list of maintainers + reword d211d03 update template.md + ``` + +1. Save the edited text. Press <kbd>Escape</kbd> to exit `INSERT` mode, + then type `:wq` and <kbd>Enter</kbd> to save and exit. + +1. Git now goes through each commit one at a time and applies the commands we selected. + Any commits with `pick` are added back to the branch unchanged. When Git reaches a commit + with `reword`, it stops and again opens up the text editor. Now it's time to finally update + the text of the commit message! + + - If you only need a one line commit message, update the text as needed. For example: + + ```plaintext + Update the monthly milestone plan + ``` + + - If the commit message needs a title and a body, separate these with a blank line. For example: + + ```plaintext + Update the monthly milestone plan + + Make the milestone plan clearer by listing the responsibilities + of each maintainer. + ``` + + After you save and exit, Git updates the commit message, and processes the next + commits in order. You should see the message `Successfully rebased and update refs/heads/my-branch-name` + when finished. + +1. Optional. To verify that the commit messages were updated, you can run `git log` + and scroll down to see the commit messages. + +## Push the changes up to GitLab + +Now all that's left is to push these changes up to GitLab: + +1. From the CLI, force push the changes to overwrite what exists in the branch in GitLab. + + ```shell + git push -f origin + ``` + + Your terminal might prompt you for your username and password before overwriting + the commit messages in GitLab. + +1. In your project in GitLab, verify that the commits have been updated: + + - If you already have a merge request open for your branch, check the **Commits** tab. + - If you are working from a branch only: + 1. Go to **Code > Commits**. + 1. Select the dropdown list in the top left and find your branch. + 1. Verify that the relevant commits in the list are now updated. + +Congratulations, you have successfully updated your commit messages and pushed them to GitLab! diff --git a/doc/tutorials/website_project_with_analytics/index.md b/doc/tutorials/website_project_with_analytics/index.md new file mode 100644 index 00000000000..a0a78b68585 --- /dev/null +++ b/doc/tutorials/website_project_with_analytics/index.md @@ -0,0 +1,162 @@ +--- +stage: Plan +group: Optimize +info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +--- + +# Tutorial: Set up an analytics-powered website project **(ULTIMATE ALL)** + +When you work on a complex project (for example, a website), you likely collaborate with other people to build and maintain it. +The way you collaborate and communicate in your team can make or break the project, so you want processes in place that help team members follow and achieve the common goal. +Analytics metrics help you understand how the team is doing, and if you need to adjust processes so you can work better together. +GitLab provides different types of [analytics](../../user/analytics/index.md) insights at the instance, group, and project level. +If this list seems long and you're not sure where to start, then this tutorial is for you. + +Follow along to learn how to set up an example website project, collaborate with other GitLab users, +and use project-level analytics reports to evaluate the development of your project. + +Prerequisite: + +- You must have the Owner role for the group in which you create the project. + +Here's an overview of what we're going to do: + +1. Create a project from a template. +1. Invite users to the project. +1. Create project labels. +1. Create a value stream with a custom stage. +1. Create an Insights report. +1. View merge request and issue analytics. + +## Create a project from a template + +First of all, you need to create a project in your group. + +GitLab provides project templates, +which make it easier to set up a project with all the necessary files for various use cases. +Here, you'll create a project for a Hugo website. + +To create a project: + +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. +1. Select **Create from template**. +1. Select the **Pages/Hugo** template. +1. In the **Project name** text box, enter a name (for example `My website`). +1. From the **Project URL** dropdown list, select the group you want to create the project in. +1. In the **Project slug** text box, enter a slug for your project (for example, `my-website`). +1. Optional. In the **Project description** text box, enter a description of your project. + For example, "Analytics-powered project for a website built with Hugo". You can add or edit this description at any time. +1. Under **Visibility Level**, select the desired level for the project. + If you create the project in a group, the visibility setting for a project must be at least as restrictive as the visibility of its parent group. +1. Select **Create project**. + +Now you have a project with all the files you need for a Hugo website. + +## Invite users to the project + +When working on a large project such as a website, you'll likely need to collaborate with other people, +such as developers and designers. +You have to invite them to your project, so that they get access to all the files, issues, and reports. + +To invite a user to the `My website` project: + +1. In the project, select **Manage > Members**. +1. Select **Invite members**. +1. Enter the user's **username**. +1. From the **Role** dropdown list, select the **Developer** role or higher. + Users must have at least the Developer role to view analytics and contribute to issues and merge requests. +1. Optional. In the **Access expiration date** picker, select a date. + This step is recommended if the invited member is expected to contribute to the project only for a limited time. +1. Select **Invite**. + +The invited user should now be a member of the project. +You can [view, filter, and search for members](../../user/project/members/index.md#filter-and-sort-members) of your project. + +## Create project labels + +[Labels](../../user/project/labels.md) help you organize and track issues, merge requests, and epics. +You can create as many labels as you need for your projects and groups. +For example, for a website project like this one, the labels `feature request` and `bug` might be useful. + +To create a project label, in the `My website` project: + +1. Select **Manage > Labels**. +1. Select **New label**. +1. In the **Title** field, enter `feature request`. +1. Optional. In the **Description** field, enter additional information about how and when to use this label. +1. Optional. Select a color by selecting from the available colors, or enter a hex color value for a specific color in the **Background color** field. +1. Select **Create label**. + +The label should now appear in the [label list](../../user/project/labels.md#view-project-labels), +and you can use it to create a value stream with a custom stage. + +## Create a value stream with a custom stage + +Now that you have a project with collaborators, you can start tracking and visualizing the activity. +[Value Stream Analytics](../../user/group/value_stream_analytics/index.md) helps you measure the time it takes +to go from an idea to production, and identify inefficiencies in the development process. + +To get started, create a value stream in the `My website` project: + +1. Select **Analyze > Value Stream Analytics**. +1. Select **Create new Value Stream**. +1. Enter a name for the value stream, for example `My website value stream`. +1. Select **Create from default template**. +1. To add a custom stage, select **Add another stage**. + - Enter a name for the stage, for example `Labeled MRs merged`. + - From the **Start event** dropdown list, select **Merge request label was added**, then the `feature request` label. + - From the **Stop event** dropdown list, select **Merge request merged**. +1. Select **Create value stream**. + +After you create the value stream, data starts collecting and loading. +This process might take a while. When it's ready, the dashboard is displayed in **Analyze > Value Stream Analytics**. + +In the meantime, you can start creating an Insights report for your project. + +## Create an Insights report + +While Value Stream Analytics give an overview of the entire development process, +[Insights](../../user/project/insights/index.md) provide a more granular view of a project's +issues created and closed, and average merge time of merge requests. +This data visualization can help you triage issues at a glance. + +You can create as many Insights reports with different charts as you need. +For example, a stacked bar chart for bugs by severity or a line chart for issues opened over the month. + +To create an Insights report, in the `My website` project: + +1. Above the file list, select the plus icon, then select **New file**. +1. In the **File name** text box, enter `.gitlab/insights.yml`. +1. In the large text box, enter the following code: + + ```yaml + bugsCharts: + title: "Charts for bugs" + charts: + - title: "Monthly bugs created" + description: "Open bugs created per month" + type: bar + query: + data_source: issuables + params: + issuable_type: issue + issuable_state: opened + filter_labels: + - bug + group_by: month + period_limit: 12 + ``` + +1. Select **Commit changes**. + +Now you have an Insights bar chart that displays the number of issues with the label `~bug` created per month, for the past 12 months. +You and project members with at least the Developer role can view the Insights report in **Analyze > Insights**. + +## View merge request and issue analytics + +In addition to the Insights reports, you can get detailed analytics on the merge requests and issues of your project. +[Merge request analytics](../../user/analytics/merge_request_analytics.md) and [Issue analytics](../../user/analytics/issue_analytics.md) display charts and tables with metrics such as assignees, merge request throughput, and issue status. + +To view merge request and issue analytics, in the `My website` project, select **Analyze > Merge request analytics** or **Analyze > Issue analytics**. + +That was it! Now you have an analytics-powered website project on which you can collaborate efficiently with your team. diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md index 804fcc77ea1..08a5a3a7549 100644 --- a/doc/update/deprecations.md +++ b/doc/update/deprecations.md @@ -55,8 +55,8 @@ For deprecation reviewers (Technical Writers only): ### Atlassian Crowd OmniAuth provider <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.3</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.3</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/369117). </div> @@ -72,8 +72,8 @@ next major release, GitLab 16.0. This gem sees very little use and its ### Auto DevOps support for Herokuish is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/211643). </div> @@ -88,8 +88,8 @@ Because Cloud Native Buildpacks do not support automatic testing, the Auto Test ### CiRunner.projects default sort is changing to `id_desc` <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.0</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/372117). </div> @@ -103,8 +103,8 @@ If you rely on the order of the returned projects to be `id_asc`, change your sc ### CiRunnerUpgradeStatusType GraphQL type renamed to CiRunnerUpgradeStatus <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.0</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/409332). </div> @@ -118,8 +118,8 @@ the aliasing for the `CiRunnerUpgradeStatusType` type will be removed. ### DAST ZAP advanced configuration variables deprecation <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.7</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.7</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/383467). </div> @@ -134,9 +134,8 @@ These three variables will be removed in GitLab 17.0. ### Deprecate Windows CMD in GitLab Runner <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.1</span> -- End of Support: GitLab <span class="milestone">17.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.1</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/414864). </div> @@ -149,9 +148,8 @@ In GitLab 11.11 the Windows Batch executor, the CMD shell was deprecated in GitL ### Deprecate `CiRunner` GraphQL fields duplicated in `CiRunnerManager` <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.2</span> -- End of Support: GitLab <span class="milestone">17.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.2</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/41518). </div> @@ -164,8 +162,8 @@ These fields (`architectureName`, `ipAddress`, `platformName`, `revision`, `vers ### Deprecate `message` field from Vulnerability Management features <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.1</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.1</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/411573). </div> @@ -176,11 +174,41 @@ The message field was removed from security reports schema in GitLab 16.0 and is <div class="deprecation " data-milestone="17.0"> +### Deprecate `terminationGracePeriodSeconds` in the GitLab Runner Kubernetes executor + +<div class="deprecation-notes"> +- Announced in GitLab <span class="milestone">16.3</span> +- End of Support in GitLab <span class="milestone">17.0</span> +- Removal in GitLab <span class="milestone">17.0</span> +- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28165). +</div> + +The GitLab Runner Kubernetes executor setting, `terminationGracePeriodSeconds`, is deprecated and will be removed in GitLab 17.0. To manage the cleanup and termination of GitLab Runner worker pods on Kubernetes, customers should instead configure `cleanupGracePeriodSeconds` and `podTerminationGracePeriodSeconds`. For information about how to use the `cleanupGracePeriodSeconds` and `podTerminationGracePeriodSeconds, see the [GitLab Runner Executor documentation](https://docs.gitlab.com/runner/executors/kubernetes.html#other-configtoml-settings). + +</div> + +<div class="deprecation breaking-change" data-milestone="17.0"> + +### Deprecate field `hasSolutions` from GraphQL VulnerabilityType + +<div class="deprecation-notes"> +- Announced in GitLab <span class="milestone">16.3</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) +- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/414895). +</div> + +The GraphQL field `Vulnerability.hasSolutions` is deprecated and will be removed in GitLab 17.0. +Use `Vulnerability.hasRemediations` instead. + +</div> + +<div class="deprecation " data-milestone="17.0"> + ### Deprecate legacy shell escaping and quoting runner shell executor <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.11</span> -- End of Support: GitLab <span class="milestone">17.9</span> +- Announced in GitLab <span class="milestone">15.11</span> +- Removal in GitLab <span class="milestone">17.0</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/406679). </div> @@ -193,8 +221,8 @@ The runner's legacy escape sequence mechanism to handle variable expansion imple ### Deprecated parameters related to custom text in the sign-in page <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.2</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.2</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124461). </div> @@ -207,8 +235,8 @@ The parameters, `sign_in_text` and `help_text`, are deprecated in the [Settings ### DingTalk OmniAuth provider <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.10</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.10</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390855). </div> @@ -222,8 +250,8 @@ major release, GitLab 17.0. This gem sees very little use and is better suited f ### Filepath field in Releases and Release Links APIs <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/groups/gitlab-org/-/epics/9661). </div> @@ -248,8 +276,8 @@ To avoid any disruptions, you should replace `filepath` with `direct_asset_path` ### GitLab Helm chart values `gitlab.kas.privateApi.*` are deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/4097). </div> @@ -269,8 +297,8 @@ Because the new values provide a streamlined, comprehensive method to enable TLS ### GitLab Runner platforms and setup instructions in GraphQL API <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/387937). </div> @@ -285,9 +313,8 @@ are deprecated and will be removed from the GraphQL API. For installation instru ### GitLab Runner registration token in Runner Operator <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.6</span> -- End of Support: GitLab <span class="milestone">17.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.6</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/382077). </div> @@ -309,8 +336,8 @@ This change is a breaking change. You should use an [authentication token](../ci ### GraphQL deprecation of `dependencyProxyTotalSizeInBytes` field <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.1</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.1</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/414236). </div> @@ -325,8 +352,8 @@ Use `dependencyProxyTotalSizeBytes` instead, introduced in GitLab 16.1. ### GraphQL field `registrySizeEstimated` has been deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.2</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.2</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/416509). </div> @@ -338,11 +365,27 @@ Use `containerRegistrySizeIsEstimated` introduced in GitLab 16.2 instead. <div class="deprecation breaking-change" data-milestone="17.0"> +### GraphQL field `totalWeight` is deprecated + +<div class="deprecation-notes"> +- Announced in GitLab <span class="milestone">16.3</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) +- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/416219). +</div> + +You can use GraphQL to query the total weight of issues in an issue board. However, the `totalWeight` field is limited to the maximum size 2147483647. As a result, `totalWeight` is deprecated and will be removed in GitLab 17.0. + +Use `totalIssueWeight` instead, introduced in GitLab 16.2. + +</div> + +<div class="deprecation breaking-change" data-milestone="17.0"> + ### GraphQL type, `RunnerMembershipFilter` renamed to `CiRunnerMembershipFilter` <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.0</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/409333). </div> @@ -356,8 +399,8 @@ the aliasing for the `RunnerMembershipFilter` type will be removed. ### GraphQL: The `DISABLED_WITH_OVERRIDE` value of the `SharedRunnersSetting` enum is deprecated. Use `DISABLED_AND_OVERRIDABLE` instead <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/385636). </div> @@ -370,8 +413,8 @@ In GitLab 17.0, the `DISABLED_WITH_OVERRIDE` value of the `SharedRunnersSetting` ### Maintainer role providing the ability to change Package settings using GraphQL API <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/370471). </div> @@ -392,8 +435,8 @@ settings for the group using either the GitLab UI or GraphQL API. ### OmniAuth Facebook is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.2</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.2</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/416000). </div> @@ -406,8 +449,8 @@ OmniAuth Facebook support will be removed in GitLab 17.0. The last gem release w ### Package pipelines in API payload is paginated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/289956). </div> @@ -422,8 +465,8 @@ In milestone 17.0, we will remove the `pipelines` attribute from the API respons ### PipelineSecurityReportFinding projectFingerprint GraphQL field <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.1</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.1</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/343475). </div> @@ -436,9 +479,8 @@ The [`project_fingerprint`](https://gitlab.com/groups/gitlab-org/-/epics/2791) a ### PostgreSQL 13 deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.0</span> -- End of Support: GitLab <span class="milestone">17.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.0</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/groups/gitlab-org/-/epics/9065). </div> @@ -457,9 +499,9 @@ PostgreSQL 14 will also be supported for instances that want to upgrade prior to ### Queue selector for running Sidekiq is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- End of Support: GitLab <span class="milestone">16.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- End of Support in GitLab <span class="milestone">16.0</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390787). </div> @@ -476,9 +518,8 @@ While the above approach is recommended for most instances, Sidekiq can also be ### Registration tokens and server-side runner arguments in `POST /api/v4/runners` endpoint <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.6</span> -- End of Support: GitLab <span class="milestone">17.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.6</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/379743). </div> @@ -506,9 +547,8 @@ This change is a breaking change. You should [create a runner in the UI](../ci/r ### Registration tokens and server-side runner arguments in `gitlab-runner register` command <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.6</span> -- End of Support: GitLab <span class="milestone">17.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.6</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/380872). </div> @@ -534,8 +574,8 @@ This change is a breaking change. You should [create a runner in the UI](../ci/r ### Required Pipeline Configuration is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/389467). </div> @@ -551,8 +591,8 @@ that is available now. We recommend this alternative solution because it provide ### Running a single database is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.1</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.1</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/411239). </div> @@ -573,8 +613,8 @@ Before upgrading to GitLab 17.0, please ensure you have [migrated](https://docs. ### Self-managed certificate-based integration with Kubernetes <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). </div> @@ -599,8 +639,8 @@ For updates and details about this deprecation, follow [this epic](https://gitla ### Single database connection is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/387898). </div> @@ -622,9 +662,8 @@ automatically from GitLab 16.0 onwards. ### Slack notifications integration <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- End of Support: GitLab <span class="milestone">17.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/372411). </div> @@ -642,9 +681,8 @@ we'll be introducing support in [this epic](https://gitlab.com/groups/gitlab-org ### Support for REST API endpoints that reset runner registration tokens <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.7</span> -- End of Support: GitLab <span class="milestone">17.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.7</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/383341). </div> @@ -670,8 +708,8 @@ From GitLab 17.0 and later, the runner registration methods implemented by the n ### The GitLab legacy requirement IID is deprecated in favor of work item IID <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390263). </div> @@ -684,8 +722,8 @@ We will be transitioning to a new IID as a result of moving requirements to a [w ### The Visual Reviews tool is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/387751). </div> @@ -698,9 +736,8 @@ Due to limited customer usage and capabilities, the Visual Reviews feature for R ### The `gitlab-runner exec` command is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.7</span> -- End of Support: GitLab <span class="milestone">17.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.7</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/385235). </div> @@ -713,8 +750,8 @@ The [`gitlab-runner exec`](https://docs.gitlab.com/runner/commands/#gitlab-runne ### The pull-based deployment features of the GitLab agent for Kubernetes is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.2</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.2</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/406545). </div> @@ -731,8 +768,8 @@ If you use the agent for pull-based deployments, you should [migrate to Flux](ht ### Trigger jobs can mirror downstream pipeline status exactly <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/285493). </div> @@ -742,11 +779,25 @@ In some cases, like when a downstream pipeline had the `passed with warnings` st <div class="deprecation breaking-change" data-milestone="17.0"> +### Twitter OmniAuth login option is deprecated from self-managed GitLab + +<div class="deprecation-notes"> +- Announced in GitLab <span class="milestone">16.3</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) +- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-com/Product/-/issues/11417). +</div> + +Twitter OAuth 1.0a OmniAuth is deprecated and will be removed for self-managed GitLab instances in GitLab 17.0 due to low use and lack of gem support. Use [another supported OmniAuth provider](https://docs.gitlab.com/ee/integration/omniauth.html#supported-providers) instead. + +</div> + +<div class="deprecation breaking-change" data-milestone="17.0"> + ### Unified approval rules are deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.1</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.1</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/groups/gitlab-org/-/epics/9662). </div> @@ -765,8 +816,8 @@ You can still access unified approval rules with the API. ### Vulnerability confidence field <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.4</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.4</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/372332). </div> @@ -782,9 +833,8 @@ removed in 17.0. ### `runnerRegistrationToken` parameter for GitLab Runner Helm Chart <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.6</span> -- End of Support: GitLab <span class="milestone">17.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.6</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/381111). </div> @@ -803,8 +853,8 @@ From GitLab 17.0 and later, the methods to register runners introduced by the ne ### `sidekiq` delivery method for `incoming_email` and `service_desk_email` is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.0</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/398132). </div> @@ -849,8 +899,8 @@ We hope this will simplify infrastructure setup and add several improvements to ### project.pipeline.securityReportFindings GraphQL query <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.1</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.1</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/343475). </div> @@ -868,7 +918,8 @@ Previous work helped [align the vulnerabilities calls for pipeline security tabs ### Adding non-LDAP synced members to a locked LDAP group is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.0</span> +- Announced in GitLab <span class="milestone">16.0</span> +- Removal in GitLab <span class="milestone">16.5</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213311). </div> @@ -881,8 +932,8 @@ Enabling the `ldap_settings_unlock_groups_by_owners` feature flag allowed non-LD ### HashiCorp Vault integration will no longer use CI_JOB_JWT by default <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.5</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/366798). </div> @@ -910,8 +961,8 @@ In GitLab 16.0 and later: ### Old versions of JSON web tokens are deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.5</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/366798). </div> @@ -957,9 +1008,8 @@ be available in CI/CD jobs. ### Bundled Grafana deprecated and disabled <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.0</span> -- End of Support: GitLab <span class="milestone">16.3</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.0</span> +- Removal in GitLab <span class="milestone">16.3</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7772). </div> @@ -983,8 +1033,8 @@ However, enabling the bundled Grafana will no longer work from GitLab 16.3. ### License Compliance CI Template <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.3</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/387561). </div> @@ -999,6 +1049,20 @@ The GitLab [License Compliance](https://docs.gitlab.com/ee/user/compliance/licen | LS template is included but DS template is not | License data from LS job is used | License data from LS job is used | No license data | </div> + +<div class="deprecation breaking-change" data-milestone="16.3"> + +### Twitter OmniAuth login option is removed from GitLab.com + +<div class="deprecation-notes"> +- Announced in GitLab <span class="milestone">16.3</span> +- Removal in GitLab <span class="milestone">16.3</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) +- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-com/Product/-/issues/11417). +</div> + +Twitter OAuth 1.0a OmniAuth is being deprecated and removed on GitLab.com in GitLab 16.3 due to low use, lack of gem support, and the lack of a functional sign-in option for this feature. If you sign into GitLab.com with Twitter, you can sign in with a password or another [supported OmniAuth provider](https://gitlab.com/users/sign_in). + +</div> </div> <div class="milestone-wrapper" data-milestone="16.1"> @@ -1010,8 +1074,9 @@ The GitLab [License Compliance](https://docs.gitlab.com/ee/user/compliance/licen ### GitLab Runner images based on Alpine 3.12, 3.13, 3.14 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.11</span> -- End of Support: GitLab <span class="milestone">16.1</span> +- Announced in GitLab <span class="milestone">15.11</span> +- End of Support in GitLab <span class="milestone">16.1</span> +- Removal in GitLab <span class="milestone">16.1</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/29639). </div> @@ -1033,8 +1098,8 @@ We will stop publishing runner images based on the following, end-of-life Alpine ### Auto DevOps no longer provisions a PostgreSQL database by default <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/343988). </div> @@ -1052,8 +1117,8 @@ set the `POSTGRES_ENABLED` CI/CD variable to `true`. ### Azure Storage Driver defaults to the correct root prefix <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/container-registry/-/issues/854). </div> @@ -1070,8 +1135,8 @@ This breaking change will happen in GitLab 16.0. ### Bundled Grafana Helm Chart is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.10</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.10</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/4353). </div> @@ -1093,8 +1158,8 @@ and [connect Grafana to the GitLab UI](https://docs.gitlab.com/ee/administration ### CAS OmniAuth provider <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.3</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.3</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/369127). </div> @@ -1109,8 +1174,8 @@ release, GitLab 16.0. This gem sees very little use and its lack of upstream mai ### CI/CD jobs will fail when no secret is returned from Hashicorp Vault <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/353080). </div> @@ -1123,8 +1188,8 @@ When using the native HashiCorp Vault integration, CI/CD jobs will fail when no ### Changing MobSF-based SAST analyzer behavior in multi-module Android projects <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">16.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">16.0</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/408396). </div> @@ -1140,8 +1205,8 @@ Instead of changing which single module would be scanned, we [improved multi-mod ### Changing merge request approvals with the `/approvals` API endpoint <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.0</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/353097). </div> @@ -1156,8 +1221,8 @@ Instead, use the [`/approval_rules` endpoint](https://docs.gitlab.com/ee/api/mer ### Conan project-level search endpoint returns project-specific results <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/384455). </div> @@ -1172,9 +1237,8 @@ This unintended functionality is deprecated in GitLab 15.8 and will be removed i ### Configuration fields in GitLab Runner Helm Chart <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.6</span> -- End of Support: GitLab <span class="milestone">16.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.6</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/379064). </div> @@ -1187,8 +1251,8 @@ From GitLab 13.6, users can [specify any runner configuration in the GitLab Runn ### Configuring Redis config file paths using environment variables is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/388255). </div> @@ -1205,8 +1269,8 @@ config file locations instead, for example `config/redis.cache.yml` or ### Container Registry pull-through cache <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/container-registry/-/issues/842). </div> @@ -1219,8 +1283,8 @@ The Container Registry [pull-through cache](https://docs.docker.com/registry/rec ### Container Scanning variables that reference Docker <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.4</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.4</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/371840). </div> @@ -1233,8 +1297,8 @@ All Container Scanning variables that are prefixed by `DOCKER_` in variable name ### Cookie authorization in the GitLab for Jira Cloud app <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/387299). </div> @@ -1249,8 +1313,8 @@ to continue to use the GitLab for Jira Cloud app. Without OAuth, you can't manag ### DAST API scans using DAST template is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.7</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.7</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/384198). </div> @@ -1263,8 +1327,8 @@ With the move to the new DAST API analyzer and the `DAST-API.gitlab-ci.yml` temp ### DAST API variables <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.7</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.7</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/383467). </div> @@ -1283,8 +1347,8 @@ These two variables will be removed in GitLab 16.0. ### DAST report variables deprecation <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.7</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.7</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/384340). </div> @@ -1299,8 +1363,8 @@ These three variables will be removed in GitLab 16.0. ### Default CI/CD job token (`CI_JOB_TOKEN`) scope changed <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/395708). </div> @@ -1314,6 +1378,8 @@ In 17.0, we plan to remove the **Limit** setting completely, and set the **Allow To prepare for this change, users on GitLab.com or self-managed GitLab 15.9 or later can enable the **Allow access** setting now and add the other projects. It will not be possible to disable the setting in 17.0 or later. +In 16.3, the names of these settings were changed to clarify their meanings: the deprecated **Limit CI_JOB_TOKEN access** setting is now called **Limit access _from_ this project**, and the newer **Allow access to this project with a CI_JOB_TOKEN** setting is now called **Limit access _to_ this project**. + </div> <div class="deprecation breaking-change" data-milestone="16.0"> @@ -1321,8 +1387,8 @@ To prepare for this change, users on GitLab.com or self-managed GitLab 15.9 or l ### Dependency Scanning support for Java 13, 14, 15, and 16 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/387560). </div> @@ -1335,8 +1401,8 @@ GitLab has deprecated Dependency Scanning support for Java versions 13, 14, 15, ### Deployment API returns error when `updated_at` and `updated_at` are not used together <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/328500). </div> @@ -1349,8 +1415,8 @@ The Deployment API will now return an error when `updated_at` filtering and `upd ### Deprecate legacy Gitaly configuration methods <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352609). </div> @@ -1367,8 +1433,8 @@ GitLab instances that use `GIT_CONFIG_SYSTEM` and `GIT_CONFIG_GLOBAL` to configu ### Deprecated Consul http metrics <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.10</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.10</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7278). </div> @@ -1387,9 +1453,8 @@ For more information, see [the deprecation notes for Consul 1.9.0](https://githu ### Deprecation and planned removal for `CI_PRE_CLONE_SCRIPT` variable on GitLab SaaS <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- End of Support: GitLab <span class="milestone">16.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/391896). </div> @@ -1402,8 +1467,8 @@ The [`CI_PRE_CLONE_SCRIPT` variable](https://docs.gitlab.com/ee/ci/runners/saas/ ### Developer role providing the ability to import projects to a group <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/387891). </div> @@ -1418,8 +1483,8 @@ will be able to import projects to that group. ### Development dependencies reported for PHP and Python <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/375505). </div> @@ -1432,8 +1497,8 @@ In GitLab 16.0 the GitLab Dependency Scanning analyzer will begin reporting deve ### Embedding Grafana panels in Markdown is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/389477). </div> @@ -1447,8 +1512,8 @@ We intend to replace this feature with the ability to [embed charts](https://git ### Enforced validation of CI/CD parameter character lengths <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/372770). </div> @@ -1469,8 +1534,8 @@ Users on self-managed instances should update their pipelines to ensure they do ### Environment search query requires at least three characters <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.10</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.10</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/382532). </div> @@ -1483,8 +1548,8 @@ From GitLab 16.0, when you search for environments with the API, you must use at ### External field in GraphQL ReleaseAssetLink type <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> In the [GraphQL API](https://docs.gitlab.com/ee/api/graphql/), the `external` field of [`ReleaseAssetLink` type](https://docs.gitlab.com/ee/api/graphql/reference/index.html#releaseassetlink) was used to indicate whether a [release link](https://docs.gitlab.com/ee/user/project/releases/release_fields.html#links) is internal or external to your GitLab instance. @@ -1498,8 +1563,8 @@ To avoid any disruptions to your workflow, please stop using the `external` fiel ### External field in Releases and Release Links APIs <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> In [Releases API](https://docs.gitlab.com/ee/api/releases/) and [Release Links API](https://docs.gitlab.com/ee/api/releases/links.html), the `external` field was used to indicate whether a [release link](https://docs.gitlab.com/ee/user/project/releases/release_fields.html#links) is internal or external to your GitLab instance. @@ -1513,7 +1578,8 @@ To avoid any disruptions to your workflow, please stop using the `external` fiel ### Geo: Project repository redownload is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.11</span> +- Announced in GitLab <span class="milestone">15.11</span> +- Removal in GitLab <span class="milestone">16.0</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/388868). </div> @@ -1529,8 +1595,8 @@ GitLab 16.0. ### GitLab self-monitoring project <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/348909). </div> @@ -1543,7 +1609,8 @@ GitLab self-monitoring gives administrators of self-hosted GitLab instances the ### GitLab.com importer <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-com/Product/-/issues/4895). </div> @@ -1562,8 +1629,8 @@ See [migrated group items](https://docs.gitlab.com/ee/user/group/import/#migrate ### GraphQL API Runner status will not return `paused` <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/344648). </div> @@ -1583,8 +1650,8 @@ When checking if a runner is `paused`, API users are advised to check the boolea ### GraphQL API legacyMode argument for Runner status <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.0</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/360545). </div> @@ -1602,8 +1669,8 @@ be present during the 16.x cycle to avoid breaking the API signature, and will b ### GraphQL field `confidential` changed to `internal` on notes <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.5</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/371485). </div> @@ -1616,8 +1683,8 @@ The `confidential` field for a `Note` will be deprecated and renamed to `interna ### Jira DVCS connector for Jira Cloud <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.1</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.1</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/groups/gitlab-org/-/epics/7508). </div> @@ -1632,9 +1699,8 @@ The Jira DVCS connector is also deprecated for Jira 8.13 and earlier. You can on ### KAS Metrics Port in GitLab Helm Chart <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.7</span> -- End of Support: GitLab <span class="milestone">16.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.7</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/383039). </div> @@ -1648,8 +1714,8 @@ This port is used for much more than just metrics, which warranted this change t ### Legacy Gitaly configuration method <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.10</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.10</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/393574). </div> @@ -1671,8 +1737,8 @@ You should update to the new configuration structure as soon as possible using ### Legacy Praefect configuration method <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390291). </div> @@ -1693,8 +1759,8 @@ didn't match. The change improves consistency between Omnibus GitLab and source ### Legacy URLs replaced or removed <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214217). </div> @@ -1713,8 +1779,8 @@ Update any scripts or bookmarks that reference the legacy URLs. GitLab APIs are ### License-Check and the Policies tab on the License Compliance page <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390417). </div> @@ -1727,8 +1793,8 @@ The [License-Check feature](https://docs.gitlab.com/ee/user/compliance/license_c ### Limit personal access token and deploy token's access with external authorization <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/387721). </div> @@ -1741,8 +1807,8 @@ With external authorization enabled, personal access tokens (PATs) and deploy to ### Major bundled Helm Chart updates for the GitLab Helm Chart <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.10</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.10</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/3442). </div> @@ -1763,8 +1829,8 @@ The full GitLab Helm Chart 7.0 upgrade steps will be available in the [upgrade d ### Managed Licenses API <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390417). </div> @@ -1777,7 +1843,8 @@ The [Managed Licenses API](https://docs.gitlab.com/ee/api/managed_licenses.html) ### Maximum number of active pipelines per project limit (`ci_active_pipelines`) <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.3</span> +- Announced in GitLab <span class="milestone">15.3</span> +- Removal in GitLab <span class="milestone">16.0</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/368195). </div> @@ -1793,8 +1860,8 @@ The [**Maximum number of active pipelines per project** limit](https://docs.gitl ### Monitor performance metrics through Prometheus <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/346541). </div> @@ -1808,8 +1875,8 @@ However, since certificate-based integration with Kubernetes clusters is depreca ### Non-expiring access tokens <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.4</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.4</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/369122). </div> @@ -1835,8 +1902,8 @@ default is applied: ### Non-standard default Redis ports are deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/388269). </div> @@ -1856,8 +1923,8 @@ and `config/redis.shared_state.yml` files. ### Option to delete projects immediately is deprecated from deletion protection settings <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/389557). </div> @@ -1874,8 +1941,8 @@ The option to delete groups and projects immediately by default was deprecated t ### PipelineSecurityReportFinding name GraphQL field <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.1</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.1</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/346335). </div> @@ -1888,8 +1955,8 @@ Previously, the [PipelineSecurityReportFinding GraphQL type was updated](https:/ ### PostgreSQL 12 deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.0</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/349185). </div> @@ -1908,8 +1975,8 @@ Support for PostgreSQL 13 was added to Geo in GitLab 15.2. ### Projects API field `operations_access_level` is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/385798). </div> @@ -1922,7 +1989,8 @@ We are deprecating the `operations_access_level` field in the Projects API. This ### Rake task for importing bare repositories <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-com/Product/-/issues/5255). </div> @@ -1951,9 +2019,9 @@ Alternatives to using the `gitlab:import:repos` Rake task include: ### Redis 5 deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.3</span> -- End of Support: GitLab <span class="milestone">15.6</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.3</span> +- End of Support in GitLab <span class="milestone">15.6</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/331468). </div> @@ -1968,8 +2036,8 @@ If you are using your own Redis 5.0 instance, you should upgrade it to Redis 6.0 ### Remove `job_age` parameter from `POST /jobs/request` Runner endpoint <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.2</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.2</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/334253). </div> @@ -1984,8 +2052,8 @@ This could be a breaking change for anyone that developed their own runner that ### SAST analyzer coverage changing in GitLab 16.0 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390416). </div> @@ -2024,8 +2092,8 @@ Work to replace the PHPCS Security Audit-based analyzer is tracked in [issue 364 ### Secure analyzers major version update <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390912). </div> @@ -2067,8 +2135,8 @@ Specifically, the following are being deprecated and will no longer be updated a ### Secure scanning CI/CD templates will use new job `rules` <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/391822). </div> @@ -2102,8 +2170,8 @@ However, due to compatibility issues [discussed in the deprecation issue](https: ### Security report schemas version 14.x.x <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.3</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.3</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/366477). </div> @@ -2122,9 +2190,8 @@ For more information, refer to [security report validation](https://docs.gitlab. ### Shimo integration <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.7</span> -- End of Support: GitLab <span class="milestone">16.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.7</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/377824). </div> @@ -2138,8 +2205,8 @@ and will be moved to the JiHu GitLab codebase. ### Starboard directive in the config for the GitLab Agent for Kubernetes <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.4</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.4</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/368828). </div> @@ -2152,8 +2219,8 @@ GitLab's operational container scanning capabilities no longer require starboard ### Support for Praefect custom metrics endpoint configuration <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.9</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390266). </div> @@ -2174,9 +2241,8 @@ This may require updating your metrics collection targets to also scrape `/db_me ### Support for periods (`.`) in Terraform state names might break existing states <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.7</span> -- End of Support: GitLab <span class="milestone">16.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.7</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/385564). </div> @@ -2199,8 +2265,8 @@ To use the full state name, including the period, [migrate to the full state fil ### The API no longer returns revoked tokens for the agent for Kubernetes <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/382129). </div> @@ -2224,8 +2290,8 @@ This change affects the following REST and GraphQL API endpoints: ### The Phabricator task importer is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.7</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.7</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-com/Product/-/issues/4894). </div> @@ -2238,8 +2304,8 @@ The [Phabricator task importer](https://docs.gitlab.com/ee/user/project/import/p ### The latest Terraform templates will overwrite current stable templates <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/386001). </div> @@ -2261,8 +2327,8 @@ To accommodate the changes, you might need to adjust the [`rules`](https://docs. ### Toggle behavior of `/draft` quick action in merge requests <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.4</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.4</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/365365). </div> @@ -2275,8 +2341,8 @@ In order to make the behavior of toggling the draft status of a merge request mo ### Toggle notes confidentiality on APIs <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.10</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.10</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/350670). </div> @@ -2289,8 +2355,8 @@ Toggling notes confidentiality with REST and GraphQL APIs is being deprecated. U ### Use of `id` field in vulnerabilityFindingDismiss mutation <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.3</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.3</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/367166). </div> @@ -2303,9 +2369,8 @@ You can use the vulnerabilityFindingDismiss GraphQL mutation to set the status o ### Use of third party container registries is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- End of Support: GitLab <span class="milestone">16.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376216). </div> @@ -2326,8 +2391,8 @@ Moving forward, we'll continue to invest in developing and releasing new feature ### Work items path with global ID at the end of the path is deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.10</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.10</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/393836). </div> @@ -2347,9 +2412,8 @@ In GitLab 16.0 we will remove the ability to use a global ID in the work items p ### ZenTao integration <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.7</span> -- End of Support: GitLab <span class="milestone">16.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.7</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/377825). </div> @@ -2363,8 +2427,8 @@ and will be moved to the JiHu GitLab codebase. ### `CI_BUILD_*` predefined variables <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352957). </div> @@ -2392,8 +2456,8 @@ The predefined CI/CD variables that start with `CI_BUILD_*` were deprecated in G ### `POST ci/lint` API endpoint deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.7</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.7</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/381669). </div> @@ -2406,8 +2470,8 @@ The `POST ci/lint` API endpoint is deprecated in 15.7, and will be removed in 16 ### `environment_tier` parameter for DORA API <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/365939). </div> @@ -2420,8 +2484,8 @@ To avoid confusion and duplication, the `environment_tier` parameter is deprecat ### `started` iteration state <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/334018). </div> @@ -2440,8 +2504,8 @@ We plan to continue to support the `started` state in REST API version until the ### vulnerabilityFindingDismiss GraphQL mutation <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.5</span> +- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/375645). </div> @@ -2459,7 +2523,8 @@ The `VulnerabilityFindingDismiss` GraphQL mutation is being deprecated and will ### openSUSE Leap 15.3 packages <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">15.11</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7371). </div> @@ -2481,13 +2546,12 @@ Starting in GitLab 15.7 we started providing packages for openSUSE Leap 15.4, an ### Automatic backup upload using Openstack Swift and Rackspace APIs <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- End of Support: GitLab <span class="milestone">15.10</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">15.10</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/387976). </div> -We are deprecating support for [uploading backups to remote storage](https://docs.gitlab.com/ee/raketasks/backup_gitlab.html#upload-backups-to-a-remote-cloud-storage) using Openstack Swift and Rackspace APIs. The support for these APIs depends on third-party libraries that are no longer actively maintained and have not been updated for Ruby 3. GitLab is switching over to Ruby 3 prior to EOL of Ruby 2 in order to stay up to date on security patches. +We are deprecating support for [uploading backups to remote storage](https://docs.gitlab.com/ee/raketasks/backup_gitlab.html#upload-backups-to-a-remote-cloud-storage) using Openstack Swift and Rackspace APIs. The support for these APIs depends on third-party libraries that are no longer actively maintained and have not been updated for Ruby 3. GitLab is switching over to Ruby 3 prior to EOL of Ruby 2 in order to stay up to date on security patches. - If you're using OpenStack, you need to change you configuration to use the S3 API instead of Swift. - If you're using Rackspace storage, you need to switch to a different provider or manually upload the backup file after the backup task is complete. @@ -2504,8 +2568,8 @@ We are deprecating support for [uploading backups to remote storage](https://doc ### Live Preview no longer available in the Web IDE <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.8</span> +- Removal in GitLab <span class="milestone">15.9</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/383889). </div> @@ -2518,8 +2582,8 @@ The Live Preview feature of the Web IDE was intended to provide a client-side pr ### SaaS certificate-based integration with Kubernetes <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">15.9</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). </div> @@ -2547,8 +2611,8 @@ GitLab self-managed customers can still use the feature [with a feature flag](ht ### File Type variable expansion in `.gitlab-ci.yml` <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">15.5</span> +- Removal in GitLab <span class="milestone">15.7</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/29407). </div> @@ -2568,7 +2632,8 @@ This breaking change fixes this issue but could disrupt user workflows that work ### NFS for Git repository storage <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.0</span> +- Announced in GitLab <span class="milestone">14.0</span> +- Removal in GitLab <span class="milestone">15.6</span> </div> With the general availability of Gitaly Cluster ([introduced in GitLab 13.0](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/)), we have deprecated development (bugfixes, performance improvements, etc) for NFS for Git repository storage in GitLab 14.0. We will continue to provide technical support for NFS for Git repositories throughout 14.x, but we will remove all support for NFS on November 22, 2022. This was originally planned for May 22, 2022, but in an effort to allow continued maturity of Gitaly Cluster, we have chosen to extend our deprecation of support date. Please see our official [Statement of Support](https://about.gitlab.com/support/statement-of-support/#gitaly-and-nfs) for further information. @@ -2593,7 +2658,8 @@ We encourage customers currently using NFS for Git repositories to plan their mi ### Bundled Grafana deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.3</span> +- Announced in GitLab <span class="milestone">15.3</span> +- Removal in GitLab <span class="milestone">15.4</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6972). </div> @@ -2610,8 +2676,8 @@ This is not expected to cause any incompatibilities with the previous version of ### SAST analyzer consolidation and CI/CD template changes <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.4</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352554). </div> @@ -2659,7 +2725,8 @@ If you applied customizations to any of the affected analyzers or if you current ### Vulnerability Report sort by State <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.0</span> +- Announced in GitLab <span class="milestone">15.0</span> +- Removal in GitLab <span class="milestone">15.3</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/360516). </div> @@ -2674,7 +2741,8 @@ by this value remains performant. Due to very low usage of the `State` column fo ### Vulnerability Report sort by Tool <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">15.1</span> +- Announced in GitLab <span class="milestone">15.1</span> +- Removal in GitLab <span class="milestone">15.3</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/362962). </div> @@ -2695,7 +2763,8 @@ GitLab 15.3 to simplify the codebase and prevent any unwanted performance degrad ### Deprecate support for Debian 9 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.9</span> +- Announced in GitLab <span class="milestone">14.9</span> +- Removal in GitLab <span class="milestone">15.1</span> </div> Long term service and support (LTSS) for [Debian 9 Stretch ends in July 2022](https://wiki.debian.org/LTS). Therefore, we will no longer support the Debian 9 distribution for the GitLab package. Users can upgrade to Debian 10 or Debian 11. @@ -2712,8 +2781,8 @@ Long term service and support (LTSS) for [Debian 9 Stretch ends in July 2022](ht ### Audit events for repository push events <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.3</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.3</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337993). </div> @@ -2730,8 +2799,8 @@ dramatically slow down GitLab instances. For this reason, they are being removed ### Background upload for object storage <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.9</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/26600). </div> @@ -2751,8 +2820,8 @@ GitLab will publish additional guidance to assist affected customers in migratin ### CI/CD job name length limit <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.6</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.6</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/342800). </div> @@ -2765,8 +2834,8 @@ In GitLab 15.0 we are going to limit the number of characters in CI/CD job names ### Changing an instance (shared) runner to a project (specific) runner <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/345347). </div> @@ -2783,8 +2852,8 @@ Administrators who need to add runners for multiple projects can register a runn ### Container Network and Host Security <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> All functionality related to GitLab's Container Network Security and Container Host Security categories is deprecated in GitLab 14.8 and scheduled for removal in GitLab 15.0. Users who need a replacement for this functionality are encouraged to evaluate the following open source projects as potential solutions that can be installed and managed outside of GitLab: [AppArmor](https://gitlab.com/apparmor/apparmor), [Cilium](https://github.com/cilium/cilium), [Falco](https://github.com/falcosecurity/falco), [FluentD](https://github.com/fluent/fluentd), [Pod Security Admission](https://kubernetes.io/docs/concepts/security/pod-security-admission/). To integrate these technologies into GitLab, add the desired Helm charts into your copy of the [Cluster Management Project Template](https://docs.gitlab.com/ee/user/clusters/management_project_template.html). Deploy these Helm charts in production by calling commands through GitLab [CI/CD](https://docs.gitlab.com/ee/user/clusters/agent/ci_cd_workflow.html). @@ -2805,7 +2874,8 @@ For additional context, or to provide feedback regarding this change, please ref ### Container scanning schemas below 14.0.0 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">15.0</span> </div> [Container scanning report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) @@ -2826,7 +2896,8 @@ in the Vulnerability Report. ### Coverage guided fuzzing schemas below 14.0.0 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">15.0</span> </div> [Coverage guided fuzzing report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) @@ -2850,7 +2921,8 @@ in the Vulnerability Report. ### DAST schemas below 14.0.0 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">15.0</span> </div> [DAST report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) @@ -2874,8 +2946,8 @@ in the Vulnerability Report. ### Dependency Scanning Python 3.9 and 3.6 image deprecation <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/334060). </div> @@ -2906,8 +2978,8 @@ gemnasium-python-dependency_scanning: ### Dependency Scanning default Java version changed to 17 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.10</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.10</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> In GitLab 15.0, for Dependency Scanning, the default version of Java that the scanner expects will be updated from 11 to 17. Java 17 is [the most up-to-date Long Term Support (LTS) version](https://en.wikipedia.org/wiki/Java_version_history). Dependency scanning continues to support the same [range of versions (8, 11, 13, 14, 15, 16, 17)](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/#supported-languages-and-package-managers), only the default version is changing. If your project uses the previous default of Java 11, be sure to [set the `DS_Java_Version` variable to match](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/#configuring-specific-analyzers-used-by-dependency-scanning). @@ -2919,7 +2991,8 @@ In GitLab 15.0, for Dependency Scanning, the default version of Java that the sc ### Dependency scanning schemas below 14.0.0 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">15.0</span> </div> [Dependency scanning report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) @@ -2943,7 +3016,8 @@ in the Vulnerability Report. ### Deprecate Geo Admin UI Routes <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/351345). </div> @@ -2956,7 +3030,8 @@ In GitLab 13.0, we introduced new project and design replication details routes ### Deprecate custom Geo:db:* Rake tasks <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/351945). </div> @@ -2988,8 +3063,8 @@ The following `geo:db:*` tasks will be replaced with their corresponding `db:*:g ### Deprecate feature flag PUSH_RULES_SUPERSEDE_CODE_OWNERS <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/262019). </div> @@ -3002,8 +3077,8 @@ The feature flag `PUSH_RULES_SUPERSEDE_CODE_OWNERS` is being removed in GitLab 1 ### Elasticsearch 6.8 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/350275). </div> @@ -3020,7 +3095,8 @@ Elasticsearch 6.8 is also incompatible with Amazon OpenSearch, which we [plan to ### Enforced validation of security report schemas <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">15.0</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/groups/gitlab-org/-/epics/6968). </div> @@ -3045,8 +3121,8 @@ in the Vulnerability Report. ### External status check API breaking changes <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> The [external status check API](https://docs.gitlab.com/ee/api/status_checks.html) was originally implemented to @@ -3072,7 +3148,8 @@ To align with this change, API calls to list external status checks will also re ### GitLab Pages running as daemon <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.9</span> +- Announced in GitLab <span class="milestone">14.9</span> +- Removal in GitLab <span class="milestone">15.0</span> </div> In 15.0, support for daemon mode for GitLab Pages will be removed. @@ -3084,8 +3161,8 @@ In 15.0, support for daemon mode for GitLab Pages will be removed. ### GitLab Serverless <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.3</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.3</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/groups/gitlab-org/configure/-/epics/6). </div> @@ -3100,7 +3177,8 @@ We decided to remove the GitLab Serverless features as they never really resonat ### Godep support in License Compliance <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">15.0</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/327057). </div> @@ -3116,8 +3194,8 @@ and will remove it in GitLab 15.0 ### GraphQL ID and GlobalID compatibility <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/257883). </div> @@ -3180,8 +3258,8 @@ an inline argument expression). ### GraphQL permissions change for Package settings <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.9</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> The GitLab Package stage offers a Package Registry, Container Registry, and Dependency Proxy to help you manage all of your dependencies using GitLab. Each of these product categories has a variety of settings that can be adjusted using the API. @@ -3200,8 +3278,8 @@ The permissions model for GraphQL is being updated. After 15.0, users with the G ### Known host required for GitLab Runner SSH executor <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28192). </div> @@ -3216,8 +3294,8 @@ In GitLab 15.0 and later, the default value for this configuration option will c ### Legacy approval status names from License Compliance API <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.6</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.6</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/335707). </div> @@ -3232,8 +3310,8 @@ If you are using our License Compliance API you should stop using the `approved` ### Legacy database configuration <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.3</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.3</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/338182). </div> @@ -3250,8 +3328,8 @@ This deprecation mainly impacts users compiling GitLab from source because Omnib ### Logging in GitLab <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/346485). </div> @@ -3264,7 +3342,8 @@ The logging features in GitLab allow users to install the ELK stack (Elasticsear ### Move `custom_hooks_dir` setting from GitLab Shell to Gitaly <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.9</span> +- Announced in GitLab <span class="milestone">14.9</span> +- Removal in GitLab <span class="milestone">15.0</span> </div> The [`custom_hooks_dir`](https://docs.gitlab.com/ee/administration/server_hooks.html#create-a-global-server-hook-for-all-repositories) setting is now configured in Gitaly, and will be removed from GitLab Shell in GitLab 15.0. @@ -3276,8 +3355,8 @@ The [`custom_hooks_dir`](https://docs.gitlab.com/ee/administration/server_hooks. ### OAuth implicit grant <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.0</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.0</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> The OAuth implicit grant authorization flow will be removed in our next major release, GitLab 15.0. Any applications that use OAuth implicit grant should switch to alternative [supported OAuth flows](https://docs.gitlab.com/ee/api/oauth2.html). @@ -3289,8 +3368,8 @@ The OAuth implicit grant authorization flow will be removed in our next major re ### OAuth tokens without expiration <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> By default, all new applications expire access tokens after 2 hours. In GitLab 14.2 and earlier, OAuth access tokens @@ -3310,8 +3389,8 @@ tokens before GitLab 15.0 is released: ### OmniAuth Kerberos gem <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.3</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.3</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337384). </div> @@ -3328,8 +3407,8 @@ Note that we are not deprecating the Kerberos SPNEGO integration, only the old p ### Optional enforcement of PAT expiration <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/351962). </div> @@ -3344,8 +3423,8 @@ Unexpected behavior in a security feature is inherently dangerous, so we have de ### Optional enforcement of SSH expiration <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/351963). </div> @@ -3360,8 +3439,8 @@ Unexpected behavior in a security feature is inherently dangerous, so we have de ### Out-of-the-box SAST support for Java 8 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352549). </div> @@ -3385,8 +3464,8 @@ If you rely on Java 8 being present in the analyzer environment, you must take a ### Outdated indices of Advanced Search migrations <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.10</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.10</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/359133). </div> @@ -3402,7 +3481,8 @@ time to remove backward compatibility for indices that have not been fully migra ### Pseudonymizer <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">15.0</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/219952). </div> @@ -3418,8 +3498,8 @@ It is now considered deprecated, and will be removed in GitLab 15.0. ### Querying Usage Trends via the `instanceStatisticsMeasurements` GraphQL node <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/332323). </div> @@ -3432,8 +3512,8 @@ The `instanceStatisticsMeasurements` GraphQL node has been renamed to `usageTren ### Request profiling <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352488). </div> @@ -3452,8 +3532,8 @@ For more information, check the [summary section of the deprecation issue](https ### Required pipeline configurations in Premium tier <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> The [required pipeline configuration](https://docs.gitlab.com/ee/administration/settings/continuous_integration.html#required-pipeline-configuration) feature is deprecated in GitLab 14.8 for Premium customers and is scheduled for removal in GitLab 15.0. This feature is not deprecated for GitLab Ultimate customers. @@ -3470,8 +3550,8 @@ This change will also help GitLab remain consistent in its tiering strategy with ### Retire-JS Dependency Scanning tool <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/350510). </div> @@ -3486,7 +3566,8 @@ If you have explicitly excluded retire.js using DS_EXCLUDED_ANALYZERS you will n ### SAST schemas below 14.0.0 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">15.0</span> </div> [SAST report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) @@ -3510,8 +3591,8 @@ in the Vulnerability Report. ### SAST support for .NET 2.1 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352553). </div> @@ -3542,7 +3623,8 @@ If you rely on .NET 2.1 support being present in the analyzer image by default, ### Secret Detection configuration variables deprecated <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352565). </div> @@ -3570,7 +3652,8 @@ For further details, see [the deprecation issue for this change](https://gitlab. ### Secret detection schemas below 14.0.0 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">15.0</span> </div> [Secret detection report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) @@ -3594,8 +3677,8 @@ in the Vulnerability Report. ### Secure and Protect analyzer images published in new location <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352564). </div> @@ -3622,8 +3705,8 @@ See the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352564 ### Secure and Protect analyzer major version update <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/350936). </div> @@ -3667,8 +3750,8 @@ Specifically, the following are being deprecated and will no longer be updated a ### Sidekiq metrics and health checks configuration <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/347509). </div> @@ -3699,7 +3782,8 @@ to serve the Sidekiq metrics, similar to the way Sidekiq will behave in 15.0. ### Static Site Editor <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">15.0</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/347137). </div> @@ -3714,8 +3798,8 @@ Current users of the Static Site Editor can view the [documentation](https://doc ### Support for SLES 12 SP2 <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> Long term service and support (LTSS) for SUSE Linux Enterprise Server (SLES) 12 SP2 [ended on March 31, 2021](https://www.suse.com/lifecycle/). The CA certificates on SP2 include the expired DST root certificate, and it's not getting new CA certificate package updates. We have implemented some [workarounds](https://gitlab.com/gitlab-org/gitlab-omnibus-builder/-/merge_requests/191), but we will not be able to continue to keep the build running properly. @@ -3727,8 +3811,8 @@ Long term service and support (LTSS) for SUSE Linux Enterprise Server (SLES) 12 ### Support for gRPC-aware proxy deployed between Gitaly and rest of GitLab <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> Although not recommended or documented, it was possible to deploy a gRPC-aware proxy between Gitaly and @@ -3750,8 +3834,8 @@ the [relevant epic](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/463). ### Test coverage project CI/CD setting <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> To simplify setting a test coverage pattern, in GitLab 15.0 the @@ -3768,8 +3852,8 @@ testing coverage results in merge requests. ### Tracing in GitLab <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/346540). </div> @@ -3782,8 +3866,8 @@ Tracing in GitLab is an integration with Jaeger, an open-source end-to-end distr ### Update to the Container Registry group-level API <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336912). </div> @@ -3798,8 +3882,8 @@ The `GET /groups/:id/registry/repositories` endpoint will remain, but won't retu ### Value Stream Analytics filtering calculation change <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/343210). </div> @@ -3814,8 +3898,8 @@ If you monitor Value Stream Analytics metrics and rely on the date filter, to av ### Vulnerability Check <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> The vulnerability check feature is deprecated in GitLab 14.8 and scheduled for removal in GitLab 15.0. We encourage you to migrate to the new security approvals feature instead. You can do so by navigating to **Security & Compliance > Policies** and creating a new Scan Result Policy. @@ -3834,8 +3918,8 @@ The new security approvals feature is similar to vulnerability check. For exampl ### `Versions` on base `PackageType` <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/327453). </div> @@ -3850,8 +3934,8 @@ In milestone 15.0, we will completely remove `Version` from `PackageType`. ### `artifacts:reports:cobertura` keyword <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.7</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.7</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/348980). </div> @@ -3867,8 +3951,8 @@ only supported report file in 15.0, but this is the first step towards GitLab su ### `defaultMergeCommitMessageWithDescription` GraphQL API field <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/345451). </div> @@ -3881,8 +3965,8 @@ The GraphQL API field `defaultMergeCommitMessageWithDescription` has been deprec ### `dependency_proxy_for_private_groups` feature flag <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/276777). </div> @@ -3897,8 +3981,8 @@ In milestone 15.0, we will remove the feature flag entirely. Moving forward, you ### `pipelines` field from the `version` field <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/342882). </div> @@ -3916,8 +4000,8 @@ To mitigate possible performance problems, we will remove the `versions` field's ### `projectFingerprint` in `PipelineSecurityReportFinding` GraphQL <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> The `projectFingerprint` field in the [PipelineSecurityReportFinding](https://docs.gitlab.com/ee/api/graphql/reference/index.html#pipelinesecurityreportfinding) @@ -3932,8 +4016,8 @@ exposed in the UUID field. Data previously available in the projectFingerprint f ### `promote-db` command from `gitlab-ctl` <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/345207). </div> @@ -3946,8 +4030,8 @@ In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Ge ### `promote-to-primary-node` command from `gitlab-ctl` <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/345207). </div> @@ -3960,8 +4044,8 @@ In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Ge ### `type` and `types` keyword in CI/CD configuration <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.6</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.6</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> The `type` and `types` CI/CD keywords will be removed in GitLab 15.0. Pipelines that use these keywords will stop working, so you must switch to `stage` and `stages`, which have the same behavior. @@ -3973,8 +4057,8 @@ The `type` and `types` CI/CD keywords will be removed in GitLab 15.0. Pipelines ### apiFuzzingCiConfigurationCreate GraphQL mutation <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.6</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.6</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/333233). </div> @@ -3989,8 +4073,8 @@ which isn't being used in GitLab anymore. ### bundler-audit Dependency Scanning tool <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.6</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.6</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/289832). </div> @@ -4005,8 +4089,8 @@ If you have explicitly excluded bundler-audit using DS_EXCLUDED_ANALYZERS you wi ### htpasswd Authentication for the Container Registry <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.9</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> The Container Registry supports [authentication](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/configuration.md#auth) with `htpasswd`. It relies on an [Apache `htpasswd` file](https://httpd.apache.org/docs/2.4/programs/htpasswd.html), with passwords hashed using `bcrypt`. @@ -4020,8 +4104,8 @@ Since it isn't used in the context of GitLab (the product), `htpasswd` authentic ### user_email_lookup_limit API field <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.9</span> +- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> The `user_email_lookup_limit` [API field](https://docs.gitlab.com/ee/api/settings.html) is deprecated and will be removed in GitLab 15.0. Until GitLab 15.0, `user_email_lookup_limit` is aliased to `search_rate_limit` and existing workflows will continue to work. @@ -4040,8 +4124,8 @@ Any API calls attempting to change the rate limits for `user_email_lookup_limit` ### Permissions change for downloading Composer dependencies <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.9</span> -- This is a [breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change). +- Announced in GitLab <span class="milestone">14.9</span> +- Removal in GitLab <span class="milestone">14.10</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> The GitLab Composer repository can be used to push, search, fetch metadata about, and download PHP dependencies. All these actions require authentication, except for downloading dependencies. @@ -4060,7 +4144,8 @@ Downloading Composer dependencies without authentication is deprecated in GitLab ### Configurable Gitaly `per_repository` election strategy <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.8</span> +- Announced in GitLab <span class="milestone">14.8</span> +- Removal in GitLab <span class="milestone">14.9</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352612). </div> @@ -4081,7 +4166,8 @@ This change is part of regular maintenance to keep our codebase clean. ### openSUSE Leap 15.2 packages <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.5</span> +- Announced in GitLab <span class="milestone">14.5</span> +- Removal in GitLab <span class="milestone">14.8</span> - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6427). </div> @@ -4101,7 +4187,8 @@ Starting in 14.5 we are providing packages for openSUSE Leap 15.3, and will stop ### Release CLI distributed as a generic package <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.2</span> +- Announced in GitLab <span class="milestone">14.2</span> +- Removal in GitLab <span class="milestone">14.6</span> </div> The [release-cli](https://gitlab.com/gitlab-org/release-cli) will be released as a [generic package](https://gitlab.com/gitlab-org/release-cli/-/packages) starting in GitLab 14.2. We will continue to deploy it as a binary to S3 until GitLab 14.5 and stop distributing it in S3 in GitLab 14.6. @@ -4118,7 +4205,8 @@ The [release-cli](https://gitlab.com/gitlab-org/release-cli) will be released as ### Rename Task Runner pod to Toolbox <div class="deprecation-notes"> -- Announced in: GitLab <span class="milestone">14.2</span> +- Announced in GitLab <span class="milestone">14.2</span> +- Removal in GitLab <span class="milestone">14.5</span> </div> The Task Runner pod is used to execute periodic housekeeping tasks within the GitLab application and is often confused with the GitLab Runner. Thus, [Task Runner will be renamed to Toolbox](https://gitlab.com/groups/gitlab-org/charts/-/epics/25). diff --git a/doc/update/index.md b/doc/update/index.md index ced7ed86691..5a0fd0bdf31 100644 --- a/doc/update/index.md +++ b/doc/update/index.md @@ -16,7 +16,7 @@ The [maintenance policy documentation](../policy/maintenance.md) has additional information about upgrading, including: - How to interpret GitLab product versioning. -- Recommendations on the what release to run. +- Recommendations on what release to run. - How we use patch and security patch releases. - When we backport code changes. @@ -25,12 +25,12 @@ has additional information about upgrading, including: Depending on the installation method and your GitLab version, there are multiple official ways to upgrade GitLab: -- [Linux packages (Omnibus GitLab)](#linux-packages-omnibus-gitlab) -- [Source installations](#installation-from-source) +- [Linux packages (Omnibus)](#linux-packages-omnibus) +- [Self-compiled installations](#self-compiled-installation) - [Docker installations](#installation-using-docker) - [Kubernetes (Helm) installations](#installation-using-helm) -### Linux packages (Omnibus GitLab) +### Linux packages (Omnibus) The [package upgrade guide](package/index.md) contains the steps needed to upgrade a package installed by official GitLab @@ -39,7 +39,7 @@ repositories. There are also instructions when you want to [upgrade to a specific version](package/index.md#upgrade-to-a-specific-version-using-the-official-repositories). -### Installation from source +### Self-compiled installation - [Upgrading Community Edition and Enterprise Edition from source](upgrading_from_source.md) - The guidelines for upgrading Community Edition and Enterprise Edition from source. @@ -114,21 +114,25 @@ This section is only applicable if you have enabled the [Elasticsearch integrati Major releases require all [advanced search migrations](../integration/advanced_search/elasticsearch.md#advanced-search-migrations) to be finished from the most recent minor release in your current version before the major version upgrade. You can find pending migrations by -running the following command: +running the following command. -**For Omnibus installations** +::Tabs + +:::TabTitle Linux package (Omnibus) ```shell sudo gitlab-rake gitlab:elastic:list_pending_migrations ``` -**For installations from source** +:::TabTitle Self-compiled (source) ```shell cd /home/git/gitlab sudo -u git -H bundle exec rake gitlab:elastic:list_pending_migrations ``` +::EndTabs + ### What do you do if your advanced search migrations are stuck? In GitLab 15.0, an advanced search migration named `DeleteOrphanedCommit` can be permanently stuck @@ -176,30 +180,21 @@ A *major* upgrade requires the following steps: Upgrading across multiple GitLab versions in one go is *only possible by accepting downtime*. If you don't want any downtime, read how to [upgrade with zero downtime](zero_downtime.md). -For a dynamic view of examples of supported upgrade paths, try the [Upgrade Path tool](https://gitlab-com.gitlab.io/support/toolbox/upgrade-path/) maintained by the [GitLab Support team](https://about.gitlab.com/handbook/support/#about-the-support-team). To share feedback and help improve the tool, create an issue or MR in the [upgrade-path project](https://gitlab.com/gitlab-com/support/toolbox/upgrade-path). +For a dynamic view of examples of supported upgrade paths, try the [Upgrade Path tool](https://gitlab-com.gitlab.io/support/toolbox/upgrade-path/) +maintained by the [GitLab Support team](https://about.gitlab.com/handbook/support/#about-the-support-team). To share +feedback and help improve the tool, create an issue or MR in the [upgrade-path project](https://gitlab.com/gitlab-com/support/toolbox/upgrade-path). -Required upgrade stops are versions of GitLab that you must upgrade to before upgrading to later versions. Required upgrade stops allow required background -migrations to finish. +When upgrading: -During GitLab 16.x, we are scheduling two or three required upgrade stops. We will give at least two milestones of notice when we -schedule a required upgrade stop. +1. Find where your version sits in the upgrade path: -The first planned required upgrade stop is scheduled for GitLab 16.3. If nothing is introduced requiring an upgrade stop, GitLab 16.3 will be treated as a -regular upgrade. + - GitLab 14: [`14.0.12`](#1400) > [`14.3.6`](#1430) > [`14.9.5`](#1490) > [`14.10.5`](#14100). + - GitLab 15: [`15.0.5`](#1500) > [`15.1.6`](#1510) (for GitLab instances with multiple web nodes) > [`15.4.6`](#1540) > [`15.11.13`](#15110). + - GitLab 16: [`16.0.x`](versions/gitlab_16_changes.md#1600) (only [instances with lots of users](versions/gitlab_16_changes.md#long-running-user-type-data-change)) > [latest `16.Y.Z`](https://gitlab.com/gitlab-org/gitlab/-/releases). -Find where your version sits in the upgrade path below, and upgrade GitLab -accordingly, while also consulting the -[version-specific upgrade instructions](#version-specific-upgrading-instructions): - -- GitLab 8: `8.11.Z` > `8.12.0` > `8.17.7` -- GitLab 9: `9.0.13` > `9.5.10` -- GitLab 10: `10.0.7` > `10.8.7` -- GitLab 11: `11.0.6` > [`11.11.8`](#1200) -- GitLab 12: `12.0.12` > [`12.1.17`](#1210) > [`12.10.14`](#12100) -- GitLab 13: `13.0.14` > [`13.1.11`](#1310) > [`13.8.8`](#1388) > [`13.12.15`](#13120) -- GitLab 14: [`14.0.12`](#1400) > [`14.3.6`](#1430) > [`14.9.5`](#1490) > [`14.10.5`](#14100) -- GitLab 15: [`15.0.5`](#1500) > [`15.1.6`](#1510) (for GitLab instances with multiple web nodes) > [`15.4.6`](#1540) > [`15.11.x`](#15110) -- GitLab 16: [latest `16.Y.Z`](https://gitlab.com/gitlab-org/gitlab/-/releases) +1. Check for [required upgrade stops](#required-upgrade-stops). +1. Consult the [version-specific upgrade instructions](#version-specific-upgrading-instructions). +1. Upgrade GitLab accordingly. NOTE: When not explicitly specified, upgrade GitLab to the latest available patch @@ -209,6 +204,25 @@ be fixes for issues relating to the upgrade process. Specifically around a [major version](#upgrading-to-a-new-major-version), crucial database schema and migration patches may be included in the latest patch releases. +### Required upgrade stops + +Required upgrade stops are versions of GitLab that you must upgrade to before upgrading to later versions. Required +upgrade stops allow required background migrations to finish. + +During GitLab 16.x, we are scheduling two or three required upgrade stops. We will give at least two milestones of +notice when we schedule a required upgrade stop. + +The first planned required upgrade stop is scheduled for GitLab 16.3. If nothing is introduced requiring an upgrade stop, +GitLab 16.3 will be treated as a regular upgrade. + +### Earlier GitLab versions + +For information on upgrading to earlier GitLab versions, see the [documentation archives](https://archives.docs.gitlab.com). +The versions of the documentation in the archives contain version-specific information for even earlier versions of GitLab. + +For example, the [documentation for GitLab 15.11](https://archives.docs.gitlab.com/15.11/ee/update/#upgrade-paths) +contains information on versions back to GitLab 12. + ## Upgrading between editions GitLab comes in two flavors: [Community Edition](https://about.gitlab.com/features/#community) which is MIT licensed, @@ -271,42 +285,9 @@ NOTE: Specific information that follow related to Ruby and Git versions do not apply to [Omnibus installations](https://docs.gitlab.com/omnibus/) and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with appropriate Ruby and Git versions and are not using system binaries for Ruby and Git. There is no need to install Ruby or Git when utilizing these two approaches. -### 16.1.0 - -- A `MigrateHumanUserType` background migration will be finalized with - the `FinalizeUserTypeMigration` migration. - GitLab 16.0 introduced a [batched background migration](background_migrations.md#batched-background-migrations) to - [migrate `user_type` values from `NULL` to `0`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115849). This - migration may take multiple days to complete on larger GitLab instances. Make sure the migration - has completed successfully before upgrading to 16.1.0. -- A `BackfillPreparedAtMergeRequests` background migration will be finalized with - the `FinalizeBackFillPreparedAtMergeRequests` post-deploy migration. - GitLab 15.10.0 introduced a [batched background migration](background_migrations.md#batched-background-migrations) to - [backfill `prepared_at` values on the `merge_requests` table](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111865). This - migration may take multiple days to complete on larger GitLab instances. Make sure the migration - has completed successfully before upgrading to 16.1.0. -- Geo: Some project imports do not initialize wiki repositories on project creation. Since the migration of project wikis to SSF, [missing wiki repositories are being incorrectly flagged as failing verification](https://gitlab.com/gitlab-org/gitlab/-/issues/409704). This is not a result of an actual replication/verification failure but an invalid internal state for these missing repositories inside Geo and results in errors in the logs and the verification progress reporting a failed state for these wiki repositories. If you have not imported projects you are not impacted by this issue. - - Impacted versions: GitLab versions 15.11.x, 16.0.x, and 16.1.0 - 16.1.2. - - Versions containing fix: GitLab 16.1.3 and later. -- Geo: Since the migration of project designs to SSF, [missing design repositories are being incorrectly flagged as failing verification](https://gitlab.com/gitlab-org/gitlab/-/issues/414279). This is not a result of an actual replication/verification failure but an invalid internal state for these missing repositories inside Geo and results in errors in the logs and the verification progress reporting a failed state for these design repositories. You could be impacted by this issue even if you have not imported projects. - - Impacted versions: GitLab versions 16.1.x. - - Versions containing fix: GitLab 16.2.0 and later. -- For self-compiled installations: You must remove any settings related to Puma worker killer from the `puma.rb` configuration file, since those have been [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118645). For more information, see the [`puma.rb.example`](https://gitlab.com/gitlab-org/gitlab/-/blob/16-0-stable-ee/config/puma.rb.example) file. - -### 16.0.0 - -- Sidekiq crashes if there are non-ASCII characters in the GitLab.rb file. You can fix this - by following the workaround in [issue 412767](https://gitlab.com/gitlab-org/gitlab/-/issues/412767#note_1404507549). -- Sidekiq jobs are only routed to `default` and `mailers` queues by default, and as a result, - every Sidekiq process also listens to those queues to ensure all jobs are processed across - all queues. This behavior does not apply if you have configured the [routing rules](../administration/sidekiq/processing_specific_job_classes.md#routing-rules). -- Docker 20.10.10 or later is required to run the GitLab Docker image. Older versions - [throw errors on startup](../install/docker.md#threaderror-cant-create-thread-operation-not-permitted). -- Geo: Some project imports do not initialize wiki repositories on project creation. Since the migration of project wikis to SSF, [missing wiki repositories are being incorrectly flagged as failing verification](https://gitlab.com/gitlab-org/gitlab/-/issues/409704). This is not a result of an actual replication/verification failure but an invalid internal state for these missing repositories inside Geo and results in errors in the logs and the verification progress reporting a failed state for these wiki repositories. If you have not imported projects you are not impacted by this issue. - - Impacted versions: GitLab versions 15.11.x, 16.0.x, and 16.1.0 - 16.1.2. - - Versions containing fix: GitLab 16.1.3 and later. -- Starting with 16.0, GitLab self-managed installations now have two database connections by default, instead of one. This change doubles the number of PostgreSQL connections. It makes self-managed versions of GitLab behave similarly to GitLab.com, and is a step toward enabling a separate database for CI features for self-managed versions of GitLab. Before upgrading to 16.0, determine if you need to [increase max connections for PostgreSQL](https://docs.gitlab.com/omnibus/settings/database.html#configuring-multiple-database-connections). - - This change applies to installation methods with Linux packages (Omnibus GitLab), GitLab Helm chart, GitLab Operator, GitLab Docker images, and installation from source. +### GitLab 16 + +Before upgrading, see [GitLab 16 changes](versions/gitlab_16_changes.md). ### 15.11.1 @@ -318,28 +299,42 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap - Versions containing fix: GitLab 16.1.3 and later. - Geo: A [bug](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7841) in the built-in `pg-upgrade` tool prevents upgrading the bundled PostgreSQL database to version 13. This leaves the secondary site in a broken state, and prevents upgrading the Geo installation to GitLab 16.x ([PostgreSQL 12 support has removed in 16.0](deprecations.md#postgresql-12-deprecated) and later releases). This occurs on secondary sites using the bundled PostgreSQL software, running both the secondary main Rails database and tracking database on the same node. There is a manual [workaround](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7841#workaround) for those impacted until a fix is backported to 15.11. - Impacted versions: GitLab versions 15.2 - 15.11 + - Versions containing fix: 15.11.12 and later. - Version 16.0 and later are not impacted. Note, 15.11 is a mandatory upgrade stop on the way to 16.0. ### 15.11.0 -- Upgrades to GitLab 15.11 directly from GitLab versions 15.5.0 and earlier on self-managed installs will fail due to a missing migration until the fix for [issue 408304](https://gitlab.com/gitlab-org/gitlab/-/issues/408304) is released in version 15.11.3. Affected users wanting to upgrade to 15.11 can either: - - Perform an intermediate upgrade to any version between 15.5 and 15.10 before upgrading to 15.11, or - - Target version 15.11.3 or later. +- **Upgrade to patch release 15.11.3 or later**. This avoids [issue 408304](https://gitlab.com/gitlab-org/gitlab/-/issues/408304) when upgrading from 15.5.0 and earlier. - Geo: Some project imports do not initialize wiki repositories on project creation. Since the migration of project wikis to SSF, [missing wiki repositories are being incorrectly flagged as failing verification](https://gitlab.com/gitlab-org/gitlab/-/issues/409704). This is not a result of an actual replication/verification failure but an invalid internal state for these missing repositories inside Geo and results in errors in the logs and the verification progress reporting a failed state for these wiki repositories. If you have not imported projects you are not impacted by this issue. - Impacted versions: GitLab versions 15.11.x, 16.0.x, and 16.1.0 - 16.1.2. - Versions containing fix: GitLab 16.1.3 and later. - Geo: A [bug](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7841) in the built-in `pg-upgrade` tool prevents upgrading the bundled PostgreSQL database to version 13. This leaves the secondary site in a broken state, and prevents upgrading the Geo installation to GitLab 16.x ([PostgreSQL 12 support has removed in 16.0](deprecations.md#postgresql-12-deprecated) and later releases). This occurs on secondary sites using the bundled PostgreSQL software, running both the secondary main Rails database and tracking database on the same node. There is a manual [workaround](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7841#workaround) for those impacted until a fix is backported to 15.11. - - Impacted versions: GitLab versions 15.2 - 15.11 + - Impacted versions: GitLab versions 15.2 - 15.11.11. + - Versions containing fix: 15.11.12 and later. - Version 16.0 and later are not impacted. Note, 15.11 is a mandatory upgrade stop on the way to 16.0. +### 15.11.x + +- A [bug](https://gitlab.com/gitlab-org/gitlab/-/issues/411604) can cause new LDAP users signing in for the first time to be assigned a username based on their email address instead of their LDAP username attribute. A manual workaround is to set `gitlab_rails['omniauth_auto_link_ldap_user'] = true`, or upgrade to GitLab 16.1 or later where the bug has been fixed. + ### 15.10.5 +- A [bug with Elastic Indexer Cron Workers](https://gitlab.com/gitlab-org/gitlab/-/issues/408214) can cause saturation in Sidekiq. + - When this issue occurs, merge request merges, pipelines, Slack notifications, and other events are not created or take a long time to occur. + - This issue may not manifest immediately as it can take up to a week before the Sidekiq is saturated enough. + - Elasticsearch does not need to be enabled for this to occur. + - To resolve this issue, upgrade to 15.11 or use the workaround in the issue. - Many [project importers](../user/project/import/index.md) and [group importers](../user/group/import/index.md) now require the Maintainer role instead of only requiring the Developer role. For more information, see the documentation for any importers you use. ### 15.10.0 +- A [bug with Elastic Indexer Cron Workers](https://gitlab.com/gitlab-org/gitlab/-/issues/408214) can cause saturation in Sidekiq. + - When this issue occurs, merge request merges, pipelines, Slack notifications, and other events are not created or take a long time to occur. + - This issue may not manifest immediately as it can take up to a week before the Sidekiq is saturated enough. + - Elasticsearch does not need to be enabled for this to occur. + - To resolve this issue, upgrade to 15.11 or use the workaround in the issue. - Gitaly configuration changes significantly in Omnibus GitLab 16.0. You can begin migrating to the new structure in Omnibus GitLab 15.10 while backwards compatibility is maintained in the lead up to Omnibus GitLab 16.0. [Read more about this change](#gitaly-omnibus-gitlab-configuration-structure-change). - You might encounter the following error while upgrading to GitLab 15.10 or later: @@ -390,6 +385,11 @@ For more information, see [issue 415724](https://gitlab.com/gitlab-org/gitlab/-/ ### 15.9.0 +- A [bug with Elastic Indexer Cron Workers](https://gitlab.com/gitlab-org/gitlab/-/issues/408214) can cause saturation in Sidekiq. + - When this issue occurs, merge request merges, pipelines, Slack notifications, and other events are not created or take a long time to occur. + - This issue may not manifest immediately as it can take up to a week before the Sidekiq is saturated enough. + - Elasticsearch does not need to be enabled for this to occur. + - To resolve this issue, upgrade to 15.11 or use the workaround in the issue. - **Upgrade to patch release 15.9.3 or later**. This provides fixes for two database migration bugs: - Patch releases 15.9.0, 15.9.1, 15.9.2 have [a bug that can cause data loss](#user-profile-data-loss-bug-in-159x) from the user profile fields. - The second [bug fix](https://gitlab.com/gitlab-org/gitlab/-/issues/394760) ensures it is possible to upgrade directly from 15.4.x. @@ -417,65 +417,65 @@ For more information, see [issue 415724](https://gitlab.com/gitlab-org/gitlab/-/ ### 15.8.2 - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. ### 15.8.1 - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.8.0 -- Git 2.38.0 and later is required by Gitaly. For installations from source, you should use the [Git version provided by Gitaly](../install/installation.md#git). +- Git 2.38.0 and later is required by Gitaly. For self-compiled installations, you should use the [Git version provided by Gitaly](../install/installation.md#git). - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. ### 15.7.6 - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.7.5 - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.7.4 - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.7.3 - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.7.2 -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the upgrades. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the upgrades. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.7.1 -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. @@ -510,8 +510,8 @@ For more information, see [issue 415724](https://gitlab.com/gitlab-org/gitlab/-/ For example, previously: - - Omnibus GitLab default (`sidekiq['max_concurrency']`): 50 - - From source installation default: 50 + - Linux package installation default (`sidekiq['max_concurrency']`): 50 + - Self-compiled installation default: 50 - Helm chart default (`gitlab.sidekiq.concurrency`): 25 Reference architectures still use a default of 10 as this is set specifically @@ -519,7 +519,7 @@ For more information, see [issue 415724](https://gitlab.com/gitlab-org/gitlab/-/ Sites that have configured `max_concurrency` will not be affected by this change. [Read more about the Sidekiq concurrency setting](../administration/sidekiq/extra_sidekiq_processes.md#concurrency). -- GitLab Runner 15.7.0 introduced a breaking change that impacts CI/CD jobs: [Correctly handle expansion of job file variables](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3613). +- GitLab Runner 15.7.0 introduced a breaking change that affects CI/CD jobs: [Correctly handle expansion of job file variables](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3613). Previously, job-defined variables that referred to [file type variables](../ci/variables/index.md#use-file-type-cicd-variables) were expanded to the value of the file variable (its content). This behavior did not @@ -527,71 +527,71 @@ For more information, see [issue 415724](https://gitlab.com/gitlab-org/gitlab/-/ that secrets or sensitive information could leak if the file variable and its contents printed. For example, if they were printed in an echo output. For more information, see [Understanding the file type variable expansion change in GitLab 15.7](https://about.gitlab.com/blog/2023/02/13/impact-of-the-file-type-variable-change-15-7/). -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. ### 15.6.7 - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.6.6 -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.6.5 -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.6.4 -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6, and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6, and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.6.3 -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.6.2 -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.6.1 -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.6.0 - You should use one of the [officially supported PostgreSQL versions](../administration/package_information/postgresql_versions.md). Some database migrations can cause stability and performance issues with older PostgreSQL versions. -- Git 2.37.0 and later is required by Gitaly. For installations from source, we recommend you use the [Git version provided by Gitaly](../install/installation.md#git). +- Git 2.37.0 and later is required by Gitaly. For self-compiled installations, you should use the [Git version provided by Gitaly](../install/installation.md#git). - A database change to modify the behavior of four indexes fails on instances where these indexes do not exist: @@ -606,9 +606,9 @@ For more information, see [issue 415724](https://gitlab.com/gitlab-org/gitlab/-/ This issue was [fixed in GitLab 15.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105375) and backported to GitLab 15.6.2. The issue can also be worked around: [read about how to create these indexes](https://gitlab.com/gitlab-org/gitlab/-/issues/378343#note_1199863087). -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. - Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. - - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. - Versions containing fix: GitLab 15.8.3 and later. - Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. @@ -689,7 +689,7 @@ For more information, see [issue 415724](https://gitlab.com/gitlab-org/gitlab/-/ - A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) prevents some premium features of GitLab from working correctly if you add a new license. Workarounds for this issue: - Restart all Rails, Sidekiq and Gitaly nodes after applying a new license. This clears the relevant license caches and allows all premium features to operate correctly. - - Upgrade to a version that is not impacted by this issue. The following upgrade paths are available for impacted versions: + - Upgrade to a version that is not affected by this issue. The following upgrade paths are available for affected versions: - 15.2.5 --> 15.3.5 - 15.3.0 - 15.3.4 --> 15.3.5 - 15.4.1 --> 15.4.3 @@ -699,7 +699,7 @@ For more information, see [issue 415724](https://gitlab.com/gitlab-org/gitlab/-/ - A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) prevents some premium features of GitLab from working correctly if you add a new license. Workarounds for this issue: - Restart all Rails, Sidekiq and Gitaly nodes after applying a new license. This clears the relevant license caches and allows all premium features to operate correctly. - - Upgrade to a version that is not impacted by this issue. The following upgrade paths are available for impacted versions: + - Upgrade to a version that is not affected by this issue. The following upgrade paths are available for affected versions: - 15.2.5 --> 15.3.5 - 15.3.0 - 15.3.4 --> 15.3.5 - 15.4.1 --> 15.4.3 @@ -742,7 +742,7 @@ For more information, see [issue 415724](https://gitlab.com/gitlab-org/gitlab/-/ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) prevents some premium features of GitLab from working correctly if you add a new license. Workarounds for this issue: - Restart all Rails, Sidekiq and Gitaly nodes after applying a new license. This clears the relevant license caches and allows all premium features to operate correctly. -- Upgrade to a version that is not impacted by this issue. The following upgrade paths are available for impacted versions: +- Upgrade to a version that is not affected by this issue. The following upgrade paths are available for affected versions: - 15.2.5 --> 15.3.5 - 15.3.0 - 15.3.4 --> 15.3.5 - 15.4.1 --> 15.4.3 @@ -754,7 +754,7 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) - A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) prevents some premium features of GitLab from working correctly if you add a new license. Workarounds for this issue: - Restart all Rails, Sidekiq and Gitaly nodes after applying a new license. This clears the relevant license caches and allows all premium features to operate correctly. - - Upgrade to a version that is not impacted by this issue. The following upgrade paths are available for impacted versions: + - Upgrade to a version that is not affected by this issue. The following upgrade paths are available for affected versions: - 15.2.5 --> 15.3.5 - 15.3.0 - 15.3.4 --> 15.3.5 - 15.4.1 --> 15.4.3 @@ -764,7 +764,7 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) prevents some premium features of GitLab from working correctly if you add a new license. Workarounds for this issue: - Restart all Rails, Sidekiq and Gitaly nodes after applying a new license. This clears the relevant license caches and allows all premium features to operate correctly. -- Upgrade to a version that is not impacted by this issue. The following upgrade paths are available for impacted versions: +- Upgrade to a version that is not affected by this issue. The following upgrade paths are available for affected versions: - 15.2.5 --> 15.3.5 - 15.3.0 - 15.3.4 --> 15.3.5 - 15.4.1 --> 15.4.3 @@ -774,7 +774,7 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) prevents some premium features of GitLab from working correctly if you add a new license. Workarounds for this issue: - Restart all Rails, Sidekiq and Gitaly nodes after applying a new license. This clears the relevant license caches and allows all premium features to operate correctly. -- Upgrade to a version that is not impacted by this issue. The following upgrade paths are available for impacted versions: +- Upgrade to a version that is not affected by this issue. The following upgrade paths are available for affected versions: - 15.2.5 --> 15.3.5 - 15.3.0 - 15.3.4 --> 15.3.5 - 15.4.1 --> 15.4.3 @@ -788,7 +788,7 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) - A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) prevents some premium features of GitLab from working correctly if you add a new license. Workarounds for this issue: - Restart all Rails, Sidekiq and Gitaly nodes after applying a new license. This clears the relevant license caches and allows all premium features to operate correctly. - - Upgrade to a version that is not impacted by this issue. The following upgrade paths are available for impacted versions: + - Upgrade to a version that is not affected by this issue. The following upgrade paths are available for affected versions: - 15.2.5 --> 15.3.5 - 15.3.0 - 15.3.4 --> 15.3.5 - 15.4.1 --> 15.4.3 @@ -798,7 +798,7 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) prevents some premium features of GitLab from working correctly if you add a new license. Workarounds for this issue: - Restart all Rails, Sidekiq and Gitaly nodes after applying a new license. This clears the relevant license caches and allows all premium features to operate correctly. -- Upgrade to a version that is not impacted by this issue. The following upgrade paths are available for impacted versions: +- Upgrade to a version that is not affected by this issue. The following upgrade paths are available for affected versions: - 15.2.5 --> 15.3.5 - 15.3.0 - 15.3.4 --> 15.3.5 - 15.4.1 --> 15.4.3 @@ -837,6 +837,14 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) 1. Ensure all GitLab web nodes are running GitLab 15.1.Z. 1. [Enable the `active_support_hash_digest_sha256` feature flag](../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) to switch `ActiveSupport::Digest` to use SHA256: + + 1. [Start the rails console](../administration/operations/rails_console.md) + 1. Enable the feature flag: + + ```ruby + Feature.enable(:active_support_hash_digest_sha256) + ``` + 1. Only then, continue to upgrade to later versions of GitLab. - Unauthenticated requests to the [`ciConfig` GraphQL field](../api/graphql/reference/index.md#queryciconfig) are no longer supported. Before you upgrade to GitLab 15.1, add an [access token](../api/rest/index.md#authentication) to your requests. @@ -1036,7 +1044,7 @@ that may remain stuck permanently in a **pending** state. ### 14.5.0 - When `make` is run, Gitaly builds are now created in `_build/bin` and no longer in the root directory of the source directory. If you -are using a source install, update paths to these binaries in your [systemd unit files](upgrading_from_source.md#configure-systemd-units) +are using a self-compiled installation, update paths to these binaries in your [systemd unit files](upgrading_from_source.md#configure-systemd-units) or [init scripts](upgrading_from_source.md#configure-sysv-init-script) by [following the documentation](upgrading_from_source.md). - Connections between Workhorse and Gitaly use the Gitaly `backchannel` protocol by default. If you deployed a gRPC proxy between Workhorse and Gitaly, @@ -1369,8 +1377,6 @@ Other issues: **GitLab 13.2 or older** directly to 14.0, this is [unsupported](#upgrading-to-a-new-major-version). You should instead follow a [supported upgrade path](#upgrade-paths). - See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144). -- See [Custom Rack Attack initializers](#custom-rack-attack-initializers) if you persist your own custom Rack Attack - initializers during upgrades. #### Upgrading to later 14.Y releases @@ -1382,263 +1388,6 @@ Other issues: 1. [Batched background migrations must finish](background_migrations.md#batched-background-migrations) before you upgrade to a later version [and may take longer than usual](#1400). -### 13.12.0 - -- See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144). - -- Check the GitLab database [has no references to legacy storage](../administration/raketasks/storage.md#on-legacy-storage). - The GitLab 14.0 pre-install check causes the package update to fail if unmigrated data exists: - - ```plaintext - Checking for unmigrated data on legacy storage - - Legacy storage is no longer supported. Please migrate your data to hashed storage. - ``` - -### 13.11.0 - -- Git 2.31.x and later is required. We recommend you use the - [Git version provided by Gitaly](../install/installation.md#git). - -- See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144). - -- GitLab 13.11 includes a faulty background migration ([`RescheduleArtifactExpiryBackfillAgain`](https://gitlab.com/gitlab-org/gitlab/-/blob/ccc70031b843ff8cff1185988c2e472a521c2701/db/post_migrate/20210413132500_reschedule_artifact_expiry_backfill_again.rb)) - that incorrectly sets the `expire_at` column in the `ci_job_artifacts` database table. - Incorrect `expire_at` values can potentially cause data loss. - - To prevent this risk of data loss, you must remove the content of the `RescheduleArtifactExpiryBackfillAgain` - migration, which makes it a no-op migration. You can repeat the changes from the - [commit that makes the migration no-op in 14.9 and later](https://gitlab.com/gitlab-org/gitlab/-/blob/42c3dfc5a1c8181767bbb5c76e7c5fa6fefbbc2b/db/post_migrate/20210413132500_reschedule_artifact_expiry_backfill_again.rb). - For more information, see [how to disable a data migration](../development/database/deleting_migrations.md#how-to-disable-a-data-migration). - -### 13.10.0 - -See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144). - -### 13.9.0 - -- We've detected an issue [with a column rename](https://gitlab.com/gitlab-org/gitlab/-/issues/324160) - that prevents upgrades to GitLab 13.9.0, 13.9.1, 13.9.2, and 13.9.3 when following the zero-downtime steps. It is necessary - to perform the following additional steps for the zero-downtime upgrade: - - 1. Before running the final `sudo gitlab-rake db:migrate` command on the deploy node, - execute the following queries using the PostgreSQL console (or `sudo gitlab-psql`) - to drop the problematic triggers: - - ```sql - drop trigger trigger_e40a6f1858e6 on application_settings; - drop trigger trigger_0d588df444c8 on application_settings; - drop trigger trigger_1572cbc9a15f on application_settings; - drop trigger trigger_22a39c5c25f3 on application_settings; - ``` - - 1. Run the final migrations: - - ```shell - sudo gitlab-rake db:migrate - ``` - - If you have already run the final `sudo gitlab-rake db:migrate` command on the deploy node and have - encountered the [column rename issue](https://gitlab.com/gitlab-org/gitlab/-/issues/324160), you - see the following error: - - ```shell - -- remove_column(:application_settings, :asset_proxy_whitelist) - rake aborted! - StandardError: An error has occurred, all later migrations canceled: - PG::DependentObjectsStillExist: ERROR: cannot drop column asset_proxy_whitelist of table application_settings because other objects depend on it - DETAIL: trigger trigger_0d588df444c8 on table application_settings depends on column asset_proxy_whitelist of table application_settings - ``` - - To work around this bug, follow the previous steps to complete the upgrade. - More details are available [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/324160). - -- See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144). - -- For GitLab Enterprise Edition customers, we noticed an issue when [subscription expiration is upcoming, and you create new subgroups and projects](https://gitlab.com/gitlab-org/gitlab/-/issues/322546). If you fall under that category and get 500 errors, you can work around this issue: - - 1. SSH into you GitLab server, and open a Rails console: - - ```shell - sudo gitlab-rails console - ``` - - 1. Disable the following features: - - ```ruby - Feature.disable(:subscribable_subscription_banner) - Feature.disable(:subscribable_license_banner) - ``` - - 1. Restart Puma or Unicorn: - - ```shell - #For installations using Puma - sudo gitlab-ctl restart puma - - #For installations using Unicorn - sudo gitlab-ctl restart unicorn - ``` - -### 13.8.8 - -GitLab 13.8 includes a background migration to address [an issue with duplicate service records](https://gitlab.com/gitlab-org/gitlab/-/issues/290008). If duplicate services are present, this background migration must complete before a unique index is applied to the services table, which was [introduced in GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52563). Upgrades from GitLab 13.8 and earlier to later versions must include an intermediate upgrade to GitLab 13.8.8 and [must wait until the background migrations complete](background_migrations.md) before proceeding. - -If duplicate services are still present, an upgrade to 13.9.x or later results in a failed upgrade with the following error: - -```console -PG::UniqueViolation: ERROR: could not create unique index "index_services_on_project_id_and_type_unique" -DETAIL: Key (project_id, type)=(NNN, ServiceName) is duplicated. -``` - -### 13.6.0 - -Ruby 2.7.2 is required. GitLab does not start with Ruby 2.6.6 or older versions. - -The required Git version is Git v2.29 or later. - -GitLab 13.6 includes a -[background migration `BackfillJiraTrackerDeploymentType2`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46368) -that may remain stuck permanently in a **pending** state despite completion of work -due to a bug. - -To clean up this stuck job, run the following in the [GitLab Rails Console](../administration/operations/rails_console.md): - -```ruby -Gitlab::Database::BackgroundMigrationJob.pending.where(class_name: "BackfillJiraTrackerDeploymentType2").find_each do |job| - puts Gitlab::Database::BackgroundMigrationJob.mark_all_as_succeeded("BackfillJiraTrackerDeploymentType2", job.arguments) -end -``` - -### 13.4.0 - -GitLab 13.4.0 includes a background migration to [move all remaining repositories in legacy storage to hashed storage](../administration/raketasks/storage.md#migrate-to-hashed-storage). There are [known issues with this migration](https://gitlab.com/gitlab-org/gitlab/-/issues/259605) which are fixed in GitLab 13.5.4 and later. If possible, skip 13.4.0 and upgrade to 13.5.4 or later instead. The migration can take quite a while to run, depending on how many repositories must be moved. Be sure to check that all background migrations have completed before upgrading further. - -### 13.3.0 - -The recommended Git version is Git v2.28. The minimum required version of Git -v2.24 remains the same. - -### 13.2.0 - -GitLab installations that have multiple web nodes must be -[upgraded to 13.1](#1310) before upgrading to 13.2 (and later) due to a -breaking change in Rails that can result in authorization issues. - -GitLab 13.2.0 [remediates](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35492) an [email verification bypass](https://about.gitlab.com/releases/2020/05/27/security-release-13-0-1-released/). -After upgrading, if some of your users are unexpectedly encountering 404 or 422 errors when signing in, -or "blocked" messages when using the command line, -their accounts may have been un-confirmed. -In that case, ask them to check their email for a re-confirmation link. -For more information, see our discussion of [Email confirmation issues](../user/upgrade_email_bypass.md). - -GitLab 13.2.0 relies on the `btree_gist` extension for PostgreSQL. For installations with an externally managed PostgreSQL setup, make sure to -[install the extension manually](https://www.postgresql.org/docs/11/sql-createextension.html) before upgrading GitLab if the database user for GitLab -is not a superuser. This is not necessary for installations using a GitLab managed PostgreSQL database. - -### 13.1.0 - -In 13.1.0, you must upgrade to either: - -- At least Git v2.24 (previously, the minimum required version was Git v2.22). -- The recommended Git v2.26. - -Failure to do so results in internal errors in the Gitaly service in some RPCs due -to the use of the new `--end-of-options` Git flag. - -Additionally, in GitLab 13.1.0, the version of -[Rails was upgraded from 6.0.3 to 6.0.3.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33454). -The Rails upgrade included a change to CSRF token generation which is -not backwards-compatible - GitLab servers with the new Rails version -generate CSRF tokens that are not recognizable by GitLab servers -with the older Rails version - which could cause non-GET requests to -fail for [multi-node GitLab installations](zero_downtime.md#multi-node--ha-deployment). - -So, if you are using multiple Rails servers and specifically upgrading from 13.0, -all servers must first be upgraded to 13.1.Z before upgrading to 13.2.0 or later: - -1. Ensure all GitLab web nodes are running GitLab 13.1.Z. -1. Enable the `global_csrf_token` feature flag to enable new - method of CSRF token generation: - - ```ruby - Feature.enable(:global_csrf_token) - ``` - -1. Only then, continue to upgrade to later versions of GitLab. - -#### Custom Rack Attack initializers - -From GitLab 13.1, custom Rack Attack initializers (`config/initializers/rack_attack.rb`) are replaced with initializers -supplied with GitLab during upgrades. You should use these GitLab-supplied initializers. - -If you persist your own Rack Attack initializers between upgrades, you might -[get `500` errors](https://gitlab.com/gitlab-org/gitlab/-/issues/334681) when [upgrading to GitLab 14.0 and later](#1400). - -For **self-compiled (source) installations**, the Rack Attack initializer on GitLab -was renamed from [`config/initializers/rack_attack_new.rb` to `config/initializers/rack_attack.rb`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33072). -The rename was part of [deprecating Rack Attack throttles on Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4750). - -If `rack_attack.rb` has been created on your installation, consider creating a backup before updating: - -```shell -cd /home/git/gitlab -cp config/initializers/rack_attack.rb config/initializers/rack_attack_backup.rb -``` - -### 12.10.0 - -- The final patch release (12.10.14) - [has a regression affecting maven package uploads](https://about.gitlab.com/releases/2020/07/06/critical-security-release-gitlab-13-1-3-released/#maven-package-upload-broken-in-121014). - If you use this feature and must stay on 12.10 while preparing to upgrade to 13.0: - - - Upgrade to 12.10.13 instead. - - Upgrade to 13.0.14 as soon as possible. - -- [GitLab 13.0 requires PostgreSQL 11](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/#postgresql-11-is-now-the-minimum-required-version-to-install-gitlab). - - - 12.10 is the final release that shipped with PostgreSQL 9.6, 10, and 11. - - You should make sure that your database is PostgreSQL 11 on GitLab 12.10 before upgrading to 13.0. This upgrade requires downtime. - -### 12.2.0 - -In 12.2.0, we enabled Rails' authenticated cookie encryption. Old sessions are -automatically upgraded. - -However, session cookie downgrades are not supported. So after upgrading to 12.2.0, -any downgrades would result to all sessions being invalidated and users are logged out. - -### 12.1.0 - -- If you are planning to upgrade from `12.0.Z` to `12.10.Z`, it is necessary to - perform an intermediary upgrade to `12.1.Z` before upgrading to `12.10.Z` to - avoid issues like [#215141](https://gitlab.com/gitlab-org/gitlab/-/issues/215141). - -- Support for MySQL was removed in GitLab 12.1. Existing users using GitLab with - MySQL/MariaDB should - [migrate to PostgreSQL](https://gitlab.com/gitlab-org/gitlab/-/blob/v15.6.0-ee/doc/update/mysql_to_postgresql.md) - before upgrading. - -### 12.0.0 - -In 12.0.0 we made various database related changes. These changes require that -users first upgrade to the latest 11.11 patch release. After upgraded to 11.11.Z, -users can upgrade to 12.0.Z. Failure to do so may result in database migrations -not being applied, which could lead to application errors. - -It is also required that you upgrade to 12.0.Z before moving to a later version -of 12.Y. - -Example 1: you are currently using GitLab 11.11.8, which is the latest patch -release for 11.11.Z. You can upgrade as usual to 12.0.Z. - -Example 2: you are currently using a version of GitLab 10.Y. To upgrade, first -upgrade to the last 10.Y release (10.8.7) then the last 11.Y release (11.11.8). -After upgraded to 11.11.8 you can safely upgrade to 12.0.Z. - -See our [documentation on upgrade paths](../policy/maintenance.md#upgrade-recommendations) -for more information. - ### User profile data loss bug in 15.9.x There is a database migration bug in 15.9.0, 15.9.1, and 15.9.2 that can cause data loss from the user profile fields `linkedin`, `twitter`, `skype`, `website_url`, `location`, and `organization`. @@ -1658,7 +1407,7 @@ It is not then required to upgrade to 15.9.3 or later for this issue. ### Gitaly: Omnibus GitLab configuration structure change Gitaly configuration structure in Omnibus GitLab [changes](https://gitlab.com/gitlab-org/gitaly/-/issues/4467) in GitLab 16.0 to be consistent with the Gitaly configuration -structure used in source installs. +structure used in self-compiled installations. As a result of this change, a single hash under `gitaly['configuration']` holds most Gitaly configuration. Some `gitaly['..']` configuration options will continue to be used by Omnibus GitLab 16.0 and later: @@ -1680,6 +1429,8 @@ The new structure is documented below with the old keys described in a comment a 1. Skip any keys you haven't configured a value for previously. 1. Remove the old keys from the configuration once migrated. 1. Optional but recommended. Include a trailing comma for all hash keys so the hash remains valid when keys are re-ordered or additional keys are added. +1. When configuring `storage` to replace `git_data_dirs`, you must append `repositories` to the path as documented below. If you omit this step, your Git repositories are + inaccessible until the configuration is fixed. ```ruby gitaly['configuration'] = { @@ -1820,7 +1571,7 @@ gitaly['configuration'] = { ### Praefect: Omnibus GitLab configuration structure change Praefect configuration structure in Omnibus GitLab [changes](https://gitlab.com/gitlab-org/gitaly/-/issues/4467) in GitLab 16.0 to be consistent with the Praefect configuration -structure used in source installs. +structure used in self-compiled installations. As a result of this change, a single hash under `praefect['configuration']` holds most Praefect configuration. Some `praefect['..']` configuration options will continue to be used by Omnibus GitLab 16.0 and later: diff --git a/doc/update/package/downgrade.md b/doc/update/package/downgrade.md index 14b9bd981fd..0e01a1bfcd8 100644 --- a/doc/update/package/downgrade.md +++ b/doc/update/package/downgrade.md @@ -79,5 +79,5 @@ Steps: sudo gitlab-ctl reconfigure ``` -1. [Restore GitLab](../../administration/backup_restore/restore_gitlab.md#restore-for-omnibus-gitlab-installations) +1. [Restore GitLab](../../administration/backup_restore/restore_gitlab.md#restore-for-linux-package-installations) to complete the downgrade. diff --git a/doc/update/package/index.md b/doc/update/package/index.md index e61eaae5883..148791dbc75 100644 --- a/doc/update/package/index.md +++ b/doc/update/package/index.md @@ -42,9 +42,6 @@ check the version your are upgrading to: - [GitLab 16](https://docs.gitlab.com/omnibus/update/gitlab_16_changes.html) - [GitLab 15](https://docs.gitlab.com/omnibus/update/gitlab_15_changes.html) - [GitLab 14](https://docs.gitlab.com/omnibus/update/gitlab_14_changes.html) -- [GitLab 13](https://docs.gitlab.com/omnibus/update/gitlab_13_changes.html) -- [GitLab 12](https://docs.gitlab.com/omnibus/update/gitlab_12_changes.html) -- [GitLab 11](https://docs.gitlab.com/omnibus/update/gitlab_11_changes.html) ## Back up before upgrading diff --git a/doc/update/plan_your_upgrade.md b/doc/update/plan_your_upgrade.md index 634c430e251..0bb760ec47e 100644 --- a/doc/update/plan_your_upgrade.md +++ b/doc/update/plan_your_upgrade.md @@ -104,8 +104,8 @@ to your instance and then upgrade it for any relevant features you're using. - Generate an upgrade plan by reading and understanding the relevant documentation: - upgrade based on the installation method: - - [Linux package (Omnibus)](index.md#linux-packages-omnibus-gitlab) - - [Compiled from source](index.md#installation-from-source) + - [Linux package (Omnibus)](index.md#linux-packages-omnibus) + - [Self-compiled](index.md#self-compiled-installation) - [Docker](index.md#installation-using-docker) - [Helm Charts](index.md#installation-using-helm) - [Zero-downtime upgrades](zero_downtime.md) (if possible and desired) diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index d9641e18e8e..21f509ebd33 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -327,10 +327,6 @@ cd /home/git/gitlab sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production ``` -NOTE: -If you get any errors concerning Rack attack, see the [13.1](index.md#custom-rack-attack-initializers) -specific changes. - ### 13. Update Gitaly If Gitaly is located on its own server, or you use Gitaly Cluster, see [Gitaly or Gitaly Cluster](zero_downtime.md#gitaly-or-gitaly-cluster) diff --git a/doc/update/versions/gitlab_16_changes.md b/doc/update/versions/gitlab_16_changes.md new file mode 100644 index 00000000000..cd51ca2a518 --- /dev/null +++ b/doc/update/versions/gitlab_16_changes.md @@ -0,0 +1,221 @@ +--- +stage: Systems +group: Distribution +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 +--- + +# GitLab 16 changes + +This page contains upgrade information for minor and patch versions of GitLab 16. +Ensure you review these instructions for: + +- Your installation type. +- All versions between your current version and your target version. + +Some GitLab installations must upgrade to GitLab 16.0 before upgrading to any other version. For more information, see +[Long-running user type data change](#long-running-user-type-data-change). + +For more information about upgrading GitLab Helm Chart, see [the release notes for 7.0](https://docs.gitlab.com/charts/releases/7_0.html). + +## 16.3.0 + +- For Go applications, [`crypto/tls`: verifying certificate chains containing large RSA keys is slow (CVE-2023-29409)](https://github.com/golang/go/issues/61460) + introduced a hard limit of 8192 bits for RSA keys. In the context of Go applications at GitLab, RSA keys can be configured for: + + - [Container Registry](../../administration/packages/container_registry.md) + - [Gitaly](../../administration/gitaly/configure_gitaly.md#enable-tls-support) + - [GitLab Pages](../../user/project/pages/custom_domains_ssl_tls_certification/index.md#manual-addition-of-ssltls-certificates) + - [Workhorse](../../development/workhorse/configuration.md#tls-support) + + You should check the size of your RSA keys (`openssl rsa -in <your-key-file> -text -noout | grep "Key:"`) + for any of the applications above before + upgrading. + +### Linux package installations + +Specific information applies to Linux package installations: + +- In GitLab 16.0, we [announced](https://about.gitlab.com/releases/2023/05/22/gitlab-16-0-released/#omnibus-improvements) an upgraded base Docker image, + which has a new version of OpenSSH Server. An unintended consequence of the new version is that it disables accepting SSH RSA SHA-1 signatures by default. This issue should only + impact users using very outdated SSH clients. + + To avoid problems with SHA-1 signatures being unavailable, users should update their SSH clients because using SHA-1 signatures is discouraged by the upstream library for security + reasons. + + To allow for a transition period where users can't immediately upgrade their SSH clients, GitLab 16.3 and later has support for a `GITLAB_ALLOW_SHA1_RSA` environment variable in + the `Dockerfile`. If `GITLAB_ALLOW_SHA1_RSA` is set to `true`, this deprecated support is reactivated. + + Because we want to foster security best practices and follow the upstream recommendation, this environment variable will only be available until GitLab 17.0, when we plan to + drop support for it. + + For more information, see: + + - [OpenSSH 8.8 release notes](https://www.openssh.com/txt/release-8.8). + - [An informal explanation](https://gitlab.com/gitlab-org/gitlab/-/issues/416714#note_1482388504). + - `omnibus-gitlab` [merge request 7035](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/7035), which introduces the environment variable. + +## 16.2.0 + +- Legacy LDAP configuration settings may cause + [`NoMethodError: undefined method 'devise' for User:Class` errors](https://gitlab.com/gitlab-org/gitlab/-/issues/419485). + This error occurs if you have TLS options (such as `ca_file`) not specified + in the `tls_options` hash, or use the legacy `gitlab_rails['ldap_host']` option. + See the [configuration workarounds](https://gitlab.com/gitlab-org/gitlab/-/issues/419485#workarounds) + for more details. +- New job artifacts are not replicated if job artifacts are configured to be stored in object storage and `direct_upload` is enabled. This bug is fixed in GitLab versions 16.1.4, + 16.2.3, 16.3.0, and later. + - Impacted versions: GitLab versions 16.1.0 - 16.1.3 and 16.2.0 - 16.2.2. + - If you deployed an affected version, after upgrading to a fixed GitLab version, follow [these instructions](https://gitlab.com/gitlab-org/gitlab/-/issues/419742#to-fix-data) + to resync the affected job artifacts. +- You might encounter the following error while upgrading to GitLab 16.2 or later: + + ```plaintext + main: == 20230620134708 ValidateUserTypeConstraint: migrating ======================= + main: -- execute("ALTER TABLE users VALIDATE CONSTRAINT check_0dd5948e38;") + rake aborted! + StandardError: An error has occurred, all later migrations canceled: + PG::CheckViolation: ERROR: check constraint "check_0dd5948e38" of relation "users" is violated by some row + ``` + + For more information, see [issue 421629](https://gitlab.com/gitlab-org/gitlab/-/issues/421629). + +### Linux package installations + +Specific information applies to Linux package installations: + +- In 16.2, we are upgrading Redis from 6.2.11 to 7.0.12. This upgrade is expected to be fully backwards compatible. + + Redis is not automatically restarted as part of `gitlab-ctl reconfigure`. + Hence, users are manually required to run `sudo gitlab-ctl restart redis` after + the reconfigure run so that the new Redis version gets used. A warning + mentioning that the installed Redis version is different than the one running is + displayed at the end of reconfigure run until the restart is performed. + + If your instance has Redis HA with Sentinel, follow the upgrade steps mentioned in + [Zero Downtime documentation](../zero_downtime.md#redis-ha-using-sentinel). + +### Self-compiled installations + +- Git 2.41.0 and later is required by Gitaly. You should use the [Git version provided by Gitaly](../../install/installation.md#git). + +## 16.1.0 + +- A `BackfillPreparedAtMergeRequests` background migration is finalized with + the `FinalizeBackFillPreparedAtMergeRequests` post-deploy migration. + GitLab 15.10.0 introduced a [batched background migration](../background_migrations.md#batched-background-migrations) to + [backfill `prepared_at` values on the `merge_requests` table](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111865). This + migration may take multiple days to complete on larger GitLab instances. Make sure the migration + has completed successfully before upgrading to 16.1.0. +- New job artifacts are not replicated if job artifacts are configured to be stored in object storage and `direct_upload` is enabled. This bug is fixed in GitLab versions 16.1.4, + 16.2.3, 16.3.0, and later. + - Impacted versions: GitLab versions 16.1.0 - 16.1.3 and 16.2.0 - 16.2.2. + - If you deployed an affected version, after upgrading to a fixed GitLab version, follow [these instructions](https://gitlab.com/gitlab-org/gitlab/-/issues/419742#to-fix-data) + to resync the affected job artifacts. + +### Self-compiled installations + +- You must remove any settings related to Puma worker killer from the `puma.rb` configuration file, because those have been + [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118645). For more information, see the + [`puma.rb.example`](https://gitlab.com/gitlab-org/gitlab/-/blob/16-0-stable-ee/config/puma.rb.example) file. + +### Geo installations + +Specific information applies to installations using Geo: + +- Some project imports do not initialize wiki repositories on project creation. Because of the migration of project wikis to + SSF, [missing wiki repositories are being incorrectly flagged as failing verification](https://gitlab.com/gitlab-org/gitlab/-/issues/409704). + This issue is not a result of an actual replication/verification failure but an invalid internal state for these missing + repositories inside Geo and results in errors in the logs and the verification progress reporting a failed state for + these wiki repositories. If you have not imported projects you are not impacted by this issue. + - Impacted versions: GitLab versions 15.11.x, 16.0.x, and 16.1.0 - 16.1.2. + - Versions containing fix: GitLab 16.1.3 and later. +- Because of the migration of project designs to SSF, [missing design repositories are being incorrectly flagged as failing verification](https://gitlab.com/gitlab-org/gitlab/-/issues/414279). + This issue is not a result of an actual replication/verification failure but an invalid internal state for these missing + repositories inside Geo and results in errors in the logs and the verification progress reporting a failed state for + these design repositories. You could be impacted by this issue even if you have not imported projects. + - Impacted versions: GitLab versions 16.1.x. + - Versions containing fix: GitLab 16.2.0 and later. + +## 16.0.0 + +- Sidekiq crashes if there are non-ASCII characters in the `/etc/gitlab/gitlab.rb` file. You can fix this + by following the workaround in [issue 412767](https://gitlab.com/gitlab-org/gitlab/-/issues/412767#note_1404507549). +- Sidekiq jobs are only routed to `default` and `mailers` queues by default, and as a result, + every Sidekiq process also listens to those queues to ensure all jobs are processed across + all queues. This behavior does not apply if you have configured the [routing rules](../../administration/sidekiq/processing_specific_job_classes.md#routing-rules). +- Docker 20.10.10 or later is required to run the GitLab Docker image. Older versions + [throw errors on startup](../../install/docker.md#threaderror-cant-create-thread-operation-not-permitted). +- Starting with 16.0, GitLab self-managed installations now have two database connections by default, instead of one. This change doubles the number of PostgreSQL connections. It makes self-managed versions of GitLab behave similarly to GitLab.com, and is a step toward enabling a separate database for CI features for self-managed versions of GitLab. Before upgrading to 16.0, determine if you need to [increase max connections for PostgreSQL](https://docs.gitlab.com/omnibus/settings/database.html#configuring-multiple-database-connections). + - This change applies to installation methods with Linux packages (Omnibus), GitLab Helm chart, GitLab Operator, GitLab Docker images, and self-compiled installations. + +### Linux package installations + +Specific information applies to Linux package installations: + +- The binaries for PostgreSQL 12 have been removed. + + Prior to upgrading, administrators of Linux package installations must ensure the installation is using + [PostgreSQL 13](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server). + +- Bundled Grafana is deprecated and is no longer supported. It is removed in GitLab 16.3. + + For more information, see [deprecation notes](../../administration/monitoring/performance/grafana_configuration.md#deprecation-of-bundled-grafana). + +- This upgrades `openssh-server` to `1:8.9p1-3`. + + Using `ssh-keyscan -t rsa` with older OpenSSH clients to obtain public key information is no longer viable because of + the deprecations listed in [OpenSSH 8.7 Release Notes](https://www.openssh.com/txt/release-8.7). + + Workaround is to make use of a different key type, or upgrade the client OpenSSH to a version >= 8.7. + +### Geo installations + +Specific information applies to installations using Geo: + +- Some project imports do not initialize wiki repositories on project creation. Because of the migration of project wikis to + SSF, [missing wiki repositories are being incorrectly flagged as failing verification](https://gitlab.com/gitlab-org/gitlab/-/issues/409704). + This issue is not a result of an actual replication/verification failure but an invalid internal state for these missing + repositories inside Geo and results in errors in the logs and the verification progress reporting a failed state for + these wiki repositories. If you have not imported projects you are not impacted by this issue. + + - Impacted versions: GitLab versions 15.11.x, 16.0.x, and 16.1.0 - 16.1.2. + - Versions containing fix: GitLab 16.1.3 and later. + +## Long-running user type data change + +GitLab 16.0 is a required stop for large GitLab instances with a lot of records in the `users` table. + +The threshold is **30,000 users**, which includes: + +- Developers and other users in any state, including active, blocked, and pending approval. +- Bot accounts for project and group access tokens. + +GitLab 16.0 introduced a [batched background migration](../background_migrations.md#batched-background-migrations) to +[migrate `user_type` values from `NULL` to `0`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115849). This +migration might take multiple days to complete on larger GitLab instances. Make sure the migration +has completed successfully before upgrading to 16.1.0 or later. + +GitLab 16.1 introduces the `FinalizeUserTypeMigration` migration which ensures the +16.0 `MigrateHumanUserType` background migration is completed, making the 16.0 changes synchronously +during the upgrade if it's not completed. + +GitLab 16.2 [implements a `NOT NULL` database constraint](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122454) +which fails if the 16.0 migration is not complete. + +If 16.0 has been skipped (or the 16.0 migration is not complete) subsequent +Linux package (Omnibus) and Docker upgrades might fail +after an hour: + +```plaintext +FATAL: Mixlib::ShellOut::CommandTimeout: rails_migration[gitlab-rails] +[..] +Mixlib::ShellOut::CommandTimeout: Command timed out after 3600s: +``` + +[There is a fix-forward workaround for this issue](../package/index.md#mixlibshelloutcommandtimeout-rails_migrationgitlab-rails--command-timed-out-after-3600s). + +While the workaround is completing the database changes, GitLab is likely to be in +an unusable state, generating `500` errors. The errors are caused by Sidekiq and Puma running +application code that is incompatible with the database schema. + +At the end of the workaround process, Sidekiq and Puma are restarted to resolve that issue. diff --git a/doc/update/zero_downtime.md b/doc/update/zero_downtime.md index c815087b0b3..7a0f49b6fe7 100644 --- a/doc/update/zero_downtime.md +++ b/doc/update/zero_downtime.md @@ -15,7 +15,7 @@ there are the following requirements: sequence [and leave the database schema in a broken state](https://gitlab.com/gitlab-org/gitlab/-/issues/321542). - You have to use [post-deployment migrations](../development/database/post_deployment_migrations.md). - You are using PostgreSQL. Starting from GitLab 12.1, MySQL is not supported. -- You have set up a multi-node GitLab instance. Single-node instances do not support zero-downtime upgrades. +- You have set up a multi-node GitLab instance. Cloud Native Hybrid installations do [not support zero-downtime upgrades](../administration/reference_architectures/index.md#zero-downtime-upgrades). If you want to upgrade multiple releases or do not meet the other requirements: diff --git a/doc/user/admin_area/settings/img/protected_paths.png b/doc/user/admin_area/settings/img/protected_paths.png Binary files differdeleted file mode 100644 index 2233a71a139..00000000000 --- a/doc/user/admin_area/settings/img/protected_paths.png +++ /dev/null diff --git a/doc/user/admin_area/settings/slack_app.md b/doc/user/admin_area/settings/slack_app.md index 5aae85081ed..86762edd1a9 100644 --- a/doc/user/admin_area/settings/slack_app.md +++ b/doc/user/admin_area/settings/slack_app.md @@ -1,109 +1,11 @@ --- -stage: Manage -group: Import and Integrate -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 +redirect_to: '../../../administration/settings/slack_app.md' +remove_date: '2023-10-14' --- -# GitLab for Slack app administration **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/slack_app.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358872) for self-managed instances in GitLab 16.2. - -NOTE: -This page contains information about administering the GitLab for Slack app for self-managed instances. For user documentation, see [GitLab for Slack app](../../../user/project/integrations/gitlab_slack_application.md). - -The GitLab for Slack app distributed through the Slack App Directory only works with GitLab.com. -On self-managed GitLab, you can create your own copy of the GitLab for Slack app from a [manifest file](https://api.slack.com/reference/manifests#creating_apps) and configure your instance. - -The app is a private one-time copy installed in your Slack workspace only and not distributed through the Slack App Directory. To have the [GitLab for Slack app](../../../user/project/integrations/gitlab_slack_application.md) on your self-managed instance, you must enable the integration. - -## Create a GitLab for Slack app - -Prerequisite: - -- You must be at least a [Slack workspace administrator](https://slack.com/help/articles/360018112273-Types-of-roles-in-Slack). - -To create a GitLab for Slack app: - -- **In GitLab**: - - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). - 1. Select **Admin Area**. - 1. On the left sidebar, select **Settings > General**. - 1. Expand **GitLab for Slack app**. - 1. Select **Create Slack app**. - -You're then redirected to Slack for the next steps. - -- **In Slack**: - - 1. Select the Slack workspace to create the app in, then select **Next**. - 1. Slack displays a summary of the app for review. To view the complete manifest, select **Edit Configurations**. To go back to the review summary, select **Next**. - 1. Select **Create**. - 1. Select **Got it** to close the dialog. - 1. Select **Install to Workspace**. - -## Configure the settings - -After you've [created a GitLab for Slack app](#create-a-gitlab-for-slack-app), you can configure the settings in GitLab: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. -1. Expand **GitLab for Slack app**. -1. Select the **Enable GitLab for Slack app** checkbox. -1. Enter the details of your GitLab for Slack app: - 1. Go to [Slack API](https://api.slack.com/apps). - 1. Search for and select **GitLab (\<your host name\>)**. - 1. Scroll to **App Credentials**. -1. Select **Save changes**. - -### Test your configuration - -To test your GitLab for Slack app configuration: - -1. Enter the `/gitlab help` slash command into a channel in your Slack workspace. -1. Press <kbd>Enter</kbd>. - -You should see a list of available Slash commands. - -To use Slash commands for a project, configure the [GitLab for Slack app](../../../user/project/integrations/gitlab_slack_application.md) for the project. - -## Update the GitLab for Slack app - -When GitLab releases new features for the GitLab for Slack app, you might have to manually update your copy to use the new features. - -To update your copy of the GitLab for Slack app: - -- **In GitLab**: - - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). - 1. Select **Admin Area**. - 1. On the left sidebar, select **Settings > General**. - 1. Expand **GitLab for Slack app**. - 1. Select **Download latest manifest file** to download `slack_manifest.json`. - -- **In Slack**: - - 1. Go to [Slack API](https://api.slack.com/apps). - 1. Search for and select **GitLab (\<your host name\>)**. - 1. On the left sidebar, select **App Manifest**. - 1. Select the **JSON** tab to switch to a JSON view of the manifest. - 1. Copy the contents of the `slack_manifest.json` file you've downloaded from GitLab. - 1. Paste the contents into the JSON viewer to replace any existing contents. - 1. Select **Save Changes**. - -## Connectivity requirements - -To enable the GitLab for Slack app functionality, your network must allow inbound and outbound connections between GitLab and Slack. - -- For [Slack notifications](../../../user/project/integrations/gitlab_slack_application.md#slack-notifications), the GitLab instance must be able to send requests to `https://slack.com`. -- For [Slash commands](../../../user/project/integrations/gitlab_slack_application.md#slash-commands) and other features, the GitLab instance must be able to receive requests from `https://slack.com`. - -## Troubleshooting - -### Slash commands return `/gitlab failed with the error "dispatch_failed"` in Slack - -Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. To resolve this issue, ensure: - -- The GitLab for Slack app is properly [configured](#configure-the-settings), and the **Enable GitLab for Slack app** checkbox is selected. -- Your GitLab instance [allows requests to and from Slack](#connectivity-requirements). +<!-- This redirect file can be deleted after <2023-10-14>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/ai_features.md b/doc/user/ai_features.md index b9bcaec8b57..9558e40d56f 100644 --- a/doc/user/ai_features.md +++ b/doc/user/ai_features.md @@ -1,6 +1,6 @@ --- -stage: ModelOps -group: AI Assisted +stage: AI-powered +group: AI Model Validation 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 type: index, reference --- @@ -40,15 +40,26 @@ The following feature is Generally Available: [Beta features](../policy/experiment-beta-support.md#beta) do not require [Experiment features to be enabled](group/manage.md#enable-experiment-features). -The following feature is in Beta: +The following features are in Beta: - [Code Suggestions](project/repository/code_suggestions.md) +- [Explain this vulnerability](application_security/vulnerabilities/index.md#explaining-a-vulnerability-beta) ## Experiment AI features [Experiment](../policy/experiment-beta-support.md#experiment) AI features require [Experiment features to be enabled](group/manage.md#enable-experiment-features) as well as [third-party AI services to be enabled](group/manage.md#enable-third-party-ai-features). +The following features are in Experiment: + +- [Fill in merge request templates](project/merge_requests/ai_in_merge_requests.md#fill-in-merge-request-templates) +- [Summarize merge request changes](project/merge_requests/ai_in_merge_requests.md#summarize-merge-request-changes) +- [Summarize my merge request review](project/merge_requests/ai_in_merge_requests.md#summarize-my-merge-request-review) +- [Suggested merge or squash commit message](project/merge_requests/ai_in_merge_requests.md#suggested-merge-or-squash-commit-message) +- [Generate suggested tests in merge requests](project/merge_requests/ai_in_merge_requests.md#generate-suggested-tests-in-merge-requests) + +The rest of the features described on this page are also in the Experiment phase. + ### Explain Selected Code in the Web UI **(ULTIMATE SAAS)** > Introduced in GitLab 15.11 as an [Experiment](../policy/experiment-beta-support.md#experiment) on GitLab.com. @@ -98,136 +109,108 @@ code in a merge request: We cannot guarantee that the large language model produces results that are correct. Use the explanation with caution. -### Explain this Vulnerability in the Web UI **(ULTIMATE SAAS)** +### GitLab Duo Chat **(ULTIMATE SAAS)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10368) in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment) on GitLab.com. +> Introduced in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). -This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by Google AI. +This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. -GitLab can help you with your vulnerability by using a large language model to: +GitLab Duo Chat is powered by Anthropic's Claude-2.0 and Claude-instant-1.1 large language models and OpenAI's text-embedding-ada-002 embeddings. The LLMs are employed to analyze user questions to collect appropriate context data from the user's project, and to generate responses. In some cases, embeddings are used to embed user questions and find relevant content in GitLab documentation to share with the LLMs to generate an answer. -- Summarize the vulnerability. -- Help developers and security analysts get started understanding the vulnerability, how it could be exploited, and how to fix it. -- Provide a suggested mitigation. +You can get AI generated support from GitLab Duo Chat about the following topics: -Prerequisites: +- How to use GitLab. +- Questions about an issue. +- Summarizing an issue. -- You must have the GitLab Ultimate subscription tier. -- You must be a member of the project. -- The vulnerability must be a SAST finding. +Example questions you might ask: -To explain your vulnerability: +- `What is a fork?` +- `How to reset my password` +- `Summarize the issue <link to your issue>` +- `Summarize the description of the current issue` -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. On the left sidebar, select **Secure > Vulnerability report**. -1. Find a SAST vulnerability. -1. Open the vulnerability. -1. Select **Try it out**. - -Review the drawer on the right-hand side of your screen. - - +The examples above all use data from either the issue or the GitLab documentation. However, you can also ask to generate code, CI/CD configurations, or to explain code. For example: -We cannot guarantee that the large language model produces results that are correct. Use the explanation with caution. +- `Write a hello world function in Ruby` +- `Write a tic tac toe game in JavaScript` +- `Write a .gitlab-ci.yml file to test and build a rails application` +- `Explain the following code: def sum(a, b) a + b end` -### GitLab Duo Chat **(ULTIMATE SAAS)** +You can also ask follow-up questions. -> Introduced in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). - -This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's GPT-3. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. - -Getting help has never been easier. If you have a question about how the GitLab product works, you can ask product how-to questions and get AI generated support from GitLab Duo Chat. +This is an experimental feature and we're continuously extending the capabilities and reliability of the chat. 1. In the lower-left corner, select the Help icon. + The [new left sidebar must be enabled](../tutorials/left_sidebar/index.md#enable-the-new-left-sidebar). 1. Select **Ask in GitLab Duo Chat**. A drawer opens on the right side of your screen. -1. Enter your question in the chat input box and press **Enter** or select **Send**. It may take a few seconds for the interactive AI chat to search the product documentation and produce an answer. +1. Enter your question in the chat input box and press **Enter** or select **Send**. It may take a few seconds for the interactive AI chat to produce an answer. +1. You can ask a follow-up question. +1. If you want to ask a new question unrelated to the previous conversation, you may receive better answers if you clear the context by typing `/reset` into the input box and selecting **Send**. -To give feedback, select the **Give Feedback** link. +To give feedback about a specific response, use the feedback buttons in the response message. +Or, you can add a comment in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/415591). NOTE: -Only the last 50 messages in the chat history are retained. The chat history expires 3 days after last use. - -### Summarize merge request changes **(ULTIMATE SAAS)** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10400) in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). - -This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's GPT-3. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. - -You can generate a merge request summary in a merge request comment. - -- In a comment, type `/summarize_diff`. - -This action posts a comment from a GitLab bot. The comment provides a summary of the changes and the related SHA for when that summary was generated. - -Provide feedback on this experimental feature in [issue 408726](https://gitlab.com/gitlab-org/gitlab/-/issues/408726). - -**Data usage**: When you use this quick action, the diff of changes between the head of the source branch -and the target branch is sent to the large language model referenced above. - -### Summarize my merge request review **(ULTIMATE SAAS)** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10466) in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). +Only the last 50 messages are retained in the chat history. The chat history expires 3 days after last use. -This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's GPT-3. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. - -When you've completed your review of a merge request and are ready to [submit your review](project/merge_requests/reviews/index.md#submit-a-review), you can have a summary generated for you. - -To generate the summary: - -1. When you are ready to submit your review, select **Finish review**. -1. Select **AI Actions** (**{tanuki}**). -1. Select **Summarize my code review**. +### Summarize issue discussions **(ULTIMATE SAAS)** -The summary is displayed in the comment box. You can edit and refine the summary prior to submitting your review. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10344) in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). -Provide feedback on this experimental feature in [issue 408991](https://gitlab.com/gitlab-org/gitlab/-/issues/408991). +This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's +GPT-3. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. -**Data usage**: When you use this feature, the following data is sent to the large language model referenced above: +You can generate a summary of discussions on an issue: -- Draft comment's text -- File path of the commented files +1. In an issue, scroll to the **Activity** section. +1. Select **View summary**. -### Generate suggested tests in merge requests **(ULTIMATE SAAS)** +The comments in the issue are summarized in as many as 10 list items. +The summary is displayed only for you. -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10366) in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). +Provide feedback on this experimental feature in [issue 407779](https://gitlab.com/gitlab-org/gitlab/-/issues/407779). -This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's GPT-3. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. +**Data usage**: When you use this feature, the text of public comments on the issue are sent to the large +language model referenced above. -In a merge request, you can get a list of suggested tests for the file you are reviewing. This functionality can help determine if appropriate test coverage has been provided, or if you need more coverage for your project. +### Show deployment frequency forecast **(ULTIMATE SAAS)** -To generate a test suggestion: +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10228) in GitLab 16.2 as an [Experiment](../policy/experiment-beta-support.md#experiment). -1. In a merge request, select the **Changes** tab. -1. On the header for the file, in the upper-right corner, select **Options** (**{ellipsis_v}**). -1. Select **Suggest test cases**. +This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com. -The test suggestion is generated in a sidebar. You can copy the suggestion to your editor and use it as the start of your tests. +In CI/CD Analytics, you can view a forecast of deployment frequency: -Feedback on this experimental feature can be provided in [issue 408995](https://gitlab.com/gitlab-org/gitlab/-/issues/408995). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Analyze > CI/CD analytics**. +1. Select the **Deployment frequency** tab. +1. Turn on the **Show forecast** toggle. +1. On the confirmation dialog, select **Accept testing terms**. -**Data usage**: When you use this feature, the following data is sent to the large language model referenced above: +The forecast is displayed as a dotted line on the chart. Data is forecasted for a duration that is half of the selected date range. +For example, if you select a 30-day range, a forecast for the following 15 days is displayed. -- Contents of the file -- The file name +Provide feedback on this experimental feature in [issue 416833](https://gitlab.com/gitlab-org/gitlab/-/issues/416833). -### Summarize issue discussions **(ULTIMATE SAAS)** +### Generate issue descriptions **(ULTIMATE SAAS)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10344) in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10762) in GitLab 16.3 as an [Experiment](../policy/experiment-beta-support.md#experiment). This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's GPT-3. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. -You can generate a summary of discussions on an issue: +You can generate the description for an issue from a short summary. -1. In an issue, scroll to the **Activity** section. -1. Select **View summary**. +1. Create a new issue. +1. Above the **Description** field, select **AI actions > Generate issue description**. +1. Write a short description and select **Submit**. -The comments in the issue are summarized in as many as 10 list items. -The summary is displayed only for you. +The issue description is replaced with AI-generated text. -Provide feedback on this experimental feature in [issue 407779](https://gitlab.com/gitlab-org/gitlab/-/issues/407779). +Provide feedback on this experimental feature in [issue 409844](https://gitlab.com/gitlab-org/gitlab/-/issues/409844). -**Data usage**: When you use this feature, the text of public comments on the issue are sent to the large +**Data usage**: When you use this feature, the text you enter is sent to the large language model referenced above. ## Data Usage @@ -236,7 +219,7 @@ GitLab AI features leverage generative AI to help increase velocity and aim to h ### Progressive enhancement -These features are designed as a progressive enhancement to existing GitLab features across our DevSecOps platform. They are designed to fail gracefully and should not prevent the core functionality of the underlying feature. Please note each feature is subject to its expected functionality as defined by the relevant [feature support policy](../policy/experiment-beta-support.md). +These features are designed as a progressive enhancement to existing GitLab features across our DevSecOps platform. They are designed to fail gracefully and should not prevent the core functionality of the underlying feature. You should note each feature is subject to its expected functionality as defined by the relevant [feature support policy](../policy/experiment-beta-support.md). ### Stability and performance @@ -246,7 +229,7 @@ These features are in a variety of [feature support levels](../policy/experiment ### Data privacy -Some AI features require the use of third-party AI services models and APIs from: Google AI and OpenAI. The processing of any personal data is in accordance with our [Privacy Statement](https://about.gitlab.com/privacy/). You may also visit the [Sub-Processors page](https://about.gitlab.com/privacy/subprocessors/#third-party-sub-processors) to see the list of our Sub-Processors that we use in order to provide these features. +Some AI features require the use of third-party AI services models and APIs from: Google AI and OpenAI. The processing of any personal data is in accordance with our [Privacy Statement](https://about.gitlab.com/privacy/). You may also visit the [Sub-Processors page](https://about.gitlab.com/privacy/subprocessors/#third-party-sub-processors) to see the list of our Sub-Processors that we use to provide these features. Group owners can control which top-level groups have access to third-party AI features by using the [group level third-party AI features setting](group/manage.md#enable-third-party-ai-features). @@ -261,4 +244,4 @@ Generative AI may produce unexpected results that may be: - Insecure code - Offensive or insensitive -GitLab is actively iterating on all our AI-assisted capabilities to improve the quality of the generated content. We will continue improving the quality through prompt engineering, evaluating new AI/ML models to power these features, and through novel heuristics built into these features directly. +GitLab is actively iterating on all our AI-assisted capabilities to improve the quality of the generated content. We improve the quality through prompt engineering, evaluating new AI/ML models to power these features, and through novel heuristics built into these features directly. diff --git a/doc/user/analytics/analytics_dashboards.md b/doc/user/analytics/analytics_dashboards.md index 9d2c91b6bc8..49870e8c66c 100644 --- a/doc/user/analytics/analytics_dashboards.md +++ b/doc/user/analytics/analytics_dashboards.md @@ -4,7 +4,7 @@ group: Product Analytics 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 --- -# Analytics dashboards (Experiment) **(ULTIMATE)** +# Analytics dashboards (Experiment) **(ULTIMATE ALL)** > Introduced in GitLab 15.9 as an [Experiment](../../policy/experiment-beta-support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. Disabled by default. @@ -24,17 +24,24 @@ filters and visualizations to query and retrieve results. The following data sources are configured for analytics dashboards: - [Product analytics](../product_analytics/index.md) +- [Value Stream Management](../analytics/value_streams_dashboard.md) ## Built-in dashboards -To help you get started with analytics, GitLab provides two built-in dashboards with predefined visualizations: +To help you get started with analytics, GitLab provides built-in dashboards with predefined visualizations. -- **Audience**, which displays metrics related to traffic, such as number of users and sessions. -- **Behavior**, which displays metrics related to user activity, such as number of page views and events. +### Product analytics + +- **Audience** displays metrics related to traffic, such as the number of users and sessions. +- **Behavior** displays metrics related to user activity, such as the number of page views and events. These dashboards are labeled **By GitLab**, and you cannot edit them. Instead, you can create a custom dashboard with a similar style. +### Value Stream Management + +- **Value Streams Dashboard** displays metrics related to [DevOps performance, security exposure, and workstream optimization](../analytics/value_streams_dashboard.md#devsecops-metrics-comparison-panel). + ## Custom dashboards With custom dashboards, you can design and create visualizations for the metrics that are most relevant to your use case. @@ -69,10 +76,14 @@ You can use the dashboard designer to: ## View project dashboards +Prerequisite: + +- You must have at least the Developer role for the project. + To view a list of dashboards (both built-in and custom) for a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Analyze > Dashboards**. +1. Select **Analyze > Analytics dashboards**. 1. From the list of available dashboards, select the dashboard you want to view. ## Change the location of dashboards @@ -170,7 +181,7 @@ create a `line_chart.yaml` file with the following required fields: To create a custom dashboard: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Analyze > Dashboards**. +1. Select **Analyze > Analytics dashboards**. 1. Select **New dashboard**. 1. In the **New dashboard** input, enter the name of the dashboard. 1. From the **Add visualizations** list on the right, select the visualizations to add to the dashboard. @@ -184,7 +195,7 @@ You can edit your custom dashboard's title and add or resize visualizations in t To edit an existing custom dashboard: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Analyze > Dashboards**. +1. Select **Analyze > Analytics dashboards**. 1. From the list of available dashboards, select a custom dashboard (one without the `By GitLab` label) you want to edit. 1. Select **Edit**. 1. Optional. Change the title of the dashboard. diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index daee21d2567..8dc69b2f664 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# CI/CD analytics **(FREE)** +# CI/CD analytics **(FREE ALL)** Use the CI/CD analytics page to view pipeline success rates and duration, and the history of DORA metrics over time. @@ -35,7 +35,7 @@ To view CI/CD analytics: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Analyze > CI/CD analytics**. -## View DORA deployment frequency chart **(ULTIMATE)** +## View DORA deployment frequency chart **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.8. @@ -56,7 +56,7 @@ To view the deployment frequency chart:  -## View DORA lead time for changes chart **(ULTIMATE)** +## View DORA lead time for changes chart **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250329) in GitLab 13.11. @@ -78,7 +78,7 @@ To view the lead time for changes chart:  -## View DORA time to restore service chart **(ULTIMATE)** +## View DORA time to restore service chart **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356959) in GitLab 15.1 @@ -94,7 +94,7 @@ To view the time to restore service chart:  -## View DORA change failure rate chart **(ULTIMATE)** +## View DORA change failure rate chart **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357072) in GitLab 15.2 diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 646a85fc7a2..27d3e45803e 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -5,7 +5,7 @@ group: Optimize 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 --- -# Code review analytics **(PREMIUM)** +# Code review analytics **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. diff --git a/doc/user/analytics/contributor_statistics.md b/doc/user/analytics/contributor_statistics.md new file mode 100644 index 00000000000..514f1ca42ab --- /dev/null +++ b/doc/user/analytics/contributor_statistics.md @@ -0,0 +1,48 @@ +--- +stage: Plan +group: Optimize +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 +--- + +# Contributor statistics **(FREE ALL)** + +Contributor statistics give you an overview of the commits made by projects members to a project over time. + +## View contributor statistics + +The contributor statistics page displays a line chart with the number of commits to the selected project branch over time, +and line charts with the number of commits by each project member. + +To view contributor statistics for a project: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Analyze > Contributor statistics**. +1. From the **Branches** (**main**) dropdown list, select the branch you want to view commits for. +1. To view the number of commits made on a specific day, hover over the line chart. +1. Optional. To display commits only for a specific time period, select the pause icons (**{status-paused}**) and slide them along the horizontal axis: + + - To change the start date, slide the left pause icon to the left or right. + - To change the end date, slide the right pause icon to the left or right. + +## View project commit history + +To view a list of commits made by project members per day: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Analyze > Contributor statistics**. +1. Select **History**. +1. From the **Branches** (**main**) dropdown list, select the branch you want to view commits for. +1. To view the number of commits made by the members on a specific day, hover over the line chart. +1. Optional. Filter the results. + + - To filter by author, from the **Author** dropdown list, select the user whose commits you want to view. + - To filter by commit message, in the text box, enter your search criteria. + +## Retrieve project commits as an RSS feed + +To view the list of commits to the project as an RSS feed in Atom format: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Analyze > Contributor statistics**. +1. Select **History**. +1. In the upper-right corner, select the feed symbol (**{rss}**). diff --git a/doc/user/analytics/dora_metrics.md b/doc/user/analytics/dora_metrics.md index bdfeffcec05..0efe4a53427 100644 --- a/doc/user/analytics/dora_metrics.md +++ b/doc/user/analytics/dora_metrics.md @@ -4,7 +4,7 @@ group: Optimize 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 --- -# DevOps Research and Assessment (DORA) metrics **(ULTIMATE)** +# DevOps Research and Assessment (DORA) metrics **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.7. > - [Added support](https://gitlab.com/gitlab-org/gitlab/-/issues/291746) for lead time for changes in GitLab 13.10. @@ -131,9 +131,9 @@ To improve this metric, you should consider: The DORA metrics are displayed on the following charts: -- [Value Streams Dashboard](value_streams_dashboard.md), which helps you identify trends, patterns, and opportunities for improvement. +- [Value Streams Dashboard](value_streams_dashboard.md), which helps you identify trends, patterns, and opportunities for improvement. DORA metrics are displayed in the [metrics comparison panel](value_streams_dashboard.md#devsecops-metrics-comparison-panel) and the [DORA Performers score panel](value_streams_dashboard.md#dora-performers-score-panel). - [CI/CD analytics charts](ci_cd_analytics.md), which show pipeline success rates and duration, and the history of DORA metrics over time. -- Insights reports for [groups](../group/insights/index.md) and [projects](value_stream_analytics.md), where you can also use [DORA query parameters](../../user/project/insights/index.md#dora-query-parameters) to create custom charts. +- Insights reports for [groups](../group/insights/index.md) and [projects](../group/value_stream_analytics/index.md), where you can also use [DORA query parameters](../../user/project/insights/index.md#dora-query-parameters) to create custom charts. The table below provides an overview of the DORA metrics' data aggregation in different charts. diff --git a/doc/user/analytics/img/dora_performers_score_panel_v16_3.png b/doc/user/analytics/img/dora_performers_score_panel_v16_3.png Binary files differnew file mode 100644 index 00000000000..9f59667f9e9 --- /dev/null +++ b/doc/user/analytics/img/dora_performers_score_panel_v16_3.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index c057a8b193d..abeda983dad 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -4,7 +4,7 @@ group: Optimize 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 --- -# Analyze GitLab usage **(FREE)** +# Analyze GitLab usage **(FREE ALL)** ## Instance-level analytics @@ -27,7 +27,7 @@ GitLab provides several analytics features at the group level. Some of these fea - [Issue](../group/issues_analytics/index.md) - [Productivity](productivity_analytics.md) - [Repositories](../group/repositories_analytics/index.md) -- [Value Stream Management Analytics](value_stream_analytics.md), and [Value Stream Management Dashboard](value_streams_dashboard.md) +- [Value Stream Management Analytics](../group/value_stream_analytics/index.md), and [Value Stream Management Dashboard](value_streams_dashboard.md) ## Project-level analytics @@ -38,12 +38,13 @@ You can use GitLab to review analytics at the project level. Some of these featu - [Application Security](../application_security/security_dashboard/index.md) - [CI/CD & DORA](ci_cd_analytics.md) - [Code Review](code_review_analytics.md) +- [Contributor statistics](../../user/analytics/contributor_statistics.md) - [Insights](../project/insights/index.md) -- [Issue](../group/issues_analytics/index.md) +- [Issue](../../user/analytics/issue_analytics.md) - [Merge Request](merge_request_analytics.md), enabled with the `project_merge_request_analytics` [feature flag](../../development/feature_flags/index.md#enabling-a-feature-flag-locally-in-development) - [Repository](repository_analytics.md) -- [Value Stream Management Analytics](value_stream_analytics.md), and [Value Stream Management Dashboard](value_streams_dashboard.md) +- [Value Stream Management Analytics](../group/value_stream_analytics/index.md), and [Value Stream Management Dashboard](value_streams_dashboard.md) ### Remove project analytics from the left sidebar @@ -67,8 +68,7 @@ Be sure to review the documentation page for this feature for GitLab tier requir You can use the following analytics features to analyze and visualize the performance of your projects and groups: -- [Value stream analytics for projects](value_stream_analytics.md) -- [Value stream analytics for groups](../group/value_stream_analytics/index.md) +- [Value stream analytics for projects and groups](../group/value_stream_analytics/index.md) - [Value streams dashboard](value_streams_dashboard.md) ## Glossary diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index aaf33f48df2..7caee947318 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -5,7 +5,7 @@ group: Optimize 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 --- -# Issue analytics for projects **(PREMIUM)** +# Issue analytics for projects **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in GitLab 12.9. diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index eeaa8271749..998f56ac40a 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -5,7 +5,7 @@ group: Optimize 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 --- -# Merge request analytics **(PREMIUM)** +# Merge request analytics **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229045) in GitLab 13.3. > - Moved to GitLab Premium in 13.9. diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index f53b516dd0d..ea896f07204 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -4,7 +4,7 @@ group: Optimize 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 --- -# Productivity analytics **(PREMIUM)** +# Productivity analytics **(PREMIUM ALL)** You can use productivity analytics to identify: diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index e686d76eda2..46fa36658c4 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -4,7 +4,7 @@ group: Optimize 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 --- -# Repository analytics for projects **(FREE)** +# Repository analytics for projects **(FREE ALL)** Use repository analytics to view information about a project's Git repository: diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md deleted file mode 100644 index 292a6f430d9..00000000000 --- a/doc/user/analytics/value_stream_analytics.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -remove_date: '2023-07-22' -redirect_to: '../group/value_stream_analytics/index.md' ---- - -# Value stream analytics for projects **(FREE)** - -This document was moved to [another location](../group/value_stream_analytics/index.md). - -<!-- This redirect file can be deleted after 2023-07-22. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md index a853263d20f..2c6626ad315 100644 --- a/doc/user/analytics/value_streams_dashboard.md +++ b/doc/user/analytics/value_streams_dashboard.md @@ -4,19 +4,17 @@ group: Optimize 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 --- -# Value Streams Dashboard **(ULTIMATE)** +# Value Streams Dashboard **(ULTIMATE ALL)** > - Introduced in GitLab 15.8 as a Closed [Beta](../../policy/experiment-beta-support.md#beta) feature [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. Disabled by default. > - Released in GitLab 15.11 as an Open [Beta](../../policy/experiment-beta-support.md#beta) feature [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/392734) in GitLab 16.0. Feature flag `group_analytics_dashboards_page` removed. -You can leave feedback on dashboard bugs or functionality in [issue 381787](https://gitlab.com/gitlab-org/gitlab/-/issues/381787). +You can leave feedback on dashboard bugs or functionality in [issue 419488](https://gitlab.com/gitlab-org/gitlab/-/issues/419488). For more information, see also the [Value Stream Management category direction page](https://about.gitlab.com/direction/plan/value_stream_management/). The Value Streams Dashboard is a customizable dashboard you can use to identify trends, patterns, and opportunities for digital transformation improvements. - -With the Value Streams Dashboard, you can compare software delivery metrics. -This comparison can help you understand whether projects and groups are improving. +The centralized UI in Value Streams Dashboard acts as the single source of truth (SSOT), where all stakeholders can access and view the same set of metrics that are relevant to the organization. The Value Streams Dashboard includes the following metrics: @@ -24,14 +22,16 @@ The Value Streams Dashboard includes the following metrics: - [Value Stream Analytics (VSA) - flow metrics](../group/value_stream_analytics/index.md) - [Vulnerabilities](https://gitlab.com/gitlab-org/gitlab/-/security/vulnerability_report) metrics. -The Value Streams Dashboard allows you to: +With the Value Streams Dashboard, you can: -- Aggregate data records from different APIs. -- Track software performance (DORA) and flow of value (VSA) across the organization. +- Track and compare the above metrics over a period of time. +- Identify downward trends early on. +- Understand security exposure. +- Drill down into individual projects or metrics to take actions for improvement. -## DevOps metrics comparison panel +## DevSecOps metrics comparison panel -The DevOps metrics comparison displays DORA4 and flow metrics for a group or project in the +The DevSecOps metrics comparison displays DORA4, vulnerability, and flow metrics for a group or project in the month-to-date, last month, the month before, and the past 180 days. This visualization helps you get a high-level custom view over multiple DevOps metrics and @@ -44,19 +44,52 @@ that are the largest value contributors, overperforming, or underperforming. You can also drill down the metrics for further analysis. When you hover over a metric, a tooltip displays an explanation of the metric and a link to the related documentation page. +## DORA Performers score panel + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386843) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `dora_performers_score_panel`. Disabled by default. + +FLAG: +By default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `dora_performers_score_panel`. + +The [DORA metrics](dora_metrics.md) Performers score panel is a bar chart that visualizes the status of the organization's DevOps performance levels across different projects. + +The chart is a breakdown of your project's DORA scores, categorized as high, medium, or low. +It aggregates all the child projects in the group. + +Each bar on the chart displays the sum of total projects per score category, calculated monthly. +To exclude data from the chart (for example, "Not Included"), in the legend select the series you want to exclude. +Hovering over each bar reveals a dialog that explains the score's definition. + +For example, if a project has a high score for Deployment Frequency (Velocity), it means that the project has one or more deploys to production per day. + +| Metric | Description | High | Medium | Low | +|--------|-------------|------|--------|-----| +| Deployment frequency | The number of deploys to production per day | ≥30 | 1-29 | \<1 | +| Lead time for changes | The number of days to go from code committed to code successfully running in production| ≤7 | 8-29 | ≥30 | +| Time to restore service | The number of days to restore service when a service incident or a defect that impacts users occurs | ≤1 | 2-6 | ≥7 | +| Change failure rate | The percentage of changes to production resulted in degraded service | ≤15% | 16%-44% | ≥45% | + +These scoring are based on Google's classifications in the [DORA 2022 Accelerate State of DevOps Report](https://cloud.google.com/blog/products/devops-sre/dora-2022-accelerate-state-of-devops-report-now-out). + ## View the value streams dashboard Prerequisite: -- To view the value streams dashboard for a group, you must have at least the Reporter role for the group. +- You must have at least the Reporter role for the group. To view the value streams dashboard: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. -1. Select **Analyze > Value stream analytics**. -1. Below the **Filter results** text box, in the **Lifecycle metrics** row, select **Value Streams Dashboard / DORA**. -1. Optional. To open the new page, append this path `/analytics/dashboards/value_streams_dashboard` to the group URL -(for example, `https://gitlab.com/groups/gitlab-org/-/analytics/dashboards/value_streams_dashboard`). +- From Analytics Dashboards: + + 1. On the group left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. + 1. Select **Analyze > Analytics Dashboards**. + +- From Value Stream Analytics: + + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. + 1. Select **Analyze > Value stream analytics**. + 1. Below the **Filter results** text box, in the **Lifecycle metrics** row, select **Value Streams Dashboard / DORA**. + 1. Optional. To open the new page, append this path `/analytics/dashboards/value_streams_dashboard` to the group URL (for example, `https://gitlab.com/groups/gitlab-org/-/analytics/dashboards/value_streams_dashboard`). ## Customize the dashboard panels @@ -117,7 +150,6 @@ description: 'Custom description' # * issues # * issues_completed # * merge_request_throughput -# (This option is dependant on the `vsd_graphql_dora_and_flow_metrics` feature.) panels: - title: 'My Custom Project' data: @@ -164,3 +196,13 @@ For an overview of editing label filters in the configuration file, see [GitLab | Merge request throughput | The number of merge requests merged by month. | [Groups Productivity analytics](productivity_analytics.md), [Projects Merge Request Analytics](https://gitlab.com/gitlab-org/gitlab/-/analytics/merge_request_analytics) | [Groups Productivity analytics](productivity_analytics.md) [Projects Merge request analytics](merge_request_analytics.md) | `merge_request_throughput` | | Critical vulnerabilities over time | Critical vulnerabilities over time in project or group | [Vulnerability report](https://gitlab.com/gitlab-org/gitlab/-/security/vulnerability_report) | [Vulnerability report](../application_security/vulnerability_report/index.md) | `vulnerability_critical` | | High vulnerabilities over time | High vulnerabilities over time in project or group | [Vulnerability report](https://gitlab.com/gitlab-org/gitlab/-/security/vulnerability_report) | [Vulnerability report](../application_security/vulnerability_report/index.md) | `vulnerability_high` | + +## Value Streams Dashboard metrics with Jira + +The following metrics do not depend on using Jira: + +- DORA Deployment frequency +- DORA Lead time for changes +- Number of deploys +- Merge request throughput +- Vulnerabilities diff --git a/doc/user/application_security/api_fuzzing/create_har_files.md b/doc/user/application_security/api_fuzzing/create_har_files.md index 0ad87facc50..b82ea30b463 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# HTTP Archive format **(ULTIMATE)** +# HTTP Archive format **(ULTIMATE ALL)** HTTP Archive (HAR) format files are an industry standard for exchanging information about HTTP requests and HTTP responses. A HAR file's content is JSON formatted, containing browser interactions diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index e8feb0f4a59..c365c7f6bab 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Web API Fuzz Testing **(ULTIMATE)** +# Web API Fuzz Testing **(ULTIMATE ALL)** Web API fuzzing performs fuzz testing of API operation parameters. Fuzz testing sets operation parameters to unexpected values in an effort to cause unexpected behavior and errors in the API @@ -1108,7 +1108,7 @@ profile increases as the number of tests increases. |[`FUZZAPI_EXCLUDE_PARAMETER_ENV`](#exclude-parameters) | JSON string containing excluded parameters. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. | |[`FUZZAPI_EXCLUDE_PARAMETER_FILE`](#exclude-parameters) | Path to a JSON file containing excluded parameters. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. | |[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI Specification file or URL. | -|[`FUZZAPI_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. | +|[`FUZZAPI_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. Introduced in GitLab 14.7. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/345950`. | |[`FUZZAPI_OPENAPI_ALL_MEDIA_TYPES`](#openapi-specification) | Use all supported media types instead of one when generating requests. Causes test duration to be longer. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`FUZZAPI_OPENAPI_MEDIA_TYPES`](#openapi-specification) | Colon (`:`) separated media types accepted for testing. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | diff --git a/doc/user/application_security/api_security/api_discovery/index.md b/doc/user/application_security/api_security/api_discovery/index.md index c7ae47a7083..0d7bb2830e9 100644 --- a/doc/user/application_security/api_security/api_discovery/index.md +++ b/doc/user/application_security/api_security/api_discovery/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# API Discovery **(ULTIMATE)** +# API Discovery **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9302) in GitLab 15.9. The API Discovery feature is in [Beta](../../../../policy/experiment-beta-support.md). diff --git a/doc/user/application_security/api_security/index.md b/doc/user/application_security/api_security/index.md index 5c2e74bceae..37549d5db51 100644 --- a/doc/user/application_security/api_security/index.md +++ b/doc/user/application_security/api_security/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# API Security **(ULTIMATE)** +# API Security **(ULTIMATE ALL)** API Security refers to the measures taken to secure and protect web Application Programming Interfaces (APIs) from unauthorized access, misuse, and attacks. APIs are a crucial component of modern application development as they allow applications to interact with each other and exchange data. diff --git a/doc/user/application_security/breach_and_attack_simulation/index.md b/doc/user/application_security/breach_and_attack_simulation/index.md index bb67150d4fa..dab625bc169 100644 --- a/doc/user/application_security/breach_and_attack_simulation/index.md +++ b/doc/user/application_security/breach_and_attack_simulation/index.md @@ -5,7 +5,7 @@ info: Breach and Attack Simulation is a GitLab Incubation Engineering program. N type: reference, howto --- -# Breach and Attack Simulation **(ULTIMATE)** +# Breach and Attack Simulation **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/402784) in GitLab 15.11 as an Incubating feature. > - [Included](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119981) in the `Security/BAS.latest.gitlab-ci.yml` in GitLab 16.0. diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index bbb7bf2f625..10e16a173d8 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -5,7 +5,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Security configuration **(FREE)** +# Security configuration **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in GitLab 12.6. > - SAST configuration was [enabled](https://gitlab.com/groups/gitlab-org/-/epics/3659) in 13.3 and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in 13.4. @@ -73,12 +73,9 @@ You can configure the following security controls: - [Coverage Fuzzing](../coverage_fuzzing/index.md) - Can be configured with `.gitlab-ci.yml`. For more details, read [Coverage Fuzzing](../../../user/application_security/coverage_fuzzing/index.md#enable-coverage-guided-fuzz-testing). -## Compliance **(ULTIMATE)** +## Compliance **(ULTIMATE ALL)** You can configure the following security controls: -- [License Compliance](../../../user/compliance/license_compliance/index.md) - - Can be configured with `.gitlab-ci.yml`. For more details, read [License Compliance](../../../user/compliance/license_compliance/index.md#enable-license-compliance). - - [Security Training](../../../user/application_security/vulnerabilities/index.md#enable-security-training-for-vulnerabilities) - Enable **Security training** for the current project. For more details, read [security training](../../../user/application_security/vulnerabilities/index.md#enable-security-training-for-vulnerabilities). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 791a73bfdc2..04b0bace265 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -5,7 +5,7 @@ group: Composition Analysis 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 --- -# Container Scanning **(FREE)** +# Container Scanning **(FREE ALL)** > - Improved support for FIPS [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) in GitLab 13.6 by upgrading `CS_MAJOR_VERSION` from `2` to `3`. > - Integration with Trivy [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322656) in GitLab 13.9 by upgrading `CS_MAJOR_VERSION` from `3` to `4`. @@ -430,7 +430,7 @@ container_scanning: The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#for-a-project), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. -### Vulnerability allowlisting **(ULTIMATE)** +### Vulnerability allowlisting **(ULTIMATE ALL)** To allowlist specific vulnerabilities, follow these steps: @@ -602,7 +602,7 @@ variables: SOURCE_IMAGE: registry.gitlab.com/security-products/container-scanning:6 TARGET_IMAGE: $CI_REGISTRY/namespace/container-scanning -image: docker:stable +image: docker:latest update-scanner-image: services: @@ -748,7 +748,7 @@ Database update information for other analyzers is available in the After a vulnerability is found, you can [address it](../vulnerabilities/index.md). -## Solutions for vulnerabilities (auto-remediation) **(ULTIMATE)** +## Solutions for vulnerabilities (auto-remediation) **(ULTIMATE ALL)** Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index b0571c8a6ca..59bd2b1ffb3 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -4,7 +4,7 @@ group: Dynamic Analysis 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 --- -# Coverage-guided fuzz testing **(ULTIMATE)** +# Coverage-guided fuzz testing **(ULTIMATE ALL)** Coverage-guided fuzz testing sends random inputs to an instrumented version of your application in an effort to cause unexpected behavior. Such behavior indicates a bug that you should address. diff --git a/doc/user/application_security/dast/authentication.md b/doc/user/application_security/dast/authentication.md index 1a68abd01f6..b13b41e4a37 100644 --- a/doc/user/application_security/dast/authentication.md +++ b/doc/user/application_security/dast/authentication.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# DAST authentication **(ULTIMATE)** +# DAST authentication **(ULTIMATE ALL)** WARNING: **DO NOT** use credentials that are valid for production systems, production servers, or any that diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 0338555598c..26782c319b1 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# DAST browser-based analyzer **(ULTIMATE)** +# DAST browser-based analyzer **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323423) in GitLab 13.12 as a Beta feature. > - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/9023) in GitLab 15.7 (GitLab DAST v3.0.50). diff --git a/doc/user/application_security/dast/browser_based_troubleshooting.md b/doc/user/application_security/dast/browser_based_troubleshooting.md index f659001e7c5..446cd0aaa92 100644 --- a/doc/user/application_security/dast/browser_based_troubleshooting.md +++ b/doc/user/application_security/dast/browser_based_troubleshooting.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Troubleshooting DAST browser-based analyzer **(ULTIMATE)** +# Troubleshooting DAST browser-based analyzer **(ULTIMATE ALL)** The following troubleshooting scenarios have been collected from customer support cases. If you experience a problem not addressed here, or the information here does not fix your problem, create a diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index bafe426ca43..1b3ce45dc43 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -4,7 +4,7 @@ group: Dynamic Analysis 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 --- -# DAST browser-based crawler vulnerability checks **(ULTIMATE)** +# DAST browser-based crawler vulnerability checks **(ULTIMATE ALL)** The [DAST browser-based crawler](../browser_based.md) provides a number of vulnerability checks that are used to scan for vulnerabilities in the site under test. diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index c2e7f153e02..08f819e020c 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Troubleshooting DAST proxy-based analyzer **(ULTIMATE)** +# Troubleshooting DAST proxy-based analyzer **(ULTIMATE ALL)** The following troubleshooting scenarios have been collected from customer support cases. If you experience a problem not addressed here, or the information here does not fix your problem, create a diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 1f4506a22e5..24aadd14dd1 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Dynamic Application Security Testing (DAST) **(ULTIMATE)** +# Dynamic Application Security Testing (DAST) **(ULTIMATE ALL)** If you deploy your web application into a new environment, your application may become exposed to new types of attacks. For example, misconfigurations of your diff --git a/doc/user/application_security/dast/proxy-based.md b/doc/user/application_security/dast/proxy-based.md index 0eec04bfeff..3052fd3a72d 100644 --- a/doc/user/application_security/dast/proxy-based.md +++ b/doc/user/application_security/dast/proxy-based.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# DAST proxy-based analyzer **(ULTIMATE)** +# DAST proxy-based analyzer **(ULTIMATE ALL)** The DAST proxy-based analyzer can be added to your [GitLab CI/CD](../../../ci/index.md) pipeline. This helps you discover vulnerabilities in web applications that do not use JavaScript heavily. For applications that do, @@ -461,7 +461,11 @@ The DAST job does not require the project's repository to be present when runnin ## On-demand scans -> Auditing for DAST profile management [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. +> - Auditing for DAST profile management [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. +> - Scheduled on-demand DAST scans [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3 [with a flag](../../../administration/feature_flags.md) named `dast_on_demand_scans_scheduler`. Disabled by default. +> - Scheduled on-demand DAST scans [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.5. Feature flag `dast_on_demand_scans_scheduler` removed. +> - Runner tags selection [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345430) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `on_demand_scans_runner_tags. Disabled by default. +> - Runner tags selection [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111499) in GitLab 16.3. An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger the scan. You must either start it manually, or schedule it to run. For on-demand DAST scans, @@ -501,7 +505,7 @@ To run an existing on-demand scan: 1. In the scan's row, select **Run scan**. If the branch saved in the scan no longer exists, you must: - + 1. [Edit the scan](#edit-an-on-demand-scan). 1. Select a new branch. 1. Save the edited scan. @@ -510,28 +514,26 @@ The on-demand DAST scan runs, and the project's dashboard shows the results. #### Create an on-demand scan -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3. [Deployed behind the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md), disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. -> - [Feature flag `dast_on_demand_scans_scheduler` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.5. - -After you create an on-demand scan, you can: +Create an on-demand scan to: - Run it immediately. - Save it to be run in the future. - Schedule it to be run at a specified schedule. +To create an on-demand DAST scan: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. 1. Select **Secure > On-demand scans**. 1. Select **New scan**. 1. Complete the **Scan name** and **Description** fields. 1. In the **Branch** dropdown list, select the desired branch. +1. Optional. Select the runner tags. 1. Select **Select scanner profile** or **Change scanner profile** to open the drawer, and either: - Select a scanner profile from the drawer, **or** - Select **New profile**, create a [scanner profile](#scanner-profile), then select **Save profile**. 1. Select **Select site profile** or **Change site profile** to open the drawer, and either: - Select a site profile from the **Site profile library** drawer, or - - Select **New profile** create a [site profile](#site-profile), then select **Save profile**. + - Select **New profile**, create a [site profile](#site-profile), then select **Save profile**. 1. To run the on-demand scan: - Immediately, select **Save and run scan**. @@ -675,6 +677,11 @@ To delete a site profile: Validating a site is required to run an active scan. +Prerequisites: + +- A runner must be available in the project to run a validation job. +- The GitLab server's certificate must be trusted and must not use a self-signed certificate. + To validate a site profile: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. @@ -857,3 +864,9 @@ For details of the report's schema, see the [schema for DAST reports](https://gi WARNING: The JSON report artifacts are not a public API of DAST and their format is expected to change in the future. + +## Troubleshooting + +### `unable to get local issuer certificate` when trying to validate a site profile + +The use of self-signed certificates is not supported and may cause the job to fail with an error message: `unable to get local issuer certificate`. For more information, see [issue 416670](https://gitlab.com/gitlab-org/gitlab/-/issues/416670). diff --git a/doc/user/application_security/dast/run_dast_offline.md b/doc/user/application_security/dast/run_dast_offline.md index a75e5832b7c..0101749be71 100644 --- a/doc/user/application_security/dast/run_dast_offline.md +++ b/doc/user/application_security/dast/run_dast_offline.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Run DAST in an offline environment **(ULTIMATE)** +# Run DAST in an offline environment **(ULTIMATE ALL)** For self-managed GitLab instances in an environment with limited, restricted, or intermittent access to external resources through the internet, some adjustments are required for the DAST job to diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index b03f9102dae..ffa2e063535 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# DAST API analyzer **(ULTIMATE)** +# DAST API analyzer **(ULTIMATE ALL)** > DAST API analyzer [became the default analyzer for on-demand DAST API scans](https://gitlab.com/groups/gitlab-org/-/epics/4254) in GitLab 15.6. @@ -1059,7 +1059,7 @@ can be added, removed, and modified by creating a custom configuration. |[`DAST_API_REQUEST_HEADERS`](#request-headers) | A comma-separated (`,`) list of headers to include on each scan request. Consider using `DAST_API_REQUEST_HEADERS_BASE64` when storing secret header values in a [masked variable](../../../ci/variables/index.md#mask-a-cicd-variable), which has character set restrictions. | |[`DAST_API_REQUEST_HEADERS_BASE64`](#request-headers) | A comma-separated (`,`) list of headers to include on each scan request, Base64-encoded. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378440) in GitLab 15.6. | |[`DAST_API_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | -|[`DAST_API_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. | +|[`DAST_API_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. Introduced in GitLab 14.7. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/345950` | |[`DAST_API_OPENAPI_ALL_MEDIA_TYPES`](#openapi-specification) | Use all supported media types instead of one when generating requests. Causes test duration to be longer. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`DAST_API_OPENAPI_MEDIA_TYPES`](#openapi-specification) | Colon (`:`) separated media types accepted for testing. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`DAST_API_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v16_3.png b/doc/user/application_security/dependency_list/img/dependency_list_v16_3.png Binary files differnew file mode 100644 index 00000000000..f3a8f3d8d5d --- /dev/null +++ b/doc/user/application_security/dependency_list/img/dependency_list_v16_3.png diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index d41c0eff860..a55f26f529d 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -5,21 +5,18 @@ group: Composition Analysis 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 --- -# Dependency list **(ULTIMATE)** +# Dependency list **(ULTIMATE ALL)** > - System dependencies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6698) in GitLab 14.6. > - Group-level dependency list [introduced](https://gitlab.com/groups/gitlab-org/-/epics/8090) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `group_level_dependencies`. Disabled by default. -FLAG: -On self-managed GitLab, by default the group-level dependency list is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `group_level_dependencies`. On GitLab.com, this feature is not available. - Use the dependency list to review your project or group's dependencies and key details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Project Dependency](https://www.youtube.com/watch?v=ckqkn9Tnbw4). -To see the dependency list, go to your project and select **Secure > Dependency list**. +To see the dependency list, go to your project or group and select **Secure > Dependency list**. This information is sometimes referred to as a Software Bill of Materials, SBOM, or BOM. @@ -66,6 +63,9 @@ The dependency list shows the path between a dependency and a top-level dependen to, if any. There are many possible paths connecting a transient dependency to top-level dependencies, but the user interface shows only one of the shortest paths. +NOTE: +The dependency path is only displayed for dependencies that have vulnerabilities. +  Dependency paths are supported for the following package managers: @@ -74,21 +74,40 @@ Dependency paths are supported for the following package managers: - [Yarn 1.x](https://classic.yarnpkg.com/lang/en/) - [sbt](https://www.scala-sbt.org) -## Licenses +### Licenses > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab 12.3. -If the [License Compliance](../../compliance/license_compliance/index.md) CI job is configured, -[discovered licenses](../../compliance/license_compliance/index.md#supported-languages-and-package-managers) are displayed on this page. +If the [Dependency Scanning](../../application_security/dependency_scanning/index.md) CI job is configured, +[discovered licenses](../../compliance/license_scanning_of_cyclonedx_files/index.md#enable-license-scanning) are displayed on this page. + +## View a group's dependencies + +FLAG: +On self-managed GitLab, and GitLab.com the feature is disabled by default. To show the feature, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `group_level_dependencies`. + + + +GitLab displays dependencies with the following information: + +| Field | Description | +|-----------|-------------| +| Component | The dependency's name and version. | +| Packager | The packager used to install the dependency. | +| Location | For operating system dependencies, this lists the image that was scanned. For application dependencies, this shows a link to the packager-specific lock file in your project that declared the dependency. It also shows the [dependency path](#dependency-paths) to a top-level dependency, if any, and if supported. If there are multiple locations, the total number of locations is displayed. | +| Projects | Links to the project related to the dependency. If there are multiple projects, the total number of projects is displayed. | + +Displayed dependencies are initially sorted by packager. They +can also be sorted by name. ## Downloading the dependency list -You can download your project's full list of dependencies and their details in +You can download the full list of dependencies and their details in `JSON` format. ### In the UI -You can download your project's list of dependencies and their details in JSON format by selecting the **Export** button. The dependency list only shows the results of the last successful pipeline to run on the default branch. +You can download your group's or project's list of dependencies and their details in JSON format by selecting the **Export** button. The dependency list only shows the results of the last successful pipeline to run on the default branch. ### Using the API diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 15fed4f2adc..5a2394113cb 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -4,39 +4,26 @@ group: Composition Analysis 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 --- -# Dependency Scanning **(ULTIMATE)** +# Dependency Scanning **(ULTIMATE ALL)** -The Dependency Scanning feature can automatically find security vulnerabilities in your -software dependencies while you're developing and testing your applications. For example, -dependency scanning lets you know if your application uses an external (open source) -library that is known to be vulnerable. You can then take action to protect your application. +Dependency Scanning analyzes your application's dependencies for known vulnerabilities. All +dependencies are scanned, including transitive dependencies, also known as nested dependencies. Dependency Scanning is often considered part of Software Composition Analysis (SCA). SCA can contain aspects of inspecting the items your code uses. These items typically include application and system dependencies that are almost always imported from external sources, rather than sourced from items you wrote yourself. +Dependency Scanning can run in the development phase of your application's life cycle. Every time a +pipeline runs, vulnerabilities are identified and compared between the source and target branches. +Vulnerabilities and their severity are listed in the merge request, enabling you to proactively +address the risk to your application, before the code change is committed. + GitLab offers both Dependency Scanning and [Container Scanning](../container_scanning/index.md) to ensure coverage for all of these dependency types. To cover as much of your risk area as possible, we encourage you to use all of our security scanners. For a comparison of these features, see [Dependency Scanning compared to Container Scanning](../comparison_dependency_and_container_scanning.md). -If you're using [GitLab CI/CD](../../../ci/index.md), you can use dependency scanning to analyze -your dependencies for known vulnerabilities. GitLab scans all dependencies, including transitive -dependencies (also known as nested dependencies). You can take advantage of dependency scanning by -either: - -- [Including the dependency scanning template](#configuration) - in your existing `.gitlab-ci.yml` file. -- Implicitly using - the [auto dependency scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning) - provided by [Auto DevOps](../../../topics/autodevops/index.md). - -GitLab checks the dependency scanning report, compares the found vulnerabilities -between the source and target branches, and shows the information on the -merge request. The results are sorted by the [severity](../vulnerabilities/severities.md) of the -vulnerability. -  <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -54,12 +41,7 @@ If you're using the shared runners on GitLab.com, this is enabled by default. Th provided are for the Linux/amd64 architecture. WARNING: -If you use your own runners, make sure your installed version of Docker -is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. - -WARNING: -Dependency Scanning does not support run-time installation of compilers and interpreters. -If you need it, explain why by filling out [the survey](https://docs.google.com/forms/d/e/1FAIpQLScKo7xEYA65rOjPTGIufAyfjPGnCALSJZoTxBlvskfFMEOZMw/viewform). +Dependency Scanning does not support runtime installation of compilers and interpreters. ## Supported languages and package managers @@ -141,9 +123,10 @@ table.supported-languages ul { <td rowspan="2"> 8 LTS, 11 LTS, - or 17 LTS + 17 LTS, + or 21 EA<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-2">2</a></b></sup> </td> - <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-2">2</a></b></sup></td> + <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-3">3</a></b></sup></td> <td> <ul> <li><code>build.gradle</code></li> @@ -175,7 +158,7 @@ table.supported-languages ul { <td>Y</td> </tr> <tr> - <td><a href="https://pnpm.io/">pnpm</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-3">3</a></b></sup></td> + <td><a href="https://pnpm.io/">pnpm</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-4">4</a></b></sup></td> <td><code>pnpm-lock.yaml</code></td> <td>Y</td> </tr> @@ -188,7 +171,7 @@ table.supported-languages ul { </tr> <tr> <td rowspan="4">Python</td> - <td rowspan="4">3.9, 3.10<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-4">4</a></b></sup></td> + <td rowspan="4">3.9, 3.10<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-5">5</a></b></sup></td> <td><a href="https://setuptools.readthedocs.io/en/latest/">setuptools</a></td> <td><code>setup.py</code></td> <td>N</td> @@ -215,7 +198,7 @@ table.supported-languages ul { <td>N</td> </tr> <tr> - <td><a href="https://python-poetry.org/">Poetry</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-5">5</a></b></sup></td> + <td><a href="https://python-poetry.org/">Poetry</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-6">6</a></b></sup></td> <td><code>poetry.lock</code></td> <td>N</td> </tr> @@ -234,7 +217,7 @@ table.supported-languages ul { <tr> <td>Scala</td> <td>All versions</td> - <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-6">6</a></b></sup></td> + <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-7">7</a></b></sup></td> <td><code>build.sbt</code></td> <td>N</td> </tr> @@ -251,18 +234,25 @@ table.supported-languages ul { <li> <a id="notes-regarding-supported-languages-and-package-managers-2"></a> <p> - Gradle is not supported when <a href="https://docs.gitlab.com/ee/development/fips_compliance.html#enable-fips-mode">FIPS mode</a> is enabled. + Java 21 EA is only available when using <a href="https://maven.apache.org/">Maven</a> and is not supported when + <a href="https://docs.gitlab.com/ee/development/fips_compliance.html#enable-fips-mode">FIPS mode</a> is enabled. </p> </li> <li> <a id="notes-regarding-supported-languages-and-package-managers-3"></a> <p> - Support for <code>pnpm</code> lockfiles was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/336809">introduced in GitLab 15.11</a>. <code>pnpm</code> lockfiles do not store bundled dependencies, so the reported dependencies may differ from <code>npm</code> or <code>yarn</code>. + Gradle is not supported when <a href="https://docs.gitlab.com/ee/development/fips_compliance.html#enable-fips-mode">FIPS mode</a> is enabled. </p> </li> <li> <a id="notes-regarding-supported-languages-and-package-managers-4"></a> <p> + Support for <code>pnpm</code> lockfiles was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/336809">introduced in GitLab 15.11</a>. <code>pnpm</code> lockfiles do not store bundled dependencies, so the reported dependencies may differ from <code>npm</code> or <code>yarn</code>. + </p> + </li> + <li> + <a id="notes-regarding-supported-languages-and-package-managers-5"></a> + <p> For support of <code>Python 3.10</code>, add the following stanza to the GitLab CI/CD configuration file. This specifies that the <code>Python 3.10</code> image is to be used, instead of the default <code>Python 3.9</code>. <div class="language-yaml highlighter-rouge"> <div class="highlight"> @@ -272,7 +262,7 @@ table.supported-languages ul { </p> </li> <li> - <a id="notes-regarding-supported-languages-and-package-managers-5"></a> + <a id="notes-regarding-supported-languages-and-package-managers-6"></a> <p> Support for <a href="https://python-poetry.org/">Poetry</a> projects with a <code>poetry.lock</code> file was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/7006">added in GitLab 15.0</a>. Support for projects without a <code>poetry.lock</code> file is tracked in issue: @@ -280,7 +270,7 @@ table.supported-languages ul { </p> </li> <li> - <a id="notes-regarding-supported-languages-and-package-managers-6"></a> + <a id="notes-regarding-supported-languages-and-package-managers-7"></a> <p> Support for <a href="https://www.scala-sbt.org/">sbt</a> 1.3 and above was added in GitLab 13.9. </p> @@ -314,9 +304,13 @@ are analyzed. There is no limit to the depth of nested or transitive dependencie Dependency Scanning supports the following official analyzers: +- `gemnasium` +- `gemnasium-maven` +- `gemnasium-python` + +Each of these supported Gemnasium-based Dependency Scanning analyzers exist in the following project: + - [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) -- [`gemnasium-maven`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven) -- [`gemnasium-python`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python) The analyzers are published as Docker images, which Dependency Scanning uses to launch dedicated containers for each analysis. You can also integrate a custom @@ -339,10 +333,10 @@ The following package managers use lockfiles that GitLab analyzers are capable o | Composer | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/default/composer.lock) | | Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/default/conan.lock#L38) | | Go | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/gosum/default/go.sum) <sup><strong><a href="#notes-regarding-parsing-lockfiles-1">1</a></strong></sup> | -| NuGet | v1, v2 | [4.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/default/src/web.api/packages.lock.json#L2) | -| npm | v1, v2, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-2">2</a></b></sup> | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4), [9.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4) | +| NuGet | v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-2">2</a></b></sup> | [4.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/default/src/web.api/packages.lock.json#L2) | +| npm | v1, v2, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-3">3</a></b></sup> | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4), [9.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4) | | pnpm | v5.3, v5.4, v6 | [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-pnpm/default/pnpm-lock.yaml#L1), [8.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/pnpm/fixtures/v6/simple/pnpm-lock.yaml#L1) | -| yarn | v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-3">3</a></b></sup>, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-3">3</a></b></sup> | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/classic/default/yarn.lock#L2), [2.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v2/default/yarn.lock), [3.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v3/default/yarn.lock) | +| yarn | v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-4">4</a></b></sup>, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-4">4</a></b></sup> | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/classic/default/yarn.lock#L2), [2.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v2/default/yarn.lock), [3.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v3/default/yarn.lock) | | Poetry | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/python-poetry/default/poetry.lock) | <!-- markdownlint-disable MD044 --> @@ -357,12 +351,18 @@ The following package managers use lockfiles that GitLab analyzers are capable o <li> <a id="notes-regarding-parsing-lockfiles-2"></a> <p> - Support for <code>lockfileVersion = 3</code> was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/365176">introduced</a> in GitLab 15.7. + Support for NuGet version 2 lock files was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/398680">introduced</a> in GitLab 16.2. </p> </li> <li> <a id="notes-regarding-parsing-lockfiles-3"></a> <p> + Support for <code>lockfileVersion = 3</code> was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/365176">introduced</a> in GitLab 15.7. + </p> + </li> + <li> + <a id="notes-regarding-parsing-lockfiles-4"></a> + <p> Support for Yarn <code>v2</code> and <code>v3</code> was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/263358">introduced in GitLab 15.11</a>. However, this feature is also available to versions of GitLab 15.0 and later. </p> <p> @@ -585,10 +585,6 @@ configuration, the last mention of the variable takes precedence. ### Overriding dependency scanning jobs -WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead. - To override a job definition (for example, to change properties like `variables` or `dependencies`), declare a new job with the same name as the one to override. Place this new job after the template inclusion and specify any additional keys under it. For example, this disables `DS_REMEDIATE` for @@ -632,7 +628,7 @@ The following variables allow configuration of global dependency scanning settin | `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | | `DS_EXCLUDED_ANALYZERS` | Specify the analyzers (by name) to exclude from Dependency Scanning. For more information, see [Dependency Scanning Analyzers](#dependency-analyzers). | | `DS_EXCLUDED_PATHS` | Exclude files and directories from the scan based on the paths. A comma-separated list of patterns. Patterns can be globs (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"`. | -| `DS_IMAGE_SUFFIX` | Suffix added to the image name. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354796) in GitLab 14.10.) Automatically set to `"-fips"` when FIPS mode is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357922) in GitLab 15.0.) | +| `DS_IMAGE_SUFFIX` | Suffix added to the image name. (Introduced in GitLab 14.10. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/354796`). Automatically set to `"-fips"` when FIPS mode is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357922) in GitLab 15.0.) | | `DS_MAX_DEPTH` | Defines how many directory levels deep that the analyzer should search for supported files to scan. A value of `-1` scans all directories regardless of depth. Default: `2`. | | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). | @@ -649,7 +645,7 @@ The following variables are used for configuring specific analyzers (used for a | `DS_REMEDIATE` | `gemnasium` | `"true"`, `"false"` in FIPS mode | Enable automatic remediation of vulnerable dependencies. Not supported in FIPS mode. | | `DS_REMEDIATE_TIMEOUT` | `gemnasium` | `5m` | Timeout for auto-remediation. | | `GEMNASIUM_LIBRARY_SCAN_ENABLED` | `gemnasium` | `"true"` | Enable detecting vulnerabilities in vendored JavaScript libraries. For now, `gemnasium` leverages [`Retire.js`](https://github.com/RetireJS/retire.js) to do this job. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350512) in GitLab 14.8. | -| `DS_JAVA_VERSION` | `gemnasium-maven` | `17` | Version of Java. Available versions: `8`, `11`, `17`. | +| `DS_JAVA_VERSION` | `gemnasium-maven` | `17` | Version of Java. Available versions: `8`, `11`, `17`, `21` | | `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repositories). | | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | | `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. | @@ -678,6 +674,9 @@ variables: HTTPS_PROXY: "https://squid-proxy:3128" ``` +NOTE: +Gradle projects require [an additional variable](#using-a-proxy-with-gradle-projects) setup to use a proxy. + Alternatively we may use it in specific jobs, like Dependency Scanning: ```yaml @@ -716,7 +715,7 @@ Read more on [how to use private Maven repositories](../index.md#using-private-m #### FIPS-enabled images -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354796) in GitLab 14.10. +> Introduced in GitLab 14.10. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/354796` GitLab also offers [FIPS-enabled Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) versions of the Gemnasium images. You can therefore replace standard images with FIPS-enabled images. @@ -1119,6 +1118,17 @@ gemnasium-dependency_scanning: - tar -xzf gemnasium_db.tar.gz -C $GEMNASIUM_DB_LOCAL_PATH ``` +## Using a proxy with Gradle projects + +The Gradle wrapper script does not read the `HTTP(S)_PROXY` environment variables. See [this upstream issue](https://github.com/gradle/gradle/issues/11065). + +To make the Gradle wrapper script use a proxy, you can specify the options using the `GRADLE_CLI_OPTS` CI/CD variable: + +```yaml +variables: + GRADLE_CLI_OPTS: "-Dhttps.proxyHost=squid-proxy -Dhttps.proxyPort=3128 -Dhttp.proxyHost=squid-proxy -Dhttp.proxyPort=3128 -Dhttp.nonProxyHosts=localhost" +``` + ## Warnings We recommend that you use the most recent version of all containers, and the most recent supported version of all package managers and languages. Using previous versions carries an increased security risk because unsupported versions may no longer benefit from active security reporting and backporting of security fixes. diff --git a/doc/user/application_security/generate_test_vulnerabilities/index.md b/doc/user/application_security/generate_test_vulnerabilities/index.md index 76d2227b86b..f9f93b97baf 100644 --- a/doc/user/application_security/generate_test_vulnerabilities/index.md +++ b/doc/user/application_security/generate_test_vulnerabilities/index.md @@ -1,32 +1,6 @@ --- -type: reference, howto -stage: Govern -group: Threat Insights -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 +redirect_to: '../../../development/sec/generate_test_vulnerabilities.md' +remove_date: '2023-11-01' --- -# Generate test vulnerabilities - -You can generate test vulnerabilities for the [Vulnerability Report](../vulnerability_report/index.md) to test GitLab -vulnerability management features without running a pipeline. - -1. Login in to GitLab. -1. Go to `/-/profile/personal_access_tokens` and generate a personal access token with `api` permissions. -1. Go to your project page and find the project ID. You can find the project ID below the project title. -1. [Clone the GitLab repository](../../../gitlab-basics/start-using-git.md#clone-a-repository) to your local machine. -1. Open a terminal and go to `gitlab/qa` directory. -1. Run `bundle install` -1. Run the following command: - -```shell -GITLAB_QA_ACCESS_TOKEN=<your_personal_access_token> GITLAB_URL="<address:port>" bundle exec rake vulnerabilities:setup\[<your_project_id>,<vulnerability_count>\] --trace -``` - -Make sure you do the following: - -- Replace `<your_personal_access_token>` with the token you generated in step one. -- Double check the `GITLAB_URL`. It should point to address and port of your GitLab instance, for example `http://localhost:3000` if you are running GDK -- Replace `<your_project_id>` with the ID you obtained in step three above. -- Replace `<vulnerability_count>` with the number of vulnerabilities you'd like to generate. - -The script creates the specified number of placeholder vulnerabilities in the project. +This document was moved to [another location](../../../development/sec/generate_test_vulnerabilities.md). diff --git a/doc/user/application_security/get-started-security.md b/doc/user/application_security/get-started-security.md index c1524c4b517..ad49f00a1bd 100644 --- a/doc/user/application_security/get-started-security.md +++ b/doc/user/application_security/get-started-security.md @@ -4,7 +4,7 @@ group: Technical writing 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 --- -# Get started with GitLab application security **(ULTIMATE)** +# Get started with GitLab application security **(ULTIMATE ALL)** <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Adopting GitLab application security](https://www.youtube.com/watch?v=5QlxkiKR04k). diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 7213fa2ba18..334e8c28378 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -4,7 +4,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Infrastructure as Code (IaC) Scanning **(FREE)** +# Infrastructure as Code (IaC) Scanning **(FREE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.5. @@ -28,7 +28,7 @@ GitLab IaC Scanning analyzers don't support running on Windows or on any CPU arc WARNING: If you use your own runners, make sure the Docker version installed -is **not** `19.03.0`. See [troubleshooting information](../sast/index.md#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. +is **not** `19.03.0`. See [troubleshooting information](../sast/troubleshooting.md#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. ## Supported languages and frameworks @@ -128,7 +128,7 @@ To enable IaC Scanning in a project, you can create a merge request: Pipelines now include an IaC Scanning job. -## Customize rulesets **(ULTIMATE)** +## Customize rulesets **(ULTIMATE ALL)** > [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 56a79191833..615ff7e3fda 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -4,7 +4,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Application security **(ULTIMATE)** +# Application security **(ULTIMATE ALL)** GitLab can check your application for security vulnerabilities including: @@ -66,7 +66,7 @@ A source code analysis can: Analysis of the web application occurs on every code commit. As part of the CI/CD pipeline, your application is built, deployed to a test environment, and subjected to the following tests: -- Test for known application vectors - [Dynamic Application Security Testing (DAST)](dast/index.md). +- Test application for known attack vectors - [Dynamic Application Security Testing (DAST)](dast/index.md). - Analysis of APIs for known attack vectors - [API Security](dast_api/index.md). - Analysis of web APIs for unknown bugs and vulnerabilities - [API fuzzing](api_fuzzing/index.md). @@ -124,7 +124,6 @@ To enable all GitLab Security scanning tools, with default settings, enable - [Auto Secret Detection](../../topics/autodevops/stages.md#auto-secret-detection) - [Auto DAST](../../topics/autodevops/stages.md#auto-dast) - [Auto Dependency Scanning](../../topics/autodevops/stages.md#auto-dependency-scanning) -- [Auto License Compliance](../../topics/autodevops/stages.md#auto-license-compliance) - [Auto Container Scanning](../../topics/autodevops/stages.md#auto-container-scanning) While you cannot directly customize Auto DevOps, you can [include the Auto DevOps template in your project's `.gitlab-ci.yml` file](../../topics/autodevops/customize.md#customize-gitlab-ciyml). @@ -224,7 +223,7 @@ We do not recommend changing the job [`allow_failure` setting](../../ci/yaml/ind The artifact generated by the secure analyzer contains all findings it discovers on the target branch, regardless of whether they were previously found, dismissed, or completely new (it puts in everything that it finds). -## View security scan information in merge requests **(FREE)** +## View security scan information in merge requests **(FREE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Free 13.5. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/273205) in 13.6. @@ -417,7 +416,6 @@ For more information about overriding security jobs, see: - [Overriding Container Scanning jobs](container_scanning/index.md#overriding-the-container-scanning-template). - [Overriding Secret Detection jobs](secret_detection/index.md#configure-scan-settings). - [Overriding DAST jobs](dast/proxy-based.md#customize-dast-settings). -- [Overriding License Compliance jobs](../compliance/license_compliance/index.md#overriding-the-template). All the security scanning tools define their stage, so this error can occur with all of them. @@ -576,7 +574,7 @@ If a Secure job is failing and it's unclear why: 1. Enable [debug-level logging](#debug-level-logging). 1. Run the job. 1. Examine the job's output. -1. Set the logging level to `info` (default). +1. Remove the `debug` log level to return to the default `info` value. ### Outdated security reports diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 63f3763cab9..1ab26229b50 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -5,7 +5,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Offline environments **(ULTIMATE SELF)** +# Offline environments **(FREE SELF)** NOTE: To set up an offline environment, you must receive an [opt-out exemption of cloud licensing](https://about.gitlab.com/pricing/licensing-faq/cloud-licensing/#offline-cloud-licensing) prior to purchase. For more details, contact your GitLab sales representative. @@ -93,7 +93,7 @@ above. You can find more information at each of the pages below: - [Secret Detection offline directions](../secret_detection/index.md#running-secret-detection-in-an-offline-environment) - [DAST offline directions](../dast/run_dast_offline.md#run-dast-in-an-offline-environment) - [API Fuzzing offline directions](../api_fuzzing/index.md#running-api-fuzzing-in-an-offline-environment) -- [License Compliance offline directions](../../compliance/license_compliance/index.md#running-license-compliance-in-an-offline-environment) +- [License Scanning offline directions](../../compliance/license_scanning_of_cyclonedx_files/index.md#running-in-an-offline-environment) - [Dependency Scanning offline directions](../dependency_scanning/index.md#running-dependency-scanning-in-an-offline-environment) ## Loading Docker images onto your offline host diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 4e610d64ec9..59e047ce5c6 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -4,7 +4,7 @@ group: Security Policies 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 --- -# Policies **(ULTIMATE)** +# Policies **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in GitLab 13.10 with a flag named `security_orchestration_policies_configuration`. Disabled by default. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab 14.3. @@ -150,5 +150,6 @@ The workaround is to amend your group or instance push rules to allow branches f - When enforcing scan execution policies, the target project's pipeline is triggered by the user who last updated the security policy project's `policy.yml` file. The user must have permission to trigger the pipeline in the project for the policy to be enforced, and the pipeline to run. Work to address this is being tracked in [issue 394958](https://gitlab.com/gitlab-org/gitlab/-/issues/394958). - You should not link a security policy project to a development project and to the group or sub-group the development project belongs to at the same time. Linking this way will result in approval rules from the Scan Result Policy not being applied to merge requests in the development project. - When creating a Scan Result Policy, neither the array `severity_levels` nor the array `vulnerability_states` in the [scan_finding rule](../policies/scan-result-policies.md#scan_finding-rule-type) can be left empty; for a working rule, at least one entry must exist. +- When configuring pipeline and scan result policies, it's important to remember that security scans performed in manual jobs aren't verified to determine whether MR approval is required. When you run a manual job with security scans, it won't ensure approval even if vulnerabilities are introduced. If you are still experiencing issues, you can [view recent reported bugs](https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=popularity&state=opened&label_name%5B%5D=group%3A%3Asecurity%20policies&label_name%5B%5D=type%3A%3Abug&first_page_size=20) and raise new unreported issues. diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index b84d4d2e49e..945d35c89da 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -4,7 +4,7 @@ group: Security Policies 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 --- -# Scan execution policies **(ULTIMATE)** +# Scan execution policies **(ULTIMATE ALL)** > - Group-level security policies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4425) in GitLab 15.2. > - Group-level security policies [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/356258) in GitLab 15.4. @@ -113,6 +113,11 @@ This rule enforces the defined actions whenever the pipeline runs for a selected > - The `branch_type` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404774) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_type`. Disabled by default. > - The `branch_type` field was [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/413062) in GitLab 16.2. +> - The security policy bot users were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394958) in GitLab 16.3 [with flags](../../../administration/feature_flags.md) named `scan_execution_group_bot_users` and `scan_execution_bot_users`. Enabled by default. + +FLAG: +On self-managed GitLab, security policy bot users are available. To hide the feature, an administrator can [disable the feature flags](../../../administration/feature_flags.md) named `scan_execution_group_bot_users` and `scan_execution_bot_users`. +On GitLab.com, this feature is available. This rule enforces the defined actions and schedules a scan on the provided date/time. @@ -127,6 +132,10 @@ This rule enforces the defined actions and schedules a scan on the provided date 1. You must specify only one of `branches`, `branch_type`, or `agents`. +Scheduled scan pipelines are triggered by a security policy bot user that is a guest member of the project. Security policy bot users are automatically created when the security policy project is linked, and removed when the security policy project is unlinked. + +If the project does not have a security policy bot user, the scheduled scan pipeline is triggered by the user that modified the security policy project last. + GitLab supports the following types of CRON syntax for the `cadence` field: - A daily cadence of once per hour at a specified hour, for example: `0 18 * * *` diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 0aac36988d4..c5cfd63641b 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -4,7 +4,7 @@ group: Security Policies 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 --- -# Scan result policies **(ULTIMATE)** +# Scan result policies **(ULTIMATE ALL)** > Group-level scan result policies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7622) in GitLab 15.6. @@ -27,6 +27,23 @@ The following video gives you an overview of GitLab scan result policies: <iframe src="https://www.youtube-nocookie.com/embed/w5I9gcUgr9U" frameborder="0" allowfullscreen> </iframe> </figure> +## Merge request with multiple pipelines + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/379108) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `multi_pipeline_scan_result_policies`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/409482) in GitLab 16.3. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `multi_pipeline_scan_result_policies`. On GitLab.com, this feature is available. + +A project can have multiple pipeline types configured. A single commit can initiate multiple +pipelines, each of which may contain a security scan. + +- In GitLab 16.3 and later, the results of all completed pipelines for the latest commit in +the MR's source and target branch are evaluated and used to enforce the scan result policy. +Parent-child pipelines and on-demand DAST pipelines are not considered. +- In GitLab 16.2 and earlier, only the results of the latest completed pipeline were evaluated +when enforcing scan result policies. + ## Scan result policy editor > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77814) in GitLab 14.8. @@ -77,6 +94,13 @@ the following sections and tables provide an alternative. ## `scan_finding` rule type +> - The scan result policy field `vulnerability_attributes` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123052) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `enforce_vulnerability_attributes_rules`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/418784) in GitLab 16.3. +> - The scan result policy field `vulnerability_age` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123956) in GitLab 16.2. + +FLAG: +On self-managed GitLab, by default the `vulnerability_attributes` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `enforce_vulnerability_attributes_rules`. +On GitLab.com, this feature is available. This rule enforces the defined actions based on security scan findings. | Field | Type | Required | Possible values | Description | @@ -88,6 +112,8 @@ This rule enforces the defined actions based on security scan findings. | `vulnerabilities_allowed` | `integer` | true | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | | `severity_levels` | `array` of `string` | true | `info`, `unknown`, `low`, `medium`, `high`, `critical` | The severity levels for this rule to consider. | | `vulnerability_states` | `array` of `string` | true | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed`, `new_needs_triage`, `new_dismissed` | All vulnerabilities fall into two categories:<br><br>**Newly Detected Vulnerabilities** - the `newly_detected` policy option covers vulnerabilities identified in the merge request branch itself but that do not currently exist on the default branch. This policy option requires a pipeline to complete before the rule is evaluated so that it knows whether vulnerabilities are newly detected or not. Merge requests are blocked until the pipeline and necessary security scans are complete. The `newly_detected` option considers both of the following statuses:<br><br> • Detected<br> • Dismissed<br><br> The `new_needs_triage` option considers the status<br><br> • Detected<br><br> The `new_dismissed` option considers the status<br><br> • Dismissed<br><br>**Pre-Existing Vulnerabilities** - these policy options are evaluated immediately and do not require a pipeline complete as they consider only vulnerabilities previously detected in the default branch.<br><br> • `Detected` - the policy looks for vulnerabilities in the detected state.<br> • `Confirmed` - the policy looks for vulnerabilities in the confirmed state.<br> • `Dismissed` - the policy looks for vulnerabilities in the dismissed state.<br> • `Resolved` - the policy looks for vulnerabilities in the resolved state. | +| `vulnerability_attributes` | `object` | false | `{false_positive: boolean, fix_available: boolean}` | All vulnerability findings are considered by default. But filters can be applied for attributes to consider only vulnerability findings: <br><br> • With a fix available (`fix_available: true`)<br><br> • With no fix available (`fix_available: false`)<br> • That are false positive (`false_positive: true`)<br> • That are not false positive (`false_positive: false`)<br> • Or a combination of both. For example (`fix_available: true, false_positive: false`) | +| `vulnerability_age` | `object` | false | N/A | Filter pre-existing vulnerability findings by age. A vulnerability's age is calculated as the time since it was detected in the project. The criteria are `operator`, `value`, and `interval`.<br>- The `operator` criterion specifies if the age comparison used is older than (`greater_than`) or younger than (`less_than`).<br>- The `value` criterion specifies the numeric value representing the vulnerability's age.<br>- The `interval` criterion specifies the unit of measure of the vulnerability's age: `day`, `week`, `month`, or `year`.<br><br>Example: `operator: greater_than`, `value: 30`, `interval: day`. | ## `license_finding` rule type @@ -150,6 +176,9 @@ scan_result_policy: - critical vulnerability_states: - newly_detected + vulnerability_attributes: + false_positive: true + fix_available: true actions: - type: require_approval approvals_required: 1 @@ -169,12 +198,14 @@ scan_result_policy: - low - unknown vulnerability_states: - - newly_detected + - detected + vulnerability_age: + operator: greater_than + value: 30 + interval: day actions: - type: require_approval approvals_required: 1 - user_approvers: - - sam.white role_approvers: - owner ``` @@ -183,8 +214,8 @@ In this example: - Every MR that contains new `critical` vulnerabilities identified by container scanning requires one approval from `alberto.dare`. -- Every MR that contains more than one new `low` or `unknown` vulnerability identified by container - scanning requires one approval from `sam.white`. +- Every MR that contains more than one preexisting `low` or `unknown` vulnerability older than 30 days identified by + container scanning requires one approval from a project member with the Owner role. ## Example for Scan Result Policy editor diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index fecadaa737d..832ad100701 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -4,7 +4,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# SAST analyzers **(FREE)** +# SAST analyzers **(FREE ALL)** > [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. @@ -141,7 +141,7 @@ To preview the upcoming changes to the CI/CD configuration in GitLab 15.3 or ear template: 'Jobs/SAST.latest.gitlab-ci.yaml' ``` - - On a Self-Managed instance, download the template from GitLab.com: + - On a self-managed instance, download the template from GitLab.com: ```yaml include: diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index 385c5ffbae1..4ae8f1c4f8b 100644 --- a/doc/user/application_security/sast/customize_rulesets.md +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -4,12 +4,13 @@ group: Static Analysis 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 --- -# Customize rulesets **(ULTIMATE)** +# Customize rulesets **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for > passthrough chains. Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8. +> - [Added](https://gitlab.com/gitlab-org/security-products/analyzers/ruleset/-/merge_requests/18) support for specifying ambiguous passthrough refs in GitLab 16.2. You can customize the behavior of our SAST analyzers by [defining a ruleset configuration file](#create-the-configuration-file) in the repository being scanned. There are two kinds of customization: @@ -161,7 +162,7 @@ they're not explicitly stored in the configuration file. [[semgrep.passthrough]] type = "git" value = "$GITURL" - ref = "refs/heads/main" + ref = "main" ``` ### The `[[$analyzer.ruleset]]` section @@ -293,7 +294,7 @@ The amount of data generated by a single passthrough is limited to 1 MB. | `type` | All | One of `file`, `raw`, `git` or `url`. | | `target` | All | The target file to contain the data written by the passthrough evaluation. If empty, a random filename is used. | | `mode` | All | If `overwrite`, the `target` file is overwritten. If `append`, new content is appended to the `target` file. The `git` type only supports `overwrite`. (Default: `overwrite`) | -| `ref` | `type = "git"` | Contains the name of the branch or the SHA to pull. When using a branch name, specify it in the form `refs/heads/<branch>`, not `refs/remotes/<remote_name>/<branch>`. | +| `ref` | `type = "git"` | Contains the name of the branch, tag, or the SHA to pull | | `subdir` | `type = "git"` | Used to select a subdirectory of the Git repository as the configuration source. | | `value` | All | For the `file`, `url`, and `git` types, defines the location of the file or Git repository. For the `raw` type, contains the inline configuration. | | `validator` | All | Used to explicitly invoke validators (`xml`, `yaml`, `json`, `toml`) on the target file after the evaluation of a passthrough. | @@ -445,7 +446,7 @@ that's written to the `/sgrules` directory within the container. A Different passthrough types are demonstrated in this example: -- Two `git` passthroughs, the first pulling `refs/heads/test` from the +- Two `git` passthroughs, the first pulling `develop` branch from the `myrules` Git repository, and the second pulling revision `97f7686` from the `sast-rules` repository, and considering only files in the `go` subdirectory. @@ -470,7 +471,7 @@ Afterwards, Semgrep is invoked with the final configuration located under [[semgrep.passthrough]] type = "git" value = "https://gitlab.com/user/myrules.git" - ref = "refs/heads/test" + ref = "develop" [[semgrep.passthrough]] type = "git" diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index a9bc331ae7b..717608274e5 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -4,9 +4,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Static Application Security Testing (SAST) **(FREE)** - -> All open source (OSS) analyzers were moved from GitLab Ultimate to GitLab Free in GitLab 13.3. +# Static Application Security Testing (SAST) **(FREE ALL)** NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) @@ -27,31 +25,11 @@ For more details, see the [Summary of features per tier](#summary-of-features-pe  -The results are sorted by the priority of the vulnerability: - -<!-- vale gitlab.SubstitutionWarning = NO --> - -1. Critical -1. High -1. Medium -1. Low -1. Info -1. Unknown - -<!-- vale gitlab.SubstitutionWarning = YES --> - A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard does not show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard does not show SAST results. On failure, the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code). -## Use cases - -- Your code has a potentially dangerous attribute in a class, or unsafe code - that can lead to unintended code execution. -- Your application is vulnerable to cross-site scripting (XSS) attacks that can - be leveraged to unauthorized access to session data. - ## Requirements SAST runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. @@ -66,7 +44,7 @@ GitLab SAST analyzers don't support running on Windows or on any CPU architectur WARNING: If you use your own runners, make sure the Docker version installed -is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. +is **not** `19.03.0`. See [troubleshooting information](troubleshooting.md#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. ## Supported languages and frameworks @@ -120,8 +98,6 @@ and the [Maven wrapper](https://github.com/takari/maven-wrapper). However, SpotB ## Multi-project support -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4895) in GitLab 13.7. - GitLab SAST can scan repositories that contain multiple projects. The following analyzers have multi-project support: @@ -143,7 +119,7 @@ The following analyzers have multi-project support: Multi-project support in the Security Code Scan requires a Solution (`.sln`) file in the root of the repository. For details on the Solution format, see the Microsoft reference [Solution (`.sln`) file](https://learn.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). -## False positive detection **(ULTIMATE)** +## False positive detection **(ULTIMATE ALL)** > - Introduced for Ruby in GitLab 14.2. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378622) for Go in GitLab 15.8. @@ -158,7 +134,7 @@ False positive detection is available in a subset of the [supported languages](#  -## Advanced vulnerability tracking **(ULTIMATE)** +## Advanced vulnerability tracking **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5144) in GitLab 14.2. @@ -171,11 +147,12 @@ GitLab SAST uses an advanced vulnerability tracking algorithm to more accurately Advanced vulnerability tracking is available in a subset of the [supported languages](#supported-languages-and-frameworks) and [analyzers](analyzers.md): -- C, in the Semgrep-based analyzer only +- C, in the Semgrep-based and Flawfinder analyzers +- C++, in the Flawfinder analyzer only - C#, in the Semgrep-based analyzer only - Go, in the Semgrep-based analyzer only -- Java, in the Semgrep-based analyzer only -- JavaScript, in the Semgrep-based analyzer only +- Java, in the Semgrep-based and mobsf analyzers +- JavaScript, in the Semgrep-based and NodeJS-Scan analyzers - Python, in the Semgrep-based analyzer only - Ruby, in the Brakeman-based analyzer @@ -290,7 +267,7 @@ When downloading, you always receive the most recent SAST artifact available. You can enable and configure SAST by using the UI, either with the default settings or with customizations. The method you can use depends on your GitLab license tier. -#### Configure SAST with customizations **(ULTIMATE)** +#### Configure SAST with customizations **(ULTIMATE ALL)** > [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/410013) individual SAST analyzers configuration options from the UI in GitLab 16.2. @@ -316,8 +293,6 @@ Pipelines now include a SAST job. #### Configure SAST with default settings only -> [Introduced](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#security-configuration-page-for-all-users) in GitLab 13.9 - NOTE: The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal configuration file. If you have a complex GitLab configuration file it may not be parsed @@ -334,11 +309,7 @@ Pipelines now include a SAST job. ### Overriding SAST jobs -WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead. - -To override a job definition, (for example, change properties like `variables` or `dependencies`), +To override a job definition, (for example, change properties like `variables`, `dependencies`, or [`rules`](../../../ci/yaml/index.md#rules)), declare a job with the same name as the SAST job to override. Place this new job after the template inclusion and specify any additional keys under it. For example, this enables `FAIL_NEVER` for the `spotbugs` analyzer: @@ -580,8 +551,7 @@ Some analyzers can be customized with CI/CD variables. | `FAIL_NEVER` | SpotBugs | Set to `1` to ignore compilation failure. | | `SAST_GOSEC_CONFIG` | Gosec | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328301)** in GitLab 14.0 - use custom rulesets instead. Path to configuration for Gosec (optional). | | `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. | -| `SAST_DISABLE_BABEL` | NodeJsScan | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64025)** in GitLab 13.5 | -| `SAST_SEMGREP_METRICS` | Semgrep | Set to `"false"` to disable sending anonymized scan metrics to [r2c](https://semgrep.dev). Default: `true`. Introduced in GitLab 14.0 from the [confidential issue](../../project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab/-/issues/330565`. | +| `SAST_SEMGREP_METRICS` | Semgrep | Set to `"false"` to disable sending anonymized scan metrics to [r2c](https://semgrep.dev). Default: `true`. Introduced in GitLab 14.0. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/330565`. | | `SAST_SCANNER_ALLOWED_CLI_OPTS` | Semgrep | CLI options (arguments with value, or flags) that are passed to the underlying security scanner when running scan operation. Only a limited set of [options](#security-scanner-configuration) are accepted. Separate a CLI option and its value using either a blank space or equals (`=`) character. For example: `name1 value1` or `name1=value1`. Multiple options must be separated by blank spaces. For example: `name1 value1 name2 value2`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368565) in GitLab 15.3. | #### Security scanner configuration @@ -610,12 +580,6 @@ all [custom variables](../../../ci/variables/index.md#define-a-cicd-variable-in- to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. -NOTE: -In [GitLab 13.3 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/220540), -variables whose names started with the following prefixes are **not** propagated to either the -analyzer containers or SAST Docker container: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, -`OLDPWD`, `PATH`, `SHLVL`, `HOSTNAME`. - ### Experimental features You can receive early access to experimental features. Experimental features might be added, @@ -624,8 +588,11 @@ removed, or promoted to regular features at any time. Experimental features available are: - Enable scanning of iOS and Android apps using the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). -- Disable the following rules in the [Semgrep analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) that are known to cause a high rate of false positives: - - [`eslint.detect-object-injection`](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/6c4764567d9854f5e4a4a35dacf5a68def7fb4c1/rules/eslint.yml#L751-773) + +These features were previously experimental, but are now generally available: + +- Disable the [`eslint.detect-object-injection`](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/6c4764567d9854f5e4a4a35dacf5a68def7fb4c1/rules/eslint.yml#L751-773) in the [Semgrep analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) because it causes a high rate of false positives. + - This rule was [disabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/373920) in 15.10. #### Enable experimental features @@ -751,156 +718,3 @@ documentation for instructions. ## Running SAST in SELinux By default SAST analyzers are supported in GitLab instances hosted on SELinux. Adding a `before_script` in an [overridden SAST job](#overriding-sast-jobs) may not work as runners hosted on SELinux have restricted permissions. - -## Troubleshooting - -### Debug-level logging - -Debug-level logging can help when troubleshooting. For details, see -[debug-level logging](../index.md#debug-level-logging). - -### Pipeline errors related to changes in the GitLab-managed CI/CD template - -The [GitLab-managed SAST CI/CD template](#configure-sast-in-your-cicd-yaml) controls which [analyzer](analyzers.md) jobs run and how they're configured. While using the template, you might experience a job failure or other pipeline error. For example, you might: - -- See an error message like `'<your job>' needs 'spotbugs-sast' job, but 'spotbugs-sast' is not in any previous stage` when you view an affected pipeline. -- Experience another type of unexpected issue with your CI/CD pipeline configuration. - -If you're experiencing a job failure or seeing a SAST-related `yaml invalid` pipeline status, you can temporarily revert to an older version of the template so your pipelines keep working while you investigate the issue. To use an older version of the template, change the existing `include` statement in your CI/CD YAML file to refer to a specific template version, such as `v15.3.3-ee`: - -```yaml -include: - remote: 'https://gitlab.com/gitlab-org/gitlab/-/raw/v15.3.3-ee/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml' -``` - -If your GitLab instance has limited network connectivity, you can also download the file and host it elsewhere. - -We recommend that you only use this solution temporarily and that you return to [the standard template](#configure-sast-in-your-cicd-yaml) as soon as possible. - -### Errors in a specific analyzer job - -GitLab SAST [analyzers](analyzers.md) are released as container images. -If you're seeing a new error that doesn't appear to be related to [the GitLab-managed SAST CI/CD template](#configure-sast-in-your-cicd-yaml) or changes in your own project, you can try [pinning the affected analyzer to a specific older version](#pinning-to-minor-image-version). - -Each [analyzer project](analyzers.md#sast-analyzers) has a `CHANGELOG.md` file listing the changes made in each available version. - -### `exec /bin/sh: exec format error` message in job log - -GitLab SAST analyzers [only support](#requirements) running on the `amd64` CPU architecture. -This message indicates that the job is being run on a different architecture, such as `arm`. - -### `Error response from daemon: error processing tar file: docker-tar: relocation error` - -This error occurs when the Docker version that runs the SAST 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"). - -### Getting warning message `gl-sast-report.json: no matching files` - -For information on this, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). - -### Error: `sast is used for configuration only, and its script should not be executed` - -For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). - -### Limitation when using rules:exists - -The [SAST CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) -uses the `rules:exists` parameter. For performance reasons, a maximum number of matches are made -against the given glob pattern. If the number of matches exceeds the maximum, the `rules:exists` -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/index.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> -``` - -### SpotBugs Error: `Project couldn't be built` - -If your job is failing at the build step with the message "Project couldn't be built", it's most likely because your job is asking SpotBugs to build with a tool that isn't part of its default tools. For a list of the SpotBugs default tools, see [SpotBugs' asdf dependencies](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/raw/master/config/.tool-versions). - -The solution is to use [pre-compilation](#pre-compilation). Pre-compilation ensures the images required by SpotBugs are available in the job's container. - -### Flawfinder encoding error - -This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, convert all source code in your project to UTF-8 character encoding. This can be done with [`cvt2utf`](https://github.com/x1angli/cvt2utf) or [`iconv`](https://www.gnu.org/software/libiconv/documentation/libiconv-1.13/iconv.1.html) either over the entire project or per job using the [`before_script`](../../../ci/yaml/index.md#before_script) feature. - -### Semgrep slowness, unexpected results, or other errors - -If Semgrep is slow, reports too many false positives or false negatives, crashes, fails, or is otherwise broken, see the Semgrep docs for [troubleshooting GitLab SAST](https://semgrep.dev/docs/troubleshooting/semgrep-ci/#troubleshooting-gitlab-sast). - -### SAST job fails with message `strconv.ParseUint: parsing "0.0": invalid syntax` - -Invoking Docker-in-Docker is the likely cause of this error. Docker-in-Docker is: - -- Disabled by default in GitLab 13.0 and later. -- Unsupported from GitLab 13.4 and later. - -Several workarounds are available. From GitLab version 13.0 and later, you must not use -Docker-in-Docker. - -#### Workaround 1: Pin analyzer versions (GitLab 12.1 and earlier) - -Set the following variables for the SAST job. This pins the analyzer versions to the last known -working version, allowing SAST with Docker-in-Docker to complete as it did previously: - -```yaml -sast: - variables: - SAST_DEFAULT_ANALYZERS: "" - SAST_ANALYZER_IMAGES: "registry.gitlab.com/gitlab-org/security-products/analyzers/bandit:2.9.6, registry.gitlab.com/gitlab-org/security-products/analyzers/brakeman:2.11.0, registry.gitlab.com/gitlab-org/security-products/analyzers/eslint:2.10.0, registry.gitlab.com/gitlab-org/security-products/analyzers/flawfinder:2.11.1, registry.gitlab.com/gitlab-org/security-products/analyzers/gosec:2.14.0, registry.gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan:2.11.0, registry.gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit:2.9.1, registry.gitlab.com/gitlab-org/security-products/analyzers/pmd-apex:2.9.0, registry.gitlab.com/gitlab-org/security-products/analyzers/secrets:3.12.0, registry.gitlab.com/gitlab-org/security-products/analyzers/security-code-scan:2.13.0, registry.gitlab.com/gitlab-org/security-products/analyzers/sobelow:2.8.0, registry.gitlab.com/gitlab-org/security-products/analyzers/spotbugs:2.13.6, registry.gitlab.com/gitlab-org/security-products/analyzers/tslint:2.4.0" -``` - -Remove any analyzers you don't need from the `SAST_ANALYZER_IMAGES` list. Keep -`SAST_DEFAULT_ANALYZERS` set to an empty string `""`. - -#### Workaround 2: Disable Docker-in-Docker for SAST and Dependency Scanning (GitLab 12.3 and later) - -Disable Docker-in-Docker for SAST. Individual `<analyzer-name>-sast` jobs are created for each -analyzer that runs in your CI/CD pipeline. - -```yaml -include: - - template: SAST.gitlab-ci.yml - -variables: - SAST_DISABLE_DIND: "true" -``` - -#### Workaround 3: Upgrade to GitLab 13.x and use the defaults - -From GitLab 13.0, SAST defaults to not using Docker-in-Docker. In GitLab 13.4 and later, SAST using -Docker-in-Docker is [no longer supported](https://gitlab.com/gitlab-org/gitlab/-/issues/220540). -If you have this problem on GitLab 13.x and later, you have customized your SAST job to -use Docker-in-Docker. To resolve this, comment out any customizations you've made to -your SAST CI job definition and [follow the documentation](index.md#configuration) -to reconfigure, using the new and improved job definition default values. - -```yaml -include: - - template: Security/SAST.gitlab-ci.yml -``` - -### MobSF job fails with error message `Reading from Info.plist` - -This error happens when `Info.plist` file is missing a `CFBundleIdentifier` key and string value. diff --git a/doc/user/application_security/sast/troubleshooting.md b/doc/user/application_security/sast/troubleshooting.md new file mode 100644 index 00000000000..34a2a3d01af --- /dev/null +++ b/doc/user/application_security/sast/troubleshooting.md @@ -0,0 +1,102 @@ +--- +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting SAST **(FREE ALL)** + +## Debug-level logging + +Debug-level logging can help when troubleshooting. For details, see +[debug-level logging](../index.md#debug-level-logging). + +## Pipeline errors related to changes in the GitLab-managed CI/CD template + +The [GitLab-managed SAST CI/CD template](index.md#configure-sast-in-your-cicd-yaml) controls which [analyzer](analyzers.md) jobs run and how they're configured. While using the template, you might experience a job failure or other pipeline error. For example, you might: + +- See an error message like `'<your job>' needs 'spotbugs-sast' job, but 'spotbugs-sast' is not in any previous stage` when you view an affected pipeline. +- Experience another type of unexpected issue with your CI/CD pipeline configuration. + +If you're experiencing a job failure or seeing a SAST-related `yaml invalid` pipeline status, you can temporarily revert to an older version of the template so your pipelines keep working while you investigate the issue. To use an older version of the template, change the existing `include` statement in your CI/CD YAML file to refer to a specific template version, such as `v15.3.3-ee`: + +```yaml +include: + remote: 'https://gitlab.com/gitlab-org/gitlab/-/raw/v15.3.3-ee/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml' +``` + +If your GitLab instance has limited network connectivity, you can also download the file and host it elsewhere. + +We recommend that you only use this solution temporarily and that you return to [the standard template](index.md#configure-sast-in-your-cicd-yaml) as soon as possible. + +## Errors in a specific analyzer job + +GitLab SAST [analyzers](analyzers.md) are released as container images. +If you're seeing a new error that doesn't appear to be related to [the GitLab-managed SAST CI/CD template](index.md#configure-sast-in-your-cicd-yaml) or changes in your own project, you can try [pinning the affected analyzer to a specific older version](index.md#pinning-to-minor-image-version). + +Each [analyzer project](analyzers.md#sast-analyzers) has a `CHANGELOG.md` file listing the changes made in each available version. + +## `exec /bin/sh: exec format error` message in job log + +GitLab SAST analyzers [only support](index.md#requirements) running on the `amd64` CPU architecture. +This message indicates that the job is being run on a different architecture, such as `arm`. + +## `Error response from daemon: error processing tar file: docker-tar: relocation error` + +This error occurs when the Docker version that runs the SAST 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"). + +## Getting warning message `gl-sast-report.json: no matching files` + +For information on this, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). + +## Error: `sast is used for configuration only, and its script should not be executed` + +For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). + +## Limitation when using rules:exists + +The [SAST CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) +uses the `rules:exists` parameter. For performance reasons, a maximum number of matches are made +against the given glob pattern. If the number of matches exceeds the maximum, the `rules:exists` +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/index.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> +``` + +## SpotBugs Error: `Project couldn't be built` + +If your job is failing at the build step with the message "Project couldn't be built", it's most likely because your job is asking SpotBugs to build with a tool that isn't part of its default tools. For a list of the SpotBugs default tools, see [SpotBugs' asdf dependencies](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/raw/master/config/.tool-versions). + +The solution is to use [pre-compilation](index.md#pre-compilation). Pre-compilation ensures the images required by SpotBugs are available in the job's container. + +## Flawfinder encoding error + +This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, convert all source code in your project to UTF-8 character encoding. This can be done with [`cvt2utf`](https://github.com/x1angli/cvt2utf) or [`iconv`](https://www.gnu.org/software/libiconv/documentation/libiconv-1.13/iconv.1.html) either over the entire project or per job using the [`before_script`](../../../ci/yaml/index.md#before_script) feature. + +## Semgrep slowness, unexpected results, or other errors + +If Semgrep is slow, reports too many false positives or false negatives, crashes, fails, or is otherwise broken, see the Semgrep docs for [troubleshooting GitLab SAST](https://semgrep.dev/docs/troubleshooting/semgrep-ci/#troubleshooting-gitlab-sast). diff --git a/doc/user/application_security/secret_detection/automatic_response.md b/doc/user/application_security/secret_detection/automatic_response.md index 66ed2f10a3c..1a5ab913b29 100644 --- a/doc/user/application_security/secret_detection/automatic_response.md +++ b/doc/user/application_security/secret_detection/automatic_response.md @@ -4,7 +4,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Automatic response to leaked secrets **(ULTIMATE)** +# Automatic response to leaked secrets **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) in GitLab 13.6. @@ -23,7 +23,7 @@ GitLab supports automatic response for the following types of secrets: | GitLab [Personal access tokens](../../profile/personal_access_tokens.md) | Immediately revoke token, send email to owner | ✅ | ✅ [15.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/371658) | | Amazon Web Services (AWS) [IAM access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) | Notify AWS | ✅ | ⚙ | | Google Cloud [service account keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys), [API keys](https://cloud.google.com/docs/authentication/api-keys), and [OAuth client secrets](https://support.google.com/cloud/answer/6158849#rotate-client-secret) | Notify Google Cloud | ✅ | ⚙ | -| Postman [API keys](https://learning.postman.com/docs/developer/postman-api/authentication/) | Notify Postman; Postman emails the key owner | ✅ | ⚙ | +| Postman [API keys](https://learning.postman.com/docs/developer/postman-api/authentication/) | Notify Postman; Postman [notifies the key owner](https://learning.postman.com/docs/administration/token-scanner/#protecting-postman-api-keys-in-gitlab) | ✅ | ⚙ | **Component legend** diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index ea2a66c7cc7..10e8356de16 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -4,7 +4,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Secret Detection **(FREE)** +# Secret Detection **(FREE ALL)** > - In GitLab 13.1, Secret Detection was split from the [SAST configuration](../sast/index.md#configuration) > into its own CI/CD template. If you're using GitLab 13.0 or earlier and SAST is enabled, then @@ -137,7 +137,7 @@ shared runners on GitLab.com, this is enabled by default. - Windows Runners are not supported. - CPU architectures other than amd64 are not supported. - If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See - [troubleshooting information](../sast#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) + [troubleshooting information](../sast/troubleshooting.md#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. - GitLab CI/CD configuration (`.gitlab-ci.yml`) must include the `test` stage. @@ -335,7 +335,7 @@ pipeline. To enable full history Secret Detection, set the variable `SECRET_DETECTION_HISTORIC_SCAN` to `true` in your `.gitlab-ci.yml` file. -## Custom rulesets **(ULTIMATE)** +## Custom rulesets **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for passthrough chains. @@ -350,6 +350,7 @@ The following customization options can be used separately, or in combination: - [Disable predefined rules](#disable-predefined-analyzer-rules). - [Override predefined rules](#override-predefined-analyzer-rules). - [Synthesize a custom configuration](#synthesize-a-custom-configuration). +- [Specify a remote configuration file](#specify-a-remote-configuration-file). ### Disable predefined analyzer rules @@ -496,7 +497,7 @@ path = "/gitleaks.toml" ] ``` -## Specify a remote configuration file +### Specify a remote configuration file Projects can be configured with a [CI/CD variable](../../../ci/variables/index.md) in order to specify a ruleset configuration outside of the current repository. diff --git a/doc/user/application_security/secret_detection/post_processing.md b/doc/user/application_security/secret_detection/post_processing.md deleted file mode 100644 index 3a6cf7f7e37..00000000000 --- a/doc/user/application_security/secret_detection/post_processing.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'automatic_response.md' -remove_date: '2023-08-08' ---- - -This document was moved to [another location](automatic_response.md). - -<!-- This redirect file can be deleted after 2023-08-08. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/application_security/secure_your_application.md b/doc/user/application_security/secure_your_application.md index 8dd1168a0d9..0b028f6936d 100644 --- a/doc/user/application_security/secure_your_application.md +++ b/doc/user/application_security/secure_your_application.md @@ -4,7 +4,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Secure your application **(FREE)** +# Secure your application **(FREE ALL)** GitLab can check your applications for security vulnerabilities. diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index e28c06236aa..b6d95e53227 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -5,7 +5,7 @@ group: Threat Insights 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 --- -# GitLab Security Dashboards and Security Center **(ULTIMATE)** +# GitLab Security Dashboards and Security Center **(ULTIMATE ALL)** You can use Security Dashboards to view trends about vulnerabilities detected by [security scanners](../index.md#application-coverage). diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index df103976901..5c2dbd8d728 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Secure and Govern glossary **(FREE)** +# Secure and Govern glossary **(FREE ALL)** The glossary of terms aims to achieve the following: diff --git a/doc/user/application_security/vulnerabilities/img/explain_this_vulnerability_beta_v16_3.png b/doc/user/application_security/vulnerabilities/img/explain_this_vulnerability_beta_v16_3.png Binary files differnew file mode 100644 index 00000000000..55266babbf2 --- /dev/null +++ b/doc/user/application_security/vulnerabilities/img/explain_this_vulnerability_beta_v16_3.png diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 1950c620627..fa0027754ad 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -4,7 +4,7 @@ group: Threat Insights 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 --- -# Vulnerability Page **(ULTIMATE)** +# Vulnerability Page **(ULTIMATE ALL)** Each vulnerability in a project has a vulnerability page containing details of the vulnerability, including: @@ -24,6 +24,59 @@ change its status to **Resolved**. This ensures that if it is accidentally reint merge, it is reported again as a new record. To change the status of multiple vulnerabilities, use the Vulnerability Report's [Activity filter](../vulnerability_report/index.md#activity-filter). +## Explaining a vulnerability (Beta) **(ULTIMATE SAAS)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10368) in GitLab 16.0 as an [Experiment](../../../policy/experiment-beta-support.md#experiment) on GitLab.com. +> - Promoted to [Beta](../../../policy/experiment-beta-support.md#beta) status in 16.2. + +GitLab can help you with a vulnerability by using a large language model to: + +- Summarize the vulnerability. +- Help developers and security analysts to understand the vulnerability, how it could be exploited, and how to fix it. +- Provide a suggested mitigation. + +### Explain a vulnerability + +Use the explain this vulnerability feature to better understand a vulnerability and its possible +mitigation. + +Prerequisites: + +- You must have the GitLab Ultimate subscription tier. +- You must be a member of the project. +- The vulnerability must be a SAST finding. + +Learn more about [how to enable all AI features](../../ai_features.md#enable-aiml-features). + +To explain the vulnerability: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Security and Compliance > Vulnerability report**. +1. In the **Tool** dropdown list, select **SAST**. +1. Select the SAST vulnerability you want explained. +1. At the bottom of the vulnerability's page, select **Try it out**. + +The response is shown on the right side of the page. + + + +On GitLab.com this feature is available. By default, it is powered by Google's `text-bison-001` +model. In the event of degraded performance with that model, the feature instead uses Anthropic's +`claude` model. + +We cannot guarantee that the large language model produces results that are correct. Use the +explanation with caution. + +### Data shared with third-party AI APIs + +The following data is shared with third-party AI APIs: + +- Vulnerability title (which might contain the filename, depending on which scanner is used). +- Vulnerability identifiers. +- Code block, but only if the "Send code with prompt" checkbox is selected (single and multi-line as instructed by the vulnerability + record). +- Filename. + ## Vulnerability status values A vulnerability's status can be: diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index 9553d15bbe9..31946d414a2 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -5,7 +5,7 @@ group: Threat Insights 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 --- -# Vulnerability severity levels **(ULTIMATE)** +# Vulnerability severity levels **(ULTIMATE ALL)** 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 @@ -22,7 +22,7 @@ GitLab analyzers make an effort to fit the severity descriptions below, but they ## Critical severity -Vulnerabilities identified at the Critical Severity level should be investigated immediately. Vulnerabilities at this level assume exploitation of the flaw could lead to full system or data compromise. Examples of critical severity flaws are Command/Code Injection and SQL Injection. Typically these flaws are rated with CVSS 3.1 between 9.0-10.0. +Vulnerabilities identified at the Critical Severity level should be investigated immediately. Vulnerabilities at this level assume exploitation of the flaw could lead to full system or data compromise. Examples of critical severity flaws are Command/Code Injection and SQL Injection. Typically these flaws are rated with CVSS 3.1 between 9.0-10.0. ## High severity diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 78f8bbdb0c3..46ce3173ee7 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -5,7 +5,7 @@ group: Threat Insights 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 --- -# Vulnerability Report **(ULTIMATE)** +# Vulnerability Report **(ULTIMATE ALL)** The Vulnerability Report provides information about vulnerabilities from scans of the default branch. It contains cumulative results of all successful jobs, regardless of whether the pipeline was successful. The scan results from a @@ -48,6 +48,9 @@ At the project level, the Vulnerability Report also contains: - The number of failures that occurred in the most recent pipeline. Select the failure notification to view the **Failed jobs** tab of the pipeline's page. +When vulnerabilities originate from a multi-project pipeline setup, +this page displays the vulnerabilities that originate from the selected project. + ### View the project-level vulnerability report To view the project-level vulnerability report: diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md index a53e0a8970b..7a414e9a4ae 100644 --- a/doc/user/application_security/vulnerability_report/pipeline.md +++ b/doc/user/application_security/vulnerability_report/pipeline.md @@ -29,6 +29,8 @@ the [Vulnerability Report](index.md), which contains cumulative results of all s [security widget](../index.md#view-security-scan-information-in-merge-requests), which combines the branch results with cumulative results. +The pipeline vulnerability report only displays after the pipeline is complete. If the pipeline has a [blocking manual job](../../../ci/jobs/job_control.md#types-of-manual-jobs), the pipeline waits for the manual job and the vulnerabilities cannot be displayed if the blocking manual job did not run. + Before GitLab displays results, the vulnerability findings in all pipeline reports are [deduplicated](#deduplication-process). ## Scan details diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index d2041083d36..b481c0458aa 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# AsciiDoc **(FREE)** +# AsciiDoc **(FREE ALL)** GitLab uses the [Asciidoctor](https://asciidoctor.org) gem to convert AsciiDoc content to HTML5. Consult the [Asciidoctor User Manual](https://asciidoctor.org/docs/user-manual/) for a complete Asciidoctor reference. diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index aaba0225653..a7c58b4d2a8 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.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/product/ux/technical-writing/#assignments --- -# Emoji reactions **(FREE)** +# Emoji reactions **(FREE ALL)** > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409884) from "award emoji" to "emoji reactions" in GitLab 16.0. > - Reacting with emoji on work items (such as tasks, objectives, and key results) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393599) in GitLab 16.0. diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index a0b42101dd5..260263632c5 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Using GitLab CI/CD with a Kubernetes cluster **(FREE)** +# Using GitLab CI/CD with a Kubernetes cluster **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1. > - The pre-configured variable `$KUBECONFIG` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. @@ -196,7 +196,7 @@ To configure your client, do one of the following: - Place the certificates in an appropriate location in the job container by updating the container image or mounting via the runner. - Not recommended. Configure the Kubernetes client with `--insecure-skip-tls-verify=true`. -## Restrict project and group access by using impersonation **(PREMIUM)** +## Restrict project and group access by using impersonation **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/357934) in GitLab 15.5 to add impersonation support for environment tiers. @@ -300,7 +300,7 @@ The identity can be specified with the following keys: See the [official Kubernetes documentation for details](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation). -## Restrict project and group access to specific environments **(FREE)** +## Restrict project and group access to specific environments **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343885) in GitLab 15.7. diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index aff78ed477b..d79d32a1234 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Using GitOps with a Kubernetes cluster **(FREE)** +# Using GitOps with a Kubernetes cluster **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. @@ -78,6 +78,7 @@ For additional repository structure recommendations, see the [Flux documentation > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/392852) in GitLab 16.1 with a [flag](../../../administration/feature_flags.md) named `notify_kas_on_git_push`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126527) in GitLab 16.2. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/410429) in GitLab 16.3. Usually, the Flux source controller reconciles Git repositories at configured intervals. This can cause delays between a `git push` and the reconciliation of the cluster state, and results in diff --git a/doc/user/clusters/agent/gitops/agent.md b/doc/user/clusters/agent/gitops/agent.md index 07ed2b3a691..a4e83916acb 100644 --- a/doc/user/clusters/agent/gitops/agent.md +++ b/doc/user/clusters/agent/gitops/agent.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Using GitOps with the agent for Kubernetes (deprecated) **(FREE)** +# Using GitOps with the agent for Kubernetes (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. diff --git a/doc/user/clusters/agent/gitops/example_repository_structure.md b/doc/user/clusters/agent/gitops/example_repository_structure.md index a5bc3b153fe..02eea3300af 100644 --- a/doc/user/clusters/agent/gitops/example_repository_structure.md +++ b/doc/user/clusters/agent/gitops/example_repository_structure.md @@ -1,78 +1,179 @@ --- stage: Deploy group: Environments -info: An example of how to structure a repository for GitOps deployments +info: A tutorial for deploying a GitLab repository using Flux --- -# Example GitOps repository structure **(FREE)** +# Tutorial: Deploy a Git repository using Flux **(FREE ALL)** -This page describes an example structure for a project that builds and deploys an application -to a Kubernetes cluster with [GitOps](https://about.gitlab.com/topics/gitops) and the -[GitLab agent for Kubernetes](../../agent/gitops.md). +In this tutorial, you'll create a GitLab project that builds and deploys an application +to a Kubernetes cluster using Flux. You'll set up a sample manifest project, configure it to +push manifests to a deployment branch, and configure Flux to sync the deployment branch. With this +setup, you can run additional steps in GitLab pipelines before Flux picks up the changes +from the repository. + +This tutorial deploys an application from a public project. If you want to add a non-public project, you should create a [project deploy token](../../../project/deploy_tokens/index.md). + +To set up a repository for GitOps deployments: + +1. [Create the Kubernetes manifest repository](#create-the-kubernetes-manifest-repository) +1. [Create a deployment branch](#create-a-deployment-branch) +1. [Configure GitLab CI/CD to push to your branch](#configure-gitlab-cicd-to-push-to-your-branch) +1. [Configure Flux to sync your manifests](#configure-flux-to-sync-your-manifests) +1. [Verify your configuration](#verify-your-configuration) + +Prerequisites: + +- You have a Flux repository connected to a Kubernetes cluster. + If you're starting from scratch, see [Set up Flux for GitOps](flux_tutorial.md). -You can find an example project that uses this structure -[in this GitLab repository](https://gitlab.com/tigerwnz/minimal-gitops-app). You can use the example project -as a starting point to create your own deployment project. +## Create the Kubernetes manifest repository -## Deployment workflow +First, create a repository for your Kubernetes manifests: -The default branch is the single source of truth for your application and the -Kubernetes manifests that deploy it. To be reflected in a Kubernetes cluster, -a code or configuration change must exist in the default branch. +1. In GitLab, create a new repository called `web-app-manifests`. +1. In `web-app-manifests`, add a file named `src/nginx-deployment.yaml` with the following contents: -A GitLab agent for Kubernetes is installed in every Kubernetes cluster. The agent -is configured to sync manifests from a corresponding branch in the repository. -These branches represent the state of each cluster, and contain only commits that -exist in the default branch. - -Changes are deployed by merging the default branch into the branch of a cluster. -The agent that watches the branch picks up the change and syncs it to the cluster. - -For the actual deployment, the example project uses the GitLab agent for Kubernetes, -but you can also use other GitOps tools. - -### Review apps - -Ephemeral environments such as [review apps](../../../../ci/review_apps/index.md) -are deployed differently. Their configuration does not exist on the default branch, -and the changes are not meant to be deployed to a permanent environment. Review app -manifests are generated and deployed in a merge request feature branch, which is removed -when the MR is merged. - -## Example deployment - -The example project deploys to two permanent environments, staging and production, -which each have a dedicated Kubernetes cluster. A third cluster is used for ephemeral -review apps. - -Each cluster has a corresponding branch that represents the current state of the cluster: -`_gitlab/agents/staging`, `_gitlab/agents/production` and `_gitlab/agents/review`. Each branch is -[protected](../../../../user/project/protected_branches.md) and -a [project access token](../../../../user/project/settings/project_access_tokens.md) -is created for each branch with a configuration that allows only the corresponding token to push to the branch. -This ensures that environment branches are updated only through the configured process. - -Deployment branches are updated by CI/CD jobs. The access token that allows pushing to each -branch is configured as a [CI/CD variable](../../../../ci/variables/index.md). These variables -are protected, and only available to pipelines running on a protected branch. -The CI/CD job merges the default branch `main` into the deployment branch, and pushes -the deployment branch back to the repository using the provided token. To preserve the -commit history between both branches, the CI/CD job uses a fast-forward merge. - -Each cluster has an agent for Kubernetes, and each agent is configured to -sync manifests from the branch corresponding to its cluster. -In your own project, you can different GitOps tool like Flux, or use the same configuration to deploy -to virtual machines with GitLab CI/CD. - -### Application changes - -The example project follows this process to deploy an application change: - -1. A new feature branch is created with the desired changes. The pipeline builds an image, - runs the test suite, and deploy the changes to a review app in the `review` cluster. -1. The feature branch is merged to `main` and the review app is removed. -1. Manifests are updated on `main` (either directly or via merge request) to point to an updated - version of the deployed image. The pipeline automatically merges `main` into the `_gitlab/agents/staging` - branch, which updates the `staging` cluster. -1. The `production` job is triggered manually, and merges `main` into the `_gitlab/agents/production` branch, - deploying to the `production` cluster. + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: nginx + spec: + replicas: 1 + template: + spec: + containers: + - name: nginx + image: nginx:1.14.2 + ports: + - containerPort: 80 + ``` + +1. In `web-app-manifests`, add a file named `src/kustomization.yaml` with the following contents: + + ```yaml + apiVersion: kustomize.config.k8s.io/v1beta1 + kind: Kustomization + resources: + - nginx-deployment.yaml + commonLabels: + app: flux-branches-tutorial + ``` + +## Create a deployment branch + +Next, create a branch to reflect the current state of your cluster. + +In this workflow, the default branch is the single source of truth for your application. +To be reflected in a Kubernetes cluster, a code or configuration change must exist in the default branch. +In a later step, you'll configure CI/CD to merge changes from the default branch into the deployment branch. + +To create a deployment branch: + +1. In `web-app-manifests`, create a branch named `_gitlab/deploy/example` from the default branch. The branch name in this example is chosen to + differentiate the deployment branch from feature branches, but this is not required. You can name the deployment branch whatever you like. +1. Create a [project](../../../../user/project/settings/project_access_tokens.md), + [group](../../../../user/group/settings/group_access_tokens.md) or + [personal access token](../../../../user/profile/personal_access_tokens.md) with the `write_repository` scope. +1. Create a [CI/CD variable](../../../../ci/variables/index.md) with a token value named `DEPLOYMENT_TOKEN`. + Remember to [mask](../../../../ci/variables/index.md#mask-a-cicd-variable) the value so that it won't show in + job logs. +1. Add a rule to [protect](../../../../user/project/protected_branches.md) + your deployment branch with the following values: + + - Allowed to merge: No one. + - Allowed to push and merge: Select the token you created in the previous step, or your user if you created + a personal access token. + - Allowed to force push: Turn off the toggle. + - Require approval from code owners: Turn off the toggle. + +This configuration ensures that only the corresponding token can push to the branch. + +You've successfully created a repository with a protected deployment branch! + +## Configure GitLab CI/CD to push to your branch + +Next, you'll configure CI/CD to merge changes from the default branch to your deployment branch. + +In the root of `web-app-manifests`, create and push a [`.gitlab-ci.yml`](../../../../ci/yaml/gitlab_ci_yaml.md) file with the following contents: + + ```yaml + deploy: + stage: deploy + environment: production + variables: + DEPLOYMENT_BRANCH: _gitlab/deploy/example + script: + - | + git config user.name "Deploy Example Bot" + git config user.email "test@example.com" + git fetch origin $DEPLOYMENT_BRANCH + git checkout $DEPLOYMENT_BRANCH + git merge $CI_COMMIT_SHA --ff-only + git push https://deploy:$DEPLOYMENT_TOKEN@$CI_SERVER_HOST/$CI_PROJECT_PATH.git HEAD:$DEPLOYMENT_BRANCH + resource_group: $CI_ENVIRONMENT_SLUG + ``` + +This creates a CI/CD pipeline with a single `deploy` job that: + +1. Checks out your deployment branch. +1. Merges new changes from the default branch into the deployment branch. +1. Pushes the changes to your repository with the configured token. + +## Configure Flux to sync your manifests + +Next, configure your Flux repository to sync the deployment branch in by the `web-app-manifests` repository. + +To configure, create a [`GitRepository`](https://fluxcd.io/flux/components/source/gitrepositories/) resource: + +1. In your local clone of your Flux repository, add a file named `clusters/my-cluster/web-app-manifests-source.yaml` + with the following contents: + + ```yaml + apiVersion: source.toolkit.fluxcd.io/v1 + kind: GitRepository + metadata: + name: web-app-manifests + namespace: flux-system + spec: + interval: 5m0s + url: https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests-branches + ref: + branch: _gitlab/deploy/example + ``` + + You will need to substitute the `url` with the URL of your `web-app-manifests` project. + +1. In your local clone of your Flux repository, add a file named `clusters/my-cluster/web-app-manifests-kustomization.yaml` + with the following contents: + + ```yaml + apiVersion: kustomize.toolkit.fluxcd.io/v1 + kind: Kustomization + metadata: + name: nginx-source-kustomization + namespace: flux-system + spec: + interval: 1m0s + path: ./src + prune: true + sourceRef: + kind: GitRepository + name: web-app-manifests + targetNamespace: default + ``` + + This file adds a [Kustomization](https://fluxcd.io/flux/components/kustomize/kustomization/) resource that tells Flux to sync the manifests in the artifact fetched from the registry. + +1. Commit the new files and push. + +## Verify your configuration + +After the pipeline completes, you should see a newly created `nginx` pod in your cluster. + +If you want to see the deployment sync again, try updating the number of replicas in the +`src/nginx-deployment.yaml` file and push to the default branch. If all is working well, the change +will sync to the cluster when the pipeline has finished. + +Congratulations! You successfully configured a project to deploy an application and synchronize your changes! diff --git a/doc/user/clusters/agent/gitops/flux_oci_tutorial.md b/doc/user/clusters/agent/gitops/flux_oci_tutorial.md new file mode 100644 index 00000000000..b970c818a72 --- /dev/null +++ b/doc/user/clusters/agent/gitops/flux_oci_tutorial.md @@ -0,0 +1,154 @@ +--- +stage: Deploy +group: Environments +info: A tutorial for deploying an OCI artifact using Flux +--- + +# Tutorial: Deploy an OCI artifact using Flux **(FREE ALL)** + +This tutorial teaches you how to package your Kubernetes manifests into an [OCI](https://opencontainers.org/) +artifact and deploy them to your cluster using Flux. You'll set up a sample manifest project, configure it to +store manifests as an artifact in the project's Container Registry, and configure Flux to sync the artifact. With this +setup, you can run additional steps in GitLab pipelines before Flux picks up the changes +from the OCI image. + +This tutorial deploys an application from a public project. If you want to add a non-public project, you should create a [project deploy token](../../../project/deploy_tokens/index.md). + +To deploy an OCI artifact using Flux: + +1. [Create the Kubernetes manifest repository](#create-the-kubernetes-manifest-repository) +1. [Configure the manifest repository to create an OCI artifact](#configure-the-manifest-repository-to-create-an-oci-artifact) +1. [Configure Flux to sync your artifact](#configure-flux-to-sync-your-artifact) +1. [Verify your configuration](#verify-your-configuration) + +Prerequisites: + +- You have a Flux repository connected to a Kubernetes cluster. + If you're starting from scratch, see [Set up Flux for GitOps](flux_tutorial.md). + +## Create the Kubernetes manifest repository + +First, create a repository for your Kubernetes manifests: + +1. In GitLab, create a new repository called `web-app-manifests`. +1. In `web-app-manifests`, add a file named `src/nginx-deployment.yaml` with the following contents: + + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: nginx + spec: + replicas: 1 + template: + spec: + containers: + - name: nginx + image: nginx:1.14.2 + ports: + - containerPort: 80 + ``` + +1. In `web-app-manifests`, add a file named `src/kustomization.yaml` with the following contents: + + ```yaml + apiVersion: kustomize.config.k8s.io/v1beta1 + kind: Kustomization + resources: + - nginx-deployment.yaml + commonLabels: + app: flux-oci-tutorial + ``` + +## Configure the manifest repository to create an OCI artifact + +Next, configure [GitLab CI/CD](../../../../ci/index.md) to package your manifests into an OCI artifact, +and push the artifact to the [GitLab Container Registry](../../../packages/container_registry/index.md): + +1. In the root of `web-app-manifests`, create and push a [`.gitlab-ci.yml`](../../../../ci/yaml/gitlab_ci_yaml.md) file with the following contents: + + ```yaml + package: + stage: deploy + image: + name: fluxcd/flux-cli:v2.0.0-rc.1 + entrypoint: [""] + script: + - mkdir -p manifests + - kubectl kustomize ./src --output ./manifests + - | + flux push artifact oci://$CI_REGISTRY_IMAGE:latest \ + --path="./manifests" \ + --source="$CI_REPOSITORY_URL" \ + --revision="$CI_COMMIT_SHORT_SHA" \ + --creds="$CI_REGISTRY_USER:$CI_REGISTRY_PASSWORD" \ + --annotations="org.opencontainers.image.url=$CI_PROJECT_URL" \ + --annotations="org.opencontainers.image.title=$CI_PROJECT_NAME" \ + --annotations="com.gitlab.job.id=$CI_JOB_ID" \ + --annotations="com.gitlab.job.url=$CI_JOB_URL" + ``` + + When the file is pushed to GitLab, a CI/CD pipeline with a single `package` job is created. This job: + + - Uses `kustomization.yaml` to render your final Kubernetes manifests. + - Packages your manifests into an OCI artifact. + - Pushes the OCI artifact to the Container Registry. + + After the pipeline has completed, you can check your OCI artifact with the Container Registry UI. + +## Configure Flux to sync your artifact + +Next, configure your Flux repository to sync the artifact produced by the `web-app-manifests` repository. + +To configure, create an [`OCIRepository`](https://fluxcd.io/flux/components/source/ocirepositories/) resource: + +1. In your local clone of your Flux repository, add a file named `clusters/my-cluster/web-app-manifests-source.yaml` + with the following contents: + + ```yaml + apiVersion: source.toolkit.fluxcd.io/v1 + kind: OCIRepository + metadata: + name: web-app-manifests + namespace: flux-system + spec: + interval: 1m0s + url: oci://registry.gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests-oci + ref: + tag: latest + ``` + + You will need to substitute the `url` with the URL of your `web-app-manifests` project's container registry. + +1. In your local clone of your Flux repository, add a file named `clusters/my-cluster/web-app-manifests-kustomization.yaml` + with the following contents: + + ```yaml + apiVersion: kustomize.toolkit.fluxcd.io/v1 + kind: Kustomization + metadata: + name: nginx-source-kustomization + namespace: flux-system + spec: + interval: 1m0s + path: ./ + prune: true + sourceRef: + kind: OCIRepository + name: web-app-manifests + targetNamespace: default + ``` + + This file adds a [Kustomization](https://fluxcd.io/flux/components/kustomize/kustomization/) resource that tells Flux to sync the manifests in the artifact fetched from the registry. + +1. Commit the new files and push. + +## Verify your configuration + +You should see a newly created `nginx` pod in your cluster. + +If you want to see the deployment sync again, try updating the number of replicas in the +`src/nginx-deployment.yaml` file and push to the default branch. If all is working well, the change +should sync to the cluster when the pipeline has finished. + +Congratulations! You successfully configured a project to deploy an application and synchronize your changes! diff --git a/doc/user/clusters/agent/gitops/flux_tutorial.md b/doc/user/clusters/agent/gitops/flux_tutorial.md index 8aee0c01d65..f2d65b900f0 100644 --- a/doc/user/clusters/agent/gitops/flux_tutorial.md +++ b/doc/user/clusters/agent/gitops/flux_tutorial.md @@ -4,7 +4,7 @@ group: Environments info: A tutorial using Flux --- -# Tutorial: Set up Flux for GitOps **(FREE)** +# Tutorial: Set up Flux for GitOps **(FREE ALL)** This tutorial teaches you how to set up Flux for GitOps. You'll complete a bootstrap installation, install `agentk` in your cluster, and deploy a simple `nginx` application. @@ -83,8 +83,19 @@ You must register `agentk` before you install it in your cluster. To register `agentk`: -- Complete the steps in [Register the agent with GitLab](../install/index.md#register-the-agent-with-gitlab). - Be sure to save the agent registration token and `kas` address. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + If you have an [agent configuration file](../install/index.md#create-an-agent-configuration-file), + it must be in this project. Your cluster manifest files should also be in this project. +1. Select **Operate > Kubernetes clusters**. +1. Select **Connect a cluster (agent)**. + - If you want to create a configuration with CI/CD defaults, type a name. + - If you already have an agent configuration file, select it from the list. +1. Select **Register an agent**. +1. Securely store the agent access token and `kasAddress` for later. + +The agent is registered for your project. You don't need to run any commands yet. + +In the next step, you'll use Flux to install `agentk` in your cluster. ## Install `agentk` @@ -103,10 +114,24 @@ To install `agentk`: name: gitlab ``` -1. Apply the agent registration token as a secret in the cluster: +1. Create a file called `secret.yaml` that contains your agent access token as a secret: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: gitlab-agent-token + type: Opaque + stringData: + values.yaml: |- + config: + token: "<your-token-here>" + ``` + +1. Apply `secret.yaml` to your cluster: ```shell - kubectl create secret generic gitlab-agent-token -n gitlab --from-literal=token=YOUR-TOKEN-HERE + kubectl apply -f secret.yaml -n gitlab ``` Although this step does not follow GitOps principles, it simplifies configuration for new Flux users. @@ -147,8 +172,11 @@ To install `agentk`: interval: 1h0m0s values: config: - kasAddress: "wss://kas.gitlab.example.com" - secretName: "gitlab-agent-token" + kasAddress: "wss://kas.gitlab.com" + valuesFrom: + - kind: Secret + name: gitlab-agent-token + valuesKey: values.yaml ``` 1. To verify that `agentk` is installed and running in the cluster, run the following command: diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index a0d6e0d415d..140ac060dc7 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -63,9 +63,9 @@ GitLab in a Kubernetes cluster, you might need a different version of Kubernetes You can upgrade your Kubernetes version to a supported version at any time: +- 1.27 (support ends on July 22, 2024 or when 1.30 becomes supported) - 1.26 (support ends on March 22, 2024 or when 1.29 becomes supported) - 1.25 (support ends on October 22, 2023 or when 1.28 becomes supported) -- 1.24 (support ends on July 22, 2023 or when 1.27 becomes supported) GitLab aims to support a new minor Kubernetes version three months after its initial release. GitLab supports at least three production-ready Kubernetes minor versions at any given time. @@ -80,6 +80,18 @@ Some GitLab features might work on versions not listed here. [This epic](https:/ Read about how to [migrate to the agent for Kubernetes](../../infrastructure/clusters/migrate_to_gitlab_agent.md) from the certificate-based integration. +## Agent connection + +The agent opens a bidirectional channel to KAS for communication. +This channel is used for all communication between the agent and KAS: + +- Each agent can maintain up to 500 logical gRPC streams, including active and idle streams. +- The number of TCP connections used by the gRPC streams is determined by gRPC itself. +- Each connection has a maximum lifetime of two hours, with a one-hour grace period. + - A proxy in front of KAS might influence the maximum lifetime of connections. On GitLab.com, this is [two hours](https://gitlab.com/gitlab-cookbooks/gitlab-haproxy/-/blob/68df3484087f0af368d074215e17056d8ab69f1c/attributes/default.rb#L217). The grace period is 50% of the maximum lifetime. + +For detailed information about channel routing, see [Routing KAS requests in the agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/kas_request_routing.md). + ## Related topics - [GitOps workflow](gitops.md) diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index c847eaff13f..75571d1a4f5 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Installing the agent for Kubernetes **(FREE)** +# Installing the agent for Kubernetes **(FREE ALL)** > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. > - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/594) multi-arch images in GitLab 14.8. The first multi-arch release is `v14.8.1`. It supports AMD64 and ARM64 architectures. diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index eddc6ef3e16..c01b1337aca 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -239,3 +239,23 @@ Error: parse error at (gitlab-agent/templates/observability-secret.yaml:1): uncl ``` This error is typically caused by an incompatible version of Helm. To resolve the issue, ensure that you are using a version of Helm [compatible with your version of Kubernetes](index.md#supported-kubernetes-versions-for-gitlab-features). + +## `GitLab Agent Server: Unauthorized` error on Dashboard for Kubernetes + +An error like `GitLab Agent Server: Unauthorized. Trace ID: <...>` +on the [Dashboard for Kubernetes](../../../ci/environments/kubernetes_dashboard.md) page +might be caused by one of the following: + +- The `user_access` entry in the agent configuration file doesn't exist or is wrong. + To resolve, see [Grant users Kubernetes access](user_access.md). +- There are multiple [`_gitlab_kas` cookies](../../../administration/clusters/kas.md#kubernetes-api-proxy-cookie) + in the browser and sent to KAS. The most likely cause is multiple GitLab instances hosted + on the same site. + + For example, `gitlab.com` set a `_gitlab_kas` cookie targeted for `kas.gitlab.com`, + but the cookie is also sent to `kas.staging.gitlab.com`, which causes the error on `staging.gitlab.com`. + + To temporarily resolve, delete the `_gitlab_kas` cookie for `gitlab.com` from the browser cookie store. + [Issue 418998](https://gitlab.com/gitlab-org/gitlab/-/issues/418998) proposes a fix for this known issue. +- GitLab and KAS run on different sites. For example, GitLab on `gitlab.example.com` and KAS on `kas.example.com`. + GitLab does not support this use case. For details, see [issue 416436](https://gitlab.com/gitlab-org/gitlab/-/issues/416436). diff --git a/doc/user/clusters/agent/user_access.md b/doc/user/clusters/agent/user_access.md index 7e04091c940..a5989d823f6 100644 --- a/doc/user/clusters/agent/user_access.md +++ b/doc/user/clusters/agent/user_access.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Grant users Kubernetes access (Beta) **(FREE)** +# Grant users Kubernetes access (Beta) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390769) in GitLab 16.1, with [flags](../../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`. This feature is in [Beta](../../../policy/experiment-beta-support.md#beta). > - Feature flag `environment_settings_to_graphql` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124177) in GitLab 16.2. @@ -15,6 +15,11 @@ of a specific project or group. Granting access also activates the Dashboard for Kubernetes for a project or group. +For self-managed instances, make sure you either: + +- Host your GitLab instance and [KAS](../../../administration/clusters/kas.md) on the same domain. +- Host KAS on a subdomain of GitLab. For example, GitLab on `gitlab.com` and KAS on `kas.gitlab.com`. + ## Configure Kubernetes access Configure access when you want to grant users access @@ -51,7 +56,7 @@ user_access: - id: group-3/subgroup ``` -## Configure access with user impersonation **(PREMIUM)** +## Configure access with user impersonation **(PREMIUM ALL)** You can grant access to a Kubernetes cluster and transform requests into impersonation requests for authenticated users. diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index 74676e31d22..a967ec9ea24 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -4,7 +4,7 @@ group: Composition analysis 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 --- -# Operational Container Scanning **(ULTIMATE)** +# Operational Container Scanning **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8. > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/368828) the starboard directive in GitLab 15.4. The starboard directive is scheduled for removal in GitLab 16.0. diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md index e8fb399d1b0..08e1021f886 100644 --- a/doc/user/clusters/agent/work_with_agent.md +++ b/doc/user/clusters/agent/work_with_agent.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Working with the agent for Kubernetes **(FREE)** +# Working with the agent for Kubernetes **(FREE ALL)** Use the following tasks when working with the agent for Kubernetes. diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index 6ed0f08c4a7..a155dcf4a3c 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../index.md' --- -# Cluster cost management (removed) **(ULTIMATE)** +# Cluster cost management (removed) **(ULTIMATE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index fa56dc320be..4a6fa8d4862 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Cluster Environments (deprecated) **(PREMIUM)** +# Cluster Environments (deprecated) **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13392) in GitLab 12.3 for group-level clusters. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14809) in GitLab 12.4 for instance-level clusters. diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index 3076730b10f..0f389b94a33 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../index.md' --- -# Cluster integrations (removed) **(FREE)** +# Cluster integrations (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index 9f769c6535c..3341074f54d 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Cluster management project (deprecated) **(FREE)** +# Cluster management project (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32810) in GitLab 12.5. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index f6bcff0481a..f4f42f4dc27 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Manage cluster applications **(FREE)** +# Manage cluster applications **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) in GitLab 12.10 with Helmfile support via Helm v2. > - Helm v2 support was [dropped](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0. Use Helm v3 instead. diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md index fde8e455421..4bd42abb9e8 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Migrate from GitLab Managed Apps to Cluster Management Projects (deprecated) **(FREE)** +# Migrate from GitLab Managed Apps to Cluster Management Projects (deprecated) **(FREE ALL)** The GitLab Managed Apps were deprecated in GitLab 14.0 in favor of user-controlled Cluster Management projects. @@ -39,16 +39,16 @@ See also [video walk-throughs](#video-walk-throughs) with examples. Either way, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) and read the logs of the `detect-helm2-releases` job to know if you have any Helm v2 releases and which are they. -1. If you have no Helm v2 releases, skip this step. Otherwise, follow the official Helm docs on +1. If you have no Helm v2 releases, skip this step. Otherwise, follow the official Helm documentation on [how to migrate from Helm v2 to Helm v3](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/), and clean up the Helm v2 releases after you are confident that they have been successfully migrated. 1. In this step you should already have only Helm v3 releases. Uncomment from the main [`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file) the paths for the applications that you would like to manage with this project. Although you could uncomment all the ones you want to - managed at once, we recommend you repeat the following steps separately for each app, so you do not get lost during + managed at once, you should repeat the following steps separately for each app, so you do not get lost during the process. -1. Edit the associated `applications/{app}/helmfiles.yaml` to match the chart version currently deployed +1. Edit the associated `applications/{app}/helmfiles.yaml` to match the chart version deployed for your app. Take a GitLab Runner Helm v3 release as an example: The following command lists the releases and their versions: @@ -62,11 +62,11 @@ See also [video walk-throughs](#video-walk-throughs) with examples. Take the version from the `CHART` column which is in the format `{release}-v{chart_version}`, then edit the `version:` attribute in the `./applications/gitlab-runner/helmfile.yaml`, so that it matches the version - you have currently deployed. This is a safe step to avoid upgrading versions during this migration. + you have deployed. This is a safe step to avoid upgrading versions during this migration. Make sure you replace `gitlab-managed-apps` from the above command if you have your apps deployed to a different namespace. -1. Edit the `applications/{app}/values.yaml` associated with your app to match the currently +1. Edit the `applications/{app}/values.yaml` associated with your app to match the deployed values. For example, for GitLab Runner: 1. Copy the output of the following command (it might be big): @@ -77,7 +77,7 @@ See also [video walk-throughs](#video-walk-throughs) with examples. 1. Overwrite `applications/gitlab-runner/values.yaml` with the output of the previous command. - This safe step guarantees that no unexpected default values overwrite your currently deployed values. + This safe step guarantees that no unexpected default values overwrite your deployed values. For instance, your GitLab Runner could have its `gitlabUrl` or `runnerRegistrationToken` overwritten by mistake. 1. Some apps require special attention: diff --git a/doc/user/compliance/compliance_center/index.md b/doc/user/compliance/compliance_center/index.md new file mode 100644 index 00000000000..bd3409abe01 --- /dev/null +++ b/doc/user/compliance/compliance_center/index.md @@ -0,0 +1,354 @@ +--- +type: reference, howto +stage: Govern +group: Compliance +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 +--- + +# Compliance center **(ULTIMATE ALL)** + +> [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122931) from Compliance report in GitLab 16.3. + +See report and manage standards adherence, violations, and compliance frameworks for the group + +## Standards adherence dashboard + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125875) GraphQL APIs in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `compliance_adherence_report`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125444) standards adherence dashboard in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `adherence_report_ui`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire +instance, an administrator can [enable the feature flags](../../../administration/feature_flags.md) named +`compliance_adherence_report` and `adherence_report_ui`. On GitLab.com, this feature is not available. +This feature is not ready for production use. + +Standards adherence dashboard lists the adherence status of projects complying to GitLab standard. + +### View the standards adherence dashboard + +Prerequisites: + +- You must be an administrator or have the Owner role for the group. + +To view the standards adherence dashboard for a group: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Secure > Compliance center**. + +### GitLab standard + +GitLab standard consists of three rules: + +- Prevent authors as approvers. +- Prevent committers as approvers. +- At least two approvals. + +#### Prevent authors as approvers + +To comply with GitLab standard, you must prevent users from approving their own merge requests. For more information, +see [Prevent approval by author](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). + +On self-managed GitLab, when instance-level setting for [prevent approval by author](../../../administration/merge_requests_approvals.md) +is updated, the adherence status for all the projects on the instance is not updated automatically. +To update the adherence status for these projects, the group-level or the project-level setting must be updated. + +#### Prevent committers as approvers + +To comply with GitLab standard, you must prevent users from approving merge requests where they've added commits. For +more information, see [Prevent approvals by users who add commits](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). + +On self-managed GitLab, when instance-level setting for [prevent approvals by users who add commits](../../../administration/merge_requests_approvals.md) +is updated, the adherence status for all the projects on the instance is not updated automatically. +To update the adherence status for these projects, the group-level or the project-level setting must be updated. + +#### At least two approvals + +To comply with GitLab standard, you must have at least two users approve a merge request to get it merged. For more +information, see [Merge request approval rules](../../project/merge_requests/approvals/rules.md). + +## Compliance violations report + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36524) in GitLab 12.8 as Compliance Dashboard. +> - Compliance violation drawer [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299357) in GitLab 14.1. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/299360) to compliance report in GitLab 14.2. +> - [Replaced](https://gitlab.com/groups/gitlab-org/-/epics/5237) by merge request violations in GitLab 14.6 [with a flag](../../../administration/feature_flags.md) named `compliance_violations_report`. Disabled by default. +> - GraphQL API [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7222) in GitLab 14.9. +> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/5237) in GitLab 14.10. [Feature flag `compliance_violations_report`](https://gitlab.com/gitlab-org/gitlab/-/issues/346266) removed. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112111) to compliance violations report in GitLab 15.9. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/394950) ability to create/edit compliance frameworks in GitLab 16.0. + +With compliance violations report, you can see a high-level view of merge request activity for all projects in the group. + +When you select a row in the compliance report, a drawer appears that provides: + +- The project name and [compliance framework label](../../project/settings/index.md#add-a-compliance-framework-to-a-project), + if the project has one assigned. +- A link to the merge request that introduced the violation. +- The merge request's branch path in the format `[source] into [target]`. +- A list of users that committed changes to the merge request. +- A list of users that commented on the merge request. +- A list of users that approved the merge request. +- The user that merged the merge request. + +### View the compliance violations report for a group + +> Target branch search [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358414) in GitLab 16.0. + +Prerequisites: + +- You must be an administrator or have the Owner role for the group. + +To view the compliance violations report: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Secure > Compliance center**. + +You can sort the compliance report on: + +- Severity level. +- Type of violation. +- Merge request title. + +You can filter the compliance violations report on: + +- Project. +- Date range of merge. +- Target branch. + +Select a row to see details of the compliance violation. + +#### Severity levels + +Each compliance violation has one of the following severities. + +<!-- vale gitlab.SubstitutionWarning = NO --> + +| Icon | Severity level | +|:----------------------------------------------|:---------------| +| **{severity-critical, 18, gl-fill-red-800}** | Critical | +| **{severity-high, 18, gl-fill-red-600}** | High | +| **{severity-medium, 18, gl-fill-orange-400}** | Medium | +| **{severity-low, 18, gl-fill-orange-300}** | Low | +| **{severity-info, 18, gl-fill-blue-400}** | Info | + +<!-- vale gitlab.SubstitutionWarning = YES --> + +#### Violation types + +From [GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870), these are the available compliance violations. + +| Violation | Severity level | Category | Description | +|:----------------------------------|:---------------|:----------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Author approved merge request | High | [Separation of duties](#separation-of-duties) | Author of the merge request approved their own merge request. For more information, see [Prevent approval by author](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). | +| Committers approved merge request | High | [Separation of duties](#separation-of-duties) | Committers of the merge request approved the merge request they contributed to. For more information, see [Prevent approvals by users who add commits](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). | +| Fewer than two approvals | High | [Separation of duties](#separation-of-duties) | Merge request was merged with fewer than two approvals. For more information, see [Merge request approval rules](../../project/merge_requests/approvals/rules.md). | + +The following are unavailable compliance violations that are tracked in [epic 5237](https://gitlab.com/groups/gitlab-org/-/epics/5237). + +<!-- vale gitlab.SubstitutionWarning = NO --> + +| Violation | Severity level | Category | Description | +|:-------------------------------------|:---------------|:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------| +| Pipeline failed | Medium | [Pipeline results](../../../ci/pipelines/index.md) | Merge requests pipeline failed and was merged. | +| Pipeline passed with warnings | Info | [Pipeline results](../../../ci/pipelines/index.md) | Merge request pipeline passed with warnings and was merged. | +| Code coverage down more than 10% | High | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of more than 10%. | +| Code coverage down between 5% to 10% | Medium | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of between 5% to 10%. | +| Code coverage down between 1% to 5% | Low | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of between 1% to 5%. | +| Code coverage down less than 1% | Info | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of less than 1%. | + +<!-- vale gitlab.SubstitutionWarning = YES --> + +##### Separation of duties + +GitLab supports a separation of duties policy between users who create and approve merge requests. Our criteria for the +separation of duties is: + +- [A merge request author is **not** allowed to approve their merge request](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). +- [A merge request committer is **not** allowed to approve a merge request they have added commits to](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). +- [The minimum number of approvals required to merge a merge request is **at least** two](../../project/merge_requests/approvals/rules.md). + +### Chain of Custody report + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in GitLab 13.3. +> - Chain of Custody reports sent using email [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342594) in GitLab 15.3 with a flag named `async_chain_of_custody_report`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/370100) in GitLab 15.5. Feature flag `async_chain_of_custody_report` removed. +> - Chain of Custody report includes all commits (instead of just merge commits) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267601) in GitLab 15.9 with a flag named `all_commits_compliance_report`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112092) in GitLab 15.9. Feature flag `all_commits_compliance_report` removed. + +The Chain of Custody report provides a 1 month trailing window of all commits to a project under the group. + +To generate the report for all commits, GitLab: + +1. Fetches all projects under the group. +1. For each project, fetches the last 1 month of commits. Each project is capped at 1024 commits. If there are more than + 1024 commits in the 1-month window, they are truncated. +1. Writes the commits to a CSV file. The file is truncated at 15 MB because the report is emailed as an attachment + (GitLab 15.5 and later). + +The report includes: + +- Commit SHA. +- Commit author. +- Committer. +- Date committed. +- Group. +- Project. + +If the commit has a related merge commit, then the following are also included: + +- Merge commit SHA. +- Merge request ID. +- User who merged the merge request. +- Merge date. +- Pipeline ID. +- Merge request approvers. + +#### Generate Chain of Custody report + +To generate the Chain of Custody report: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Secure > Compliance center**. +1. Select **List of all merge commits**. + +Depending on your version of GitLab, the Chain of Custody report is either sent through email or available for download. + +#### Generate commit-specific Chain of Custody report + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in GitLab 13.6. +> - Support for including all commits instead of only merge commits [added](https://gitlab.com/gitlab-org/gitlab/-/issues/393446) in GitLab 15.10. + +You can generate a commit-specific Chain of Custody report for a given commit SHA. This report provides only the +details for the provided commit SHA. + +To generate a commit-specific Chain of Custody report: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Secure > Compliance center**. +1. At the top of the compliance report, to the right of **List of all commits**, select the down arrow + (**{chevron-lg-down}**). +1. Enter the commit SHA, and then select **Export commit custody report**. + +Depending on your version of GitLab, the Chain of Custody report is either sent through email or available for download. + +Alternatively, use a direct link: `https://gitlab.com/groups/<group-name>/-/security/merge_commit_reports.csv?commit_sha={optional_commit_sha}`, +passing in an optional value to the `commit_sha` query parameter. + +## Compliance frameworks report + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387910) in GitLab 15.10. + +With compliance frameworks report, you can see the compliance frameworks that are applied to projects in a group. Each row of the report shows: + +- Project name. +- Project path. +- Compliance framework label if the project has one assigned. + +The default framework for the group has a **default** badge. + +### View the compliance frameworks report for a group + +Prerequisites: + +- You must be an administrator or have the Owner role for the group. + +To view the compliance frameworks report: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Secure > Compliance center**. +1. On the page, select the **Frameworks** tab. + +### Apply a compliance framework to projects in a group + +> - Adding compliance frameworks using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11. +> - Adding compliance frameworks without using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394795) in GitLab 16.0. + +You can apply a compliance framework to projects in a group. + +Prerequisites: + +- You must have the Owner role for the group. + +To apply a compliance framework to one project in a group: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Secure > Compliance center**. +1. On the page, select the **Frameworks** tab. +1. Next to the project you want to add the compliance framework to, select **{plus}** **Add framework**. +1. Select an existing compliance framework or create a new one. + +To apply a compliance framework to multiple projects in a group: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Secure > Compliance center**. +1. On the page, select the **Frameworks** tab. +1. Select multiple projects. +1. From the **Choose one bulk action** dropdown list, select **Apply framework to selected projects**. +1. Select framework to apply. +1. Select **Apply**. + +### Remove a compliance framework from projects in a group + +> - Removing compliance frameworks using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11. +> - Removing compliance frameworks without using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394795) in GitLab 16.0. + +You can remove a compliance framework from projects in a group. + +Prerequisites: + +- You must have the Owner role for the group. + +To remove a compliance framework from one project in a group: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Secure > Compliance center**. +1. On the page, select the **Frameworks** tab. +1. Next to the compliance framework to remove from the project, select **{close}** on the framework label. + +To remove a compliance framework from multiple projects in a group: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Secure > Compliance center**. +1. On the page, select the **Frameworks** tab. +1. Select multiple projects. +1. From the **Choose one bulk action** dropdown list, select **Remove framework from selected projects**. +1. Select **Remove**. + +### Export a report of compliance frameworks on projects in a group + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387912) in GitLab 16.0. + +Export a report of compliance frameworks that are applied to projects in a group. Reports: + +- Do not use filters on the framework report. +- Are truncated at 15 MB so the email attachment too large. + +Prerequisites: + +- You must be an administrator or have the Owner role for the group. + +To export a report of compliance frameworks on projects in a group: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Secure > Compliance center**. +1. On the page, select the **Frameworks** tab. +1. On the Frameworks tab, select the **Export as CSV** action in the top right corner + +A report is compiled and delivered to your email inbox as an attachment. + +#### Filter the compliance frameworks report + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387911) in GitLab 15.11. + +To filter the list of compliance frameworks: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Secure > Compliance center**. +1. On the page, select the **Frameworks** tab. +1. In the search field: + 1. Select the attribute you want to filter by. + 1. Select an operator. + 1. Select from the list of options or enter text for the search. +1. Select **Search** (**{search}**). + +Repeat this process to filter by multiple attributes. diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index ab80fbbba8e..998e9c81d18 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -1,297 +1,11 @@ --- -type: reference, howto -stage: Govern -group: Compliance -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 +redirect_to: '../compliance_center/index.md' +remove_date: '2023-09-20' --- -# Compliance reports **(ULTIMATE)** +This document was moved to [another location](../compliance_center/index.md). -See reports about compliance violations and compliance frameworks for the group. - -## Compliance violations report - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36524) in GitLab 12.8 as Compliance Dashboard. -> - Compliance violation drawer [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299357) in GitLab 14.1. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/299360) to compliance report in GitLab 14.2. -> - [Replaced](https://gitlab.com/groups/gitlab-org/-/epics/5237) by merge request violations in GitLab 14.6 [with a flag](../../../administration/feature_flags.md) named `compliance_violations_report`. Disabled by default. -> - GraphQL API [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7222) in GitLab 14.9. -> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/5237) in GitLab 14.10. [Feature flag `compliance_violations_report`](https://gitlab.com/gitlab-org/gitlab/-/issues/346266) removed. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112111) to compliance violations report in GitLab 15.9. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/394950) ability to create/edit compliance frameworks in GitLab 16.0. - -With compliance violations report, you can see a high-level view of merge request activity for all projects in the group. - -When you select a row in the compliance report, a drawer appears that provides: - -- The project name and [compliance framework label](../../project/settings/index.md#add-a-compliance-framework-to-a-project), - if the project has one assigned. -- A link to the merge request that introduced the violation. -- The merge request's branch path in the format `[source] into [target]`. -- A list of users that committed changes to the merge request. -- A list of users that commented on the merge request. -- A list of users that approved the merge request. -- The user that merged the merge request. - -### View the compliance violations report for a group - -> Target branch search [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358414) in GitLab 16.0. - -Prerequisites: - -- You must be an administrator or have the Owner role for the group. - -To view the compliance violations report: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. On the left sidebar, select **Secure > Compliance report**. - -You can sort the compliance report on: - -- Severity level. -- Type of violation. -- Merge request title. - -You can filter the compliance violations report on: - -- Project. -- Date range of merge. -- Target branch. - -Select a row to see details of the compliance violation. - -#### Severity levels - -Each compliance violation has one of the following severities. - -<!-- vale gitlab.SubstitutionWarning = NO --> - -| Icon | Severity level | -|:----------------------------------------------|:---------------| -| **{severity-critical, 18, gl-fill-red-800}** | Critical | -| **{severity-high, 18, gl-fill-red-600}** | High | -| **{severity-medium, 18, gl-fill-orange-400}** | Medium | -| **{severity-low, 18, gl-fill-orange-300}** | Low | -| **{severity-info, 18, gl-fill-blue-400}** | Info | - -<!-- vale gitlab.SubstitutionWarning = YES --> - -#### Violation types - -From [GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870), these are the available compliance violations. - -| Violation | Severity level | Category | Description | -|:----------------------------------|:---------------|:----------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Author approved merge request | High | [Separation of duties](#separation-of-duties) | Author of the merge request approved their own merge request. For more information, see [Prevent approval by author](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). | -| Committers approved merge request | High | [Separation of duties](#separation-of-duties) | Committers of the merge request approved the merge request they contributed to. For more information, see [Prevent approvals by users who add commits](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). | -| Fewer than two approvals | High | [Separation of duties](#separation-of-duties) | Merge request was merged with fewer than two approvals. For more information, see [Merge request approval rules](../../project/merge_requests/approvals/rules.md). | - -The following are unavailable compliance violations that are tracked in [epic 5237](https://gitlab.com/groups/gitlab-org/-/epics/5237). - -<!-- vale gitlab.SubstitutionWarning = NO --> - -| Violation | Severity level | Category | Description | -|:-------------------------------------|:---------------|:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------| -| Pipeline failed | Medium | [Pipeline results](../../../ci/pipelines/index.md) | Merge requests pipeline failed and was merged. | -| Pipeline passed with warnings | Info | [Pipeline results](../../../ci/pipelines/index.md) | Merge request pipeline passed with warnings and was merged. | -| Code coverage down more than 10% | High | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of more than 10%. | -| Code coverage down between 5% to 10% | Medium | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of between 5% to 10%. | -| Code coverage down between 1% to 5% | Low | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of between 1% to 5%. | -| Code coverage down less than 1% | Info | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of less than 1%. | - -<!-- vale gitlab.SubstitutionWarning = YES --> - -##### Separation of duties - -GitLab supports a separation of duties policy between users who create and approve merge requests. Our criteria for the -separation of duties is: - -- [A merge request author is **not** allowed to approve their merge request](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). -- [A merge request committer is **not** allowed to approve a merge request they have added commits to](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). -- [The minimum number of approvals required to merge a merge request is **at least** two](../../project/merge_requests/approvals/rules.md). - -### Chain of Custody report - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in GitLab 13.3. -> - Chain of Custody reports sent using email [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342594) in GitLab 15.3 with a flag named `async_chain_of_custody_report`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/370100) in GitLab 15.5. Feature flag `async_chain_of_custody_report` removed. -> - Chain of Custody report includes all commits (instead of just merge commits) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267601) in GitLab 15.9 with a flag named `all_commits_compliance_report`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112092) in GitLab 15.9. Feature flag `all_commits_compliance_report` removed. - -The Chain of Custody report provides a 1 month trailing window of all commits to a project under the group. - -To generate the report for all commits, GitLab: - -1. Fetches all projects under the group. -1. For each project, fetches the last 1 month of commits. Each project is capped at 1024 commits. If there are more than - 1024 commits in the 1-month window, they are truncated. -1. Writes the commits to a CSV file. The file is truncated at 15 MB because the report is emailed as an attachment - (GitLab 15.5 and later). - -The report includes: - -- Commit SHA. -- Commit author. -- Committer. -- Date committed. -- Group. -- Project. - -If the commit has a related merge commit, then the following are also included: - -- Merge commit SHA. -- Merge request ID. -- User who merged the merge request. -- Merge date. -- Pipeline ID. -- Merge request approvers. - -#### Generate Chain of Custody report - -To generate the Chain of Custody report: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. On the left sidebar, select **Secure > Compliance report**. -1. Select **List of all merge commits**. - -Depending on your version of GitLab, the Chain of Custody report is either sent through email or available for download. - -#### Generate commit-specific Chain of Custody report - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in GitLab 13.6. -> - Support for including all commits instead of only merge commits [added](https://gitlab.com/gitlab-org/gitlab/-/issues/393446) in GitLab 15.10. - -You can generate a commit-specific Chain of Custody report for a given commit SHA. This report provides only the -details for the provided commit SHA. - -To generate a commit-specific Chain of Custody report: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. On the left sidebar, select **Secure > Compliance report**. -1. At the top of the compliance report, to the right of **List of all commits**, select the down arrow - (**{chevron-lg-down}**). -1. Enter the commit SHA, and then select **Export commit custody report**. - -Depending on your version of GitLab, the Chain of Custody report is either sent through email or available for download. - -Alternatively, use a direct link: `https://gitlab.com/groups/<group-name>/-/security/merge_commit_reports.csv?commit_sha={optional_commit_sha}`, -passing in an optional value to the `commit_sha` query parameter. - -## Compliance frameworks report - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387910) in GitLab 15.10. - -With compliance frameworks report, you can see the compliance frameworks that are applied to projects in a group. Each row of the report shows: - -- Project name. -- Project path. -- Compliance framework label if the project has one assigned. - -The default framework for the group has a **default** badge. - -### View the compliance frameworks report for a group - -Prerequisites: - -- You must be an administrator or have the Owner role for the group. - -To view the compliance frameworks report: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. On the left sidebar, select **Secure > Compliance report**. -1. On the page, select the **Frameworks** tab. - -### Apply a compliance framework to projects in a group - -> - Adding compliance frameworks using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11. -> - Adding compliance frameworks without using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394795) in GitLab 16.0. - -You can apply a compliance framework to projects in a group. - -Prerequisites: - -- You must have the Owner role for the group. - -To apply a compliance framework to one project in a group: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. On the left sidebar, select **Secure > Compliance report**. -1. On the page, select the **Frameworks** tab. -1. Next to the project you want to add the compliance framework to, select **{plus}** **Add framework**. -1. Select an existing compliance framework or create a new one. - -To apply a compliance framework to multiple projects in a group: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. On the left sidebar, select **Secure > Compliance report**. -1. On the page, select the **Frameworks** tab. -1. Select multiple projects. -1. From the **Choose one bulk action** dropdown list, select **Apply framework to selected projects**. -1. Select framework to apply. -1. Select **Apply**. - -### Remove a compliance framework from projects in a group - -> - Removing compliance frameworks using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11. -> - Removing compliance frameworks without using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394795) in GitLab 16.0. - -You can remove a compliance framework from projects in a group. - -Prerequisites: - -- You must have the Owner role for the group. - -To remove a compliance framework from one project in a group: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. On the left sidebar, select **Secure > Compliance report**. -1. On the page, select the **Frameworks** tab. -1. Next to the compliance framework to remove from the project, select **{close}** on the framework label. - -To remove a compliance framework from multiple projects in a group: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. On the left sidebar, select **Secure > Compliance report**. -1. On the page, select the **Frameworks** tab. -1. Select multiple projects. -1. From the **Choose one bulk action** dropdown list, select **Remove framework from selected projects**. -1. Select **Remove**. - -### Export a report of compliance frameworks on projects in a group - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387912) in GitLab 16.0. - -Export a report of compliance frameworks that are applied to projects in a group. Reports: - -- Do not use filters on the framework report. -- Are truncated at 15 MB so the email attachment too large. - -Prerequisites: - -- You must be an administrator or have the Owner role for the group. - -To export a report of compliance frameworks on projects in a group: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. On the left sidebar, select **Secure > Compliance report**. -1. On the page, select the **Frameworks** tab. -1. On the Frameworks tab, select the **Export as CSV** action in the top right corner - -A report is compiled and delivered to your email inbox as an attachment. - -#### Filter the compliance frameworks report - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387911) in GitLab 15.11. - -To filter the list of compliance frameworks: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. On the left sidebar, select **Secure > Compliance report**. -1. On the page, select the **Frameworks** tab. -1. In the search field: - 1. Select the attribute you want to filter by. - 1. Select an operator. - 1. Select from the list of options or enter text for the search. -1. Select **Search** (**{search}**). - -Repeat this process to filter by multiple attributes. +<!-- This redirect file can be deleted after <2023-09-20>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/compliance/index.md b/doc/user/compliance/index.md index ad36684d987..51053c03d8c 100644 --- a/doc/user/compliance/index.md +++ b/doc/user/compliance/index.md @@ -5,11 +5,11 @@ group: Compliance 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 --- -# Compliance **(ULTIMATE)** +# Compliance **(ULTIMATE ALL)** The compliance tools provided by GitLab help you keep an eye on various aspects of your project, including: -- [Compliance report](compliance_report/index.md). +- [Compliance center](compliance_center/index.md). - [License approval policies](license_approval_policies.md). - [License list](license_list.md). - [License scanning of CycloneDX files](license_scanning_of_cyclonedx_files/index.md). diff --git a/doc/user/compliance/license_approval_policies.md b/doc/user/compliance/license_approval_policies.md index 96a4a08249a..e3350b1ae10 100644 --- a/doc/user/compliance/license_approval_policies.md +++ b/doc/user/compliance/license_approval_policies.md @@ -5,7 +5,7 @@ group: Security Policies 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 --- -# License approval policies **(ULTIMATE)** +# License approval policies **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `license_scanning_policies`. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/397644) in GitLab 15.11. Feature flag `license_scanning_policies` removed. diff --git a/doc/user/compliance/license_check_rules.md b/doc/user/compliance/license_check_rules.md deleted file mode 100644 index 3007d04a8c1..00000000000 --- a/doc/user/compliance/license_check_rules.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -redirect_to: 'license_approval_policies.md' -remove_date: '2023-07-25' ---- - -# License Check Policies (removed) **(ULTIMATE)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/390417) in GitLab 15.9 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/397067) in 16.0. -Use [License Approval Policies](license_approval_policies.md) instead. - -<!-- This redirect file can be deleted after <2023-07-25>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 238cf10cba9..00578219016 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -3,845 +3,12 @@ type: reference, howto stage: Secure group: Composition Analysis 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 +remove_date: '2023-08-22' +redirect_to: '../license_approval_policies.md' --- -# License Compliance (deprecated) **(ULTIMATE)** +# License Compliance (removed) **(ULTIMATE ALL)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5483) in GitLab 11.0. -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9. - -WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9. You should instead migrate to use [License approval policies](../license_approval_policies.md) and the [new method of license scanning](../license_scanning_of_cyclonedx_files/index.md) prior to GitLab 16.1. - -If you're using [GitLab CI/CD](../../../ci/index.md), you can use License Compliance to search your -project's dependencies for their licenses. You can then decide whether to allow or deny the use of -each license. For example, if your application uses an external (open source) library whose license -is incompatible with yours, then you can deny the use of that license. - -To detect the licenses in use, License Compliance uses the [License Finder](https://github.com/pivotal/LicenseFinder) scan tool that runs as part of the CI/CD pipeline. The License Compliance job is not dependent on any other job in -a pipeline. - -For the job to activate, License Finder needs to find a compatible package definition in the project directory. For details, see the [Activation on License Finder documentation](https://github.com/pivotal/LicenseFinder#activation). -GitLab checks the License Compliance report, compares the -licenses between the source and target branches, and shows the information right on the merge -request. Denied licenses are indicated by a `x` red icon next to them as well as new licenses that -need a decision from you. In addition, you can [manually allow or deny](../license_approval_policies.md) licenses in your -project's security policies section. If a denied license is detected in a new commit, -GitLab blocks any merge requests containing that commit and instructs the developer to remove the -license. - -NOTE: -Starting with GitLab 15.9, License Compliance can detect the licenses in use -[using Dependency Scanning CI jobs](../license_scanning_of_cyclonedx_files/index.md) -instead of the License Scanning ones. - -NOTE: -If the license compliance report doesn't have anything to compare to, no information -is displayed in the merge request area. That is the case when you add the -`license_scanning` job in your `.gitlab-ci.yml` for the first time. -Consecutive merge requests have something to compare to and the license -compliance report is shown properly. - -The results are saved as a -[License Compliance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportslicense_scanning) -that you can later download and analyze. - -WARNING: -License Compliance Scanning does not support run-time installation of compilers and interpreters. - -## Enable License Compliance - -To enable License Compliance in your project's pipeline, either: - -- Enable [Auto License Compliance](../../../topics/autodevops/stages.md#auto-license-compliance) - (provided by [Auto DevOps](../../../topics/autodevops/index.md)). -- Include the [`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml) in your `.gitlab-ci.yml` file. - -License Compliance is not supported when GitLab is run with FIPS mode enabled. - -### Include the License Scanning template - -Prerequisites: - -- [GitLab Runner](../../../ci/runners/index.md) available, with the - [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). If you're using the - shared runners on GitLab.com, this is enabled by default. -- License Scanning runs in the `test` stage, which is available by default. If you redefine the stages in the - `.gitlab-ci.yml` file, the `test` stage is required. -- [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) must be disabled. - -To [include](../../../ci/yaml/index.md#includetemplate) the -[`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml), add it to your `.gitlab-ci.yml` file: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml -``` - -The included template creates a `license_scanning` job in your CI/CD pipeline and scans your -dependencies to find their licenses. - -## License expressions - -GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/). -License compliance can read multiple licenses, but always considers them combined using the `AND` operator. For example, -if a dependency has two licenses, and one of them is allowed and the other is denied by the project [license approval policy](../license_approval_policies.md), -GitLab evaluates the composite license as _denied_, as this is the safer option. -The ability to support other license expression operators (like `OR`, `WITH`) is tracked -in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/6571). - -## Supported languages and package managers - -The following languages and package managers are supported. - -Gradle 1.x projects are not supported. The minimum supported version of Maven is 3.2.5. - -| Language | Package managers | Notes | -|------------|----------------------------------------------------------------------------------------------|-------| -| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) (7 and earlier) | | -| Go | [Godep](https://github.com/tools/godep) ([deprecated](../../../update/deprecations.md#godep-support-in-license-compliance)), [go mod](https://github.com/golang/go/wiki/Modules) | | -| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | | -| .NET | [NuGet](https://www.nuget.org/) | The .NET Framework is supported via the [mono project](https://www.mono-project.com/). There are, however, some limitations. The scanner doesn't support Windows-specific dependencies and doesn't report dependencies of your project's listed dependencies. Also, the scanner always marks detected licenses for all dependencies as `unknown`. | -| Python | [pip](https://pip.pypa.io/en/stable/) | Python is supported through [requirements.txt](https://pip.pypa.io/en/stable/user_guide/#requirements-files) and [Pipfile.lock](https://github.com/pypa/pipfile#pipfilelock). | -| Ruby | [gem](https://rubygems.org/) | | - -### Experimental support - -The following languages and package managers are [supported experimentally](https://github.com/pivotal/LicenseFinder#experimental-project-types). -The reported licenses might be incomplete or inaccurate. - -| Language | Package managers | -|------------|---------------------------------------------------------------------------------------------------------------| -| JavaScript | [Yarn](https://yarnpkg.com/) | -| Go | `go get`, `gvt`, `glide`, `dep`, `trash`, `govendor` | -| Erlang | [Rebar](https://rebar3.org/) | -| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage), [CocoaPods](https://cocoapods.org/) v0.39 and below | -| Elixir | [Mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) | -| C++/C | [Conan](https://conan.io/) | -| Rust | [Cargo](https://crates.io/) | -| PHP | [Composer](https://getcomposer.org/) | - -## Available CI/CD variables - -License Compliance can be configured using CI/CD variables. - -| CI/CD variable | Required | Description | -|-----------------------------|----------|-------------| -| `ADDITIONAL_CA_CERT_BUNDLE` | no | Bundle of trusted CA certificates (currently supported in Pip, Pipenv, Maven, Gradle, Yarn, and npm projects). | -| `ASDF_JAVA_VERSION` | no | Version of Java to use for the scan. | -| `ASDF_NODEJS_VERSION` | no | Version of Node.js to use for the scan. | -| `ASDF_PYTHON_VERSION` | no | Version of Python to use for the scan. [Configuration](#selecting-the-version-of-python) | -| `ASDF_RUBY_VERSION` | no | Version of Ruby to use for the scan. | -| `GRADLE_CLI_OPTS` | no | Additional arguments for the Gradle executable. If not supplied, defaults to `--exclude-task=test`. | -| `LICENSE_FINDER_CLI_OPTS` | no | Additional arguments for the `license_finder` executable. For example, if you have multiple projects in nested directories, you can update your `.gitlab-ci.yml` template to specify a recursive scan, like `LICENSE_FINDER_CLI_OPTS: '--recursive'`. | -| `LM_JAVA_VERSION` | no | Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8. [Configuration](#selecting-the-version-of-java) | -| `LM_PYTHON_VERSION` | no | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. [Configuration](#selecting-the-version-of-python) | -| `MAVEN_CLI_OPTS` | no | Additional arguments for the `mvn` executable. If not supplied, defaults to `-DskipTests`. | -| `PIP_INDEX_URL` | no | Base URL of Python Package Index (default: `https://pypi.org/simple/`). | -| `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address to download the analyzer from. | -| `SETUP_CMD` | no | Custom setup for the dependency installation (experimental). | - -## Installing custom dependencies - -> Introduced in GitLab 11.4. - -The `license_finder` image already embeds many auto-detection scripts, languages, -and packages. Nevertheless, it's almost impossible to cover all cases for all projects. -That's why sometimes it's necessary to install extra packages, or to have extra steps -in the project automated setup, like the download and installation of a certificate. -For that, a `SETUP_CMD` CI/CD variable can be passed to the container, -with the required commands to run before the license detection. - -If present, this variable overrides the setup step necessary to install all the packages -of your application (for example: for a project with a `Gemfile`, the setup step could be -`bundle install`). - -For example: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -variables: - SETUP_CMD: sh my-custom-install-script.sh -``` - -In this example, `my-custom-install-script.sh` is a shell script at the root -directory of your project. - -## Working with Monorepos - -Depending on your language, you may need to specify the path to the individual -projects of a monorepo using the `LICENSE_FINDER_CLI_OPTS` variable. Passing in -the project paths can significantly speed up builds over using the `--recursive` -License Finder option. - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -variables: - LICENSE_FINDER_CLI_OPTS: "--aggregate_paths=relative-path/to/sub-project/one relative-path/to/sub-project/two" -``` - -## Overriding the template - -WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead. - -If you want to override the job definition (for example, change properties like -`variables` or `dependencies`), you need to declare a `license_scanning` job -after the template inclusion and specify any additional keys under it. For example: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - variables: - CI_DEBUG_TRACE: "true" -``` - -## Configuring Maven projects - -The License Compliance tool provides a `MAVEN_CLI_OPTS` CI/CD variable which can hold -the command line arguments to pass to the `mvn install` command which is executed under the hood. -Feel free to use it for the customization of Maven execution. For example: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - variables: - MAVEN_CLI_OPTS: --debug -``` - -`mvn install` runs through all of the [build life cycle](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html) -stages prior to `install`, including `test`. Running unit tests is not directly -necessary for the license scanning purposes and consumes time, so it's skipped -by having the default value of `MAVEN_CLI_OPTS` as `-DskipTests`. If you want -to supply custom `MAVEN_CLI_OPTS` and skip tests at the same time, don't forget -to explicitly add `-DskipTests` to your options. -If you still need to run tests during `mvn install`, add `-DskipTests=false` to -`MAVEN_CLI_OPTS`. - -### Using private Maven repositories - -If you have a private Maven repository which requires login credentials, -you can use the `MAVEN_CLI_OPTS` CI/CD variable. - -Read more on [how to use private Maven repositories](../../application_security/index.md#using-private-maven-repositories). - -You can also use `MAVEN_CLI_OPTS` to connect to a trusted Maven repository that uses a self-signed -or internally trusted certificate. For example: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - variables: - MAVEN_CLI_OPTS: -Dmaven.wagon.http.ssl.allowall=true -Dmaven.wagon.http.ssl.ignore.validity.dates=true -Dmaven.wagon.http.ssl.insecure=true -``` - -Alternatively, you can use a Java key store to verify the TLS connection. For instructions on how to -generate a key store file, see the -[Maven Guide to Remote repository access through authenticated HTTPS](https://maven.apache.org/guides/mini/guide-repository-ssl.html). - -## Selecting the version of Java - -License Compliance uses Java 8 by default. You can specify a different Java version using `LM_JAVA_VERSION`. - -`LM_JAVA_VERSION` only accepts versions: 8, 11, 14, 15. - -## Selecting the version of Python - -> - [Introduced](https://gitlab.com/gitlab-org/security-products/license-management/-/merge_requests/36) in GitLab 12.0. -> - In [GitLab 12.2](https://gitlab.com/gitlab-org/gitlab/-/issues/12032), Python 3.5 became the default. -> - In [GitLab 12.7](https://gitlab.com/gitlab-org/security-products/license-management/-/merge_requests/101), Python 3.8 became the default. - -License Compliance uses Python 3.8 and pip 19.1 by default. -If your project requires Python 2, you can switch to Python 2.7 and pip 10.0 -by setting the `LM_PYTHON_VERSION` CI/CD variable to `2`. - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - variables: - LM_PYTHON_VERSION: 2 -``` - -`LM_PYTHON_VERSION` or `ASDF_PYTHON_VERSION` can be used to specify the desired version of Python. When both variables are specified `LM_PYTHON_VERSION` takes precedence. - -## Custom root certificates for Python - -You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). - -### Using private Python repositories - -If you have a private Python repository you can use the `PIP_INDEX_URL` [CI/CD variable](#available-cicd-variables) -to specify its location. - -## Configuring npm projects - -You can configure npm projects by using an [`.npmrc`](https://docs.npmjs.com/configuring-npm/npmrc.html/) -file. - -### Using private npm registries - -If you have a private npm registry you can use the -[`registry`](https://docs.npmjs.com/using-npm/config/#registry) -setting to specify its location. - -For example: - -```plaintext -registry = https://npm.example.com -``` - -### Custom root certificates for npm - -You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). - -To disable TLS verification you can provide the [`strict-ssl`](https://docs.npmjs.com/using-npm/config/#strict-ssl) -setting. - -For example: - -```plaintext -strict-ssl = false -``` - -## Configuring Yarn projects - -You can configure Yarn projects by using a [`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc/) -file. - -### Using private Yarn registries - -If you have a private Yarn registry you can use the -[`npmRegistryServer`](https://yarnpkg.com/configuration/yarnrc/#npmRegistryServer) -setting to specify its location. - -For example: - -```plaintext -npmRegistryServer: "https://npm.example.com" -``` - -### Custom root certificates for Yarn - -You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). - -## Configuring Bower projects - -You can configure Bower projects by using a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) -file. - -### Using private Bower registries - -If you have a private Bower registry you can use the -[`registry`](https://bower.io/docs/config/#bowerrc-specification) -setting to specify its location. - -For example: - -```plaintext -{ - "registry": "https://registry.bower.io" -} -``` - -### Custom root certificates for Bower - -You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by -specifying a `ca` setting in a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) -file. - -## Configuring Bundler projects - -### Using private Bundler registries - -If you have a private Bundler registry you can use the -[`source`](https://bundler.io/man/gemfile.5.html#GLOBAL-SOURCES) -setting to specify its location. - -For example: - -```plaintext -source "https://gems.example.com" -``` - -### Custom root certificates for Bundler - -You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by -specifying a [`BUNDLE_SSL_CA_CERT`](https://bundler.io/v2.0/man/bundle-config.1.html) -[variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) -in the job definition. - -## Configuring Cargo projects - -### Using private Cargo registries - -If you have a private Cargo registry you can use the -[`registries`](https://doc.rust-lang.org/cargo/reference/registries.html) -setting to specify its location. - -For example: - -```toml -[registries] -my-registry = { index = "https://my-intranet:8080/git/index" } -``` - -### Custom root certificates for Cargo - -To supply a custom root certificate to complete TLS verification, do one of the following: - -- Use the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). -- Specify a [`CARGO_HTTP_CAINFO`](https://doc.rust-lang.org/cargo/reference/environment-variables.html) - [variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) - in the job definition. - -## Configuring Composer projects - -### Using private Composer registries - -If you have a private Composer registry you can use the -[`repositories`](https://getcomposer.org/doc/05-repositories.md) -setting to specify its location. - -For example: - -```json -{ - "repositories": [ - { "packagist.org": false }, - { - "type": "composer", - "url": "https://composer.example.com" - } - ], - "require": { - "monolog/monolog": "1.0.*" - } -} -``` - -### Custom root certificates for Composer - -You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by -specifying a [`COMPOSER_CAFILE`](https://getcomposer.org/doc/03-cli.md#composer-cafile) -[variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) -in the job definition. - -## Configuring Conan projects - -You can configure [Conan](https://conan.io/) projects by adding a `.conan` directory to your -project root. The project root serves as the [`CONAN_USER_HOME`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-user-home). - -Consult the [Conan](https://docs.conan.io/en/latest/reference/config_files/conan.conf.html#conan-conf) -documentation for a list of settings that you can apply. - -The `license_scanning` job runs in a [Debian 10](https://www.debian.org/releases/buster/) Docker -image. The supplied image ships with some build tools such as [CMake](https://cmake.org/) and [GCC](https://gcc.gnu.org/). -However, not all project types are supported by default. To install additional tools needed to -compile dependencies, use a [`before_script`](../../../ci/yaml/index.md#before_script) -to install the necessary build tools using the [`apt`](https://wiki.debian.org/PackageManagementTools) -package manager. For a comprehensive list, consult [the Conan documentation](https://docs.conan.io/en/latest/introduction.html#all-platforms-all-build-systems-and-compilers). - -The default [Conan](https://conan.io/) configuration sets [`CONAN_LOGIN_USERNAME`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name) -to `ci_user`, and binds [`CONAN_PASSWORD`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-password-conan-password-remote-name) -to the [`CI_JOB_TOKEN`](../../../ci/variables/predefined_variables.md) -for the running job. This allows Conan projects to fetch packages from a [GitLab Conan Repository](../../packages/conan_repository/index.md#fetch-conan-package-information-from-the-package-registry) -if a GitLab remote is specified in the `.conan/remotes.json` file. - -To override the default credentials specify a [`CONAN_LOGIN_USERNAME_{REMOTE_NAME}`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name) -matching the name of the remote specified in the `.conan/remotes.json` file. - -NOTE: -[MSBuild](https://github.com/mono/msbuild#microsoftbuild-msbuild) projects aren't supported. The -`license_scanning` image ships with [Mono](https://www.mono-project.com/) and [MSBuild](https://github.com/mono/msbuild#microsoftbuild-msbuild). -Additional setup may be required to build packages for this project configuration. - -### Using private Conan registries - -By default, [Conan](https://conan.io/) uses the `conan-center` remote. For example: - -```json -{ - "remotes": [ - { - "name": "conan-center", - "url": "https://conan.bintray.com", - "verify_ssl": true - } - ] -} -``` - -To fetch dependencies from an alternate remote, specify that remote in a `.conan/remotes.json`. For -example: - -```json -{ - "remotes": [ - { - "name": "gitlab", - "url": "https://gitlab.com/api/v4/packages/conan", - "verify_ssl": true - } - ] -} -``` - -If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/index.md#protect-a-cicd-variable) -following the naming convention described in the [`CONAN_LOGIN_USERNAME` documentation](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name). - -### Custom root certificates for Conan - -You can provide custom certificates by adding a `.conan/cacert.pem` file to the project root and -setting [`CA_CERT_PATH`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-cacert-path) -to `.conan/cacert.pem`. - -If you specify the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), this -variable's X.509 certificates are installed in the Docker image's default trust store and Conan is -configured to use this as the default `CA_CERT_PATH`. - -## Configuring Go projects - -To configure [Go modules](https://github.com/golang/go/wiki/Modules) -based projects, specify [CI/CD variables](https://pkg.go.dev/cmd/go#hdr-Environment_variables) -in the `license_scanning` job's [variables](#available-cicd-variables) section in `.gitlab-ci.yml`. - -If a project has [vendored](https://pkg.go.dev/cmd/go#hdr-Vendor_Directories) its modules, -then the combination of the `vendor` directory and `mod.sum` file are used to detect the software -licenses associated with the Go module dependencies. - -### Using private Go registries - -You can use the [`GOPRIVATE`](https://pkg.go.dev/cmd/go#hdr-Environment_variables) -and [`GOPROXY`](https://pkg.go.dev/cmd/go#hdr-Environment_variables) -environment variables to control where modules are sourced from. Alternatively, you can use -[`go mod vendor`](https://go.dev/ref/mod#tmp_28) to vendor a project's modules. - -### Custom root certificates for Go - -You can specify the [`-insecure`](https://pkg.go.dev/cmd/go/internal/get) flag by exporting the -[`GOFLAGS`](https://pkg.go.dev/cmd/go#hdr-Environment_variables) -environment variable. For example: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - variables: - GOFLAGS: '-insecure' -``` - -### Using private NuGet registries - -If you have a private NuGet registry you can add it as a source -by adding it to the [`packageSources`](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file#package-source-sections) -section of a [`nuget.config`](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file) file. - -For example: - -```xml -<?xml version="1.0" encoding="utf-8"?> -<configuration> - <packageSources> - <clear /> - <add key="custom" value="https://nuget.example.com/v3/index.json" /> - </packageSources> -</configuration> -``` - -### Custom root certificates for NuGet - -You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). - -### Migration from `license_management` to `license_scanning` - -WARNING: -The `license_management` job was deprecated in GitLab 12.8. The `License-Management.gitlab-ci.yml` template was removed from GitLab 14.0. - -In GitLab 12.8 a new name for `license_management` job was introduced. This change was made to improve clarity around the purpose of the scan, which is to scan and collect the types of licenses present in a projects dependencies. -GitLab 13.0 drops support for `license_management`. -If you're using a custom setup for License Compliance, you're required -to update your CI configuration accordingly: - -1. Change the CI template to `License-Scanning.gitlab-ci.yml`. -1. Change the job name to `license_scanning` (if you mention it in `.gitlab-ci.yml`). -1. Change the artifact name to `license_scanning`, and the filename to `gl-license-scanning-report.json` (if you mention it in `.gitlab-ci.yml`). - -For example, the following `.gitlab-ci.yml`: - -```yaml -include: - - template: License-Management.gitlab-ci.yml - -license_management: - artifacts: - reports: - license_management: gl-license-management-report.json -``` - -Should be changed to: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - artifacts: - reports: - license_scanning: gl-license-scanning-report.json -``` - -If you use the `license_management` artifact in GitLab 13.0 or later, the License Compliance job generates this error: - -```plaintext -WARNING: Uploading artifacts to coordinator... failed id=:id responseStatus=400 Bad Request status=400 Bad Request token=:sha - -FATAL: invalid_argument -``` - -If you encounter this error, follow the instructions described in this section. - -## Running License Compliance in an offline environment - -For self-managed GitLab instances in an environment with limited, restricted, or intermittent access -to external resources through the internet, some adjustments are required for the License Compliance job to -successfully run. For more information, see [Offline environments](../../application_security/offline_deployments/index.md). - -### Requirements for offline License Compliance - -To use License Compliance in an offline environment, you need: - -- To meet the standard [License Compliance prerequisites](#include-the-license-scanning-template). -- Docker Container Registry with locally available copies of License Compliance [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - -NOTE: -GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), -meaning the runner tries to pull Docker images from the GitLab container registry even if a local -copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) -in an offline environment if you prefer using only locally available Docker images. However, we -recommend keeping the pull policy setting to `always` if not in an offline environment, as this -enables the use of updated scanners in your CI/CD pipelines. - -### Make GitLab License Compliance analyzer images available inside your Docker registry - -For License Compliance with all [supported languages and package managers](#supported-languages-and-package-managers), -import the following default License Compliance analyzer images from `registry.gitlab.com` to your -offline [local Docker container registry](../../packages/container_registry/index.md): - -```plaintext -registry.gitlab.com/security-products/license-finder:latest -``` - -The process for importing Docker images into a local offline Docker registry depends on -**your network security policy**. Consult your IT staff to find an accepted and approved -process by which external resources can be imported or temporarily accessed. These scanners are [updated periodically](../../application_security/index.md#vulnerability-scanner-maintenance) -with new definitions, so consider if you are able to make periodic updates yourself. - -For details on saving and transporting Docker images as a file, see the Docker documentation on -[`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), -[`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). - -### Set License Compliance CI/CD variables to use local License Compliance analyzers - -Add the following configuration to your `.gitlab-ci.yml` file. You must replace `image` to refer to -the License Compliance Docker image hosted on your local Docker container registry: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - image: - name: localhost:5000/analyzers/license-management:latest -``` - -The License Compliance job should now use local copies of the License Compliance analyzers to scan -your code and generate security reports, without requiring internet access. - -Additional configuration may be needed for connecting to private registries for: - -- [Bower](#using-private-bower-registries), -- [Bundler](#using-private-bundler-registries), -- [Conan](#using-private-bower-registries), -- [Go](#using-private-go-registries), -- [Maven repositories](#using-private-maven-repositories), -- [npm](#using-private-npm-registries), -- [Python repositories](#using-private-python-repositories), -- [Yarn](#using-private-yarn-registries). - -### SPDX license list name matching - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212388) in GitLab 13.3. - -Prior to GitLab 13.3, offline environments required an exact name match for [project policies](../license_approval_policies.md). -In GitLab 13.3 and later, GitLab matches the name of [project policies](../license_approval_policies.md) -with license names from the [SPDX license list](https://spdx.org/licenses/). -A local copy of the SPDX license list is distributed with the GitLab instance. If needed, the GitLab -instance's administrator can manually update it with a [Rake task](../../../raketasks/spdx.md). - -## Warnings - -We recommend that you use the most recent version of all containers, and the most recent supported version of all package managers and languages. Using previous versions carries an increased security risk because unsupported versions may no longer benefit from active security reporting and backporting of security fixes. - -## Troubleshooting - -### `ASDF_PYTHON_VERSION` does not automatically install the version - -Defining a non-latest Python version in `ASDF_PYTHON_VERSION` [doesn't have it automatically installed](https://gitlab.com/gitlab-org/gitlab/-/issues/325604). If your project requires a non-latest version of Python: - -1. Define the required version by setting the `ASDF_PYTHON_VERSION` CI/CD variable. -1. Pass a custom script to the `SETUP_CMD` CI/CD variable to install the required version and dependencies. - -For example: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - SETUP_CMD: ./setup.sh - ASDF_PYTHON_VERSION: "3.7.2" - before_script: - - echo "asdf install python 3.7.2 && pip install -r requirements.txt" > setup.sh - - chmod +x setup.sh - - apt-get -y update - - apt-get -y install build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python-openssl git -``` - -### `ERROR -- : asdf: No preset version installed for command` - -This error occurs when the version of the tools used by your project -do not match the version of the pre-installed tools available in the -`license_scanning` Docker image. The `license_scanning` job uses -[asdf-vm](https://asdf-vm.com/) to activate the appropriate version of -a tool that your project relies on. For example, if your project relies on a specific -version of [Node.js](https://nodejs.org/) or any other supported tool you can -specify the desired version by adding a -[`.tool-versions`](https://asdf-vm.com/#/core-configuration?id=tool-versions) file to the project -or using the appropriate [`ASDF_<tool>_VERSION`](https://asdf-vm.com/#/core-configuration?id=environment-variables) environment variable to -activate the appropriate version. - -For example, the following `.tool-versions` file activates version `12.16.3` of [Node.js](https://nodejs.org/) -and version `2.7.4` of [Ruby](https://www.ruby-lang.org/). - -```plaintext -nodejs 12.16.3 -ruby 2.7.4 -``` - -The next example shows how to activate the same versions of the tools mentioned above by using CI/CD variables defined in your -project's `.gitlab-ci.yml` file. - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - variables: - ASDF_NODEJS_VERSION: '12.16.3' - ASDF_RUBY_VERSION: '2.7.4' -``` - -A full list of variables can be found in [CI/CD variables](#available-cicd-variables). - -To find out what tools are pre-installed in the `license_scanning` Docker image use the following command: - -```shell -$ docker run --entrypoint='' -ti --rm registry.gitlab.com/security-products/license-finder:4 \ - /bin/bash -c 'dpkg -i /opt/toolcache/*.deb && asdf list' -... -dotnet-core - 3.1.302 -elixir - 1.10.4 -golang - 1.15.5 - 1.16.2 -gradle -No versions installed -java - 11 - 14 - 15 - 8 -maven -No versions installed -nodejs - 10.21.0 - 12.18.2 - 14.17.1 -php - 7.4.8 -python - 2.7.18 - 3.3.7 - 3.4.10 - 3.5.9 - 3.6.11 - 3.7.7 - 3.8.5 -ruby - 2.4.10 - 2.4.5 - 2.4.9 - 2.5.8 - 2.6.0 - 2.6.1 - 2.6.2 - 2.6.3 - 2.6.4 - 2.6.5 - 2.6.6 - 2.7.0 - 2.7.1 - 2.7.2 -rust - 1.45.0 -``` - -It might take more than 10 minutes to run the command above. -This is because it installs every single tool version available in the Docker image. - -To interact with the `license_scanning` runtime environment use the following command: - -```shell -$ docker run -it --entrypoint='' registry.gitlab.com/security-products/license-finder:4 /bin/bash -l -root@6abb70e9f193:~# -``` - -NOTE: -Selecting a custom version of [Mono](https://www.mono-project.com/) or [.NET Core](https://dotnet.microsoft.com/download/dotnet) is currently not supported. - -### LicenseFinder::Maven: is not installed error - -If your project contains a `mvnw` or `mvnw.cmd` file, then the license scanning job may fail with the `LicenseFinder::Maven: is not installed error` error. To resolve this, modify the license scanning job to remove the files in the `before_script` section. Example: - -```yaml -include: - - template: License-Scanning.gitlab-ci.yml - -license_scanning: - before_script: - - rm mvnw - - rm mvnw.cmd -``` +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/421363) in GitLab 16.3. +Use [License Approval Policies](https://gitlab.com/groups/gitlab-org/-/epics/8092) instead. diff --git a/doc/user/compliance/license_list.md b/doc/user/compliance/license_list.md index deec4e28911..96ea43e5ce2 100644 --- a/doc/user/compliance/license_list.md +++ b/doc/user/compliance/license_list.md @@ -5,7 +5,7 @@ group: Threat Insights 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 --- -# License list **(ULTIMATE)** +# License list **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13582) in GitLab 12.7. @@ -16,13 +16,13 @@ For the licenses to appear under the license list, the following requirements must be met: 1. You must be generating an SBOM file with components from one of our [one of our supported languages](license_scanning_of_cyclonedx_files/index.md#supported-languages-and-package-managers). -1. If using our [`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/License-Scanning.gitlab-ci.yml) to generate the SBOM file, then your project must use at least one of the [supported languages and package managers](license_compliance/index.md#supported-languages-and-package-managers). +1. If using our [`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/License-Scanning.gitlab-ci.yml) to generate the SBOM file, then your project must use at least one of the [supported languages and package managers](license_scanning_of_cyclonedx_files/index.md#supported-languages-and-package-managers). Alternatively, licenses will also appear under the license list when using our deprecated [`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/License-Scanning.gitlab-ci.yml) as long as the following requirements are met: -1. The License Compliance CI/CD job must be [enabled](license_compliance/index.md#enable-license-compliance) for your project. +1. The Dependency Scanning CI/CD job must be [enabled](license_scanning_of_cyclonedx_files/index.md#enable-license-scanning) for your project. 1. Your project must use at least one of the - [supported languages and package managers](license_compliance/index.md#supported-languages-and-package-managers). + [supported languages and package managers](license_scanning_of_cyclonedx_files/index.md#supported-languages-and-package-managers). When everything is configured, on the left sidebar, select **Secure > License compliance**. diff --git a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md index 1fbe67a62b2..97f9f277776 100644 --- a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md +++ b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md @@ -5,13 +5,16 @@ group: Composition Analysis 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 --- -# License scanning of CycloneDX files **(ULTIMATE)** +# License scanning of CycloneDX files **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384932) in GitLab 15.9 for GitLab SaaS [with two flags](../../../administration/feature_flags.md) named `license_scanning_sbom_scanner` and `package_metadata_synchronization`. Both flags are disabled by default and both flags must be enabled for this feature to work. > - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/385173) in GitLab 15.10 for GitLab SaaS. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385173) in GitLab 15.10 for self-managed GitLab [with two flags](../../../administration/feature_flags.md) named `license_scanning_sbom_scanner` and `package_metadata_synchronization`, both of which must be enabled for this feature to work. The flags are disabled by default due to the initial performance load when the license database is first imported. Work to improve performance is being tracked in [issue 397670](https://gitlab.com/gitlab-org/gitlab/-/issues/397670). > - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/385173) in GitLab 15.11 for self-managed GitLab. +FLAG: +The legacy License Compliance analyzer was deprecated in GitLab 15.9 and removed in GitLab 16.3. To continue using GitLab for License Compliance, remove the License Compliance template from your CI/CD pipeline and add the [Dependency Scanning template](../../application_security/dependency_scanning/index.md#configuration). The Dependency Scanning template is now capable of gathering the required license information so it is no longer necessary to run a separate License Compliance job. The License Compliance CI/CD template should not be removed prior to verifying that the `license_scanning_sbom_scanner` and `package_metadata_synchronization` flags are enabled for the instance and that the instance has been upgraded to a version that supports the new method of license scanning. To begin using the Dependency Scanner quickly at scale, you may set up a [scan execution policy](../../application_security/policies/scan-execution-policies.md) at the group level to enforce the SBOM-based license scan for all projects in the group. Then, you may remove the inclusion of the `Jobs/License-Scanning.gitlab-ci.yml` template from your CI/CD configuration. If you wish to continue using the legacy License Compliance feature, you can do so by setting the `LICENSE_MANAGEMENT_VERSION CI` variable to `4`. This variable can be set at the [project](../../../ci/variables/index.md#for-a-project), [group](../../../ci/variables/index.md#for-a-group) or [instance](../../../ci/variables/index.md#for-an-instance) level. This configuration change will allow you to continue using an existing version of the License Compliance without having to adopt the new approach. **Bugs and vulnerabilities in this legacy analyzer will no longer be fixed.** + To detect the licenses in use, License Compliance relies on running the [Dependency Scanning CI Jobs](../../application_security/dependency_scanning/index.md), and analyzing the [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM) generated by those jobs. @@ -142,3 +145,22 @@ $ docker run -it --rm -v "$PWD:/my-cyclonedx-sboms" -w /my-cyclonedx-sboms cyclo Validating JSON BOM... BOM validated successfully. ``` + +If the JSON BOM fails validation, for example, because there are duplicate components: + +```shell +Validation failed: Found duplicates at the following index pairs: "(A, B), (C, D)" +#/properties/components/uniqueItems +``` + +This issue can be fixed by updating the CI template to use [jq](https://jqlang.github.io/jq/) to remove the duplicate components from the `gl-sbom-*.cdx.json` report by overriding the job definition that produces the duplicate components. For example, the following removes duplicate components from the `gl-sbom-gem-bundler.cdx.json` report file produced by the `gemnasium-dependency_scanning` job: + +```yaml +include: + - template: Jobs/Dependency-Scanning.gitlab-ci.yml + +gemnasium-dependency_scanning: + after_script: + - apk update && apk add jq + - jq '.components |= unique' gl-sbom-gem-bundler.cdx.json > tmp.json && mv tmp.json gl-sbom-gem-bundler.cdx.json +``` diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index c81cf6762e3..53add75ee19 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -4,7 +4,7 @@ group: Respond 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 --- -# Customer relations management (CRM) **(FREE)** +# Customer relations management (CRM) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2256) in GitLab 14.6 [with a flag](../../administration/feature_flags.md) named `customer_relations`. Disabled by default. > - In GitLab 14.8 and later, you can [create contacts and organizations only in root groups](https://gitlab.com/gitlab-org/gitlab/-/issues/350634). @@ -157,7 +157,7 @@ organizations using the GraphQL API. ## Issues -If you use [Service Desk](../project/service_desk.md) and create issues from emails, +If you use [Service Desk](../project/service_desk/index.md) and create issues from emails, issues are linked to contacts matching the email addresses in the sender and CC of the email. ### View issues linked to a contact diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 2e26b67170c..0bdbfe79775 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Comments and threads **(FREE)** +# Comments and threads **(FREE ALL)** > - Paginated merge request discussions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340172) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `paginated_mr_discussions`. Disabled by default. > - Paginated merge request discussions [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.2. @@ -221,7 +221,7 @@ To change the activity sort order: 1. On the right side of the page, from the **Sort or filter** dropdown list, select the sort order **Newest first** or **Oldest first** (default). -## View description change history **(PREMIUM)** +## View description change history **(PREMIUM ALL)** You can see changes to the description listed in the history. diff --git a/doc/user/enterprise_user/index.md b/doc/user/enterprise_user/index.md index 27fff4bf8e3..e7be5bfb140 100644 --- a/doc/user/enterprise_user/index.md +++ b/doc/user/enterprise_user/index.md @@ -134,6 +134,15 @@ You then see: - The domains' status of **Verified** or **Unverified**. - The project where the domain has been configured. +### Manage domains in group + +To edit or remove a domain: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your top-level group. +1. Select **Settings > Domain Verification**. +1. When viewing **Domain Verification**, select the project listed next to the relevant domain. +1. Edit or remove a domain following the relevant [GitLab Pages custom domains](../project/pages/custom_domains_ssl_tls_certification/index.md) instructions. + ## Manage enterprise users in a namespace A top-level Owner of a namespace on a paid plan can retrieve information about and diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 04858d8ac34..47f6e0ac1d9 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -11,6 +11,15 @@ This page contains information about the settings that are used on GitLab.com, a See some of these settings on the [instance configuration page](https://gitlab.com/help/instance_configuration) of GitLab.com. +## Email confirmation + +GitLab.com has the: + +- [`email_confirmation_setting`](../../administration/settings/sign_up_restrictions.md#confirm-user-email) + setting set to **Hard**. +- [`unconfirmed_users_delete_after_days`](../../administration/moderate_users.md#automatically-delete-unconfirmed-users) + setting set to one day. + ## Password requirements GitLab.com has the following requirements for passwords on new accounts and password changes: @@ -73,7 +82,7 @@ The IP addresses for `mg.gitlab.com` are subject to change at any time. On GitLab.com, there's a mailbox configured for Service Desk with the email address: `contact-project+%{key}@incoming.gitlab.com`. To use this mailbox, configure the -[custom suffix](../project/service_desk.md#configure-a-suffix-for-service-desk-alias-email) in project +[custom suffix](../project/service_desk/index.md#configure-a-suffix-for-service-desk-alias-email) in project settings. ## Backups @@ -201,11 +210,14 @@ varies by format: GitLab.com has the following account limits enabled. If a setting is not listed, the default value [is the same as for self-managed instances](../../administration/settings/account_and_limit_settings.md): -| Setting | GitLab.com default | -|-------------------------------|--------------------| -| [Repository size including LFS](../../administration/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | -| [Maximum import size](../project/settings/import_export.md#import-a-project-and-its-data) | 5 GB | -| Maximum attachment size | 100 MB | +| Setting | GitLab.com default | +|--------------------------------------------------------------------------------------------------------------------|--------------------| +| [Repository size including LFS](../../administration/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | +| [Maximum import size](../project/settings/import_export.md#import-a-project-and-its-data) | 5 GB | +| Maximum remote file size for imports from external object storages | 10 GB | +| Maximum download file size when importing from source GitLab instances by direct transfer | 5 GB | +| Maximum attachment size | 100 MB | +| [Maximum decompressed file size for imported archives](../../administration/settings/account_and_limit_settings.md#maximum-decompressed-file-size-for-imported-archives) | 25 GB | If you are near or over the repository size limit, you can either [reduce your repository size with Git](../project/repository/reducing_the_repo_size_using_git.md) diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index 8bebaae003c..0ccd4512039 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Configure your groups to control group permissions and access. -## Group push rules **(PREMIUM)** +## Group push rules **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in GitLab 12.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/224129) in GitLab 13.4. @@ -52,7 +52,7 @@ To change the permitted Git access protocols for a group: 1. Choose the permitted protocols from **Enabled Git access protocols**. 1. Select **Save changes**. -## Restrict group access by IP address **(PREMIUM)** +## Restrict group access by IP address **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in GitLab 12.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) from GitLab Ultimate to GitLab Premium in 13.1. @@ -101,8 +101,9 @@ Keep in mind that restricting group access by IP address has the following impli - IP access restrictions for Git operations via SSH are supported on GitLab SaaS. IP access restrictions applied to self-managed instances are possible with [`gitlab-sshd`](../../administration/operations/gitlab_sshd.md) with [PROXY protocol](../../administration/operations/gitlab_sshd.md#proxy-protocol-support) enabled. +- IP restriction is not applicable to shared resources belonging to a group. Any shared resource is accessible to a user even if that user is not able to access the group. -## Restrict group access by domain **(PREMIUM)** +## Restrict group access by domain **(PREMIUM ALL)** > - Support for specifying multiple email domains [added](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) in GitLab 13.1. > - Support for restricting access to projects in the group [added](https://gitlab.com/gitlab-org/gitlab/-/issues/14004) in GitLab 14.1.2. @@ -192,7 +193,7 @@ your group. 1. Clear the **Allow users to request access** checkbox. 1. Select **Save changes**. -## Prevent project forking outside group **(PREMIUM)** +## Prevent project forking outside group **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216987) in GitLab 13.3. @@ -214,7 +215,7 @@ To prevent projects from being forked outside the group: Existing forks are not removed. -## Prevent members from being added to projects in a group **(PREMIUM)** +## Prevent members from being added to projects in a group **(PREMIUM ALL)** As a group Owner, you can prevent any new project membership for all projects in a group, allowing tighter control over project membership. diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 15fa5941dc2..e41991f365c 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -5,7 +5,7 @@ group: Environments 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 --- -# Group-level Kubernetes clusters (certificate-based) (deprecated) **(FREE)** +# Group-level Kubernetes clusters (certificate-based) (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in GitLab 11.6. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. @@ -106,7 +106,7 @@ the [Auto DevOps](../../../topics/autodevops/index.md) stages. The domain should have a wildcard DNS configured to the Ingress IP address. [More details](../../project/clusters/gitlab_managed_clusters.md#base-domain). -## Environment scopes **(PREMIUM)** +## Environment scopes **(PREMIUM ALL)** When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with @@ -162,7 +162,7 @@ The result is: - The Staging cluster is used for the `deploy to staging` job. - The Production cluster is used for the `deploy to production` job. -## Cluster environments **(PREMIUM)** +## Cluster environments **(PREMIUM ALL)** For a consolidated view of which CI [environments](../../../ci/environments/index.md) are deployed to the Kubernetes cluster, see the documentation for diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md index 267cdbbebd3..35e8ad27bc3 100644 --- a/doc/user/group/compliance_frameworks.md +++ b/doc/user/group/compliance_frameworks.md @@ -4,7 +4,7 @@ group: Compliance 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 --- -# Compliance frameworks **(PREMIUM)** +# Compliance frameworks **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.12. @@ -113,7 +113,7 @@ mutation { } ``` -## Compliance pipelines **(ULTIMATE)** +## Compliance pipelines **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3156) in GitLab 13.9, disabled behind `ff_evaluate_group_level_compliance_pipeline` [feature flag](../../administration/feature_flags.md). > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300324) in GitLab 13.11. diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 02f1e7f21e2..9716143f5e2 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -4,7 +4,7 @@ stage: Plan group: Optimize 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 --- -# Contribution analytics **(PREMIUM)** +# Contribution analytics **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3090) in GitLab 12.2 for subgroups. diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 6bd57079c67..1a481641111 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -4,16 +4,16 @@ group: Source Code 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 --- -# Custom group-level project templates **(PREMIUM)** +# Custom group-level project templates **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6861) in GitLab 11.6. -When you create a project, you can [choose from a list of templates](../project/index.md#create-a-project). +When you create a project, you can [choose from a list of templates](../project/index.md). These templates, for things like GitLab Pages or Ruby, populate the new project with a copy of the files contained in the template. This information is identical to the information used by [GitLab project import/export](../project/settings/import_export.md) and can help you start a new project more quickly. -You can [customize the list](../project/index.md#create-a-project) of available templates, so +You can [customize the list](../project/index.md) of available templates, so that all projects in your group have the same list. To do this, you populate a subgroup with the projects you want to use as templates. diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 7aa4695e58b..852d26f3816 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -4,7 +4,7 @@ group: Optimize 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 --- -# Group DevOps Adoption **(ULTIMATE)** +# Group DevOps Adoption **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321083) in GitLab 13.11 as a [Beta feature](../../../policy/experiment-beta-support.md#beta). > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/333556) in GitLab 14.1. diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 47bcd92f134..41231db5964 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Epic boards **(PREMIUM)** +# Epic boards **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5067) in GitLab 13.10. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/290039) in GitLab 14.1. diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 5d3bac4f895..7b977dc2026 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Epics **(PREMIUM)** +# Epics **(PREMIUM ALL)** When [issues](../../project/issues/index.md) share a theme across projects and milestones, you can manage them by using epics. @@ -52,7 +52,7 @@ You can add issues from a different group hierarchy to an epic. To do it, paste the issue URL when [adding an existing issue](manage_epics.md#add-an-existing-issue-to-an-epic). -## Roadmap in epics **(ULTIMATE)** +## Roadmap in epics **(ULTIMATE ALL)** If your epic contains one or more [child epics](manage_epics.md#multi-level-child-epics) that have a start or due date, a visual diff --git a/doc/user/group/epics/linked_epics.md b/doc/user/group/epics/linked_epics.md index 9ce4a585d14..8b57c1b4d1f 100644 --- a/doc/user/group/epics/linked_epics.md +++ b/doc/user/group/epics/linked_epics.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Linked epics **(ULTIMATE)** +# Linked epics **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353473) in GitLab 14.9 [with a flag](../../../administration/feature_flags.md) named `related_epics_widget`. Enabled by default. > - [Feature flag `related_epics_widget`](https://gitlab.com/gitlab-org/gitlab/-/issues/357089) removed in GitLab 15.0. diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 8265540cc34..e6116151012 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -5,7 +5,7 @@ group: Product Planning 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 --- -# Manage epics **(PREMIUM)** +# Manage epics **(PREMIUM ALL)** This page collects instructions for all the things you can do with [epics](index.md) or in relation to them. @@ -448,7 +448,7 @@ To reorder issues assigned to an epic: 1. Go to the **Child issues and epics** section. 1. Drag issues into the desired order. -### Move issues between epics **(ULTIMATE)** +### Move issues between epics **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0. > - Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8. @@ -508,7 +508,7 @@ For an introduction to epic templates, see [GitLab Epics and Epic Template Tip]( For more on epic templates, see [Epic Templates - Repeatable sets of issues](https://about.gitlab.com/handbook/marketing/brand-and-product-marketing/product-and-solution-marketing/getting-started/104/). -## Multi-level child epics **(ULTIMATE)** +## Multi-level child epics **(ULTIMATE ALL)** You can add any epic that belongs to a group or subgroup of the parent epic's group. New child epics appear at the top of the list of epics in the **Child issues and epics** section. diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 154eb467ece..b645ea04038 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Migrating GitLab groups **(FREE)** +# Migrating GitLab groups **(FREE ALL)** You can migrate GitLab groups: @@ -64,6 +64,53 @@ groups are in the same GitLab instance. Transferring groups is a faster and more See [epic 6629](https://gitlab.com/groups/gitlab-org/-/epics/6629) for a list of known issues for migrating by direct transfer. +### Estimating migration duration + +Estimating the duration of migration by direct transfer is difficult. The following factors affect migration duration: + +- Hardware and database resources available on the source and destination GitLab instances. More resources on the source and destination instances can result in + shorter migration duration because: + - The source instance receives API requests, and extracts and serializes the entities to export. + - The destination instance runs the jobs and creates the entities in its database. +- Complexity and size of data to be exported. For example, imagine you want to migrate two different projects with 1000 merge requests each. The two projects can take + very different amounts of time to migrate if one of the projects has a lot more attachments, comments, and other items on the merge requests. Therefore, the number + of merge requests on a project is a poor predictor of how long a project will take to migrate. + +There’s no exact formula to reliably estimate a migration. However, the average durations of each pipeline worker importing a project relation can help you to get an idea of how long importing your projects might take: + +| Project resource type | Average time (in seconds) to import a record | +|:----------------------------|:---------------------------------------------| +| Empty Project | 2.4 | +| Repository | 20 | +| Project Attributes | 1.5 | +| Members | 0.2 | +| Labels | 0.1 | +| Milestones | 0.07 | +| Badges | 0.1 | +| Issues | 0.1 | +| Snippets | 0.05 | +| Snippet Repositories | 0.5 | +| Boards | 0.1 | +| Merge Requests | 1 | +| External Pull Requests | 0.5 | +| Protected Branches | 0.1 | +| Project Feature | 0.3 | +| Container Expiration Policy | 0.3 | +| Service Desk Setting | 0.3 | +| Releases | 0.1 | +| CI Pipelines | 0.2 | +| Commit Notes | 0.05 | +| Wiki | 10 | +| Uploads | 0.5 | +| LFS Objects | 0.5 | +| Design | 0.1 | +| Auto DevOps | 0.1 | +| Pipeline Schedules | 0.5 | +| References | 5 | +| Push Rule | 0.1 | + +If you are migrating large projects and encounter problems with timeouts or duration of the migration, see [Reducing migration duration](#reducing-migration-duration). + ### Limits Hardcoded limits apply on migration by direct transfer. @@ -77,7 +124,6 @@ Hardcoded limits apply on migration by direct transfer. | 50 MB | Maximum length an NDJSON row can have. | | 5 minutes | Maximum number of seconds until an empty export status on source instance is raised. | | 8 hours | Time until migration times out. | -| 90 minutes | Time the destination is waiting for export to complete. | You can test the maximum relation size limit using these APIs: @@ -91,8 +137,12 @@ If either API produces files larger than the maximum relation size limit, group After migration: - Private groups and projects stay private. +- Internal groups and projects: + - Stay internal when copied into an internal group unless internal visibility is [restricted](../../../administration/settings/visibility_and_access_controls.md#restrict-visibility-levels). In that case, the groups and projects become private. + - Become private when copied into a private group. - Public groups and projects: - - Stay public when copied into a public group. + - Stay public when copied into a public group unless public visibility is [restricted](../../../administration/settings/visibility_and_access_controls.md#restrict-visibility-levels). In that case, the groups and projects become internal. + - Become internal when copied into an internal group unless internal visibility is [restricted](../../../administration/settings/visibility_and_access_controls.md#restrict-visibility-levels). In that case, the groups and projects become private. - Become private when copied into a private group. If you used a private network on your source instance to hide content from the general public, @@ -429,6 +479,24 @@ You can receive other `404` errors when importing a group, for example: This error indicates a problem transferring from the _source_ instance. To solve this, check that you have met the [prerequisites](#prerequisites) on the source instance. +#### Reducing migration duration + +A single direct transfer migration runs 5 entities (groups or projects) per import at a time, independent of the number of workers available on the destination instance. +That said, having more workers on the destination instance speeds up migration by decreasing the time it takes to import each entity. + +Increasing the number of workers on the destination instance helps reduce the migration duration until the source instance hardware resources are saturated. Exporting and importing relations in batches (proposed in [epic 9036](https://gitlab.com/groups/gitlab-org/-/epics/9036)) will make having enough available workers on +the destination instance even more useful. + +The number of workers on the source instance should be enough to export the 5 concurrent entities in parallel (for each running import). Otherwise, there can be +delays and potential timeouts as the destination is waiting for exported data to become available. + +Distributing projects in different groups helps to avoid timeouts. If several large projects are in the same group, you can: + +1. Move large projects to different groups or subgroups. +1. Start separate migrations each group and subgroup. + +The GitLab UI can only migrate top-level groups. Using the API, you can also migrate subgroups. + ## Migrate groups by uploading an export file (deprecated) > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. @@ -581,7 +649,7 @@ To help avoid abuse, by default, users are rate limited to: | Download export | 1 download per group per minute | | Import | 6 groups per minute | -## Automate group and project import **(PREMIUM)** +## Automate group and project import **(PREMIUM ALL)** For information on automating user, group, and project import API calls, see [Automate group and project import](../../project/import/index.md#automate-group-and-project-import). diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 7ff9648e41e..13fba43f8ef 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -4,7 +4,7 @@ group: Tenant Scale 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 --- -# Groups **(FREE)** +# Groups **(FREE ALL)** In GitLab, you use groups to manage one or more related projects at the same time. @@ -27,7 +27,7 @@ organization view of all groups, [see epic 9266](https://gitlab.com/groups/gitla A single top-level group provides insights in your entire organization via a complete [Security Dashboard and Center](../application_security/security_dashboard/index.md), [Vulnerability](../application_security/vulnerability_report/index.md#vulnerability-report) and -[Compliance Report](../compliance/compliance_report/index.md), and +[Compliance center](../compliance/compliance_center/index.md), and [Value stream analytics](../group/value_stream_analytics/index.md). ## Group visibility @@ -63,6 +63,24 @@ This page shows groups that you are a member of: - Through membership of a subgroup's parent group. - Through direct or inherited membership of a project in the group or subgroup. +## View group activity + +To view the activity of a project: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Activity**. +1. Optional. To filter activity by contribution type, select a tab: + + - **All**: All contributions by group members in the group and group's projects. + - **Push events**: Push events in the group's projects. + - **Merge events**: Accepted merge requests in the group's projects. + - **Issue events**: Issues opened and closed in the group's projects. + - **Epic events**: Epics opened and closed in the group. + - **Comments**: Comments posted by group members in the group's projects. + - **Wiki**: Updates to wiki pages in the group. + - **Designs**: Designs added, updated, and removed in the group's projects. + - **Team**: Group members who joined and left the group's projects. + ## Create a group To create a group: @@ -111,7 +129,7 @@ In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/39504), if the user who sets up the deletion is removed from the group before the deletion happens, the job is cancelled, and the group is no longer scheduled for deletion. -## Remove a group immediately **(PREMIUM)** +## Remove a group immediately **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336985) in GitLab 14.2. > - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. @@ -134,7 +152,7 @@ To immediately remove a group marked for deletion: Your group, its subgroups, projects, and all related resources, including issues and merge requests, are deleted. -## Restore a group **(PREMIUM)** +## Restore a group **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33257) in GitLab 12.8. @@ -231,6 +249,8 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last ## Add users to a group +> Expiring access email notification [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.2. + You can give a user access to all projects in a group. Prerequisite: @@ -242,9 +262,13 @@ Prerequisite: 1. Select **Invite members**. 1. Fill in the fields. - The role applies to all projects in the group. For more information, see [permissions](../permissions.md). - - On the **Access expiration date**, the user can no longer access projects in the group. + - Optional. Select an **Access expiration date**. From that date onward, the + user can no longer access the project. 1. Select **Invite**. +If you selected an access expiration date, the group member gets an email notification +seven days before their access expires. + Members that are not automatically added are displayed on the **Invited** tab. Users can be on this tab because they: @@ -283,7 +307,7 @@ To avoid this problem, GitLab administrators can [ensure removed users cannot in There are two different ways to add a new project to a group: -- Select a group, and then select **New project**. You can then continue [creating your project](../../user/project/index.md#create-a-project). +- Select a group, and then select **New project**. You can then continue [creating your project](../../user/project/index.md). - While you are creating a project, select a group from the dropdown list.  diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index ab967c8b12c..5cb982a85e4 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -4,7 +4,7 @@ group: Optimize 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 --- -# Insights for groups **(ULTIMATE)** +# Insights for groups **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 12.0. @@ -47,8 +47,8 @@ Insights display data from the last 90 days. You can zoom in to display data onl To do this, select the pause icons (**{status-paused}**) and slide them along the horizontal axis: -- To select a later start date, slide the left pause icon to the right. -- To select an earlier end date, slide the right pause icon to the left. +- To change the start date, slide the left pause icon to the left or right. +- To change the end date, slide the right pause icon to the left or right. ### Exclude dimensions from charts diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index cc43ca80801..46ba1747b06 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Issue analytics for groups **(PREMIUM)** +# Issue analytics for groups **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in GitLab 11.5. diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index a4677182bb0..91e69f3a02d 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Iterations **(PREMIUM)** +# Iterations **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214713) in GitLab 13.1 [with a flag](../../../administration/feature_flags.md) named `group_iterations`. Disabled by default. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) in GitLab 13.2. diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index b7bdf236ff7..743aabd8f4b 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -15,7 +15,7 @@ organization view of all groups, [see epic 9266](https://gitlab.com/groups/gitla A single top-level group provides insights in your entire organization via a complete [Security Dashboard and Center](../application_security/security_dashboard/index.md), [Vulnerability](../application_security/vulnerability_report/index.md#vulnerability-report) and -[Compliance Report](../compliance/compliance_report/index.md), and +[Compliance center](../compliance/compliance_center/index.md), and [Value stream analytics](../group/value_stream_analytics/index.md). ## Add a group README @@ -215,7 +215,7 @@ To disable group mentions: 1. Select **Group mentions are disabled**. 1. Select **Save changes**. -## Export members as CSV **(PREMIUM)** +## Export members as CSV **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287940) in GitLab 14.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/336520) in GitLab 14.5. @@ -233,11 +233,10 @@ For members with `Minimal Access` in the selected group, their `Max Role` and `S ## User cap for groups -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330027) in GitLab 14.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330027) in GitLab 14.7 [with a flag](../../administration/feature_flags.md) named `saas_user_caps`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/9263) in GitLab 16.3. -FLAG: -On self-managed GitLab, this feature is not available. On GitLab.com, this feature is available for some groups. -This feature is not ready for production use. +For more information about user caps for GitLab self-managed, see [User cap](../../administration/settings/sign_up_restrictions.md#user-cap). When the number of billable members reaches the user cap, new users can't be added to the group without being approved by the group owner. @@ -301,7 +300,17 @@ To approve members that are pending because they've exceeded the user cap: 1. On the **Seats** tab, under the alert, select **View pending approvals**. 1. For each member you want to approve, select **Approve**. -## Group file templates **(PREMIUM)** +### Known issues + +The user cap cannot be enabled if a group, subgroup, or project is shared externally. If a group, subgroup, +or project is shared externally, it is shared outside of the namespace hierarchy, regardless of its level +in the hierarchy. + +To ensure that the user cap applies when groups, subgroups, or projects are shared externally, restrict group sharing only within the top-level namespace. This ensure that groups in the same top-leve namespace can be invited, and prevents the addition of new users (seats) when the group is shared. + +User cap doesn’t consider whether users are billable or not (e.g., Free Guest Users in Ultimate). In other words, if you set a cap of 500, user caps block new sign-ups after 500 users, regardless of whether those are all consuming paid seats or not. + +## Group file templates **(PREMIUM ALL)** Use group file templates to share a set of templates for common file types with every project in a group. It is analogous to the @@ -323,7 +332,7 @@ To learn how to create templates for issues and merge requests, see Define project templates at a group level by setting a group as the template source. For more information, see [group-level project templates](custom_project_templates.md). -### Enable group file template **(PREMIUM)** +### Enable group file template **(PREMIUM ALL)** To enable group file templates: @@ -333,7 +342,7 @@ To enable group file templates: 1. Choose a project to act as the template repository. 1. Select **Save changes**. -## Group merge checks settings **(PREMIUM)** +## Group merge checks settings **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372040) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) name `support_group_level_merge_checks_setting`. Disabled by default. @@ -404,7 +413,7 @@ To enable this setting: 1. Under **Merge checks**, select **All threads must be resolved**. 1. Select **Save changes**. -## Group merge request approval settings **(PREMIUM)** +## Group merge request approval settings **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285458) in GitLab 13.9. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.5. @@ -493,7 +502,10 @@ To disable third-party AI features for a group: 1. Under **Third-party AI services**, uncheck the **Use third-party AI services** checkbox. 1. Select **Save changes**. -## Group activity analytics **(PREMIUM)** +When Code Suggestions are enabled and disabled, an +[audit event](../../administration/audit_events.md#view-audit-events) is created. + +## Group activity analytics **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab 12.10 as a [Beta feature](../../policy/experiment-beta-support.md#beta). diff --git a/doc/user/group/moderate_users.md b/doc/user/group/moderate_users.md index 85fdeeb25c7..7e67bb6ddb5 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)** +# Moderate users **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/155) in GitLab 15.8. diff --git a/doc/user/group/planning_hierarchy/index.md b/doc/user/group/planning_hierarchy/index.md index f48a027ab2d..17552ceaf88 100644 --- a/doc/user/group/planning_hierarchy/index.md +++ b/doc/user/group/planning_hierarchy/index.md @@ -5,7 +5,7 @@ group: Product Planning 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 --- -# Planning hierarchies **(PREMIUM)** +# Planning hierarchies **(PREMIUM ALL)** Planning hierarchies are an integral part of breaking down your work in GitLab. To understand how you can use epics and issues together in hierarchies, remember the following: @@ -31,7 +31,7 @@ graph TD Group_epic --> Project2_Issue1 ``` -### Hierarchies with multi-level epics **(ULTIMATE)** +### Hierarchies with multi-level epics **(ULTIMATE ALL)** With the addition of [multi-level epics](../epics/manage_epics.md#multi-level-child-epics) and up to seven levels of nested epics, you can achieve the following hierarchy: diff --git a/doc/user/group/reporting/git_abuse_rate_limit.md b/doc/user/group/reporting/git_abuse_rate_limit.md index cde19531ed3..abb967ad8b1 100644 --- a/doc/user/group/reporting/git_abuse_rate_limit.md +++ b/doc/user/group/reporting/git_abuse_rate_limit.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 --- -# Git abuse rate limit **(ULTIMATE)** +# Git abuse rate limit **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8066) in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. Disabled by default. diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index 6f5f4905102..3e7bacbb817 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Repositories analytics for groups **(PREMIUM)** +# Repositories analytics for groups **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in GitLab 13.4. diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 9e0ff22eafa..89d461127e7 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Roadmap **(PREMIUM)** +# Roadmap **(PREMIUM ALL)** > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/198062) from GitLab Ultimate to GitLab Premium in 12.9. > - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/5164) and later, the epic bars show epics' title, progress, and completed weight percentage. @@ -150,7 +150,7 @@ the timeline header represent the days of the week. The timeline bar indicates the approximate position of an epic or milestone based on its start and due dates. -## Blocked epics **(ULTIMATE)** +## Blocked epics **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33587) in GitLab 15.5: View blocking epics when hovering over the "blocked" icon. diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md index f6eb4ad539c..c5f84510c57 100644 --- a/doc/user/group/saml_sso/example_saml_config.md +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -41,6 +41,9 @@ This section has screenshots for the elements of Azure Active Directory configur  +NOTE: +Attribute names starting with phrases such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/` are not supported. + ### SCIM mapping Provisioning: diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index dd455944bf8..c3edc01fe74 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.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 --- -# SAML Group Sync **(PREMIUM)** +# SAML Group Sync **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363084) for self-managed instances in GitLab 15.1. @@ -24,10 +24,6 @@ For a demo of Group Sync using Azure, see [Demo: SAML Group Sync](https://youtu. NOTE: You must include the SAML configuration block on all Sidekiq nodes in addition to Rails application nodes if you use SAML Group Sync and have multiple GitLab nodes, for example in a distributed or highly available architecture. -NOTE: -SAML Group Sync is only supported for the [SAML provider named `saml`](../../../integration/saml.md#configure-gitlab-to-use-multiple-saml-idps). -As a result, SAML Group Sync only supports a single SAML provider. For more information, see [issue 386605](https://gitlab.com/gitlab-org/gitlab/-/issues/386605). - WARNING: To prevent users being accidentally removed from the GitLab group, follow these instructions closely before enabling Group Sync in GitLab. @@ -73,9 +69,9 @@ For example, Azure AD sends the Azure Group Object ID instead of the name. Use t ``` Other attribute names such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` -are not accepted as a source of groups. -See [examples](../../../user/group/saml_sso/example_saml_config.md) -for configuring the required attribute name in the SAML identity provider's settings. +are not accepted as a source of groups. For more information on configuring the +required attribute name in the SAML identity provider's settings, see +[example group SAML and SCIM configurations](../../../user/group/saml_sso/example_saml_config.md). ## Configure SAML Group Links @@ -106,7 +102,83 @@ Users granted: SAML group membership is evaluated each time a user signs in. -### Global SAML group memberships lock **(PREMIUM SELF)** +### Use the API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3. + +You can use the GitLab API to [list, add, and delete](../../../api/groups.md#saml-group-links) SAML group links. + +## Microsoft Azure Active Directory integration + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10507) in GitLab 16.3. + +NOTE: +Microsoft has [announced](https://azure.microsoft.com/en-us/updates/azure-ad-is-becoming-microsoft-entra-id/) that Azure Active Directory (AD) is being renamed to Entra ID. + +Azure AD sends up to 150 groups in the groups claim. When users are members of more than 150 groups Azure AD sends a +group overage claim attribute in the SAML response. Then group memberships must be obtained using the Microsoft Graph API. + +To integrate Microsoft Azure AD, you: + +- Configure Azure AD to enable GitLab to communicate with the Microsoft Graph API. +- Configure GitLab. + +### GitLab settings to Azure AD fields + +| GitLab setting | Azure field | +| ============== | ========================================== | +| Tenant ID | Directory (tenant) ID | +| Client ID | Application (client) ID | +| Client Secret | Value (on **Certificates & secrets** page) | + +### Configure Azure AD + +<!-- vale gitlab.SentenceSpacing = NO --> + +1. In the [Azure Portal](https://portal.azure.com), go to **Azure Active Directory > App registrations > All applications**, and select your GitLab SAML application. +1. Under **Essentials**, the **Application (client) ID** and **Directory (tenant) ID** values are displayed. Copy these values, because you need them for the GitLab configuration. +1. In the left navigation, select **Certificates & secrets**. +1. On the **Client secrets** tab, select **New client secret**. + 1. In the **Description** text box, add a description. + 1. In the **Expires** dropdown list, set the expiration date for the credentials. If the secret expires, the GitLab integration will no longer work until the credentials are updated. + 1. To generate the credentials, select **Add**. + 1. Copy the **Value** of the credential. This value is displayed only once, and you need it for the GitLab configuration. +1. In the left navigation, select **API permissions**. +1. Select **Microsoft Graph > Application permissions**. +1. Select the checkboxes **GroupMember.Read.All** and **User.Read.All**. +1. Select **Add permissions** to save. +1. Select **Grant admin consent for `<application_name>`**, then on the confirmation dialog select **Yes**. The **Status** column for both permissions should change to a green check with **Granted for `<application_name>`**. + +<!-- vale gitlab.SentenceSpacing = YES --> + +### Configure GitLab + +To configure for a GitLab.com group: + +1. Configure [SAML SSO for the group](../../../user/group/saml_sso/index.md). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your top-level group. +1. Select **Settings > SAML SSO**. +1. In the **Microsoft Azure integration** section, select the **Enable Microsoft Azure integration for this group** checkbox. +1. Enter the **Tenant ID**, **Client ID**, and **Client secret** obtained earlier when configuring Azure Active Directory in the Azure Portal. +1. Optional. If using Azure AD for US Government or Azure AD China, enter the appropriate **Login API endpoint** and **Graph API endpoint**. The default values work for most organizations. +1. Select **Save changes**. + +To configure for self-managed: + +1. Configure [SAML SSO for the instance](../../../integration/saml.md). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. +1. In the **Microsoft Azure integration** section, select the **Enable Microsoft Azure integration for this group** checkbox. +1. Enter the **Tenant ID**, **Client ID**, and **Client secret** obtained earlier when configuring Azure Active Directory in the Azure Portal. +1. Optional. If using Azure AD for US Government or Azure AD China, enter the appropriate **Login API endpoint** and **Graph API endpoint**. The default values work for most organizations. +1. Select **Save changes**. + +With this configuration, if a user signs in with SAML and Azure sends a group overage claim in the response, +GitLab initiates a Group Sync job to call the Microsoft Graph API and retrieve the user's group membership. +Then the GitLab Group membership is updated according to SAML Group Links. + +## Global SAML group memberships lock **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386390) in GitLab 15.10. @@ -131,7 +203,7 @@ To enable global group memberships lock: 1. Expand the **Visibility and access controls** section. 1. Ensure the **Lock memberships to SAML synchronization** checkbox is selected. -### Automatic member removal +## Automatic member removal After a group sync, users who are not members of a mapped SAML group are removed from the group. On GitLab.com, users in the top-level group are assigned the @@ -215,23 +287,17 @@ graph TB GitLabGroupD --> |Member|GitLabUserD ``` -#### User that belongs to many SAML groups automatically removed from GitLab group - -When using Azure AD as the SAML identity provider, users that belong to many SAML groups can be automatically removed from your GitLab group. Users are removed from GitLab -groups if the group claim is missing from the user's SAML assertion. +### User that belongs to many SAML groups automatically removed from GitLab group -Because of a [known issue with Azure AD](https://support.esri.com/en/technical-article/000022190), if a user belongs to more than 150 SAML groups, the group claim is not sent -in the user's SAML assertion. +When using Azure AD with SAML, if any user in your organization is a member of more than 150 groups and you use SAML Group Sync, +that user may lose their group memberships. +For more information, see +[Microsoft Group overages](https://learn.microsoft.com/en-us/security/zero-trust/develop/configure-tokens-group-claims-app-roles#group-overages). -With an Azure AD premium subscription, you can allow up to 500 group IDs to be sent in a SAML token using the -[Azure AD documentation configuration steps](https://support.esri.com/en/technical-article/000022190). +GitLab has a [Microsoft Azure Active Directory integration](#microsoft-azure-active-directory-integration) that enables SAML Group Sync for organizations +with users in more than 150 groups. This integration uses the Microsoft Graph API to obtain all user memberships and is +not limited to 150 groups. Otherwise, you can work around this issue by changing the [group claims](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/connect/how-to-connect-fed-group-claims#configure-the-azure-ad-application-registration-for-group-attributes) to use the `Groups assigned to the application` option instead. . - -### Use the API - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3. - -You can use the GitLab API to [list, add, and delete](../../../api/groups.md#saml-group-links) SAML group links. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 7795aed5fd0..41c2090f4bc 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -225,8 +225,7 @@ After you set up your identity provider to work with GitLab, you must configure 1. In the **Default membership role** field, select the role to assign to new users. The default role is **Guest**. In [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/214523) and later, group owners can set a default membership role other than **Guest**. - To do so, [configure the SAML SSO for the group](#configure-gitlab). That role - becomes the starting role of all users added to the group. + That role becomes the starting role of all users added to the group. 1. Select the **Enable SAML authentication for this group** checkbox. 1. Optional. Select: - **Enforce SSO-only authentication for web activity for this group**. @@ -265,6 +264,9 @@ You can pass user information to GitLab as attributes in the SAML assertion. For more information, see the [attributes available for self-managed GitLab instances](../../../integration/saml.md#configure-assertions). +NOTE: +Attribute names starting with phrases such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/` are not supported. For more information on configuring required attribute names in the SAML identity provider's settings, see [example group SAML and SCIM configurations](../../../user/group/saml_sso/example_saml_config.md). + ### Link SAML to your existing GitLab.com account > **Remember me** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/121569) in GitLab 15.7. diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md index 62c13e8909b..82703893834 100644 --- a/doc/user/group/saml_sso/troubleshooting.md +++ b/doc/user/group/saml_sso/troubleshooting.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 --- -# Troubleshooting SAML **(FREE)** +# Troubleshooting SAML **(FREE ALL)** This page contains possible solutions for problems you might encounter when using: diff --git a/doc/user/group/saml_sso/troubleshooting_scim.md b/doc/user/group/saml_sso/troubleshooting_scim.md index e4531882fc1..7d2aa8faa99 100644 --- a/doc/user/group/saml_sso/troubleshooting_scim.md +++ b/doc/user/group/saml_sso/troubleshooting_scim.md @@ -40,41 +40,43 @@ To check if a user's SAML `NameId` matches their SCIM `externalId`: - Administrators can use the Admin Area to [list SCIM identities for a user](../../../administration/admin_area.md#user-identities). - Group owners can see the list of users and the identifier stored for each user in the group SAML SSO Settings page. -- You can use the [SCIM API](../../../api/scim.md) to manually retrieve the `external_uid` GitLab has stored for users and compare the value for each user from the [SAML API](../../../api/saml.md) . -- Have the user use a [SAML Tracer](troubleshooting.md#saml-debugging-tools) and compare the `external_uid` to +- You can use the [SCIM API](../../../api/scim.md) to manually retrieve the `extern_uid` GitLab has stored for users and compare the value for each user from the [SAML API](../../../api/saml.md) . +- Have the user use a [SAML Tracer](troubleshooting.md#saml-debugging-tools) and compare the `extern_uid` to the value returned as the SAML `NameId`. ## Mismatched SCIM `extern_uid` and SAML `NameId` Whether the value was changed or you need to map to a different field, the following must map to the same field: -- `id` - `externalId` - `NameId` -If the GitLab `extern_uid` doesn't match the SAML `NameId`, it must be updated for the user to sign in. Your identity -provider should be configured to do this update. In some cases the identity provider cannot do the update, for example -when a user lookup fails because of an ID change. +If the GitLab `extern_uid` does not match the SAML `NameId`, you must update the GitLab `extern_uid` to enable the user to sign in. -Be cautious if you revise the fields used by your SCIM identity provider, typically `id` and `externalId`. -GitLab uses these IDs to look up users. If the identity provider does not know the current values for these fields, -that provider may create duplicate users. +Be cautious if you revise the fields used by your SCIM identity provider, typically `externalId`. +Your identity provider should be configured to do this update. +In some cases the identity provider cannot do the update, for example when a user lookup fails. -If the `extern_uid` for a user is not correct, and also doesn't match the SAML `NameID`, either: +GitLab uses these IDs to look up users. +If the identity provider does not know the current values for these fields, +that provider may create duplicate users, or fail to complete expected actions. -- Have users unlink and relink themselves, based on the +To change the identifier values to match: + +1. Have users unlink and relink themselves, based on the [SAML authentication failed: User has already been taken](troubleshooting.md#message-saml-authentication-failed-user-has-already-been-taken) section. -- Unlink all users simultaneously by removing all users from the SCIM app while provisioning is turned on. -- Use the [SCIM API](../../../api/scim.md) to manually correct the `extern_uid` stored for users to match the SAML - `NameId`. To look up a user, you must know the desired value that matches the `NameId` as well as the current - `extern_uid`. +1. Unlink all users simultaneously by removing all users from the SCIM app while provisioning is turned on. +1. Use the [SAML API](../../../api/saml.md) or [SCIM API](../../../api/scim.md) to manually correct the `extern_uid` stored for users to match the SAML + `NameId` or SCIM `externalId`. You must not: - Update these to incorrect values because this causes users to be unable to sign in. - Assign a value to the wrong user because this causes users to be signed in to the wrong account. +Additionally, the user's primary email must match the email in your SCIM identity provider. + ## Change SCIM app When the SCIM app changes: diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 84902a5cbe9..4fb8b293334 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -4,7 +4,7 @@ group: Tenant Scale 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 --- -# Subgroups **(FREE)** +# Subgroups **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2772) in GitLab 9.0. diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index dba7a507fef..1e042ab1924 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -5,7 +5,7 @@ group: Optimize 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 --- -# Value stream analytics **(FREE)** +# Value stream analytics **(FREE ALL)** Value stream analytics measures the time it takes to go from an idea to production. @@ -100,7 +100,7 @@ These events play a key role in the duration calculation, which is calculated by To learn what start and end events can be paired, see [Validating start and end events](../../../development/value_stream_analytics.md#validating-start-and-end-events). -### How value stream analytics aggregates data **(PREMIUM)** +### How value stream analytics aggregates data **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335391) in GitLab 14.5. > - Filter by stop date toggle [added](https://gitlab.com/gitlab-org/gitlab/-/issues/352428) in GitLab 14.9 @@ -143,6 +143,9 @@ Each pre-defined stages of value stream analytics is further described in the ta | Review | The median time taken to review a merge request that has a closing issue pattern, between its creation and until it's merged. | | Staging | The median time between merging a merge request that has a closing issue pattern until the very first deployment to a [production environment](#how-value-stream-analytics-identifies-the-production-environment). If there isn't a production environment, this is not tracked. | +NOTE: +Value stream analytics works on timestamp data and aggregates only the final start and stop events of the stage. For items that move back and forth between stages multiple times, the stage time is calculated solely from the final events' timestamps. + For information about how value stream analytics calculates each stage, see the [Value stream analytics development guide](../../../development/value_stream_analytics.md). #### Example workflow @@ -264,7 +267,7 @@ Value stream analytics includes the following lifecycle metrics: - **New issues**: Number of new issues created. - **Deploys**: Total number of deployments to production. -### DORA metrics **(ULTIMATE)** +### DORA metrics **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) lead time for changes DORA metric in GitLab 14.5. > - DORA API-based deployment metrics for value stream analytics for groups were [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) from GitLab Ultimate to GitLab Premium in GitLab 14.3. @@ -343,7 +346,7 @@ NOTE: The date range selector filters items by the event time. The event time is when the selected stage finished for the given item. -## View tasks by type **(PREMIUM)** +## View tasks by type **(PREMIUM ALL)** The **Tasks by type** chart displays the cumulative number of issues and merge requests per day for your group. @@ -360,7 +363,7 @@ To view tasks by type: 1. To add or remove labels, select the **Settings** (**{settings}**) dropdown list and select or search for a label. By default the top group-level labels (maximum 10) are selected. You can select a maximum of 15 labels. -## Create a value stream **(PREMIUM)** +## Create a value stream **(PREMIUM ALL)** ### Create a value stream with GitLab default stages @@ -421,7 +424,7 @@ In the example above, two independent value streams are set up for two teams tha The first value stream uses standard timestamp-based events for defining the stages. The second value stream uses label events. -## Edit a value stream **(PREMIUM)** +## Edit a value stream **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267537) in GitLab 13.10. @@ -440,7 +443,7 @@ After you create a value stream, you can customize it to suit your purposes. To 1. Optional. To undo any modifications, select **Restore value stream defaults**. 1. Select **Save Value Stream**. -## Delete a value stream **(PREMIUM)** +## Delete a value stream **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221205) in GitLab 13.4. @@ -453,7 +456,7 @@ To delete a custom value stream:  -## View number of days for a cycle to complete **(PREMIUM)** +## View number of days for a cycle to complete **(PREMIUM ALL)** > - Chart median line [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235455) in GitLab 13.4. > - Totals [replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/262070) with averages in GitLab 13.12. diff --git a/doc/user/img/explain_this_vulnerability.png b/doc/user/img/explain_this_vulnerability.png Binary files differdeleted file mode 100644 index bb938241911..00000000000 --- a/doc/user/img/explain_this_vulnerability.png +++ /dev/null diff --git a/doc/user/index.md b/doc/user/index.md index 8d761c88484..490a946a077 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Use GitLab **(FREE)** +# Use GitLab **(FREE ALL)** Get to know the GitLab end-to-end workflow. Configure permissions, organize your work, create and secure your application, and analyze its performance. Report on team productivity throughout the process. diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index 01911f2b889..5010c2e92a3 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Connect a cluster to GitLab **(FREE)** +# Connect a cluster to GitLab **(FREE ALL)** The [certificate-based Kubernetes integration with GitLab](../index.md) was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) diff --git a/doc/user/infrastructure/clusters/deploy/inventory_object.md b/doc/user/infrastructure/clusters/deploy/inventory_object.md index 4c55a87a52c..cd81f6a1f86 100644 --- a/doc/user/infrastructure/clusters/deploy/inventory_object.md +++ b/doc/user/infrastructure/clusters/deploy/inventory_object.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Tracking cluster resources managed by GitLab (deprecated) **(FREE)** +# Tracking cluster resources managed by GitLab (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/346567) from GitLab Premium to GitLab Free in 15.3. diff --git a/doc/user/infrastructure/clusters/index.md b/doc/user/infrastructure/clusters/index.md index d0419e08f95..ad587154021 100644 --- a/doc/user/infrastructure/clusters/index.md +++ b/doc/user/infrastructure/clusters/index.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Kubernetes clusters **(FREE)** +# Kubernetes clusters **(FREE ALL)** To connect clusters to GitLab, use the [GitLab agent](../../clusters/agent/index.md). diff --git a/doc/user/infrastructure/clusters/manage/clusters_health.md b/doc/user/infrastructure/clusters/manage/clusters_health.md index d9b849ffccc..cf1b5585a0c 100644 --- a/doc/user/infrastructure/clusters/manage/clusters_health.md +++ b/doc/user/infrastructure/clusters/manage/clusters_health.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../index.md' --- -# Clusters health (removed) **(FREE)** +# Clusters health (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md index f07b70dd8e0..2408e16160b 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Install cert-manager with a cluster management project **(FREE)** +# Install cert-manager with a cluster management project **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. > - Support for cert-manager v1.4 was [introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/69405) in GitLab 14.3. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md index 1d56e7c1ba1..ee9b2f848fe 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Install Ingress with a cluster management project **(FREE)** +# Install Ingress with a cluster management project **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md index e23f5e8745c..cbc23402915 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md @@ -4,7 +4,7 @@ group: Runner 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 --- -# Install GitLab Runner with a cluster management project **(FREE)** +# Install GitLab Runner with a cluster management project **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md index bbf8391e8a0..193e3b70fba 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Install Vault with a cluster management project **(FREE)** +# Install Vault with a cluster management project **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md index 614e0f5a7e5..1e1372bb035 100644 --- a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md +++ b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Migrate to the GitLab agent for Kubernetes **(FREE)** +# Migrate to the GitLab agent for Kubernetes **(FREE ALL)** To connect your Kubernetes cluster with GitLab, you can use: diff --git a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md index d5376bfbcb1..2161c2ba191 100644 --- a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md +++ b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# GitLab Terraform helpers **(FREE)** +# GitLab Terraform helpers **(FREE ALL)** GitLab provides two helpers to ease your integration with the [GitLab-managed Terraform State](terraform_state.md). diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index f27f1306c31..26b4b66ac63 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Infrastructure as Code with Terraform and GitLab **(FREE)** +# Infrastructure as Code with Terraform and GitLab **(FREE ALL)** To manage your infrastructure with GitLab, you can use the integration with Terraform to define resources that you can version, reuse, and share: diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md index 26bb1d16510..24ae3c998f8 100644 --- a/doc/user/infrastructure/iac/mr_integration.md +++ b/doc/user/infrastructure/iac/mr_integration.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Terraform integration in merge requests **(FREE)** +# Terraform integration in merge requests **(FREE ALL)** 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. diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index 31c4ad757c8..4a8f2f11e58 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# GitLab-managed Terraform state **(FREE)** +# GitLab-managed Terraform state **(FREE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. > - Support for state names that contain periods introduced in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `allow_dots_on_tf_state_names`. Disabled by default. diff --git a/doc/user/infrastructure/iac/terraform_template_recipes.md b/doc/user/infrastructure/iac/terraform_template_recipes.md index 0011e7c9242..404e48d61bf 100644 --- a/doc/user/infrastructure/iac/terraform_template_recipes.md +++ b/doc/user/infrastructure/iac/terraform_template_recipes.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Terraform template recipes **(FREE)** +# Terraform template recipes **(FREE ALL)** You can customize your Terraform integration by adding the recipes on this page to your pipeline. diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index d60f20a3713..54f062884ee 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Infrastructure management **(FREE)** +# Infrastructure management **(FREE ALL)** With the rise of DevOps and SRE approaches, infrastructure management becomes codified, automatable, and software development best practices gain their place around infrastructure diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 51a4499d716..15a3703adbf 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -36,7 +36,7 @@ GitLab tries to match clusters in the following order: To be selected, the cluster must be enabled and match the [environment selector](../../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable). -## Cluster environments **(PREMIUM)** +## Cluster environments **(PREMIUM ALL)** For a consolidated view of which CI [environments](../../../ci/environments/index.md) are deployed to the Kubernetes cluster, see the documentation for diff --git a/doc/user/markdown.md b/doc/user/markdown.md index c3e4f77411c..c724ae465b8 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.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/product/ux/technical-writing/#assignments --- -# GitLab Flavored Markdown (GLFM) **(FREE)** +# GitLab Flavored Markdown (GLFM) **(FREE ALL)** > The abbreviation [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/24592) from `GFM` to `GLFM` in GitLab 14.10. @@ -215,8 +215,6 @@ For more information, see the [Kroki integration](../administration/integration/ :::TabTitle Rendered Markdown -<!-- vale gitlab.Markdown_emoji = NO --> - Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/monkey.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":monkey:" alt=":monkey:"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/star2.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":star2:" alt=":star2:"> to your <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":speech_balloon:" alt=":speech_balloon:">. Well we have a gift for you: <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/zap.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":zap:" alt=":zap:">You can use emoji anywhere GitLab Flavored Markdown is supported. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/v.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":v:" alt=":v:"> @@ -227,8 +225,6 @@ If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-f Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":thumbsup:" alt=":thumbsup:"> -<!-- vale gitlab.Markdown_emoji = YES --> - :::TabTitle Code ```markdown @@ -691,6 +687,10 @@ For example, a reference like `#123+s` is rendered as URL references like `https://gitlab.com/gitlab-org/gitlab/-/issues/1234+s` are also expanded. +To update the rendered references if the assignee, milestone, or health status changed, +edit the comment or description and save it. +For more information, see issue [420807](https://gitlab.com/gitlab-org/gitlab/-/issues/420807). + ### Embedding metrics Metric charts can be embedded in GitLab Flavored Markdown. Read diff --git a/doc/user/okrs.md b/doc/user/okrs.md index 6579ecbadbc..f9c242e7c2a 100644 --- a/doc/user/okrs.md +++ b/doc/user/okrs.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Objectives and key results (OKR) **(ULTIMATE)** +# Objectives and key results (OKR) **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103355) in GitLab 15.6 [with a flag](../administration/feature_flags.md) named `okrs_mvc`. Disabled by default. @@ -354,6 +354,80 @@ Prerequisites: By default, child OKRs are ordered by creation date. To reorder them, drag them around. +## Confidential OKRs + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8410) in GitLab 15.3. + +Confidential OKRs are OKRs visible only to members of a project with +[sufficient permissions](#who-can-see-confidential-okrs). +You can use confidential OKRs to keep security vulnerabilities private or prevent surprises from +leaking out. + +### Make an OKR confidential + +By default, OKRs are public. +You can make an OKR confidential when you create or edit it. + +Prerequisites: + +- You must have at least the Reporter role for the project. +- A **confidential objective** can have only confidential + [child objectives or key results](#child-objectives-and-key-results): + - To make an objective confidential: If it has any child objectives or key results, you must first + make all of them confidential or remove them. + - To make an objective non-confidential: If it has any child objectives or key results, you must + first make all of them non-confidential or remove them. + - To add child objectives or key results to a confidential objective, you must first make them + confidential. + +#### In a new OKR + +When you create a new objective, a checkbox right below the text area is available to mark the +OKR as confidential. + +Check that box and select **Create objective** or **Create key result** to create the OKR. + +#### In an existing OKR + +To change the confidentiality of an existing OKR: + +1. [Open the objective](#view-an-objective) or [key result](#view-a-key-result). +1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **Turn on confidentiality**. + +### Who can see confidential OKRs + +When an OKR is made confidential, only users with at least the Reporter role for the project have +access to the OKR. +Users with Guest or [Minimal](permissions.md#users-with-minimal-access) roles can't access +the OKR even if they were actively participating before the change. + +However, a user with the **Guest role** can create confidential OKRs, but can only view the ones +that they created themselves. + +Users with the Guest role or non-members can read the confidential OKR if they are assigned to the OKR. +When a Guest user or non-member is unassigned from a confidential OKR, they can no longer view it. + +Confidential OKRs are hidden in search results for users without the necessary permissions. + +### Confidential OKR indicators + +Confidential OKRs are visually different from regular OKRs in a few ways. +Wherever OKRs are listed, you can see the confidential (**{eye-slash}**) icon +next to the OKRs that are marked as confidential. + +If you don't have [enough permissions](#who-can-see-confidential-okrs), +you cannot see confidential OKRs at all. + +Likewise, while inside the OKR, you can see the confidential (**{eye-slash}**) icon right next to +the breadcrumbs. + +Every change from regular to confidential and vice versa, is indicated by a +system note in the OKR's comments, for example: + +> - **{eye-slash}** Jo Garcia made the issue confidential 5 minutes ago +> - **{eye}** Jo Garcia made the issue visible to everyone just now + ## Two-column layout > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415077) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 3239467ceb6..3f86e945492 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Operations Dashboard **(PREMIUM)** +# Operations Dashboard **(PREMIUM ALL)** The Operations Dashboard provides a summary of each project's operational health, including pipeline and alert status. diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 3f8b0761188..0fcc44e8780 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Composer packages in the Package Registry **(FREE)** +# Composer packages in the Package Registry **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in GitLab 13.2. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. @@ -38,7 +38,7 @@ Prerequisites: 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. -- A valid `composer.json` file. +- A valid `composer.json` file at the project root directory. - The Packages feature is enabled in a GitLab repository. - The project ID, which is on the project's home page. - One of the following token types: @@ -324,6 +324,14 @@ If you committed your `composer.lock`, you could do a `composer install` in CI w In GitLab 14.10 and later, authorization is required for the [downloading a package archive](../../../api/packages/composer.md#download-a-package-archive) endpoint. If you encounter a credentials prompt when you are using `composer install`, follow the instructions in the [install a composer package](#install-a-composer-package) section to create an `auth.json` file. +### Publish fails with `The file composer.json was not found` + +You might see an error that says `The file composer.json was not found`. + +This issue occurs when [configuration requirements for publishing a package](#publish-a-composer-package-by-using-the-api) are not met. + +To resolve the error, commit a `composer.json` file to the project root directory. + ## Supported CLI commands The GitLab Composer repository supports the following Composer CLI commands: diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 1ebd59d18fa..72c5a1980b5 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Conan packages in the Package Registry **(FREE)** +# Conan packages in the Package Registry **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in GitLab 12.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. diff --git a/doc/user/packages/container_registry/authenticate_with_container_registry.md b/doc/user/packages/container_registry/authenticate_with_container_registry.md index 6a7c92fd924..2aab69877ff 100644 --- a/doc/user/packages/container_registry/authenticate_with_container_registry.md +++ b/doc/user/packages/container_registry/authenticate_with_container_registry.md @@ -4,7 +4,7 @@ group: Container Registry 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 --- -# Authenticate with the Container Registry **(FREE)** +# Authenticate with the Container Registry **(FREE ALL)** <!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> WARNING: diff --git a/doc/user/packages/container_registry/build_and_push_images.md b/doc/user/packages/container_registry/build_and_push_images.md index 4d74e029cdd..93140e34493 100644 --- a/doc/user/packages/container_registry/build_and_push_images.md +++ b/doc/user/packages/container_registry/build_and_push_images.md @@ -4,7 +4,7 @@ group: Container Registry 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 --- -# Build and push container images to the Container Registry **(FREE)** +# Build and push container images to the Container Registry **(FREE ALL)** Before you can build and push container images, you must [authenticate](authenticate_with_container_registry.md) with the Container Registry. diff --git a/doc/user/packages/container_registry/delete_container_registry_images.md b/doc/user/packages/container_registry/delete_container_registry_images.md index 148fa65d8c7..88a318d0770 100644 --- a/doc/user/packages/container_registry/delete_container_registry_images.md +++ b/doc/user/packages/container_registry/delete_container_registry_images.md @@ -4,7 +4,7 @@ group: Container Registry 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 --- -# Delete container images from the Container Registry **(FREE)** +# Delete container images from the Container Registry **(FREE ALL)** You can delete container images from your Container Registry. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index f9b1138ed84..3ec5ddb235e 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -4,7 +4,7 @@ group: Container Registry 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 --- -# GitLab Container Registry **(FREE)** +# GitLab Container Registry **(FREE ALL)** > Searching by image repository name was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31322) in GitLab 13.0. diff --git a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md index 110f3ff908c..9ac00445b95 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md +++ b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md @@ -4,7 +4,7 @@ group: Container Registry 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 --- -# Reduce Container Registry data transfers **(FREE)** +# Reduce Container Registry data transfers **(FREE ALL)** Depending on the frequency with which images or tags are downloaded from the Container Registry, data transfers can exceed the GitLab.com limit. This page offers several recommendations and tips for diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md index e3ca78becf1..fd781847855 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -4,7 +4,7 @@ group: Container Registry 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 --- -# Reduce Container Registry storage **(FREE)** +# Reduce Container Registry storage **(FREE ALL)** Container registries can grow in size over time if you don't manage your registry usage. For example, if you add a large number of images or tags: diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 220e2085637..b7fbeb96202 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Debian packages in the Package Registry **(FREE)** +# Debian packages in the Package Registry **(FREE ALL)** > - Debian API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42670) in GitLab 13.5. > - Debian group API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66188) in GitLab 14.2. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index ebe87332948..11b67e5cda3 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -4,7 +4,7 @@ group: Container Registry 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 --- -# Dependency Proxy **(FREE)** +# Dependency Proxy **(FREE ALL)** > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) from GitLab Premium to GitLab Free in 13.6. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) support for private groups in GitLab 13.7. @@ -69,6 +69,7 @@ Prerequisites: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in GitLab 13.7 [with a flag](../../../administration/feature_flags.md) named `dependency_proxy_for_private_groups`. Enabled by default. > - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/276777) the feature flag `dependency_proxy_for_private_groups` in GitLab 15.0. +> - Support for group access tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362991) in GitLab 16.3. Because the Dependency Proxy is storing Docker images in a space associated with your group, you must authenticate against the Dependency Proxy. @@ -87,6 +88,7 @@ You can authenticate using: - Your GitLab username and password. - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `read_registry` and `write_registry`. - A [group deploy token](../../../user/project/deploy_tokens/index.md) with the scope set to `read_registry` and `write_registry`. +- A [group access token](../../../user/group/settings/group_access_tokens.md) for the group, with the scope set to `read_registry` and `write_registry`. Users accessing the Dependency Proxy with a personal access token or username and password must have at least the Guest role for the group they pull images from. diff --git a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md index 4c625499d07..e24a3d3fa84 100644 --- a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md +++ b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md @@ -4,7 +4,7 @@ group: Container Registry 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 --- -# Reduce Dependency Proxy Storage **(FREE)** +# Reduce Dependency Proxy Storage **(FREE ALL)** There's no automatic removal process for blobs. Unless you delete them manually, they're stored indefinitely. Since this impacts your diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index d24808674dc..e309ab002c4 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# GitLab Generic Packages Repository **(FREE)** +# GitLab Generic Packages Repository **(FREE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4209) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `generic_packages`. Enabled by default. > - [Feature flag `generic_packages`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80886) removed in GitLab 14.8. @@ -111,7 +111,9 @@ Example response with attribute `select = package_file`: ### Publishing a package with the same name or version When you publish a package with the same name and version as an existing package, the new package -files are added to the existing package. You can still use the UI or API to access and view the +files are added to the existing package. When you install a generic package that has a duplicate, GitLab downloads the latest version. + +You can use the UI or API to access and view the existing package's older files. To delete these older package revisions, consider using the Packages API or the UI. @@ -125,11 +127,10 @@ or the UI. In the UI: -1. For your group, go to **Settings > Packages and registries**. -1. Expand the **Package Registry** section. -1. Turn on the **Reject duplicates** toggle. -1. Optional. To allow some duplicate packages, in the **Exceptions** box enter a regex pattern that - matches the names and/or versions of packages to allow. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > Packages and registries**. +1. In the **Generic** row of the **Duplicate packages** table, turn off the **Allow duplicates** toggle. +1. Optional. In the **Exceptions** text box, enter a regular expression that matches the names and versions of packages to allow. Your changes are automatically saved. diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index f0e10d73d08..52f98ecf4dc 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Go proxy for GitLab **(FREE)** +# Go proxy for GitLab **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in GitLab 13.1. > - It's deployed behind a feature flag, disabled by default. diff --git a/doc/user/packages/gradle_repository/index.md b/doc/user/packages/gradle_repository/index.md deleted file mode 100644 index 456acc0da59..00000000000 --- a/doc/user/packages/gradle_repository/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../maven_repository/index.md' -remove_date: '2023-08-09' ---- - -This document was moved to [another location](../maven_repository/index.md). - -<!-- This redirect file can be deleted after <2023-08-09>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/packages/harbor_container_registry/index.md b/doc/user/packages/harbor_container_registry/index.md index 21468b9d3bb..0cdaaf8ece0 100644 --- a/doc/user/packages/harbor_container_registry/index.md +++ b/doc/user/packages/harbor_container_registry/index.md @@ -4,7 +4,7 @@ group: Container Registry 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 --- -# Harbor Registry **(FREE)** +# Harbor Registry **(FREE ALL)** You can integrate the [Harbor container registry](../../../user/project/integrations/harbor.md) into GitLab and use Harbor as the container registry for your GitLab project to store images. @@ -68,7 +68,7 @@ To remove the Harbor Registry for a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. 1. Select **Settings > Integrations**. 1. Select **Harbor** under **Active integrations**. -1. Clear the **Active** checkbox under **Enable integration**. +1. Under **Enable integration**, clear the **Active** checkbox. 1. Select **Save changes**. The **Operate > Harbor Registry** entry is removed from the sidebar. diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index 58c8e17f48b..57aee4fb4ca 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Helm charts in the Package Registry **(FREE)** +# Helm charts in the Package Registry **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18997) in GitLab 14.1. diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 2084de58bdb..8173a0407f0 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Packages and Registries **(FREE)** +# Packages and Registries **(FREE ALL)** The GitLab [Package Registry](package_registry/index.md) acts as a private or public registry for a variety of common package managers. You can publish and share diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index f06db7ef1ac..51755eda7bb 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Maven packages in the Package Registry **(FREE)** +# Maven packages in the Package Registry **(FREE ALL)** Publish [Maven](https://maven.apache.org) artifacts in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -480,10 +480,10 @@ To prevent users from publishing duplicate Maven packages, you can use the [Grap In the UI: -1. For your group, go to **Settings > Packages and registries**. -1. Expand the **Package Registry** section. -1. Turn on the **Do not allow duplicates** toggle. -1. Optional. To allow some duplicate packages, in the **Exceptions** box, enter a regex pattern that matches the names and/or versions of packages you want to allow. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > Packages and registries**. +1. In the **Maven** row of the **Duplicate packages** table, turn off the **Allow duplicates** toggle. +1. Optional. In the **Exceptions** text box, enter a regular expression that matches the names and versions of packages to allow. Your changes are automatically saved. diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 0fe2b39a591..695193f878a 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# npm packages in the Package Registry **(FREE)** +# npm packages in the Package Registry **(FREE ALL)** For documentation of the specific API endpoints that the npm package manager client uses, see the [npm API documentation](../../../api/packages/npm.md). @@ -29,12 +29,13 @@ Do not use authentication methods other than the methods documented here. Undocu Depending on how the package is installed, you may need to adhere to the naming convention. -You can use one of two API endpoints to install packages: +You can use one of three API endpoints to install packages: - **Instance-level**: Use when you have many npm packages in different GitLab groups or in their own namespace. +- **Group-level**: Use when you have many npm packages in different projects under the same group or subgroup. - **Project-level**: Use when you have few npm packages and they are not in the same GitLab group. -If you plan to install a package through the [project level](#install-from-the-project-level), then you do not have to adhere to the naming convention. +If you plan to install a package through the [project level](#install-from-the-project-level) or [group level](#install-from-the-group-level), then you do not have to adhere to the naming convention. If you plan to install a package through the [instance level](#install-from-the-instance-level), then you must name your package with a [scope](https://docs.npmjs.com/misc/scope/). Scoped packages begin with a `@` have the format of `@owner/package-name`. You can set up the scope for your package in the `.npmrc` file and by using the `publishConfig` option in the `package.json`. diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index ea9bfd7defb..74daf9fd891 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# NuGet packages in the Package Registry **(FREE)** +# NuGet packages in the Package Registry **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in GitLab 12.8. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. @@ -70,6 +70,7 @@ You can now add a new source to NuGet with: - [Visual Studio](#add-a-source-with-visual-studio) - [.NET CLI](#add-a-source-with-the-net-cli) - [Configuration file](#add-a-source-with-a-configuration-file) +- [Chocolatey CLI](#add-a-source-with-chocolatey-cli) ### Add a source with the NuGet CLI @@ -281,6 +282,22 @@ To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Re export GITLAB_PACKAGE_REGISTRY_PASSWORD=<gitlab_personal_access_token or deploy_token> ``` +### Add a source with Chocolatey CLI + +You can add a source feed with the Chocolatey CLI. If you use Chocolatey CLI v1.x, you can add only a NuGet v2 source feed. + +#### Configure a project-level endpoint + +You need a project-level endpoint to publish NuGet packages to the Package Registry. + +To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for Chocolatey: + +- Add the Package Registry as a source with `choco`: + + ```shell + choco source add -n=gitlab -s "'https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/v2'" -u=<gitlab_username or deploy_token_username> -p=<gitlab_personal_access_token or deploy_token> + ``` + ## Publish a NuGet package Prerequisite: @@ -385,6 +402,31 @@ updated: 1. Commit the changes and push it to your GitLab repository to trigger a new CI/CD build. +### Publish a NuGet package with Chocolatey CLI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416404) in GitLab 16.2. + +Prerequisite: + +- The project-level Package Registry is a source for Chocolatey. + +To publish a package with the Chocolatey CLI: + +```shell +choco push <package_file> --source <source_url> --api-key <gitlab_personal_access_token, deploy_token or job token> +``` + +In this command: + +- `<package_file>` is your package filename and ends with `.nupkg`. +- `<source_url>` is the URL of the NuGet v2 feed Package Registry. + +For example: + +```shell +choco push MyPackage.1.0.0.nupkg --source "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/v2" --api-key <gitlab_personal_access_token, deploy_token or job token> +``` + ### Publishing a package with the same name or version When you publish a package with the same name or version as an existing package, diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index d06b1ababb8..4d9ad03afde 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Package Registry **(FREE)** +# Package Registry **(FREE ALL)** > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. @@ -104,12 +104,14 @@ You can view which pipeline published the package, and the commit and user who t ### To import packages If you already have packages built in a different registry, you can import them -into your GitLab package registry with the [Packages Importer](https://gitlab.com/gitlab-org/ci-cd/package-stage/pkgs_importer) +into your GitLab package registry with the [Packages Importer](https://gitlab.com/gitlab-org/ci-cd/package-stage/pkgs_importer). The Packages Importer runs a CI/CD pipeline that [can import these package types](https://gitlab.com/gitlab-org/ci-cd/package-stage/pkgs_importer#formats-supported): +- Maven - NPM - NuGet +- PyPI ## Reduce storage usage @@ -157,13 +159,29 @@ Registry disables all Package Registry operations. ### Allow anyone to pull from Package Registry -> Introduced in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `package_registry_access_level`. Enabled by default. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385994) in GitLab 15.7. -FLAG: -On self-managed GitLab, by default this feature is available. To disable it, -an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `package_registry_access_level`. +To allow anyone to pull from the Package Registry, regardless of project visibility: -If you want to allow anyone (everyone on the internet) to pull from the Package Registry, no matter what the project visibility is, you can use the additional toggle `Allow anyone to pull from Package Registry` that appears when the project visibility is Private or Internal. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your private or internal project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Turn on the **Allow anyone to pull from Package Registry** toggle. +1. Select **Save changes**. + +Anyone on the internet can access the Package Registry for the project. + +#### Disable allowing anyone to pull + +Prerequisite: + +- You must be an administrator. + +To hide the **Allow anyone to pull from Package Registry** toggle globally: + +- [Change the application setting](../../../api/settings.md#change-application-settings) `package_registry_allow_anyone_to_pull_option` to `false`. + +Anonymous downloads are disabled, even for projects that turned on the **Allow anyone to pull from Package Registry** toggle. Several known issues exist when you allow anyone to pull from the Package Registry: diff --git a/doc/user/packages/package_registry/reduce_package_registry_storage.md b/doc/user/packages/package_registry/reduce_package_registry_storage.md index 4882753d6cf..e6251034cb2 100644 --- a/doc/user/packages/package_registry/reduce_package_registry_storage.md +++ b/doc/user/packages/package_registry/reduce_package_registry_storage.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Reduce Package Registry Storage **(FREE)** +# Reduce Package Registry Storage **(FREE ALL)** Without cleanup, package registries become large over time. When a large number of packages and their assets are added: diff --git a/doc/user/packages/package_registry/supported_functionality.md b/doc/user/packages/package_registry/supported_functionality.md index d2ee5645fc1..d3aa522f780 100644 --- a/doc/user/packages/package_registry/supported_functionality.md +++ b/doc/user/packages/package_registry/supported_functionality.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The GitLab Package Registry supports different functionalities for each package type. This support includes publishing and pulling packages, request forwarding, managing duplicates, and authentication. -## Publishing packages **(FREE)** +## Publishing packages **(FREE ALL)** Packages can be published to your project, group, or instance. @@ -30,7 +30,7 @@ Packages can be published to your project, group, or instance. | [Go](../go_proxy/index.md) | Y | N | N | | [Ruby gems](../rubygems_registry/index.md) | Y | N | N | -## Pulling packages **(FREE)** +## Pulling packages **(FREE ALL)** Packages can be pulled from your project, group, or instance. @@ -51,7 +51,7 @@ Packages can be pulled from your project, group, or instance. | [Go](../go_proxy/index.md) | Y | N | Y | | [Ruby gems](../rubygems_registry/index.md) | Y | N | N | -## Forwarding requests **(PREMIUM)** +## Forwarding requests **(PREMIUM ALL)** Requests for packages not found in your GitLab project are forwarded to the public registry. For example, Maven Central, npmjs, or PyPI. @@ -89,7 +89,7 @@ To reduce the associated security risks, before deleting a package you can: - Instance administrators can disable forwarding in the [**Continuous Integration** section](../../../administration/settings/continuous_integration.md#package-registry-configuration) of the Admin Area. - Group owners can disable forwarding in the **Packages and Registries** section of the group settings. -## Allow or prevent duplicates **(FREE)** +## Allow or prevent duplicates **(FREE ALL)** By default, the GitLab package registry either allows or prevents duplicates based on the default of that specific package manager format. @@ -110,7 +110,7 @@ By default, the GitLab package registry either allows or prevents duplicates bas | [Go](../go_proxy/index.md) | N | | [Ruby gems](../rubygems_registry/index.md) | Y | -## Authentication tokens **(FREE)** +## Authentication tokens **(FREE ALL)** GitLab tokens are used to authenticate with the GitLab Package Registry. @@ -133,7 +133,7 @@ The following tokens are supported: | [Go](../go_proxy/index.md) | Personal access, job tokens, project access | | [Ruby gems](../rubygems_registry/index.md) | Personal access, job tokens, deploy (project or group) | -## Authentication protocols **(FREE)** +## Authentication protocols **(FREE ALL)** The following authentication protocols are supported: @@ -156,7 +156,7 @@ The following authentication protocols are supported: 1. Basic authentication for Maven packages [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212854) in GitLab 16.0. -## Supported hash types **(FREE)** +## Supported hash types **(FREE ALL)** Hash values are used to ensure you are using the correct package. You can view these values in the user interface or with the [API](../../../api/packages.md). diff --git a/doc/user/packages/package_registry/supported_package_managers.md b/doc/user/packages/package_registry/supported_package_managers.md index 94e5af7cc04..8d31399a36b 100644 --- a/doc/user/packages/package_registry/supported_package_managers.md +++ b/doc/user/packages/package_registry/supported_package_managers.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Supported package managers **(FREE)** +# Supported package managers **(FREE ALL)** WARNING: Not all package manager formats are ready for production use. diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index d23966f26fe..c196e414461 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# PyPI packages in the Package Registry **(FREE)** +# PyPI packages in the Package Registry **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in GitLab 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index ae444880b6b..1c898ee6d92 100644 --- a/doc/user/packages/rubygems_registry/index.md +++ b/doc/user/packages/rubygems_registry/index.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Ruby gems in the Package Registry **(FREE)** +# Ruby gems in the Package Registry **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/803) in GitLab 13.10. diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 3a3409daa6a..cb0516bdc4a 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Terraform Module Registry **(FREE)** +# Terraform Module Registry **(FREE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. > - Infrastructure registry and Terraform Module Registry [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/404075) into a single Terraform Module Registry feature in GitLab 15.11. diff --git a/doc/user/packages/workflows/build_packages.md b/doc/user/packages/workflows/build_packages.md index eab1e4392e3..a0757e968bc 100644 --- a/doc/user/packages/workflows/build_packages.md +++ b/doc/user/packages/workflows/build_packages.md @@ -51,6 +51,10 @@ Learn how to install and build packages different package formats. ### Install Conan +Prerequisite: + +- You must install Conan version 1.x. Support for Conan version 2 is proposed in [epic 8258](https://gitlab.com/groups/gitlab-org/-/epics/8258). + Download the Conan package manager to your local development environment by following the instructions at [conan.io](https://conan.io/downloads.html). diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 1df244cf0c6..4db77348bd4 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Store all of your packages in one GitLab project **(FREE)** +# Store all of your packages in one GitLab project **(FREE ALL)** You can store all of your packages in one project's Package Registry. Rather than using a GitLab repository to store code, you can use the repository to store all your packages. diff --git a/doc/user/packages/workflows/working_with_monorepos.md b/doc/user/packages/workflows/working_with_monorepos.md index 572cd309e67..1383cd6df27 100644 --- a/doc/user/packages/workflows/working_with_monorepos.md +++ b/doc/user/packages/workflows/working_with_monorepos.md @@ -4,7 +4,7 @@ group: Package Registry 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 --- -# Monorepo package management workflows **(FREE)** +# Monorepo package management workflows **(FREE ALL)** One project or Git repository can contain multiple different subprojects or submodules that are all packaged and published individually. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index cf859174c10..d19f98b98ed 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -4,7 +4,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 --- -# Permissions and roles **(FREE)** +# Permissions and roles **(FREE ALL)** When you add a user to a project or group, you assign them a role. The role determines which actions they can take in GitLab. @@ -102,7 +102,7 @@ The following table lists project permissions available for each role: | [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [related issues](project/issues/related_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Set [weight](project/issues/issue_weight.md) | ✓ (15) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set [weight](project/issues/issue_weight.md) | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Set metadata such as labels, milestones, or assignees when creating an issue | ✓ (15) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Edit metadata such labels, milestones, or assignees for an existing issue | (15) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Set [parent epic](group/epics/manage_epics.md#add-an-existing-issue-to-an-epic) | | ✓ | ✓ | ✓ | ✓ | @@ -116,10 +116,10 @@ The following table lists project permissions available for each role: | [Issues](project/issues/index.md):<br>Archive [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Delete | | | | | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses | ✓ (1) | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports | ✓ (1) | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View License list | | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>Manage license policy | | | | ✓ | ✓ | +| [License Scanning](compliance/license_scanning_of_cyclonedx_files/index.md):<br>View allowed and denied licenses | ✓ (1) | ✓ | ✓ | ✓ | ✓ | +| [License Scanning](compliance/license_scanning_of_cyclonedx_files/index.md):<br>View License Compliance reports | ✓ (1) | ✓ | ✓ | ✓ | ✓ | +| [License Scanning](compliance/license_scanning_of_cyclonedx_files/index.md):<br>View License list | | ✓ | ✓ | ✓ | ✓ | +| [License approval policies](../user/compliance/license_approval_policies.md):<br>Manage license policy | | | | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | @@ -250,7 +250,7 @@ The following table lists project permissions available for each role: 20. Maintainers cannot create, demote, or remove Owners, and they cannot promote users to the Owner role. They also cannot approve Owner role access requests. 21. Authors of tasks can delete them even if they don't have the Owner role, but they have to have at least the Guest role for the project. 22. You must have permission to [view the epic](group/epics/manage_epics.md#who-can-view-an-epic). -23. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can view private repository content if an administrator gives those users permission. The administrator can create a [custom role](#custom-roles) through the API and assign that role to the users. +23. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can view private repository content if an administrator (on self-managed) or group owner (on GitLab.com) gives those users permission. The administrator or group owner can create a [custom role](#custom-roles) through the API and assign that role to the users. <!-- markdownlint-enable MD029 --> @@ -284,6 +284,7 @@ More details about the permissions for some project-level features follow. | Run CI/CD pipeline | | | | ✓ | ✓ | ✓ | | Run CI/CD pipeline for a protected branch | | | | ✓ (5) | ✓ (5) | ✓ | | Stop [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | +| Run deployment job for a protected environment | | | ✓ (5) | ✓ (6) | ✓ (6) | ✓ | | View a job with [debug logging](../ci/variables/index.md#enable-debug-logging) | | | | ✓ | ✓ | ✓ | | Use pipeline editor | | | | ✓ | ✓ | ✓ | | Run [interactive web terminals](../ci/interactive_web_terminal/index.md) | | | | ✓ | ✓ | ✓ | @@ -307,6 +308,7 @@ More details about the permissions for some project-level features follow. - [In GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/35069) and later, run for a non-protected branch. 5. If the user is [allowed to merge or push to the protected branch](../ci/pipelines/index.md#pipeline-security-on-protected-branches). +6. If the user if [part of a group with at least the Reporter role](../ci/environments/protected_environments.md#deployment-only-access-to-protected-environments) <!-- markdownlint-enable MD029 --> @@ -427,7 +429,7 @@ nested groups if you have membership in one of its parents. For more information, see [subgroup memberships](group/subgroups/index.md#subgroup-membership). -## Users with Minimal Access **(PREMIUM)** +## Users with Minimal Access **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40942) in GitLab 13.4. > - Support for inviting users with Minimal Access role [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106438) in GitLab 15.9. @@ -466,13 +468,16 @@ To work around the issue, give these users the Guest role or higher to any proje - [Release permissions](project/releases/index.md#release-permissions) - [Read-only namespaces](../user/read_only_namespaces.md) -## Custom roles **(ULTIMATE)** +## Custom roles **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106256) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `customizable_roles`. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110810) in GitLab 15.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114524) in GitLab 15.10. > - The ability for a custom role to view a vulnerability report [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10160) in GitLab 16.1. +FLAG: +On self-managed GitLab, by default the ability for a custom role to view a vulnerability report is not available. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `elevated_guests`. On GitLab.com, this feature is available. + Custom roles allow group members who are assigned the Owner role to create roles specific to the needs of their organization. @@ -482,10 +487,17 @@ For a demo of the custom roles feature, see [[Demo] Ultimate Guest can view code The following custom roles are available: - The Guest+1 role, which allows users with the Guest role to view code. -- In GitLab 16.1 and later, you can create a custom role that can view vulnerability reports and update (change status) of the vulnerabilities. +- In GitLab 16.1 and later, you can create a custom role that can view vulnerability reports and change the status of the vulnerabilities. You can discuss individual custom role and permission requests in [issue 391760](https://gitlab.com/gitlab-org/gitlab/-/issues/391760). +When you enable the view vulnerability custom role for a user with the Guest role, that user has access to elevated permissions, and therefore: + +- Is considered a [billable user](../subscriptions/self_managed/index.md#billable-users) on self-managed GitLab. +- [Uses a seat](../subscriptions/gitlab_com/index.md#how-seat-usage-is-determined) on GitLab.com. + +This does not apply to the Guest+1 custom role because the `view_code` ability is excluded from this behavior. + ### Create a custom role To enable custom roles for your group, a group member with the Owner role: @@ -514,7 +526,7 @@ You can see the required minimal access levels and abilities requirements in the To associate a custom role with an existing group member, a group member with the Owner role: -1. Invites a user to the root group or any subgroup or project in the root +1. Invites a user as a direct member to the root group or any subgroup or project in the root group's hierarchy as a Guest. At this point, this Guest user cannot see any code on the projects in the group or subgroup. 1. Optional. If the Owner does not know the `ID` of the Guest user receiving a custom diff --git a/doc/user/product_analytics/index.md b/doc/user/product_analytics/index.md index e04c61b2c00..06a90af55c7 100644 --- a/doc/user/product_analytics/index.md +++ b/doc/user/product_analytics/index.md @@ -4,7 +4,7 @@ group: Product Analytics 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 --- -# Product analytics (Experiment) **(ULTIMATE)** +# Product analytics (Experiment) **(ULTIMATE ALL)** > - Introduced in GitLab 15.4 as an [Experiment](../../policy/experiment-beta-support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default. > - `cube_api_proxy` revised to only reference the [Product Analytics API](../../api/product_analytics.md) in GitLab 15.6. @@ -94,11 +94,9 @@ Prerequisites: - Product analytics must be enabled at the instance-level. - You must have at least the Maintainer role for the project or group the project belongs to. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General** -1. Expand **Product Analytics**. -1. In the **Connect to your instance** section, enter the configuration values. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Analytics**. +1. Expand **Configure** and enter the configuration values. 1. Select **Save changes**. ## Instrument a GitLab project diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index b27658e5e41..2694ed5f213 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.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 --- -# Deleting a user account **(FREE)** +# Deleting a user account **(FREE ALL)** Users can be deleted from a GitLab instance, either by: diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 33888e4f06e..83bdf883510 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -4,7 +4,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 --- -# Two-factor authentication **(FREE)** +# Two-factor authentication **(FREE ALL)** Two-factor authentication (2FA) provides an additional level of security to your GitLab account. For others to access your account, they would need your username and password _and_ access to your second factor of authentication. @@ -71,9 +71,12 @@ To enable 2FA with a one-time password: - Cloud-based (recommended because you can restore access if you lose the hardware device): - [Authy](https://authy.com/). - [Duo](https://duo.com/). - - Other: + - Other (proprietary): - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en). - [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app). + - Other (Free Software) + - [Aegis Authenticator](https://getaegis.app/). + - [FreeOTP](https://freeotp.github.io/). 1. In the application, add a new entry in one of two ways: - Scan the code displayed by GitLab with your device's camera to add the entry automatically. - Enter the details provided to add the entry manually. @@ -114,14 +117,14 @@ Configure FortiAuthenticator in GitLab. On your GitLab server: sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml ``` -1. Add the provider configuration: +1. Add the provider configuration. For Linux package installations: @@ -133,7 +136,7 @@ Configure FortiAuthenticator in GitLab. On your GitLab server: gitlab_rails['forti_authenticator_access_token'] = 's3cr3t' ``` - For installations from source: + For self-compiled installations: ```yaml forti_authenticator: @@ -146,7 +149,7 @@ Configure FortiAuthenticator in GitLab. On your GitLab server: 1. Save the configuration file. 1. [Reconfigure](../../../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) - (Linux package installations) or [restart](../../../administration/restart_gitlab.md#installations-from-source) + (Linux package installations) or [restart](../../../administration/restart_gitlab.md#self-compiled-installations) (self-compiled installations). ### Enable one-time password using Duo @@ -181,14 +184,14 @@ On your GitLab server: sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml ``` -1. Add the provider configuration: +1. Add the provider configuration. For Linux package installations: @@ -199,7 +202,7 @@ On your GitLab server: gitlab_rails['duo_auth_hostname'] = '<duo_api_hostname>' ``` - For installations from source: + For self-compiled installations: ```yaml duo_auth: @@ -211,7 +214,7 @@ On your GitLab server: 1. Save the configuration file. 1. For Linux package installations, [reconfigure GitLab](../../../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). - For installations from source, [restart GitLab](../../../administration/restart_gitlab.md#installations-from-source). + For self-compiled installations, [restart GitLab](../../../administration/restart_gitlab.md#self-compiled-installations). ### Enable one-time password using FortiToken Cloud @@ -240,14 +243,14 @@ Configure FortiToken Cloud in GitLab. On your GitLab server: sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml ``` -1. Add the provider configuration: +1. Add the provider configuration. For Linux package installations: @@ -257,7 +260,7 @@ Configure FortiToken Cloud in GitLab. On your GitLab server: gitlab_rails['forti_token_cloud_client_secret'] = '<your_fortinet_cloud_client_secret>' ``` - For installations from source: + For self-compiled installations: ```yaml forti_token_cloud: @@ -268,7 +271,7 @@ Configure FortiToken Cloud in GitLab. On your GitLab server: 1. Save the configuration file. 1. [Reconfigure](../../../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) (Linux package installations) or - [restart](../../../administration/restart_gitlab.md#installations-from-source) (self-compiled installations). + [restart](../../../administration/restart_gitlab.md#self-compiled-installations) (self-compiled installations). ### Set up a WebAuthn device diff --git a/doc/user/profile/achievements.md b/doc/user/profile/achievements.md index a90144beb1b..080ab41083b 100644 --- a/doc/user/profile/achievements.md +++ b/doc/user/profile/achievements.md @@ -4,7 +4,7 @@ group: Tenant Scale 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 --- -# Achievements (Experiment) **(FREE)** +# Achievements (Experiment) **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113156) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `achievements`. Disabled by default. @@ -115,7 +115,7 @@ To supply the avatar file, call the mutation using `curl`: curl "https://gitlab.com/api/graphql" \ -H "Authorization: Bearer <your-pat-token>" \ -H "Content-Type: multipart/form-data" \ - -F operations='{ "query": "mutation ($file: Upload!) { achievementsCreate(input: { namespaceId: \"gid://gitlab/Namespace/<namespace-id>\", name: \"<name>\", description: \"<description>\", avatar: $file }) { achievement { id name description avatarUrl } } }", "variables": { "file": null } }' \ + -F operations='{ "query": "mutation ($file: Upload!) { achievementsCreate(input: { namespaceId: \"gid://gitlab/Namespace/<namespace-id>\", name: \"<name>\", description: \"<description>\", avatar: $file }) { achievement { id name description avatarUrl } } }", "variables": { "file": null } }' \ -F map='{ "0": ["variables.file"] }' \ -F 0='@/path/to/your/file.jpg' ``` @@ -252,7 +252,7 @@ mutation { ## Delete an achievement If you consider you no longer need an achievement, you can delete it. -This will delete all related awarded and revoked instances of the achievement. +This deletes all related awarded and revoked instances of the achievement. Prerequisites: diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index cb56aa8a07a..5e8eb80a1aa 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Active sessions **(FREE)** +# Active sessions **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17867) in GitLab 10.8. diff --git a/doc/user/profile/comment_templates.md b/doc/user/profile/comment_templates.md index a9db2d268fe..50df5f8fdb4 100644 --- a/doc/user/profile/comment_templates.md +++ b/doc/user/profile/comment_templates.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Comment templates **(FREE)** +# Comment templates **(FREE ALL)** > - GraphQL support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352956) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `saved_replies`. Disabled by default. > - User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113232) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `saved_replies`. Disabled by default. Enabled for GitLab team members only. @@ -41,6 +41,7 @@ To create a comment template for future use: 1. On the left sidebar, select your avatar. 1. From the dropdown list, select **Preferences**. 1. On the left sidebar, select **Comment templates** (**{comment-lines}**). +1. Select **Add new**. 1. Provide a **Name** for your comment template. 1. Enter the **Content** of your reply. You can use any formatting you use in other GitLab text areas. diff --git a/doc/user/profile/contributions_calendar.md b/doc/user/profile/contributions_calendar.md index e7f7211aeae..37b2c1a26e6 100644 --- a/doc/user/profile/contributions_calendar.md +++ b/doc/user/profile/contributions_calendar.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Contributions calendar **(FREE)** +# Contributions calendar **(FREE ALL)** The contributions calendar displays a [user's events](#user-contribution-events) from the past 12 months. This includes contributions made in forked and [private](#show-private-contributions-on-your-user-profile-page) repositories. diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 32ea9dd2c23..a25260c3db9 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.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 account **(FREE)** +# User account **(FREE ALL)** Each GitLab account has a user profile, which contains information about you and your GitLab activity. @@ -57,6 +57,7 @@ To add new email to your account: 1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Emails**. +1. Select **Add new email**. 1. In the **Email** text box, enter the new email. 1. Select **Add email address**. 1. Verify your email address with the verification email received. @@ -310,7 +311,8 @@ the maximum number of users you can follow is 300. ### Disable following and being followed by other users -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325558) in GitLab 16.0 [with a flag](../feature_flags.md) named `disable_follow_users`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325558) in GitLab 16.0 [with a flag](../feature_flags.md) named `disable_follow_users`. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/420620) in GitLab 16.3. You can disable following and being followed by other users. @@ -337,14 +339,33 @@ You can disable searching with Zoekt and use Elasticsearch instead. 1. Clear the **Enable advanced code search** checkbox. 1. Select **Save changes**. -## View your activity +## View a user's activity GitLab tracks [user contribution activity](contributions_calendar.md). -To view a summary of your activity, or the activity of other users: +To view a user's activity: -1. From a user's profile, select **Follow**. +1. Go to the user's profile. 1. In the GitLab menu, select **Activity**. -1. Select the **Followed users** tab. + +A list of **Most Recent Activity** contributions is displayed. + +## View your activity + +To view your activity: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Your work**. +1. Select **Activity**. +1. Optional. To filter your activity by contribution type, in the **Your Activity** tab, select a tab: + + - **All**: All contributions you made in your groups and projects. + - **Push events**: Push events you made in your projects. + - **Merge events**: Merge requests you accepted in your projects. + - **Issue events**: Issues you opened and closed in your projects. + - **Comments**: Comments you posted in your projects. + - **Wiki**: Wiki pages you created and updated in your projects. + - **Designs**: Designs you added, updated, and removed in your projects. + - **Team**: Projects you joined and left. ## Session duration @@ -405,5 +426,5 @@ a session if the browser is closed or the existing session expires. - Manage applications that can [use GitLab as an OAuth provider](../../integration/oauth_provider.md) - Manage [personal access tokens](personal_access_tokens.md) to access your account via API and authorized applications - Manage [SSH keys](../ssh.md) to access your account via SSH -- Change your [syntax highlighting theme](preferences.md#syntax-highlighting-theme) +- [Change the syntax highlighting theme](preferences.md#change-the-syntax-highlighting-theme) - [View your active sessions](active_sessions.md) and revoke any of them if necessary diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index f378b0ae301..f1310bbb323 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.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/product/ux/technical-writing/#assignments --- -# Notification emails **(FREE)** +# Notification emails **(FREE ALL)** > - Enhanced email styling [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78604) in GitLab 14.9 [with a feature flag](../../administration/feature_flags.md) named `enhanced_notify_css`. Disabled by default. > - Enhanced email styling [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/355907) in GitLab 14.9. @@ -199,6 +199,8 @@ Users are notified of the following events: | Two-factor authentication disabled | User | Security email, always sent. | | User added to group | User | Sent when user is added to group. | | User added to project | User | Sent when user is added to project. | +| Group access expired | Group members | Sent when user's access to a group expires in seven days. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.3._ | +| Project access expired | Project members | Sent when user's access to a project expires in seven days. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.3._ | ## Notifications on issues, merge requests, and epics @@ -331,6 +333,13 @@ The participants are: - Authors of comments on the design. - Anyone that is [mentioned](../discussions/index.md#mentions) in a comment on the design. +## Notifications on group or project access expiration + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.3. + +GitLab sends an email notification if a user's access to a group or project expires in seven days. +This reminds group or project members to extend their access duration if they want to. + ## Opt out of all GitLab emails If you no longer wish to receive any email notifications: @@ -389,7 +398,7 @@ For example, an email with the reason `assigned` has this sentence in the footer > You are receiving this email because you have been assigned an item on \<configured GitLab hostname>. -#### On-call alerts notifications **(PREMIUM)** +#### On-call alerts notifications **(PREMIUM ALL)** An [on-call alert](../../operations/incident_management/oncall_schedules.md) notification email can have one of [the alert's](../../operations/incident_management/alerts.md) statuses: @@ -399,7 +408,7 @@ notification email can have one of [the alert's](../../operations/incident_manag - `alert_resolved` - `alert_ignored` -#### Incident escalation notifications **(PREMIUM)** +#### Incident escalation notifications **(PREMIUM ALL)** An [incident escalation](../../operations/incident_management/escalation_policies.md) notification email can have one of [the incident's](../../operations/incident_management/incidents.md) status: @@ -427,3 +436,9 @@ current_user = User.first recipients = NotificationRecipients::BuildService.build_recipients(merge_request, current_user, action: "push_to"); recipients.count recipients.each { |notify| puts notify.user.username } ``` + +### Notifications about failed pipeline that doesn't exist + +If you receive notifications (through email or Slack) regarding a failed pipeline that no longer +exists, double-check to see if you have any duplicate GitLab instances that could have triggered the +message. diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index a8231460045..9161f5d4cf6 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.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 --- -# Personal access tokens **(FREE)** +# Personal access tokens **(FREE ALL)** > - Notifications for expiring tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab 12.6. > - Token lifetime limits [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab 12.6. @@ -51,6 +51,7 @@ You can create as many personal access tokens as you like. 1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. +1. Select **Add new token**. 1. Enter a name and expiry date for the token. - The token expires on that date at midnight UTC. - If you do not enter an expiry date, the expiry date is automatically set to 365 days later than the current date. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 17dea99e5ef..2df2674d539 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -5,96 +5,64 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Profile preferences **(FREE)** +# Profile preferences **(FREE ALL)** -A user's profile preferences page allows the user to customize various aspects -of GitLab to their liking. +You can update your preferences to change the look and feel of GitLab. -To navigate to your profile's preferences: +## Change the color theme -1. On the left sidebar, select your avatar. -1. Select **Preferences**. - -## Navigation theme - -The GitLab navigation theme setting allows you to personalize your GitLab experience. -You can choose from several color themes that add unique colors to the left sidebar. +You can change the color theme of the GitLab UI. These colors are displayed on the left sidebar. Using individual color themes might help you differentiate between your different -GitLab instances. +GitLab instances. -The default theme is Indigo. You can choose between 10 themes: +To change the color theme: -- Indigo -- Light Indigo -- Blue -- Light Blue -- Green -- Light Green -- Red -- Light Red -- Dark -- Light -- [Dark Mode](#dark-mode) - -## Dark mode - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252) in GitLab 13.1 as an [Experiment](../../policy/experiment-beta-support.md#experiment) release. +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. In the **Color theme** section, select a theme. -GitLab has started work on dark mode! The dark mode Experiment release is available in the -spirit of iteration and the lower expectations of -[Experiment features](../../policy/experiment-beta-support.md#experiment). +### Dark mode -Progress on dark mode is tracked in the [Dark theme epic](https://gitlab.com/groups/gitlab-org/-/epics/2902). -See the epic for: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252) in GitLab 13.1 as an [Experiment](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252). -- A list of known issues. -- Our planned direction and next steps. +Dark mode makes elements on the GitLab UI stand out on a dark background. -If you find an issue that isn't listed, leave a comment on the epic or create a -new issue. +- To turn on Dark mode, Select **Preferences > Color theme > Dark Mode**. -Dark mode is available as a navigation theme, for MVC and compatibility reasons. -[An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/219512) -to make it configurable in its own section along with support for -different navigation themes. +Dark mode works only with the **Dark** Syntax highlighting theme. You can report and view issues, send feedback, and track progress in [epic 2092](https://gitlab.com/groups/gitlab-org/-/epics/2902). -Dark theme only works with the **Dark** syntax highlighting theme. +## Change the syntax highlighting theme -## Syntax highlighting theme +> Changing the default syntax highlighting theme for authenticated and unauthenticated users [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25129) in GitLab 15.1. -> Changing the default syntax highlighting theme for new users and users who are not signed in [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25129) in GitLab 15.10. +Syntax highlighting is a feature in code editors and IDEs. The highlighter assigns a color to each type of code, such as strings and comments. -GitLab uses the [Rouge Ruby library](https://github.com/rouge-ruby/rouge) -for syntax highlighting outside of any Editor context. The WebIDE (like Snippets) -uses [Monaco Editor](https://microsoft.github.io/monaco-editor/) and it's provided -[Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for -syntax highlighting. For a list of supported languages, see the documentation of -the respective libraries. +To change the syntax highlighting theme: -Changing this setting allows you to customize the color theme when viewing any -syntax highlighted code on GitLab. +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. In the **Syntax highlighting theme** section, select a theme. +1. Select **Save changes**. - +To view the updated syntax highlighting theme, refresh your project's page. -Introduced in GitLab 13.6, the themes [Solarized](https://gitlab.com/gitlab-org/gitlab/-/issues/221034) and [Monokai](https://gitlab.com/gitlab-org/gitlab/-/issues/221034) also apply to the [Web IDE](../project/web_ide/index.md) and [Snippets](../snippets.md). +To customize the syntax highlighting theme, you can also [use the Application settings API](../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). Use `default_syntax_highlighting_theme` to change the syntax highlighting colors on a more granular level. -You can use an API call to change the default syntax highlighting theme for new users and users -who are not signed in. For more information, see the `default_syntax_highlighting_theme` -in the [list of settings that can be accessed through API calls](../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). +If these steps do not work, your programming language might not be supported by the syntax highlighters. +For more information, view [Rouge Ruby Library](https://github.com/rouge-ruby/rouge) for guidance on code files and Snippets. View [Moncaco Editor](https://microsoft.github.io/monaco-editor/) and [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) for guidance on the Web IDE. -## Diff colors +## Change the diff colors -A diff compares the old/removed content with the new/added content (for example, when -[reviewing a merge request](../project/merge_requests/reviews/index.md#review-a-merge-request) or in a -[Markdown inline diff](../markdown.md#inline-diff)). -Typically, the colors red and green are used for removed and added lines in diffs. -The exact colors depend on the selected [syntax highlighting theme](#syntax-highlighting-theme). -The colors may lead to difficulties in case of red-green color blindness. +Diffs use two different background colors to show changes between versions of code. By default, the original file in red and the changes made in green. -For this reason, you can customize the following colors: +To change the diff colors: -- Color for removed lines -- Color for added lines +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Diff colors** section. +1. Complete the fields. +1. Select **Save changes**. +1. Optional. Type a color code in the fields. ## Behavior @@ -157,7 +125,8 @@ You can choose one of the following options as the first day of the week: - Sunday - Monday -If you select **System Default**, the [instance default](../../administration/settings/index.md#default-first-day-of-the-week) setting is used. +If you select **System Default**, the first day of the week is set to the +[instance default](../../administration/settings/index.md#change-the-default-first-day-of-the-week). ## Time preferences diff --git a/doc/user/profile/service_accounts.md b/doc/user/profile/service_accounts.md new file mode 100644 index 00000000000..e593378ce4a --- /dev/null +++ b/doc/user/profile/service_accounts.md @@ -0,0 +1,157 @@ +--- +type: index, howto +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Service accounts **(PREMIUM ALL)** + +A service account is a type of machine user that is not tied to an individual human +user. + +A service account: + +- Does not use a licensed seat. +- Is not a: + - Billable user. + - Bot user. +- Is listed in group membership as a service account. +- Cannot sign into GitLab through the UI. + +You should use service accounts in pipelines or integrations where credentials must be +set up and maintained without being impacted by changes in human user membership. + +## Create a service account + +The number of service accounts you can create is restricted by the number of service +accounts allowed under your license: + +- On GitLab Free, service accounts are not available. +- On GitLab Premium, you can create one service account for every paid seat you have. +- On GitLab Ultimate, you can create an unlimited number of service accounts. + +How you create an account differs depending on whether you are on GitLab.com or self-managed. + +### GitLab.com + +Prerequisite: + +- You must have the Owner role in a top-level group. + +1. [Create a service account](../../api/groups.md#create-service-account-user). + + This service account is associated only with your top-level group. + +1. [Create a personal access token](../../api/groups.md#create-personal-access-token-for-service-account-user) + for the service account user. + + You define the scopes for the service account by [setting the scopes for the personal access token](personal_access_tokens.md#personal-access-token-scopes). + + The response includes the personal access token value. + +1. Use the returned personal access token value to authenticate with the GitLab API as the service account user. + +### Self-managed GitLab + +Prerequisite: + +- You must be an administrator for your self-managed instance. + +1. [Create a service account](../../api/users.md#create-service-account-user). + + This service account is associated with the entire instance, not a specific group + or project in the instance. + +1. [Create a personal access token](../../api/users.md#create-service-account-user) + for the service account user. + + You define the scopes for the service account by [setting the scopes for the personal access token](personal_access_tokens.md#personal-access-token-scopes). + + The response includes the personal access token value. + +1. Use the returned personal access token value to authenticate with the GitLab API as the service account user. + +## Add a service account to subgroup or project + +In terms of functionality, a service account is the same as an [external user](../../administration/external_users.md) +and has minimal access when you first create it. + +You must manually add the service account to each +[project](../project/members/index.md#add-users-to-a-project) or +[group](../group/index.md#add-users-to-a-group) you want the account to have access to. + +There is no limit to the number of service accounts you can add to a project or group. + +A service account: + +- Can have different roles across multiple subgroups and projects of the same top level group. +- On GitLab.com, only belongs to one top-level group. + +### Add to a subgroup + +You can add the service account to a subgroup [through the UI](../group/index.md#add-users-to-a-group) +or API. + +To add the service account through the API, call the following endpoint: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <ACCESS TOKEN>" --data "user_id=<service_account_user_id>&access_level=30" "https://gitlab.example.com/api/v4/groups/<subgroup_id>/members" +``` + +### Add to a project + +You can add the service account to a project [through the UI](../project/members/index.md#add-users-to-a-project) +or API. + +To add the service account through the API, call the following endpoint: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <PRIVATE-TOKEN>" --data "user_id=<service_account_user_id>&access_level=30" "https://gitlab.example.com/api/v4/projects/<project_id>/members" +``` + +### Change a service account role in a subgroup or project + +You can change a service account role in a subgroup or project through the UI or the API. + +To use the UI, go to the subgroup's or project's membership list and change the service +account's role. + +To use the API, call the following endpoint: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <PRIVATE-TOKEN>" \ --data "user_id=<service_account_user_id>&access_level=30" "https://gitlab.example.com/api/v4/projects/<project_id>/members" +``` + +For more information on the attributes, see the [API documentation on editing a member of a group or project](../../api/members.md#edit-a-member-of-a-group-or-project). + +### Rotate the personal access token + +Prerequisites: + +- For GitLab.com, you must have the Owner role in a top-level group. +- For self-managed GitLab, you must be an administrator for your self-managed instance. + +Use the groups API to [rotate the personal access token](../../api/groups.md#rotate-a-personal-access-token-for-service-account-user) for a service account user. + +### Disable a service account + +You cannot directly disable or delete a service account. Instead, you must: + +1. Remove the service account as a member of all subgroups and projects: + + ```shell + curl --request DELETE --header "PRIVATE-TOKEN: <access_token_id>" "https://gitlab.example.com/api/v4/groups/<group_id>/members/<service_account_id>" + ``` + + For more information, see the [API documentation on removing a member from a group or project](../../api/members.md#remove-a-member-from-a-group-or-project). + +1. Revoke the personal access token using the [UI](personal_access_tokens.md#revoke-a-personal-access-token) or the [API](../../api/personal_access_tokens.md#revoke-a-personal-access-token). + +## Related topics + +- [Billable users](../../subscriptions/self_managed/index.md#billable-users) +- [Associated records](account/delete_account.md#associated-records) +- [Project access tokens - bot users](../project/settings/project_access_tokens.md#bot-users-for-projects) +- [Group access tokens - bot users](../group/settings/group_access_tokens.md#bot-users-for-groups) +- [Internal users](../../development/internal_users.md#internal-users) diff --git a/doc/user/profile/user_passwords.md b/doc/user/profile/user_passwords.md index c57a81c00bf..d8604bc712e 100644 --- a/doc/user/profile/user_passwords.md +++ b/doc/user/profile/user_passwords.md @@ -4,7 +4,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 passwords **(FREE)** +# User passwords **(FREE ALL)** If you use a password to sign in to GitLab, a strong password is very important. A weak or guessable password makes it easier for unauthorized people to log into your account. diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index e0c1ceb7ec5..0bec72d64e8 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -6,7 +6,7 @@ type: reference description: "Autocomplete characters in Markdown fields." --- -# Autocomplete characters **(FREE)** +# Autocomplete characters **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36705) in GitLab 13.9: you can search using the full name in user autocomplete. diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index be47d6f18bd..c275d2b39db 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -4,7 +4,7 @@ group: Tenant Scale 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 --- -# Badges **(FREE)** +# Badges **(FREE ALL)** Badges are a unified way to present condensed pieces of information about your projects. A badge consists of a small image and a URL that the image points to. @@ -133,6 +133,7 @@ To add a new badge to a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > General**. 1. Expand **Badges**. +1. Select **Add badge**. 1. Under **Link**, enter the URL that the badges should point to. 1. Under **Badge image URL**, enter the URL of the image that should be displayed. 1. Select **Add badge**. diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index c4ef6a647db..efa1fad92b8 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Canary deployments **(FREE)** +# Canary deployments **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in GitLab 9.1. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) from GitLab Premium to GitLab Free in 13.8. diff --git a/doc/user/project/changelogs.md b/doc/user/project/changelogs.md index 0c12f7d476b..1f251565d3f 100644 --- a/doc/user/project/changelogs.md +++ b/doc/user/project/changelogs.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Changelogs **(FREE)** +# Changelogs **(FREE ALL)** Changelogs are generated based on commit titles and Git trailers. To be included in a changelog, a commit must contain a specific Git trailer. Changelogs are generated diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 9a30cbe94e2..45d3834542b 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Connect EKS clusters through cluster certificates (deprecated) **(FREE)** +# Connect EKS clusters through cluster certificates (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index aaaa72d282e..5127248baed 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Connect existing clusters through cluster certificates (deprecated) **(FREE)** +# Connect existing clusters through cluster certificates (deprecated) **(FREE ALL)** > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 09dbd70d1bb..a3a7cb35346 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Connect GKE clusters through cluster certificates (deprecated) **(FREE)** +# Connect GKE clusters through cluster certificates (deprecated) **(FREE ALL)** > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 470daf499be..16ad95bb95c 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Add a cluster using cluster certificates (deprecated) **(FREE)** +# Add a cluster using cluster certificates (deprecated) **(FREE ALL)** > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index ff30da2ca98..2b57fa964c0 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Access controls with cluster certificates (RBAC or ABAC) (deprecated) **(FREE)** +# Access controls with cluster certificates (RBAC or ABAC) (deprecated) **(FREE ALL)** > - Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 2ea7ac0f1fd..70c96280e48 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Deploy to a Kubernetes cluster with cluster certificates (deprecated) **(FREE)** +# Deploy to a Kubernetes cluster with cluster certificates (deprecated) **(FREE ALL)** > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index 537b38dd547..1126e5a7241 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# GitLab-managed clusters (deprecated) **(FREE)** +# GitLab-managed clusters (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 11.5. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index ab6084acd5e..58553fbb1c3 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Project-level Kubernetes clusters (certificate-based) (deprecated) **(FREE)** +# Project-level Kubernetes clusters (certificate-based) (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index c8f49b1917d..7763cb13cd7 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Multiple clusters per project with cluster certificates (deprecated) **(FREE)** +# Multiple clusters per project with cluster certificates (deprecated) **(FREE ALL)** > - Introduced in GitLab 10.3 > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) from GitLab Premium to GitLab Free in 13.2. diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index a985436d67d..7f0fd954d97 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Runbooks **(FREE)** +# Runbooks **(FREE ALL)** Runbooks are a collection of documented procedures that explain how to carry out a particular process, be it starting, stopping, debugging, diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 3fec38a61a0..0df0ef977c0 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Code Intelligence **(FREE)** +# Code Intelligence **(FREE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/1576) in GitLab 13.1. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md deleted file mode 100644 index f9244177aa5..00000000000 --- a/doc/user/project/code_owners.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'codeowners/index.md' -remove_date: '2023-07-07' ---- - -This document was moved to [another location](codeowners/index.md). - -<!-- This redirect file can be deleted after <2023-07-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/codeowners/index.md b/doc/user/project/codeowners/index.md index 272d59bd6a4..74974958910 100644 --- a/doc/user/project/codeowners/index.md +++ b/doc/user/project/codeowners/index.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Code Owners **(PREMIUM)** +# Code Owners **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -339,8 +339,16 @@ The `Documentation` Code Owners section under the **Approval Rules** area displa ### Allowed to Push -The Code Owner approval and protected branch features do not apply to users who -are **Allowed to push**. +Users who are **Allowed to push** can choose to create a merge request +for their changes, or push the changes directly to a branch. If the user +skips the merge request process, the protected-branch features +and Code Owner approvals built into merge requests are also skipped. + +This permission is often granted to accounts associated with +automation ([internal users](../../../development/internal_users.md)) +and release tooling. + +All changes from users _without_ the **Allowed to push** permission must be routed through a merge request. ## Technical Resources diff --git a/doc/user/project/codeowners/reference.md b/doc/user/project/codeowners/reference.md index d486b689638..c2fbbe88b6f 100644 --- a/doc/user/project/codeowners/reference.md +++ b/doc/user/project/codeowners/reference.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Code Owners syntax and error handling **(PREMIUM)** +# Code Owners syntax and error handling **(PREMIUM ALL)** This page describes the syntax and error handling used in Code Owners files, and provides an example file. @@ -210,6 +210,8 @@ Users can be owners of an entry. Each entry can be owned by ## Error handling in Code Owners +> Error validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216066) in GitLab 16.3. + ### Entries with spaces Paths containing whitespace must be escaped with backslashes: `path\ with\ spaces/*.md`. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 8f64fe7dd7d..395873d3107 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy boards (deprecated) **(FREE)** +# Deploy boards (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in GitLab 9.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) from GitLab Premium to GitLab Free in 13.8. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 4e380d485a8..f0d84616c24 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Deploy keys **(FREE)** +# Deploy keys **(FREE ALL)** Use deploy keys to access repositories that are hosted in GitLab. In most cases, you use deploy keys to access a repository from an external host, like a build server or Continuous Integration (CI) server. @@ -85,6 +85,7 @@ Prerequisites: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Deploy keys**. +1. Select **Add new key**. 1. Complete the fields. 1. Optional. To grant `read-write` permission, select the **Grant write permissions to this key** checkbox. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 0b9c42f2a60..41fb0018be9 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Deploy tokens **(FREE)** +# Deploy tokens **(FREE ALL)** > [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) package registry scopes in GitLab 13.0. @@ -95,6 +95,7 @@ Prerequisites: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. 1. Select **Settings > Repository**. 1. Expand **Deploy tokens**. +1. Select **Add token**. 1. Complete the fields, and select the desired [scopes](#scope). 1. Select **Create deploy token**. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 3fb338a75ec..4da49c4fb12 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.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/product/ux/technical-writing/#assignments --- -# Description templates **(FREE)** +# Description templates **(FREE ALL)** You can define templates to use as descriptions for your [issues](issues/index.md) and [merge requests](merge_requests/index.md). @@ -16,7 +16,7 @@ You might want to use these templates: - For different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. - For every issue or merge request for a specific project, so the layout is consistent. -- For a [Service Desk email template](service_desk.md#use-a-custom-template-for-service-desk-tickets). +- For a [Service Desk email template](service_desk/index.md#use-a-custom-template-for-service-desk-tickets). For description templates to work, they must be: @@ -113,7 +113,7 @@ You can also use the instance template repository for file templates. You might also be interested [project templates](../admin_area/custom_project_templates.md) that you can use when creating a new project in the instance. -### Set group-level description templates **(PREMIUM)** +### Set group-level description templates **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 4c77323778c..88aa9446787 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# File Locking **(FREE)** +# File Locking **(FREE ALL)** Preventing wasted work caused by unresolvable merge conflicts requires a different way of working. This means explicitly requesting write permissions, @@ -190,7 +190,7 @@ Suggested workflow for shared projects: 1. Get your changes reviewed, approved, and merged. 1. Unlock the file. -## Default branch file and directory locks **(PREMIUM)** +## Default branch file and directory locks **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in GitLab 8.9. diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 698b888a32a..5e67706708d 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Git attributes **(FREE)** +# Git attributes **(FREE ALL)** GitLab supports defining custom [Git attributes](https://git-scm.com/docs/gitattributes) such as what files to treat as binary, and what language to use for syntax highlighting diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index fbb6d1b329d..ba7d7d39e84 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Syntax Highlighting **(FREE)** +# Syntax Highlighting **(FREE ALL)** GitLab provides syntax highlighting on all files through [Highlight.js](https://github.com/highlightjs/highlight.js/) and the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index b957ff93a4c..0f612d5b222 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Import your project from Bitbucket Cloud to GitLab **(FREE)** +# Import your project from Bitbucket Cloud to GitLab **(FREE ALL)** NOTE: The Bitbucket Cloud importer works only with [Bitbucket.org](https://bitbucket.org/), not with Bitbucket diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 6226e4c1296..a80ce95c163 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Import your project from Bitbucket Server **(FREE)** +# Import your project from Bitbucket Server **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2. @@ -23,7 +23,8 @@ created as private in GitLab as well. ## Import your Bitbucket repositories -> Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. +> - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. +> - Ability to import reviewers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416611) in GitLab 16.3. You can import Bitbucket repositories to GitLab. diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 35ed7a043d0..30a85a108c9 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Migrating from ClearCase **(FREE)** +# Migrating from ClearCase **(FREE ALL)** [ClearCase](https://www.ibm.com/products/rational-clearcase) is a set of tools developed by IBM which also include a centralized version control system diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index fb3416a3492..f5f924ef603 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Migrating from CVS **(FREE)** +# Migrating from CVS **(FREE ALL)** [CVS](https://savannah.nongnu.org/projects/cvs) is an old centralized version control system similar to [SVN](https://subversion.apache.org/). diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 18758ba99e6..85c24886687 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Import your project from FogBugz to GitLab **(FREE)** +# Import your project from FogBugz to GitLab **(FREE ALL)** > Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 22c89084c56..98457b96dde 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Import your project from Gitea to GitLab **(FREE)** +# Import your project from Gitea to GitLab **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. @@ -57,7 +57,7 @@ GitLab access your repositories: 1. Select **Generate Token**. 1. Copy the token hash. 1. Go back to GitLab and provide the token to the Gitea importer. -1. Select **List Your Gitea Repositories** and wait while GitLab reads +1. Select **List your Gitea repositories** and wait while GitLab reads your repositories' information. After it's done, GitLab displays the importer page to select the repositories to import. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index afc36f309be..2079c61da31 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Import your project from GitHub to GitLab **(FREE)** +# Import your project from GitHub to GitLab **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388716) in GitLab 15.10, you no longer need to add any users to the parent group in GitLab to successfully import the **Require a pull request before merging - Allow specified actors to bypass required pull requests** branch protection rule. @@ -203,7 +203,7 @@ After imports are completed, they can be in one of three states: Expand **Details** to see a list of [repository entities](#imported-data) that failed to import. -## Mirror a repository and share pipeline status **(PREMIUM)** +## Mirror a repository and share pipeline status **(PREMIUM ALL)** Depending on your GitLab tier, [repository mirroring](../repository/mirror/index.md) can be set up to keep your imported repository in sync with its GitHub copy. @@ -425,7 +425,7 @@ LoadModule ssl_module lib/httpd/modules/mod_ssl.so </VirtualHost> ``` -## Automate group and project import **(PREMIUM)** +## Automate group and project import **(PREMIUM ALL)** For information on automating user, group, and project import API calls, see [Automate group and project import](index.md#automate-group-and-project-import). diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 2b69cd40fc7..26054317441 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Import a project from GitLab.com to your self-managed GitLab instance (removed) **(FREE)** +# Import a project from GitLab.com to your self-managed GitLab instance (removed) **(FREE ALL)** WARNING: The GitLab.com importer was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108502) in GitLab 15.8 diff --git a/doc/user/project/import/img/jira/import_issues_from_jira_button_v12_10.png b/doc/user/project/import/img/jira/import_issues_from_jira_button_v12_10.png Binary files differdeleted file mode 100644 index 3c1dc44df93..00000000000 --- a/doc/user/project/import/img/jira/import_issues_from_jira_button_v12_10.png +++ /dev/null diff --git a/doc/user/project/import/img/jira/import_issues_from_jira_button_v16_3.png b/doc/user/project/import/img/jira/import_issues_from_jira_button_v16_3.png Binary files differnew file mode 100644 index 00000000000..e9b15838a4c --- /dev/null +++ b/doc/user/project/import/img/jira/import_issues_from_jira_button_v16_3.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 6f9c64b73cb..c1d6f5dbcbe 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Import and migrate projects **(FREE)** +# Import and migrate projects **(FREE ALL)** If you want to bring existing projects to GitLab or copy GitLab projects to a different location, you can: @@ -147,7 +147,7 @@ repository. For example, if an administrator creates the alias `gitlab` for the `https://gitlab.com/gitlab-org/gitlab`, you can clone the project with `git clone git@gitlab.com:gitlab.git` instead of `git clone git@gitlab.com:gitlab-org/gitlab.git`. -## Automate group and project import **(PREMIUM)** +## Automate group and project import **(PREMIUM ALL)** The GitLab Professional Services team uses [Congregate](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate) to orchestrate user, group, and project import API calls. With Congregate, you can migrate data to diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index ede9eb244c6..b2092082bf8 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -4,27 +4,21 @@ group: Project Management 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 --- -# Import your Jira project issues to GitLab **(FREE)** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2766) in GitLab 12.10. +# Import your Jira project issues to GitLab **(FREE ALL)** Using GitLab Jira importer, you can import your Jira issues to GitLab.com or to your self-managed GitLab instance. Jira issues import is an MVC, project-level feature, meaning that issues from multiple Jira projects can be imported into a GitLab project. MVC version imports issue title and description -as well as some other issue metadata as a section in the issue description. +and some other issue metadata as a section in the issue description. ## Known limitations -The information imported into GitLab fields from Jira depends on the version of GitLab: +GitLab imports the following information directly: -- From GitLab 12.10 to GitLab 13.1, only the issue's title and description are imported - directly. -- From GitLab 13.2: - - The issue's labels are also imported directly. - - You're also able to map Jira users to GitLab project members when preparing for the - import. +- The issue's title, description, and labels. +- You can also map Jira users to GitLab project members when preparing for the import. Other Jira issue metadata that is not formally mapped to GitLab issue fields is imported into the GitLab issue's description as plain text. @@ -44,8 +38,6 @@ iterations of the GitLab Jira importer. ## Import Jira issues to GitLab -> New import form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216145) in GitLab 13.2. - NOTE: Importing Jira issues is done as an asynchronous background job, which may result in delays based on import queues load, system load, or other factors. @@ -55,7 +47,7 @@ To import Jira issues to a GitLab project: 1. On the **{issues}** **Issues** page, select **Actions** (**{ellipsis_v}**) **> Import from Jira**. -  +  The **Import from Jira** option is only visible if you have the [correct permissions](#prerequisites). diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 980c051eac7..433496ba6c9 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Import multiple repositories by uploading a manifest file **(FREE)** +# Import multiple repositories by uploading a manifest file **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28811) in GitLab 11.2. > - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index 5f06daef0aa..86981799739 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Migrating from Perforce Helix **(FREE)** +# Migrating from Perforce Helix **(FREE ALL)** [Perforce Helix](https://www.perforce.com/) provides a set of tools which also include a centralized, proprietary version control system similar to Git. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index c3c516042f7..5d23ee885bb 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Import project from repository by URL **(FREE)** +# Import project from repository by URL **(FREE ALL)** You can import your existing repositories by providing the Git URL. @@ -30,7 +30,7 @@ You can import your existing repositories by providing the Git URL. Your newly created project is displayed. -## Automate group and project import **(PREMIUM)** +## Automate group and project import **(PREMIUM ALL)** For information on automating user, group, and project import API calls, see [Automate group and project import](index.md#automate-group-and-project-import). diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index da9d31e0ca8..b66e8431f9b 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Migrate from TFVC to Git **(FREE)** +# Migrate from TFVC to Git **(FREE ALL)** Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/products/devops/server/) in 2019, is a set of tools developed by Microsoft which also includes diff --git a/doc/user/project/index.md b/doc/user/project/index.md index b7bdf47ae49..478e9c6bf1b 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -4,7 +4,7 @@ group: Tenant Scale 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" --- -# Create a project **(FREE)** +# Create a project **(FREE ALL)** You can create a project in many ways in GitLab. @@ -62,7 +62,7 @@ A user who creates a project [from a template](#create-a-project-from-a-built-in Imported objects are labeled as `By <username> on <timestamp> (imported from GitLab)`. For this reason, the creation date of imported objects can be older than the creation date of the user's account. This can lead to objects appearing to have been created by a user before they even had an account. -## Create a project from a custom template **(PREMIUM)** +## Create a project from a custom template **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in GitLab 11.2. @@ -87,7 +87,7 @@ Custom project templates are available at: change the **Visibility Level**. 1. Select **Create project**. -## Create a project from the HIPAA Audit Protocol template **(ULTIMATE)** +## Create a project from the HIPAA Audit Protocol template **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10 @@ -126,7 +126,7 @@ You cannot use `git push` to create projects with project paths that: Previously used project paths have a redirect. The redirect causes push attempts to redirect requests to the renamed project location, instead of creating a new project. To create a new project for a previously -used or renamed project, use the [UI](#create-a-project) or the [Projects API](../../api/projects.md#create-project). +used or renamed project, use the UI or the [Projects API](../../api/projects.md#create-project). Prerequisites: diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 533824dd58a..60b23540ac3 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -4,7 +4,7 @@ group: Optimize 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 --- -# Insights for projects **(ULTIMATE)** +# Insights for projects **(ULTIMATE ALL)** Configure project insights to explore data such as: diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md index 405531abd0d..6005bc48d56 100644 --- a/doc/user/project/integrations/apple_app_store.md +++ b/doc/user/project/integrations/apple_app_store.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Apple App Store **(FREE)** +# Apple App Store **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104888) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385335) in GitLab 15.10. Feature flag `apple_app_store_integration` removed. @@ -32,7 +32,7 @@ GitLab supports enabling the Apple App Store integration at the project level. C 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Apple App Store Connect**. -1. Turn on the **Active** toggle under **Enable Integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Provide the Apple App Store Connect configuration information: - **Issuer ID**: The Apple App Store Connect issuer ID. - **Key ID**: The key ID of the generated private key. diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index edd08f1e3d3..c73563ba162 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Asana **(FREE)** +# Asana **(FREE ALL)** The Asana integration adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 8394687d8f5..9abbe75cc4c 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Atlassian Bamboo **(FREE)** +# Atlassian Bamboo **(FREE ALL)** You can automatically trigger builds in Atlassian Bamboo when you push changes to your project in GitLab. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 1796e674b00..048673cd4a2 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Bugzilla **(FREE)** +# Bugzilla **(FREE ALL)** [Bugzilla](https://www.bugzilla.org/) is a web-based general-purpose bug tracking system and testing tool. @@ -17,7 +17,7 @@ To enable the Bugzilla integration in a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Bugzilla**. -1. Select the checkbox under **Enable integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Fill in the required fields: - **Project URL**: The URL to the project in Bugzilla. diff --git a/doc/user/project/integrations/clickup.md b/doc/user/project/integrations/clickup.md index bf2c738049c..7075aca28c2 100644 --- a/doc/user/project/integrations/clickup.md +++ b/doc/user/project/integrations/clickup.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# ClickUp **(FREE)** +# ClickUp **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120732) in GitLab 16.1. @@ -14,7 +14,7 @@ To enable the ClickUp integration in a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **ClickUp**. -1. Select the checkbox under **Enable integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Fill in the required fields: - **Project URL**: The URL to the ClickUp project to link to this GitLab project. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 9580c924fd1..54d092d2fa9 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Custom issue tracker **(FREE)** +# Custom issue tracker **(FREE ALL)** You can integrate an [external issue tracker](../../../integration/external-issue-tracker.md) with GitLab. If your preferred issue tracker is not listed in the @@ -23,7 +23,7 @@ To enable a custom issue tracker in a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Custom issue tracker**. -1. Select the checkbox under **Enable integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Fill in the required fields: - **Project URL**: The URL to view all the issues in the custom issue tracker. diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 180e39e3254..67f76d48744 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Discord Notifications **(FREE)** +# Discord Notifications **(FREE ALL)** The Discord Notifications integration sends event notifications from GitLab to the channel for which the webhook was created. @@ -24,14 +24,18 @@ and configure it in GitLab. ## Configure created webhook in GitLab +> Event webhook overrides [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125621) in GitLab 16.3. + With the webhook URL created in the Discord channel, you can set up the Discord Notifications integration in GitLab. 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Discord Notifications**. 1. Ensure that the **Active** toggle is enabled. -1. Check the checkboxes corresponding to the GitLab events for which you want to send notifications to Discord. -1. Paste the webhook URL that you copied from the create Discord webhook step. +1. Paste the webhook URL that you [created earlier](#create-webhook) into the **Webhook** field. +1. Select the checkboxes corresponding to the GitLab events for which you want to send notifications to Discord. +1. Optionally for each checkbox that you select, enter a new Discord webhook URL that you have [configured](#create-webhook) + to override the default one in the **Webhook** field. 1. Configure the remaining options and select the **Save changes** button. The Discord channel you created the webhook for now receives notification of the GitLab events that were configured. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index eb3eecaa656..105061efba7 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Emails on push **(FREE)** +# Emails on push **(FREE ALL)** When you enable emails on push, you receive email notifications for every change that is pushed to your project. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index d96558579d1..7ee0306e7c0 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Engineering Workflow Management (EWM) **(FREE)** +# Engineering Workflow Management (EWM) **(FREE ALL)** The EWM integration allows you to go from GitLab to EWM work items mentioned in merge request descriptions and commit messages. @@ -17,7 +17,7 @@ To enable the EWM integration, in a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **EWM**. -1. Select the checkbox under **Enable integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Fill in the required fields: - **Project URL**: The URL to the EWM project area. diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 98654a3b59f..3f4b110468b 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# GitHub **(PREMIUM)** +# GitHub **(PREMIUM ALL)** You can update GitHub with pipeline status updates from GitLab. The GitHub integration can help you if you use GitLab for CI/CD. diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index bfa8a905699..a082d9aa5be 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -4,12 +4,12 @@ group: Import and Integrate 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 --- -# GitLab for Slack app **(FREE)** +# GitLab for Slack app **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358872) for self-managed instances in GitLab 16.2. NOTE: -This page contains information about configuring the GitLab for Slack app on GitLab.com. For administrator documentation, see [GitLab for Slack app administration](../../admin_area/settings/slack_app.md). +This page contains information about configuring the GitLab for Slack app on GitLab.com. For administrator documentation, see [GitLab for Slack app administration](../../../administration/settings/slack_app.md). The GitLab for Slack app is a native Slack app that provides [slash commands](#slash-commands) and [notifications](#slack-notifications) in your Slack workspace. GitLab links your Slack user with your GitLab user so that any command @@ -176,7 +176,7 @@ The following events are available for Slack notifications: ### GitLab for Slack app does not appear in the list of integrations -The GitLab for Slack app might not appear in the list of integrations. To have the GitLab for Slack app on your self-managed instance, an administrator must [enable the integration](../../admin_area/settings/slack_app.md). On GitLab.com, the GitLab for Slack app is available by default. +The GitLab for Slack app might not appear in the list of integrations. To have the GitLab for Slack app on your self-managed instance, an administrator must [enable the integration](../../../administration/settings/slack_app.md). On GitLab.com, the GitLab for Slack app is available by default. The GitLab for Slack app is enabled at the project level only. Support for the app at the group and instance levels is proposed in [issue 391526](https://gitlab.com/gitlab-org/gitlab/-/issues/391526). @@ -197,7 +197,7 @@ As a workaround, ensure: ### Slash commands return `/gitlab failed with the error "dispatch_failed"` in Slack -Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. To resolve this issue, ensure an administrator has properly configured the [GitLab for Slack app settings](../../admin_area/settings/slack_app.md) on your self-managed instance. +Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. To resolve this issue, ensure an administrator has properly configured the [GitLab for Slack app settings](../../../administration/settings/slack_app.md) on your self-managed instance. ### Notifications are not received to a channel diff --git a/doc/user/project/integrations/google_play.md b/doc/user/project/integrations/google_play.md index 4b0f4fe205a..696bb6acf99 100644 --- a/doc/user/project/integrations/google_play.md +++ b/doc/user/project/integrations/google_play.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Google Play **(FREE)** +# Google Play **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111621) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `google_play_integration`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/389611) in GitLab 15.11. Feature flag `google_play_integration` removed. @@ -34,7 +34,9 @@ To enable the Google Play integration in GitLab: 1. Select **Google Play**. 1. In **Enable integration**, select the **Active** checkbox. 1. In **Package name**, enter the package name of the app (for example, `com.gitlab.app_name`). +1. Optional. Under **Protected branches and tags only**, select the **Only set variables on protected branches and tags** checkbox. 1. In **Service account key (.JSON)**, drag or upload your key file. +1. Optional. Select **Test settings**. 1. Select **Save changes**. After you enable the integration, the global variables `$SUPPLY_PACKAGE_NAME` and `$SUPPLY_JSON_KEY_DATA` are created for CI/CD use. diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 4046869072d..e0d30f63ad9 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Google Chat **(FREE)** +# Google Chat **(FREE ALL)** You can configure your project to send notifications from GitLab to a room of your choice in [Google Chat](https://chat.google.com/) (formerly Google diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index 12986cba555..803984f82bf 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Harbor **(FREE)** +# Harbor **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80999) in GitLab 14.9. @@ -28,7 +28,7 @@ GitLab supports integrating Harbor projects at the group or project level. Compl 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Harbor**. -1. Turn on the **Active** toggle under **Enable Integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Provide the Harbor configuration information: - **Harbor URL**: The base URL of Harbor instance which is being linked to this GitLab project. For example, `https://harbor.example.net`. - **Harbor project name**: The project name in the Harbor instance. For example, `testproject`. diff --git a/doc/user/project/integrations/img/slack_setup.png b/doc/user/project/integrations/img/slack_setup.png Binary files differdeleted file mode 100644 index d8aedf84be5..00000000000 --- a/doc/user/project/integrations/img/slack_setup.png +++ /dev/null diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index fd59f54a066..00ae1a0478c 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Project integrations **(FREE)** +# Project integrations **(FREE ALL)** You can integrate your GitLab projects with other applications. Integrations are like plugins, and give you the freedom to add @@ -75,16 +75,16 @@ You can configure the following integrations. | [Pumble](pumble.md) | Send event notifications to a Pumble channel. | **{dotted-circle}** No | | Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | | [Redmine](redmine.md) | Use Redmine as the issue tracker. | **{dotted-circle}** No | -| [Shimo Workspace](shimo.md) | Use Shimo instead of the GitLab Wiki. | **{dotted-circle}** No | +| [Shimo](shimo.md) (deprecated) | Use Shimo instead of the GitLab Wiki. | **{dotted-circle}** No | | [GitLab for Slack app](gitlab_slack_application.md) | Use Slack's official GitLab application. | **{dotted-circle}** No | -| [Slack notifications](slack.md) | Send notifications about project events to Slack. | **{dotted-circle}** No | +| [Slack notifications](slack.md) (deprecated) | Send notifications about project events to Slack. | **{dotted-circle}** No | | [Slack slash commands](slack_slash_commands.md) | Enable slash commands in a workspace. | **{dotted-circle}** No | | [Squash TM](squash_tm.md) | Update Squash TM requirements when GitLab issues are modified. | **{check-circle}** Yes | | [Telegram](telegram.md) | Send notifications about project events to Telegram. | **{dotted-circle}** No | | [Unify Circuit](unify_circuit.md) | Send notifications about project events to Unify Circuit. | **{dotted-circle}** No | | [Webex Teams](webex_teams.md) | Receive events notifications. | **{dotted-circle}** No | | [YouTrack](youtrack.md) | Use YouTrack as the issue tracker. | **{dotted-circle}** No | -| [ZenTao](zentao.md) | Use ZenTao as the issue tracker. | **{dotted-circle}** No | +| [ZenTao](zentao.md) (deprecated) | Use ZenTao as the issue tracker. | **{dotted-circle}** No | ### Project webhooks diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 7d3c85b2c62..f5084392841 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# irker (IRC gateway) **(FREE)** +# irker (IRC gateway) **(FREE ALL)** GitLab provides a way to push update messages to an irker server. After you configure the integration, each push to a project triggers the integration to send data directly diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index a73c0f001f3..9e1de5e3aab 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Mattermost notifications **(FREE)** +# Mattermost notifications **(FREE ALL)** Use the Mattermost notifications integration to send notifications for GitLab events (for example, `issue created`) to Mattermost. You must configure both [Mattermost](#configure-mattermost-to-receive-gitlab-notifications) diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 6a09a1cfbcd..4898d5bd337 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Mattermost slash commands **(FREE)** +# Mattermost slash commands **(FREE ALL)** You can use [slash commands](gitlab_slack_application.md#slash-commands) to run common GitLab operations, like creating an issue, from a [Mattermost](https://mattermost.com/) chat environment. @@ -34,7 +34,7 @@ you can automatically configure Mattermost slash commands: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Mattermost slash commands**. -1. In **Enable integration**, ensure the **Active** checkbox is selected. +1. Under **Enable integration**, ensure the **Active** checkbox is selected. 1. Select **Add to Mattermost**, and select **Save changes**. ## Configure manually @@ -42,7 +42,7 @@ you can automatically configure Mattermost slash commands: To manually configure slash commands in Mattermost, you must: 1. [Enable custom slash commands in Mattermost](#enable-custom-slash-commands-in-mattermost). - (This step is required only for installations from source.) + This step is required only for self-compiled installations. 1. [Get configuration values from GitLab](#get-configuration-values-from-gitlab). 1. [Create a slash command in Mattermost](#create-a-slash-command-in-mattermost). 1. [Provide the Mattermost token to GitLab](#provide-the-mattermost-token-to-gitlab). diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 3d0b77069a3..b359696c72b 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Microsoft Teams notifications **(FREE)** +# Microsoft Teams notifications **(FREE ALL)** You can integrate Microsoft Teams notifications with GitLab and display notifications about GitLab projects in Microsoft Teams. To integrate the services, you must: diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index da09d621d07..fe702766a1d 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Mock CI **(FREE)** +# Mock CI **(FREE ALL)** NOTE: This integration only appears if you're in a [development environment](https://gitlab.com/gitlab-org/gitlab-mock-ci-service#setup-mockci-integration). diff --git a/doc/user/project/integrations/pipeline_status_emails.md b/doc/user/project/integrations/pipeline_status_emails.md index 9a87b5b3110..bf485d73691 100644 --- a/doc/user/project/integrations/pipeline_status_emails.md +++ b/doc/user/project/integrations/pipeline_status_emails.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Pipeline status emails **(FREE)** +# Pipeline status emails **(FREE ALL)** You can send notifications about pipeline status changes in a group or project to a list of email addresses. diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 7f53f08e808..3697e660deb 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Pivotal Tracker **(FREE)** +# Pivotal Tracker **(FREE ALL)** The Pivotal Tracker integration adds commit messages as comments to Pivotal Tracker stories. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index d17e8e6bfca..c0b2591d824 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: 'index.md' --- -# Prometheus (removed) **(FREE)** +# Prometheus (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 848ccbb85f6..e31f3b26e66 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../../../operations/index.md' --- -# Monitoring AWS resources (removed) **(FREE)** +# Monitoring AWS resources (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index ca015d7dc8a..4a0d324932b 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../../../operations/index.md' --- -# Monitoring HAProxy (removed) **(FREE)** +# Monitoring HAProxy (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index ee0b0d1fccb..49345f41514 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../../../operations/index.md' --- -# Prometheus Metrics library (removed) **(FREE)** +# Prometheus Metrics library (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 4b8b9b4bc21..f5bbaffa58e 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../../../operations/index.md' --- -# Monitoring Kubernetes (removed) **(FREE)** +# Monitoring Kubernetes (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 995de6a28f3..e38f26710fc 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../../../operations/index.md' --- -# Monitoring NGINX (removed) **(FREE)** +# Monitoring NGINX (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 03f88e6f7c5..189cf59a514 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../../../operations/index.md' --- -# Monitoring NGINX Ingress Controller (removed) **(FREE)** +# Monitoring NGINX Ingress Controller (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index 837be9d1e0a..e4edd63314f 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../../../operations/index.md' --- -# Monitoring NGINX Ingress Controller with VTS metrics (removed) **(FREE)** +# Monitoring NGINX Ingress Controller with VTS metrics (removed) **(FREE ALL)** This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/pumble.md b/doc/user/project/integrations/pumble.md index 62703ebfad9..218a036f0a2 100644 --- a/doc/user/project/integrations/pumble.md +++ b/doc/user/project/integrations/pumble.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Pumble **(FREE)** +# Pumble **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93623) in GitLab 15.3. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 9cb93c2d082..af2c7265f5d 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Redmine **(FREE)** +# Redmine **(FREE ALL)** You can use [Redmine](https://www.redmine.org/) as an external issue tracker. To enable the Redmine integration in a project: @@ -12,7 +12,7 @@ To enable the Redmine integration in a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Redmine**. -1. Select the checkbox under **Enable integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Fill in the required fields: - **Project URL**: The URL to the Redmine project to link to this GitLab project. diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index a0beb71d83f..2d02a4f631c 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# ServiceNow **(FREE)** +# ServiceNow **(FREE ALL)** ServiceNow offers several integrations to help centralize and automate your management of GitLab workflows. diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md index 6fbd246d7f4..b2c85c8cb4c 100644 --- a/doc/user/project/integrations/shimo.md +++ b/doc/user/project/integrations/shimo.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w <!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> -# Shimo (deprecated) **(FREE)** +# Shimo (deprecated) **(FREE ALL)** WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377824) in GitLab 15.7 @@ -26,7 +26,7 @@ To enable the Shimo integration for your project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Shimo**. -1. In **Enable integration**, ensure the **Active** checkbox is selected. +1. Under **Enable integration**, ensure the **Active** checkbox is selected. 1. Provide the **Shimo Workspace URL** you want to link to your group or project (for example, `https://shimo.im/space/aBAYV6VvajUP873j`). 1. Select **Save changes**. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 55000a0a992..87d7476e42e 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w --- <!--- start_remove The following content will be removed on remove_date: '2024-05-22' --> -# Slack notifications (deprecated) **(FREE)** +# Slack notifications (deprecated) **(FREE ALL)** WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/372411) in GitLab 15.9 @@ -35,7 +35,7 @@ to control GitLab from Slack. Slash commands are configured separately. 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Slack notifications**. -1. In the **Enable integration** section, select the **Active** checkbox. +1. Under **Enable integration**, select the **Active** checkbox. 1. In the **Trigger** section, select the checkboxes for each type of GitLab event to send to Slack as a notification. For a full list, see [Triggers for Slack notifications](#triggers-for-slack-notifications). diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index c1e04f2aa63..78c8180cb4c 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -12,10 +12,10 @@ For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) inst You can use [slash commands](gitlab_slack_application.md#slash-commands) to run common GitLab operations, like creating an issue, from a [Slack](https://slack.com/) chat environment. -To use slash commands in Slack, you must configure both Slack and GitLab. +To run slash commands in Slack, you must configure both Slack and GitLab. -GitLab can also send events (such as `issue created`) to Slack as part of the -separately configured [Slack notifications](slack.md). +GitLab can also send events (such as `issue created`) to Slack as part of +[Slack notifications](gitlab_slack_application.md#slack-notifications). For a list of available slash commands, see [Slash commands](gitlab_slack_application.md#slash-commands). @@ -25,15 +25,15 @@ Slack slash commands are scoped to a project. To configure Slack slash commands: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. -1. Select **Slack slash commands**. Leave this browser tab open. -1. Open a new browser tab, sign in to your Slack team, and [start a new Slash Commands integration](https://my.slack.com/services/new/slash-commands). -1. Enter a trigger command. We suggest you use the project name. - Select **Add Slash Command Integration**. -1. Complete the rest of the fields in the Slack configuration page using information from the GitLab browser tab. - In particular, make sure you copy and paste the **URL**. - -  - -1. On the Slack configuration page, select **Save Integration** and copy the **Token**. -1. Go back to the GitLab configuration page and paste in the **Token**. -1. Ensure the **Active** checkbox is selected and select **Save changes**. +1. Select **Slack slash commands** and leave this browser tab open. +1. In a new browser tab, sign in to Slack and [add a new slash command](https://my.slack.com/services/new/slash-commands). +1. Enter a slash command trigger name. You could use the project name. +1. Select **Add Slash Command Integration**. +1. In the Slack browser tab: + 1. Complete the fields with information from the GitLab browser tab. + 1. Select **Save Integration** and copy the **Token** value. +1. In the GitLab browser tab: + 1. Paste the token and ensure the **Active** checkbox is selected. + 1. Select **Save changes**. + +You can now run slash commands in Slack. diff --git a/doc/user/project/integrations/telegram.md b/doc/user/project/integrations/telegram.md index 9d36a16f5fc..d68222d2f94 100644 --- a/doc/user/project/integrations/telegram.md +++ b/doc/user/project/integrations/telegram.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Telegram **(FREE)** +# Telegram **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122879) in GitLab 16.1. @@ -47,7 +47,7 @@ After you invite the bot to a Telegram channel, you can configure GitLab to send 1. Select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select **Telegram**. -1. In **Enable integration**, select the **Active** checkbox. +1. Under **Enable integration**, select the **Active** checkbox. 1. In **New token**, [paste the token value from the Telegram bot](#create-a-telegram-bot). 1. In the **Trigger** section, select the checkboxes for the GitLab events you want to receive in Telegram. 1. In **Channel identifier**, [paste the Telegram channel identifier](#configure-the-telegram-bot). diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 7d0dd6d2af3..d59bfde5944 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Unify Circuit **(FREE)** +# Unify Circuit **(FREE ALL)** The Unify Circuit integration sends notifications from GitLab to a Circuit conversation. diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 3ba05476e63..370584303f8 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Webex Teams **(FREE)** +# Webex Teams **(FREE ALL)** You can configure GitLab to send notifications to a Webex Teams space: diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 8d66f3e48dd..c4dd8dcf812 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Webhook events **(FREE)** +# Webhook events **(FREE ALL)** You can configure a [webhook](webhooks.md) in your project that triggers when an event occurs. The following events are supported. @@ -611,6 +611,7 @@ Payload example: } }, "work_in_progress": false, + "draft": false, "assignee": { "name": "User1", "username": "user1", @@ -898,6 +899,7 @@ Payload example: "state": "opened", "blocking_discussions_resolved": true, "work_in_progress": false, + "draft": false, "first_contribution": true, "merge_status": "unchecked", "target_project_id": 14, @@ -983,6 +985,10 @@ Payload example: "previous": null, "current": 1 }, + "draft": { + "previous": true, + "current": false + } "updated_at": { "previous": "2017-09-15 16:50:55 UTC", "current":"2017-09-15 16:52:00 UTC" @@ -1454,6 +1460,19 @@ Payload example: "git_http_url": "http://192.168.64.1:3005/gitlab-org/gitlab-test.git", "visibility_level": 20 }, + "project":{ + "id": 380, + "name": "Gitlab Test", + "description": "Atque in sunt eos similique dolores voluptatem.", + "web_url": "http://192.168.64.1:3005/gitlab-org/gitlab-test", + "avatar_url": null, + "git_ssh_url": "git@192.168.64.1:gitlab-org/gitlab-test.git", + "git_http_url": "http://192.168.64.1:3005/gitlab-org/gitlab-test.git", + "namespace": "Gitlab Org", + "visibility_level": 20, + "path_with_namespace": "gitlab-org/gitlab-test", + "default_branch": "master" + }, "runner": { "active": true, "runner_type": "project_type", @@ -1466,6 +1485,15 @@ Payload example: ] }, "environment": null + "source_pipeline":{ + "project":{ + "id": 41, + "web_url": "https://gitlab.example.com/gitlab-org/upstream-project", + "path_with_namespace": "gitlab-org/upstream-project" + }, + "pipeline_id": 30, + "job_id": 3401 + }, } ``` @@ -1547,7 +1575,7 @@ Payload example: } ``` -## Group member events **(PREMIUM)** +## Group member events **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. @@ -1642,7 +1670,7 @@ Payload example: } ``` -## Subgroup events **(PREMIUM)** +## Subgroup events **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260419) in GitLab 13.9. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 9f24f3b49ff..fe3d5e015a6 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Webhooks **(FREE)** +# Webhooks **(FREE ALL)** [Webhooks](https://en.wikipedia.org/wiki/Webhook) are custom HTTP callbacks that you define. They are usually triggered by an @@ -28,7 +28,7 @@ listens for specific [events](#events) and GitLab sends a POST request with data Usually, you set up your own [webhook receiver](#create-an-example-webhook-receiver) to receive information from GitLab and send it to another app, according to your requirements. -We have a [built-in receiver](slack.md) +We have a [built-in receiver](gitlab_slack_application.md#slack-notifications) for sending [Slack](https://api.slack.com/incoming-webhooks) notifications per project. GitLab.com enforces [webhook limits](../../../user/gitlab_com/index.md#webhooks), @@ -37,7 +37,7 @@ including: - The maximum number of webhooks and their size, both per project and per group. - The number of webhook calls per minute. -## Group webhooks **(PREMIUM)** +## Group webhooks **(PREMIUM ALL)** You can configure a group webhook, which is triggered by events that occur across all projects in the group. If you configure identical webhooks @@ -55,6 +55,7 @@ specific to a group, including: To configure a webhook for a project or group: 1. In your project or group, on the left sidebar, select **Settings > Webhooks**. +1. Select **Add new webhook**. 1. In **URL**, enter the URL of the webhook endpoint. The URL must be percent-encoded if it contains one or more special characters. 1. In **Secret token**, enter the [secret token](#validate-payloads-by-using-a-secret-token) to validate payloads. @@ -309,6 +310,7 @@ These public tools include: - [Beeceptor](https://beeceptor.com) to create a temporary HTTPS endpoint and inspect incoming payloads - [Webhook.site](https://webhook.site) to review incoming payloads +- [Webhook Tester](https://webhook-test.com) to inspect and debug incoming payloads ### GitLab Development Kit (GDK) @@ -378,4 +380,11 @@ If you're receiving multiple webhook requests, the webhook might have timed out. GitLab expects a response in [10 seconds](../../../user/gitlab_com/index.md#other-limits). On self-managed GitLab instances, you can [change the webhook timeout limit](../../../administration/instance_limits.md#webhook-timeout). -If a webhook is not triggered, the webhook might be [automatically disabled](#failing-webhooks). +### Webhook is not triggered + +> Webhooks not triggered in Silent Mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393639) in GitLab 16.3. + +If a webhook is not triggered, check that: + +- The webhook was not [automatically disabled](#failing-webhooks). +- The GitLab instance is not in [Silent Mode](../../../administration/silent_mode/index.md). diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index 8845aa8fdfd..651c1a15b7a 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# YouTrack **(FREE)** +# YouTrack **(FREE ALL)** JetBrains [YouTrack](https://www.jetbrains.com/youtrack/) is a web-based issue tracking and project management platform. @@ -17,7 +17,7 @@ To enable the YouTrack integration in a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **YouTrack**. -1. Select the checkbox under **Enable integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Fill in the required fields: - **Project URL**: The URL to the project in YouTrack. - **Issue URL**: The URL to view an issue in the YouTrack project. diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md index b14b9eac9da..e42b0a032fd 100644 --- a/doc/user/project/integrations/zentao.md +++ b/doc/user/project/integrations/zentao.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w <!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> -# ZenTao (deprecated) **(PREMIUM)** +# ZenTao (deprecated) **(PREMIUM ALL)** WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377825) in GitLab 15.7 @@ -43,7 +43,7 @@ Complete these steps in GitLab: 1. Go to your project and select **Settings > Integrations**. 1. Select **ZenTao**. -1. Turn on the **Active** toggle under **Enable Integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Provide the ZenTao configuration information: - **ZenTao Web URL**: The base URL of the ZenTao instance web interface you're linking to this GitLab project (for example, `example.zentao.net`). - **ZenTao API URL** (optional): The base URL to the ZenTao instance API. Defaults to the Web URL value if not set. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index bca1ee5245c..8e3310d3234 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/product/ux/technical-writing/#assignments --- -# Issue boards **(FREE)** +# Issue boards **(FREE ALL)** The issue board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. @@ -253,12 +253,12 @@ Users on GitLab Free can use a single group issue board. GitLab issue boards are available on the GitLab Free tier, but some advanced functionality is present in [higher tiers only](https://about.gitlab.com/pricing/). -### Configurable issue boards **(PREMIUM)** +### Configurable issue boards **(PREMIUM ALL)** > - Setting current iteration as scope [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196804) in GitLab 13.8. > - Moved to GitLab Premium in 13.9. -An issue board can be associated with a [milestone](milestones/index.md#milestones), +An issue board can be associated with a [milestone](milestones/index.md), [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. @@ -277,7 +277,7 @@ selecting **View scope**. Watch a [video presentation](https://youtu.be/m5UTNCSqaDk) of the configurable issue board feature. -### Sum of issue weights **(PREMIUM)** +### Sum of issue weights **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -287,7 +287,7 @@ especially in combination with [assignee lists](#assignee-lists).  -### Assignee lists **(PREMIUM)** +### Assignee lists **(PREMIUM ALL)** As in a regular list showing all issues with a chosen label, you can add an assignee list that shows all issues assigned to a user. @@ -310,7 +310,7 @@ To remove an assignee list, just as with a label list, select the trash icon.  -### Milestone lists **(PREMIUM)** +### Milestone lists **(PREMIUM ALL)** You're also able to create lists of a milestone. These are lists that filter issues by the assigned milestone, giving you more freedom and visibility on the issue board. @@ -332,7 +332,7 @@ As in other list types, select the trash icon to remove a list.  -### Iteration lists **(PREMIUM)** +### Iteration lists **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250479) in GitLab 13.11 [with a flag](../../administration/feature_flags.md) named `iteration_board_lists`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75404) in GitLab 14.6. Feature flag `iteration_board_lists` removed. @@ -355,7 +355,7 @@ to and from a iteration list to manipulate the iteration of the dragged issues.  -### Group issues in swimlanes **(PREMIUM)** +### Group issues in swimlanes **(PREMIUM ALL)** > - Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in GitLab 13.6. > - Editing issue titles in the issue sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232745) in GitLab 13.8. @@ -401,7 +401,7 @@ You can also [drag issues](#move-issues-and-lists) to change their position and  -## Work in progress limits **(PREMIUM)** +## Work in progress limits **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -428,7 +428,7 @@ To set a WIP limit for a list, in an issue board: 1. Enter the maximum number of issues. 1. Press <kbd>Enter</kbd> to save. -## Blocked issues **(PREMIUM)** +## Blocked issues **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210452) in GitLab 13.10: View blocking issues when hovering over the "blocked" icon. diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index d286e784e0a..bb8f0ccd186 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.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/product/ux/technical-writing/#assignments --- -# Associate a Zoom meeting with an issue **(FREE)** +# Associate a Zoom meeting with an issue **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609) in GitLab 12.4. diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 6c2e6cb2132..0b8f6cc33fc 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -4,10 +4,10 @@ group: Project Management 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 --- -# Confidential issues **(FREE)** +# Confidential issues **(FREE ALL)** Confidential issues are [issues](index.md) visible only to members of a project with -[sufficient permissions](#permissions-and-access-to-confidential-issues). +[sufficient permissions](#who-can-see-confidential-issues). Confidential issues can be used by open source projects and companies alike to keep security vulnerabilities private or prevent surprises from leaking out. @@ -15,6 +15,13 @@ keep security vulnerabilities private or prevent surprises from leaking out. You can make an issue confidential when you create or edit an issue. +Prerequisites: + +- You must have at least the Reporter role for the project. +- If the issue you want to make confidential has any child [tasks](../../tasks.md), + you must first make all the child tasks confidential. + A confidential issue can have only confidential children. + ### In a new issue When you create a new issue, a checkbox right below the text area is available @@ -51,63 +58,40 @@ for the project have access to the issue. Users with Guest or [Minimal](../../permissions.md#users-with-minimal-access) roles can't access the issue even if they were actively participating before the change. +However, a user with the **Guest role** can create confidential issues, but can only view the ones +that they created themselves. + +Users with the Guest role or non-members can read the confidential issue if they are assigned to the issue. +When a Guest user or non-member is unassigned from a confidential issue, they can no longer view it. + +Confidential issues are hidden in search results for users without the necessary permissions. + ## Confidential issue indicators Confidential issues are visually different from regular issues in a few ways. -In the issues index page view, you can see the confidential (**{eye-slash}**) icon -next to the issues that are marked as confidential: - - +In the issues list and boards, you can see the confidential (**{eye-slash}**) icon +next to issues marked as confidential. -If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), +If you don't have [enough permissions](#who-can-see-confidential-issues), you cannot see confidential issues at all. Likewise, while inside the issue, you can see the confidential (**{eye-slash}**) icon right next to the issue number. There is also an indicator in the comment area that the issue you are commenting on is confidential. - - There is also an indicator on the sidebar denoting confidentiality. -| Confidential issue | Not confidential issue | -| :-----------: | :----------: | -|  |  | - Every change from regular to confidential and vice versa, is indicated by a -system note in the issue's comments: +system note in the issue's comments, for example: -- **{eye-slash}** The issue is made confidential. -- **{eye}** The issue is made public. - - +> - **{eye-slash}** Jo Garcia made the issue confidential 5 minutes ago +> - **{eye}** Jo Garcia made the issue visible to everyone just now ## Merge requests for confidential issues Although you can create confidential issues (and make existing issues confidential) in a public project, you cannot make confidential merge requests. Learn how to create [merge requests for confidential issues](../merge_requests/confidential.md) that prevent leaks of private data. -## Permissions and access to confidential issues - -Access to confidential issues is by one of two routes. The general rule -is that confidential issues are visible only to members of a project with at -least the **Reporter role**. - -However, a user with the **Guest role** can create -confidential issues, but can only view the ones that they created themselves. - -Users with the Guest role or non-members can read the confidential issue if they are assigned to the issue. -When a Guest user or non-member is unassigned from a confidential issue, -they can no longer view it. - -Confidential issues are hidden in search results for unprivileged users. -For example, here's what a user with the Maintainer role and the Guest role -sees in the project's search results: - -| Maintainer role | Guest role | -|:----------------|:-----------| -|  |  | - ## Related topics - [Merge requests for confidential issues](../merge_requests/confidential.md) diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md index 8cc9ab71ca7..3014b088fd6 100644 --- a/doc/user/project/issues/create_issues.md +++ b/doc/user/project/issues/create_issues.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/product/ux/technical-writing/#assignments --- -# Create an issue **(FREE)** +# Create an issue **(FREE ALL)** When you create an issue, you are prompted to enter the fields of the issue. If you know the values you want to assign to an issue, you can use @@ -192,7 +192,7 @@ To create an issue in the GitLab project: ## Using Service Desk -To offer email support, enable [Service Desk](../service_desk.md) for your project. +To offer email support, enable [Service Desk](../service_desk/index.md) for your project. Now, when your customer sends a new email, a new issue can be created in the appropriate project and followed up from there. diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index f1f41de7cb4..b3fe7da4280 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.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/product/ux/technical-writing/#assignments --- -# Crosslinking issues **(FREE)** +# Crosslinking issues **(FREE ALL)** There are several ways to mention an issue or make [issues](index.md) appear in each other's [Linked issues](related_issues.md) section. diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 9b131372672..86370cab963 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Export issues to CSV **(FREE)** +# Export issues to CSV **(FREE ALL)** > Moved to GitLab Free in 12.10. diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index d23650e973a..9770c333cdd 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -4,7 +4,7 @@ group: Import and Integrate 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 --- -# Importing issues from CSV **(FREE)** +# Importing issues from CSV **(FREE ALL)** You can import issues to a project by uploading a CSV file with the following columns: diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 6013abc4892..4068083cd1e 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Design management **(FREE)** +# Design management **(FREE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in GitLab 12.2. > - Support for SVGs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in GitLab 12.4. @@ -44,7 +44,7 @@ For a video overview, see [Design Management (GitLab 12.2)](https://www.youtube. A GitLab administrator can verify the storage type of a project by going to **Admin Area > Projects** and then selecting the project in question. A project can be identified as - hashed-stored if its **Gitaly relative path** contains `@hashed`. + hashed-stored if the value of the **Relative path** field contains `@hashed`. If the requirements are not met, you are notified in the **Designs** section. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 63b60e4538f..322d603aced 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.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/product/ux/technical-writing/#assignments --- -# Due dates **(FREE)** +# Due dates **(FREE ALL)** Due dates can be used in [issues](index.md) to keep track of deadlines and make sure features are shipped on time. Users need at least the Reporter role diff --git a/doc/user/project/issues/img/confidential_issues_index_page.png b/doc/user/project/issues/img/confidential_issues_index_page.png Binary files differdeleted file mode 100644 index 16979bf9ac2..00000000000 --- a/doc/user/project/issues/img/confidential_issues_index_page.png +++ /dev/null diff --git a/doc/user/project/issues/img/confidential_issues_issue_page.png b/doc/user/project/issues/img/confidential_issues_issue_page.png Binary files differdeleted file mode 100644 index b349149aa98..00000000000 --- a/doc/user/project/issues/img/confidential_issues_issue_page.png +++ /dev/null diff --git a/doc/user/project/issues/img/confidential_issues_search_guest.png b/doc/user/project/issues/img/confidential_issues_search_guest.png Binary files differdeleted file mode 100644 index dc1b4ba8ad7..00000000000 --- a/doc/user/project/issues/img/confidential_issues_search_guest.png +++ /dev/null diff --git a/doc/user/project/issues/img/confidential_issues_search_master.png b/doc/user/project/issues/img/confidential_issues_search_master.png Binary files differdeleted file mode 100644 index fc01f4da9db..00000000000 --- a/doc/user/project/issues/img/confidential_issues_search_master.png +++ /dev/null diff --git a/doc/user/project/issues/img/confidential_issues_system_notes_v15_4.png b/doc/user/project/issues/img/confidential_issues_system_notes_v15_4.png Binary files differdeleted file mode 100644 index e448f609112..00000000000 --- a/doc/user/project/issues/img/confidential_issues_system_notes_v15_4.png +++ /dev/null diff --git a/doc/user/project/issues/img/sidebar_confidential_issue.png b/doc/user/project/issues/img/sidebar_confidential_issue.png Binary files differdeleted file mode 100644 index 0ef61c7f1b0..00000000000 --- a/doc/user/project/issues/img/sidebar_confidential_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/sidebar_not_confidential_issue.png b/doc/user/project/issues/img/sidebar_not_confidential_issue.png Binary files differdeleted file mode 100644 index c09f8204b37..00000000000 --- a/doc/user/project/issues/img/sidebar_not_confidential_issue.png +++ /dev/null diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index b2cc555d3b7..0b64328fe03 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.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/product/ux/technical-writing/#assignments --- -# Issues **(FREE)** +# Issues **(FREE ALL)** Use issues to collaborate on ideas, solve problems, and plan work. Share and discuss proposals with your team and with outside collaborators. diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index 05c348acf58..b1a1390d3d2 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.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/product/ux/technical-writing/#assignments --- -# Issue weight **(PREMIUM)** +# Issue weight **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 6bf8e2eeb97..02cefaa47ef 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.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/product/ux/technical-writing/#assignments --- -# Manage issues **(FREE)** +# Manage issues **(FREE ALL)** After you create an issue, you can start working with it. @@ -71,8 +71,9 @@ When bulk editing issues in a project, you can edit the following attributes: - [Health status](#health-status) - [Notification](../../profile/notifications.md) subscription - [Iteration](../../group/iterations/index.md) +- [Confidentiality](confidential_issues.md) -### Bulk edit issues from a group **(PREMIUM)** +### Bulk edit issues from a group **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in GitLab 12.1. > - Assigning epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. @@ -388,7 +389,7 @@ Alternatively: 1. Select **Edit title and description** (**{pencil}**). 1. Select **Delete issue**. -## Promote an issue to an epic **(PREMIUM)** +## Promote an issue to an epic **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in GitLab 11.6. > - Moved from GitLab Ultimate to GitLab Premium in 12.8. @@ -414,7 +415,7 @@ Read more about [promoting an issues to epics](../../group/epics/manage_epics.md You can use the `/promote_to_incident` [quick action](../quick_actions.md) to promote the issue to an [incident](../../../operations/incident_management/incidents.md). -## Add an issue to an iteration **(PREMIUM)** +## Add an issue to an iteration **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in GitLab 13.2. > - Moved to GitLab Premium in 13.9. @@ -565,7 +566,7 @@ As you type in the title text box of the **New issue** page, GitLab searches tit across all issues 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 text box. -## Health status **(ULTIMATE)** +## Health status **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in GitLab 12.10. > - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in GitLab 13.4 and later. @@ -606,7 +607,7 @@ until the issue is reopened. You can also set and clear health statuses using the `/health_status` and `/clear_health_status` [quick actions](../quick_actions.md#issues-merge-requests-and-epics). -## Publish an issue **(ULTIMATE)** +## Publish an issue **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.1. diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index 59555e1f675..3ec3b72b173 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.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/product/ux/technical-writing/#assignments --- -# Multiple assignees for issues **(PREMIUM)** +# Multiple assignees for issues **(PREMIUM ALL)** > Moved from Starter to Premium in GitLab 13.9. diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 43acaaf9c2f..10c7899ac30 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Linked issues **(FREE)** +# Linked issues **(FREE ALL)** > The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) from GitLab Premium to GitLab Free in 13.4. @@ -70,7 +70,7 @@ Due to the bi-directional relationship, the relationship no longer appears in ei Access our [permissions](../../permissions.md) page for more information. -## Blocking issues **(PREMIUM)** +## Blocking issues **(PREMIUM ALL)** When you [add a linked issue](#add-a-linked-issue), you can show that it **blocks** or **is blocked by** another issue. diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 4c0566c2386..c365bfa5a52 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -4,12 +4,12 @@ group: Project Management 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 --- -# Sorting and ordering issue lists **(FREE)** +# Sorting and ordering issue lists **(FREE ALL)** You can sort a list of issues several ways. The available sorting options can change based on the context of the list. -## Sorting by blocking issues **(PREMIUM)** +## Sorting by blocking issues **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34247/) in GitLab 13.7. @@ -105,7 +105,7 @@ title in this order: - Numbers - Letters: first Latin, then accented (for example, `ö`) -## Sorting by health status **(ULTIMATE)** +## Sorting by health status **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377841) in GitLab 15.7. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 7f98b62cabf..4daaaf72683 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.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/product/ux/technical-writing/#assignments --- -# Labels **(FREE)** +# Labels **(FREE ALL)** As your count of issues, merge requests, and epics grows in GitLab, it gets more challenging to keep track of those items. Especially as your organization grows from just a few people to @@ -153,7 +153,7 @@ To create a group label: a specific color in the **Background color** field. 1. Select **Create label**. -### Create a group label from an epic **(PREMIUM)** +### Create a group label from an epic **(PREMIUM ALL)** You can also create a new group label from an epic. Labels you create this way belong to the same group as the epic. @@ -317,7 +317,7 @@ The following labels are created: - `suggestion` - `support` -## Scoped labels **(PREMIUM)** +## Scoped labels **(PREMIUM ALL)** Teams can use scoped labels to annotate issues, merge requests, and epics with mutually exclusive labels. By preventing certain labels from being used together, you can create more complex workflows. @@ -455,6 +455,13 @@ The labels higher in the list get higher priority. To learn what happens when you sort by priority or label priority, see [Sorting and ordering issue lists](issues/sorting_issue_lists.md). +## Related topics + +Practice working with labels in the following tutorials: + +- [Set up a single project for issue triage](../../tutorials/issue_triage/index.md) +- [Set up issue boards for team hand-off](../../tutorials/boards_for_teams/index.md) + ## Troubleshooting ### Some label titles end with `_duplicate<number>` diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 37b24cda5aa..1e9bd307333 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -4,7 +4,7 @@ group: Tenant Scale 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 --- -# Members of a project **(FREE)** +# Members of a project **(FREE ALL)** Members are the users and groups who have access to your project. @@ -79,7 +79,7 @@ and rights into the group or project. | View labels of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | | View milestones of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | | Be shared into other groups | ✓ | | | | -| Be shared into other projects | ✓ | ✓ | | | +| Be shared into other projects | ✓ | ✓ | ✓ | ✓ | | Share the group with other members | ✓ | ✓ | ✓ | ✓ | In the following example, `User` is a: @@ -108,6 +108,7 @@ graph TD > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. > - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. +> - Expiring access email notification [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.2. Add users to a project so they become direct members and have permission to perform actions. @@ -130,6 +131,9 @@ To add a user to a project: 1. Optional. Select an **Access expiration date**. From that date onward, the user can no longer access the project. + If you selected an access expiration date, the project member gets an email notification + seven days before their access expires. + WARNING: If you give a member the Maintainer role and select an expiration date, that member has full permissions for the time they are in the role. This includes the ability diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 15c5935648f..3780018bf11 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -4,7 +4,7 @@ group: Tenant Scale 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 --- -# Share a project with a group **(FREE)** +# Share a project with a group **(FREE ALL)** When you want a group to have access to your project, you can invite [a group](../../group/index.md) to the project. @@ -30,7 +30,7 @@ In addition: - You must be a member of the group or the subgroup being invited. -- The [visibility level](../../public_access.md#project-and-group-visibility) of the group you're inviting +- The [visibility level](../../public_access.md) of the group you're inviting must be at least as restrictive as that of the project. For example, you can invite: - A _private_ group to a _private_ project - A _private_ group to an _internal_ project. diff --git a/doc/user/project/merge_requests/ai_in_merge_requests.md b/doc/user/project/merge_requests/ai_in_merge_requests.md new file mode 100644 index 00000000000..c1aa729d8c5 --- /dev/null +++ b/doc/user/project/merge_requests/ai_in_merge_requests.md @@ -0,0 +1,120 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# AI/ML powered features in merge requests + +AI-assisted features in merge requests are designed to provide contextually relevant information during the lifecycle of a merge request. + +Additional information on enabling these features and maturity can be found in our [AI/ML Overview](../../ai_features.md). + +## Fill in merge request templates **(ULTIMATE SAAS)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10591) in GitLab 16.3 as an [Experiment](../../../policy/experiment-beta-support.md#experiment). + +This feature is an [Experiment](../../../policy/experiment-beta-support.md) on GitLab.com that is using Google's Vertex service and the `text-bison` model. It requires the [group-level third-party AI features setting](../../group/manage.md#enable-third-party-ai-features) to be enabled. + +Merge requests in projects often have [templates](../description_templates.md#create-a-merge-request-template) defined that need to be filled out. This helps reviewers and other users understand the purpose and changes a merge request might propose. + +When creating a merge request you can now choose to generate a description for the merge request based on the contents of the template. This fills in the template and replaces the current contents of the description. + +To generate the description: + +1. Create a new merge request, go to the **Description** field. +1. Select **AI Actions** (**{tanuki}**). +1. Select **Fill in merge request template**. + +The updated description is applied to the box. You can edit or revise this description before you finish creating your merge request. + +Provide feedback on this experimental feature in [issue 416537](https://gitlab.com/gitlab-org/gitlab/-/issues/416537). + +**Data usage**: When you use this feature, the following data is sent to the large language model referenced above: + +- Title of the merge request +- Contents of the description +- Source branch name +- Target branch name + +## Summarize merge request changes **(ULTIMATE SAAS)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10401) in GitLab 16.2 as an [Experiment](../../../policy/experiment-beta-support.md#experiment). + +This feature is an [Experiment](../../../policy/experiment-beta-support.md) on GitLab.com that is using Google's Vertex service and the `text-bison` model. It requires the [group-level third-party AI features setting](../../group/manage.md#enable-third-party-ai-features) to be enabled. + +These summaries are automatically generated. They are available on the merge request page in the **Merge request summaries** dialog, the To-Do list, and in email notifications. + +Provide feedback on this experimental feature in [issue 408726](https://gitlab.com/gitlab-org/gitlab/-/issues/408726). + +**Data usage**: The diff of changes between the source branch's head and the target branch is sent to the large language model. + +## Summarize my merge request review **(ULTIMATE SAAS)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10466) in GitLab 16.0 as an [Experiment](../../../policy/experiment-beta-support.md#experiment). + +This feature is an [Experiment](../../../policy/experiment-beta-support.md) on GitLab.com that is using Google's Vertex service and the `text-bison` model. It requires the [group-level third-party AI features setting](../../group/manage.md#enable-third-party-ai-features) to be enabled. + +When you've completed your review of a merge request and are ready to [submit your review](reviews/index.md#submit-a-review), you can have a summary generated for you. + +To generate the summary: + +1. When you are ready to submit your review, select **Finish review**. +1. Select **AI Actions** (**{tanuki}**). +1. Select **Summarize my code review**. + +The summary is displayed in the comment box. You can edit and refine the summary prior to submitting your review. + +Merge request review summaries are also automatically generated when you submit your review. These automatically generated summaries are available on the merge request page in the **Merge request summaries** dialog, the To-Do list, and in email notifications. + +Provide feedback on this experimental feature in [issue 408991](https://gitlab.com/gitlab-org/gitlab/-/issues/408991). + +**Data usage**: When you use this feature, the following data is sent to the large language model referenced above: + +- Draft comment's text + +## Suggested merge or squash commit message **(ULTIMATE SAAS)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10453) in GitLab 16.2 as an [Experiment](../../../policy/experiment-beta-support.md#experiment). + +This feature is an [Experiment](../../../policy/experiment-beta-support.md) on GitLab.com that is using Google's Vertex service and the `text-bison` model. It requires the [group-level third-party AI features setting](../../group/manage.md#enable-third-party-ai-features) to be enabled. + +When preparing to merge your merge request you may wish to edit the squash or merge commit message that will be used. + +To generate a commit message: + +1. Select the **Edit commit message** checkbox on the merge widget. +1. Select **Create AI-generated commit message**. +1. Review the commit message provide and choose **Insert** to add it to the commit. + +Provide feedback on this experimental feature in [issue 408994](https://gitlab.com/gitlab-org/gitlab/-/issues/408994). + +**Data usage**: When you use this feature, the following data is sent to the large language model referenced above: + +- Contents of the file +- The filename + +## Generate suggested tests in merge requests **(ULTIMATE SAAS)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10366) in GitLab 16.0 as an [Experiment](../../../policy/experiment-beta-support.md#experiment). + +This feature is an [Experiment](../../../policy/experiment-beta-support.md) on GitLab.com that is using Google's Vertex service and the `text-bison` model. It requires the [group-level third-party AI features setting](../../group/manage.md#enable-third-party-ai-features) to be enabled. + +In a merge request, you can get a list of suggested tests for the file you are reviewing. This functionality can help determine if appropriate test coverage has been provided, or if you need more coverage for your project. + +View a [click-through demo](https://go.gitlab.com/Xfp0l4). + +To generate a test suggestion: + +1. In a merge request, select the **Changes** tab. +1. On the header for the file, in the upper-right corner, select **Options** (**{ellipsis_v}**). +1. Select **Suggest test cases**. + +The test suggestion is generated in a sidebar. You can copy the suggestion to your editor and use it as the start of your tests. + +Feedback on this experimental feature can be provided in [issue 408995](https://gitlab.com/gitlab-org/gitlab/-/issues/408995). + +**Data usage**: When you use this feature, the following data is sent to the large language model referenced above: + +- Contents of the file +- The filename diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 4cc8f50dd70..8ca87f4518e 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -4,7 +4,7 @@ group: Code Review 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 --- -# Collaborate on merge requests across forks **(FREE)** +# Collaborate on merge requests across forks **(FREE ALL)** When you open a merge request from your [fork](../repository/forking_workflow.md), you can allow upstream members to collaborate with you on your branch. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 0dcf5f37d65..bace1dfb8b5 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge request approvals **(FREE)** +# Merge request approvals **(FREE ALL)** You can configure your merge requests so that they must be approved before they can be merged. While [GitLab Free](https://about.gitlab.com/pricing/) allows @@ -87,7 +87,7 @@ GitLab allows all users with Developer or greater [permissions](../../../permiss to approve merge requests. Approvals in GitLab Free are optional, and don't prevent a merge request from merging without approval. -## Required approvals **(PREMIUM)** +## Required approvals **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 169c7a09875..cbbeac17355 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Merge request approval rules **(PREMIUM)** +# Merge request approval rules **(PREMIUM ALL)** Approval rules define how many [approvals](index.md) a merge request must receive before it can be merged, and which users should do the approving. They can be used in conjunction @@ -259,7 +259,7 @@ coverage. For more information, see [Coverage check approval rule](../../../../ci/testing/code_coverage.md#coverage-check-approval-rule). -## Security Approvals **(ULTIMATE)** +## Security Approvals **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. > - Bot comment for approvals [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/411656) in GitLab 16.2 [with a flag](../../../../administration/feature_flags.md) named `security_policy_approval_notification`. Enabled by default. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index eed8cbcd94d..b520ee41493 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Merge request approval settings **(PREMIUM)** +# Merge request approval settings **(PREMIUM ALL)** You can configure the settings for [merge request approvals](index.md) to ensure the approval rules meet your use case. You can also configure @@ -63,7 +63,8 @@ this setting, unless you configure one of these options: ## Prevent approvals by users who add commits -> Moved to GitLab Premium in 13.9. +> - Moved to GitLab Premium in 13.9. +> - [Feature flag `keep_merge_commits_for_approvals`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127744) added in GitLab 16.3 to also include merge commits in this check. By default, users who commit to a merge request can still approve it. At both the project level or [instance level](../../../admin_area/merge_requests_approvals.md), @@ -172,5 +173,5 @@ that inherited them. ## Related topics - [Instance-level merge request approval settings](../../../admin_area/merge_requests_approvals.md) -- [Compliance report](../../../compliance/compliance_report/index.md) +- [Compliance center](../../../compliance/compliance_center/index.md) - [Merge request approvals API](../../../../api/merge_request_approvals.md) diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 280ad20712b..75c9083332a 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts --- -# Merge request workflows **(FREE)** +# Merge request workflows **(FREE ALL)** There are two main ways to have a merge request flow with GitLab: diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index 79599580f3e..ab882af7eda 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Changes in merge requests **(FREE)** +# Changes in merge requests **(FREE ALL)** A [merge request](index.md) proposes a set of changes to files in a branch in your repository. These changes are shown as a _diff_ (difference) between the current state and the proposed @@ -16,6 +16,10 @@ to the files in the target branch, and shows only the parts of a file that have  +For technical details on how GitLab calculates the diff between the two revisions, +read [Working with diffs](../../../development/merge_request_concepts/diffs/index.md) +in our development documentation. + ## Show all changes in a merge request To view the diff of changes included in a merge request: @@ -23,9 +27,9 @@ To view the diff of changes included in a merge request: 1. Go to your merge request. 1. Below the merge request title, select **Changes**. 1. If the merge request changes many files, you can jump directly to a specific file: - 1. Select **Show file browser** (**{file-tree}**) to display the file tree. + 1. Select **Show file browser** (**{file-tree}**) or press <kbd>F</kbd> to display the file tree. 1. Select the file you want to view. - 1. To hide the file browser, select **Show file browser** again. + 1. To hide the file browser, select **Show file browser** or press <kbd>F</kbd> again. Files with many changes are collapsed to improve performance. GitLab displays the message: **Some changes are not shown**. To view the changes for that file, select **Expand file**. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 6669b2883a4..d9b2ecf0806 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Cherry-pick changes **(FREE)** +# Cherry-pick changes **(FREE ALL)** In Git, *cherry-picking* is taking a single commit from one branch and adding it as the latest commit on another branch. The rest of the commits in the source branch diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index c930c5c6f7f..1fc7188ffea 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Commit message templates **(FREE)** +# Commit message templates **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) squash commit templates in GitLab 14.6. @@ -72,6 +72,7 @@ GitLab creates a squash commit message with this template: > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/26303) `all_commits` variable in GitLab 14.9. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/378352) `reviewed_by` variable in GitLab 15.7. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/199823) `local_reference` variable in GitLab 16.1. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128553) `source_project_id` variables in GitLab 16.3. Commit message templates support these variables: @@ -84,6 +85,7 @@ Commit message templates support these variables: | `%{description}` | Description of the merge request. | `Merge request description.`<br>`Can be multiline.` | | `%{reference}` | Reference to the merge request. | `group-name/project-name!72359` | | `%{local_reference}` | Local reference to the merge request. | `!72359` | +| `%{source_project_id}` | ID of the merge request's source project. | `123` | | `%{first_commit}` | Full message of the first commit in merge request diff. | `Update README.md` | | `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge request title if all commits aren't multiline. | `Update README.md`<br><br>`Improved project description in readme file.` | | `%{url}` | Full URL to the merge request. | `https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1` | diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index a36e45d159a..ddd2a0ddcb5 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Merge request commits **(FREE)** +# Merge request commits **(FREE ALL)** Each merge request has a history of the commits made to the source branch after the merge request was created. diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md index edcc5711b98..901da6d4cf8 100644 --- a/doc/user/project/merge_requests/confidential.md +++ b/doc/user/project/merge_requests/confidential.md @@ -4,7 +4,7 @@ group: Code Review 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 --- -# Merge requests for confidential issues **(FREE)** +# Merge requests for confidential issues **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58583) in GitLab 12.1. diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index 44cef4d63e5..fefc6aabddf 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge conflicts **(FREE)** +# Merge conflicts **(FREE ALL)** _Merge conflicts_ happen when the two branches in a merge request (the source and target) each have different changes, and you must decide which change to accept. In a merge request, Git compares diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 4eb4476422f..e31460c1997 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: "How to create merge requests in GitLab." --- -# Creating merge requests **(FREE)** +# Creating merge requests **(FREE ALL)** GitLab provides many different ways to create a merge request. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index f8988ae7bd7..15b2e53d7d9 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -4,7 +4,7 @@ group: Compliance 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 --- -# Export merge requests to CSV **(FREE)** +# Export merge requests to CSV **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3619) in GitLab 13.6. diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md index 1cd81e2aac2..b80698f99c3 100644 --- a/doc/user/project/merge_requests/dependencies.md +++ b/doc/user/project/merge_requests/dependencies.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge request dependencies **(PREMIUM)** +# Merge request dependencies **(PREMIUM ALL)** A single feature can span several merge requests, spread out across multiple projects, and the order in which the work merges can be significant. Use merge request dependencies diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index ff5421d5785..85ebc75e61f 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Draft merge requests **(FREE)** +# Draft merge requests **(FREE ALL)** If a merge request isn't ready to merge, potentially because of continued development or open threads, you can prevent it from being accepted before you diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index dfa62628e46..3ad07d0377e 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Merge requests **(FREE)** +# Merge requests **(FREE ALL)** To incorporate changes from a source branch to a target branch, you use a *merge request* (MR). @@ -18,10 +18,6 @@ Merge requests include: - A comment section for discussion threads. - The list of commits. -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a quick overview of merge requests, -view [this GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE). - ## Create a merge request Learn the various ways to [create a merge request](creating_merge_requests.md). @@ -168,7 +164,7 @@ a merge request, or: The merge request is added to the user's assigned merge request list. -### Assign multiple users **(PREMIUM)** +### Assign multiple users **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -284,7 +280,7 @@ For a software developer working in a team: 1. You gather feedback from your team. 1. You work on the implementation optimizing code with [Code Quality reports](../../../ci/testing/code_quality.md). 1. You verify your changes with [Unit test reports](../../../ci/testing/unit_test_reports.md) in GitLab CI/CD. -1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../compliance/license_compliance/index.md). +1. You avoid using dependencies whose license is not compatible with your project with [License approval policies](../../../user/compliance/license_approval_policies.md). 1. You request the [approval](approvals/index.md) from your manager. 1. Your manager: 1. Pushes a commit with their final review. diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index 66c3b1fda74..16482d92d7e 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Auto-merge **(FREE)** +# Auto-merge **(FREE ALL)** > **Merge when pipeline succeeds** and **Add to merge train when pipeline succeeds** [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409530) to **Auto-merge** in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `auto_merge_labels_mr_widget`. Enabled by default. @@ -41,6 +41,7 @@ To do this from the GitLab user interface: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Code > Merge requests**. +1. Select the merge request to edit. 1. Scroll to the merge request reports section. 1. Optional. Select your desired merge options, such as **Delete source branch**, **Squash commits**, or **Edit commit message**. @@ -64,6 +65,7 @@ To do this: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Code > Merge requests**. +1. Select the merge request to edit. 1. Scroll to the merge request reports section. 1. Select **Cancel auto-merge**. diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index 7bb10303d7e..7eac0e8839a 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge methods **(FREE)** +# Merge methods **(FREE ALL)** The merge method you select for your project determines how the changes in your merge requests are merged into an existing branch. diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index c4288a7793c..14e2ff84eae 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -4,7 +4,7 @@ group: Code Review 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 --- -# Revert changes **(FREE)** +# Revert changes **(FREE ALL)** You can revert individual commits or an entire merge request in GitLab. When you revert a commit in Git, you create a new commit that reverses all actions diff --git a/doc/user/project/merge_requests/reviews/data_usage.md b/doc/user/project/merge_requests/reviews/data_usage.md index f0eb3c015b6..24e3b6a5667 100644 --- a/doc/user/project/merge_requests/reviews/data_usage.md +++ b/doc/user/project/merge_requests/reviews/data_usage.md @@ -1,6 +1,6 @@ --- -stage: ModelOps -group: Applied ML +stage: AI-powered +group: AI Model Validation 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 type: index, reference --- diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 54ebfd9eecb..e4882134654 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Merge request reviews **(FREE)** +# Merge request reviews **(FREE ALL)** [Merge requests](../index.md) are the primary method of making changes to files in a GitLab project. [Create and submit a merge request](../creating_merge_requests.md) @@ -159,7 +159,7 @@ If you have a review in progress, you can also add a comment from the **Overview  -### Approval Rule information for Reviewers **(PREMIUM)** +### Approval Rule information for Reviewers **(PREMIUM ALL)** When editing the **Reviewers** field in a new or existing merge request, GitLab displays the name of the matching [approval rule](../approvals/rules.md) @@ -225,7 +225,7 @@ To update multiple project merge requests at the same time: 1. Select the appropriate fields and their values from the sidebar. 1. Select **Update all**. -## Bulk edit merge requests at the group level **(PREMIUM)** +## Bulk edit merge requests at the group level **(PREMIUM ALL)** Users with at least the Developer role can manage merge requests. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index f949dba85dd..4857d58933a 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Suggest changes **(FREE)** +# Suggest changes **(FREE ALL)** Reviewers can suggest code changes with a Markdown syntax in merge request diff threads. The merge request author (or other users with the appropriate role) can apply any or diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index b9b8485021b..ea999fe039a 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Squash and merge **(FREE)** +# Squash and merge **(FREE ALL)** As you work on a feature branch, you often create small, self-contained commits. These small commits help describe the process of building a feature, but can clutter your Git history after the feature diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index a151a7cbf1b..e0e65c99433 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# External status checks **(ULTIMATE)** +# External status checks **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0, disabled behind the `:ff_external_status_checks` feature flag. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320783) in GitLab 14.1. diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 120e300da5e..a5635d22530 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -4,7 +4,7 @@ group: Code Review 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 --- -# Merge requests versions **(FREE)** +# Merge requests versions **(FREE ALL)** Every time you push to a branch that is tied to a merge request, a new version of merge request diff is created. When you visit a merge request that contains diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md index 639552ca75a..da766b685a3 100644 --- a/doc/user/project/merge_requests/widgets.md +++ b/doc/user/project/merge_requests/widgets.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Merge request widgets **(FREE)** +# Merge request widgets **(FREE ALL)** The **Overview** page of a merge request displays status updates from services that perform actions on your merge request. All subscription levels display a @@ -63,13 +63,13 @@ faster to preview proposed modifications. [Read more about Review Apps](../../../ci/review_apps/index.md). -## License compliance **(ULTIMATE)** +## License compliance **(ULTIMATE ALL)** If you have configured [License Compliance](../../compliance/license_scanning_of_cyclonedx_files/index.md) for your project, then you can view a list of licenses that are detected for your project's dependencies.  -## External status checks **(ULTIMATE)** +## External status checks **(ULTIMATE ALL)** If you have configured [external status checks](status_checks.md) you can see the status of these checks in merge requests diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 59b11e78622..7c9a5a37292 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Burndown and burnup charts **(PREMIUM)** +# Burndown and burnup charts **(PREMIUM ALL)** [Burndown](#burndown-charts) and [burnup](#burnup-charts) charts show the progress of completing a milestone. diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 47325ee7c90..4bb751aedc5 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Milestones **(FREE)** +# Milestones **(FREE ALL)** Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time. diff --git a/doc/user/project/ml/experiment_tracking/img/candidate_detail_ci_v16_12.png b/doc/user/project/ml/experiment_tracking/img/candidate_detail_ci_v16_12.png Binary files differindex fb4f8d5dc66..8826067f56b 100644 --- a/doc/user/project/ml/experiment_tracking/img/candidate_detail_ci_v16_12.png +++ b/doc/user/project/ml/experiment_tracking/img/candidate_detail_ci_v16_12.png diff --git a/doc/user/project/ml/experiment_tracking/index.md b/doc/user/project/ml/experiment_tracking/index.md index 4e9e736f067..d4516746afc 100644 --- a/doc/user/project/ml/experiment_tracking/index.md +++ b/doc/user/project/ml/experiment_tracking/index.md @@ -4,7 +4,7 @@ group: Incubation info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering program. No technical writer assigned to this group. --- -# Machine learning model experiments **(FREE)** +# Machine learning model experiments **(FREE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9341) in GitLab 15.11 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. To enable the feature, an administrator can [enable the feature flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95373) in GitLab 16.2. @@ -71,7 +71,7 @@ on how to use GitLab as a backend for the MLflow Client. To list the current active experiments, either go to `https/-/ml/experiments` or: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Deploy > Model experiments**. +1. Select **Analyze > Model experiments**. 1. To display all candidates that have been logged, along with their metrics, parameters, and metadata, select an experiment. 1. To display details for a candidate, select **Details**. diff --git a/doc/user/project/ml/experiment_tracking/mlflow_client.md b/doc/user/project/ml/experiment_tracking/mlflow_client.md index 7fd5c7cca92..3e78cc5b7f2 100644 --- a/doc/user/project/ml/experiment_tracking/mlflow_client.md +++ b/doc/user/project/ml/experiment_tracking/mlflow_client.md @@ -4,7 +4,7 @@ group: Incubation info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering program. No technical writer assigned to this group. --- -# MLflow client compatibility **(FREE)** +# MLflow client compatibility **(FREE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.11 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. @@ -76,30 +76,30 @@ candidate metadata. To associate a candidate to a CI/CD job: GitLab supports these methods from the MLflow client. Other methods might be supported but were not tested. More information can be found in the [MLflow Documentation](https://www.mlflow.org/docs/1.28.0/python_api/mlflow.html). -| Method | Supported | Version Added | Comments | -|--------------------------|------------------|----------------|----------| -| `get_experiment` | Yes | 15.11 | | -| `get_experiment_by_name` | Yes | 15.11 | | -| `set_experiment` | Yes | 15.11 | | -| `get_run` | Yes | 15.11 | | -| `start_run` | Yes | 15.11 | | -| `log_artifact` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty string. Does not support directories. -| `log_artifacts` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty string. Does not support directories. -| `log_batch` | Yes | 15.11 | | -| `log_metric` | Yes | 15.11 | | -| `log_metrics` | Yes | 15.11 | | -| `log_param` | Yes | 15.11 | | -| `log_params` | Yes | 15.11 | | -| `log_figure` | Yes | 15.11 | | -| `log_image` | Yes | 15.11 | | -| `log_text` | Yes with caveat | 15.11 | (15.11) Does not support directories. -| `log_dict` | Yes with caveat | 15.11 | (15.11) Does not support directories. -| `set_tag` | Yes | 15.11 | | -| `set_tags` | Yes | 15.11 | | -| `set_terminated` | Yes | 15.11 | | -| `end_run` | Yes | 15.11 | | -| `update_run` | Yes | 15.11 | | -| `log_model` | Partial | 15.11 | (15.11) Saves the artifacts, but not the model data. `artifact_path` must be empty. +| Method | Supported | Version Added | Comments | +|--------------------------|------------------|----------------|-------------------------------------------------------------------------------------| +| `get_experiment` | Yes | 15.11 | | +| `get_experiment_by_name` | Yes | 15.11 | | +| `set_experiment` | Yes | 15.11 | | +| `get_run` | Yes | 15.11 | | +| `start_run` | Yes | 15.11 | (16.3) If a name is not provided, the candidate receives a random nickname. | +| `log_artifact` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty. Does not support directories. | +| `log_artifacts` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty. Does not support directories. | +| `log_batch` | Yes | 15.11 | | +| `log_metric` | Yes | 15.11 | | +| `log_metrics` | Yes | 15.11 | | +| `log_param` | Yes | 15.11 | | +| `log_params` | Yes | 15.11 | | +| `log_figure` | Yes | 15.11 | | +| `log_image` | Yes | 15.11 | | +| `log_text` | Yes with caveat | 15.11 | (15.11) Does not support directories. | +| `log_dict` | Yes with caveat | 15.11 | (15.11) Does not support directories. | +| `set_tag` | Yes | 15.11 | | +| `set_tags` | Yes | 15.11 | | +| `set_terminated` | Yes | 15.11 | | +| `end_run` | Yes | 15.11 | | +| `update_run` | Yes | 15.11 | | +| `log_model` | Partial | 15.11 | (15.11) Saves the artifacts, but not the model data. `artifact_path` must be empty. | ## Limitations diff --git a/doc/user/project/organize_work_with_projects.md b/doc/user/project/organize_work_with_projects.md index 85a1dfda679..b280a2645c5 100644 --- a/doc/user/project/organize_work_with_projects.md +++ b/doc/user/project/organize_work_with_projects.md @@ -4,7 +4,7 @@ group: Tenant Scale 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 --- -# Organize work with projects **(FREE)** +# Organize work with projects **(FREE ALL)** In GitLab, you can create projects to host your codebase. You can also use projects to track issues, plan work, 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 5cdf493fe6f..4d8675b104d 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 @@ -5,7 +5,7 @@ group: Knowledge 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 --- -# GitLab Pages DNS records **(FREE)** +# GitLab Pages DNS records **(FREE ALL)** A Domain Name System (DNS) web service routes visitors to websites by translating domain names (such as `www.example.com`) into the 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 0601e236a08..8bf4875ba1e 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 @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# GitLab Pages custom domains **(FREE)** +# GitLab Pages custom domains **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238461) in GitLab 15.4, you can use verified domains to [bypass user email confirmation for SAML- or SCIM-provisioned users](../../../group/saml_sso/index.md#bypass-user-email-confirmation-with-verified-domains). @@ -25,6 +25,7 @@ To set up Pages with a custom domain name, read the requirements and steps below ### Prerequisites +- An administrator has configured the server for [GitLab Pages custom domains](../../../../administration/pages/index.md#advanced-configuration) - A GitLab Pages website up and running, served under the default Pages domain (`*.gitlab.io`, for GitLab.com). - A custom domain name `example.com` or subdomain `subdomain.example.com`. @@ -32,17 +33,6 @@ To set up Pages with a custom domain name, read the requirements and steps below - A DNS record (`A`, `ALIAS`, or `CNAME`) pointing your domain to the GitLab Pages server. If there are multiple DNS records on that name, you must use an `ALIAS` record. - A DNS `TXT` record to verify your domain's ownership. -- Set either `external_http` or `external_https` in `/etc/gitlab/gitlab.rb` to the IP and port of - your [Pages daemon](../../../../administration/pages/index.md#the-gitlab-pages-daemon). - If you don't have IPv6, you can omit the IPv6 address. - - Example: - - ```ruby - # Redirect pages from HTTP to HTTPS - gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001:db8::2]:80'] # The secondary IPs for the GitLab Pages daemon - gitlab_pages['external_https'] = ['192.0.2.2:443', '[2001:db8::2]:443'] # The secondary IPs for the GitLab Pages daemon - ``` ### Steps @@ -301,6 +291,33 @@ To enable this setting: If you use Cloudflare CDN in front of GitLab Pages, make sure to set the SSL connection setting to `full` instead of `flexible`. For more details, see the [Cloudflare CDN directions](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). +## Edit a custom domain + +You can edit a custom domain to: + +- View the custom domain. +- View the DNS record to add. +- View the TXT verification entry. +- Retry verification. +- Edit the certificate settings. + +To edit a custom domain: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Deploy > Pages**. +1. Next to the domain name, select **Edit**. + +## Delete a custom domain + +After a custom domain is deleted, the domain is no longer verified in GitLab and cannot be used with GitLab Pages. + +To delete and remove a custom domain: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Deploy > Pages**. +1. Next to the domain name, select **Remove**. +1. When prompted, select **Remove domain**. + ## Troubleshooting ### Domain verification 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 878613c3b9c..5c1fc41d947 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 @@ -6,7 +6,7 @@ group: Knowledge 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 --- -# GitLab Pages Let's Encrypt certificates **(FREE)** +# GitLab Pages Let's Encrypt certificates **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28996) in GitLab 12.1. 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 484dc784fdb..f42fdf4fc40 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 @@ -5,7 +5,7 @@ group: Knowledge 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 --- -# GitLab Pages SSL/TLS certificates **(FREE)** +# GitLab Pages SSL/TLS certificates **(FREE ALL)** Every GitLab Pages project on GitLab.com is available under HTTPS for the default Pages domain (`*.gitlab.io`). Once you set 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 02e662d15b3..f8ee3f10d1e 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 @@ -5,7 +5,7 @@ group: Knowledge 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 --- -# Create a GitLab Pages website from a CI/CD template **(FREE)** +# Create a GitLab Pages website from a CI/CD template **(FREE ALL)** GitLab provides `.gitlab-ci.yml` templates for the most popular Static Site Generators (SSGs). You can create your own `.gitlab-ci.yml` file from one of these templates, and run 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 8332d96d99e..e3b3b99b8e1 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 @@ -5,7 +5,7 @@ group: Knowledge 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 --- -# Create a GitLab Pages website from a forked sample project **(FREE)** +# Create a GitLab Pages website from a forked sample project **(FREE ALL)** GitLab provides [sample projects for the most popular Static Site Generators (SSG)](https://gitlab.com/pages). You can fork one of the sample projects and run the CI/CD pipeline to generate a Pages website. diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 51f53860fee..545fc6a568b 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# Tutorial: Create a GitLab Pages website from scratch **(FREE)** +# Tutorial: Create a GitLab Pages website from scratch **(FREE ALL)** This tutorial shows you how to create a Pages site from scratch using the [Jekyll](https://jekyllrb.com/) Static Site Generator (SSG). You start with diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index ae0dd9507ad..fe073fe6de7 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# Create a GitLab Pages website from a project template **(FREE)** +# Create a GitLab Pages website from a project template **(FREE ALL)** GitLab provides templates for the most popular Static Site Generators (SSGs). You can create a new project from a template and run the CI/CD pipeline to generate a Pages website. diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index 94dab9dfd17..ab3c12427b3 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# Create a GitLab Pages deployment for a static site **(FREE)** +# Create a GitLab Pages deployment for a static site **(FREE ALL)** If you already have a GitLab project that contains your static site or framework, you can generate a GitLab Pages website from it. diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 6eb996db210..e44a7bf347f 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# GitLab Pages default domain names and URLs **(FREE)** +# GitLab Pages default domain names and URLs **(FREE ALL)** On this document, learn how to name your project for GitLab Pages according to your intended website's URL. diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index e3a32a9afe9..418c97c9433 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -5,7 +5,7 @@ group: Knowledge 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 --- -# GitLab Pages **(FREE)** +# GitLab Pages **(FREE ALL)** With GitLab Pages, you can publish static websites directly from a repository in GitLab. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index d00af81c10e..4585ee2cecd 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# GitLab Pages settings **(FREE)** +# GitLab Pages settings **(FREE ALL)** This document is a user guide to explore the options and settings GitLab Pages offers. @@ -93,6 +93,7 @@ you can create your project first and access it under `http(s)://namespace.examp > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9347) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `pages_unique_domain`. Disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/388151) in GitLab 15.11. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122229) in GitLab 16.3. By default, every project in a group shares the same domain, for example, `group.gitlab.io`. This means that cookies are also shared for all projects in a group. diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 1b046d03f59..26f28be72ae 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# GitLab Pages access control **(FREE)** +# GitLab Pages access control **(FREE ALL)** You can enable Pages access control on your project if your administrator has [enabled the access control feature](../../../administration/pages/index.md#access-control) diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index 68023b87560..8471a4ec55a 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -6,7 +6,7 @@ group: Knowledge 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 --- -# GitLab Pages public folder **(FREE)** +# GitLab Pages public folder **(FREE ALL)** > With GitLab 16.1 we introduced the ability to configure the published folder in `.gitlab-ci.yml`, so you longer need to change your framework config. For more information, see how to [set a custom folder to be deployed with Pages](introduction.md#customize-the-default-folder). diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index bd8206b3bda..5f1f5bc59ae 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# GitLab Pages redirects **(FREE)** +# GitLab Pages redirects **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/367) in GitLab 13.5. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 78384249abc..505f1a530cd 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Protected branches **(FREE)** +# Protected branches **(FREE ALL)** In GitLab, [permissions](../permissions.md) are fundamentally defined around the idea of having read or write permission to the repository and branches. To impose @@ -98,6 +98,7 @@ To protect a branch: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to merge** list, select a role that can merge into this branch. 1. From the **Allowed to push and merge** list, select a role that can push to this branch. @@ -110,7 +111,7 @@ To protect a branch: The protected branch displays in the list of protected branches. -### For all projects in a group **(PREMIUM)** +### For all projects in a group **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106532) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `group_protected_branches`. Disabled by default. @@ -135,6 +136,7 @@ To protect a branch for all the projects in a group: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. In the **Branch** text box, type the branch name or a wildcard. 1. From the **Allowed to merge** list, select a role that can merge into this branch. 1. From the **Allowed to push and merge** list, select a role that can push to this branch. @@ -158,6 +160,7 @@ To protect multiple branches at the same time: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. From the **Branch** dropdown list, type the branch name and a wildcard. For example: @@ -200,12 +203,12 @@ To create a new branch through the user interface: ## Require everyone to submit merge requests for a protected branch You can force everyone to submit a merge request, rather than allowing them to -check in directly to a protected branch. This setting is compatible with workflows -like the [GitLab workflow](../../topics/gitlab_flow.md). +check in directly to a protected branch: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to merge** list, select **Developers + Maintainers**. 1. From the **Allowed to push and merge** list, select **No one**. @@ -218,6 +221,7 @@ You can allow everyone with write access to push to the protected branch. 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push and merge** list, select **Developers + Maintainers**. 1. Select **Protect**. @@ -246,6 +250,7 @@ To allow a deploy key to push to a protected branch: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push and merge** list, select the deploy key. 1. Select **Protect**. @@ -265,6 +270,7 @@ To protect a new branch and enable force push: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push and merge** and **Allowed to merge** lists, select the settings you want. 1. To allow all users with push access to force push, turn on the **Allowed to force push** toggle. @@ -277,6 +283,7 @@ To enable force pushes on branches that are already protected: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. In the list of protected branches, next to the branch, turn on the **Allowed to force push** toggle. Members who can push to this branch can now also force push. @@ -305,7 +312,7 @@ Force push settings for a branch at the project level are overridden by group le if the `group_protected_branches` feature flag is enabled and a group owner has set [group level protection for the same branch](#for-all-projects-in-a-group). -## Require Code Owner approval on a protected branch **(PREMIUM)** +## Require Code Owner approval on a protected branch **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in GitLab 13.5, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. @@ -318,6 +325,7 @@ To protect a new branch and enable Code Owner's approval: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push and merge** and **Allowed to merge** lists, select the settings you want. 1. Turn on the **Require approval from code owners** toggle. @@ -328,6 +336,7 @@ To enable Code Owner's approval on branches that are already protected: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. In the list of protected branches, next to the branch, turn on the **Code owner approval** toggle. When enabled, all merge requests for these branches require approval diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 0449c9867e2..8686d02271c 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Protected tags **(FREE)** +# Protected tags **(FREE ALL)** Protected [tags](repository/tags/index.md): @@ -34,6 +34,7 @@ Prerequisites: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Protected tags**. +1. Select **Add new**. 1. To protect a single tag, select **Tag**, then choose your tag from the dropdown list. 1. To protect all tags with names matching a string: 1. Select **Tag**. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 2dfdb77df9c..d0a938e054d 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Push options **(FREE)** +# Push options **(FREE ALL)** GitLab supports using client-side [Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) to perform various actions at the same time as pushing changes. Additionally, [Push Rules](repository/push_rules.md) offer server-side control and enforcement options. diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 066da445eeb..aee052631fc 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -5,20 +5,13 @@ group: Project Management 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 --- -# GitLab quick actions **(FREE)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26672) in GitLab 12.1: -> once an action is executed, an alert appears when a quick action is successfully applied. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16877) in GitLab 13.2: you can use -> quick actions when updating the description of issues, epics, and merge requests. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292393) in GitLab 13.8: 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. +# GitLab quick actions **(FREE ALL)** Quick actions are text-based shortcuts for common actions that are usually done by selecting buttons or dropdowns in the GitLab user interface. You can enter these commands in the descriptions or comments of issues, epics, merge requests, -and commits. +and commits. Quick actions are executed from both new comments and description, and when you edit +existing ones. Many quick actions are context-aware, requiring certain conditions be met. For example, to remove an issue due date with `/remove_due_date`, the issue must have a due date set. @@ -48,90 +41,93 @@ of quotation marks, automatically. The following quick actions are applicable to descriptions, discussions, and threads. Some quick actions might not be available to all subscription tiers. -<!-- Keep this table sorted alphabetically --> -<!-- Don't prettify this table; it will expand out the last field into illegibility --> +<!-- +Keep this table sorted alphabetically + +To auto-format this table, use the VS Code Markdown Table formatter: `https://docs.gitlab.com/ee/development/documentation/styleguide/#editor-extensions-for-table-formatting`. +--> | Command | Issue | Merge request | Epic | Action | |:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| -| `/add_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more active [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). -| `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. -| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users. -| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. -| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. -| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. -| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle an emoji reaction. +| `/add_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more active [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). | +| `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. | +| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users. | +| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. | +| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. | +| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | +| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle an emoji reaction. | +| `/blocked_by <issue1> <issue2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the issue as blocked by other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). | +| `/blocks <issue1> <issue2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the issue as blocking other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). | | `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. [In GitLab 14.9 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/31200), mentioning a user at the start of a line created a specific type of to-do item notification. | -| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. -| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). -| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. -| `/clone <path/to/project> [--with_notes]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. -| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. +| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | +| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | +| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | +| `/clone <path/to/project> [--with_notes]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given. Copies as much data as possible as long as the target project contains equivalent objects like labels, milestones, or epics. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | +| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | | `/confidential` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Mark issue or epic as confidential. Support for epics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213741) in GitLab 15.6. | -| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. -| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. -| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. -| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item as done. +| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. | +| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. | +| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | +| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item as done. | | `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [draft status](merge_requests/drafts.md). | -| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. See [Chronic](https://gitlab.com/gitlab-org/ruby/gems/gitlab-chronic#examples) for more examples. -| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue. Mark as a duplicate of, and related to, issue `<#issue>`. -| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. -| `/estimate <time>` or `/estimate_time <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. For more information, see [Time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. -| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). -| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. -| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). -| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. -| `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. See [Chronic](https://gitlab.com/gitlab-org/ruby/gems/gitlab-chronic#examples) for more examples. | +| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue. Mark as a duplicate of, and related to, issue `<#issue>`. | +| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | +| `/estimate <time>` or `/estimate_time <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. For more information, see [Time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | +| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | +| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. | +| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"`. | +| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | | `/link` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a link and description to [linked resources](../../operations/incident_management/linked_resources.md) in an incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374964) in GitLab 15.5). | -| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). -| `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. -| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. -| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. -| `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. -| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). In [GitLab 15.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/376760), you can also use the quick action when creating a new issue. -| `/page <policy name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Start escalations for the incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79977) in GitLab 14.9). -| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.0) -| `/ready` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [ready status](merge_requests/drafts.md#mark-merge-requests-as-ready) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90361) in GitLab 15.1). -| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. -| `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. +| `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | +| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). | +| `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. | +| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. | +| `/page <policy name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Start escalations for the incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79977) in GitLab 14.9). | +| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | +| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). In [GitLab 15.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/376760), you can also use the quick action when creating a new issue. | +| `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | +| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md). | +| `/ready` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [ready status](merge_requests/drafts.md#mark-merge-requests-as-ready) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90361) in GitLab 15.1). | +| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | +| `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | | `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | -| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. -| `/relate #issue1 #issue2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark issues as related. -| `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. -| `/remove_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). -| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. -| `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. -| `/remove_estimate` or `/remove_time_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. Alias `/remove_time_estimate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. -| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). -| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. -| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic. -| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. -| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue. -| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. -| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Issue type must be `Incident`. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. -| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. -| `/spend <time> [<date>]` or `/spend_time <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. For more information, see [Time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. -| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review. -| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. -| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. -| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. -| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. +| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | +| `/relate #issue1 #issue2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark issues as related. | +| `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | +| `/remove_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). | +| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. | +| `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. | +| `/remove_estimate` or `/remove_time_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. Alias `/remove_time_estimate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | +| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration. | +| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. | +| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic. | +| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | +| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue. | +| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | +| `/severity <severity>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set the severity. Issue type must be `Incident`. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. | +| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | +| `/spend <time> [<date>]` or `/spend_time <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. For more information, see [Time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | +| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review. | +| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | +| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | +| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | | `/timeline <timeline comment> \| <date(YYYY-MM-DD)> <time(HH:MM)>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a timeline event to this incident. For example, `/timeline DB load spiked \| 2022-09-07 09:30`. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368721) in GitLab 15.4). | -| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. -| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) in GitLab 14.3. -| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. -| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. -| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. -| `/unassign_reviewer me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove yourself as a reviewer. -| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. -| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. -| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. -| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. -| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. -| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. -| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident). -| `/blocks <issue1> <issue2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the issue as blocking other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). -| `/blocked_by <issue1> <issue2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the issue as blocked by other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). -| `/unlink <issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove link with to the provided issue. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414400) in GitLab 16.1). +| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | +| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | +| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) in GitLab 14.3). | +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | +| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. | +| `/unassign_reviewer me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove yourself as a reviewer. | +| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. | +| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | +| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | +| `/unlink <issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove link with to the provided issue. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414400) in GitLab 16.1). | +| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | +| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid values are integers like `0`, `1`, or `2`. | +| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident). | ## Work items @@ -140,33 +136,39 @@ threads. Some quick actions might not be available to all subscription tiers. Work items in GitLab include [tasks](../tasks.md) and [OKRs](../okrs.md). The following quick actions can be applied through the description field when editing or commenting on work items. -| Command | Task | Objective | Key Result | Action -|:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| -| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. -| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. -| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. -| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. -| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. -| `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. [In GitLab 14.9 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/31200), mentioning a user at the start of a line creates a specific type of to-do item notification. -| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign one or more users. -| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign yourself. -| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove specific assignees. -| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove all assignees. -| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Replace current assignees with those specified. -| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. -| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. -| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. -| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. -| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. -| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Remove due date. -| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk`. -| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). -| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. -| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. -| `/type` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Converts work item to specified type. Available options for `<type>` include `issue`, `task`, `objective` and `key result`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385227) in GitLab 16.0. -| `/promote_to <type>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Promotes work item to specified type. Available options for `<type>`: `issue` (promote a task) and `objective` (promote a key result). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412534) in GitLab 16.1. -| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412277) in GitLab 16.2. -| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item as done. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412277) in GitLab 16.2. +<!-- +Keep this table sorted alphabetically + +To auto-format this table, use the VS Code Markdown Table formatter: `https://docs.gitlab.com/ee/development/documentation/styleguide/#editor-extensions-for-table-formatting`. +--> + +| Command | Task | Objective | Key Result | Action | +|:--------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| +| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Assign one or more users. | +| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Assign yourself. | +| `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. [In GitLab 14.9 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/31200), mentioning a user at the start of a line creates a specific type of to-do item notification. | +| `/clear_health_status` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). | +| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | +| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | +| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item as done. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412277) in GitLab 16.2. | +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | +| `/health_status <value>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, or `at_risk`. | +| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | +| `/promote_to <type>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Promotes work item to specified type. Available options for `<type>`: `issue` (promote a task) or `objective` (promote a key result). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412534) in GitLab 16.1. | +| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current assignees with those specified. | +| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | +| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Remove due date. | +| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | +| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | +| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | +| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | +| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412277) in GitLab 16.2. | +| `/type` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Converts work item to specified type. Available options for `<type>` include `issue`, `task`, `objective` and `key result`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385227) in GitLab 16.0. | +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specific assignees. | +| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | Remove all assignees. | +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | +| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. | ## Commit messages @@ -176,14 +178,15 @@ The following quick actions are applicable for commit messages: |:----------------------- |:------------------------------------------| | `/tag v1.2.3 <message>` | Tags the commit with an optional message. | -<!-- ## Troubleshooting +## Troubleshooting + +### Quick action isn't executed -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +If you run a quick action, but nothing happens, check if the quick action appears in the autocomplete +box as you type it. +If it doesn't, it's possible that: -Each scenario can be a third-level heading, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +- The feature related to the quick action isn't available to you based on your subscription tier or + user role in the group or project. +- A required condition for the quick action isn't met. + For example, you're running `/unlabel` on an issue without any labels. diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 40fb6969def..8e65514cd1d 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -4,7 +4,7 @@ group: Environments 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 --- -# Releases **(FREE)** +# Releases **(FREE ALL)** In GitLab, a release enables you to create a snapshot of your project for your users, including installation packages and release notes. You can create a GitLab release on any branch. Creating a @@ -359,7 +359,7 @@ users with at least the Maintainer role to create, update, and delete releases by protecting the tag with a wildcard (`*`), and set **Maintainer** in the **Allowed to create** column. -## Release Metrics **(ULTIMATE)** +## Release Metrics **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259703) in GitLab Premium 13.9. diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index c5fb3838b11..e1de9cbdc1c 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -26,7 +26,7 @@ release-cli create --name "Release $CI_COMMIT_SHA" --description \ --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"}" ``` -## Install the `release-cli` for the Shell executor **(FREE)** +## Install the `release-cli` for the Shell executor **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/release-cli/-/issues/21) in GitLab 13.8. > - [Changed](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/108) in GitLab 14.2, the `release-cli` binaries are also [available in the Package Registry](https://gitlab.com/gitlab-org/release-cli/-/packages). diff --git a/doc/user/project/releases/release_evidence.md b/doc/user/project/releases/release_evidence.md index 990945b1a2b..7f8624fc520 100644 --- a/doc/user/project/releases/release_evidence.md +++ b/doc/user/project/releases/release_evidence.md @@ -4,7 +4,7 @@ group: Compliance 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 --- -# Release evidence **(FREE)** +# Release evidence **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. @@ -91,7 +91,7 @@ When a release is created, release evidence is automatically collected. To initi Evidence collection snapshots are visible on the Releases page, along with the timestamp the evidence was collected. -## Include report artifacts as release evidence **(ULTIMATE)** +## Include report artifacts as release evidence **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32773) in GitLab 13.2. diff --git a/doc/user/project/remote_development/connect_machine.md b/doc/user/project/remote_development/connect_machine.md index 53c5d342f74..ec3d63462f3 100644 --- a/doc/user/project/remote_development/connect_machine.md +++ b/doc/user/project/remote_development/connect_machine.md @@ -4,14 +4,24 @@ group: IDE 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 --- -# Tutorial: Connect a remote machine to the Web IDE **(FREE)** +# Tutorial: Connect a remote machine to the Web IDE (Beta) **(FREE ALL)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115741) in GitLab 15.11. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. + +WARNING: +This feature is in [Beta](../../../policy/experiment-beta-support.md#beta) and subject to change without notice. This tutorial shows you how to: - Create a development environment outside of GitLab. - Connect a remote machine to the [Web IDE](../web_ide/index.md). -To connect a remote machine to the Web IDE, you must: +To connect a remote machine to the Web IDE, you'll: 1. [Generate Let's Encrypt certificates](#generate-lets-encrypt-certificates). 1. [Connect a development environment to the Web IDE](#connect-a-development-environment-to-the-web-ide). @@ -102,7 +112,7 @@ Alternatively, you can pass the parameters from a URL and connect directly to th 1. Go to that URL and enter the token you've fetched. -You've done it! Your development environment now runs as a remote host that's connected to the Web IDE. +You've done it! Your development environment now runs as a remote host that's connected to the [Web IDE](../web_ide/index.md). ## Related topics diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index ccb1745d490..16110af984a 100644 --- a/doc/user/project/remote_development/index.md +++ b/doc/user/project/remote_development/index.md @@ -4,7 +4,7 @@ group: IDE 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 --- -# Remote development (Beta) **(FREE)** +# Remote development (Beta) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7. @@ -16,7 +16,8 @@ On self-managed GitLab, by default this feature is available. To hide the featur WARNING: This feature is in [Beta](../../../policy/experiment-beta-support.md#beta) and subject to change without notice. -You can use remote development to write and compile code hosted on GitLab. With remote development, you can: +You can use remote development to write and compile code hosted on GitLab. +With remote development, you can: - Create a secure development environment in the cloud. - Connect to that environment from your local machine through a web browser or client-based solution. @@ -32,9 +33,10 @@ With remote development, you can use: - The Web IDE as a frontend - A separate machine as a backend runtime environment -For a complete IDE experience, connect the Web IDE to a development environment configured to run as a remote host. You can create this environment [inside](../../workspace/index.md) or [outside](connect_machine.md) of GitLab. +For a complete IDE experience, connect the Web IDE to a development environment configured to run as a remote host. +You can create this environment [inside](../../workspace/configuration.md) or [outside](connect_machine.md) of GitLab. -## Workspace +## Workspaces **(PREMIUM ALL)** A [workspace](../../workspace/index.md) is a virtual sandbox environment for your code in GitLab that includes: diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index ae978e2123d..e123debb724 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -5,14 +5,14 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Default branch **(FREE)** +# Default branch **(FREE ALL)** When you create a new [project](../../index.md), GitLab creates a default branch in the repository. A default branch has special configuration options not shared by other branches: - It cannot be deleted. -- It's [initially protected](../../protected_branches.md#protected-branches) against +- It's [initially protected](../../protected_branches.md) against forced pushes. - When a merge request uses an [issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically) @@ -94,25 +94,28 @@ Users with the Owner role of groups and subgroups can configure the default bran Projects created in this group after you change the setting use the custom branch name, unless a subgroup configuration overrides it. -## Protect initial default branches **(FREE SELF)** +## Protect initial default branches **(FREE ALL)** > Full protection after initial push [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118729) in GitLab 16.0. GitLab administrators and group owners can define [branch protections](../../../project/protected_branches.md) -to apply to every repository's [default branch](#default-branch) +to apply to every repository's default branch at the [instance level](#instance-level-default-branch-protection) and [group level](#group-level-default-branch-protection) with one of the following options: -- **Not protected** - Both developers and maintainers can push new commits - and force push. +- **Fully protected** - Default value. Developers cannot push new commits, but maintainers can. + No one can force push. +- **Fully protected after initial push** - Developers can push the initial commit + to a repository, but none afterward. Maintainers can always push. No one can force push. - **Protected against pushes** - Developers cannot push new commits, but are allowed to accept merge requests to the branch. Maintainers can push to the branch. - **Partially protected** - Both developers and maintainers can push new commits, but cannot force push. -- **Fully protected** - Developers cannot push new commits, but maintainers can. - No one can force push. -- **Fully protected after initial push** - Developers can push the initial commit - to a repository, but none afterward. Maintainers can always push. No one can force push. +- **Not protected** - Both developers and maintainers can push new commits + and force push. + +WARNING: +Unless **Fully protected** is chosen, a malicious developer could attempt to steal your sensitive data. For example, a malicious `.gitlab-ci.yml` file could be committed to a protected branch and later, if a pipeline is run against that branch, result in exfiltration of group CI/CD variables. ### Instance-level default branch protection **(FREE SELF)** @@ -153,12 +156,12 @@ disable this privilege for group owners, enforcing the instance-level protection NOTE: GitLab administrators can still update the default branch protection of a group. -### Group-level default branch protection **(PREMIUM)** +### Group-level default branch protection **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. > - [Settings moved and renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/340403) in GitLab 14.9. -Instance-level protections for [default branch](#default-branch) +Instance-level protections for the default branch can be overridden on a per-group basis by the group's owner. In [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), GitLab administrators can [enforce protection of initial default branches](#prevent-overrides-of-default-branch-protection) diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 3e9957806c8..f7445ffe950 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -4,7 +4,7 @@ group: Source Code 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" --- -# Branches **(FREE)** +# Branches **(FREE ALL)** Branches are versions of a project's working tree. When you create a new [project](../../index.md), GitLab creates a [default branch](default.md) (which @@ -93,7 +93,7 @@ GitLab provides you multiple methods to protect individual branches. These metho ensure your branches receive oversight and quality checks from their creation to their deletion: - The [default branch](default.md) in your project receives extra protection. -- Configure [protected branches](../../protected_branches.md#protected-branches) +- Configure [protected branches](../../protected_branches.md) to restrict who can commit to a branch, merge other branches into it, or merge the branch itself into another branch. - Configure [approval rules](../../merge_requests/approvals/rules.md) to set review diff --git a/doc/user/project/repository/code_suggestions.md b/doc/user/project/repository/code_suggestions.md index 95d5873a535..6f18aabaa46 100644 --- a/doc/user/project/repository/code_suggestions.md +++ b/doc/user/project/repository/code_suggestions.md @@ -1,11 +1,11 @@ --- -stage: ModelOps -group: AI Assisted +stage: AI-powered +group: AI Model Validation 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 type: index, reference --- -# Code Suggestions (Beta) **(FREE)** +# Code Suggestions (Beta) **(FREE ALL)** > - [Introduced](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#code-suggestions-available-in-closed-beta) in GitLab 15.9 as [Beta](../../../policy/experiment-beta-support.md#beta) for early access Ultimate customers on GitLab.com. > - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/408104) as opt-in with GitLab 15.11 as [Beta](../../../policy/experiment-beta-support.md#beta). @@ -26,8 +26,8 @@ Write code more efficiently by using generative AI to suggest code while you're Code Suggestions are available: - To users of GitLab SaaS (by default) and self-managed GitLab Enterprise Edition (when requested). Code Suggestions are not available for GitLab Community Edition. -- In VS Code and Microsoft Visual Studio when you have the corresponding GitLab extension installed. -- In the GitLab WebIDE +- In VS Code, Microsoft Visual Studio, JetBrains IDEs, and Neovim. You must have the corresponding GitLab extension installed. +- In the GitLab WebIDE. <div class="video-fallback"> <a href="https://www.youtube.com/watch?v=WnxBYxN2-p4">View an end-to-end demo of Code Suggestions in VS Code</a>. @@ -58,7 +58,9 @@ The best results from Code Suggestions are expected [for languages the Google Ve - Swift - TypeScript - Supported [code infrastructure interfaces](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview#supported_code_infrastructure_interfaces) include: +### Supported code infrastructure interfaces + +Code Suggestions includes [Google Vertex AI Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview#supported_code_infrastructure_interfaces) support for the following infrastructure as code interfaces: - Google Cloud CLI - Kubernetes Resource Model (KRM) @@ -66,6 +68,47 @@ The best results from Code Suggestions are expected [for languages the Google Ve Suggestion quality for other languages and using natural language code comments to request completions may not yet result in high-quality suggestions. +### Supported languages in IDEs + +Editor support for languages is documented in the following table. + +| Language | VS Code | JetBrains IDEs | Visual Studio | Neovim | +|---------------------------------|--------------------------------------------------------------|------------------------------|---------------|--------| +| C++ | ✓ | | ✓ | | +| C# | ✓ | ✓ | ✓ | | +| Go | ✓ | ✓ (IDEA Ultimate / GoLand) | | | +| Google SQL | | | | | +| Java | ✓ | ✓ | | | +| JavaScript | ✓ | ✓ | | | +| Kotlin | ✓ | ✓ | | | +| PHP | ✓ | ✓ (IDEA Ultimate) | | | +| Python | ✓ | ✓ | | ✓ | +| Ruby | ✓ | ✓ (IDEA Ultimate / RubyMine) | | ✓ | +| Rust | ✓ | ✓ | | | +| Scala | ✓ | ✓ | | | +| Swift | ✓ | ✓ | | | +| TypeScript | ✓ | ✓ | | | +| Google Cloud CLI | | | | | +| Kubernetes Resource Model (KRM) | | | | | +| Terraform | ✓ (Requires 3rd party extension providing Terraform support) | | | | + +## Supported editor extensions + +Code Suggestions supports a variety of popular editors including: + +- VS Code, using [the VS Code GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). +- [GitLab WebIDE (VS Code in the Cloud)](../../project/web_ide/index.md), with no additional configuration. +- Microsoft Visual Studio, using the [Visual Studio GitLab extension](https://marketplace.visualstudio.com/items?itemName=GitLab.GitLabExtensionForVisualStudio). +- JetBrains IDEs, using the [GitLab plugin](https://plugins.jetbrains.com/plugin/22325-gitlab). +- Neovim, using the [`gitlab.vim` plugin](https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim). + +A [GitLab Language Server for Code Suggestions](https://gitlab.com/gitlab-org/editor-extensions/gitlab-language-server-for-code-suggestions) +is also in process. +This improvement should result in: + +- Faster iteration and standardization of the IDE extensions. +- The ability to use Code Suggestions even when an official editor extension isn't available. + ## Enable Code Suggestions on GitLab SaaS **(FREE SAAS)** Code Suggestions can be enabled [for all members of a group](../../group/manage.md#enable-code-suggestions). @@ -150,21 +193,13 @@ on self-managed instances. To request access: After GitLab has provisioned access to Code Suggestions for your instance, the users in your instance can now enable Code Suggestions. -## Enable Code Suggestions in other IDEs and editors - -We have experimental support for Code Suggestions in JetBrains, Neovim, Emacs, Sublime, etc. - -More details in this [blog](https://about.gitlab.com/blog/2023/06/01/extending-code-suggestions/). - ## Use Code Suggestions Prerequisites: - For self-managed GitLab, Code Suggestions must be enabled [for the instance](#enable-code-suggestions-on-self-managed-gitlab). - For GitLab SaaS, Code Suggestions must be enabled [for the top-level group](../../group/manage.md#enable-code-suggestions) and [for your user account](#enable-code-suggestions-for-an-individual-user). -- To use VS Code, ensure you have installed [the VS Code GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). -- To use Microsoft Visual Studio, ensure you have installed [the Visual Studio GitLab extension](https://marketplace.visualstudio.com/items?itemName=GitLab.GitLabExtensionForVisualStudio). - +- Install and configure a [supported IDE editor extension](#supported-editor-extensions). To use Code Suggestions: 1. Author your code. As you type, suggestions are displayed. Depending on the cursor position, the extension either: @@ -202,9 +237,11 @@ Learn more about Google Vertex AI Codey APIs [Data Governance](https://cloud.goo ### Inference window context Code Suggestions currently inferences against the currently opened file and has a context window of 2,048 tokens and 8,192 character limits. This limit includes content before and after the cursor, the file name, and the extension type. - Learn more about Google Vertex AI [code-gecko](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models). +The maximum number of tokens that is generated in the response is default 64. A token is approximately four characters. 100 tokens correspond to roughly 60-80 words. +Learn more about Google Vertex AI [`code-gecko`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-completion). + ### Self-managed instance data privacy A self-managed GitLab instance does not generate the code suggestion. After successful diff --git a/doc/user/project/repository/csv.md b/doc/user/project/repository/csv.md index 101878ee4b4..fcf8d538431 100644 --- a/doc/user/project/repository/csv.md +++ b/doc/user/project/repository/csv.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# CSV files **(FREE)** +# CSV files **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14174) in GitLab 14.1. diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index dece959bdc9..ee2be6dee7c 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -4,7 +4,7 @@ group: IDE 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 --- -# File finder **(FREE)** +# File finder **(FREE ALL)** With file finder, you can search for a file in a repository directly from the GitLab UI. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index a6bb02989a3..4c37b92b388 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -4,10 +4,10 @@ group: Source Code 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 --- -# Project forking workflow **(FREE)** +# Project forking workflow **(FREE ALL)** Whenever possible, it's recommended to work in a common Git repository and use -[branching strategies](../../../topics/gitlab_flow.md) to manage your work. However, +branching strategies to manage your work. However, if you do not have write access for the repository you want to contribute to, you can create a fork. @@ -134,7 +134,7 @@ an `upstream` remote repository for your fork: git push origin main ``` -### With repository mirroring **(PREMIUM)** +### With repository mirroring **(PREMIUM ALL)** A fork can be configured as a mirror of the upstream if all these conditions are met: @@ -202,7 +202,7 @@ to share objects with another repository: ### Error: `An error occurred while forking the project. Please try again` This error can be due to a mismatch in shared runner settings between the forked project -and the new namespace. See [Forks](../../../ci/runners/configure_runners.md#forks) +and the new namespace. See [Forks](../../../ci/runners/configure_runners.md#using-shared-runners-in-forked-projects) in the Runner documentation for more information. ### Removing fork relationship fails diff --git a/doc/user/project/repository/geojson.md b/doc/user/project/repository/geojson.md index 723121bc923..eb66a667deb 100644 --- a/doc/user/project/repository/geojson.md +++ b/doc/user/project/repository/geojson.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GeoJSON files **(FREE)** +# GeoJSON files **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14134) in GitLab 16.1. diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 235c1f34d1a..3f49f1e05f2 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -6,7 +6,7 @@ type: reference, howto description: "Documentation on Git file blame." --- -# Git file blame **(FREE)** +# Git file blame **(FREE ALL)** [Git blame](https://git-scm.com/docs/git-blame) provides more information about every line in a file, including the last modified time, author, and diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index edfcc4b1dc2..db50e6d185e 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -6,7 +6,7 @@ type: reference, howto description: "Documentation on Git file history." --- -# Git file history **(FREE)** +# Git file history **(FREE ALL)** Git file History provides information about the commit history associated with a file. To use it: diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 8d8639400bd..8bb6d868270 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Sign commits with GPG **(FREE)** +# Sign commits with GPG **(FREE ALL)** You can sign the commits you make in a GitLab repository with a GPG ([GNU Privacy Guard](https://gnupg.org/)) key. When you add a cryptographic @@ -122,6 +122,7 @@ To add a GPG key to your user settings: 1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. Select **GPG Keys** (**{key}**). +1. Select **Add new key**. 1. In **Key**, paste your _public_ key. 1. To add the key to your account, select **Add key**. GitLab shows the key's fingerprint, email address, and creation date: diff --git a/doc/user/project/repository/img/contributors_graph.png b/doc/user/project/repository/img/contributors_graph.png Binary files differdeleted file mode 100644 index 83fdf1fc41f..00000000000 --- a/doc/user/project/repository/img/contributors_graph.png +++ /dev/null diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 7383772a45b..3d00ceafc05 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Repository **(FREE)** +# Repository **(FREE ALL)** A [repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository) is where you store your code and make changes to it. Your changes are tracked with version control. @@ -15,7 +15,7 @@ Each [project](../index.md) contains a repository. To create a repository, you can: -- [Create a project](../../../user/project/index.md#create-a-project) or +- [Create a project](../../../user/project/index.md) or - [Fork an existing project](forking_workflow.md). ## Add files to a repository @@ -237,11 +237,7 @@ Administrators can set a [repository size limit](../../admin_area/settings/accou ## Repository contributor statistics -All code contributors are displayed under your project's **Analyze > Contributor statistics**. - -The graph shows the contributor with the most commits to the fewest. - - +You can view a list and charts of commits made by project members in [Contributor statistics](../../analytics/contributor_statistics.md). ## Repository history graph diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index d3d9b202e63..70ee841a991 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -4,7 +4,7 @@ group: Source Code 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" type: reference --- -# Jupyter Notebook files **(FREE)** +# Jupyter Notebook files **(FREE ALL)** [Jupyter Notebook](https://jupyter.org/) (previously, IPython Notebook) files are used for interactive computing in many fields. They contain a complete record of the diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index 550d4535adb..fade9e1b63c 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Bidirectional mirroring **(PREMIUM)** +# Bidirectional mirroring **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -138,7 +138,7 @@ This sample has a few limitations: - The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO` is seen as a ref update, and Git displays warnings about it. -## Mirror with Perforce Helix with Git Fusion **(PREMIUM)** +## Mirror with Perforce Helix with Git Fusion **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -167,4 +167,5 @@ Read about [Git Fusion settings on Perforce.com](https://www.perforce.com/manual ## Related topics +- [Troubleshooting](troubleshooting.md) for repository mirroring. - [Configure server hooks](../../../../administration/server_hooks.md) diff --git a/doc/user/project/repository/mirror/img/mirror_error_v16_3.png b/doc/user/project/repository/mirror/img/mirror_error_v16_3.png Binary files differnew file mode 100644 index 00000000000..7d3c03534ef --- /dev/null +++ b/doc/user/project/repository/mirror/img/mirror_error_v16_3.png diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 58c6c343282..7ade27e556d 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Repository mirroring **(FREE)** +# Repository mirroring **(FREE ALL)** You can _mirror_ a repository to and from external sources. You can select which repository serves as the source. Branches, tags, and commits are synced automatically. @@ -43,6 +43,7 @@ Prerequisites: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. +1. Select **Add new**. 1. Enter a **Git repository URL**. For security reasons, the URL to the original repository is only displayed to users with the Maintainer role or the Owner role for the mirrored project. @@ -76,7 +77,7 @@ non-protected branches in the mirroring project are not mirrored and can diverge To use this option, select **Only mirror protected branches** when you create a repository mirror. -### Mirror specific branches **(PREMIUM)** +### Mirror specific branches **(PREMIUM ALL)** > - Mirroring branches matching a regex [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../../../../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 16.0. @@ -205,193 +206,7 @@ Older versions of SSH may require you to remove `-E md5` from the command. ## Related topics +- [Troubleshooting](troubleshooting.md) for repository mirroring. - Configure a [Pull Mirroring Interval](../../../../administration/instance_limits.md#pull-mirroring-interval) - [Disable mirrors for a project](../../../../administration/settings/visibility_and_access_controls.md#enable-project-mirroring) - [Secrets file and mirroring](../../../../administration/backup_restore/backup_gitlab.md#when-the-secrets-file-is-lost) - -## Troubleshooting - -Should an error occur during a push, GitLab displays an **Error** highlight for that repository. Details on the error can then be seen by hovering over the highlight text. - -### Received RST_STREAM with error code 2 with GitHub - -If you receive this message while mirroring to a GitHub repository: - -```plaintext -13:Received RST_STREAM with error code 2 -``` - -One of these issues might be occurring: - -1. Your GitHub settings might be set to block pushes that expose your email address - used in commits. To fix this problem, either: - - Set your GitHub email address to public. - - Disable the [Block command line pushes that expose my email](https://github.com/settings/emails) - setting. -1. Your repository exceeds GitHub's file size limit of 100 MB. To fix this problem, - check the file size limit configured for on GitHub, and consider using - [Git Large File Storage](https://git-lfs.github.com) to manage large files. - -### Deadline Exceeded - -When upgrading GitLab, a change in how usernames are represented means that you -must update your mirroring username and password to ensure that `%40` characters are replaced with `@`. - -### Connection blocked because server only allows public key authentication - -The connection between GitLab and the remote repository is blocked. Even if a -[TCP Check](../../../../administration/raketasks/maintenance.md#check-tcp-connectivity-to-a-remote-site) -is successful, you must check any networking components in the route from GitLab -to the remote server for blockage. - -This error can occur when a firewall performs a `Deep SSH Inspection` on outgoing packets. - -### Could not read username: terminal prompts disabled - -If you receive this error after creating a new project using -[GitLab CI/CD for external repositories](../../../../ci/ci_cd_for_external_repos/index.md): - -- In Bitbucket Cloud: - - ```plaintext - "2:fetch remote: "fatal: could not read Username for 'https://bitbucket.org': - terminal prompts disabled\n": exit status 128." - ``` - -- In Bitbucket Server (self-managed): - - ```plaintext - "2:fetch remote: "fatal: could not read Username for 'https://lab.example.com': - terminal prompts disabled\n": exit status 128. - ``` - -Check if the repository owner is specified in the URL of your mirrored repository: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > Repository**. -1. Expand **Mirroring repositories**. -1. If no repository owner is specified, delete and add the URL again in this format, - replacing `OWNER`, `ACCOUNTNAME`, `PATH_TO_REPO`, and `REPONAME` with your values: - - - In Bitbucket Cloud: - - ```plaintext - https://OWNER@bitbucket.org/ACCOUNTNAME/REPONAME.git - ``` - - - In Bitbucket Server (self-managed): - - ```plaintext - https://OWNER@lab.example.com/PATH_TO_REPO/REPONAME.git - ``` - -When connecting to the Cloud or self-managed Bitbucket repository for mirroring, the repository owner is required in the string. - -### Pull mirror is missing LFS files - -In some cases, pull mirroring does not transfer LFS files. This issue occurs when: - -- You use an SSH repository URL. The workaround is to use an HTTPS repository URL instead. - An issue exists [to fix this problem for SSH URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/11997). -- You're using GitLab 14.0 or older, and the source repository is a public Bitbucket URL. - [Fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/335123) in GitLab 14.0.6. -- You mirror an external repository using object storage. - An issue exists [to fix this problem](https://gitlab.com/gitlab-org/gitlab/-/issues/335495). - -### `The repository is being updated`, but neither fails nor succeeds visibly - -In rare cases, mirroring slots on Redis can become exhausted, -possibly because Sidekiq workers are reaped due to out-of-memory (OoM) events. -When this occurs, mirroring jobs start and complete quickly, but they neither -fail nor succeed. They also do not leave a clear log. To check for this problem: - -1. Enter the [Rails console](../../../../administration/operations/rails_console.md) - and check Redis' mirroring capacity: - - ```ruby - current = Gitlab::Redis::SharedState.with { |redis| redis.scard('MIRROR_PULL_CAPACITY') }.to_i - maximum = Gitlab::CurrentSettings.mirror_max_capacity - available = maximum - current - ``` - -1. If the mirroring capacity is `0` or very low, you can drain all stuck jobs with: - - ```ruby - Gitlab::Redis::SharedState.with { |redis| redis.smembers('MIRROR_PULL_CAPACITY') }.each do |pid| - Gitlab::Redis::SharedState.with { |redis| redis.srem('MIRROR_PULL_CAPACITY', pid) } - end - ``` - -1. After you run the command, the [background jobs page](../../../../administration/admin_area.md#background-jobs) - should show new mirroring jobs being scheduled, especially when - [triggered manually](#update-a-mirror). - -### Invalid URL - -If you receive this error while setting up mirroring over [SSH](#ssh-authentication), make sure the URL is in a valid format. - -Mirroring does not support the short version of SSH clone URLs (`git@gitlab.com:gitlab-org/gitlab.git`) -and requires the full version including the protocol (`ssh://git@gitlab.com/gitlab-org/gitlab.git`). - -Make sure that host and project path are separated using `/` instead of `:`. - -### Host key verification failed - -This error is returned when the target host public SSH key changes. -Public SSH keys rarely, if ever, change. If host key verification fails, -but you suspect the key is still valid, you can refresh the key's information. - -Prerequisites: - -- You must have at least the Maintainer role for a project. - -To resolve the issue: - -1. [Verify the host key](#verify-a-host-key). -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > Repository**. -1. Expand **Mirroring repositories**. -1. To refresh the keys, either: - - - Select **Detect host keys** for GitLab to fetch the host keys from the server, and display the fingerprints. - - Select **Input host keys manually**, and enter the host key into the **SSH host key** field. - -- Select **Mirror repository**. - -### Transfer mirror users and tokens to a single service account in Rails console - -This requires access to the [GitLab Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session). - -Use case: If you have multiple users using their own GitHub credentials to set up -repository mirroring, mirroring breaks when people leave the company. Use this -script to migrate disparate mirroring users and tokens into a single service account: - -WARNING: -Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. - -```ruby -svc_user = User.find_by(username: 'ourServiceUser') -token = 'githubAccessToken' - -Project.where(mirror: true).each do |project| - import_url = project.import_url - - # The url we want is https://token@project/path.git - repo_url = if import_url.include?('@') - # Case 1: The url is something like https://23423432@project/path.git - import_url.split('@').last - elsif import_url.include?('//') - # Case 2: The url is something like https://project/path.git - import_url.split('//').last - end - - next unless repo_url - - final_url = "https://#{token}@#{repo_url}" - - project.mirror_user = svc_user - project.import_url = final_url - project.username_only_import_url = final_url - project.save -end -``` diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 56e85157c03..ba54c18f8ee 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Pull from a remote repository **(PREMIUM)** +# Pull from a remote repository **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -145,5 +145,6 @@ end ## Related topics +- [Troubleshooting](troubleshooting.md) for repository mirroring. - [Pull mirroring intervals](../../../../administration/instance_limits.md#pull-mirroring-interval) - [Pull mirroring API](../../../../api/projects.md#configure-pull-mirroring-for-a-project) diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index 26a60002f0e..cd4fe68b01b 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Push mirroring **(FREE)** +# Push mirroring **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40137) in GitLab 13.5: LFS support over HTTPS. @@ -209,4 +209,5 @@ If it isn't working correctly, a red `error` tag appears, and shows the error me ## Related topics +- [Troubleshooting](troubleshooting.md) for repository mirroring. - [Remote mirrors API](../../../../api/remote_mirrors.md) diff --git a/doc/user/project/repository/mirror/troubleshooting.md b/doc/user/project/repository/mirror/troubleshooting.md new file mode 100644 index 00000000000..5817aab5fc7 --- /dev/null +++ b/doc/user/project/repository/mirror/troubleshooting.md @@ -0,0 +1,217 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting repository mirroring **(FREE ALL)** + +When mirroring fails, project maintainers can see a link similar to **{warning-solid}** **Pull mirroring failed 1 hour ago.** +on the project details page. Select this link to go directly to the mirroring settings, +where GitLab displays an **Error** badge for the mirrored repository. You can hover your mouse cursor +over the badge to display the text of the error: + + + +## Received RST_STREAM with error code 2 with GitHub + +If you receive this message while mirroring to a GitHub repository: + +```plaintext +13:Received RST_STREAM with error code 2 +``` + +One of these issues might be occurring: + +1. Your GitHub settings might be set to block pushes that expose your email address + used in commits. To fix this problem, either: + - Set your GitHub email address to public. + - Disable the [Block command line pushes that expose my email](https://github.com/settings/emails) + setting. +1. Your repository exceeds GitHub's file size limit of 100 MB. To fix this problem, + check the file size limit configured for on GitHub, and consider using + [Git Large File Storage](https://git-lfs.github.com) to manage large files. + +## Deadline Exceeded + +When upgrading GitLab, a change in how usernames are represented means that you +must update your mirroring username and password to ensure that `%40` characters are replaced with `@`. + +## Connection blocked because server only allows public key authentication + +The connection between GitLab and the remote repository is blocked. Even if a +[TCP Check](../../../../administration/raketasks/maintenance.md#check-tcp-connectivity-to-a-remote-site) +is successful, you must check any networking components in the route from GitLab +to the remote server for blockage. + +This error can occur when a firewall performs a `Deep SSH Inspection` on outgoing packets. + +## Could not read username: terminal prompts disabled + +If you receive this error after creating a new project using +[GitLab CI/CD for external repositories](../../../../ci/ci_cd_for_external_repos/index.md): + +- In Bitbucket Cloud: + + ```plaintext + "2:fetch remote: "fatal: could not read Username for 'https://bitbucket.org': + terminal prompts disabled\n": exit status 128." + ``` + +- In Bitbucket Server (self-managed): + + ```plaintext + "2:fetch remote: "fatal: could not read Username for 'https://lab.example.com': + terminal prompts disabled\n": exit status 128. + ``` + +Check if the repository owner is specified in the URL of your mirrored repository: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. If no repository owner is specified, delete and add the URL again in this format, + replacing `OWNER`, `ACCOUNTNAME`, `PATH_TO_REPO`, and `REPONAME` with your values: + + - In Bitbucket Cloud: + + ```plaintext + https://OWNER@bitbucket.org/ACCOUNTNAME/REPONAME.git + ``` + + - In Bitbucket Server (self-managed): + + ```plaintext + https://OWNER@lab.example.com/PATH_TO_REPO/REPONAME.git + ``` + +When connecting to the Cloud or self-managed Bitbucket repository for mirroring, the repository owner is required in the string. + +## Pull mirror is missing LFS files + +In some cases, pull mirroring does not transfer LFS files. This issue occurs when: + +- You use an SSH repository URL. The workaround is to use an HTTPS repository URL instead. + An issue exists [to fix this problem for SSH URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/11997). +- You're using GitLab 14.0 or older, and the source repository is a public Bitbucket URL. + [Fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/335123) in GitLab 14.0.6. +- You mirror an external repository using object storage. + An issue exists [to fix this problem](https://gitlab.com/gitlab-org/gitlab/-/issues/335495). + +## Pull mirroring is not triggering pipelines + +Pipelines might not run for multiple reasons: + +- [Trigger pipelines for mirror updates](pull.md#trigger-pipelines-for-mirror-updates) + might not be enabled. This setting can only be enabled when initially + [configuring pull mirroring](pull.md#configure-pull-mirroring). The status + [is not displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/346630) + when checking the project afterwards. + + When mirroring is set up using [CI/CD for external repositories](../../../../ci/ci_cd_for_external_repos/index.md) + this setting is enabled by default. If repository mirroring is manually reconfigured, triggering pipelines + is off by default and this could be why pipelines stop running. +- [`rules`](../../../../ci/yaml/index.md#rules) configuration prevents any jobs from + being added to the pipeline. +- Pipelines are triggered using [the account that set up the pull mirror](https://gitlab.com/gitlab-org/gitlab/-/issues/13697). + If the account is no longer valid, pipelines do not run. +- [Branch protection](../../protected_branches.md#run-pipelines-on-protected-branches) + might prevent the account that set up mirroring from running pipelines. + +## `The repository is being updated`, but neither fails nor succeeds visibly + +In rare cases, mirroring slots on Redis can become exhausted, +possibly because Sidekiq workers are reaped due to out-of-memory (OoM) events. +When this occurs, mirroring jobs start and complete quickly, but they neither +fail nor succeed. They also do not leave a clear log. To check for this problem: + +1. Enter the [Rails console](../../../../administration/operations/rails_console.md) + and check Redis' mirroring capacity: + + ```ruby + current = Gitlab::Redis::SharedState.with { |redis| redis.scard('MIRROR_PULL_CAPACITY') }.to_i + maximum = Gitlab::CurrentSettings.mirror_max_capacity + available = maximum - current + ``` + +1. If the mirroring capacity is `0` or very low, you can drain all stuck jobs with: + + ```ruby + Gitlab::Redis::SharedState.with { |redis| redis.smembers('MIRROR_PULL_CAPACITY') }.each do |pid| + Gitlab::Redis::SharedState.with { |redis| redis.srem('MIRROR_PULL_CAPACITY', pid) } + end + ``` + +1. After you run the command, the [background jobs page](../../../../administration/admin_area.md#background-jobs) + should show new mirroring jobs being scheduled, especially when + [triggered manually](index.md#update-a-mirror). + +## Invalid URL + +If you receive this error while setting up mirroring over [SSH](index.md#ssh-authentication), make sure the URL is in a valid format. + +Mirroring does not support the short version of SSH clone URLs (`git@gitlab.com:gitlab-org/gitlab.git`) +and requires the full version including the protocol (`ssh://git@gitlab.com/gitlab-org/gitlab.git`). + +Make sure that host and project path are separated using `/` instead of `:`. + +## Host key verification failed + +This error is returned when the target host public SSH key changes. +Public SSH keys rarely, if ever, change. If host key verification fails, +but you suspect the key is still valid, you can refresh the key's information. + +Prerequisites: + +- You must have at least the Maintainer role for a project. + +To resolve the issue: + +1. [Verify the host key](index.md#verify-a-host-key). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. To refresh the keys, either: + + - Select **Detect host keys** for GitLab to fetch the host keys from the server, and display the fingerprints. + - Select **Input host keys manually**, and enter the host key into the **SSH host key** field. + +- Select **Mirror repository**. + +## Transfer mirror users and tokens to a single service account in Rails console + +This requires access to the [GitLab Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session). + +Use case: If you have multiple users using their own GitHub credentials to set up +repository mirroring, mirroring breaks when people leave the company. Use this +script to migrate disparate mirroring users and tokens into a single service account: + +WARNING: +Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. + +```ruby +svc_user = User.find_by(username: 'ourServiceUser') +token = 'githubAccessToken' + +Project.where(mirror: true).each do |project| + import_url = project.import_url + + # The url we want is https://token@project/path.git + repo_url = if import_url.include?('@') + # Case 1: The url is something like https://23423432@project/path.git + import_url.split('@').last + elsif import_url.include?('//') + # Case 2: The url is something like https://project/path.git + import_url.split('//').last + end + + next unless repo_url + + final_url = "https://#{token}@#{repo_url}" + + project.mirror_user = svc_user + project.import_url = final_url + project.username_only_import_url = final_url + project.save +end +``` diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index 81896d64815..2756149b5bd 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -4,7 +4,9 @@ group: Source Code 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" --- -# Push rules **(PREMIUM)** +# Push rules **(PREMIUM ALL)** + +> Maximum regular expression length for push rules [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/411901) from 255 to 511 characters in GitLab 16.3. Push rules are [pre-receive Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) you can enable in a user-friendly interface. Push rules give you more control over what @@ -19,7 +21,7 @@ can and can't be pushed to your repository. While GitLab offers GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular expressions in push rules. You can test them at the [regex101 regex tester](https://regex101.com/). -Each regular expression is limited to 255 characters. +Each regular expression is limited to 511 characters. For custom push rules use [server hooks](../../../administration/server_hooks.md). diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 334db91cd82..590323bfadd 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Reduce repository size **(FREE)** +# Reduce repository size **(FREE ALL)** Git repositories become larger over time. When large files are added to a Git repository: diff --git a/doc/user/project/repository/ssh_signed_commits/index.md b/doc/user/project/repository/ssh_signed_commits/index.md index 85a8917022e..d8d798ac651 100644 --- a/doc/user/project/repository/ssh_signed_commits/index.md +++ b/doc/user/project/repository/ssh_signed_commits/index.md @@ -4,7 +4,7 @@ group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Sign commits with SSH keys **(FREE)** +# Sign commits with SSH keys **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343879) in GitLab 15.7 [with a flag](../../../../administration/feature_flags.md) named `ssh_commit_signatures`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/384202) in GitLab 15.8. Feature flag `ssh_commit_signatures` removed. diff --git a/doc/user/project/repository/tags/index.md b/doc/user/project/repository/tags/index.md index 8c6774408e6..5a01d6f2085 100644 --- a/doc/user/project/repository/tags/index.md +++ b/doc/user/project/repository/tags/index.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Tags **(FREE)** +# Tags **(FREE ALL)** In Git, a tag marks an important point in a repository's history. Git supports two types of tags: @@ -97,7 +97,7 @@ To create a tag from the GitLab UI: create a lightweight tag. 1. Select **Create tag**. -## Prevent tag deletion **(PREMIUM)** +## Prevent tag deletion **(PREMIUM ALL)** To prevent users from removing a tag with `git push`, create a [push rule](../push_rules.md). diff --git a/doc/user/project/repository/vscode.md b/doc/user/project/repository/vscode.md index 2a33476b545..476cfc55298 100644 --- a/doc/user/project/repository/vscode.md +++ b/doc/user/project/repository/vscode.md @@ -1,49 +1,11 @@ --- -stage: Create -group: IDE -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 +redirect_to: '../../../editor_extensions/visual_studio_code/index.md' +remove_date: '2023-10-31' --- -# GitLab Workflow extension for VS Code **(FREE)** +This document was moved to [another location](../../../editor_extensions/visual_studio_code/index.md). -The [GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) -integrates GitLab with Visual Studio Code. You can decrease context switching and -do more day-to-day tasks in Visual Studio Code, such as: - -- [View issues](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-issues-review-mrs). -- Run [common commands](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#commands) - from the Visual Studio Code [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette). -- Create and [review](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#merge-request-reviews) - merge requests directly from Visual Studio Code. -- [Validate your GitLab CI/CD configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-cicd-configuration). -- [View the status of your pipeline](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#information-about-your-branch-pipelines-mr-closing-issue). -- [View the output of CI/CD jobs](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#view-the-job-output). -- [Create](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#create-snippet) - and paste snippets to, and from, your editor. -- [Browse repositories](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-a-repository-without-cloning) - without cloning them. -- [Receive Code Suggestions](code_suggestions.md) - -## Download the extension - -Download the extension from the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). - -## Configure the extension - -After you [download the extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) -you can [configure](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#extension-settings): - -- [Features to display or hide](https://gitlab.com/gitlab-org/gitlab-vscode-extension#extension-settings). -- [Self-signed certificate](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#self-signed-certificates) information. -- [Code Suggestions](code_suggestions.md) - -## Report issues with the extension - -Report any issues, bugs, or feature requests in the -[`gitlab-vscode-extension` issue queue](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/issues). - -## Related topics - -- [Download the extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) -- [Extension documentation](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/README.md) -- [View source code](https://gitlab.com/gitlab-org/gitlab-vscode-extension/) +<!-- This redirect file can be deleted after <2023-10-31>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 7b2dcd04982..121a7b41f54 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -4,7 +4,7 @@ group: IDE 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 --- -# Web Editor **(FREE)** +# Web Editor **(FREE ALL)** You can use the Web Editor to make changes to a single file directly from the GitLab UI. To make changes to multiple files, see [Web IDE](../web_ide/index.md). diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 80538697100..20860718b43 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# Sign commits and tags with X.509 certificates **(FREE)** +# Sign commits and tags with X.509 certificates **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17773) in GitLab 12.8. diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 4079f821064..1f79982bb1f 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -5,7 +5,7 @@ group: Product Planning 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 --- -# Requirements management **(ULTIMATE)** +# Requirements management **(ULTIMATE ALL)** NOTE: In 14.4, Requirements was moved under **Issues**. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index b508fbcf676..cd09f84641e 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -1,914 +1,11 @@ --- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'service_desk/index.md' +remove_date: '2023-10-24' --- -# Service Desk **(FREE)** +This document was moved to [another location](service_desk/index.md). -> Moved to GitLab Free in 13.2. - -With Service Desk, your customers -can email you bug reports, feature requests, or general feedback. -Service Desk provides a unique email address, so they don't need their own GitLab accounts. - -Service Desk emails are created in your GitLab project as new issues. -Your team can respond directly from the project, while customers interact with the thread only -through email. - -## Service Desk workflow - -For example, 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 works for you: - -1. You provide a project-specific email address to your paying customers, who can email you directly - from the application. -1. Each email they send creates an issue in the appropriate project. -1. Your team members go to the Service Desk issue tracker, where they can see new support - requests and respond inside associated issues. -1. Your team communicates with the customer to understand the request. -1. Your team starts working on implementing code to solve your customer's problem. -1. When your team finishes the implementation, the merge request is merged and the issue - is closed automatically. - -Meanwhile: - -- The customer interacts with your team entirely through email, without needing access to your - GitLab instance. -- Your team saves time by not having to leave GitLab (or set up integrations) to follow up with - your customer. - -## Configure Service Desk - -By default, Service Desk is active in new projects. -If it's not active, you can do it in the project's settings. - -Prerequisites: - -- You must have at least the Maintainer role for the project. -- On GitLab self-managed, you must [set up incoming email](../../administration/incoming_email.md#set-it-up) - for the GitLab instance. You should use - [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), - but you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). - To do this, you must have administrator access. -- You must have enabled [issue](settings/index.md#configure-project-visibility-features-and-permissions) - tracker for the project. - -To enable Service Desk in your project: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Service Desk**. -1. Turn on the **Activate Service Desk** toggle. -1. Optional. Complete the fields. - - [Add a suffix](#configure-a-suffix-for-service-desk-alias-email) to your Service Desk email address. - - If the list below **Template to append to all Service Desk issues** is empty, create a - [description template](description_templates.md) in your repository. -1. Select **Save changes**. - -Service Desk is now enabled for this project. -If anyone sends an email to the address available below **Email address to use for Service Desk**, -GitLab creates a confidential issue with the email's content. - -### Improve your project's security - -To improve your Service Desk project's security, you should: - -- Put the Service Desk email address behind an alias on your email system so you can change it later. -- [Enable Akismet](../../integration/akismet.md) on your GitLab instance to add spam checking to this service. - Unblocked email spam can result in many spam issues being created. - -### Customize emails sent to the requester - -> - Moved from GitLab Premium to GitLab Free in 13.2. -> - `UNSUBSCRIBE_URL`, `SYSTEM_HEADER`, `SYSTEM_FOOTER`, and `ADDITIONAL_TEXT` placeholders [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285512) in GitLab 15.9. -> - `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. -> - `%{ISSUE_URL}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408793) in GitLab 16.1. - -An email is sent to the requester when: - -- A requester submits a new ticket by emailing Service Desk. -- A new public comment is added on a Service Desk ticket. - - Editing a comment does not trigger a new email to be sent. - -You can customize the body of these email messages with Service Desk email templates. The templates -can include [GitLab Flavored Markdown](../markdown.md) and [some HTML tags](../markdown.md#inline-html). -For example, you can format the emails to include a header and footer in accordance with your -organization's brand guidelines. You can also include the following placeholders to display dynamic -content specific to the Service Desk ticket or your GitLab instance. - -| Placeholder | `thank_you.md` | `new_note.md` | Description -| ---------------------- | ---------------------- | ---------------------- | ----------- -| `%{ISSUE_ID}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket IID. -| `%{ISSUE_PATH}` | **{check-circle}** Yes | **{check-circle}** Yes | Project path appended with the ticket IID. -| `%{ISSUE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | URL of the ticket. External participants can only view the ticket if the project is public and ticket is not confidential (Service Desk tickets are confidential by default). -| `%{ISSUE_DESCRIPTION}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket description. If a user has edited the description, it may contain sensitive information that is not intended to be delivered to external participants. Use this placeholder with care and ideally only if you never modify descriptions or your team is aware of the template design. -| `%{UNSUBSCRIBE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe URL. -| `%{NOTE_TEXT}` | **{dotted-circle}** No | **{check-circle}** Yes | The new comment added to the ticket by a user. Take care to include this placeholder in `new_note.md`. Otherwise, the requesters may never see the updates on their Service Desk ticket. - -#### Thank you email - -When a requester submits an issue through Service Desk, GitLab sends a **thank you email**. -Without additional configuration, GitLab sends the default thank you email. - -To create a custom thank you email template: - -1. In the `.gitlab/service_desk_templates/` directory of your repository, create a file named `thank_you.md`. -1. Populate the Markdown file with text, [GitLab Flavored Markdown](../markdown.md), - [some selected HTML tags](../markdown.md#inline-html), and placeholders to customize the reply - to Service Desk requesters. - -#### New note email - -When a Service Desk ticket has a new public comment, GitLab sends a **new note email**. -Without additional configuration, GitLab sends the content of the comment. - -To keep your emails on brand, you can create a custom new note email template. To do so: - -1. In the `.gitlab/service_desk_templates/` directory in your repository, create a file named `new_note.md`. -1. Populate the Markdown file with text, [GitLab Flavored Markdown](../markdown.md), - [some selected HTML tags](../markdown.md#inline-html), and placeholders to customize the new note - email. Be sure to include the `%{NOTE_TEXT}` in the template to make sure the email recipient can - read the contents of the comment. - -#### Instance-level email header, footer, and additional text **(FREE SELF)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344819) in GitLab 15.9. - -Instance administrators can add a header, footer or additional text to the GitLab instance and apply -them to all emails sent from GitLab. If you're using a custom `thank_you.md` or `new_note.md`, to include -this content, add `%{SYSTEM_HEADER}`, `%{SYSTEM_FOOTER}`, or `%{ADDITIONAL_TEXT}` to your templates. - -For more information, see [System header and footer messages](../../administration/appearance.md#system-header-and-footer-messages) and [custom additional text](../../administration/settings/email.md#custom-additional-text). - -### Use a custom template for Service Desk tickets - -You can select one [description template](description_templates.md#create-an-issue-template) -**per project** to be appended to every new Service Desk ticket's description. - -You can set description templates at various levels: - -- The entire [instance](description_templates.md#set-instance-level-description-templates). -- A specific [group or subgroup](description_templates.md#set-group-level-description-templates). -- A specific [project](description_templates.md#set-a-default-template-for-merge-requests-and-issues). - -The templates are inherited. For example, in a project, you can also access templates set for the instance, or the project's parent groups. - -Prerequisite: - -- You must have [created a description template](description_templates.md#create-an-issue-template). - -To use a custom description template with Service Desk: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Service Desk**. -1. From the dropdown list **Template to append to all Service Desk issues**, search or select your template. - -### Support Bot user - -Behind the scenes, Service Desk works by the special Support Bot user creating issues. -This user isn't a [billable user](../../subscriptions/self_managed/index.md#billable-users), -so it does not count toward the license limit count. - -In GitLab 16.0 and earlier, comments generated from Service Desk emails show `GitLab Support Bot` -as the author. In [GitLab 16.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/226995), -these comments show the email of the user who sent the email. -This feature only applies to comments made in GitLab 16.1 and later. - -#### Change the Support Bot's display name - -You can change the display name of the Support Bot user. Emails sent from Service Desk have -this name in the `From` header. The default display name is `GitLab Support Bot`. - -To edit the custom email display name: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Service Desk**. -1. Below **Email display name**, enter a new name. -1. Select **Save changes**. - -### Use an additional Service Desk alias email **(FREE SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab 13.0. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. - -You can use an additional alias email address for Service Desk on an instance level. - -To do this, you must configure -a [`service_desk_email`](#configure-service-desk-alias-email) in the instance configuration. You can also configure a -[custom suffix](#configure-a-suffix-for-service-desk-alias-email) that replaces the default `-issue-` portion on the sub-addressing part. - -#### Configure Service Desk alias email - -NOTE: -On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address. You can still configure the -[custom suffix](#configure-a-suffix-for-service-desk-alias-email) in project settings. - -Service Desk uses the [incoming email](../../administration/incoming_email.md) -configuration by default. However, to have a separate email address for Service Desk, -configure `service_desk_email` with a [custom suffix](#configure-a-suffix-for-service-desk-alias-email) -in project settings. - -Prerequisites: - -- The `address` must include the `+%{key}` placeholder in the `user` portion of the address, - before the `@`. The placeholder is used to identify the project where the issue should be created. -- The `service_desk_email` and `incoming_email` configurations must always use separate mailboxes - to make sure Service Desk emails are processed correctly. - -To configure a custom mailbox for Service Desk with IMAP, add the following snippets to your configuration file in full: - -::Tabs - -:::TabTitle Linux package (Omnibus) - -NOTE: -In GitLab 15.3 and later, Service Desk uses `webhook` (internal API call) by default instead of enqueuing a Sidekiq job. -To use `webhook` on a Linux package installation running GitLab 15.3, you must generate a secret file. -For more information, see [merge request 5927](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5927). -In GitLab 15.4, reconfiguring a Linux package installation generates this secret file automatically, so no -secret file configuration setting is needed. -For more information, see [issue 1462](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1462). - -```ruby -gitlab_rails['service_desk_email_enabled'] = true -gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" -gitlab_rails['service_desk_email_email'] = "project_contact@gmail.com" -gitlab_rails['service_desk_email_password'] = "[REDACTED]" -gitlab_rails['service_desk_email_mailbox_name'] = "inbox" -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_host'] = "imap.gmail.com" -gitlab_rails['service_desk_email_port'] = 993 -gitlab_rails['service_desk_email_ssl'] = true -gitlab_rails['service_desk_email_start_tls'] = false -``` - -:::TabTitle Self-compiled (source) - -```yaml -service_desk_email: - enabled: true - address: "project_contact+%{key}@example.com" - user: "project_contact@example.com" - password: "[REDACTED]" - host: "imap.gmail.com" - delivery_method: webhook - secret_file: .gitlab-mailroom-secret - port: 993 - ssl: true - start_tls: false - log_path: "log/mailroom.log" - mailbox: "inbox" - idle_timeout: 60 - expunge_deleted: true -``` - -::EndTabs - -The configuration options are the same as for configuring -[incoming email](../../administration/incoming_email.md#set-it-up). - -##### Use encrypted credentials - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9. - -Instead of having the Service Desk email credentials stored in plaintext in the configuration files, you can optionally -use an encrypted file for the incoming email credentials. - -Prerequisites: - -- To use encrypted credentials, you must first enable the - [encrypted configuration](../../administration/encrypted_configuration.md). - -The supported configuration items for the encrypted file are: - -- `user` -- `password` - -::Tabs - -:::TabTitle Linux package (Omnibus) - -1. If initially your Service Desk configuration in `/etc/gitlab/gitlab.rb` looked like: - - ```ruby - gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" - gitlab_rails['service_desk_email_password'] = "examplepassword" - ``` - -1. Edit the encrypted secret: - - ```shell - sudo gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=vim - ``` - -1. Enter the unencrypted contents of the Service Desk email secret: - - ```yaml - user: 'service-desk-email@mail.example.com' - password: 'examplepassword' - ``` - -1. Edit `/etc/gitlab/gitlab.rb` and remove the `service_desk` settings for `email` and `password`. -1. Save the file and reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -:::TabTitle Helm chart (Kubernetes) - -Use a Kubernetes secret to store the Service Desk email password. For more information, -read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails). - -:::TabTitle Docker - -1. If initially your Service Desk configuration in `docker-compose.yml` looked like: - - ```yaml - version: "3.6" - services: - gitlab: - image: 'gitlab/gitlab-ee:latest' - restart: always - hostname: 'gitlab.example.com' - environment: - GITLAB_OMNIBUS_CONFIG: | - gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" - gitlab_rails['service_desk_email_password'] = "examplepassword" - ``` - -1. Get inside the container, and edit the encrypted secret: - - ```shell - sudo docker exec -t <container_name> bash - gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=editor - ``` - -1. Enter the unencrypted contents of the Service Desk secret: - - ```yaml - user: 'service-desk-email@mail.example.com' - password: 'examplepassword' - ``` - -1. Edit `docker-compose.yml` and remove the `service_desk` settings for `email` and `password`. -1. Save the file and restart GitLab: - - ```shell - docker compose up -d - ``` - -:::TabTitle Self-compiled (source) - -1. If initially your Service Desk configuration in `/home/git/gitlab/config/gitlab.yml` looked like: - - ```yaml - production: - service_desk_email: - user: 'service-desk-email@mail.example.com' - password: 'examplepassword' - ``` - -1. Edit the encrypted secret: - - ```shell - bundle exec rake gitlab:service_desk_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production - ``` - -1. Enter the unencrypted contents of the Service Desk secret: - - ```yaml - user: 'service-desk-email@mail.example.com' - password: 'examplepassword' - ``` - -1. Edit `/home/git/gitlab/config/gitlab.yml` and remove the `service_desk_email:` settings for `user` and `password`. -1. Save the file and restart GitLab and Mailroom - - ```shell - # For systems running systemd - sudo systemctl restart gitlab.target - - # For systems running SysV init - sudo service gitlab restart - ``` - -::EndTabs - -##### Microsoft Graph - -> - Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9. -> - [Introduced for self-compiled (source) installs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116494) in GitLab 15.11. - -`service_desk_email` can be configured to read Microsoft Exchange Online mailboxes with the Microsoft -Graph API instead of IMAP. Set up an OAuth 2.0 application for Microsoft Graph -[the same way as for incoming email](../../administration/incoming_email.md#microsoft-graph). - -::Tabs - -:::TabTitle Linux package (Omnibus) - -1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, substituting - the values you want: - - ```ruby - gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" - gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" - gitlab_rails['service_desk_email_mailbox_name'] = "inbox" - gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' - gitlab_rails['service_desk_email_inbox_options'] = { - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional - } - ``` - - For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), - configure the `azure_ad_endpoint` and `graph_endpoint` settings. For example: - - ```ruby - gitlab_rails['service_desk_email_inbox_options'] = { - 'azure_ad_endpoint': 'https://login.microsoftonline.us', - 'graph_endpoint': 'https://graph.microsoft.us', - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional - } - ``` - -:::TabTitle Helm chart (Kubernetes) - -1. Create the [Kubernetes Secret containing the OAuth 2.0 application client secret](https://docs.gitlab.com/charts/installation/secrets.html#microsoft-graph-client-secret-for-service-desk-emails): - - ```shell - kubectl create secret generic service-desk-email-client-secret --from-literal=secret=<YOUR-CLIENT_SECRET> - ``` - -1. Create the [Kubernetes Secret for the GitLab Service Desk email auth token](https://docs.gitlab.com/charts/installation/secrets.html#gitlab-service-desk-email-auth-token). - Replace `<name>` with the name of the [Helm release name](https://helm.sh/docs/intro/using_helm/) for the GitLab installation: - - ```shell - kubectl create secret generic <name>-service-desk-email-auth-token --from-literal=authToken=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64) - ``` - -1. Export the Helm values: - - ```shell - helm get values gitlab > gitlab_values.yaml - ``` - -1. Edit `gitlab_values.yaml`: - - ```yaml - global: - appConfig: - serviceDeskEmail: - enabled: true - address: "project_contact+%{key}@example.onmicrosoft.com" - user: "project_contact@example.onmicrosoft.com" - mailbox: inbox - inboxMethod: microsoft_graph - azureAdEndpoint: https://login.microsoftonline.com - graphEndpoint: https://graph.microsoft.com - tenantId: "YOUR-TENANT-ID" - clientId: "YOUR-CLIENT-ID" - clientSecret: - secret: service-desk-email-client-secret - key: secret - deliveryMethod: webhook - authToken: - secret: <name>-service-desk-email-auth-token - key: authToken - ``` - - For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), -configure the `azureAdEndpoint` and `graphEndpoint` settings. These fields are case-sensitive: - - ```yaml - global: - appConfig: - serviceDeskEmail: - [..] - azureAdEndpoint: https://login.microsoftonline.us - graphEndpoint: https://graph.microsoft.us - [..] - ``` - -1. Save the file and apply the new values: - - ```shell - helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab - ``` - -:::TabTitle Docker - -1. Edit `docker-compose.yml`: - - ```yaml - version: "3.6" - services: - gitlab: - environment: - GITLAB_OMNIBUS_CONFIG: | - gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" - gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" - gitlab_rails['service_desk_email_mailbox_name'] = "inbox" - gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' - gitlab_rails['service_desk_email_inbox_options'] = { - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional - } - ``` - -1. Save the file and restart GitLab: - - ```shell - docker compose up -d - ``` - -For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), -configure the `azure_ad_endpoint` and `graph_endpoint` settings: - -1. Edit `docker-compose.yml`: - - ```yaml - version: "3.6" - services: - gitlab: - environment: - GITLAB_OMNIBUS_CONFIG: | - gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" - gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" - gitlab_rails['service_desk_email_mailbox_name'] = "inbox" - gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' - gitlab_rails['service_desk_email_inbox_options'] = { - 'azure_ad_endpoint': 'https://login.microsoftonline.us', - 'graph_endpoint': 'https://graph.microsoft.us', - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional - } - ``` - -1. Save the file and restart GitLab: - - ```shell - docker compose up -d - ``` - -:::TabTitle Self-compiled (source) - -1. Edit `/home/git/gitlab/config/gitlab.yml`: - - ```yaml - service_desk_email: - enabled: true - address: "project_contact+%{key}@example.onmicrosoft.com" - user: "project_contact@example.onmicrosoft.com" - mailbox: "inbox" - delivery_method: webhook - log_path: "log/mailroom.log" - secret_file: .gitlab-mailroom-secret - inbox_method: "microsoft_graph" - inbox_options: - tenant_id: "<YOUR-TENANT-ID>" - client_id: "<YOUR-CLIENT-ID>" - client_secret: "<YOUR-CLIENT-SECRET>" - poll_interval: 60 # Optional - ``` - - For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), - configure the `azure_ad_endpoint` and `graph_endpoint` settings. For example: - - ```yaml - service_desk_email: - enabled: true - address: "project_contact+%{key}@example.onmicrosoft.com" - user: "project_contact@example.onmicrosoft.com" - mailbox: "inbox" - delivery_method: webhook - log_path: "log/mailroom.log" - secret_file: .gitlab-mailroom-secret - inbox_method: "microsoft_graph" - inbox_options: - azure_ad_endpoint: "https://login.microsoftonline.us" - graph_endpoint: "https://graph.microsoft.us" - tenant_id: "<YOUR-TENANT-ID>" - client_id: "<YOUR-CLIENT-ID>" - client_secret: "<YOUR-CLIENT-SECRET>" - poll_interval: 60 # Optional - ``` - -::EndTabs - -#### Configure a suffix for Service Desk alias email - -You can set a custom suffix in your project's Service Desk settings. - -A suffix can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). - -When configured, the custom suffix creates a new Service Desk email address, consisting of the -`service_desk_email_address` setting and a key of the format: `<project_full_path>-<custom_suffix>` - -Prerequisites: - -- You must have configured a [Service Desk alias email](#configure-service-desk-alias-email). - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Service Desk**. -1. Below **Email address suffix**, enter the suffix to use. -1. Select **Save changes**. - -For example, suppose the `mygroup/myproject` project Service Desk settings has the following configured: - -- Email address suffix is set to `support`. -- Service Desk email address is configured to `contact+%{key}@example.com`. - -The Service Desk email address for this project is: `contact+mygroup-myproject-support@example.com`. -The [incoming email](../../administration/incoming_email.md) address still works. - -If you don't configure a custom suffix, the default project identification is used for identifying -the project. - -### Configure email ingestion in multi-node environments - -A multi-node environment is a setup where GitLab is run across multiple servers -for scalability, fault tolerance, and performance reasons. - -GitLab uses a separate process called `mail_room` to ingest new unread emails -from the `incoming_email` and `service_desk_email` mailboxes. - -#### Helm chart (Kubernetes) - -The [GitLab Helm chart](https://docs.gitlab.com/charts/) is made up of multiple subcharts, and one of them is -the [Mailroom subchart](https://docs.gitlab.com/charts/charts/gitlab/mailroom/index.html). Configure the -[common settings for `incoming_email`](https://docs.gitlab.com/charts/installation/command-line-options.html#incoming-email-configuration) -and the [common settings for `service_desk_email`](https://docs.gitlab.com/charts/installation/command-line-options.html#service-desk-email-configuration). - -#### Linux package (Omnibus) - -In multi-node Linux package installation environments, run `mail_room` only on one node. Run it either on a single -`rails` node (for example, `application_role`) -or completely separately. - -##### Set up all nodes - -1. Add basic configuration for `incoming_email` and `service_desk_email` on every node - to render email addresses in the web UI and in generated emails. - - Find the `incoming_email` or `service_desk_email` section in `/etc/gitlab/gitlab.rb`: - - ::Tabs - - :::TabTitle `incoming_email` - - ```ruby - gitlab_rails['incoming_email_enabled'] = true - gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.com" - ``` - - :::TabTitle `service_desk_email` - - ```ruby - gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.com" - ``` - - ::EndTabs - -1. GitLab offers two methods to transport emails from `mail_room` to the GitLab -application. You can configure the `delivery_method` for each email setting individually: - 1. Recommended: `webhook` (default in GitLab 15.3 and later) sends the email payload via an API POST request to your GitLab - application. It uses a shared token to authenticate. If you choose this method, - make sure the `mail_room` process can access the API endpoint and distribute the shared - token across all application nodes. - - ::Tabs - - :::TabTitle `incoming_email` - - ```ruby - gitlab_rails['incoming_email_delivery_method'] = "webhook" - - # The URL that mail_room can contact. You can also use an internal URL or IP, - # just make sure mail_room can access the GitLab API via that address. - # Do not end with "/". - gitlab_rails['incoming_email_gitlab_url'] = "https://gitlab.example.com" - - # The shared secret file that should contain a random token. Make sure it's the same on every node. - gitlab_rails['incoming_email_secret_file'] = ".gitlab_mailroom_secret" - ``` - - :::TabTitle `service_desk_email` - - ```ruby - gitlab_rails['service_desk_email_delivery_method'] = "webhook" - - # The URL that mail_room can contact. You can also use an internal URL or IP, - # just make sure mail_room can access the GitLab API via that address. - # Do not end with "/". - - gitlab_rails['service_desk_email_gitlab_url'] = "https://gitlab.example.com" - - # The shared secret file that should contain a random token. Make sure it's the same on every node. - gitlab_rails['service_desk_email_secret_file'] = ".gitlab_mailroom_secret" - ``` - - ::EndTabs - - 1. [Deprecated in GitLab 16.0 and planned for removal in 17.0)](../../update/deprecations.md#sidekiq-delivery-method-for-incoming_email-and-service_desk_email-is-deprecated): - If you experience issues with the `webhook` setup, use `sidekiq` to deliver the email payload directly to GitLab Sidekiq using Redis. - - ::Tabs - - :::TabTitle `incoming_email` - - ```ruby - # It uses the Redis configuration to directly add Sidekiq jobs - gitlab_rails['incoming_email_delivery_method'] = "sidekiq" - ``` - - :::TabTitle `service_desk_email` - - ```ruby - # It uses the Redis configuration to directly add Sidekiq jobs - gitlab_rails['service_desk_email_delivery_method'] = "sidekiq" - ``` - - ::EndTabs - -1. Disable `mail_room` on all nodes that should not run email ingestion. For example, in `/etc/gitlab/gitlab.rb`: - - ```ruby - mailroom['enabled'] = false - ``` - -1. [Reconfigure GitLab](../../administration/restart_gitlab.md) for the changes to take effect. - -##### Set up a single email ingestion node - -After setting up all nodes and disabling the `mail_room` process, enable `mail_room` on a single node. -This node polls the mailboxes for `incoming_email` and `service_desk_email` on a regular basis and -move new unread emails to GitLab. - -1. Choose an existing node that additionally handles email ingestion. -1. Add [full configuration and credentials](../../administration/incoming_email.md#configuration-examples) - for `incoming_email` and `service_desk_email`. -1. Enable `mail_room` on this node. For example, in `/etc/gitlab/gitlab.rb`: - - ```ruby - mailroom['enabled'] = true - ``` - -1. [Reconfigure GitLab](../../administration/restart_gitlab.md) on this node for the changes to take effect. - -## Use Service Desk - -You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). -In these issues, you can also see our friendly neighborhood [Support Bot](#support-bot-user). - -### View Service Desk email address - -To check what the Service Desk email address is for your project: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Monitor > Service Desk**. - -The email address is available at the top of the issue list. - -### As an end user (issue creator) - -> Support for additional email headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346600) in GitLab 14.6. In earlier versions, the Service Desk email address had to be in the "To" field. - -To create a Service Desk issue, an end user does not need to know anything about -the GitLab instance. They just send an email to the address they are given, and -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 -are sent as emails: - - - -Any responses they send via email are displayed in the issue itself. - -For information about headers used for treating email, see -[the incoming email documentation](../../administration/incoming_email.md#accepted-headers). - -### As a responder to the issue - -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 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 usually do in GitLab: - - - -- The project's visibility (private, internal, public) does not affect Service Desk. -- The path to the project, including its group or namespace, is shown in emails. - -#### View Service Desk issues - -Prerequisites: - -- You must have at least the Reporter role for the project. - -To view Service Desk issues: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Monitor > Service Desk**. - -### Email contents and formatting - -#### Special HTML formatting in HTML emails - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109811) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116809) in GitLab 15.11. Feature flag `service_desk_html_to_text_email_handler` removed. - -HTML emails show HTML formatting, such as: - -- Tables -- Blockquotes -- Images -- Collapsible sections - -#### Files attached to comments - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386860) in GitLab 15.10. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. -On GitLab.com, this feature is available. - -If a comment contains any attachments and their total size is less than or equal to 10 MB, these -attachments are sent as part of the email. In other cases, the email contains links to the attachments. - -In GitLab 15.9 and earlier, uploads to a comment are sent as links in the email. - -## Privacy considerations - -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108901) the minimum required role to view the creator's and participant's email in GitLab 15.9. - -Service Desk issues are [confidential](issues/confidential_issues.md), so they are -only visible to project members. The project owner can -[make an issue public](issues/confidential_issues.md#in-an-existing-issue). -When a Service Desk issue becomes public, the issue creator's and participants' email addresses are -visible to signed-in users with at least the Reporter role for the project. - -In GitLab 15.8 and earlier, when a Service Desk issue becomes public, the issue creator's email -address is disclosed to everyone who can view the project. - -Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless -of their role** in the project. - -The unique internal email address is visible to project members at least -the Reporter role in your GitLab instance. -An external user (issue creator) cannot see the internal email address -displayed in the information note. - -### Moving a Service Desk issue - -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/372246) in GitLab 15.7: customers continue receiving notifications when a Service Desk issue is moved. - -You can move a Service Desk issue the same way you -[move a regular issue](issues/managing_issues.md#move-an-issue) in GitLab. - -If a Service Desk issue is moved to a different project with Service Desk enabled, -the customer who created the issue continues to receive email notifications. -Because a moved issue is first closed, then copied, the customer is considered to be a participant -in both issues. They continue to receive any notifications in the old issue and the new one. - -## Troubleshooting Service Desk - -### Emails to Service Desk do not create issues - -Your emails might be ignored because they contain one of the -[email headers that GitLab ignores](../../administration/incoming_email.md#rejected-headers). +<!-- This redirect file can be deleted after <2023-10-24>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/img/service_desk_confirmation_email.png b/doc/user/project/service_desk/img/service_desk_confirmation_email.png Binary files differindex e08dced1e38..e08dced1e38 100644 --- a/doc/user/project/img/service_desk_confirmation_email.png +++ b/doc/user/project/service_desk/img/service_desk_confirmation_email.png diff --git a/doc/user/project/img/service_desk_issue_tracker.png b/doc/user/project/service_desk/img/service_desk_issue_tracker.png Binary files differindex 0fde4c182cf..0fde4c182cf 100644 --- a/doc/user/project/img/service_desk_issue_tracker.png +++ b/doc/user/project/service_desk/img/service_desk_issue_tracker.png diff --git a/doc/user/project/img/service_desk_reply.png b/doc/user/project/service_desk/img/service_desk_reply.png Binary files differindex ae6ce31713b..ae6ce31713b 100644 --- a/doc/user/project/img/service_desk_reply.png +++ b/doc/user/project/service_desk/img/service_desk_reply.png diff --git a/doc/user/project/img/service_desk_thread.png b/doc/user/project/service_desk/img/service_desk_thread.png Binary files differindex 8d8ac39cc5b..8d8ac39cc5b 100644 --- a/doc/user/project/img/service_desk_thread.png +++ b/doc/user/project/service_desk/img/service_desk_thread.png diff --git a/doc/user/project/service_desk/index.md b/doc/user/project/service_desk/index.md new file mode 100644 index 00000000000..208e798bd21 --- /dev/null +++ b/doc/user/project/service_desk/index.md @@ -0,0 +1,912 @@ +--- +stage: Monitor +group: Respond +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Service Desk **(FREE ALL)** + +With Service Desk, your customers +can email you bug reports, feature requests, or general feedback. +Service Desk provides a unique email address, so they don't need their own GitLab accounts. + +Service Desk emails are created in your GitLab project as new issues. +Your team can respond directly from the project, while customers interact with the thread only +through email. + +## Service Desk workflow + +For example, 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 works for you: + +1. You provide a project-specific email address to your paying customers, who can email you directly + from the application. +1. Each email they send creates an issue in the appropriate project. +1. Your team members go to the Service Desk issue tracker, where they can see new support + requests and respond inside associated issues. +1. Your team communicates with the customer to understand the request. +1. Your team starts working on implementing code to solve your customer's problem. +1. When your team finishes the implementation, the merge request is merged and the issue + is closed automatically. + +Meanwhile: + +- The customer interacts with your team entirely through email, without needing access to your + GitLab instance. +- Your team saves time by not having to leave GitLab (or set up integrations) to follow up with + your customer. + +## Configure Service Desk + +By default, Service Desk is active in new projects. +If it's not active, you can do it in the project's settings. + +Prerequisites: + +- You must have at least the Maintainer role for the project. +- On GitLab self-managed, you must [set up incoming email](../../../administration/incoming_email.md#set-it-up) + for the GitLab instance. You should use + [email sub-addressing](../../../administration/incoming_email.md#email-sub-addressing), + but you can also use [catch-all mailboxes](../../../administration/incoming_email.md#catch-all-mailbox). + To do this, you must have administrator access. +- You must have enabled [issue](../settings/index.md#configure-project-visibility-features-and-permissions) + tracker for the project. + +To enable Service Desk in your project: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Turn on the **Activate Service Desk** toggle. +1. Optional. Complete the fields. + - [Add a suffix](#configure-a-suffix-for-service-desk-alias-email) to your Service Desk email address. + - If the list below **Template to append to all Service Desk issues** is empty, create a + [description template](../description_templates.md) in your repository. +1. Select **Save changes**. + +Service Desk is now enabled for this project. +If anyone sends an email to the address available below **Email address to use for Service Desk**, +GitLab creates a confidential issue with the email's content. + +### Improve your project's security + +To improve your Service Desk project's security, you should: + +- Put the Service Desk email address behind an alias on your email system so you can change it later. +- [Enable Akismet](../../../integration/akismet.md) on your GitLab instance to add spam checking to this service. + Unblocked email spam can result in many spam issues being created. + +### Customize emails sent to the requester + +> - Moved from GitLab Premium to GitLab Free in 13.2. +> - `UNSUBSCRIBE_URL`, `SYSTEM_HEADER`, `SYSTEM_FOOTER`, and `ADDITIONAL_TEXT` placeholders [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285512) in GitLab 15.9. +> - `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. +> - `%{ISSUE_URL}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408793) in GitLab 16.1. + +An email is sent to the requester when: + +- A requester submits a new ticket by emailing Service Desk. +- A new public comment is added on a Service Desk ticket. + - Editing a comment does not trigger a new email to be sent. + +You can customize the body of these email messages with Service Desk email templates. The templates +can include [GitLab Flavored Markdown](../../markdown.md) and [some HTML tags](../../markdown.md#inline-html). +For example, you can format the emails to include a header and footer in accordance with your +organization's brand guidelines. You can also include the following placeholders to display dynamic +content specific to the Service Desk ticket or your GitLab instance. + +| Placeholder | `thank_you.md` | `new_note.md` | Description +| ---------------------- | ---------------------- | ---------------------- | ----------- +| `%{ISSUE_ID}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket IID. +| `%{ISSUE_PATH}` | **{check-circle}** Yes | **{check-circle}** Yes | Project path appended with the ticket IID. +| `%{ISSUE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | URL of the ticket. External participants can only view the ticket if the project is public and ticket is not confidential (Service Desk tickets are confidential by default). +| `%{ISSUE_DESCRIPTION}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket description. If a user has edited the description, it may contain sensitive information that is not intended to be delivered to external participants. Use this placeholder with care and ideally only if you never modify descriptions or your team is aware of the template design. +| `%{UNSUBSCRIBE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe URL. +| `%{NOTE_TEXT}` | **{dotted-circle}** No | **{check-circle}** Yes | The new comment added to the ticket by a user. Take care to include this placeholder in `new_note.md`. Otherwise, the requesters may never see the updates on their Service Desk ticket. + +#### Thank you email + +When a requester submits an issue through Service Desk, GitLab sends a **thank you email**. +Without additional configuration, GitLab sends the default thank you email. + +To create a custom thank you email template: + +1. In the `.gitlab/service_desk_templates/` directory of your repository, create a file named `thank_you.md`. +1. Populate the Markdown file with text, [GitLab Flavored Markdown](../../markdown.md), + [some selected HTML tags](../../markdown.md#inline-html), and placeholders to customize the reply + to Service Desk requesters. + +#### New note email + +When a Service Desk ticket has a new public comment, GitLab sends a **new note email**. +Without additional configuration, GitLab sends the content of the comment. + +To keep your emails on brand, you can create a custom new note email template. To do so: + +1. In the `.gitlab/service_desk_templates/` directory in your repository, create a file named `new_note.md`. +1. Populate the Markdown file with text, [GitLab Flavored Markdown](../../markdown.md), + [some selected HTML tags](../../markdown.md#inline-html), and placeholders to customize the new note + email. Be sure to include the `%{NOTE_TEXT}` in the template to make sure the email recipient can + read the contents of the comment. + +#### Instance-level email header, footer, and additional text **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344819) in GitLab 15.9. + +Instance administrators can add a header, footer or additional text to the GitLab instance and apply +them to all emails sent from GitLab. If you're using a custom `thank_you.md` or `new_note.md`, to include +this content, add `%{SYSTEM_HEADER}`, `%{SYSTEM_FOOTER}`, or `%{ADDITIONAL_TEXT}` to your templates. + +For more information, see [System header and footer messages](../../../administration/appearance.md#system-header-and-footer-messages) and [custom additional text](../../../administration/settings/email.md#custom-additional-text). + +### Use a custom template for Service Desk tickets + +You can select one [description template](../description_templates.md#create-an-issue-template) +**per project** to be appended to every new Service Desk ticket's description. + +You can set description templates at various levels: + +- The entire [instance](../description_templates.md#set-instance-level-description-templates). +- A specific [group or subgroup](../description_templates.md#set-group-level-description-templates). +- A specific [project](../description_templates.md#set-a-default-template-for-merge-requests-and-issues). + +The templates are inherited. For example, in a project, you can also access templates set for the instance, or the project's parent groups. + +Prerequisite: + +- You must have [created a description template](../description_templates.md#create-an-issue-template). + +To use a custom description template with Service Desk: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. From the dropdown list **Template to append to all Service Desk issues**, search or select your template. + +### Support Bot user + +Behind the scenes, Service Desk works by the special Support Bot user creating issues. +This user isn't a [billable user](../../../subscriptions/self_managed/index.md#billable-users), +so it does not count toward the license limit count. + +In GitLab 16.0 and earlier, comments generated from Service Desk emails show `GitLab Support Bot` +as the author. In [GitLab 16.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/226995), +these comments show the email of the user who sent the email. +This feature only applies to comments made in GitLab 16.1 and later. + +#### Change the Support Bot's display name + +You can change the display name of the Support Bot user. Emails sent from Service Desk have +this name in the `From` header. The default display name is `GitLab Support Bot`. + +To edit the custom email display name: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Below **Email display name**, enter a new name. +1. Select **Save changes**. + +### Use an additional Service Desk alias email **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab 13.0. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. + +You can use an additional alias email address for Service Desk on an instance level. + +To do this, you must configure +a [`service_desk_email`](#configure-service-desk-alias-email) in the instance configuration. You can also configure a +[custom suffix](#configure-a-suffix-for-service-desk-alias-email) that replaces the default `-issue-` portion on the sub-addressing part. + +#### Configure Service Desk alias email + +NOTE: +On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address. You can still configure the +[custom suffix](#configure-a-suffix-for-service-desk-alias-email) in project settings. + +Service Desk uses the [incoming email](../../../administration/incoming_email.md) +configuration by default. However, to have a separate email address for Service Desk, +configure `service_desk_email` with a [custom suffix](#configure-a-suffix-for-service-desk-alias-email) +in project settings. + +Prerequisites: + +- The `address` must include the `+%{key}` placeholder in the `user` portion of the address, + before the `@`. The placeholder is used to identify the project where the issue should be created. +- The `service_desk_email` and `incoming_email` configurations must always use separate mailboxes + to make sure Service Desk emails are processed correctly. + +To configure a custom mailbox for Service Desk with IMAP, add the following snippets to your configuration file in full: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +NOTE: +In GitLab 15.3 and later, Service Desk uses `webhook` (internal API call) by default instead of enqueuing a Sidekiq job. +To use `webhook` on a Linux package installation running GitLab 15.3, you must generate a secret file. +For more information, see [merge request 5927](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5927). +In GitLab 15.4, reconfiguring a Linux package installation generates this secret file automatically, so no +secret file configuration setting is needed. +For more information, see [issue 1462](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1462). + +```ruby +gitlab_rails['service_desk_email_enabled'] = true +gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" +gitlab_rails['service_desk_email_email'] = "project_contact@gmail.com" +gitlab_rails['service_desk_email_password'] = "[REDACTED]" +gitlab_rails['service_desk_email_mailbox_name'] = "inbox" +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_host'] = "imap.gmail.com" +gitlab_rails['service_desk_email_port'] = 993 +gitlab_rails['service_desk_email_ssl'] = true +gitlab_rails['service_desk_email_start_tls'] = false +``` + +:::TabTitle Self-compiled (source) + +```yaml +service_desk_email: + enabled: true + address: "project_contact+%{key}@example.com" + user: "project_contact@example.com" + password: "[REDACTED]" + host: "imap.gmail.com" + delivery_method: webhook + secret_file: .gitlab-mailroom-secret + port: 993 + ssl: true + start_tls: false + log_path: "log/mailroom.log" + mailbox: "inbox" + idle_timeout: 60 + expunge_deleted: true +``` + +::EndTabs + +The configuration options are the same as for configuring +[incoming email](../../../administration/incoming_email.md#set-it-up). + +##### Use encrypted credentials + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9. + +Instead of having the Service Desk email credentials stored in plaintext in the configuration files, you can optionally +use an encrypted file for the incoming email credentials. + +Prerequisites: + +- To use encrypted credentials, you must first enable the + [encrypted configuration](../../../administration/encrypted_configuration.md). + +The supported configuration items for the encrypted file are: + +- `user` +- `password` + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. If initially your Service Desk configuration in `/etc/gitlab/gitlab.rb` looked like: + + ```ruby + gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" + gitlab_rails['service_desk_email_password'] = "examplepassword" + ``` + +1. Edit the encrypted secret: + + ```shell + sudo gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=vim + ``` + +1. Enter the unencrypted contents of the Service Desk email secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and remove the `service_desk` settings for `email` and `password`. +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +Use a Kubernetes secret to store the Service Desk email password. For more information, +read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails). + +:::TabTitle Docker + +1. If initially your Service Desk configuration in `docker-compose.yml` looked like: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" + gitlab_rails['service_desk_email_password'] = "examplepassword" + ``` + +1. Get inside the container, and edit the encrypted secret: + + ```shell + sudo docker exec -t <container_name> bash + gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=editor + ``` + +1. Enter the unencrypted contents of the Service Desk secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `docker-compose.yml` and remove the `service_desk` settings for `email` and `password`. +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. If initially your Service Desk configuration in `/home/git/gitlab/config/gitlab.yml` looked like: + + ```yaml + production: + service_desk_email: + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit the encrypted secret: + + ```shell + bundle exec rake gitlab:service_desk_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production + ``` + +1. Enter the unencrypted contents of the Service Desk secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `/home/git/gitlab/config/gitlab.yml` and remove the `service_desk_email:` settings for `user` and `password`. +1. Save the file and restart GitLab and Mailroom + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs + +##### Microsoft Graph + +> - Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9. +> - [Introduced for self-compiled (source) installs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116494) in GitLab 15.11. + +`service_desk_email` can be configured to read Microsoft Exchange Online mailboxes with the Microsoft +Graph API instead of IMAP. Set up an OAuth 2.0 application for Microsoft Graph +[the same way as for incoming email](../../../administration/incoming_email.md#microsoft-graph). + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, substituting + the values you want: + + ```ruby + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" + gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" + gitlab_rails['service_desk_email_mailbox_name'] = "inbox" + gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" + gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' + gitlab_rails['service_desk_email_inbox_options'] = { + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + + For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), + configure the `azure_ad_endpoint` and `graph_endpoint` settings. For example: + + ```ruby + gitlab_rails['service_desk_email_inbox_options'] = { + 'azure_ad_endpoint': 'https://login.microsoftonline.us', + 'graph_endpoint': 'https://graph.microsoft.us', + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Create the [Kubernetes Secret containing the OAuth 2.0 application client secret](https://docs.gitlab.com/charts/installation/secrets.html#microsoft-graph-client-secret-for-service-desk-emails): + + ```shell + kubectl create secret generic service-desk-email-client-secret --from-literal=secret=<YOUR-CLIENT_SECRET> + ``` + +1. Create the [Kubernetes Secret for the GitLab Service Desk email auth token](https://docs.gitlab.com/charts/installation/secrets.html#gitlab-service-desk-email-auth-token). + Replace `<name>` with the name of the [Helm release name](https://helm.sh/docs/intro/using_helm/) for the GitLab installation: + + ```shell + kubectl create secret generic <name>-service-desk-email-auth-token --from-literal=authToken=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64) + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + serviceDeskEmail: + enabled: true + address: "project_contact+%{key}@example.onmicrosoft.com" + user: "project_contact@example.onmicrosoft.com" + mailbox: inbox + inboxMethod: microsoft_graph + azureAdEndpoint: https://login.microsoftonline.com + graphEndpoint: https://graph.microsoft.com + tenantId: "YOUR-TENANT-ID" + clientId: "YOUR-CLIENT-ID" + clientSecret: + secret: service-desk-email-client-secret + key: secret + deliveryMethod: webhook + authToken: + secret: <name>-service-desk-email-auth-token + key: authToken + ``` + + For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), +configure the `azureAdEndpoint` and `graphEndpoint` settings. These fields are case-sensitive: + + ```yaml + global: + appConfig: + serviceDeskEmail: + [..] + azureAdEndpoint: https://login.microsoftonline.us + graphEndpoint: https://graph.microsoft.us + [..] + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" + gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" + gitlab_rails['service_desk_email_mailbox_name'] = "inbox" + gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" + gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' + gitlab_rails['service_desk_email_inbox_options'] = { + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), +configure the `azure_ad_endpoint` and `graph_endpoint` settings: + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" + gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" + gitlab_rails['service_desk_email_mailbox_name'] = "inbox" + gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" + gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' + gitlab_rails['service_desk_email_inbox_options'] = { + 'azure_ad_endpoint': 'https://login.microsoftonline.us', + 'graph_endpoint': 'https://graph.microsoft.us', + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + service_desk_email: + enabled: true + address: "project_contact+%{key}@example.onmicrosoft.com" + user: "project_contact@example.onmicrosoft.com" + mailbox: "inbox" + delivery_method: webhook + log_path: "log/mailroom.log" + secret_file: .gitlab-mailroom-secret + inbox_method: "microsoft_graph" + inbox_options: + tenant_id: "<YOUR-TENANT-ID>" + client_id: "<YOUR-CLIENT-ID>" + client_secret: "<YOUR-CLIENT-SECRET>" + poll_interval: 60 # Optional + ``` + + For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), + configure the `azure_ad_endpoint` and `graph_endpoint` settings. For example: + + ```yaml + service_desk_email: + enabled: true + address: "project_contact+%{key}@example.onmicrosoft.com" + user: "project_contact@example.onmicrosoft.com" + mailbox: "inbox" + delivery_method: webhook + log_path: "log/mailroom.log" + secret_file: .gitlab-mailroom-secret + inbox_method: "microsoft_graph" + inbox_options: + azure_ad_endpoint: "https://login.microsoftonline.us" + graph_endpoint: "https://graph.microsoft.us" + tenant_id: "<YOUR-TENANT-ID>" + client_id: "<YOUR-CLIENT-ID>" + client_secret: "<YOUR-CLIENT-SECRET>" + poll_interval: 60 # Optional + ``` + +::EndTabs + +#### Configure a suffix for Service Desk alias email + +You can set a custom suffix in your project's Service Desk settings. + +A suffix can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). + +When configured, the custom suffix creates a new Service Desk email address, consisting of the +`service_desk_email_address` setting and a key of the format: `<project_full_path>-<custom_suffix>` + +Prerequisites: + +- You must have configured a [Service Desk alias email](#configure-service-desk-alias-email). + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Below **Email address suffix**, enter the suffix to use. +1. Select **Save changes**. + +For example, suppose the `mygroup/myproject` project Service Desk settings has the following configured: + +- Email address suffix is set to `support`. +- Service Desk email address is configured to `contact+%{key}@example.com`. + +The Service Desk email address for this project is: `contact+mygroup-myproject-support@example.com`. +The [incoming email](../../../administration/incoming_email.md) address still works. + +If you don't configure a custom suffix, the default project identification is used for identifying +the project. + +### Configure email ingestion in multi-node environments + +A multi-node environment is a setup where GitLab is run across multiple servers +for scalability, fault tolerance, and performance reasons. + +GitLab uses a separate process called `mail_room` to ingest new unread emails +from the `incoming_email` and `service_desk_email` mailboxes. + +#### Helm chart (Kubernetes) + +The [GitLab Helm chart](https://docs.gitlab.com/charts/) is made up of multiple subcharts, and one of them is +the [Mailroom subchart](https://docs.gitlab.com/charts/charts/gitlab/mailroom/index.html). Configure the +[common settings for `incoming_email`](https://docs.gitlab.com/charts/installation/command-line-options.html#incoming-email-configuration) +and the [common settings for `service_desk_email`](https://docs.gitlab.com/charts/installation/command-line-options.html#service-desk-email-configuration). + +#### Linux package (Omnibus) + +In multi-node Linux package installation environments, run `mail_room` only on one node. Run it either on a single +`rails` node (for example, `application_role`) +or completely separately. + +##### Set up all nodes + +1. Add basic configuration for `incoming_email` and `service_desk_email` on every node + to render email addresses in the web UI and in generated emails. + + Find the `incoming_email` or `service_desk_email` section in `/etc/gitlab/gitlab.rb`: + + ::Tabs + + :::TabTitle `incoming_email` + + ```ruby + gitlab_rails['incoming_email_enabled'] = true + gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.com" + ``` + + :::TabTitle `service_desk_email` + + ```ruby + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.com" + ``` + + ::EndTabs + +1. GitLab offers two methods to transport emails from `mail_room` to the GitLab +application. You can configure the `delivery_method` for each email setting individually: + 1. Recommended: `webhook` (default in GitLab 15.3 and later) sends the email payload via an API POST request to your GitLab + application. It uses a shared token to authenticate. If you choose this method, + make sure the `mail_room` process can access the API endpoint and distribute the shared + token across all application nodes. + + ::Tabs + + :::TabTitle `incoming_email` + + ```ruby + gitlab_rails['incoming_email_delivery_method'] = "webhook" + + # The URL that mail_room can contact. You can also use an internal URL or IP, + # just make sure mail_room can access the GitLab API via that address. + # Do not end with "/". + gitlab_rails['incoming_email_gitlab_url'] = "https://gitlab.example.com" + + # The shared secret file that should contain a random token. Make sure it's the same on every node. + gitlab_rails['incoming_email_secret_file'] = ".gitlab_mailroom_secret" + ``` + + :::TabTitle `service_desk_email` + + ```ruby + gitlab_rails['service_desk_email_delivery_method'] = "webhook" + + # The URL that mail_room can contact. You can also use an internal URL or IP, + # just make sure mail_room can access the GitLab API via that address. + # Do not end with "/". + + gitlab_rails['service_desk_email_gitlab_url'] = "https://gitlab.example.com" + + # The shared secret file that should contain a random token. Make sure it's the same on every node. + gitlab_rails['service_desk_email_secret_file'] = ".gitlab_mailroom_secret" + ``` + + ::EndTabs + + 1. [Deprecated in GitLab 16.0 and planned for removal in 17.0)](../../../update/deprecations.md#sidekiq-delivery-method-for-incoming_email-and-service_desk_email-is-deprecated): + If you experience issues with the `webhook` setup, use `sidekiq` to deliver the email payload directly to GitLab Sidekiq using Redis. + + ::Tabs + + :::TabTitle `incoming_email` + + ```ruby + # It uses the Redis configuration to directly add Sidekiq jobs + gitlab_rails['incoming_email_delivery_method'] = "sidekiq" + ``` + + :::TabTitle `service_desk_email` + + ```ruby + # It uses the Redis configuration to directly add Sidekiq jobs + gitlab_rails['service_desk_email_delivery_method'] = "sidekiq" + ``` + + ::EndTabs + +1. Disable `mail_room` on all nodes that should not run email ingestion. For example, in `/etc/gitlab/gitlab.rb`: + + ```ruby + mailroom['enabled'] = false + ``` + +1. [Reconfigure GitLab](../../../administration/restart_gitlab.md) for the changes to take effect. + +##### Set up a single email ingestion node + +After setting up all nodes and disabling the `mail_room` process, enable `mail_room` on a single node. +This node polls the mailboxes for `incoming_email` and `service_desk_email` on a regular basis and +move new unread emails to GitLab. + +1. Choose an existing node that additionally handles email ingestion. +1. Add [full configuration and credentials](../../../administration/incoming_email.md#configuration-examples) + for `incoming_email` and `service_desk_email`. +1. Enable `mail_room` on this node. For example, in `/etc/gitlab/gitlab.rb`: + + ```ruby + mailroom['enabled'] = true + ``` + +1. [Reconfigure GitLab](../../../administration/restart_gitlab.md) on this node for the changes to take effect. + +## Use Service Desk + +You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). +In these issues, you can also see our friendly neighborhood [Support Bot](#support-bot-user). + +### View Service Desk email address + +To check what the Service Desk email address is for your project: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Monitor > Service Desk**. + +The email address is available at the top of the issue list. + +### As an end user (issue creator) + +> Support for additional email headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346600) in GitLab 14.6. In earlier versions, the Service Desk email address had to be in the "To" field. + +To create a Service Desk issue, an end user does not need to know anything about +the GitLab instance. They just send an email to the address they are given, and +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 +are sent as emails: + + + +Any responses they send via email are displayed in the issue itself. + +For information about headers used for treating email, see +[the incoming email documentation](../../../administration/incoming_email.md#accepted-headers). + +### As a responder to the issue + +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 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 usually do in GitLab: + + + +- The project's visibility (private, internal, public) does not affect Service Desk. +- The path to the project, including its group or namespace, is shown in emails. + +#### View Service Desk issues + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To view Service Desk issues: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Monitor > Service Desk**. + +### Email contents and formatting + +#### Special HTML formatting in HTML emails + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109811) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116809) in GitLab 15.11. Feature flag `service_desk_html_to_text_email_handler` removed. + +HTML emails show HTML formatting, such as: + +- Tables +- Blockquotes +- Images +- Collapsible sections + +#### Files attached to comments + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386860) in GitLab 15.10. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. +On GitLab.com, this feature is available. + +If a comment contains any attachments and their total size is less than or equal to 10 MB, these +attachments are sent as part of the email. In other cases, the email contains links to the attachments. + +In GitLab 15.9 and earlier, uploads to a comment are sent as links in the email. + +## Privacy considerations + +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108901) the minimum required role to view the creator's and participant's email in GitLab 15.9. + +Service Desk issues are [confidential](../issues/confidential_issues.md), so they are +only visible to project members. The project owner can +[make an issue public](../issues/confidential_issues.md#in-an-existing-issue). +When a Service Desk issue becomes public, the issue creator's and participants' email addresses are +visible to signed-in users with at least the Reporter role for the project. + +In GitLab 15.8 and earlier, when a Service Desk issue becomes public, the issue creator's email +address is disclosed to everyone who can view the project. + +Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless +of their role** in the project. + +The unique internal email address is visible to project members at least +the Reporter role in your GitLab instance. +An external user (issue creator) cannot see the internal email address +displayed in the information note. + +### Moving a Service Desk issue + +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/372246) in GitLab 15.7: customers continue receiving notifications when a Service Desk issue is moved. + +You can move a Service Desk issue the same way you +[move a regular issue](../issues/managing_issues.md#move-an-issue) in GitLab. + +If a Service Desk issue is moved to a different project with Service Desk enabled, +the customer who created the issue continues to receive email notifications. +Because a moved issue is first closed, then copied, the customer is considered to be a participant +in both issues. They continue to receive any notifications in the old issue and the new one. + +## Troubleshooting Service Desk + +### Emails to Service Desk do not create issues + +Your emails might be ignored because they contain one of the +[email headers that GitLab ignores](../../../administration/incoming_email.md#rejected-headers). diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 8330b8c14bc..087330431ad 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -4,7 +4,7 @@ group: Import and Integrate 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" --- -# Migrating projects using file exports **(FREE)** +# Migrating projects using file exports **(FREE ALL)** Existing projects on any self-managed GitLab instance or GitLab.com can be exported to a file and then imported into another GitLab instance. You can also copy GitLab projects to another location with more automation by @@ -155,14 +155,16 @@ For a quick overview, items that are exported include: - Labels - Milestones - Snippets +- Releases - Time tracking and other project entities - Design management files and data - LFS objects - Issue boards -- Pipelines history +- CI/CD pipelines and pipeline schedules +- Protected branches and tags - Push rules - Emoji reactions -- Group members as long as the user has the Maintainer role in the +- Project and inherited group members, as long as the user has the Maintainer role in the exported project's group or is an administrator ### Items that are not exported @@ -212,7 +214,7 @@ may be possible for an attacker to steal your sensitive data. To import a project: -1. When [creating a new project](../index.md#create-a-project), +1. When [creating a new project](../index.md), select **Import project**. 1. In **Import project from**, select **GitLab export**. 1. Enter your project name and URL. Then select the file you exported previously. diff --git a/doc/user/project/settings/import_export_troubleshooting.md b/doc/user/project/settings/import_export_troubleshooting.md index c3abfa015a6..79401a7734a 100644 --- a/doc/user/project/settings/import_export_troubleshooting.md +++ b/doc/user/project/settings/import_export_troubleshooting.md @@ -187,6 +187,13 @@ e = Projects::ImportExport::ExportService.new(p,u) e.send(:version_saver).send(:save) e.send(:repo_saver).send(:save) +e.send(:avatar_saver).send(:save) +e.send(:project_tree_saver).send(:save) +e.send(:uploads_saver).send(:save) +e.send(:wiki_repo_saver).send(:save) +e.send(:lfs_saver).send(:save) +e.send(:snippets_repo_saver).send(:save) +e.send(:design_repo_saver).send(:save) ## continue using `e.send(:exporter_name).send(:save)` going through the list of exporters # The following line should show you the export_path similar to /var/opt/gitlab/gitlab-rails/shared/tmp/gitlab_exports/@hashed/49/94/4994.... diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 4a7e7d2fe7d..6c2140595d9 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -5,7 +5,7 @@ info: 'To determine the technical writer assigned to the Stage/Group associated type: reference, index, howto --- -# Project settings **(FREE)** +# Project settings **(FREE ALL)** Use the **Settings** page to manage the configuration options in your [project](../index.md). @@ -46,7 +46,7 @@ If you're an instance administrator, you can administer all project topics from NOTE: The assigned topics are visible only to users with access to the project, but everyone can see which topics exist on the GitLab instance. Do not include sensitive information in the name of a topic. -## Add a compliance framework to a project **(PREMIUM)** +## Add a compliance framework to a project **(PREMIUM ALL)** You can [add compliance frameworks to projects](../../group/compliance_frameworks.md#add-a-compliance-framework-to-a-project) @@ -74,7 +74,7 @@ Use the toggles to enable or disable features in the project. | **Repository** | **{check-circle}** Yes | Enables [repository](../repository/index.md) functionality. | **Merge requests** | **{check-circle}** Yes | Enables [merge request](../merge_requests/index.md) functionality; also see [Merge request settings](#configure-merge-request-settings-for-a-project). | **Forks** | **{check-circle}** Yes | Enables [forking](../repository/forking_workflow.md) functionality. -| **Git Large File Storage (LFS)** | **{dotted-circle}** No | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). +| **Git Large File Storage (LFS)** | **{dotted-circle}** No | Enables the use of [large files](../../../topics/git/lfs/index.md). | **Packages** | **{dotted-circle}** No | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. | **CI/CD** | **{check-circle}** Yes | Enables [CI/CD](../../../ci/index.md) functionality. | **Container Registry** | **{dotted-circle}** No | Activates a [registry](../../packages/container_registry/index.md) for your Docker images. @@ -161,7 +161,7 @@ Prerequisites: Configure your project's merge request settings: - Set up the [merge request method](../merge_requests/methods/index.md) (merge commit, fast-forward merge). -- Add merge request [description templates](../description_templates.md#description-templates). +- Add merge request [description templates](../description_templates.md). - Enable [merge request approvals](../merge_requests/approvals/index.md). - Enable [status checks](../merge_requests/status_checks.md). - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). @@ -175,7 +175,7 @@ Configure your project's merge request settings: ## Service Desk -Enable [Service Desk](../service_desk.md) for your project to offer customer support. +Enable [Service Desk](../service_desk/index.md) for your project to offer customer support. ## Export project @@ -312,7 +312,7 @@ To delete a project: This action deletes the project and all associated resources (such as issues and merge requests). -### Delayed project deletion **(PREMIUM)** +### Delayed project deletion **(PREMIUM ALL)** > - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. > - [Disabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95495) in GitLab 15.3. @@ -346,7 +346,7 @@ To immediately delete a project marked for deletion: 1. In the **Delete this project** section, select **Delete project**. 1. On the confirmation dialog, enter the project name and select **Yes, delete project**. -## Restore a project **(PREMIUM)** +## Restore a project **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. @@ -381,7 +381,7 @@ Automatically [create](../../../operations/incident_management/alerts.md#trigger Configure Error Tracking to discover and view [Sentry errors within GitLab](../../../operations/error_tracking.md). -### Status Page **(ULTIMATE)** +### Status Page **(ULTIMATE ALL)** [Add Storage credentials](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) to enable the syncing of public Issues to a [deployed status page](../../../operations/incident_management/status_page.md#create-a-status-page-project). diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index f4652d592f0..78620eb2ab3 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -81,6 +81,9 @@ To revoke a project access token: The scope determines the actions you can perform when you authenticate with a project access token. +NOTE: +See the warning in [create a project access token](#create-a-project-access-token) regarding internal projects. + | Scope | Description | |:-------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------| | `api` | Grants complete read and write access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | diff --git a/doc/user/project/system_notes.md b/doc/user/project/system_notes.md index 56873c328fa..84ff9efbd14 100644 --- a/doc/user/project/system_notes.md +++ b/doc/user/project/system_notes.md @@ -4,7 +4,7 @@ group: Source Code 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 --- -# System notes **(FREE)** +# System notes **(FREE ALL)** System notes are short descriptions that help you understand the history of events that occur during the life cycle of a GitLab object, such as: diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 9b5469f6cec..ec8d886c68e 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Time tracking **(FREE)** +# Time tracking **(FREE ALL)** You can estimate and track the time you spend on [issues](issues/index.md) and [merge requests](merge_requests/index.md). diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 45abcd867c0..994ed244832 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -4,7 +4,7 @@ group: IDE 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 --- -# Web IDE **(FREE)** +# Web IDE **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7. @@ -217,3 +217,16 @@ You cannot use interactive web terminals to interact with a runner. However, you can use a terminal to install dependencies and compile and debug code. For more information about configuring a workspace that supports interactive web terminals, see [remote development](../remote_development/index.md). + +## Troubleshooting + +When working with the Web IDE, you might encounter the following issues. + +### Character offset in the Web IDE + +When you type in the Web IDE, you might get a four-character offset. To resolve the issue, do one of the following: + +- Add `"editor.disableMonospaceOptimizations": true` to your settings. +- Modify your `"editor.font"` setting. + +For more information, see [VS Code issue 80170](https://github.com/microsoft/vscode/issues/80170). diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 41fd7e81db5..916c8abf066 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# Group wikis **(PREMIUM)** +# Group wikis **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in GitLab 13.5. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 4a53faeee73..71fc4dd20a3 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# Wiki **(FREE)** +# Wiki **(FREE ALL)** > - Page loading [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/336792) to asynchronous in GitLab 14.9. > - Page slug encoding method [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71753) to `ERB::Util.url_encode` in GitLab 14.9. @@ -287,7 +287,7 @@ To hide the link to an external wiki: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **External wiki**. -1. In the **Enable integration** section, clear the **Active** checkbox. +1. Under **Enable integration**, clear the **Active** checkbox. 1. Select **Save changes**. ## Disable the project's wiki diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 472bbb81648..8c050caed17 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -4,7 +4,7 @@ group: Tenant Scale 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" --- -# Manage projects **(FREE)** +# Manage projects **(FREE ALL)** Most work in GitLab is done in a [project](../../user/project/index.md). Files and code are saved in projects, and most features are in the scope of projects. @@ -151,7 +151,7 @@ To delete a project: 1. Select **Delete project**. 1. Confirm this action by completing the field. -## View projects pending deletion **(PREMIUM)** +## View projects pending deletion **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3 for Administrators. > - [Tab renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/347468) from **Deleted projects** in GitLab 14.6. @@ -178,7 +178,15 @@ To view the activity of a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Manage > Activity**. -1. Select a tab to view the type of project activity. +1. Optional. To filter activity by contribution type, select a tab: + + - **All**: All contributions by project members. + - **Push events**: Push events in the project. + - **Merge events**: Accepted merge requests in the project. + - **Issue events**: Issues opened and closed in the project. + - **Comments**: Comments posted by project members. + - **Designs**: Designs added, updated, and removed in the project. + - **Team**: Members who joined and left the project. ## Search in projects diff --git a/doc/user/public_access.md b/doc/user/public_access.md index 57439a4595e..5f43f177e36 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Project and group visibility **(FREE)** +# Project and group visibility **(FREE ALL)** Projects and groups in GitLab can be private, internal, or public. diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md index 23a662ccfeb..bad62825ba5 100644 --- a/doc/user/report_abuse.md +++ b/doc/user/report_abuse.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 --- -# Report abuse **(FREE)** +# Report abuse **(FREE ALL)** You can report abuse from other GitLab users to GitLab administrators. diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index bc9de9357f6..75eed6d4b52 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -4,7 +4,7 @@ group: Tenant Scale 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 --- -# Reserved project and group names **(FREE)** +# Reserved project and group names **(FREE ALL)** Not all project & group names are allowed because they would conflict with existing routes used by GitLab. diff --git a/doc/user/rich_text_editor.md b/doc/user/rich_text_editor.md index ea85dfdbcb4..c60c89eb0de 100644 --- a/doc/user/rich_text_editor.md +++ b/doc/user/rich_text_editor.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Rich text editor **(FREE)** +# Rich text editor **(FREE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) for [wikis](project/wiki/index.md#rich-text-editor) in GitLab 14.0. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371931) for editing issue descriptions in GitLab 15.5 [with a flag](../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default. diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index 5a9f75f1d6c..c12d7889fb8 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Advanced search **(PREMIUM)** +# Advanced search **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -87,13 +87,17 @@ In user search, a [fuzzy query](https://www.elastic.co/guide/en/elasticsearch/re ## Known issues - You can only search files smaller than 1 MB. + For more information, see [issue 195764](https://gitlab.com/gitlab-org/gitlab/-/issues/195764). For self-managed GitLab instances, an administrator can [change this limit](../../integration/advanced_search/elasticsearch.md#advanced-search-configuration). - You can only use advanced search on the default branch of a project. + For more information, see [issue 229966](https://gitlab.com/gitlab-org/gitlab/-/issues/229966). - The search query must not contain any of the following characters: ```plaintext . , : ; / ` ' = ? $ & ^ | < > ( ) { } [ ] @ ``` + For more information, see [issue 325234](https://gitlab.com/gitlab-org/gitlab/-/issues/325234). - Search results show only the first match in a file. + For more information, see [issue 668](https://gitlab.com/gitlab-org/gitlab/-/issues/668). diff --git a/doc/user/search/command_palette.md b/doc/user/search/command_palette.md index ab284bd6a5f..671afe13ace 100644 --- a/doc/user/search/command_palette.md +++ b/doc/user/search/command_palette.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Command palette **(FREE)** +# Command palette **(FREE ALL)** > Introduced in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `command_palette`. Enabled by default. diff --git a/doc/user/search/exact_code_search.md b/doc/user/search/exact_code_search.md index 469d91b5194..8a64dc9e70f 100644 --- a/doc/user/search/exact_code_search.md +++ b/doc/user/search/exact_code_search.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Exact Code Search **(PREMIUM)** +# Exact Code Search **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105049) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `index_code_with_zoekt` for indexing and `search_code_with_zoekt` for searching. Both are disabled by default. diff --git a/doc/user/search/index.md b/doc/user/search/index.md index fe5ee3a5e0a..5600f18c61c 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -4,7 +4,7 @@ group: Global Search 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 --- -# Searching in GitLab **(FREE)** +# Searching in GitLab **(FREE ALL)** GitLab has two types of searches available: **basic** and **advanced**. diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index ac3c6bace09..d8b4d147d24 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab keyboard shortcuts **(FREE)** +# GitLab keyboard shortcuts **(FREE ALL)** GitLab has several keyboard shortcuts you can use to access its different features. @@ -92,17 +92,18 @@ relatively quickly to work, and they take you to another page in the project. These shortcuts are available when viewing issues: -| Keyboard shortcut | Description | -|------------------------------|-------------| -| <kbd>e</kbd> | Edit description. | -| <kbd>a</kbd> | Change assignee. | -| <kbd>m</kbd> | Change milestone. | -| <kbd>l</kbd> | Change label. | -| <kbd>r</kbd> | Start writing a comment. Pre-selected text is quoted in the comment. Can't be used to reply in a thread. | -| <kbd>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | -| <kbd>→</kbd> | Go to the next design. | -| <kbd>←</kbd> | Go to the previous design. | -| <kbd>Escape</kbd> | Close the design. | +| Keyboard shortcut | Description | +|-------------------------------|-------------| +| <kbd>e</kbd> | Edit description. | +| <kbd>a</kbd> | Change assignee. | +| <kbd>m</kbd> | Change milestone. | +| <kbd>l</kbd> | Change label. | +| <kbd>c</kbd> + <kbd>r</kbd> | Copy issue reference. | +| <kbd>r</kbd> | Start writing a comment. Pre-selected text is quoted in the comment. Can't be used to reply in a thread. | +| <kbd>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | +| <kbd>→</kbd> | Go to the next design. | +| <kbd>←</kbd> | Go to the previous design. | +| <kbd>Escape</kbd> | Close the design. | ### Merge requests @@ -116,6 +117,7 @@ These shortcuts are available when viewing [merge requests](project/merge_reques | <kbd>n</kbd> | | Move to next unresolved discussion. | | <kbd>p</kbd> | | Move to previous unresolved discussion. | | <kbd>b</kbd> | | Copy source branch name. | +| <kbd>c</kbd> + <kbd>r</kbd> | | Copy merge request reference. | | <kbd>r</kbd> | | Start writing a comment. Pre-selected text is quoted in the comment. Can't be used to reply in a thread. | | <kbd>c</kbd> | | Move to next commit. | | <kbd>x</kbd> | | Move to previous commit. | @@ -230,6 +232,14 @@ page (go to **Code > Repository graph**): | <kbd>Shift</kbd> + <kbd>↑</kbd> or <kbd>Shift</kbd> + <kbd>k</kbd> | Scroll to top. | | <kbd>Shift</kbd> + <kbd>↓</kbd> or <kbd>Shift</kbd> + <kbd>j</kbd> | Scroll to bottom. | +### Incidents + +These shortcuts are available when viewing incidents: + +| Keyboard shortcut | Description | +|-------------------------------|-------------| +| <kbd>c</kbd> + <kbd>r</kbd> | Copy incident reference. | + ### Wiki pages This shortcut is available when viewing a [wiki page](project/wiki/index.md): @@ -301,15 +311,16 @@ These shortcuts are available when using a [filtered search input](search/index. | <kbd>Command</kbd> | <kbd>Delete</kbd> | Clear entire search filter. | | <kbd>Option</kbd> | <kbd>Control</kbd> + <kbd>Delete</kbd> | Clear one token at a time. | -## Epics **(PREMIUM)** +## Epics **(PREMIUM ALL)** These shortcuts are available when viewing [epics](group/epics/index.md): -| Keyboard shortcut | Description | -|-------------------|-------------------| -| <kbd>r</kbd> | Start writing a comment. Pre-selected text is quoted in the comment. Can't be used to reply in a thread. | -| <kbd>e</kbd> | Edit description. | -| <kbd>l</kbd> | Change label. | +| Keyboard shortcut | Description | +|------------------------------|-------------------| +| <kbd>r</kbd> | Start writing a comment. Pre-selected text is quoted in the comment. Can't be used to reply in a thread. | +| <kbd>e</kbd> | Edit description. | +| <kbd>l</kbd> | Change label. | +| <kbd>c</kbd> + <kbd>r</kbd> | Copy epic reference. | ## Disable keyboard shortcuts diff --git a/doc/user/snippets.md b/doc/user/snippets.md index aace26b4bb0..a5a547727d3 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Snippets **(FREE)** +# Snippets **(FREE ALL)** With GitLab snippets, you can store and share bits of code and text with other users. You can [comment on](#comment-on-snippets), [clone](#clone-snippets), and @@ -247,8 +247,8 @@ GitLab forwards the spam to Akismet. than 10 files results in an error. - Revisions are not visible to the user on the GitLab UI, but [an issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/39271) for updates. -- The [maximum size for a snippet](../administration/snippets/index.md#snippets-content-size-limit) - is 50 MB, by default. +- The default [maximum size for a snippet](../administration/snippets/index.md) + is 50 MB. - Git LFS is not supported. ### Reduce snippets repository size diff --git a/doc/user/ssh.md b/doc/user/ssh.md index d92e3944521..f418cc5f6b7 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -4,7 +4,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 --- -# Use SSH keys to communicate with GitLab **(FREE)** +# Use SSH keys to communicate with GitLab **(FREE ALL)** Git is a distributed version control system, which means you can work locally, then share or *push* your changes to a server. In this case, the server you push to is GitLab. @@ -20,7 +20,7 @@ SSH uses two keys, a public key and a private key. - The public key can be distributed. - The private key should be protected. -It is not possible to reveal confidential data by uploading your public key. When you need to copy or upload your SSH public key, make sure you do not accidentally copy or upload your private key instead. +It is not possible to reveal confidential data by uploading your public key. When you need to copy or upload your SSH public key, make sure you do not accidentally copy or upload your private key instead. You can use your private key to [sign commits](project/repository/ssh_signed_commits/index.md), which makes your use of GitLab and your data even more secure. @@ -325,6 +325,7 @@ To use SSH with GitLab, copy your public key to your GitLab account: 1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **SSH Keys**. +1. Select **Add new key**. 1. In the **Key** box, paste the contents of your public key. If you manually copied the key, make sure you copy the entire key, which starts with `ssh-rsa`, `ssh-dss`, `ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`, diff --git a/doc/user/storage_management_automation.md b/doc/user/storage_management_automation.md new file mode 100644 index 00000000000..210aca4ee35 --- /dev/null +++ b/doc/user/storage_management_automation.md @@ -0,0 +1,1145 @@ +--- +type: howto +stage: Fulfillment +group: Utilization +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 +--- + +# Storage management automation **(FREE ALL)** + +You can manage your storage through the GitLab UI and the API. This page describes how to +automate storage analysis and cleanup to manage your [usage quota](usage_quotas.md). You can also +manage your storage usage by making your pipelines more efficient. For more information, see [pipeline efficiency](../ci/pipelines/pipeline_efficiency.md). + +You can also use the [GitLab community forum and Discord](https://about.gitlab.com/community/) to ask for help with API automation. + +## API requirements + +To automate storage management, your GitLab.com SaaS or self-managed instance must have access to the [GitLab REST API](../api/api_resources.md). + +### API authentication scope + +You must use the following scopes to [authenticate](../api/rest/index.md#authentication) with the API: + +- Storage analysis: + - Read API access with the `read_api` scope. + - At least the Developer role on all projects. +- Storage clean up: + - Full API access with the `api` scope. + - At least the Maintainer role on all projects. + +You can use command line tools or a programming language to interact with the REST API. + +### Command line + +You must install the following tools to send API requests: + +- Install `curl` with your preferred package manager. +- Install the [GitLab CLI](../editor_extensions/gitlab_cli/index.md) and use the `api` subcommand. +- Install `jq` to format JSON responses. For more information, see [Tips for productive DevOps workflows: JSON formatting with jq and CI/CD linting automation](https://about.gitlab.com/blog/2021/04/21/devops-workflows-json-format-jq-ci-cd-lint/). + +Example with `curl` and `jq`: + +```shell +export GITLAB_TOKEN=xxx + +curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" "https://gitlab.com/api/v4/user" | jq +``` + +Example with the [GitLab CLI](../editor_extensions/gitlab_cli/index.md): + +```shell +glab auth login + +glab api groups/YOURGROUPNAME/projects +``` + +#### Using the GitLab CLI + +Some API endpoints require [pagination](../api/rest/index.md#pagination) and subsequent page fetches to retrieve all results. The [GitLab CLI](../editor_extensions/gitlab_cli/index.md) provides the flag `--paginate`. + +Requests that require sending a POST body formatted as JSON data can be written as `key=value` pairs passed to the `--raw-field` parameter. + +For more information, see the [GitLab CLI endpoint documentation](../editor_extensions/gitlab_cli/index.md#core-commands). + +### API client libraries + +The storage management and cleanup automation methods described in this page use the [`python-gitlab`](https://python-gitlab.readthedocs.io/en/stable/) library in programmatic example. The `python-gitlab` library provides +a feature-rich programming interface. For more information about use cases for the `python-gitlab` library, +see [Efficient DevSecOps workflows: Hands-on `python-gitlab` API automation](https://about.gitlab.com/blog/2023/02/01/efficient-devsecops-workflows-hands-on-python-gitlab-api-automation/). + +For more information about other API client libraries, see [Third-party clients](../api/rest/index.md#third-party-clients). + +NOTE: +Use [GitLab Duo Code Suggestions](project/repository/code_suggestions.md) to write code more efficiently. + +## Strategies for storage analysis + +### Identify the storage types + +The [projects API endpoint](../api/projects.md#list-all-projects) provides statistics for projects +in your GitLab instance. To use the projects API endpoint, set the `statistics` key to boolean `true`. +This data provides insight into storage consumption of the project by the following storage types: + +- `storage_size`: Overall storage +- `lfs_objects_size`: LFS objects storage +- `job_artifacts_size`: Job artifacts storage +- `packages_size`: Packages storage +- `repository_size`: Git repository storage +- `snippets_size`: Snippets storage +- `uploads_size`: Uploads storage +- `wiki_size`: Wiki storage + +Additional queries are required for detailed storage statistics for [job artifacts](../api/job_artifacts.md), the [container registry](../api/container_registry.md), the [package registry](../api/packages.md) and [dependency proxy](../api/dependency_proxy.md). It is explained later in this how-to. + +Example that uses `curl` and `jq` on the command line: + +```shell +curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$GL_PROJECT_ID?statistics=true" | jq --compact-output '.id,.statistics' | jq +48349590 +{ + "commit_count": 2, + "storage_size": 90241770, + "repository_size": 3521, + "wiki_size": 0, + "lfs_objects_size": 0, + "job_artifacts_size": 90238249, + "pipeline_artifacts_size": 0, + "packages_size": 0, + "snippets_size": 0, + "uploads_size": 0 +} +``` + +Example that uses the [GitLab CLI](../editor_extensions/gitlab_cli/index.md): + +```shell +export GL_PROJECT_ID=48349590 +glab api --method GET projects/$GL_PROJECT_ID --field 'statistics=true' | jq --compact-output '.id,.statistics' | jq +48349590 +{ + "commit_count": 2, + "storage_size": 90241770, + "repository_size": 3521, + "wiki_size": 0, + "lfs_objects_size": 0, + "job_artifacts_size": 90238249, + "pipeline_artifacts_size": 0, + "packages_size": 0, + "snippets_size": 0, + "uploads_size": 0 +} +``` + +Example using the `python-gitlab` library: + +```python +project_obj = gl.projects.get(project.id, statistics=True) + +print("Project {n} statistics: {s}".format(n=project_obj.name_with_namespace, s=json.dump(project_obj.statistics, indent=4))) +``` + +You can find an example implementation in the script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` which is located in the [GitLab API with Python project](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/). Export the `GL_GROUP_ID` environment variable and run the script to see the project statistics printed in the terminal. + +```shell +export GL_TOKEN=xxx +export GL_GROUP_ID=56595735 + +pip3 install python-gitlab +python3 get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py + +Project Developer Evangelism and Technical Marketing at GitLab / playground / Artifact generator group / Gen Job Artifacts 4 statistics: { + "commit_count": 2, + "storage_size": 90241770, + "repository_size": 3521, + "wiki_size": 0, + "lfs_objects_size": 0, + "job_artifacts_size": 90238249, + "pipeline_artifacts_size": 0, + "packages_size": 0, + "snippets_size": 0, + "uploads_size": 0 +} +``` + +### Analyzing multiple subgroups and projects + +You can use automation to analyze multiple projects and groups. For example, you can start at the top namespace level, +and recursively analyze all subgroups and projects. You can also analyze different storage types. + +Here's an example of an algorithm that analyzes multiple subgroups and projects: + +1. Fetch the top-level namespace ID. You can copy the ID value from the [namespace/group overview](../user/namespace/index.md#types-of-namespaces). +1. Fetch all [subgroups](../api/groups.md#list-a-groups-subgroups) from the top-level group, and save the IDs in a list. +1. Loop over all groups and fetch all [projects from each group](../api/groups.md#list-a-groups-projects) and save the IDs in a list. +1. Identify the storage type to analyze, and collect the information from project attributes, like project statistics, and job artifacts. +1. Print an overview of all projects, grouped by group, and their storage information. + +Example with the [GitLab CLI](../editor_extensions/gitlab_cli/index.md): + +```shell +export GROUP_NAME="gitlab-de" + +# Return sub group IDs +glab api groups/$GROUP_NAME/subgroups | jq --compact-output '.[]' | jq --compact-output '.id' +12034712 +67218622 +67162711 +67640130 +16058698 +12034604 + +# Loop over all subgroups to get subgroups, until the result set is empty. Example group: 12034712 +glab api groups/12034712/subgroups | jq --compact-output '.[]' | jq --compact-output '.id' +56595735 +70677315 +67218606 +70812167 + +# Lowest group level +glab api groups/56595735/subgroups | jq --compact-output '.[]' | jq --compact-output '.id' +# empty result, return and continue with analysis + +# Fetch projects from all collected groups. Example group: 56595735 +glab api groups/56595735/projects | jq --compact-output '.[]' | jq --compact-output '.id' +48349590 +48349263 +38520467 +38520405 + +# Fetch storage types from a project (ID 48349590): Job artifacts in the `artifacts` key +glab api projects/48349590/jobs | jq --compact-output '.[]' | jq --compact-output '.id, .artifacts' +4828297946 +[{"file_type":"archive","size":52444993,"filename":"artifacts.zip","file_format":"zip"},{"file_type":"metadata","size":156,"filename":"metadata.gz","file_format":"gzip"},{"file_type":"trace","size":3140,"filename":"job.log","file_format":null}] +4828297945 +[{"file_type":"archive","size":20978113,"filename":"artifacts.zip","file_format":"zip"},{"file_type":"metadata","size":157,"filename":"metadata.gz","file_format":"gzip"},{"file_type":"trace","size":3147,"filename":"job.log","file_format":null}] +4828297944 +[{"file_type":"archive","size":10489153,"filename":"artifacts.zip","file_format":"zip"},{"file_type":"metadata","size":158,"filename":"metadata.gz","file_format":"gzip"},{"file_type":"trace","size":3146,"filename":"job.log","file_format":null}] +4828297943 +[{"file_type":"archive","size":5244673,"filename":"artifacts.zip","file_format":"zip"},{"file_type":"metadata","size":157,"filename":"metadata.gz","file_format":"gzip"},{"file_type":"trace","size":3145,"filename":"job.log","file_format":null}] +4828297940 +[{"file_type":"archive","size":1049089,"filename":"artifacts.zip","file_format":"zip"},{"file_type":"metadata","size":157,"filename":"metadata.gz","file_format":"gzip"},{"file_type":"trace","size":3140,"filename":"job.log","file_format":null}] +``` + +While the shell approach with `glab` works for smaller analysis, you should consider a script that +uses the API client libraries. This improves readability, storing data, flow control, testing, and reusability. + +You can also implement this algorithm with a Python script that uses the `python-gitlab` library: + +```python +#!/usr/bin/env python + +import datetime +import gitlab +import os +import sys + +GITLAB_SERVER = os.environ.get('GL_SERVER', 'https://gitlab.com') +GITLAB_TOKEN = os.environ.get('GL_TOKEN') # token requires developer permissions +PROJECT_ID = os.environ.get('GL_PROJECT_ID') #optional +GROUP_ID = os.environ.get('GL_GROUP_ID') #optional + +if __name__ == "__main__": + if not GITLAB_TOKEN: + print("🤔 Please set the GL_TOKEN env variable.") + sys.exit(1) + + gl = gitlab.Gitlab(GITLAB_SERVER, private_token=GITLAB_TOKEN, pagination="keyset", order_by="id", per_page=100) + + # Collect all projects, or prefer projects from a group id, or a project id + projects = [] + + # Direct project ID + if PROJECT_ID: + projects.append(gl.projects.get(PROJECT_ID)) + # Groups and projects inside + elif GROUP_ID: + group = gl.groups.get(GROUP_ID) + + for project in group.projects.list(include_subgroups=True, get_all=True): + manageable_project = gl.projects.get(project.id , lazy=True) + projects.append(manageable_project) + + for project in projects: + jobs = project.jobs.list(pagination="keyset", order_by="id", per_page=100, iterator=True) + for job in jobs: + print("DEBUG: ID {i}: {a}".format(i=job.id, a=job.attributes['artifacts'])) +``` + +The script outputs the project job artifacts in a JSON formatted list: + +```json +[ + { + "file_type": "archive", + "size": 1049089, + "filename": "artifacts.zip", + "file_format": "zip" + }, + { + "file_type": "metadata", + "size": 157, + "filename": "metadata.gz", + "file_format": "gzip" + }, + { + "file_type": "trace", + "size": 3146, + "filename": "job.log", + "file_format": null + } +] +``` + +The full script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` with specific examples for automating storage management and cleanup is located is located in the [GitLab API with Python](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/) project. To ensure the script doesn't reach [API rate limits](../api/rest/index.md#rate-limits), the example code is not optimized for parallel API requests. + +### Helper functions + +You may need to convert timestamp seconds into a duration format, or print raw bytes in a more +representative format. You can use the following helper functions to transform values for improved +readability: + +```shell +# Current Unix timestamp +date +%s + +# Convert `created_at` date time with timezone to Unix timestamp +date -d '2023-08-08T18:59:47.581Z' +%s +``` + +Example with Python that uses the `python-gitlab` API library: + +```python +def render_size_mb(v): + return "%.4f" % (v / 1024 / 1024) + +def render_age_time(v): + return str(datetime.timedelta(seconds = v)) + +# Convert `created_at` date time with timezone to Unix timestamp +def calculate_age(created_at_datetime): + created_at_ts = datetime.datetime.strptime(created_at_datetime, '%Y-%m-%dT%H:%M:%S.%fZ') + now = datetime.datetime.now() + return (now - created_at_ts).total_seconds() +``` + +## Managing storage in CI/CD pipelines + +WARNING: +Deleting job log and artifacts is a destructive action that cannot be reverted. Use with caution. Deleting certain files, including report artifacts, job logs, and metadata files, affects GitLab features that use these files as data sources. + +Job artifacts consume most of the pipeline storage, and job logs can also generate several hundreds of kilobytes. +You should delete the unnecessary job artifacts first and then clean up job logs after analysis. + +### Analyze pipeline storage + +The following example shows a response from a query for job artifacts in a project: + +```json +[ + { + "file_type": "archive", + "size": 1049089, + "filename": "artifacts.zip", + "file_format": "zip" + }, + { + "file_type": "metadata", + "size": 157, + "filename": "metadata.gz", + "file_format": "gzip" + }, + { + "file_type": "trace", + "size": 3146, + "filename": "job.log", + "file_format": null + } +] +``` + +The [Job API endpoint](../api/jobs.md#list-project-jobs) returns the job artifacts `file_type` key in the `artifacts` attribute. The the job artifacts `file_type` key provides insights into the specific artifact type: + +- `archive` is used for the generated job artifacts as a zip file. +- `metadata` is used for additional metadata in a Gzip file. +- `trace` is used for the `job.log` as a raw file. + +These three types are relevant for storage counting, and should be collected for a later summary. Based on the example code for fetching all projects, you can extend the Python script to do more analysis. + +The Python code loops over all projects, and fetches a `project_obj` object variable that contains all attributes. Because there can be many pipelines and jobs, fetching the list of jobs can be expensive in one call. Therefore, this is done using [keyset pagination](https://python-gitlab.readthedocs.io/en/stable/api-usage.html#pagination). The remaining step is to fetch the `artifacts` attribute from the `job` object. + +Based on how you implement the script, you could either: + +- Collect all job artifacts and print a summary table at the end of the script. +- Print the information immediately. + +Collecting the job artifacts provides a data structure that can be written as a cache file to +disk for example, which you can use when testing the implementation. + +In the following example, the job artifacts are collected in the `ci_job_artifacts` list. + +```python + ci_job_artifacts = [] + + for project in projects: + project_obj = gl.projects.get(project.id) + + jobs = project.jobs.list(pagination="keyset", order_by="id", per_page=100, iterator=True) + + for job in jobs: + artifacts = job.attributes['artifacts'] + #print("DEBUG: ID {i}: {a}".format(i=job.id, a=json.dumps(artifacts, indent=4))) + if not artifacts: + continue + + for a in artifacts: + data = { + "project_id": project_obj.id, + "project_web_url": project_obj.name, + "project_path_with_namespace": project_obj.path_with_namespace, + "job_id": job.id, + "artifact_filename": a['filename'], + "artifact_file_type": a['file_type'], + "artifact_size": a['size'] + } + + ci_job_artifacts.append(data) + + print("\nDone collecting data.") + + if len(ci_job_artifacts) > 0: + print("|Project|Job|Artifact name|Artifact type|Artifact size|\n|-|-|-|-|-|") #Start markdown friendly table + for artifact in ci_job_artifacts: + print('| [{project_name}]({project_web_url}) | {job_name} | {artifact_name} | {artifact_type} | {artifact_size} |'.format(project_name=artifact['project_path_with_namespace'], project_web_url=artifact['project_web_url'], job_name=artifact['job_id'], artifact_name=artifact['artifact_filename'], artifact_type=artifact['artifact_file_type'], artifact_size=render_size_mb(artifact['artifact_size']))) + else: + print("No artifacts found.") +``` + +At the end of the script, the job artifacts are printed as a Markdown formatted table. You can copy the table content into a new issue comment or description, or populate a Markdown file in a GitLab repository. + +```shell +$ python3 get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py + +|Project|Job|Artifact name|Artifact type|Artifact size| +|-|-|-|-|-| +| [gitlab-de/playground/artifact-gen-group/gen-job-artifacts-4](Gen Job Artifacts 4) | 4828297946 | artifacts.zip | archive | 50.0154 | +| [gitlab-de/playground/artifact-gen-group/gen-job-artifacts-4](Gen Job Artifacts 4) | 4828297946 | metadata.gz | metadata | 0.0001 | +| [gitlab-de/playground/artifact-gen-group/gen-job-artifacts-4](Gen Job Artifacts 4) | 4828297946 | job.log | trace | 0.0030 | +| [gitlab-de/playground/artifact-gen-group/gen-job-artifacts-4](Gen Job Artifacts 4) | 4828297945 | artifacts.zip | archive | 20.0063 | +| [gitlab-de/playground/artifact-gen-group/gen-job-artifacts-4](Gen Job Artifacts 4) | 4828297945 | metadata.gz | metadata | 0.0001 | +| [gitlab-de/playground/artifact-gen-group/gen-job-artifacts-4](Gen Job Artifacts 4) | 4828297945 | job.log | trace | 0.0030 | +``` + +The full example of the script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` is located in the [GitLab API with Python project](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/). To ensure the script doesn't hit [API rate limits](../api/rest/index.md#rate-limits), the example code is not optimized for parallel API requests. + +### Delete job artifacts + +You can use a filter to select the types of job artifacts to delete in bulk. A typical request: + +- Deletes job artifacts older than the specified number of days. +- Deletes job artifacts that exceed a specified amount of storage. For example, 100 MB. + +You can use a Python script to implement this type of filter. You can filter the API queries results, and compare +the `created_at` value to calculate the artifact age. + +You can also loop over all job artifacts and compare their `size` attribute to see whether they match +the size threshold. When a matching job has been found, it is marked for deletion. Because of the +analysis that happens when the script loops through job attributes, the job can be marked as deleted +only. When the collection loops remove the object locks, all marked as deleted jobs can actually be deleted. + +```python + for project in projects: + project_obj = gl.projects.get(project.id) + + jobs = project.jobs.list(pagination="keyset", order_by="id", per_page=100, iterator=True) + + for job in jobs: + artifacts = job.attributes['artifacts'] + if not artifacts: + continue + + # Advanced filtering: Age and Size + # Example: 90 days, 10 MB threshold (TODO: Make this configurable) + threshold_age = 90 * 24 * 60 * 60 + threshold_size = 10 * 1024 * 1024 + + # job age, need to parse API format: 2023-08-08T22:41:08.270Z + created_at = datetime.datetime.strptime(job.created_at, '%Y-%m-%dT%H:%M:%S.%fZ') + now = datetime.datetime.now() + age = (now - created_at).total_seconds() + # Shorter: Use a function + # age = calculate_age(job.created_at) + + for a in artifacts: + # ... removed analysis collection code for readability + + # Advanced filtering: match job artifacts age and size against thresholds + if (float(age) > float(threshold_age)) or (float(a['size']) > float(threshold_size)): + # mark job for deletion (cannot delete inside the loop) + jobs_marked_delete_artifacts.append(job) + + print("\nDone collecting data.") + + # Advanced filtering: Delete all job artifacts marked to being deleted. + for job in jobs_marked_delete_artifacts: + # delete the artifact + print("DEBUG", job) + job.delete_artifacts() + + # Print collection summary (removed for readability) +``` + +The full example of the script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` is located in the [GitLab API Python project](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/). + +#### Delete all job artifacts for a project + +If you do not need the project's [job artifacts](../ci/jobs/job_artifacts.md), you can +use the following command to delete them all. This action cannot be reverted. + +Job artifact deletion happens asynchronously in GitLab and can take a while to complete in the background. Subsequent analysis queries against the API can still return the artifacts as a false-positive result. Artifact deletion can take minutes or hours, depending on the artifacts to delete. To avoid confusion with results, do not run immediate additional API requests. + +The [artifacts for the most recent successful jobs](../ci/jobs/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs) are also kept by default. + +Example with curl: + +```shell +export GL_PROJECT_ID=48349590 + +curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" --request DELETE "https://gitlab.com/api/v4/projects/$GL_PROJECT_ID/artifacts" +``` + +Example with the [GitLab CLI](../editor_extensions/gitlab_cli/index.md): + +```shell +glab api --method GET projects/$GL_PROJECT_ID/jobs | jq --compact-output '.[]' | jq --compact-output '.id, .artifacts' + +glab api --method DELETE projects/$GL_PROJECT_ID/artifacts +``` + +Example with the [`python-gitlab` library](https://python-gitlab.readthedocs.io/en/stable/gl_objects/pipelines_and_jobs.html#jobs): + +```python + project.artifacts.delete() +``` + +### Delete job logs + +When you delete a job log you also [erase the entire job](../api/jobs.md#erase-a-job). + +Example with the [GitLab CLI](../editor_extensions/gitlab_cli/index.md): + +```shell +glab api --method GET projects/$GL_PROJECT_ID/jobs | jq --compact-output '.[]' | jq --compact-output '.id' + +4836226184 +4836226183 +4836226181 +4836226180 + +glab api --method POST projects/$GL_PROJECT_ID/jobs/4836226180/erase | jq --compact-output '.name,.status' +"generate-package: [1]" +"success" +``` + +In the `python-gitlab` API library, you must use [`job.erase()`](https://python-gitlab.readthedocs.io/en/stable/gl_objects/pipelines_and_jobs.html#jobs) instead of `job.delete_artifacts()`. +To avoid this API call from being blocked, set the script to sleep for a short amount of time between calls +that delete the job artifact. + +```python + for job in jobs_marked_delete_artifacts: + # delete the artifacts and job log + print("DEBUG", job) + #job.delete_artifacts() + job.erase() + # Sleep for 1 second + time.sleep(1) +``` + +The full example of the script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` is located in the [GitLab API with Python project](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/). + +Support for creating a retention policy for job logs is proposed in [issue 374717](https://gitlab.com/gitlab-org/gitlab/-/issues/374717). + +### Inventory of job artifacts expiry settings + +To manage artifact storage, you can update or configure when an artifact expires. +The expiry setting for artifacts are configured in each job configuration in the `.gitlab-ci.yml`. + +If you have multiple projects, and depending on how job definitions are organized in the CI/CD configuration, it may be difficult to locate the expiry setting. You can use a script to search the entire CI/CD configuration. This includes access to objects that are resolved after inheriting values, like `extends` or `!reference`. +The script retrieves merged CI/CD configuration files and searches for the artifacts key to: + +- Identify the jobs that don't have an expiry setting. +- Return the expiry setting for jobs that have the artifact expiry configured. + +The following process describes how the script searches for the artifact expiry setting: + +1. To generate a merged CI/CD configuration, the script loops over all projects and calls + the [`ci_lint()`](https://python-gitlab.readthedocs.io/en/stable/gl_objects/ci_lint.html) method. +1. The `yaml_load` function loads the merged configuration into Python data structures for more analysis. +1. A dictionary that also has the key `script` identifies itself as a job definition, where the `artifacts` + key might exists. +1. If yes, the script parses the sub key `expire_in` and stores the details to print later in a Markdown table summary. + +```python + ci_job_artifacts_expiry = {} + + # Loop over projects, fetch .gitlab-ci.yml, run the linter to get the full translated config, and extract the `artifacts:` setting + # https://python-gitlab.readthedocs.io/en/stable/gl_objects/ci_lint.html + for project in projects: + project_obj = gl.projects.get(project.id) + project_name = project_obj.name + project_web_url = project_obj.web_url + try: + lint_result = project.ci_lint.get() + if lint_result.merged_yaml is None: + continue + + ci_pipeline = yaml.safe_load(lint_result.merged_yaml) + #print("Project {p} Config\n{c}\n\n".format(p=project_name, c=json.dumps(ci_pipeline, indent=4))) + + for k in ci_pipeline: + v = ci_pipeline[k] + # This is a job object with `script` attribute + if isinstance(v, dict) and 'script' in v: + print(".", end="", flush=True) # Get some feedback that it is still looping + artifacts = v['artifacts'] if 'artifacts' in v else {} + + print("Project {p} job {j} artifacts {a}".format(p=project_name, j=k, a=json.dumps(artifacts, indent=4))) + + expire_in = None + if 'expire_in' in artifacts: + expire_in = artifacts['expire_in'] + + store_key = project_web_url + '_' + k + ci_job_artifacts_expiry[store_key] = { 'project_web_url': project_web_url, + 'project_name': project_name, + 'job_name': k, + 'artifacts_expiry': expire_in} + + except Exception as e: + print(f"Exception searching artifacts on ci_pipelines: {e}".format(e=e)) + + if len(ci_job_artifacts_expiry) > 0: + print("|Project|Job|Artifact expiry|\n|-|-|-|") #Start markdown friendly table + for k, details in ci_job_artifacts_expiry.items(): + if details['job_name'][0] == '.': + continue # ignore job templates that start with a '.' + print(f'| [{ details["project_name"] }]({details["project_web_url"]}) | { details["job_name"] } | { details["artifacts_expiry"] if details["artifacts_expiry"] is not None else "❌ N/A" } |') +``` + +The script generates a Markdown summary table with project name and URL, job name, and the `artifacts:expire_in` setting, or `N/A` if not existing. It does not print job templates starting with a `.` character which are not instantiated as runtime job objects that would generate artifacts. + +```shell +export GL_GROUP_ID=56595735 + +# Script requires pyyaml too. +pip3 install python-gitlab pyyaml + +python3 get_all_cicd_config_artifacts_expiry.py + +|Project|Job|Artifact expiry| +|-|-|-| +| [Gen Job Artifacts 4](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-4) | generator | 30 days | +| [Gen Job Artifacts with expiry and included jobs](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-expiry-included-jobs) | included-job10 | 10 days | +| [Gen Job Artifacts with expiry and included jobs](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-expiry-included-jobs) | included-job1 | 1 days | +| [Gen Job Artifacts with expiry and included jobs](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-expiry-included-jobs) | included-job30 | 30 days | +| [Gen Job Artifacts with expiry and included jobs](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-expiry-included-jobs) | generator | 30 days | +| [Gen Job Artifacts 2](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-2) | generator | ❌ N/A | +| [Gen Job Artifacts 1](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-1) | generator | ❌ N/A | +``` + +The `get_all_cicd_config_artifacts_expiry.py` script is located in the [GitLab API with Python project](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/). + +Alternatively, you can use [advanced search](search/advanced_search.md) with API requests. The following example uses the [scope: blobs](../api/search.md#scope-blobs-premium-all-2) to searches for the string `artifacts` in all `*.yml` files: + +```shell +# https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-expiry-included-jobs +export GL_PROJECT_ID=48349263 + +glab api --method GET projects/$GL_PROJECT_ID/search --field "scope=blobs" --field "search=expire_in filename:*.yml" +``` + +For more information about the inventory approach, see [How GitLab can help mitigate deletion of open source container images on Docker Hub](https://about.gitlab.com/blog/2023/03/16/how-gitlab-can-help-mitigate-deletion-open-source-images-docker-hub/). + +### Set the default expiry for job artifacts in projects + +Based on the output of the `get_all_cicd_config_artifacts_expiry.py` script, you can define the [default artifact expiration](../ci/yaml/index.md#default) in your `.gitlab-ci.yml` configuration. + +```yaml +default: + artifacts: + expire_in: 1 week +``` + +### Delete old pipelines + +Pipelines do not add to the overall storage consumption, but if you want to delete them you can use the following methods. + +Example using the [GitLab CLI](../editor_extensions/gitlab_cli/index.md): + +```shell +export GL_PROJECT_ID=48349590 + +glab api --method GET projects/$GL_PROJECT_ID/pipelines | jq --compact-output '.[]' | jq --compact-output '.id,.created_at' +960031926 +"2023-08-08T22:09:52.745Z" +959884072 +"2023-08-08T18:59:47.581Z" + +glab api --method DELETE projects/$GL_PROJECT_ID/pipelines/960031926 + +glab api --method GET projects/$GL_PROJECT_ID/pipelines | jq --compact-output '.[]' | jq --compact-output '.id,.created_at' +959884072 +"2023-08-08T18:59:47.581Z" +``` + +The `created_at` key must be converted from a timestamp to Unix epoch time, +for example with `date -d '2023-08-08T18:59:47.581Z' +%s`. In the next step, the +age can be calculated with the difference between now, and the pipeline creation +date. If the age is larger than the threshold, the pipeline should be deleted. + +The following example uses a Bash script that expects `jq` and the [GitLab CLI](../editor_extensions/gitlab_cli/index.md) installed, and authorized, and the exported environment variable `GL_PROJECT_ID`. + +The full script `get_cicd_pipelines_compare_age_threshold_example.sh` is located in the [GitLab API with Linux Shell](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-linux-shell) project. + +```shell +#/bin/bash + +CREATED_AT_ARR=$(glab api --method GET projects/$GL_PROJECT_ID/pipelines | jq --compact-output '.[]' | jq --compact-output '.created_at' | jq --raw-output @sh) + +for row in ${CREATED_AT_ARR[@]} +do + stripped=$(echo $row | xargs echo) + #echo $stripped #DEBUG + + CREATED_AT_TS=$(date -d "$stripped" +%s) + NOW=$(date +%s) + + AGE=$(($NOW-$CREATED_AT_TS)) + AGE_THRESHOLD=$((90*24*60*60)) # 90 days + + if [ $AGE -gt $AGE_THRESHOLD ]; + then + echo "Pipeline age $AGE older than threshold $AGE_THRESHOLD, should be deleted." + # TODO call glab to delete the pipeline. Needs an ID collected from the glab call above. + else + echo "Pipeline age $AGE not older than threshold $AGE_THRESHOLD. Ignore." + fi +done +``` + +You can use the [`python-gitlab` API library](https://python-gitlab.readthedocs.io/en/stable/gl_objects/pipelines_and_jobs.html#project-pipelines) and +the `created_at` attribute to implement a similar algorithm that compares the job artifact age: + +```python + # ... + + for pipeline in project.pipelines.list(iterator=True): + pipeline_obj = project.pipelines.get(pipeline.id) + print("DEBUG: {p}".format(p=json.dumps(pipeline_obj.attributes, indent=4))) + + created_at = datetime.datetime.strptime(pipeline.created_at, '%Y-%m-%dT%H:%M:%S.%fZ') + now = datetime.datetime.now() + age = (now - created_at).total_seconds() + + threshold_age = 90 * 24 * 60 * 60 + + if (float(age) > float(threshold_age)): + print("Deleting pipeline", pipeline.id) + pipeline_obj.delete() +``` + +The full example of the script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` is located in the [GitLab API with Python project](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/). + +Automatically deleting old pipelines in GitLab is tracked in [this feature proposal](https://gitlab.com/gitlab-org/gitlab/-/issues/338480). + +## Manage storage for Container Registries + +Container registries are available [in a project](../api/container_registry.md#within-a-project) or [in a group](../api/container_registry.md#within-a-group). Both locations require analysis and cleanup strategies. + +The following example uses using `curl` and `jq` for a project: + +```shell +export GL_PROJECT_ID=48057080 + +curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$GL_PROJECT_ID/registry/repositories" | jq --compact-output '.[]' | jq --compact-output '.id,.location' | jq +4435617 +"registry.gitlab.com/gitlab-de/playground/container-package-gen-group/docker-alpine-generator" + +curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" "https://gitlab.com/api/v4/registry/repositories/4435617?size=true" | jq --compact-output '.id,.location,.size' +4435617 +"registry.gitlab.com/gitlab-de/playground/container-package-gen-group/docker-alpine-generator" +3401613 +``` + +The following example uses the [GitLab CLI](../editor_extensions/gitlab_cli/index.md) for a project: + +```shell +export GL_PROJECT_ID=48057080 + +glab api --method GET projects/$GL_PROJECT_ID/registry/repositories | jq --compact-output '.[]' | jq --compact-output '.id,.location' +4435617 +"registry.gitlab.com/gitlab-de/playground/container-package-gen-group/docker-alpine-generator" + +glab api --method GET registry/repositories/4435617 --field='size=true' | jq --compact-output '.id,.location,.size' +4435617 +"registry.gitlab.com/gitlab-de/playground/container-package-gen-group/docker-alpine-generator" +3401613 + +glab api --method GET projects/$GL_PROJECT_ID/registry/repositories/4435617/tags | jq --compact-output '.[]' | jq --compact-output '.name' +"latest" + +glab api --method GET projects/$GL_PROJECT_ID/registry/repositories/4435617/tags/latest | jq --compact-output '.name,.created_at,.total_size' +"latest" +"2023-08-07T19:20:20.894+00:00" +3401613 +``` + +A similar automation shell script is created in the [delete old pipelines](#delete-old-pipelines) section. + +The `python-gitlab` API library provides bulk deletion interfaces explained in the next section. + +### Delete container images in bulk + +When you [delete container image tags in bulk](../api/container_registry.md#delete-registry-repository-tags-in-bulk), +you can configure: + +- The matching regular expressions for tag names and images to keep (`name_regex_keep`) or delete (`name_regex_delete`) +- The number of image tags to keep matching the tag name (`keep_n`) +- The number of days before an image tag can be deleted (`older_than`) + +WARNING: +On GitLab.com, due to the scale of the Container Registry, the number of tags deleted by this API is limited. +If your Container Registry has a large number of tags to delete, only some of them are deleted. You might need +to call the API multiple times. To schedule tags for automatic deletion, use a [cleanup policy](#cleanup-policy-for-containers) instead. + +The following example uses the [`python-gitlab` API library](https://python-gitlab.readthedocs.io/en/stable/gl_objects/repository_tags.html) to fetch a list of tags, and calls the `delete_in_bulk()` method with filter parameters. + +```python + repositories = project.repositories.list(iterator=True, size=True) + if len(repositories) > 0: + repository = repositories.pop() + tags = repository.tags.list() + + # Cleanup: Keep only the latest tag + repository.tags.delete_in_bulk(keep_n=1) + # Cleanup: Delete all tags older than 1 month + repository.tags.delete_in_bulk(older_than="1m") + # Cleanup: Delete all tags matching the regex `v.*`, and keep the latest 2 tags + repository.tags.delete_in_bulk(name_regex_delete="v.+", keep_n=2) +``` + +The full example of the script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` is located +in the [GitLab API with Python](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/) project. + +### Cleanup policy for containers + +Use the project REST API endpoint to [create cleanup policies](packages/container_registry/reduce_container_registry_storage.md#use-the-cleanup-policy-api). The following example uses the [GitLab CLI](../editor_extensions/gitlab_cli/index.md) to create a cleanup policy. + +To send the attributes as a body parameter, you must: + +- Use the `--input -` parameter to read from the standard input. +- Set the `Content-Type` header. + +```shell +export GL_PROJECT_ID=48057080 + +echo '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":".*","name_regex_keep":".*-main"}}' | glab api --method PUT --header 'Content-Type: application/json;charset=UTF-8' projects/$GL_PROJECT_ID --input - + +... + + "container_expiration_policy": { + "cadence": "1month", + "enabled": true, + "keep_n": 1, + "older_than": "14d", + "name_regex": ".*", + "name_regex_keep": ".*-main", + "next_run_at": "2023-09-08T21:16:25.354Z" + }, + +``` + +After you set up the cleanup policy, all container images that match your specifications are deleted automatically. You do not need additional API automation scripts. + +### Optimize container images + +You can optimize container images to reduce the image size and overall storage consumption in the container registry. Learn more in the [pipeline efficiency documentation](../ci/pipelines/pipeline_efficiency.md#optimize-docker-images). + +## Manage storage for Package Registry + +Package registries are available [in a project](../api/packages.md#within-a-project) or [in a group](../api/packages.md#within-a-group). + +### List packages and files + +The following example shows fetching packages from a defined project ID using the [GitLab CLI](../editor_extensions/gitlab_cli/index.md). The result set is an array of dictionary items that can be filtered with the `jq` command chain. + +```shell +# https://gitlab.com/gitlab-de/playground/container-package-gen-group/generic-package-generator +export GL_PROJECT_ID=48377643 + +glab api --method GET projects/$GL_PROJECT_ID/packages | jq --compact-output '.[]' | jq --compact-output '.id,.name,.package_type' +16669383 +"generator" +"generic" +16671352 +"generator" +"generic" +16672235 +"generator" +"generic" +16672237 +"generator" +"generic" +``` + +Use the package ID to inspect the files and their size in the package. + +```shell +glab api --method GET projects/$GL_PROJECT_ID/packages/16669383/package_files | jq --compact-output '.[]' | + jq --compact-output '.package_id,.file_name,.size' + +16669383 +"nighly.tar.gz" +10487563 +``` + +A similar automation shell script is created in the [delete old pipelines](#delete-old-pipelines) section. + +The following script example uses the `python-gitlab` library to fetch all packages in a loop, +and loops over its package files to print the `file_name` and `size` attributes. + +```python + packages = project.packages.list(order_by="created_at") + + for package in packages: + + package_files = package.package_files.list() + for package_file in package_files: + print("Package name: {p} File name: {f} Size {s}".format( + p=package.name, f=package_file.file_name, s=render_size_mb(package_file.size))) +``` + +### Delete packages + +[Deleting a file in a package](../api/packages.md#delete-a-package-file) can corrupt the package. You should delete the package when performing automated cleanup maintenance. + +To delete a package, use the [GitLab CLI](../editor_extensions/gitlab_cli/index.md) to change the `--method` +parameter to `DELETE`: + +```shell +glab api --method DELETE projects/$GL_PROJECT_ID/packages/16669383 +``` + +To calculate the package size and compare it against a size threshold, you can use the `python-gitlab` library +to extend the code described in the [list packages and files](#list-packages-and-files) section. + +The following code example also calculates the package age and deletes the package when the conditions match: + +```python + packages = project.packages.list(order_by="created_at") + for package in packages: + package_size = 0.0 + + package_files = package.package_files.list() + for package_file in package_files: + print("Package name: {p} File name: {f} Size {s}".format( + p=package.name, f=package_file.file_name, s=render_size_mb(package_file.size))) + + package_size =+ package_file.size + + print("Package size: {s}\n\n".format(s=render_size_mb(package_size))) + + threshold_size = 10 * 1024 * 1024 + + if (package_size > float(threshold_size)): + print("Package size {s} > threshold {t}, deleting package.".format( + s=render_size_mb(package_size), t=render_size_mb(threshold_size))) + package.delete() + + threshold_age = 90 * 24 * 60 * 60 + package_age = created_at = calculate_age(package.created_at) + + if (float(package_age > float(threshold_age))): + print("Package age {a} > threshold {t}, deleting package.".format( + a=render_age_time(package_age), t=render_age_time(threshold_age))) + package.delete() +``` + +The code generates the following output that you can use for further analysis: + +```shell +Package name: generator File name: nighly.tar.gz Size 10.0017 +Package size: 10.0017 +Package size 10.0017 > threshold 10.0000, deleting package. + +Package name: generator File name: 1-nightly.tar.gz Size 1.0004 +Package size: 1.0004 + +Package name: generator File name: 10-nightly.tar.gz Size 10.0018 +Package name: generator File name: 20-nightly.tar.gz Size 20.0033 +Package size: 20.0033 +Package size 20.0033 > threshold 10.0000, deleting package. +``` + +The full example of the script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` is located in the [GitLab API with Python](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/) project. + +### Dependency Proxy + +Review the [cleanup policy](packages/dependency_proxy/reduce_dependency_proxy_storage.md#cleanup-policies) and how to [purge the cache using the API](packages/dependency_proxy/reduce_dependency_proxy_storage.md#use-the-api-to-clear-the-cache) + +## Community resources + +These resources are not officially supported. Ensure to test scripts and tutorials before running destructive cleanup commands that may not be reverted. + +- Forum topic: [Storage management automation resources](https://forum.gitlab.com/t/storage-management-automation-resources/) +- Script: [GitLab Storage Analyzer](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-storage-analyzer), unofficial project by the [GitLab Developer Evangelism team](https://gitlab.com/gitlab-de/). You find similar code examples in this documentation how-to here. + +## Testing for storage management automation + +To test storage management automation, you might need to generate test data, or populate +storage to verify that the analysis and deletion works as expected. The following sections +provide tools and tips about testing and generating storage blobs in a short amount of time. + +### Generate job artifacts + +Create a test project to generate fake artifact blobs using CI/CD job matrix builds. Add a CI/CD pipeline to generate artifacts on a daily basis + +1. Create a new project. +1. Add the following snippet to `.gitlab-ci.yml` to include the job artifact generator configuration. + + ```yaml + include: + - remote: https://gitlab.com/gitlab-de/use-cases/efficiency/job-artifact-generator/-/raw/main/.gitlab-ci.yml + ``` + +1. [Configure pipeline schedules](../ci/pipelines/schedules.md#add-a-pipeline-schedule). +1. [Trigger the pipeline manually](../ci/pipelines/schedules.md#run-manually). + +Alternatively, reduce the 86 MB daily generated MB to different values in the `MB_COUNT` variable. + +```yaml +include: + - remote: https://gitlab.com/gitlab-de/use-cases/efficiency/job-artifact-generator/-/raw/main/.gitlab-ci.yml + +generator: + parallel: + matrix: + - MB_COUNT: [1, 5, 10, 20, 50] + +``` + +For more information, see the [Job Artifact Generator README](https://gitlab.com/gitlab-de/use-cases/efficiency/job-artifact-generator), with an [example group](https://gitlab.com/gitlab-de/playground/artifact-gen-group). + +### Generate job artifacts with expiry + +The project CI/CD configuration specifies job definitions in: + +- The main `.gitlab-ci.yml` configuration file. +- The `artifacts:expire_in` setting. +- Project files and templates. + +To test the analysis scripts, the [`gen-job-artifacts-expiry-included-jobs`](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-expiry-included-jobs) project provides an example configuration. + +```yaml +# .gitlab-ci.yml +include: + - include_jobs.yml + +default: + artifacts: + paths: + - '*.txt' + +.gen-tmpl: + script: + - dd if=/dev/urandom of=${$MB_COUNT}.txt bs=1048576 count=${$MB_COUNT} + +generator: + extends: [.gen-tmpl] + parallel: + matrix: + - MB_COUNT: [1, 5, 10, 20, 50] + artifacts: + untracked: false + when: on_success + expire_in: 30 days + +# include_jobs.yml +.includeme: + script: + - dd if=/dev/urandom of=1.txt bs=1048576 count=1 + +included-job10: + script: + - echo "Servus" + - !reference [.includeme, script] + artifacts: + untracked: false + when: on_success + expire_in: 10 days + +included-job1: + script: + - echo "Gruezi" + - !reference [.includeme, script] + artifacts: + untracked: false + when: on_success + expire_in: 1 days + +included-job30: + script: + - echo "Grias di" + - !reference [.includeme, script] + artifacts: + untracked: false + when: on_success + expire_in: 30 days +``` + +### Generate container images + +The example group [`container-package-gen-group`](https://gitlab.com/gitlab-de/playground/container-package-gen-group) provides projects that: + +- Use a base image in Dockerfile to build a new image. +- Include the `Docker.gitlab-ci.yml` template to build images on GitLab.com SaaS. +- Configure pipeline schedules to generate new images daily. + +Example projects available to fork: + +- [`docker-alpine-generator`](https://gitlab.com/gitlab-de/playground/container-package-gen-group/docker-alpine-generator) +- [`docker-python-generator`](https://gitlab.com/gitlab-de/playground/container-package-gen-group/docker-python-generator) + +### Generate generic packages + +The example project [`generic-package-generator`](https://gitlab.com/gitlab-de/playground/container-package-gen-group/generic-package-generator) provides projects that: + +- Generate a random text blob, and create a tarball with the current Unix timestamp as release version. +- Upload the tarball into the generic package registry, using the Unix timestamp as release version. + +To generate generic packages, you can use this standalone `.gitlab-ci.yml` configuration: + +```yaml +generate-package: + parallel: + matrix: + - MB_COUNT: [1, 5, 10, 20] + before_script: + - apt update && apt -y install curl + script: + - dd if=/dev/urandom of="${MB_COUNT}.txt" bs=1048576 count=${MB_COUNT} + - tar czf "generated-$MB_COUNT-nighly-`date +%s`.tar.gz" "${MB_COUNT}.txt" + - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file "generated-$MB_COUNT-nighly-`date +%s`.tar.gz" "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/generator/`date +%s`/${MB_COUNT}-nightly.tar.gz"' + + artifacts: + paths: + - '*.tar.gz' + +``` + +### Generate storage usage with forks + +Use the following projects to test storage usage with [cost factors for forks](usage_quotas.md#view-project-fork-storage-usage): + +- Fork [`gitlab-org/gitlab`](https://gitlab.com/gitlab-org/gitlab) into a new namespace or group (includes LFS, Git repository). +- Fork [`gitlab-com/www-gitlab-com`](https://gitlab.com/gitlab-com/www-gitlab-comgitlab-com/www-gitlab-com) into a new namespace or group. diff --git a/doc/user/tasks.md b/doc/user/tasks.md index ecd5ef0c42f..c340bb736ef 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.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/product/ux/technical-writing/#assignments --- -# Tasks **(FREE)** +# Tasks **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `work_items`. Disabled by default. > - [Creating, editing, and deleting tasks](https://gitlab.com/groups/gitlab-org/-/epics/7169) introduced in GitLab 15.0. @@ -269,7 +269,7 @@ To add a task to a milestone: If a task already belongs to a milestone, the dropdown list shows the current milestone. 1. From the dropdown list, select the milestone to be associated with the task. -## Set task weight **(PREMIUM)** +## Set task weight **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362550) in GitLab 15.3. @@ -287,7 +287,7 @@ To set issue weight of a task: 1. Next to **Weight**, enter a whole, positive number. 1. Select the close icon (**{close}**). -## Add a task to an iteration **(PREMIUM)** +## Add a task to an iteration **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367456) in GitLab 15.5 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/367456) to feature flag named `work_items_mvc` in GitLab 15.7. Disabled by default. @@ -360,6 +360,75 @@ To copy the task's email address: 1. Select **Plan > Issues**, then select your issue to view it. 1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy task email address**. +## Confidential tasks + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8410) in GitLab 15.3. + +Confidential tasks are tasks visible only to members of a project with +[sufficient permissions](#who-can-see-confidential-tasks). +You can use confidential tasks to keep security vulnerabilities private or prevent surprises from +leaking out. + +### Make a task confidential + +By default, tasks are public. +You can make a task confidential when you create or edit it. + +Prerequisites: + +- You must have at least the Reporter role for the project. +- If the task has a parent issue which is non-confidential, and you want to make the issue confidential, + you must first make all the child tasks confidential. + A [confidential issue](project/issues/confidential_issues.md) can have only confidential children. + +#### In a new task + +When you create a new task, a checkbox right below the text area is available to mark the +task as confidential. + +Check that box and select **Create task**. + +#### In an existing task + +To change the confidentiality of an existing task: + +1. [Open the task](#view-tasks). +1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **Turn on confidentiality**. + +### Who can see confidential tasks + +When a task is made confidential, only users with at least the Reporter role for the project have +access to the task. +Users with Guest or [Minimal](permissions.md#users-with-minimal-access) roles can't access +the task even if they were actively participating before the change. + +However, a user with the **Guest role** can create confidential tasks, but can only view the ones +that they created themselves. + +Users with the Guest role or non-members can read the confidential task if they are assigned to the task. +When a Guest user or non-member is unassigned from a confidential task, they can no longer view it. + +Confidential tasks are hidden in search results for users without the necessary permissions. + +### Confidential task indicators + +Confidential tasks are visually different from regular tasks in a few ways. +Wherever tasks are listed, you can see the confidential (**{eye-slash}**) icon +next to the tasks that are marked as confidential. + +If you don't have [enough permissions](#who-can-see-confidential-tasks), +you cannot see confidential tasks at all. + +Likewise, while inside the task, you can see the confidential (**{eye-slash}**) icon right next to +the breadcrumbs. + +Every change from regular to confidential and vice versa, is indicated by a +system note in the task's comments, for example: + +> - **{eye-slash}** Jo Garcia made the issue confidential 5 minutes ago +> - **{eye}** Jo Garcia made the issue visible to everyone just now + ## Two-column layout > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415077) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. diff --git a/doc/user/todos.md b/doc/user/todos.md index 97f67c67671..eedd5d8a510 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.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/product/ux/technical-writing/#assignments --- -# To-Do List **(FREE)** +# To-Do List **(FREE ALL)** Your *To-Do List* is a chronological list of items waiting for your input. The items are known as *to-do items*. diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index d119044930a..ade99a5fef8 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -5,7 +5,7 @@ group: Utilization 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 --- -# Storage usage quota **(FREE)** +# Storage usage quota **(FREE ALL)** Storage usage statistics are available for projects and namespaces. You can use that information to manage storage usage within the applicable quotas. @@ -112,6 +112,10 @@ Depending on your role, you can also use the following methods to manage or redu - [Reduce repository size](project/repository/reducing_the_repo_size_using_git.md). - [Reduce container registry storage](packages/container_registry/reduce_container_registry_storage.md). - [Reduce wiki repository size](../administration/wikis/index.md#reduce-wiki-repository-size). +- [Manage artifact expiration period](../ci/yaml/index.md#artifactsexpire_in). +- [Reduce build artifact storage](../ci/jobs/job_artifacts.md#delete-job-log-and-artifacts). + +To automate storage usage analysis and management, see the [storage management automation](storage_management_automation.md) documentation. ## Manage your transfer usage @@ -161,7 +165,7 @@ example, no additional storage has yet been purchased. To remove the read-only state from the Red and Green projects, 50 GB additional storage is purchased. Assuming the Green and Red projects' repositories and LFS grow past the 10 GB quota, the purchased storage -available decreases. All projects remain read-only because 40 GB purchased storage is available: +available decreases. All projects no longer have the read-only status because 40 GB purchased storage is available: 50 GB (purchased storage) - 10 GB (total excess storage used). | Repository | Storage used | Excess storage | Quota | Status | @@ -205,6 +209,20 @@ To prevent exceeding the namespace storage quota, you can: - [Start a trial](https://about.gitlab.com/free-trial/) or [upgrade to GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) which include higher limits and features that enable growing teams to ship faster without sacrificing on quality. - [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) for more information about your options. +### View project fork storage usage + +A cost factor is applied to the storage consumed by project forks so that forks consume less namespace storage than their actual size. + +To view the amount of namespace storage the fork has used: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Settings > Usage Quotas**. +1. Select the **Storage** tab. The **Total** column displays the amount of namespace storage used by the fork as a portion of the actual size of the fork on disk. + +The cost factor applies to the project repository, LFS objects, job artifacts, packages, snippets, and the wiki. + +The cost factor does not apply to private forks in namespaces on the Free plan. + ### Namespace storage limit application schedule Information on when namespace-level storage limits are applied is available on these FAQ pages for the [Free](https://about.gitlab.com/pricing/faq-efficient-free-tier/#storage-limits-on-gitlab-saas-free-tier) and [Paid](https://about.gitlab.com/pricing/faq-paid-storage-transfer/) tier. diff --git a/doc/user/version.md b/doc/user/version.md new file mode 100644 index 00000000000..b7846988e06 --- /dev/null +++ b/doc/user/version.md @@ -0,0 +1,23 @@ +--- +stage: none +group: none +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 +--- + +# Find the GitLab version + +Find the version of GitLab you're running. + +## For self-managed GitLab + +- On the left sidebar, at the bottom, select **Help**. + +The version is displayed at the top of the dialog. + +## For GitLab.com + +- Go to <https://gitlab.com/help>. + +The version is displayed at the top of the page. For example, +`GitLab Enterprise Edition 16.3.0-pre 1e04d6b7fa9` indicates a pre-release +version of GitLab 16.3. diff --git a/doc/user/workspace/configuration.md b/doc/user/workspace/configuration.md new file mode 100644 index 00000000000..3900c95e41a --- /dev/null +++ b/doc/user/workspace/configuration.md @@ -0,0 +1,207 @@ +--- +stage: Create +group: IDE +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 +--- + +# Workspace configuration (Beta) **(PREMIUM ALL)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. + +FLAG: +On self-managed GitLab, by default this feature is available. +To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. +On GitLab.com, this feature is available. +The feature is not ready for production use. + +WARNING: +This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. +To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). + +You can use [workspaces](index.md) to create and manage isolated development environments for your GitLab projects. +Each workspace includes its own set of dependencies, libraries, and tools, +which you can customize to meet the specific needs of each project. + +## Set up a workspace + +### Prerequisites + +- Set up a Kubernetes cluster that the GitLab agent for Kubernetes supports. + See the [supported Kubernetes versions](../clusters/agent/index.md#supported-kubernetes-versions-for-gitlab-features). +- Ensure autoscaling for the Kubernetes cluster is enabled. +- In the Kubernetes cluster, verify that a [default storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) + is defined so that volumes can be dynamically provisioned for each workspace. +- In the Kubernetes cluster, install an Ingress controller of your choice (for example, `ingress-nginx`) + and make that controller accessible over a domain. For example, point `*.workspaces.example.dev` and + `workspaces.example.dev` to the load balancer exposed by the Ingress controller. +- In the Kubernetes cluster, [install `gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy#installation-instructions). +- In the Kubernetes cluster, [install the GitLab agent for Kubernetes](../clusters/agent/install/index.md). +- Configure remote development settings for the GitLab agent with this snippet and update `dns_zone` as needed: + + ```yaml + remote_development: + enabled: true + dns_zone: "workspaces.example.dev" + ``` + + You can use any agent defined under the root group of your project, + provided that remote development is properly configured for that agent. +- You must have at least the Developer role in the root group. +- In each public project you want to use this feature for, create a [devfile](index.md#devfile): + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. In the root directory of your project, create a file named `.devfile.yaml`. + You can use one of the [example configurations](index.md#example-configurations). +- Ensure the container images used in the devfile support [arbitrary user IDs](index.md#arbitrary-user-ids). + +### Create a workspace + +To create a workspace: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Your work**. +1. Select **Workspaces**. +1. Select **New workspace**. +1. From the **Select project** dropdown list, [select a project with a `.devfile.yaml` file](#prerequisites). + You can only create workspaces for public projects. +1. From the **Select cluster agent** dropdown list, select a cluster agent owned by the group the project belongs to. +1. In **Time before automatic termination**, enter the number of hours until the workspace automatically terminates. + This timeout is a safety measure to prevent a workspace from consuming excessive resources or running indefinitely. +1. Select **Create workspace**. + +The workspace might take a few minutes to start. +To open the workspace, under **Preview**, select the workspace. +You also have access to the terminal and can install any necessary dependencies. + +## Connect to a workspace with SSH + +Prerequisites: + +- SSH must be enabled for the workspace. +- You must have a TCP load balancer that points to [`gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy). + +To connect to a workspace with an SSH client: + +1. Run this command: + + ```shell + ssh <workspace_name>@<ssh_proxy> + ``` + +1. For the password, enter your personal access token with at least the `read_api` scope. + +When you connect to `gitlab-workspaces-proxy` through the TCP load balancer, +`gitlab-workspaces-proxy` examines the username (workspace name) and interacts with GitLab to verify: + +- The personal access token +- User access to the workspace + +### Set up `gitlab-workspaces-proxy` for SSH connections + +Prerequisite: + +- You must have an SSH host key for client verification. + +SSH is now enabled by default in [`gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy). +To set up `gitlab-workspaces-proxy` with the GitLab Helm chart: + +1. Run this command: + + ```shell + ssh-keygen -f ssh-host-key -N '' -t rsa + export SSH_HOST_KEY=$(pwd)/ssh-host-key + ``` + +1. Install `gitlab-workspaces-proxy` with the generated SSH host key: + + ```shell + helm upgrade --install gitlab-workspaces-proxy \ + gitlab-workspaces-proxy/gitlab-workspaces-proxy \ + --version 0.1.8 \ + --namespace=gitlab-workspaces \ + --create-namespace \ + --set="auth.client_id=${CLIENT_ID}" \ + --set="auth.client_secret=${CLIENT_SECRET}" \ + --set="auth.host=${GITLAB_URL}" \ + --set="auth.redirect_uri=${REDIRECT_URI}" \ + --set="auth.signing_key=${SIGNING_KEY}" \ + --set="ingress.host.workspaceDomain=${GITLAB_WORKSPACES_PROXY_DOMAIN}" \ + --set="ingress.host.wildcardDomain=${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \ + --set="ingress.tls.workspaceDomainCert=$(cat ${WORKSPACES_DOMAIN_CERT})" \ + --set="ingress.tls.workspaceDomainKey=$(cat ${WORKSPACES_DOMAIN_KEY})" \ + --set="ingress.tls.wildcardDomainCert=$(cat ${WILDCARD_DOMAIN_CERT})" \ + --set="ingress.tls.wildcardDomainKey=$(cat ${WILDCARD_DOMAIN_KEY})" \ + --set="ssh.host_key=$(cat ${SSH_HOST_KEY})" \ + --set="ingress.className=nginx" + ``` + +### Update your runtime images + +To update your runtime images for SSH connections: + +1. Install [`sshd`](https://man.openbsd.org/sshd.8) in your runtime images. +1. Create a user named `gitlab-workspaces` to allow access to your container without a password. + +```Dockerfile +FROM golang:1.20.5-bullseye + +# Install `openssh-server` and other dependencies +RUN apt update \ + && apt upgrade -y \ + && apt install openssh-server sudo curl git wget software-properties-common apt-transport-https --yes \ + && rm -rf /var/lib/apt/lists/* + +# Permit empty passwords +RUN sed -i 's/nullok_secure/nullok/' /etc/pam.d/common-auth +RUN echo "PermitEmptyPasswords yes" >> /etc/ssh/sshd_config + +# Generate a workspace host key +RUN ssh-keygen -A +RUN chmod 775 /etc/ssh/ssh_host_rsa_key && \ + chmod 775 /etc/ssh/ssh_host_ecdsa_key && \ + chmod 775 /etc/ssh/ssh_host_ed25519_key + +# Create a `gitlab-workspaces` user +RUN useradd -l -u 5001 -G sudo -md /home/gitlab-workspaces -s /bin/bash gitlab-workspaces +RUN passwd -d gitlab-workspaces +ENV HOME=/home/gitlab-workspaces +WORKDIR $HOME +RUN mkdir -p /home/gitlab-workspaces && chgrp -R 0 /home && chmod -R g=u /etc/passwd /etc/group /home + +# Allow sign-in access to `/etc/shadow` +RUN chmod 775 /etc/shadow + +USER gitlab-workspaces +``` + +## Disable remote development in the GitLab agent for Kubernetes + +You can stop the `remote_development` module of the GitLab agent for Kubernetes from communicating with GitLab. +To disable remote development in the GitLab agent configuration, set this property: + +```yaml +remote_development: + enabled: false +``` + +If you already have running workspaces, an administrator must manually delete these workspaces in Kubernetes. + +## Related topics + +- [Quickstart guide for GitLab remote development workspaces](https://go.gitlab.com/AVKFvy) +- [Set up your infrastructure for on-demand, cloud-based development environments in GitLab](https://go.gitlab.com/dp75xo) + +## Troubleshooting + +### `Failed to renew lease` when creating a workspace + +You might not be able to create a workspace due to a known issue in the GitLab agent for Kubernetes. +The following error message might appear in the agent's log: + +```plaintext +{"level":"info","time":"2023-01-01T00:00:00.000Z","msg":"failed to renew lease gitlab-agent-remote-dev-dev/agent-123XX-lock: timed out waiting for the condition\n","agent_id":XXXX} +``` + +This issue occurs when an agent instance cannot renew its leadership lease, which results +in the shutdown of leader-only modules including the `remote_development` module. +To resolve this issue, restart the agent instance. diff --git a/doc/user/workspace/create_image.md b/doc/user/workspace/create_image.md new file mode 100644 index 00000000000..43140a622e0 --- /dev/null +++ b/doc/user/workspace/create_image.md @@ -0,0 +1,119 @@ +--- +stage: Create +group: IDE +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 +--- + +# Tutorial: Create a custom workspace image that supports arbitrary user IDs (Beta) **(PREMIUM ALL)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. On GitLab.com, this feature is available. The feature is not ready for production use. + +WARNING: +This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). + +In this tutorial, you'll learn how to create a custom workspace image that supports arbitrary user IDs. +You can then use this custom image with any [workspace](index.md) you create in GitLab. + +To create a custom workspace image that supports arbitrary user IDs, you'll: + +1. [Create a base Dockerfile](#create-a-base-dockerfile). +1. [Add support for arbitrary user IDs](#add-support-for-arbitrary-user-ids). +1. [Build the custom workspace image](#build-the-custom-workspace-image). +1. [Push the custom workspace image to the GitLab Container Registry](#push-the-custom-workspace-image-to-the-gitlab-container-registry). +1. [Use the custom workspace image in GitLab](#use-the-custom-workspace-image-in-gitlab). + +## Prerequisites + +- A GitLab account with permission to create and push container images to the GitLab Container Registry +- Docker installation + +## Create a base Dockerfile + +To create a base Dockerfile for the container image, let's use the Python `3.11-slim-bullseye` image from Docker Hub: + +```Dockerfile +FROM python:3.11-slim-bullseye +``` + +Next, you'll modify this base image. + +## Add support for arbitrary user IDs + +To add support for arbitrary user IDs to the base image, let's: + +1. Add a new `gitlab-workspaces` user with a `5001` user ID. +1. Set the necessary directory permissions. + +```Dockerfile +RUN useradd -l -u 5001 -G sudo -md /home/gitlab-workspaces -s /bin/bash -p gitlab-workspaces gitlab-workspaces + +ENV HOME=/home/gitlab-workspaces + +WORKDIR $HOME + +RUN mkdir -p /home/gitlab-workspaces && chgrp -R 0 /home && chmod -R g=u /etc/passwd /etc/group /home + +USER 5001 +``` + +Now that the image supports arbitrary user IDs, it's time to build the custom workspace image. + +## Build the custom workspace image + +To build the custom workspace image, run this command: + +```shell +docker build -t my-gitlab-workspace . +``` + +When the build is complete, you can test the image locally: + +```shell +docker run -ti my-gitlab-workspace sh +``` + +You should now be able to run commands as the `gitlab-workspaces` user. + +## Push the custom workspace image to the GitLab Container Registry + +To push the custom workspace image to the GitLab Container Registry: + +1. Sign in to your GitLab account: + + ```shell + docker login registry.gitlab.com + ``` + +1. Tag the image with the GitLab Container Registry URL: + + ```shell + docker tag my-gitlab-workspace registry.gitlab.com/your-namespace/my-gitlab-workspace:latest + ``` + +1. Push the image to the GitLab Container Registry: + + ```shell + docker push registry.gitlab.com/your-namespace/my-gitlab-workspace:latest + ``` + +Now that you've pushed the custom workspace image to the GitLab Container Registry, you can use the image in GitLab. + +## Use the custom workspace image in GitLab + +To use the custom workspace image in GitLab, in your project's `.devfile.yaml`, update the container image: + +```yaml +schemaVersion: 2.2.0 +components: + - name: tooling-container + attributes: + gl/inject-editor: true + container: + image: registry.gitlab.com/your-namespace/my-gitlab-workspace:latest +``` + +You're all set! You can now use this custom image with any [workspace](index.md) you create in GitLab. diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index a101e5f5f8c..51e3e905a92 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -4,82 +4,76 @@ group: IDE 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 --- -# Workspaces (Beta) **(PREMIUM)** +# Workspaces (Beta) **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. On GitLab.com, this feature is available. The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. +To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. +On GitLab.com, this feature is available. +The feature is not ready for production use. WARNING: -This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). +This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. +To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). -A workspace is a virtual sandbox environment for your code in GitLab. You can use workspaces to create and manage isolated development environments for your GitLab projects. These environments ensure that different projects don't interfere with each other. +A workspace is a virtual sandbox environment for your code in GitLab. +You can use workspaces to create and manage isolated development environments for your GitLab projects. +These environments ensure that different projects don't interfere with each other. -Each workspace includes its own set of dependencies, libraries, and tools, which you can customize to meet the specific needs of each project. Workspaces use the AMD64 architecture. +Each workspace includes its own set of dependencies, libraries, and tools, +which you can customize to meet the specific needs of each project. +Workspaces use the AMD64 architecture. -For a demo of this feature, see [GitLab Workspaces Demo](https://go.gitlab.com/qtu66q). +## Workspaces and projects -## Set up a workspace +Workspaces are scoped to a project. +When you [create a workspace](configuration.md#set-up-a-workspace), you must: -### Prerequisites +- Assign the workspace to a specific project. +- Select a project with a [`.devfile.yaml`](#devfile) file. -- Set up a Kubernetes cluster that the GitLab agent for Kubernetes supports. See the [supported Kubernetes versions](../clusters/agent/index.md#supported-kubernetes-versions-for-gitlab-features). -- Ensure autoscaling for the Kubernetes cluster is enabled. -- In the Kubernetes cluster, verify that a [default storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) is defined so that volumes can be dynamically provisioned for each workspace. -- In the Kubernetes cluster, install an Ingress controller of your choice (for example, `ingress-nginx`), and make that controller accessible over a domain. For example, point `*.workspaces.example.dev` and `workspaces.example.dev` to the load balancer exposed by the Ingress controller. -- In the Kubernetes cluster, [install `gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy#installation-instructions). -- In the Kubernetes cluster, [install the GitLab agent for Kubernetes](../clusters/agent/install/index.md). -- Configure remote development settings for the GitLab agent with this snippet, and update `dns_zone` as needed: +The workspace can then interact with the GitLab API based on the permissions granted to the current user. - ```yaml - remote_development: - enabled: true - dns_zone: "workspaces.example.dev" - ``` +### Open and manage workspaces from a project - You can use any agent defined under the root group of your project, provided that remote development is properly configured for that agent. -- You must have at least the Developer role in the root group. -- In each public project you want to use this feature for, create a [devfile](#devfile): - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project - 1. In the root directory of your project, create a file named `.devfile.yaml`. You can use one of the [example configurations](#example-configurations). -- Ensure the container images used in the devfile support [arbitrary user IDs](#arbitrary-user-ids). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125331) in GitLab 16.2. -### Create a workspace +To open a workspace from a file or the repository file list: -To create a workspace: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. In the upper right, select **Edit**. +1. From the dropdown list, under **Your workspaces**, select the workspace. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Your work**. -1. Select **Workspaces**. -1. Select **New workspace**. -1. From the **Select project** dropdown list, [select a project with a `.devfile.yaml` file](#prerequisites). You can only create workspaces for public projects. -1. From the **Select cluster agent** dropdown list, select a cluster agent owned by the group the project belongs to. -1. In **Time before automatic termination**, enter the number of hours until the workspace automatically terminates. This timeout is a safety measure to prevent a workspace from consuming excessive resources or running indefinitely. -1. Select **Create workspace**. +From the dropdown list, you can also: -The workspace might take a few minutes to start. To access the workspace, under **Preview**, select the workspace link. -You also have access to the terminal and can install any necessary dependencies. +- Restart, stop, or terminate an existing workspace. +- Create a new workspace. -## Deleting data associated with a workspace +### Deleting data associated with a workspace When you delete a project, agent, user, or token associated with a workspace: - The workspace is deleted from the user interface. -- In the Kubernetes cluster, the running workspace resources become orphaned. +- In the Kubernetes cluster, the running workspace resources become orphaned and are not automatically deleted. To clean up orphaned resources, an administrator must manually delete the workspace in Kubernetes. -For more information about our plans to change the current behavior, see [issue 414384](https://gitlab.com/gitlab-org/gitlab/-/issues/414384). +[Issue 414384](https://gitlab.com/gitlab-org/gitlab/-/issues/414384) proposes to change this behavior. ## Devfile -A devfile is a file that defines a development environment by specifying the necessary tools, languages, runtimes, and other components for a GitLab project. +A devfile is a file that defines a development environment by specifying the necessary +tools, languages, runtimes, and other components for a GitLab project. -Workspaces have built-in support for devfiles. You can specify a devfile for your project in the GitLab configuration file. The devfile is used to automatically configure the development environment with the defined specifications. +Workspaces have built-in support for devfiles. +You can specify a devfile for your project in the GitLab configuration file. +The devfile is used to automatically configure the development environment with the defined specifications. -This way, you can create consistent and reproducible development environments regardless of the machine or platform you use. +This way, you can create consistent and reproducible development environments +regardless of the machine or platform you use. ### Relevant schema properties @@ -123,66 +117,63 @@ components: For more information, see the [devfile documentation](https://devfile.io/docs/2.2.0/devfile-schema). For other examples, see the [`examples` projects](https://gitlab.com/gitlab-org/remote-development/examples). -This container image is for demonstration purposes only. To use your own container image, see [Arbitrary user IDs](#arbitrary-user-ids). +This container image is for demonstration purposes only. +To use your own container image, see [Arbitrary user IDs](#arbitrary-user-ids). ## Web IDE -Workspaces are bundled with the Web IDE by default. The Web IDE is the only code editor available for workspaces. +Workspaces are bundled with the Web IDE by default. +The Web IDE is the only code editor available for workspaces. -The Web IDE is powered by the [GitLab VS Code fork](https://gitlab.com/gitlab-org/gitlab-web-ide-vscode-fork). For more information, see [Web IDE](../project/web_ide/index.md). +The Web IDE is powered by the [GitLab VS Code fork](https://gitlab.com/gitlab-org/gitlab-web-ide-vscode-fork). +For more information, see [Web IDE](../project/web_ide/index.md). ## Private repositories -You cannot create a workspace for a private repository because GitLab does not inject any credentials into the workspace. You can only create a workspace for public repositories that have a devfile. +You cannot [create a workspace](configuration.md#set-up-a-workspace) for a private repository +because GitLab does not inject any credentials into the workspace. +You can only create a workspace for public repositories that have a devfile. From a workspace, you can clone any repository manually. ## Pod interaction in a cluster -Workspaces run as pods in a Kubernetes cluster. GitLab does not impose any restrictions on the manner in which pods interact with each other. +Workspaces run as pods in a Kubernetes cluster. +GitLab does not impose any restrictions on the manner in which pods interact with each other. Because of this requirement, you might want to isolate this feature from other containers in your cluster. ## Network access and workspace authorization -It's the client's responsibility to restrict network access to the Kubernetes control plane as GitLab does not have control over the API. +It's the client's responsibility to restrict network access to the Kubernetes control plane +because GitLab does not have control over the API. -Only the workspace creator can access the workspace and any endpoints exposed in that workspace. The workspace creator is only authorized to access the workspace after user authentication with OAuth. +Only the workspace creator can access the workspace and any endpoints exposed in that workspace. +The workspace creator is only authorized to access the workspace after user authentication with OAuth. ## Compute resources and volume storage -When you stop a workspace, the compute resources for that workspace are scaled down to zero. However, the volume provisioned for the workspace still exists. +When you stop a workspace, the compute resources for that workspace are scaled down to zero. +However, the volume provisioned for the workspace still exists. To delete the provisioned volume, you must terminate the workspace. -## Disable remote development in the GitLab agent for Kubernetes - -You can stop the `remote_development` module of the GitLab agent for Kubernetes from communicating with GitLab. To disable remote development in the GitLab agent configuration, set this property: - -```yaml -remote_development: - enabled: false -``` - -If you already have running workspaces, an administrator must manually delete these workspaces in Kubernetes. - ## Arbitrary user IDs -You can provide your own container image, which can run as any Linux user ID. It's not possible for GitLab to predict the Linux user ID for a container image. -GitLab uses the Linux root group ID permission to create, update, or delete files in a container. The container runtime used by the Kubernetes cluster must ensure all containers have a default Linux group ID of `0`. - -If you have a container image that does not support arbitrary user IDs, you cannot create, update, or delete files in a workspace. To create a container image that supports arbitrary user IDs, see the [OpenShift documentation](https://docs.openshift.com/container-platform/4.12/openshift_images/create-images.html#use-uid_create-images). +You can provide your own container image, which can run as any Linux user ID. -## Troubleshooting +It's not possible for GitLab to predict the Linux user ID for a container image. +GitLab uses the Linux root group ID permission to create, update, or delete files in a container. +The container runtime used by the Kubernetes cluster must ensure all containers have a default Linux group ID of `0`. -When working with workspaces, you might encounter the following issues. +If you have a container image that does not support arbitrary user IDs, +you cannot create, update, or delete files in a workspace. +To create a container image that supports arbitrary user IDs, +see [Create a custom workspace image that supports arbitrary user IDs](../workspace/create_image.md). -### `Failed to renew lease` when creating a workspace +For more information, see the +[OpenShift documentation](https://docs.openshift.com/container-platform/4.12/openshift_images/create-images.html#use-uid_create-images). -You might not be able to create a workspace due to a known issue in the GitLab agent for Kubernetes. The following error message might appear in the agent's log: - -```plaintext -{"level":"info","time":"2023-01-01T00:00:00.000Z","msg":"failed to renew lease gitlab-agent-remote-dev-dev/agent-123XX-lock: timed out waiting for the condition\n","agent_id":XXXX} -``` +## Related topics -This issue occurs when an agent instance cannot renew its leadership lease, which results in the shutdown of leader-only modules including the `remote_development` module. To resolve this issue, restart the agent instance. +- [GitLab workspaces demo](https://go.gitlab.com/qtu66q) |
