diff options
Diffstat (limited to 'doc')
1011 files changed, 28536 insertions, 10016 deletions
diff --git a/doc/.vale/gitlab/Acronyms.yml b/doc/.vale/gitlab/Acronyms.yml index 53690138300..494b1e42d2f 100644 --- a/doc/.vale/gitlab/Acronyms.yml +++ b/doc/.vale/gitlab/Acronyms.yml @@ -16,18 +16,24 @@ second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' exceptions: - ANSI - API + - ARM - ARN - ASCII - AWS + - BSD - CLI - CNAME - CORE - CPU - CSS - CSV + - DAG - DAST + - DHCP - DNS + - DVCS - EKS + - EOL - FAQ - FOSS - GCP @@ -41,6 +47,7 @@ exceptions: - HTTP - HTTPS - IAM + - IANA - IBM - IDE - IID @@ -48,13 +55,17 @@ exceptions: - IRC - ISO - JSON + - LAN - LDAP - LDAPS - LESS - LFS - LRU + - LTS - MIME + - MIT - MVC + - NAT - NFS - NGINX - NOTE @@ -67,7 +78,9 @@ exceptions: - PUT - RAM - REST + - RHEL - RPC + - RPM - RSA - RSS - RVM @@ -81,6 +94,7 @@ exceptions: - SLA - SMTP - SQL + - SSD - SSH - SSL - SSO @@ -88,6 +102,7 @@ exceptions: - SVN - TCP - TIP + - TLD - TLS - TODO - TOML @@ -95,6 +110,7 @@ exceptions: - URI - URL - USB + - UTC - UUID - VPC - WIP diff --git a/doc/.vale/gitlab/Admin.yml b/doc/.vale/gitlab/Admin.yml index 27a703c30c3..6d01882138a 100644 --- a/doc/.vale/gitlab/Admin.yml +++ b/doc/.vale/gitlab/Admin.yml @@ -10,4 +10,4 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide.html level: warning ignorecase: true swap: - 'admin ?\w*': '(?:Admin Area|[Aa]dminist(ration|rator|er))' + 'admin ?\w*': '(?:Admin Area|[Aa]dminist(ration|rator|er|rative))' diff --git a/doc/.vale/gitlab/AlertBoxCaution.yml b/doc/.vale/gitlab/AlertBoxCaution.yml new file mode 100644 index 00000000000..49d4dc62ab5 --- /dev/null +++ b/doc/.vale/gitlab/AlertBoxCaution.yml @@ -0,0 +1,14 @@ +--- +# Error: gitlab.AlertBoxCaution +# +# Makes sure CAUTION: alert boxes follow standard formatting. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: "CAUTION: alert boxes must be of the format 'CAUTION: **Caution:**'. 'Caution' can be replaced with 'Warning' or 'Important'." +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#alert-boxes +level: warning +nonword: true +scope: raw +swap: + 'CAUTION: *?\*\*.*\*\*': 'CAUTION: \*\*(?:Caution|Warning|Important):\*\*' diff --git a/doc/.vale/gitlab/AlertBoxDanger.yml b/doc/.vale/gitlab/AlertBoxDanger.yml new file mode 100644 index 00000000000..2589d34614c --- /dev/null +++ b/doc/.vale/gitlab/AlertBoxDanger.yml @@ -0,0 +1,14 @@ +--- +# Error: gitlab.AlertBoxDanger +# +# Makes sure DANGER: alert boxes follow standard formatting. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: "DANGER: alert boxes must be of the format 'DANGER: **Warning:**'. 'Warning' can be replaced with 'Important', 'Deprecated', or 'Required'." +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#alert-boxes +level: error +nonword: true +scope: raw +swap: + 'DANGER: *?\*\*.*\*\*': 'DANGER: \*\*(?:Warning|Important|Deprecated|Required):\*\*' diff --git a/doc/.vale/gitlab/AlertBoxNoteTip.yml b/doc/.vale/gitlab/AlertBoxNoteTip.yml new file mode 100644 index 00000000000..0b480794476 --- /dev/null +++ b/doc/.vale/gitlab/AlertBoxNoteTip.yml @@ -0,0 +1,15 @@ +--- +# Error: gitlab.AlertBoxNoteTip +# +# Makes sure NOTE: and TIP: alert boxes follow standard formatting. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: "NOTE: and TIP: alert boxes must be of the format 'NOTE: **Note:**' or 'TIP: **Tip:**" +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#alert-boxes +level: warning +nonword: true +scope: raw +swap: + 'NOTE: *?\*\*.*\*\*': 'NOTE: \*\*Note:\*\*' + 'TIP: *?\*\*.*\*\*': 'TIP: \*\*Tip:\*\*' diff --git a/doc/.vale/gitlab/AlertBoxStyle.yml b/doc/.vale/gitlab/AlertBoxStyle.yml index 06743d95ea9..d15757d38fc 100644 --- a/doc/.vale/gitlab/AlertBoxStyle.yml +++ b/doc/.vale/gitlab/AlertBoxStyle.yml @@ -3,9 +3,7 @@ # # Makes sure alert boxes follow standard formatting. # -# Checks for 4 known issues: -# - Alert boxes with no colon, or colon outside the bold text -# - Known incorrect capitalization of the most commonly used alert box text +# Checks for 2 formatting issues: # - Alert boxes with the note text on the same line # - Alert boxes using blockquote formatting, like "> **Note:**" # @@ -16,7 +14,5 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#alert level: error scope: raw raw: - - '((NOTE|TIP|CAUTION|DANGER): \*\*[^:]*\*\*)|' - - '((NOTE: \*\*(NOTE|note):\*\*)|(TIP: \*\*(TIP|tip):\*\*)|(CAUTION: \*\*(CAUTION|caution):\*\*)|(DANGER: \*\*(DANGER|danger):\*\*))|' - - '((NOTE|TIP|CAUTION|DANGER): \*\*.*\*\*.+)|' + - '(\n(NOTE|TIP|CAUTION|DANGER): \*\*.*\*\*.+)|' - '((\n[> ]*(\*){1,2}(NOTE|Note|note|TIP|Tip|tip|CAUTION|Caution|caution|DANGER|Danger|danger):(\*){1,2}))' diff --git a/doc/.vale/gitlab/CurlStringsQuoted.yml b/doc/.vale/gitlab/CurlStringsQuoted.yml index 39ee9372947..a09c3fbfb51 100644 --- a/doc/.vale/gitlab/CurlStringsQuoted.yml +++ b/doc/.vale/gitlab/CurlStringsQuoted.yml @@ -1,12 +1,12 @@ --- # Warning: gitlab.CurlStringsQuoted # -# Ensures all codeblocks using curl quote any URL strings. +# Ensures all code blocks using curl quote any URL strings. # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence -message: 'Curl commands must wrap URLs in double quotes ("): %s' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#curl-commands +message: 'For consistency across all cURL examples, always wrap the URL in double quotes ("): %s' +link: https://docs.gitlab.com/ee/development/documentation/restful_api_styleguide.html#curl-commands level: warning scope: code raw: diff --git a/doc/.vale/gitlab/CurrentStatus.yml b/doc/.vale/gitlab/CurrentStatus.yml index 7368310eee8..584ac73aa17 100644 --- a/doc/.vale/gitlab/CurrentStatus.yml +++ b/doc/.vale/gitlab/CurrentStatus.yml @@ -5,7 +5,7 @@ # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence -message: 'Avoid words like "%s" that promise future changes.' +message: 'Avoid words like "%s" that promise future changes, because documentation is about the current state of the product.' level: suggestion ignorecase: true link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language-to-avoid diff --git a/doc/.vale/gitlab/FutureTense.yml b/doc/.vale/gitlab/FutureTense.yml index 4a74ee87331..bba60dc9657 100644 --- a/doc/.vale/gitlab/FutureTense.yml +++ b/doc/.vale/gitlab/FutureTense.yml @@ -6,7 +6,7 @@ # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence -message: 'Avoid using future tense: "%s"' +message: 'Avoid using future tense: "%s". Use present tense instead.' ignorecase: true level: warning link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language-to-avoid diff --git a/doc/.vale/gitlab/InternalLinkExtension.yml b/doc/.vale/gitlab/InternalLinkExtension.yml index 61a08e4a86c..9b5a3499815 100644 --- a/doc/.vale/gitlab/InternalLinkExtension.yml +++ b/doc/.vale/gitlab/InternalLinkExtension.yml @@ -10,4 +10,4 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links level: error scope: raw raw: - - '\[.+\]\((https?:){0}[\w\/\.-]+(\.html).*\)' + - '\[.+\]\((https?:){0}[\w\/\.-]+(\.html).*?\)' diff --git a/doc/.vale/gitlab/InternalLinkFormat.yml b/doc/.vale/gitlab/InternalLinkFormat.yml new file mode 100644 index 00000000000..9a72778140e --- /dev/null +++ b/doc/.vale/gitlab/InternalLinkFormat.yml @@ -0,0 +1,13 @@ +--- +# Error: gitlab.InternalLinkFormat +# +# Checks that internal link paths don't start with "./", which is not needed. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Link "%s" must not start with "./".' +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links-to-internal-documentation +level: error +scope: raw +raw: + - '\[.+\]\(\.\/.+?\)' diff --git a/doc/.vale/gitlab/RelativeLinks.yml b/doc/.vale/gitlab/RelativeLinks.yml index 7af20d8226f..1ae73472f8a 100644 --- a/doc/.vale/gitlab/RelativeLinks.yml +++ b/doc/.vale/gitlab/RelativeLinks.yml @@ -5,7 +5,7 @@ # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence -message: 'Link "%s" must be relative.' +message: 'Link "%s" must be a relative link with a .md extension.' link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links-to-internal-documentation level: error scope: raw diff --git a/doc/.vale/gitlab/Simplicity.yml b/doc/.vale/gitlab/Simplicity.yml new file mode 100644 index 00000000000..fa7a07c3e81 --- /dev/null +++ b/doc/.vale/gitlab/Simplicity.yml @@ -0,0 +1,18 @@ +--- +# Suggestion: gitlab.Simplicity +# +# Checks for words implying ease of use, to avoid cognitive dissonance for frustrated users. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Avoid words like "%s" that imply ease of use, because the user may find this action hard.' +level: suggestion +ignorecase: true +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language-to-avoid +tokens: + - easy + - easily + - handy + - simple + - simply + - useful diff --git a/doc/.vale/gitlab/SubstitutionSuggestions.yml b/doc/.vale/gitlab/SubstitutionSuggestions.yml new file mode 100644 index 00000000000..df68961b1ce --- /dev/null +++ b/doc/.vale/gitlab/SubstitutionSuggestions.yml @@ -0,0 +1,17 @@ +--- +# Suggestion: gitlab.SubstitutionSuggestions +# +# Suggests better options for frequently misused terms at GitLab that are +# often - but not always - incorrect. +# +# For a list of all options, see https://errata-ai.github.io/vale/styles/ +extends: substitution +message: 'Consider "%s" instead of "%s".' +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language +level: suggestion +ignorecase: true +swap: + since: because + once that: after that + once the: after the + once you: after you diff --git a/doc/.vale/gitlab/SubstitutionWarning.yml b/doc/.vale/gitlab/SubstitutionWarning.yml index 68313a37e7d..ed0f8b498fe 100644 --- a/doc/.vale/gitlab/SubstitutionWarning.yml +++ b/doc/.vale/gitlab/SubstitutionWarning.yml @@ -18,3 +18,4 @@ swap: filesystem: file system info: information repo: repository + utilize: use diff --git a/doc/.vale/gitlab/Substitutions.yml b/doc/.vale/gitlab/Substitutions.yml index 704c64f1fbd..3d1cf8057eb 100644 --- a/doc/.vale/gitlab/Substitutions.yml +++ b/doc/.vale/gitlab/Substitutions.yml @@ -25,5 +25,13 @@ swap: self hosted: self-managed self-hosted: self-managed styleguide: style guide + to login: to log in + can login: can log in + to log-in: to log in + can log-in: can log in + to signin: to sign in + can signin: can sign in + to sign-in: to sign in + can sign-in: can sign in x509: X.509 yaml: YAML diff --git a/doc/.vale/gitlab/ToDo.yml b/doc/.vale/gitlab/ToDo.yml new file mode 100644 index 00000000000..b3c5f6077b1 --- /dev/null +++ b/doc/.vale/gitlab/ToDo.yml @@ -0,0 +1,14 @@ +--- +# Warning: gitlab.ToDo +# +# You should not use "To Do", unless it refers to the UI element. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: 'Use "to-do item" in most cases, or "Add a to do" if referring to the UI button.' +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#feature-names +level: warning +ignorecase: false +swap: + '[Tt]o [Dd]o [Ii]tems?': to-do item + '\w* [Aa] [Tt]o [Dd]o': Add a to do diff --git a/doc/.vale/gitlab/VersionText.yml b/doc/.vale/gitlab/VersionText.yml index 3723170b169..e59b936ae3f 100644 --- a/doc/.vale/gitlab/VersionText.yml +++ b/doc/.vale/gitlab/VersionText.yml @@ -15,9 +15,9 @@ # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence -message: '"%s" is not formatted correctly.' +message: 'This introduced-in line is not formatted correctly.' link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#text-for-documentation-requiring-version-text level: error scope: raw raw: - - '> (- ){0}\[?Introduced.+\n.+' + - '> (- ){0}\[?Introduced.+\n[^\n`]' diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index c0a85fc6b70..bbb5c892298 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -232,6 +232,7 @@ Laravel LDAP ldapsearch Leiningen +Lefthook Libravatar liveness Lograge @@ -347,6 +348,7 @@ proxied proxies proxyable proxying +pseudocode pseudonymized pseudonymizer Puma diff --git a/doc/.vale/vale.tmpl b/doc/.vale/vale.tmpl new file mode 100644 index 00000000000..36dfbd6b778 --- /dev/null +++ b/doc/.vale/vale.tmpl @@ -0,0 +1,51 @@ +{{- /* Modify Vale's output https://docs.errata.ai/vale/cli#--output */ -}} + +{{- /* Keep track of our various counts */ -}} + +{{- $e := 0 -}} +{{- $w := 0 -}} +{{- $s := 0 -}} +{{- $f := 0 -}} + +{{- /* Range over the linted files */ -}} + +{{- range .Files}} + +{{- $f = add1 $f -}} +{{- $path := .Path | underline -}} + +{{- /* Range over the file's alerts */ -}} + +{{- range .Alerts -}} + +{{- $error := "" -}} +{{- if eq .Severity "error" -}} + {{- $error = .Severity | red -}} + {{- $e = add1 $e -}} +{{- else if eq .Severity "warning" -}} + {{- $error = .Severity | yellow -}} + {{- $w = add1 $w -}} +{{- else -}} + {{- $error = .Severity | blue -}} + {{- $s = add1 $s -}} +{{- end}} + +{{- /* Variables setup */ -}} + +{{- $path = $path -}} +{{- $loc := printf "Line %d, position %d" .Line (index .Span 0) -}} +{{- $check := printf "%s" .Check -}} +{{- $message := printf "%s" .Message -}} +{{- $link := printf "%s" .Link -}} + +{{- /* Output */ -}} + +{{ $path }}: + {{ $loc }} (rule {{ $check }}) + {{ $error }}: {{ $message }} + More information: {{ $link }} + +{{end -}} +{{end -}} + +{{- $e}} {{"errors" | red}}, {{$w}} {{"warnings" | yellow}}, and {{$s}} {{"suggestions" | blue}} found in {{$f}} {{$f | int | plural "file" "files"}}. diff --git a/doc/README.md b/doc/README.md index 09638bb4ce8..759b5dda32b 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,9 +1,12 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false description: 'Learn how to use and administer GitLab, the most scalable Git-based fully integrated platform for software development.' --- -<div class="display-none"> +<div class="d-none"> <em>Visit <a href="https://docs.gitlab.com/ee/">docs.gitlab.com</a> for optimized navigation, discoverability, and readability.</em> </div> @@ -20,14 +23,14 @@ Here you can access the complete documentation for GitLab, the single applicatio No matter how you use GitLab, we have documentation for you. -| Essential documentation | Essential documentation | -|:-------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------| -| [**User Documentation**](user/index.md)<br/>Discover features and concepts for GitLab users. | [**Administrator documentation**](administration/index.md)<br/>Everything GitLab self-managed administrators need to know. | -| [**Contributing to GitLab**](#contributing-to-gitlab)<br/>At GitLab, everyone can contribute! | [**New to Git and GitLab?**](#new-to-git-and-gitlab)<br/>We have the resources to get you started. | -| [**Build an integration with GitLab?**](#build-an-integration-with-gitlab)<br/>Consult our automation and integration documentation. | [**Coming to GitLab from another platform?**](#coming-to-gitlab-from-another-platform)<br/>Consult our handy guides. | -| [**Install GitLab**](https://about.gitlab.com/install/)<br/>Installation options for different platforms. | [**Customers**](subscriptions/index.md)<br/>Information for new and existing customers. | -| [**Update GitLab**](update/README.md)<br/>Update your GitLab self-managed instance to the latest version. | [**Reference Architectures**](administration/reference_architectures/index.md)<br/>GitLab's reference architectures | -| [**GitLab Releases**](https://about.gitlab.com/releases/)<br/>What's new in GitLab. | | +| Essential documentation | Essential documentation | +|:------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------| +| [**User documentation**](user/index.md)<br>Discover features and concepts for GitLab users. | [**Administrator documentation**](administration/index.md)<br/>Everything GitLab self-managed administrators need to know. | +| [**Contributing to GitLab**](#contributing-to-gitlab)<br/>At GitLab, everyone can contribute! | [**New to Git and GitLab?**](#new-to-git-and-gitlab)<br/>We have the resources to get you started. | +| [**Build an integration with GitLab**](#build-an-integration-with-gitlab)<br/>Consult our automation and integration documentation. | [**Coming to GitLab from another platform?**](#coming-to-gitlab-from-another-platform)<br/>Consult our guides. | +| [**Install GitLab**](https://about.gitlab.com/install/)<br/>Installation options for different platforms. | [**Customers**](subscriptions/index.md)<br/>Information for new and existing customers. | +| [**Update GitLab**](update/README.md)<br/>Update your GitLab self-managed instance to the latest version. | [**Reference Architectures**](administration/reference_architectures/index.md)<br/>GitLab's reference architectures | +| [**GitLab releases**](https://about.gitlab.com/releases/)<br/>What's new in GitLab. | | ## Popular topics @@ -47,7 +50,7 @@ Have a look at some of our most popular topics: | [Omnibus GitLab SSL configuration](https://docs.gitlab.com/omnibus/settings/ssl.html) **(CORE ONLY)** | SSL settings for Omnibus GitLab self-managed instances. | | [GitLab.com settings](user/gitlab_com/index.md) | Settings used for GitLab.com. | -## The entire DevOps Lifecycle +## The entire DevOps lifecycle GitLab is the first single application for software development, security, and operations that enables [Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/), @@ -89,11 +92,11 @@ GitLab provides statistics and insights into ways you can maximize the value of The following documentation relates to the DevOps **Manage** stage: -| Manage topics | Description | -|:--------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Authentication and<br/>Authorization](administration/auth/README.md) **(CORE ONLY)** | Supported authentication and authorization providers. | -| [GitLab Value Stream Analytics](user/analytics/value_stream_analytics.md) | Measure the time it takes to go from an [idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) for each project you have. | -| [Instance-level Analytics](user/admin_area/analytics/index.md) | Discover statistics on how many GitLab features you use and user activity. | +| Manage topics | Description | +|:--------------------------------------------------------------------------------------|:---------------------------------------------------------------------------| +| [Authentication and<br/>Authorization](administration/auth/README.md) **(CORE ONLY)** | Supported authentication and authorization providers. | +| [GitLab Value Stream Analytics](user/analytics/value_stream_analytics.md) | Measure the time it takes to go from an [idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) for each project you have. | +| [Instance-level analytics](user/admin_area/analytics/index.md) | Discover statistics on how many GitLab features you use and user activity. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -110,23 +113,23 @@ management tools. The following documentation relates to the DevOps **Plan** stage: -| Plan topics | Description | -|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------| -| [Burndown Charts](user/project/milestones/burndown_charts.md) **(STARTER)** | Watch your project's progress throughout a specific milestone. | -| [Discussions](user/discussions/index.md) | Threads, comments, and resolvable threads in issues, commits, and merge requests. | -| [Due Dates](user/project/issues/due_dates.md) | Keep track of issue deadlines. | -| [Epics](user/group/epics/index.md) **(ULTIMATE)** | Tracking groups of issues that share a theme. | +| Plan topics | Description | +|:-----------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------| +| [Burndown charts](user/project/milestones/burndown_charts.md) **(STARTER)** | Watch your project's progress throughout a specific milestone. | +| [Discussions](user/discussions/index.md) | Threads, comments, and resolvable threads in issues, commits, and merge requests. | +| [Due dates](user/project/issues/due_dates.md) | Keep track of issue deadlines. | +| [Epics](user/group/epics/index.md) **(ULTIMATE)** | Tracking groups of issues that share a theme. | | [Issues](user/project/issues/index.md), including [confidential issues](user/project/issues/confidential_issues.md),<br/>[issue and merge request templates](user/project/description_templates.md),<br/>and [moving issues](user/project/issues/managing_issues.md#moving-issues) | Project issues and restricting access to issues as well as creating templates for submitting new issues and merge requests. Also, moving issues between projects. | -| [Labels](user/project/labels.md) | Categorize issues or merge requests with descriptive labels. | -| [Milestones](user/project/milestones/index.md) | Set milestones for delivery of issues and merge requests, with optional due date. | -| [Project Issue Board](user/project/issue_board.md) | Display issues on a Scrum or Kanban board. | -| [Quick Actions](user/project/quick_actions.md) | Shortcuts for common actions on issues or merge requests, replacing the need to click buttons or use dropdowns in GitLab's UI. | -| [Related Issues](user/project/issues/related_issues.md) | Create a relationship between issues. | -| [Requirements Management](user/project/requirements/index.md) **(ULTIMATE)** | Check your products against a set of criteria. | -| [Roadmap](user/group/roadmap/index.md) **(ULTIMATE)** | Visualize epic timelines. | -| [Service Desk](user/project/service_desk.md) | A simple way to allow people to create issues in your GitLab instance without needing their own user account. | -| [Time Tracking](user/project/time_tracking.md) | Track time spent on issues and merge requests. | -| [To-Do List](user/todos.md) | Keep track of work requiring attention with a chronological list displayed on a simple dashboard. | +| [Labels](user/project/labels.md) | Categorize issues or merge requests with descriptive labels. | +| [Milestones](user/project/milestones/index.md) | Set milestones for delivery of issues and merge requests, with optional due date. | +| [Project Issue Board](user/project/issue_board.md) | Display issues on a Scrum or Kanban board. | +| [Quick Actions](user/project/quick_actions.md) | Shortcuts for common actions on issues or merge requests, replacing the need to click buttons or use dropdowns in GitLab's UI. | +| [Related issues](user/project/issues/related_issues.md) | Create a relationship between issues. | +| [Requirements Management](user/project/requirements/index.md) **(ULTIMATE)** | Check your products against a set of criteria. | +| [Roadmap](user/group/roadmap/index.md) **(ULTIMATE)** | Visualize epic timelines. | +| [Service Desk](user/project/service_desk.md) | A simple way to allow people to create issues in your GitLab instance without needing their own user account. | +| [Time Tracking](user/project/time_tracking.md) | Track time spent on issues and merge requests. | +| [To-Do list](user/todos.md) | Keep track of work requiring attention with a chronological list displayed on a simple dashboard. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -145,25 +148,25 @@ on projects and code. The following documentation relates to the DevOps **Create** stage: -#### Projects and Groups - -| Create topics - Projects and Groups | Description | -|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------| -| [Advanced search](user/search/advanced_global_search.md) **(STARTER)** | Leverage Elasticsearch for faster, more advanced code search across your entire GitLab instance. | -| [Advanced syntax search](user/search/advanced_search_syntax.md) **(STARTER)** | Use advanced queries for more targeted search results. | -| [Contribution analytics](user/group/contribution_analytics/index.md) **(STARTER)** | See detailed statistics of group contributors. | -| [Create](gitlab-basics/create-project.md) and [fork](gitlab-basics/fork-project.md) projects, and<br/>[import and export projects<br/>between instances](user/project/settings/import_export.md) | Create, duplicate, and move projects. | -| [File locking](user/project/file_lock.md) **(PREMIUM)** | Lock files to avoid merge conflicts. | -| [GitLab Pages](user/project/pages/index.md) | Build, test, and deploy your static website with GitLab Pages. | -| [Groups](user/group/index.md) and [Subgroups](user/group/subgroups/index.md) | Organize your projects in groups. | -| [Issue Analytics](user/group/issues_analytics/index.md) **(PREMIUM)** | Check how many issues were created per month. | -| [Merge Request Analytics](user/analytics/merge_request_analytics.md) **(PREMIUM)** | Check your throughput productivity - how many merge requests were merged per month. | -| [Projects](user/project/index.md), including [project access](public_access/public_access.md)<br/>and [settings](user/project/settings/index.md) | Host source code, and control your project's visibility and set configuration. | -| [Search through GitLab](user/search/index.md) | Search for issues, merge requests, projects, groups, and to-dos. | -| [Snippets](user/snippets.md) | Snippets allow you to create little bits of code. | -| [Web IDE](user/project/web_ide/index.md) | Edit files within GitLab's user interface. | -| [Static Site Editor](user/project/static_site_editor/index.md) | Edit content on static websites. | -| [Wikis](user/project/wiki/index.md) | Enhance your repository documentation with built-in wikis. | +#### Projects and groups + +| Create topics - Projects and Groups | Description | +|:-----------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------| +| [Advanced search](user/search/advanced_global_search.md) **(STARTER)** | Leverage Elasticsearch for faster, more advanced code search across your entire GitLab instance. | +| [Advanced syntax search](user/search/advanced_search_syntax.md) **(STARTER)** | Use advanced queries for more targeted search results. | +| [Contribution analytics](user/group/contribution_analytics/index.md) **(STARTER)** | See detailed statistics of group contributors. | +| [Create](gitlab-basics/create-project.md) and [fork](gitlab-basics/fork-project.md) projects, and<br/>[import and export projects<br/>between instances](user/project/settings/import_export.md) | Create, duplicate, and move projects. | +| [File locking](user/project/file_lock.md) **(PREMIUM)** | Lock files to avoid merge conflicts. | +| [GitLab Pages](user/project/pages/index.md) | Build, test, and deploy your static website with GitLab Pages. | +| [Groups](user/group/index.md) and [Subgroups](user/group/subgroups/index.md) | Organize your projects in groups. | +| [Issue analytics](user/group/issues_analytics/index.md) **(PREMIUM)** | Check how many issues were created per month. | +| [Merge Request analytics](user/analytics/merge_request_analytics.md) **(PREMIUM)** | Check your throughput productivity - how many merge requests were merged per month. | +| [Projects](user/project/index.md), including [project access](public_access/public_access.md)<br/>and [settings](user/project/settings/index.md) | Host source code, and control your project's visibility and set configuration. | +| [Search through GitLab](user/search/index.md) | Search for issues, merge requests, projects, groups, and to-dos. | +| [Snippets](user/snippets.md) | Snippets allow you to create little bits of code. | +| [Web IDE](user/project/web_ide/index.md) | Edit files within GitLab's user interface. | +| [Static Site Editor](user/project/static_site_editor/index.md) | Edit content on static websites. | +| [Wikis](user/project/wiki/index.md) | Enhance your repository documentation with built-in wikis. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -173,20 +176,20 @@ The following documentation relates to the DevOps **Create** stage: #### Repositories -| Create topics - Repositories | Description | -|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------| -| [Branches](user/project/repository/branches/index.md) and the [default branch](user/project/repository/branches/index.md#default-branch) | How to use branches in GitLab. | -| [Commits](user/project/repository/index.md#commits) and [signing commits](user/project/repository/gpg_signed_commits/index.md) | Work with commits, and use GPG to sign your commits. | +| Create topics - Repositories | Description | +|:-----------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------| +| [Branches](user/project/repository/branches/index.md) and the [default branch](user/project/repository/branches/index.md#default-branch) | How to use branches in GitLab. | +| [Commits](user/project/repository/index.md#commits) and [signing commits](user/project/repository/gpg_signed_commits/index.md) | Work with commits, and use GPG to sign your commits. | | [Create branches](user/project/repository/web_editor.md#create-a-new-branch), [create](user/project/repository/web_editor.md#create-a-file)<br/>and [upload](user/project/repository/web_editor.md#upload-a-file) files, and [create directories](user/project/repository/web_editor.md#create-a-directory) | Create branches, create and upload files, and create directories within GitLab. | -| [Delete merged branches](user/project/repository/branches/index.md#delete-merged-branches) | Bulk delete branches after their changes are merged. | -| [File templates](user/project/repository/web_editor.md#template-dropdowns) | File templates for common files. | -| [Files](user/project/repository/index.md#files) | Files management. | -| [Jupyter Notebook files](user/project/repository/jupyter_notebooks/index.md#jupyter-notebook-files) | GitLab's support for `.ipynb` files. | -| [Protected branches](user/project/protected_branches.md) | Use protected branches. | -| [Push rules](push_rules/push_rules.md) **(STARTER)** | Additional control over pushes to your projects. | -| [Repositories](user/project/repository/index.md) | Manage source code repositories in GitLab's user interface. | -| [Repository mirroring](user/project/repository/repository_mirroring.md) **(STARTER)** | Push to or pull from repositories outside of GitLab | -| [Start a merge request](user/project/repository/web_editor.md#tips) | Start merge request when committing via GitLab's user interface. | +| [Delete merged branches](user/project/repository/branches/index.md#delete-merged-branches) | Bulk delete branches after their changes are merged. | +| [File templates](user/project/repository/web_editor.md#template-dropdowns) | File templates for common files. | +| [Files](user/project/repository/index.md#files) | Files management. | +| [Jupyter Notebook files](user/project/repository/jupyter_notebooks/index.md#jupyter-notebook-files) | GitLab's support for `.ipynb` files. | +| [Protected branches](user/project/protected_branches.md) | Use protected branches. | +| [Push rules](push_rules/push_rules.md) **(STARTER)** | Additional control over pushes to your projects. | +| [Repositories](user/project/repository/index.md) | Manage source code repositories in GitLab's user interface. | +| [Repository mirroring](user/project/repository/repository_mirroring.md) **(STARTER)** | Push to or pull from repositories outside of GitLab | +| [Start a merge request](user/project/repository/web_editor.md#tips) | Start merge request when committing via GitLab's user interface. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -194,15 +197,15 @@ The following documentation relates to the DevOps **Create** stage: </a> </div> -#### Merge Requests +#### Merge requests -| Create topics - Merge Requests | Description | -|:--------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------| -| [Checking out merge requests locally](user/project/merge_requests/reviewing_and_managing_merge_requests.md#checkout-merge-requests-locally-through-the-head-ref) | Tips for working with merge requests locally. | -| [Cherry-picking](user/project/merge_requests/cherry_pick_changes.md) | Use GitLab for cherry-picking changes. | -| [Merge request thread resolution](user/discussions/index.md#moving-a-single-thread-to-a-new-issue) | Resolve threads, move threads in a merge request to an issue, and only allow merge requests to be merged if all threads are resolved. | -| [Merge requests](user/project/merge_requests/index.md) | Merge request management. | -| [**Draft** merge requests](user/project/merge_requests/work_in_progress_merge_requests.md) | Prevent merges of draft merge requests. | +| Create topics - Merge Requests | Description | +|:---------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------| +| [Checking out merge requests locally](user/project/merge_requests/reviewing_and_managing_merge_requests.md#checkout-merge-requests-locally-through-the-head-ref) | Tips for working with merge requests locally. | +| [Cherry-picking](user/project/merge_requests/cherry_pick_changes.md) | Use GitLab for cherry-picking changes. | +| [Merge request thread resolution](user/discussions/index.md#moving-a-single-thread-to-a-new-issue) | Resolve threads, move threads in a merge request to an issue, and only allow merge requests to be merged if all threads are resolved. | +| [Merge requests](user/project/merge_requests/index.md) | Merge request management. | +| [Draft merge requests](user/project/merge_requests/work_in_progress_merge_requests.md) | Prevent merges of draft merge requests. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -212,15 +215,15 @@ The following documentation relates to the DevOps **Create** stage: #### Integration and Automation -| Create topics - Integration and Automation | Description | -|:------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------| -| [GitLab REST API](api/README.md) | Integrate with GitLab using our REST API. | -| [GitLab GraphQL API](api/graphql/index.md) | Integrate with GitLab using our GraphQL API. | -| [GitLab Integration](integration/README.md) | Integrate with multiple third-party services with GitLab to allow external issue trackers and external authentication. | -| [GitLab Webhooks](user/project/integrations/webhooks.md) | Let GitLab notify you when new code has been pushed to your project. | +| Create topics - Integration and Automation | Description | +|:----------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------| +| [GitLab REST API](api/README.md) | Integrate with GitLab using our REST API. | +| [GitLab GraphQL API](api/graphql/index.md) | Integrate with GitLab using our GraphQL API. | +| [GitLab integrations](integration/README.md) | Integrate with multiple third-party services with GitLab to allow external issue trackers and external authentication. | +| [GitLab Webhooks](user/project/integrations/webhooks.md) | Let GitLab notify you when new code has been pushed to your project. | | [Jira Development Panel](integration/jira_development_panel.md) | See GitLab information in the Jira Development Panel. | -| [Integrations](user/project/integrations/overview.md) | Integrate a project with external services, such as CI and chat. | -| [Trello Power-Up](integration/trello_power_up.md) | Integrate with GitLab's Trello Power-Up. | +| [Integrations](user/project/integrations/overview.md) | Integrate a project with external services, such as CI and chat. | +| [Trello Power-Up](integration/trello_power_up.md) | Integrate with GitLab's Trello Power-Up. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -240,14 +243,14 @@ scales to run your tests faster. The following documentation relates to the DevOps **Verify** stage: -| Verify topics | Description | -|:----------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------| -| [Code Quality reports](user/project/merge_requests/code_quality.md) | Analyze source code quality. | -| [GitLab CI/CD](ci/README.md) | Explore the features and capabilities of Continuous Integration with GitLab. | -| [Unit test reports](ci/unit_test_reports.md) | Display Unit test reports on merge requests. | -| [Multi-project pipelines](ci/multi_project_pipelines.md) **(PREMIUM)** | Visualize entire pipelines that span multiple projects, including all cross-project inter-dependencies. | -| [Pipeline Graphs](ci/pipelines/index.md#visualize-pipelines) | Visualize builds. | -| [Review Apps](ci/review_apps/index.md) | Preview changes to your application right from a merge request. | +| Verify topics | Description | +|:-----------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------| +| [Code Quality reports](user/project/merge_requests/code_quality.md) | Analyze source code quality. | +| [GitLab CI/CD](ci/README.md) | Explore the features and capabilities of Continuous Integration with GitLab. | +| [Unit test reports](ci/unit_test_reports.md) | Display Unit test reports on merge requests. | +| [Multi-project pipelines](ci/multi_project_pipelines.md) **(PREMIUM)** | Visualize entire pipelines that span multiple projects, including all cross-project inter-dependencies. | +| [Pipeline graphs](ci/pipelines/index.md#visualize-pipelines) | Visualize builds. | +| [Review Apps](ci/review_apps/index.md) | Preview changes to your application right from a merge request. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -257,17 +260,17 @@ The following documentation relates to the DevOps **Verify** stage: ### Package -GitLab Packages allows organizations to utilize GitLab as a private repository +GitLab Packages allows organizations to use GitLab as a private repository for a variety of common package managers. Users are able to build and publish -packages, which can be easily consumed as a dependency in downstream projects. +packages, which can be consumed as a dependency in downstream projects. The following documentation relates to the DevOps **Package** stage: -| Package topics | Description | -|:----------------------------------------------------------------|:-------------------------------------------------------| -| [Container Registry](user/packages/container_registry/index.md) | The GitLab Container Registry enables every project in GitLab to have its own space to store [Docker](https://www.docker.com/) images. | -| [Dependency Proxy](user/packages/dependency_proxy/index.md) **(PREMIUM)** | The GitLab Dependency Proxy sets up a local proxy for frequently used upstream images/packages. | -| [Package Registry](user/packages/package_registry/index.md) | Use GitLab as a private or public registry for a variety of common package managers, including [NPM](user/packages/npm_registry/index.md), [Maven](user/packages/maven_repository/index.md), [PyPI](user/packages/pypi_repository/index.md), and others. You can also store generic files. | +| Package topics | Description | +|:----------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------| +| [Container Registry](user/packages/container_registry/index.md) | The GitLab Container Registry enables every project in GitLab to have its own space to store [Docker](https://www.docker.com/) images. | +| [Dependency Proxy](user/packages/dependency_proxy/index.md) | The GitLab Dependency Proxy sets up a local proxy for frequently used upstream images/packages. | +| [Package Registry](user/packages/package_registry/index.md) | Use GitLab as a private or public registry for a variety of common package managers, including [NPM](user/packages/npm_registry/index.md), [Maven](user/packages/maven_repository/index.md), [PyPI](user/packages/pypi_repository/index.md), and others. You can also store generic files. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -285,19 +288,19 @@ remediation processes when needed. The following documentation relates to the DevOps **Secure** stage: -| Secure topics | Description | -|:------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------| -| [Compliance Dashboard](user/compliance/compliance_dashboard/index.md) **(ULTIMATE)** | View the most recent Merge Request activity in a group. | -| [Container Scanning](user/application_security/container_scanning/index.md) **(ULTIMATE)** | Use Clair to scan Docker images for known vulnerabilities. | -| [Dependency List](user/application_security/dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. | -| [Dependency Scanning](user/application_security/dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | -| [Dynamic Application Security Testing (DAST)](user/application_security/dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | -| [Group Security Dashboard](user/application_security/security_dashboard/index.md#group-security-dashboard) **(ULTIMATE)** | View vulnerabilities in all the projects in a group and its subgroups. | -| [Instance Security Center](user/application_security/security_dashboard/index.md#instance-security-center) **(ULTIMATE)** | View vulnerabilities in all the projects you're interested in. | -| [License Compliance](user/compliance/license_compliance/index.md) **(ULTIMATE)** | Search your project's dependencies for their licenses. | -| [Pipeline Security](user/application_security/security_dashboard/index.md#pipeline-security) **(ULTIMATE)** | View the security reports for your project's pipelines. | -| [Project Security Dashboard](user/application_security/security_dashboard/index.md#project-security-dashboard) **(ULTIMATE)** | View the latest security reports for your project. | -| [Static Application Security Testing (SAST)](user/application_security/sast/index.md) **(ULTIMATE)** | Analyze source code for known vulnerabilities. | +| Secure topics | Description | +|:------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------| +| [Compliance Dashboard](user/compliance/compliance_dashboard/index.md) **(ULTIMATE)** | View the most recent Merge Request activity in a group. | +| [Container Scanning](user/application_security/container_scanning/index.md) **(ULTIMATE)** | Use Clair to scan Docker images for known vulnerabilities. | +| [Dependency List](user/application_security/dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. | +| [Dependency Scanning](user/application_security/dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | +| [Dynamic Application Security Testing (DAST)](user/application_security/dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | +| [Group Security Dashboard](user/application_security/security_dashboard/index.md#group-security-dashboard) **(ULTIMATE)** | View vulnerabilities in all the projects in a group and its subgroups. | +| [Instance Security Center](user/application_security/security_dashboard/index.md#instance-security-center) **(ULTIMATE)** | View vulnerabilities in all the projects you're interested in. | +| [License Compliance](user/compliance/license_compliance/index.md) **(ULTIMATE)** | Search your project's dependencies for their licenses. | +| [Pipeline Security](user/application_security/security_dashboard/index.md#pipeline-security) **(ULTIMATE)** | View the security reports for your project's pipelines. | +| [Project Security Dashboard](user/application_security/security_dashboard/index.md#project-security-dashboard) **(ULTIMATE)** | View the latest security reports for your project. | +| [Static Application Security Testing (SAST)](user/application_security/sast/index.md) **(ULTIMATE)** | Analyze source code for known vulnerabilities. | ### Release @@ -307,17 +310,17 @@ confidently and securely with GitLab’s built-in Continuous Delivery and Deploy The following documentation relates to the DevOps **Release** stage: -| Release topics | Description | -|:------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------| -| [Auto Deploy](topics/autodevops/stages.md#auto-deploy) | Configure GitLab for the deployment of your application. | -| [Canary Deployments](user/project/canary_deployments.md) **(PREMIUM)** | Employ a popular CI strategy where a small portion of the fleet is updated to the new version first. | -| [Deploy Boards](user/project/deploy_boards.md) **(PREMIUM)** | View the current health and status of each CI environment running on Kubernetes, displaying the status of the pods in the deployment. | -| [Environments and deployments](ci/environments/index.md) | With environments, you can control the continuous deployment of your software within GitLab. | -| [Environment-specific variables](ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) | Limit the scope of variables to specific environments. | -| [GitLab CI/CD](ci/README.md) | Explore the features and capabilities of Continuous Deployment and Delivery with GitLab. | -| [GitLab Pages](user/project/pages/index.md) | Build, test, and deploy a static site directly from GitLab. | -| [Protected Runners](ci/runners/README.md#prevent-runners-from-revealing-sensitive-information) | Select Runners to only pick jobs for protected branches and tags. | -| [Scheduled Pipelines](ci/pipelines/schedules.md) | Execute pipelines on a schedule. | +| Release topics | Description | +|:---------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------| +| [Auto Deploy](topics/autodevops/stages.md#auto-deploy) | Configure GitLab for the deployment of your application. | +| [Canary Deployments](user/project/canary_deployments.md) **(PREMIUM)** | Employ a popular CI strategy where a small portion of the fleet is updated to the new version first. | +| [Deploy Boards](user/project/deploy_boards.md) **(PREMIUM)** | View the current health and status of each CI environment running on Kubernetes, displaying the status of the pods in the deployment. | +| [Environments and deployments](ci/environments/index.md) | With environments, you can control the continuous deployment of your software within GitLab. | +| [Environment-specific variables](ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) | Limit the scope of variables to specific environments. | +| [GitLab CI/CD](ci/README.md) | Explore the features and capabilities of Continuous Deployment and Delivery with GitLab. | +| [GitLab Pages](user/project/pages/index.md) | Build, test, and deploy a static site directly from GitLab. | +| [Protected runners](ci/runners/README.md#prevent-runners-from-revealing-sensitive-information) | Select Runners to only pick jobs for protected branches and tags. | +| [Schedule pipelines](ci/pipelines/schedules.md) | Execute pipelines on a schedule. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -333,19 +336,19 @@ configuration. Then customize everything from buildpacks to CI/CD. The following documentation relates to the DevOps **Configure** stage: -| Configure topics | Description | -|:-----------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------| -| [Auto DevOps](topics/autodevops/index.md) | Automatically employ a complete DevOps lifecycle. | -| [Create Kubernetes clusters](user/project/clusters/add_remove_clusters.md#create-new-cluster) | Use Kubernetes and GitLab. | -| [Executable Runbooks](user/project/clusters/runbooks/index.md) | Documented procedures that explain how to carry out particular processes. | -| [GitLab ChatOps](ci/chatops/README.md) | Interact with CI/CD jobs through chat services. | -| [Installing Applications](user/project/clusters/index.md#installing-applications) | Install Helm charts such as Ingress and Prometheus on Kubernetes. | -| [Mattermost slash commands](user/project/integrations/mattermost_slash_commands.md) | Enable and use slash commands from within Mattermost. | -| [Multiple Kubernetes Clusters](user/project/clusters/index.md#multiple-kubernetes-clusters) | Associate more than one Kubernetes clusters to your project. | -| [Protected variables](ci/variables/README.md#protect-a-custom-variable) | Restrict variables to protected branches and tags. | -| [Serverless](user/project/clusters/serverless/index.md) | Run serverless workloads on Kubernetes. | -| [Slack slash commands](user/project/integrations/slack_slash_commands.md) | Enable and use slash commands from within Slack. | -| [Manage your infrastructure with Terraform](user/infrastructure/index.md) | Manage your infrastructure as you run your CI/CD pipeline. | +| Configure topics | Description | +|:----------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------| +| [Auto DevOps](topics/autodevops/index.md) | Automatically employ a complete DevOps lifecycle. | +| [Create Kubernetes clusters](user/project/clusters/add_remove_clusters.md#create-new-cluster) | Use Kubernetes and GitLab. | +| [Executable Runbooks](user/project/clusters/runbooks/index.md) | Documented procedures that explain how to carry out particular processes. | +| [GitLab ChatOps](ci/chatops/README.md) | Interact with CI/CD jobs through chat services. | +| [Installing applications](user/project/clusters/index.md#installing-applications) | Install Helm charts such as Ingress and Prometheus on Kubernetes. | +| [Mattermost slash commands](user/project/integrations/mattermost_slash_commands.md) | Enable and use slash commands from within Mattermost. | +| [Multiple Kubernetes clusters](user/project/clusters/index.md#multiple-kubernetes-clusters) | Associate more than one Kubernetes clusters to your project. | +| [Protected variables](ci/variables/README.md#protect-a-custom-variable) | Restrict variables to protected branches and tags. | +| [Serverless](user/project/clusters/serverless/index.md) | Run serverless workloads on Kubernetes. | +| [Slack slash commands](user/project/integrations/slack_slash_commands.md) | Enable and use slash commands from within Slack. | +| [Manage your infrastructure with Terraform](user/infrastructure/index.md) | Manage your infrastructure as you run your CI/CD pipeline. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -364,12 +367,12 @@ The following documentation relates to the DevOps **Monitor** stage: | Monitor topics | Description | |:------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------| -| [GitLab Performance Monitoring](administration/monitoring/performance/index.md) **(CORE ONLY)** | Use Prometheus and Grafana to monitor the performance of your GitLab instance. | +| [GitLab Performance Monitoring](administration/monitoring/performance/index.md) **(CORE ONLY)** | Use Prometheus and Grafana to monitor the performance of your GitLab instance. | | [GitLab Prometheus](administration/monitoring/prometheus/index.md) **(CORE ONLY)** | Configure the bundled Prometheus to collect various metrics from your GitLab instance. | | [Health check](user/admin_area/monitoring/health_check.md) | GitLab provides liveness and readiness probes to indicate service health and reachability to required services. | | [Prometheus project integration](user/project/integrations/prometheus.md) | Configure the Prometheus integration per project and monitor your CI/CD environments. | | [Prometheus metrics](user/project/integrations/prometheus_library/index.md) | Let Prometheus collect metrics from various services, like Kubernetes, NGINX, NGINX Ingress controller, HAProxy, and Amazon Cloud Watch. | -| [Incident management](operations/incident_management/index.md) | Use GitLab to help you better respond to incidents that may occur in your systems. | +| [Incident management](operations/incident_management/index.md) | Use GitLab to help you better respond to incidents that may occur in your systems. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -388,11 +391,11 @@ your applications that are deployed in production. The following documentation relates to the DevOps **Defend** stage: -| Defend topics | Description | -|:------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------| -| [Web Application Firewall with ModSecurity](user/compliance/compliance_dashboard/index.md) | Filter, monitor, and block HTTP traffic to and from a web application. | -| [Container Host Security](user/clusters/applications.md#install-falco-using-gitlab-cicd) | Detect and respond to security threats at the Kubernetes, network, and host level. | -| [Container Network Security](user/clusters/applications.md#install-cilium-using-gitlab-cicd) | Detect and block unauthorized network traffic between pods and to/from the internet.| +| Defend topics | Description | +|:---------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------| +| [Web Application Firewall with ModSecurity](user/compliance/compliance_dashboard/index.md) | Filter, monitor, and block HTTP traffic to and from a web application. | +| [Container host security](user/clusters/applications.md#install-falco-using-gitlab-cicd) | Detect and respond to security threats at the Kubernetes, network, and host level. | +| [Container network security](user/clusters/applications.md#install-cilium-using-gitlab-cicd) | Detect and block unauthorized network traffic between pods and to/from the internet. | ## New to Git and GitLab? @@ -400,13 +403,13 @@ Working with new systems can be daunting. We have the following documentation to rapidly uplift your GitLab knowledge: -| Topic | Description | -|:-----------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------| -| [GitLab basics guides](gitlab-basics/README.md) | Start working on the command line and with GitLab. | -| [GitLab workflow overview](https://about.gitlab.com/blog/2016/10/25/gitlab-workflow-an-overview/) | Enhance your workflow with the best of GitLab Workflow. | -| [Get started with GitLab CI/CD](ci/quick_start/README.md) | Quickly implement GitLab CI/CD. | -| [Auto DevOps](topics/autodevops/index.md) | Learn more about GitLab's Auto DevOps. | -| [GitLab Markdown](user/markdown.md) | GitLab's advanced formatting system (GitLab Flavored Markdown) | +| Topic | Description | +|:--------------------------------------------------------------------------------------------------|:---------------------------------------------------------------| +| [GitLab basics guides](gitlab-basics/README.md) | Start working on the command line and with GitLab. | +| [GitLab workflow overview](https://about.gitlab.com/blog/2016/10/25/gitlab-workflow-an-overview/) | Enhance your workflow with the best of GitLab Workflow. | +| [Get started with GitLab CI/CD](ci/quick_start/README.md) | Quickly implement GitLab CI/CD. | +| [Auto DevOps](topics/autodevops/index.md) | Learn more about GitLab's Auto DevOps. | +| [GitLab Markdown](user/markdown.md) | GitLab's advanced formatting system (GitLab Flavored Markdown) | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -435,11 +438,11 @@ Learn more about GitLab account management: Learn more about using Git, and using Git with GitLab: -| Topic | Description | -|:----------------------------------------------------------------------------|:---------------------------------------------------------------------------| -| [Git](topics/git/index.md) | Getting started with Git, branching strategies, Git LFS, and advanced use. | +| Topic | Description | +|:-----------------------------------------------------------------------------|:---------------------------------------------------------------------------| +| [Git](topics/git/index.md) | Getting started with Git, branching strategies, Git LFS, and advanced use. | | [Git cheat sheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf) | Download a PDF describing the most used Git operations. | -| [GitLab Flow](topics/gitlab_flow.md) | Explore the best of Git with the GitLab Flow strategy. | +| [GitLab Flow](topics/gitlab_flow.md) | Explore the best of Git with the GitLab Flow strategy. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -449,12 +452,12 @@ Learn more about using Git, and using Git with GitLab: ## Coming to GitLab from another platform -If you are coming to GitLab from another platform, you'll find the following information useful: +If you are coming to GitLab from another platform, the following information is useful: -| Topic | Description | -|:---------------------------------------------------------------|:---------------------------------------------------------------------------------------| -| [Importing to GitLab](user/project/import/index.md) | Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz, and SVN into GitLab. | -| [Migrating from SVN](user/project/import/svn.md) | Convert a SVN repository to Git and GitLab. | +| Topic | Description | +|:----------------------------------------------------|:---------------------------------------------------------------------------------------| +| [Importing to GitLab](user/project/import/index.md) | Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz, and SVN into GitLab. | +| [Migrating from SVN](user/project/import/svn.md) | Convert a SVN repository to Git and GitLab. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -466,11 +469,11 @@ If you are coming to GitLab from another platform, you'll find the following inf There are many ways to integrate with GitLab, including: -| Topic | Description | -|:-----------------------------------------------------------|:------------------------------------------------| -| [GitLab REST API](api/README.md) | Integrate with GitLab using our REST API. | -| [GitLab GraphQL API](api/graphql/index.md) | Integrate with GitLab using our GraphQL API. | -| [Integrations and automation](#integration-and-automation) | All GitLab integration and automation options. | +| Topic | Description | +|:-----------------------------------------------------------|:-----------------------------------------------| +| [GitLab REST API](api/README.md) | Integrate with GitLab using our REST API. | +| [GitLab GraphQL API](api/graphql/index.md) | Integrate with GitLab using our GraphQL API. | +| [Integrations and automation](#integration-and-automation) | All GitLab integration and automation options. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index ac972e2e33e..67a3a3c1539 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -11,6 +11,8 @@ GitLab offers a way to view the changes made within the GitLab server for owners GitLab system administrators can also take advantage of the logs located on the file system. See [the logs system documentation](logs.md) for more details. +You can generate an [Audit report](audit_reports.md) of audit events. + ## Overview **Audit Events** is a tool for GitLab owners and administrators @@ -96,9 +98,10 @@ From there, you can see the following actions: - Permission to approve merge requests by authors was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7531) in GitLab 12.9) - Number of required approvals was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7531) in GitLab 12.9) - Added or removed users and groups from project approval groups ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213603) in GitLab 13.2) -- Project CI/CD variable added, removed, or protected status changed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30857) in GitLab 13.4. +- Project CI/CD variable added, removed, or protected status changed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30857) in GitLab 13.4) +- User was approved via Admin Area ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276250) in GitLab 13.6) -Project events can also be accessed via the [Project Audit Events API](../api/audit_events.md#project-audit-events) +Project events can also be accessed via the [Project Audit Events API](../api/audit_events.md#project-audit-events). ### Instance events **(PREMIUM ONLY)** @@ -113,8 +116,8 @@ To view the server-wide administrator log, visit **Admin Area > Monitoring > Aud In addition to the group and project events, the following user actions are also recorded: -- Failed Logins - Sign-in events and the authentication type (such as standard, LDAP, or OmniAuth) +- Failed sign-ins - Added SSH key - Added or removed email - Changed password @@ -127,6 +130,8 @@ recorded: - User was blocked via Admin Area ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/251) in GitLab 12.8) - User was blocked via API ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25872) in GitLab 12.9) - Failed second-factor authentication attempt ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16826) in GitLab 13.5) +- A user's personal access token was successfully created or revoked ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276921) in GitLab 13.6) +- A failed attempt to create or revoke a user's personal access token ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276921) in GitLab 13.6) It's possible to filter particular actions by choosing an audit data type from the filter dropdown box. You can further filter by specific group, project, or user @@ -134,7 +139,7 @@ the filter dropdown box. You can further filter by specific group, project, or u  -Instance events can also be accessed via the [Instance Audit Events API](../api/audit_events.md#instance-audit-events) +Instance events can also be accessed via the [Instance Audit Events API](../api/audit_events.md#instance-audit-events). ### Missing events @@ -175,6 +180,12 @@ the steps bellow. Feature.enable(:repository_push_audit_event) ``` +## Retention policy + +On GitLab.com, Audit Event records become subject to deletion after 400 days, or when your license is downgraded to a tier that does not include access to Audit Events. Data that is subject to deletion will be deleted at GitLab's discretion, possibly without additional notice. + +If you require a longer retention period, you should independently archive your Audit Event data, which you can retrieve through the [Audit Events API](../api/audit_events.md). + ## Export to CSV **(PREMIUM ONLY)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1449) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. @@ -228,7 +239,7 @@ The first row contains the headers, which are listed in the following table alon ### Limitation -The Audit Log CSV file size is limited to a maximum of `15 MB`. +The Audit Log CSV file size is limited to a maximum of `100,000` events. The remaining records are truncated when this limit is reached. ### Enable or disable Audit Log Export to CSV diff --git a/doc/administration/audit_reports.md b/doc/administration/audit_reports.md index 83fbeda26aa..9c772302375 100644 --- a/doc/administration/audit_reports.md +++ b/doc/administration/audit_reports.md @@ -18,12 +18,12 @@ needs. ## APIs -- `https://docs.gitlab.com/ee/api/audit_events.html` -- `https://docs.gitlab.com/ee/api/graphql/reference/#user` -- `https://docs.gitlab.com/ee/api/graphql/reference/#groupmember` -- `https://docs.gitlab.com/ee/api/graphql/reference/#projectmember` +- [Audit events](../api/audit_events.md) +- [GraphQL - User](../api/graphql/reference/index.md#user) +- [GraphQL - GroupMember](../api/graphql/reference/index.md#groupmember) +- [GraphQL - ProjectMember](../api/graphql/reference/index.md#projectmember) ## Features -- `https://docs.gitlab.com/ee/administration/audit_events.html` -- `https://docs.gitlab.com/ee/administration/logs.html` +- [Audit events](audit_events.md) +- [Log system](logs.md) diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md index 254bd259344..6e3dbcb68b3 100644 --- a/doc/administration/auth/crowd.md +++ b/doc/administration/auth/crowd.md @@ -82,6 +82,8 @@ If you see an error message like the one below when you sign in after Crowd auth could not authorize you from Crowd because invalid credentials ``` -Please make sure the Crowd users who need to login to GitLab are authorized to [the application](#configure-a-new-crowd-application) in the step of **Authorisation**. This could be verified by try "Authentication test" for Crowd as of 2.11. +Ensure the Crowd users who need to sign in to GitLab are authorized to the +[application](#configure-a-new-crowd-application) in the **Authorisation** step. +This could be verified by trying "Authentication test" for Crowd (as of 2.11).  diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 3df85babc94..9d88d66bf46 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -17,7 +17,7 @@ This integration works with most LDAP-compliant directory servers, including: - Open LDAP - 389 Server -Users added through LDAP take a [licensed seat](../../../subscriptions/self_managed/index.md#choose-the-number-of-users). +Users added through LDAP take a [licensed seat](../../../subscriptions/self_managed/index.md#billable-users). GitLab Enterprise Editions (EE) include enhanced integration, including group membership syncing as well as multiple LDAP servers support. @@ -97,7 +97,8 @@ library. `start_tls` corresponds to StartTLS, not to be confused with regular TL Normally, if you specify `simple_tls` it will be on port 636, while `start_tls` (StartTLS) would be on port 389. `plain` also operates on port 389. Removed values: `tls` was replaced with `start_tls` and `ssl` was replaced with `simple_tls`. -LDAP users must have an email address set, regardless of whether it is used to sign-in. +LDAP users must have a set email address, regardless of whether or not it's used +to sign in. ### Example Configurations **(CORE ONLY)** @@ -444,10 +445,10 @@ account control attribute (`userAccountControl:1.2.840.113556.1.4.803`) has bit 2 set. For more information, see <https://ctovswild.com/2009/09/03/bitmask-searches-in-ldap/> -The user will be set to `ldap_blocked` state in GitLab if the above conditions -fail. This means the user will not be able to sign-in or push/pull code. +The user is set to an `ldap_blocked` state in GitLab if the previous conditions +fail. This means the user won't be able to sign in or push/pull code. -The process will also update the following user information: +The process also updates the following user information: - Email address. - If `sync_ssh_keys` is set, SSH public keys. @@ -460,16 +461,12 @@ The LDAP sync process: ### Adjusting LDAP user sync schedule **(STARTER ONLY)** -NOTE: **Note:** -These are cron formatted values. You can use a crontab generator to create -these values, for example <http://www.crontabgenerator.com/>. - By default, GitLab runs a worker once per day at 01:30 a.m. server time to check and update GitLab users against LDAP. You can manually configure LDAP user sync times by setting the following configuration values, in cron format. If needed, you can -use a [crontab generator](http://crontabgenerator.com). +use a [crontab generator](http://www.crontabgenerator.com). The example below shows how to set LDAP user sync to run once every 12 hours at the top of the hour. diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index c6558bf1791..8920479949d 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -13,10 +13,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w #### Connection refused -If you are getting `Connection Refused` errors when trying to connect to the -LDAP server please double-check the LDAP `port` and `encryption` settings used by -GitLab. Common combinations are `encryption: 'plain'` and `port: 389`, OR -`encryption: 'simple_tls'` and `port: 636`. +If you're getting `Connection Refused` error messages when attempting to +connect to the LDAP server, review the LDAP `port` and `encryption` settings +used by GitLab. Common combinations are `encryption: 'plain'` and `port: 389`, +or `encryption: 'simple_tls'` and `port: 636`. #### Connection times out @@ -69,10 +69,10 @@ options = { # :filter is optional # 'cn' looks for all "cn"s under :base # '*' is the search string - here, it's a wildcard - filter: Net::Ldap::Filter.eq('cn', '*'), + filter: Net::LDAP::Filter.eq('cn', '*'), # :attributes is optional - # the attributes we want to get returned + # the attributes we want to get returnedk attributes: %w(dn cn memberuid member submember uniquemember memberof) } adapter.ldap_search(options) @@ -103,16 +103,16 @@ A user can have trouble signing in for any number of reasons. To get started, here are some questions to ask yourself: - Does the user fall under the [configured `base`](index.md#configuration) in - LDAP? The user must fall under this `base` to sign-in. + LDAP? The user must fall under this `base` to sign in. - Does the user pass through the [configured `user_filter`](index.md#set-up-ldap-user-filter)? If one is not configured, this question can be ignored. If it is, then the - user must also pass through this filter to be allowed to sign-in. + user must also pass through this filter to be allowed to sign in. - Refer to our docs on [debugging the `user_filter`](#debug-ldap-user-filter). If the above are both okay, the next place to look for the problem is the logs themselves while reproducing the issue. -- Ask the user to sign-in and let it fail. +- Ask the user to sign in and let it fail. - [Look through the output](#gitlab-logs) for any errors or other messages about the sign-in. You may see one of the other error messages on this page, in which case that section can help resolve the issue. @@ -159,7 +159,7 @@ The user should now be able to sign in. #### Email has already been taken -A user tries to sign-in with the correct LDAP credentials, is denied access, +A user tries to sign in with the correct LDAP credentials, is denied access, and the [production.log](../../logs.md#productionlog) shows an error that looks like this: ```plaintext @@ -649,8 +649,7 @@ ldapsearch -D "cn=admin,dc=ldap-testing,dc=example,dc=com" \ Note that the `bind_dn`, `password`, `port`, `host`, and `base` are all identical to what's configured in the `gitlab.rb`. -Please see [the official -`ldapsearch` documentation](https://linux.die.net/man/1/ldapsearch) for more. +For more information, see the [official `ldapsearch` documentation](https://linux.die.net/man/1/ldapsearch). ### Using **AdFind** (Windows) @@ -675,15 +674,15 @@ adfind -h ad.example.org:636 -ssl -u "CN=GitLabSRV,CN=Users,DC=GitLab,DC=org" -u ### Rails console CAUTION: **Caution:** -Please note that it is very easy to create, read, modify, and destroy data on the -rails console, so please be sure to run commands exactly as listed. +It is very easy to create, read, modify, and destroy data with the rails +console. Be sure to run commands exactly as listed. The rails console is a valuable tool to help debug LDAP problems. It allows you to directly interact with the application by running commands and seeing how GitLab responds to them. -Please refer to [this guide](../../operations/rails_console.md#starting-a-rails-console-session) -for instructions on how to use the rails console. +For instructions about how to use the rails console, refer to this +[guide](../../operations/rails_console.md#starting-a-rails-console-session). #### Enable debug output diff --git a/doc/administration/auth/okta.md b/doc/administration/auth/okta.md index 7a55e127733..06b50be2647 100644 --- a/doc/administration/auth/okta.md +++ b/doc/administration/auth/okta.md @@ -14,7 +14,9 @@ The following documentation enables Okta as a SAML provider. ## Configure the Okta application -1. On Okta go to the admin section and choose to **Add an App**. +The following guidance is based on this Okta article, on adding a [SAML Application with an Okta Developer account](https://support.okta.com/help/s/article/Why-can-t-I-add-a-SAML-Application-with-an-Okta-Developer-account?language=en_US): + +1. On Okta admin section, make sure to select Classic UI view in the top left corner. From there, choose to **Add an App**. 1. When the app screen comes up you see another button to **Create an App** and choose SAML 2.0 on the next screen. 1. Now, very important, add a logo diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md index a696d0499a4..d2937d36a35 100644 --- a/doc/administration/auth/smartcard.md +++ b/doc/administration/auth/smartcard.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Manage +group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index 44270283308..4cb2c002015 100644 --- a/doc/administration/compliance.md +++ b/doc/administration/compliance.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Manage +group: Compliance info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/administration/consul.md b/doc/administration/consul.md index 4eed020c284..491251bc842 100644 --- a/doc/administration/consul.md +++ b/doc/administration/consul.md @@ -17,12 +17,9 @@ a service networking solution that you can manage by using `/etc/gitlab/gitlab.r ## Configure the Consul nodes -NOTE: **Important:** -Before proceeding, refer to the -[available reference architectures](reference_architectures/index.md#available-reference-architectures) -to find out how many Consul server nodes you should have. - -On **each** Consul server node perform the following: +After you review the [reference architecture](reference_architectures/index.md#available-reference-architectures) +documentation to determine the number of Consul server nodes you should have, +on _each_ Consul server node: 1. Follow the instructions to [install](https://about.gitlab.com/install/) GitLab by choosing your preferred platform, but do not supply the @@ -87,16 +84,15 @@ Consul nodes communicate using the raft protocol. If the current leader goes offline, there needs to be a leader election. A leader node must exist to facilitate synchronization across the cluster. If too many nodes go offline at the same time, the cluster will lose quorum and not elect a leader due to -[broken consensus](https://www.consul.io/docs/internals/consensus.html). +[broken consensus](https://www.consul.io/docs/architecture/consensus). Consult the [troubleshooting section](#troubleshooting-consul) if the cluster is not able to recover after the upgrade. The [outage recovery](#outage-recovery) may be of particular interest. -NOTE: **Note:** -GitLab uses Consul to store only transient data that is easily regenerated. If -the bundled Consul was not used by any process other than GitLab itself, then -[rebuilding the cluster from scratch](#recreate-from-scratch) is fine. +GitLab uses Consul to store only easily regenerated, transient data. If the +bundled Consul wasn't used by any process other than GitLab itself, you can +[rebuild the cluster from scratch](#recreate-from-scratch). ## Troubleshooting Consul diff --git a/doc/administration/database_load_balancing.md b/doc/administration/database_load_balancing.md index e88f88a0427..2b25ee4bab8 100644 --- a/doc/administration/database_load_balancing.md +++ b/doc/administration/database_load_balancing.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Enablement +group: Database info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/administration/feature_flags.md b/doc/administration/feature_flags.md index 4129677f134..2a5260a1342 100644 --- a/doc/administration/feature_flags.md +++ b/doc/administration/feature_flags.md @@ -36,8 +36,8 @@ error, it's very important that you [**provide feedback**](https://gitlab.com/gi as possible so we can improve or fix it while behind a flag. When you upgrade GitLab to an earlier version, the feature flag status may change. -NOTE: **Note:** -Mind that features deployed behind feature flags may not be ready for +CAUTION: **Caution:** +Features deployed behind feature flags may not be ready for production use. However, disabling features behind flags that were deployed enabled by default may also present a risk. If they're enabled, we recommend you leave them as-is. diff --git a/doc/administration/geo/disaster_recovery/bring_primary_back.md b/doc/administration/geo/disaster_recovery/bring_primary_back.md index 83081e2cef6..b73d3ba52a2 100644 --- a/doc/administration/geo/disaster_recovery/bring_primary_back.md +++ b/doc/administration/geo/disaster_recovery/bring_primary_back.md @@ -45,9 +45,12 @@ To bring the former **primary** node up to date: all the writes to this node](planned_failover.md#prevent-updates-to-the-primary-node) during this procedure. -1. [Setup database replication](../setup/database.md). Note that in this - case, **primary** node refers to the current **primary** node, and **secondary** node refers to the - former **primary** node. +1. [Set up database replication](../setup/database.md). In this case, the **secondary** node + refers to the former **primary** node. + 1. If [PgBouncer](../../postgresql/pgbouncer.md) was enabled on the **current secondary** node + (when it was a primary node) disable it by editing `/etc/gitlab/gitlab.rb` + and running `sudo gitlab-ctl reconfigure`. + 1. You can then set up database replication on the **secondary** node. If you have lost your original **primary** node, follow the [setup instructions](../setup/index.md) to set up a new **secondary** node. diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index 5876a8c36e6..1e9b430834c 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -133,6 +133,12 @@ Note the following when promoting a secondary: ``` 1. Promote the **secondary** node to the **primary** node. + DANGER: **Warning:** + In GitLab 13.2 and 13.3, promoting a secondary node to a primary while the + secondary is paused fails. Do not pause replication before promoting a + secondary. If the node is paused, be sure to resume before promoting. This + issue has been fixed in GitLab 13.4 and later. + CAUTION: **Caution:** If the secondary node [has been paused](../../geo/index.md#pausing-and-resuming-replication), this performs a point-in-time recovery to the last known state. @@ -167,8 +173,14 @@ conjunction with multiple servers, as it can only perform changes on a **secondary** with only a single machine. Instead, you must do this manually. +DANGER: **Warning:** +In GitLab 13.2 and 13.3, promoting a secondary node to a primary while the +secondary is paused fails. Do not pause replication before promoting a +secondary. If the node is paused, be sure to resume before promoting. This +issue has been fixed in GitLab 13.4 and later. + CAUTION: **Caution:** -If the secondary node [has been paused](../../geo/index.md#pausing-and-resuming-replication), this performs + If the secondary node [has been paused](../../geo/index.md#pausing-and-resuming-replication), this performs a point-in-time recovery to the last known state. Data that was created on the primary while the secondary was paused will be lost. diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md index c89b7929b13..3864445bbf4 100644 --- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md +++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md @@ -227,6 +227,12 @@ conjunction with multiple servers, as it can only perform changes on a **secondary** with only a single machine. Instead, you must do this manually. +DANGER: **Warning:** +In GitLab 13.2 and 13.3, promoting a secondary node to a primary while the +secondary is paused fails. Do not pause replication before promoting a +secondary. If the node is paused, be sure to resume before promoting. This +issue has been fixed in GitLab 13.4 and later. + CAUTION: **Caution:** If the secondary node [has been paused](../../../geo/index.md#pausing-and-resuming-replication), this performs a point-in-time recovery to the last known state. diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index 0bfdf1d2d65..02b907ae237 100644 --- a/doc/administration/geo/index.md +++ b/doc/administration/geo/index.md @@ -49,7 +49,7 @@ Geo provides: - Read-only **secondary** nodes: Maintain one **primary** GitLab node while still enabling read-only **secondary** nodes for each of your distributed teams. - Authentication system hooks: **Secondary** nodes receives all authentication data (like user accounts and logins) from the **primary** instance. -- An intuitive UI: **Secondary** nodes utilize the same web interface your team has grown accustomed to. In addition, there are visual notifications that block write operations and make it clear that a user is on a **secondary** node. +- An intuitive UI: **Secondary** nodes use the same web interface your team has grown accustomed to. In addition, there are visual notifications that block write operations and make it clear that a user is on a **secondary** node. ## How it works @@ -116,6 +116,7 @@ The following are required to run Geo: - [Ubuntu](https://ubuntu.com) 16.04+ - PostgreSQL 11+ with [Streaming Replication](https://wiki.postgresql.org/wiki/Streaming_Replication) - Git 2.9+ +- Git-lfs 2.4.2+ on the user side when using LFS - All nodes must run the same GitLab version. Additionally, check GitLab's [minimum requirements](../../install/requirements.md), @@ -195,6 +196,12 @@ For information on how to update your Geo nodes to the latest GitLab version, se > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35913) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +DANGER: **Warning:** +In GitLab 13.2 and 13.3, promoting a secondary node to a primary while the +secondary is paused fails. Do not pause replication before promoting a +secondary. If the node is paused, be sure to resume before promoting. This +issue has been fixed in GitLab 13.4 and later. + CAUTION: **Caution:** Pausing and resuming of replication is currently only supported for Geo installations using an Omnibus GitLab-managed database. External databases are currently not supported. diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index 8c818bcfbe2..43a422c4bc3 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.md @@ -229,19 +229,10 @@ replicating missing data from the **primary** node in a process known as **backf Meanwhile, the **primary** node will start to notify each **secondary** node of any changes, so that the **secondary** node can act on those notifications immediately. -Make sure the **secondary** node is running and accessible. -You can login to the **secondary** node with the same credentials as used for the **primary** node. +Be sure the _secondary_ node is running and accessible. You can sign in to the +_secondary_ node with the same credentials as were used with the _primary_ node. -### Step 4. Enabling Hashed Storage - -Using Hashed Storage significantly improves Geo replication. Project and group -renames no longer require synchronization between nodes. - -1. Visit the **primary** node's **Admin Area > Settings > Repository** - (`/admin/application_settings/repository`) in your browser. -1. In the **Repository storage** section, check **Use hashed storage paths for newly created and renamed projects**. - -### Step 5. (Optional) Configuring the **secondary** node to trust the **primary** node +### Step 4. (Optional) Configuring the **secondary** node to trust the **primary** node You can safely skip this step if your **primary** node uses a CA-issued HTTPS certificate. @@ -251,21 +242,23 @@ certificate from the **primary** node and follow [these instructions](https://docs.gitlab.com/omnibus/settings/ssl.html) on the **secondary** node. -### Step 6. Enable Git access over HTTP/HTTPS +### Step 5. Enable Git access over HTTP/HTTPS Geo synchronizes repositories over HTTP/HTTPS, and therefore requires this clone -method to be enabled. Navigate to **Admin Area > Settings** -(`/admin/application_settings/general`) on the **primary** node, and set -`Enabled Git access protocols` to `Both SSH and HTTP(S)` or `Only HTTP(S)`. +method to be enabled. This is enabled by default, but if converting an existing node to Geo it should be checked: + +1. Navigate to **Admin Area > Settings** (`/admin/application_settings/general`) on the **primary** node. +1. Expand "Visibility and access controls". +1. Ensure "Enabled Git access protocols" is set to either "Both SSH and HTTP(S)" or "Only HTTP(S)". -### Step 7. Verify proper functioning of the **secondary** node +### Step 6. Verify proper functioning of the **secondary** node Your **secondary** node is now configured! -You can login to the **secondary** node with the same credentials you used for the -**primary** node. Visit the **secondary** node's **Admin Area > Geo** -(`/admin/geo/nodes`) in your browser to check if it's correctly identified as a -**secondary** Geo node and if Geo is enabled. +You can sign in to the _secondary_ node with the same credentials you used with +the _primary_ node. Visit the _secondary_ node's **Admin Area > Geo** +(`/admin/geo/nodes`) in your browser to determine if it's correctly identified +as a _secondary_ Geo node, and if Geo is enabled. The initial replication, or 'backfill', will probably still be in progress. You can monitor the synchronization process on each Geo node from the **primary** diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index d1fa2d503be..9e896f2c07c 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -127,8 +127,11 @@ and verification status on a **secondary** node. You can keep track of the progress to implement the missing items in these epics/issues: -- [Unreplicated Data Types](https://gitlab.com/groups/gitlab-org/-/epics/893) -- [Verify all replicated data](https://gitlab.com/groups/gitlab-org/-/epics/1430) +- [Geo: Build a scalable, self-service Geo replication and verification framework](https://gitlab.com/groups/gitlab-org/-/epics/2161) +- [Geo: Improve the self-service Geo replication framework](https://gitlab.com/groups/gitlab-org/-/epics/3761) +- [Geo: Move existing blobs to framework](https://gitlab.com/groups/gitlab-org/-/epics/3588) +- [Geo: Add unreplicated data types](https://gitlab.com/groups/gitlab-org/-/epics/893) +- [Geo: Support GitLab Pages](https://gitlab.com/groups/gitlab-org/-/epics/589) ### Replicated data types behind a feature flag @@ -157,18 +160,19 @@ To enable, such as for package file replication: Feature.enable(:geo_package_file_replication) ``` -DANGER: **Danger:** +DANGER: **Warning:** Features not on this list, or with **No** in the **Replicated** column, are not replicated on the **secondary** node. Failing over without manually replicating data from those features will cause the data to be **lost**. If you wish to use those features on a **secondary** node, or to execute a failover successfully, you must replicate their data using some other means. -| Feature | Replicated (added in GitLab version) | Verified (added in GitLab version) | Object Storage replication (please see [Geo with Object Storage](object_storage.md)) | Notes | +| Feature | Replicated (added in GitLab version) | Verified (added in GitLab version) | Object Storage replication (see [Geo with Object Storage](object_storage.md)) | Notes | |:---------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------|:----------------------------------------------------------|:-------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Application data in PostgreSQL](../../postgresql/index.md) | **Yes** (10.2) | **Yes** (10.2) | No | | | [Project repository](../../..//user/project/repository/) | **Yes** (10.2) | **Yes** (10.7) | No | | -| [Project wiki repository](../../../user/project/wiki/) | **Yes** (10.2) | **Yes** (10.7) | No | | +| [Project wiki repository](../../../user/project/wiki/) | **Yes** (10.2) | **Yes** (10.7) | No | +| [Group wiki repository](../../../user/group/index.md#group-wikis) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/208147) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/208147) | No | | | [Uploads](../../uploads.md) | **Yes** (10.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | No | Verified only on transfer or manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them. | | [LFS objects](../../lfs/index.md) | **Yes** (10.2) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8922) | Via Object Storage provider if supported. Native Geo support (Beta). | Verified only on transfer or manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them. 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). | | [Personal snippets](../../../user/snippets.md#personal-snippets) | **Yes** (10.2) | **Yes** (10.2) | No | | @@ -176,7 +180,7 @@ successfully, you must replicate their data using some other means. | [CI job artifacts (other than Job Logs)](../../../ci/pipelines/job_artifacts.md) | **Yes** (10.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8923) | Via Object Storage provider if supported. Native Geo support (Beta) . | Verified only manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them | | [Job logs](../../job_logs.md) | **Yes** (10.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8923) | Via Object Storage provider if supported. Native Geo support (Beta). | Verified only on transfer or manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them | | [Object pools for forked project deduplication](../../../development/git_object_deduplication.md) | **Yes** | No | No | | -| [Container Registry](../../packages/container_registry.md) | **Yes** (12.3) | No | No | Disabled by default. See [instructions](./docker_registry.md) to enable. | +| [Container Registry](../../packages/container_registry.md) | **Yes** (12.3) | No | No | Disabled by default. See [instructions](docker_registry.md) to enable. | | [Content in object storage (beta)](object_storage.md) | **Yes** (12.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/13845) | No | | | [Project designs repository](../../../user/project/issues/design_management.md) | **Yes** (12.7) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/32467) | Via Object Storage provider if supported. Native Geo support (Beta). | | | [NPM Registry](../../../user/packages/npm_registry/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | @@ -187,7 +191,7 @@ successfully, you must replicate their data using some other means. | [Composer Repository](../../../user/packages/composer_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | | [Generic packages](../../../user/packages/generic_packages/index.md) | **Yes** (13.5) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | | [Versioned Terraform State](../../terraform_state.md) | **Yes** (13.5) | No | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_terraform_state_version_replication`, enabled by default | -| [External merge request diffs](../../merge_request_diffs.md) | **Yes** (13.5) | No | Behind feature flag `geo_merge_request_diff_replication`, enabled by default | | +| [External merge request diffs](../../merge_request_diffs.md) | **Yes** (13.5) | No | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_merge_request_diff_replication`, enabled by default | | [Versioned snippets](../../../user/snippets.md#versioned-snippets) | [No](https://gitlab.com/groups/gitlab-org/-/epics/2809) | [No](https://gitlab.com/groups/gitlab-org/-/epics/2810) | No | | | [Server-side Git hooks](../../server_hooks.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1867) | No | No | | | [Elasticsearch integration](../../../integration/elasticsearch.md) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/1186) | No | No | | diff --git a/doc/administration/geo/replication/disable_geo.md b/doc/administration/geo/replication/disable_geo.md index 14a11d9c1e3..dabf4499f9d 100644 --- a/doc/administration/geo/replication/disable_geo.md +++ b/doc/administration/geo/replication/disable_geo.md @@ -25,7 +25,7 @@ To disable Geo, follow these steps: ## Remove all secondary Geo nodes To disable Geo, you need to first remove all your secondary Geo nodes, which means replication will not happen -anymore on these nodes. You can follow our docs to [remove your secondary Geo nodes](./remove_geo_node.md). +anymore on these nodes. You can follow our docs to [remove your secondary Geo nodes](remove_geo_node.md). If the current node that you want to keep using is a secondary node, you need to first promote it to primary. You can use our steps on [how to promote a secondary node](../disaster_recovery/#step-3-promoting-a-secondary-node) diff --git a/doc/administration/geo/replication/location_aware_git_url.md b/doc/administration/geo/replication/location_aware_git_url.md index ddcdea736e7..82fda8b0fc2 100644 --- a/doc/administration/geo/replication/location_aware_git_url.md +++ b/doc/administration/geo/replication/location_aware_git_url.md @@ -43,8 +43,8 @@ In any case, you require: - A working GitLab **secondary** node. - A Route53 Hosted Zone managing your domain. -If you have not yet setup a Geo **primary** node and **secondary** node, please consult -[the Geo setup instructions](../index.md#setup-instructions). +If you haven't yet set up a Geo _primary_ node and _secondary_ node, see the +[Geo setup instructions](../index.md#setup-instructions). ## Create a traffic policy diff --git a/doc/administration/geo/replication/object_storage.md b/doc/administration/geo/replication/object_storage.md index 642d31f6298..3f5ba1939b8 100644 --- a/doc/administration/geo/replication/object_storage.md +++ b/doc/administration/geo/replication/object_storage.md @@ -72,7 +72,7 @@ If you are using Google Cloud Storage, consider using Or you can use the [Storage Transfer Service](https://cloud.google.com/storage-transfer/docs/), although this only supports daily synchronization. -For manual synchronization, or scheduled by `cron`, please have a look at: +For manual synchronization, or scheduled by `cron`, see: - [`s3cmd sync`](https://s3tools.org/s3cmd-sync) - [`gsutil rsync`](https://cloud.google.com/storage/docs/gsutil/commands/rsync) diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index b62c5c6f460..15e3d3ff0a8 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -720,7 +720,8 @@ GitLab cannot find or doesn't have permission to access the `database_geo.yml` c In an Omnibus GitLab installation, the file should be in `/var/opt/gitlab/gitlab-rails/etc`. If it doesn't exist or inadvertent changes have been made to it, run `sudo gitlab-ctl reconfigure` to restore it to its correct state. -If this path is mounted on a remote volume, please check your volume configuration and that it has correct permissions. +If this path is mounted on a remote volume, ensure your volume configuration +has the correct permissions. ### An existing tracking database cannot be reused @@ -782,3 +783,13 @@ To resolve this issue: using IPv6 to send its status to the **primary** node. If it is, add an entry to the **primary** node using IPv4 in the `/etc/hosts` file. Alternatively, you should [enable IPv6 on the **primary** node](https://docs.gitlab.com/omnibus/settings/nginx.html#setting-the-nginx-listen-address-or-addresses). + +## Fixing client errors + +### Authorization errors from LFS HTTP(s) client requests + +You may have problems if you're running a version of [Git LFS](https://git-lfs.github.com/) before 2.4.2. +As noted in [this authentication issue](https://github.com/git-lfs/git-lfs/issues/3025), +requests redirected from the secondary to the primary node do not properly send the +Authorization header. This may result in either an infinite `Authorization <-> Redirect` +loop, or Authorization errors. diff --git a/doc/administration/geo/replication/updating_the_geo_nodes.md b/doc/administration/geo/replication/updating_the_geo_nodes.md index 55ddccb1d98..af59e45250c 100644 --- a/doc/administration/geo/replication/updating_the_geo_nodes.md +++ b/doc/administration/geo/replication/updating_the_geo_nodes.md @@ -8,7 +8,9 @@ type: howto # Updating the Geo nodes **(PREMIUM ONLY)** CAUTION: **Warning:** -Please ensure you read these sections carefully before updating your Geo nodes! Not following version-specific update steps may result in unexpected downtime. Please [contact support](https://about.gitlab.com/support/#contact-support) if you have any specific questions. +Read these sections carefully before updating your Geo nodes. Not following +version-specific update steps may result in unexpected downtime. If you have +any specific questions, [contact Support](https://about.gitlab.com/support/#contact-support). Updating Geo nodes involves performing: @@ -47,4 +49,4 @@ everything is working correctly: 1. Test the data replication by pushing code to the **primary** node and see if it is received by **secondary** nodes. -If you encounter any issues, please consult the [Geo troubleshooting guide](troubleshooting.md). +If you encounter any issues, see the [Geo troubleshooting guide](troubleshooting.md). diff --git a/doc/administration/geo/replication/version_specific_updates.md b/doc/administration/geo/replication/version_specific_updates.md index 85c869eff92..9ea5283812e 100644 --- a/doc/administration/geo/replication/version_specific_updates.md +++ b/doc/administration/geo/replication/version_specific_updates.md @@ -24,34 +24,41 @@ DROP SERVER gitlab_secondary CASCADE; DROP EXTENSION IF EXISTS postgres_fdw; ``` +DANGER: **Warning:** +In GitLab 13.3, promoting a secondary node to a primary while the secondary is +paused fails. Do not pause replication before promoting a secondary. If the +node is paused, be sure to resume before promoting. To avoid this issue, +upgrade to GitLab 13.4 or later. + +## Updating to GitLab 13.2 + +In GitLab 13.2, promoting a secondary node to a primary while the secondary is paused fails. **Do not pause replication before promoting a secondary.** If the node is paused, please resume before promoting. To avoid this issue, upgrade to GitLab 13.4 or later. + ## Updating to GitLab 13.0 Upgrading to GitLab 13.0 requires GitLab 12.10 to already be using PostgreSQL -version 11. Please see -[the Omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) -for the recommended procedure. +version 11. For the recommended procedure, see the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). ## Updating to GitLab 12.10 -GitLab 12.10 does not attempt to automatically update the embedded PostgreSQL -server when using Geo, because the PostgreSQL upgrade requires downtime on -secondaries while reinitializing streaming replication. It must be upgraded -manually. Please see -[the Omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) -for the recommended procedure. +GitLab 12.10 doesn't attempt to update 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 the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). ## Updating to GitLab 12.9 CAUTION: **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. Please upgrade to GitLab 12.9.4 or later. +The issue is fixed in GitLab 12.9.4. Upgrade to GitLab 12.9.4 or later. By default, GitLab 12.9 will attempt to automatically update the embedded PostgreSQL server to 10.12 from 9.6, which requires downtime on secondaries -while reinitializing streaming replication. Please see -[the Omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) -for the recommended procedure. +while reinitializing streaming replication. For the recommended procedure, see the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). This can be temporarily disabled by running the following before updating: @@ -63,9 +70,8 @@ sudo touch /etc/gitlab/disable-postgresql-upgrade By default, GitLab 12.8 will attempt to automatically update the embedded PostgreSQL server to 10.12 from 9.6, which requires downtime on secondaries -while reinitializing streaming replication. Please see -[the Omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) -for the recommended procedure. +while reinitializing streaming replication. For the recommended procedure, see +the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). This can be temporarily disabled by running the following before updating: @@ -75,7 +81,7 @@ sudo touch /etc/gitlab/disable-postgresql-upgrade ## Updating to GitLab 12.7 -DANGER: **Danger:** +DANGER: **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 @@ -84,10 +90,9 @@ fix](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24021) was shipped in 12.7.5. By default, GitLab 12.7 will attempt to automatically update the embedded -PostgreSQL server to 10.9 from 9.6, which requires downtime on secondaries while -reinitializing streaming replication. Please see -[the Omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) -for the recommended procedure. +PostgreSQL server to 10.9 from 9.6, which requires downtime on secondaries +while reinitializing streaming replication. For the recommended procedure, see +the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). This can be temporarily disabled by running the following before updating: @@ -98,10 +103,9 @@ sudo touch /etc/gitlab/disable-postgresql-upgrade ## Updating to GitLab 12.6 By default, GitLab 12.6 will attempt to automatically update the embedded -PostgreSQL server to 10.9 from 9.6, which requires downtime on secondaries while -reinitializing streaming replication. Please see -[the Omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) -for the recommended procedure. +PostgreSQL server to 10.9 from 9.6, which requires downtime on secondaries +while reinitializing streaming replication. For the recommended procedure, see +the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). This can be temporarily disabled by running the following before updating: @@ -112,10 +116,9 @@ sudo touch /etc/gitlab/disable-postgresql-upgrade ## Updating to GitLab 12.5 By default, GitLab 12.5 will attempt to automatically update the embedded -PostgreSQL server to 10.9 from 9.6, which requires downtime on secondaries while -reinitializing streaming replication. Please see -[the Omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) -for the recommended procedure. +PostgreSQL server to 10.9 from 9.6, which requires downtime on secondaries +while reinitializing streaming replication. For the recommended procedure, see +the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). This can be temporarily disabled by running the following before updating: @@ -126,10 +129,9 @@ sudo touch /etc/gitlab/disable-postgresql-upgrade ## Updating to GitLab 12.4 By default, GitLab 12.4 will attempt to automatically update the embedded -PostgreSQL server to 10.9 from 9.6, which requires downtime on secondaries while -reinitializing streaming replication. Please see -[the Omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) -for the recommended procedure. +PostgreSQL server to 10.9 from 9.6, which requires downtime on secondaries +while reinitializing streaming replication. For the recommended procedure, see +the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). This can be temporarily disabled by running the following before updating: @@ -139,35 +141,31 @@ sudo touch /etc/gitlab/disable-postgresql-upgrade ## Updating to GitLab 12.3 -DANGER: **Danger:** +DANGER: **Warning:** If the existing PostgreSQL server version is 9.6.x, it is recommended to -upgrade to GitLab 12.4 or newer. By default, GitLab 12.3 will attempt to -automatically update the embedded PostgreSQL server to 10.9 from 9.6. In -certain circumstances, it will fail. Please see -[the Omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) -for more information. +upgrade to GitLab 12.4 or later. By default, GitLab 12.3 attempts to update the +embedded PostgreSQL server from 9.6 to 10.9. In certain circumstances, it will +fail. For more information, see the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). -Additionally, if the PostgreSQL upgrade does not fail, a successful upgrade -requires downtime on secondaries while reinitializing streaming replication. -Please see -[the Omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) -for the recommended procedure. +Additionally, if the PostgreSQL upgrade doesn't fail, a successful upgrade +requires downtime for secondaries while reinitializing streaming replication. +For the recommended procedure, see the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). ## Updating to GitLab 12.2 -DANGER: **Danger:** +DANGER: **Warning:** If the existing PostgreSQL server version is 9.6.x, it is recommended to -upgrade to GitLab 12.4 or newer. By default, GitLab 12.2 will attempt to -automatically update the embedded PostgreSQL server to 10.9 from 9.6. In -certain circumstances, it will fail. Please see -[the Omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) -for more information. +upgrade to GitLab 12.4 or later. By default, GitLab 12.2 attempts to update the +embedded PostgreSQL server from 9.6 to 10.9. In certain circumstances, it will +fail. For more information, see the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). Additionally, if the PostgreSQL upgrade does not fail, a successful upgrade -requires downtime on secondaries while reinitializing streaming replication. -Please see -[the Omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) -for the recommended procedure. +requires downtime for secondaries while reinitializing streaming replication. +For the recommended procedure, see the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). GitLab 12.2 includes the following minor PostgreSQL updates: @@ -187,33 +185,31 @@ The restart avoids a version mismatch when PostgreSQL tries to load the FDW exte ## Updating to GitLab 12.1 -DANGER: **Danger:** +DANGER: **Warning:** If the existing PostgreSQL server version is 9.6.x, it is recommended to -upgrade to GitLab 12.4 or newer. By default, GitLab 12.1 will attempt to -automatically update the embedded PostgreSQL server to 10.9 from 9.6. In -certain circumstances, it will fail. Please see -[the Omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) -for more information. +upgrade to GitLab 12.4 or later. By default, GitLab 12.1 attempts to update the +embedded PostgreSQL server from 9.6 to 10.9. In certain circumstances, it will +fail. For more information, see the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). -Additionally, if the PostgreSQL upgrade does not fail, a successful upgrade -requires downtime on secondaries while reinitializing streaming replication. -Please see -[the Omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) -for the recommended procedure. +Additionally, if the PostgreSQL upgrade doesn't fail, a successful upgrade +requires downtime for secondaries while reinitializing streaming replication. +For the recommended procedure, see the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). ## Updating to GitLab 12.0 CAUTION: **Warning:** -This version is affected by [a bug that results in new LFS objects not being replicated to -Geo secondary nodes](https://gitlab.com/gitlab-org/gitlab/-/issues/32696). The issue is fixed -in GitLab 12.1. Please upgrade to GitLab 12.1 or later. +This version is affected by a [bug that results in new LFS objects not being +replicated to Geo secondary nodes](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. ## Updating to GitLab 11.11 CAUTION: **Warning:** -This version is affected by [a bug that results in new LFS objects not being replicated to -Geo secondary nodes](https://gitlab.com/gitlab-org/gitlab/-/issues/32696). The issue is fixed -in GitLab 12.1. Please upgrade to GitLab 12.1 or later. +This version is affected by a [bug that results in new LFS objects not being +replicated to Geo secondary nodes](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. ## Updating to GitLab 10.8 @@ -329,7 +325,7 @@ In GitLab 10.2, synchronizing secondaries over SSH was deprecated. In 10.3, support is removed entirely. All installations will switch to the HTTP/HTTPS cloning method instead. Before updating, ensure that all your Geo nodes are configured to use this method and that it works for your installation. In -particular, ensure that [Git access over HTTP/HTTPS is enabled](configuration.md#step-6-enable-git-access-over-httphttps). +particular, ensure that [Git access over HTTP/HTTPS is enabled](configuration.md#step-5-enable-git-access-over-httphttps). Synchronizing repositories over the public Internet using HTTP is insecure, so you should ensure that you have HTTPS configured before updating. Note that @@ -433,7 +429,7 @@ required because replication slots are used by default. However, if you started with GitLab 9.3 and updated later, you should still follow the instructions below. -When in doubt, it does not hurt to do a resync. The easiest way to do this in +When in doubt, it doesn't hurt to do a resync. The easiest way to do this in Omnibus is the following: 1. Make sure you have Omnibus GitLab on the **primary** server. diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md index 09b9c71aeb7..24e55d26997 100644 --- a/doc/administration/geo/setup/database.md +++ b/doc/administration/geo/setup/database.md @@ -474,6 +474,81 @@ high-availability configuration with a cluster of nodes supporting a Geo **primary** node and another cluster of nodes supporting a Geo **secondary** node. For more information, see [High Availability with Omnibus GitLab](../../postgresql/replication_and_failover.md). +## Patroni support + +Support for Patroni is intended to replace `repmgr` as a +[highly availabile PostgreSQL solution](../../postgresql/replication_and_failover.md) +on the primary node, but it can also be used for PostgreSQL HA on a secondary +node. + +Starting with GitLab 13.5, Patroni is available for _experimental_ use with Geo +primary and secondary nodes. Due to its experimental nature, Patroni support is +subject to change without notice. + +This experimental implementation has the following limitations: + +- Whenever a new Leader is elected, the PgBouncer instance must be reconfigured + to point to the new Leader. +- Whenever a new Leader is elected on the primary node, the Standby Leader on + the secondary needs to be reconfigured to point to the new Leader. +- Whenever `gitlab-ctl reconfigure` runs on a Patroni Leader instance, there's a + chance the node will be demoted due to the required short-time restart. To + avoid this, you can pause auto-failover by running `gitlab-ctl patroni pause`. + After a reconfigure, it unpauses on its own. + +For instructions about how to set up Patroni on the primary node, see the +[PostgreSQL replication and failover with Omnibus GitLab](../../postgresql/replication_and_failover.md#patroni) page. + +A production-ready and secure setup requires at least three Patroni instances on +the primary, and a similar configuration on the secondary nodes. Be sure to use +password credentials and other database best practices. + +Similar to `repmgr`, using Patroni on a secondary node is optional. + +To set up database replication with Patroni on a secondary node, configure a +_permanent replication slot_ on the primary node's Patroni cluster, and ensure +password authentication is used. + +On Patroni instances for the primary node, add the following to the +`/etc/gitlab/gitlab.rb` file: + +```ruby +# You need one entry for each secondary, with a unique name following PostgreSQL slot_name constraints: +# +# Configuration syntax will be: 'unique_slotname' => { 'type' => 'physical' }, +# We don't support setting a permanent replication slot for logical replication type +patroni['replication_slots'] = { + 'geo_secondary' => { 'type' => 'physical' } +} + +postgresql['md5_auth_cidr_addresses'] = [ + 'PATRONI_PRIMARY1_IP/32', 'PATRONI_PRIMARY2_IP/32', 'PATRONI_PRIMARY3_IP/32', 'PATRONI_PRIMARY_PGBOUNCER/32', + 'PATRONI_SECONDARY1_IP/32', 'PATRONI_SECONDARY2_IP/32', 'PATRONI_SECONDARY3_IP/32' # we list all secondary instances as they can all become a Standby Leader + # any other instance that needs access to the database as per documentation +] + +postgresql['pgbouncer_user_password'] = 'PGBOUNCER_PASSWORD_HASH' +postgresql['sql_replication_password'] = 'POSTGRESQL_REPLICATION_PASSWORD_HASH' +postgresql['sql_user_password'] = 'POSTGRESQL_PASSWORD_HASH' +``` + +On Patroni instances for the secondary node, add the following to the +`/etc/gitlab/gitlab.rb` file: + +```ruby +postgresql['md5_auth_cidr_addresses'] = [ + 'PATRONI_SECONDARY1_IP/32', 'PATRONI_SECONDARY2_IP/32', 'PATRONI_SECONDARY3_IP/32', 'PATRONI_SECONDARY_PGBOUNCER/32', + # any other instance that needs access to the database as per documentation +] + +patroni['enable'] = true +patroni['standby_cluster']['enable'] = true +patroni['standby_cluster']['host'] = 'PATRONI_PRIMARY_LEADER_IP' # this needs to be changed anytime the primary Leader changes +patroni['standby_cluster']['port'] = 5432 +patroni['standby_cluster']['primary_slot_name'] = 'geo_secondary' # or the unique replication slot name you setup before +patroni['replication_password'] = 'PLAIN_TEXT_POSTGRESQL_REPLICATION_PASSWORD' +``` + ## Troubleshooting Read the [troubleshooting document](../replication/troubleshooting.md). diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 59a6f2596da..0d9c761e078 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -121,7 +121,7 @@ The following list depicts the network architecture of Gitaly: - Authentication is done through a static token which is shared among the Gitaly and GitLab Rails nodes. -DANGER: **Danger:** +DANGER: **Warning:** Gitaly servers must not be exposed to the public internet as Gitaly's network traffic is unencrypted by default. The use of firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#enable-tls-support). @@ -373,7 +373,7 @@ As the final step, you must update Gitaly clients to switch from using local Git the Gitaly servers you just configured. This can be risky because anything that prevents your Gitaly clients from reaching the Gitaly -servers will cause all Gitaly requests to fail. For example, any sort of network, firewall, or name +servers causes all Gitaly requests to fail. For example, any sort of network, firewall, or name resolution problems. Additionally, you must [disable Rugged](../nfs.md#improving-nfs-performance-with-gitlab) @@ -450,7 +450,7 @@ server (with `gitaly_address`) unless you setup with special When you tail the Gitaly logs on your Gitaly server, you should see requests coming in. One sure way to trigger a Gitaly request is to clone a repository from GitLab over HTTP or HTTPS. -DANGER: **Danger:** +DANGER: **Warning:** If you have [server hooks](../server_hooks.md) configured, either per repository or globally, you must move these to the Gitaly servers. If you have multiple Gitaly servers, copy your server hooks to all Gitaly servers. diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index bd075e86a15..20dce6d68df 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -42,6 +42,8 @@ a mail server feature where any email to `user+arbitrary_tag@example.com` will e in the mailbox for `user@example.com` . It is supported by providers such as Gmail, Google Apps, Yahoo! Mail, Outlook.com, and iCloud, as well as the [Postfix mail server](reply_by_email_postfix_setup.md), which you can run on-premises. +Microsoft Exchange Server [does not support sub-addressing](#microsoft-exchange-server), +and Microsoft Office 365 [does not support sub-addressing by default](#microsoft-office-365) TIP: **Tip:** If your provider or server supports email sub-addressing, we recommend using it. @@ -326,11 +328,11 @@ incoming_email: #### Microsoft Exchange Server -Example configurations for Microsoft Exchange Server with IMAP enabled. Since +Example configurations for Microsoft Exchange Server with IMAP enabled. Because Exchange does not support sub-addressing, only two options exist: -- Catch-all mailbox (recommended for Exchange-only) -- Dedicated email address (supports Reply by Email only) +- [Catch-all mailbox](#catch-all-mailbox) (recommended for Exchange-only) +- [Dedicated email address](#dedicated-email-address) (supports Reply by Email only) ##### Catch-all mailbox @@ -417,7 +419,8 @@ Example for source installs: incoming_email: enabled: true - # Exchange does not support sub-addressing, and we're not using a catch-all mailbox so %{key} is not used here + # Exchange does not support sub-addressing, + # and we're not using a catch-all mailbox so %{key} is not used here address: "incoming@exchange.example.com" # Email account username @@ -433,3 +436,180 @@ incoming_email: # Whether the IMAP server uses SSL ssl: true ``` + +#### Microsoft Office 365 + +Example configurations for Microsoft Office 365 with IMAP enabled. + +##### Sub-addressing mailbox + +NOTE: **Note:** +As of September 2020 sub-addressing support +[has been added to Office 365](https://office365.uservoice.com/forums/273493-office-365-admin/suggestions/18612754-support-for-dynamic-email-aliases-in-office-36). This feature is not +enabled by default, and must be enabled through PowerShell. + +This series of PowerShell commands enables [sub-addressing](#email-sub-addressing) +at the organization level in Office 365. This allows all mailboxes in the organization +to receive sub-addressed mail: + +NOTE: **Note:** +This series of commands will enable sub-addressing at the organization +level in Office 365. This will allow all mailboxes in the organization +to receive sub-addressed mail. + +```powershell +Set-ExecutionPolicy RemoteSigned -Scope CurrentUser + +$UserCredential = Get-Credential + +$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection + +Import-PSSession $Session -DisableNameChecking + +Set-OrganizationConfig -AllowPlusAddressInRecipients $true +``` + +This example for Omnibus GitLab assumes the mailbox `incoming@office365.example.com`: + +```ruby +gitlab_rails['incoming_email_enabled'] = true + +# The email address including the `%{key}` placeholder that will be replaced +# to reference the item being replied to. The placeholder can be omitted, but if +# present, it must appear in the "user" part of the address (before the `@`). +gitlab_rails['incoming_email_address'] = "incoming+%{key}@office365.example.com" + +# Email account username +# Typically this is the userPrincipalName (UPN) +gitlab_rails['incoming_email_email'] = "incoming@office365.example.com" +# Email account password +gitlab_rails['incoming_email_password'] = "[REDACTED]" + +# IMAP server host +gitlab_rails['incoming_email_host'] = "outlook.office365.com" +# IMAP server port +gitlab_rails['incoming_email_port'] = 993 +# Whether the IMAP server uses SSL +gitlab_rails['incoming_email_ssl'] = true +``` + +This example for source installs assumes the mailbox `incoming@office365.example.com`: + +```yaml +incoming_email: + enabled: true + + # The email address including the `%{key}` placeholder that will be replaced + # to reference the item being replied to. The placeholder can be omitted, but + # if present, it must appear in the "user" part of the address (before the `@`). + address: "incoming+%{key}@office365.example.comm" + + # Email account username + # Typically this is the userPrincipalName (UPN) + user: "incoming@office365.example.comm" + # Email account password + password: "[REDACTED]" + + # IMAP server host + host: "outlook.office365.com" + # IMAP server port + port: 993 + # Whether the IMAP server uses SSL + ssl: true +``` + +##### Catch-all mailbox + +This example for Omnibus installs assumes the catch-all mailbox `incoming@office365.example.com`: + +```ruby +gitlab_rails['incoming_email_enabled'] = true + +# The email address including the `%{key}` placeholder that will be replaced to +# reference the item being replied to. The placeholder can be omitted, but if present, +# it must appear in the "user" part of the address (before the `@`). +gitlab_rails['incoming_email_address'] = "incoming-%{key}@office365.example.com" + +# Email account username +# Typically this is the userPrincipalName (UPN) +gitlab_rails['incoming_email_email'] = "incoming@office365.example.com" +# Email account password +gitlab_rails['incoming_email_password'] = "[REDACTED]" + +# IMAP server host +gitlab_rails['incoming_email_host'] = "outlook.office365.com" +# IMAP server port +gitlab_rails['incoming_email_port'] = 993 +# Whether the IMAP server uses SSL +gitlab_rails['incoming_email_ssl'] = true +``` + +This example for source installs assumes the catch-all mailbox `incoming@office365.example.com`: + +```yaml +incoming_email: + enabled: true + + # The email address including the `%{key}` placeholder that will be replaced + # to reference the item being replied to. The placeholder can be omitted, but + # if present, it must appear in the "user" part of the address (before the `@`). + address: "incoming-%{key}@office365.example.com" + + # Email account username + # Typically this is the userPrincipalName (UPN) + user: "incoming@ad-domain.example.com" + # Email account password + password: "[REDACTED]" + + # IMAP server host + host: "outlook.office365.com" + # IMAP server port + port: 993 + # Whether the IMAP server uses SSL + ssl: true +``` + +##### Dedicated email address + +This example for Omnibus installs assumes the dedicated email address `incoming@office365.example.com`: + +```ruby +gitlab_rails['incoming_email_enabled'] = true + +gitlab_rails['incoming_email_address'] = "incoming@office365.example.com" + +# Email account username +# Typically this is the userPrincipalName (UPN) +gitlab_rails['incoming_email_email'] = "incoming@office365.example.com" +# Email account password +gitlab_rails['incoming_email_password'] = "[REDACTED]" + +# IMAP server host +gitlab_rails['incoming_email_host'] = "outlook.office365.com" +# IMAP server port +gitlab_rails['incoming_email_port'] = 993 +# Whether the IMAP server uses SSL +gitlab_rails['incoming_email_ssl'] = true +``` + +This example for source installs assumes the dedicated email address `incoming@office365.example.com`: + +```yaml +incoming_email: + enabled: true + + address: "incoming@office365.example.com" + + # Email account username + # Typically this is the userPrincipalName (UPN) + user: "incoming@office365.example.com" + # Email account password + password: "[REDACTED]" + + # IMAP server host + host: "outlook.office365.com" + # IMAP server port + port: 993 + # Whether the IMAP server uses SSL + ssl: true +``` diff --git a/doc/administration/index.md b/doc/administration/index.md index 07aa3b50bc6..0aa94b86371 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" description: 'Learn how to install, configure, update, and maintain your GitLab instance.' --- @@ -143,7 +143,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Container Registry](packages/container_registry.md): Configure Container Registry with GitLab. - [Package Registry](packages/index.md): Enable GitLab to act as an NPM Registry and a Maven Repository. -- [Dependency Proxy](packages/dependency_proxy.md): Configure the Dependency Proxy, a local proxy for frequently used upstream images/packages. **(PREMIUM ONLY)** +- [Dependency Proxy](packages/dependency_proxy.md): Configure the Dependency Proxy, a local proxy for frequently used upstream images/packages. ### Repository settings diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index cb37be8d9dd..ec56a59fdc2 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.md @@ -179,7 +179,6 @@ Plan.default.actual_limits.update!(project_hooks: 100) Plan.default.actual_limits.update!(group_hooks: 100) ``` -NOTE: **Note:** Set the limit to `0` to disable it. ## Incoming emails from auto-responders @@ -217,7 +216,6 @@ Plan.default.actual_limits.update!(offset_pagination_limit: 10000) - **Default offset pagination limit:** 50000 -NOTE: **Note:** Set the limit to `0` to disable it. ## CI/CD limits @@ -250,7 +248,6 @@ To set this limit on a self-managed installation, run the following in the Plan.default.actual_limits.update!(ci_active_jobs: 500) ``` -NOTE: **Note:** Set the limit to `0` to disable it. ### Number of CI/CD subscriptions to a project @@ -273,7 +270,6 @@ To set this limit on a self-managed installation, run the following in the Plan.default.actual_limits.update!(ci_project_subscriptions: 500) ``` -NOTE: **Note:** Set the limit to `0` to disable it. ### Number of pipeline schedules @@ -351,7 +347,7 @@ setting is used: | `ci_max_artifact_size_license_management` | 0 | | `ci_max_artifact_size_license_scanning` | 0 | | `ci_max_artifact_size_load_performance` | 0 | -| `ci_max_artifact_size_lsif` | 20 MB ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37226) in GitLab 13.3) | +| `ci_max_artifact_size_lsif` | 100 MB ([Introduced at 20 MB](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37226) in GitLab 13.3 and [raised to 100 MB](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46980) in GitLab 13.6.) | | `ci_max_artifact_size_metadata` | 0 | | `ci_max_artifact_size_metrics_referee` | 0 | | `ci_max_artifact_size_metrics` | 0 | @@ -462,11 +458,10 @@ Setting a limit helps reduce the memory usage of the indexing processes as well as the overall index size. This value defaults to `1024 KiB` (1 MiB) as any text files larger than this likely aren't meant to be read by humans. -NOTE: **Note:** -You must set a limit, as an unlimited file size is not supported. Setting this -value to be greater than the amount of memory on GitLab's Sidekiq nodes will -lead to GitLab's Sidekiq nodes running out of memory as they will pre-allocate -this amount of memory during indexing. +You must set a limit, as unlimited file sizes aren't supported. Setting this +value to be greater than the amount of memory on GitLab's Sidekiq nodes causes +GitLab's Sidekiq nodes to run out of memory, as they will pre-allocate this +amount of memory during indexing. ### Maximum field length @@ -486,7 +481,6 @@ indexed](#maximum-file-size-indexed)). This limit can be configured for self-managed installations when [enabling Elasticsearch](../integration/elasticsearch.md#enabling-advanced-search). -NOTE: **Note:** Set the limit to `0` to disable it. ## Wiki limits diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md index 7eadb54804b..b00586b281b 100644 --- a/doc/administration/instance_review.md +++ b/doc/administration/instance_review.md @@ -4,15 +4,15 @@ group: Conversion info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Instance Review **(CORE ONLY)** +# Instance Review > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6995) in [GitLab Core](https://about.gitlab.com/pricing/) 11.3. -If you are running a medium size instance (50+ users) of -[GitLab Core](https://about.gitlab.com/pricing/) edition, you are qualified for a -free Instance Review. +If you run a medium-sized self-managed instance (50+ users) of a free version of GitLab, +[either Community Edition or unlicensed Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/), +you qualify for a free Instance Review. -1. Sign in as a user with Admin [permissions](../user/permissions.md). +1. Sign in as a user with administrator [permissions](../user/permissions.md). 1. In the top menu, click your user icon, and select **Get a free instance review**: diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 8069b12e0b9..a010903013e 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -103,7 +103,7 @@ If you configure GitLab to store artifacts on object storage, you may also want [eliminate local disk usage for job logs](job_logs.md#prevent-local-disk-usage). In both cases, job logs are archived and moved to object storage when the job completes. -DANGER: **Danger:** +DANGER: **Warning:** In a multi-server setup you must use one of the options to [eliminate local disk usage for job logs](job_logs.md#prevent-local-disk-usage), or job logs could be lost. diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index c89ffb8da8b..23343d309de 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.md @@ -43,6 +43,45 @@ To change the location where the job logs will be stored, follow the steps below 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +Alternatively, if you have existing job logs you can follow +these steps to move the logs to a new location without losing any data. + +1. Pause continuous integration data processing by updating this setting in `/etc/gitlab/gitlab.rb`. + Jobs in progress are not affected, based on how [data flow](#data-flow) works. + + ```ruby + sidekiq['experimental_queue_selector'] = true + sidekiq['queue_groups'] = [ + "feature_category!=continuous_integration" + ] + ``` + +1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the + changes to take effect. +1. Set the new storage location in `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_ci['builds_directory'] = '/mnt/to/gitlab-ci/builds' + ``` + +1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the + changes to take effect. +1. Use `rsync` to move job logs from the current location to the new location: + + ```shell + sudo rsync -avzh --remove-source-files --ignore-existing --progress /var/opt/gitlab/gitlab-ci/builds/ /mnt/to/gitlab-ci/builds` + ``` + + Use `--ignore-existing` so you don't override new job logs with older versions of the same log. +1. Unpause continuous integration data processing by editing `/etc/gitlab/gitlab.rb` and removing the `sidekiq` setting you updated earlier. +1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the + changes to take effect. +1. Remove the old job logs storage location: + + ```shell + sudo rm -rf /var/opt/gitlab/gitlab-ci/builds` + ``` + **In installations from source:** 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines: @@ -82,7 +121,7 @@ job output in the UI will be empty. For example, to delete all job logs older than 60 days, run the following from a shell in your GitLab instance: -DANGER: **Danger:** +DANGER: **Warning:** This command will permanently delete the log files and is irreversible. ```shell @@ -104,7 +143,7 @@ The data flow is the same as described in the [data flow section](#data-flow) with one change: _the stored path of the first two phases is different_. This incremental log architecture stores chunks of logs in Redis and a persistent store (object storage or database) instead of file storage. Redis is used as first-class storage, and it stores up-to 128KB -of data. Once the full chunk is sent, it is flushed to a persistent store, either object storage (temporary directory) or database. +of data. After the full chunk is sent, it is flushed to a persistent store, either object storage (temporary directory) or database. After a while, the data in Redis and a persistent store will be archived to [object storage](#uploading-logs-to-object-storage). The data are stored in the following Redis namespace: `Gitlab::Redis::SharedState`. @@ -114,9 +153,9 @@ Here is the detailed data flow: 1. The runner picks a job from GitLab 1. The runner sends a piece of log to GitLab 1. GitLab appends the data to Redis -1. Once the data in Redis reach 128KB, the data is flushed to a persistent store (object storage or the database). +1. After the data in Redis reaches 128KB, the data is flushed to a persistent store (object storage or the database). 1. The above steps are repeated until the job is finished. -1. Once the job is finished, GitLab schedules a Sidekiq worker to archive the log. +1. After the job is finished, GitLab schedules a Sidekiq worker to archive the log. 1. The Sidekiq worker archives the log to object storage and cleans up the log in Redis and a persistent store (object storage or the database). diff --git a/doc/administration/load_balancer.md b/doc/administration/load_balancer.md index ae4fa83662a..410381ff2b0 100644 --- a/doc/administration/load_balancer.md +++ b/doc/administration/load_balancer.md @@ -114,7 +114,7 @@ Configure DNS for an alternate SSH hostname such as `altssh.gitlab.example.com`. ## Readiness check -It is strongly recommend that multi-node deployments configure load balancers to utilize the [readiness check](../user/admin_area/monitoring/health_check.md#readiness) to ensure a node is ready to accept traffic, before routing traffic to it. This is especially important when utilizing Puma, as there is a brief period during a restart where Puma will not accept requests. +It is strongly recommend that multi-node deployments configure load balancers to use the [readiness check](../user/admin_area/monitoring/health_check.md#readiness) to ensure a node is ready to accept traffic, before routing traffic to it. This is especially important when utilizing Puma, as there is a brief period during a restart where Puma will not accept requests. <!-- ## Troubleshooting diff --git a/doc/administration/logs.md b/doc/administration/logs.md index c9e0cca807e..e5523ba67aa 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -14,8 +14,8 @@ Find more about them [in Audit Events documentation](audit_events.md). System log files are typically plain text in a standard log file format. This guide talks about how to read and use these system log files. -[Read more about how to customise logging on Omnibus GitLab -installations](https://docs.gitlab.com/omnibus/settings/logs.html) +Read more about how to +[customize logging on Omnibus GitLab installations](https://docs.gitlab.com/omnibus/settings/logs.html) including adjusting log retention, log forwarding, switching logs from JSON to plain text logging, and more. @@ -87,7 +87,7 @@ In addition, the log contains the originating IP address, (`remote_ip`), the user's ID (`user_id`), and username (`username`). Some endpoints such as `/search` may make requests to Elasticsearch if using -[Advanced Search](../user/search/advanced_global_search.md). These will +[Advanced Search](../user/search/advanced_global_search.md). These additionally log `elasticsearch_calls` and `elasticsearch_call_duration_s`, which correspond to: @@ -367,9 +367,9 @@ After GitLab version 12.2, this file was renamed from `githost.log` to `git_json.log` and stored in JSON format. GitLab has to interact with Git repositories, but in some rare cases -something can go wrong, and in this case you may need know what exactly +something can go wrong. If this happens, you need to know exactly what happened. This log file contains all failed requests from GitLab to Git -repositories. In the majority of cases this file will be useful for developers +repositories. In the majority of cases this file is useful for developers only. For example: ```json @@ -482,7 +482,7 @@ This file contains logging information about jobs before Sidekiq starts processing them, such as before being enqueued. This log file follows the same structure as -[`sidekiq.log`](#sidekiqlog), so it will be structured as JSON if +[`sidekiq.log`](#sidekiqlog), so it is structured as JSON if you've configured this for Sidekiq as mentioned above. ## `gitlab-shell.log` @@ -582,6 +582,12 @@ This file lives in `/var/log/gitlab/gitaly/current` and is produced by [runit](h This file lives in `/var/log/gitlab/gitlab-rails/grpc.log` for Omnibus GitLab packages. Native [gRPC](https://grpc.io/) logging used by Gitaly. +### `gitaly_ruby_json.log` + +> [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/2678) in GitLab 13.6. + +This file lives in `/var/log/gitlab/gitaly/gitaly_ruby_json.log` and is produced by [`gitaly-ruby`](gitaly/reference.md#gitaly-ruby). It contains an access log of gRPC calls made by Gitaly to `gitaly-ruby`. + ## Puma Logs ### `puma_stdout.log` @@ -599,7 +605,7 @@ installations from source. ## Unicorn Logs Starting with GitLab 13.0, Puma is the default web server used in GitLab -all-in-one package based installations as well as GitLab Helm chart deployments. +all-in-one package based installations, and GitLab Helm chart deployments. ### `unicorn_stdout.log` @@ -720,21 +726,26 @@ was initiated, such as `1509705644.log` ## `sidekiq_exporter.log` and `web_exporter.log` If Prometheus metrics and the Sidekiq Exporter are both enabled, Sidekiq -will start a Web server and listen to the defined port (default: +starts a Web server and listen to the defined port (default: `8082`). By default, Sidekiq Exporter access logs are disabled but can -be enabled via the `sidekiq['exporter_log_enabled'] = true` option in `/etc/gitlab/gitlab.rb` -for Omnibus installations, or via the `sidekiq_exporter.log_enabled` option -in `gitlab.yml` for installations from source. When enabled, -access logs will be generated in +be enabled: + +- For Omnibus GitLab installations, using the `sidekiq['exporter_log_enabled'] = true` + option in `/etc/gitlab/gitlab.rb`. +- For installations from source, using the `sidekiq_exporter.log_enabled` option + in `gitlab.yml`. + +When enabled, access logs are generated in `/var/log/gitlab/gitlab-rails/sidekiq_exporter.log` for Omnibus GitLab packages or in `/home/git/gitlab/log/sidekiq_exporter.log` for installations from source. -If Prometheus metrics and the Web Exporter are both enabled, Puma/Unicorn will -start a Web server and listen to the defined port (default: `8083`). Access logs -will be generated in `/var/log/gitlab/gitlab-rails/web_exporter.log` for -Omnibus GitLab packages or in `/home/git/gitlab/log/web_exporter.log` for -installations from source. +If Prometheus metrics and the Web Exporter are both enabled, Puma/Unicorn +starts a Web server and listen to the defined port (default: `8083`), and access logs +are generated: + +- For Omnibus GitLab packages, in `/var/log/gitlab/gitlab-rails/web_exporter.log`. +- For installations from source, in `/home/git/gitlab/log/web_exporter.log`. ## `database_load_balancing.log` **(PREMIUM ONLY)** @@ -750,13 +761,11 @@ It's stored at: > Introduced in GitLab 12.6. -This file lives in -`/var/log/gitlab/gitlab-rails/elasticsearch.log` for Omnibus GitLab -packages or in `/home/git/gitlab/log/elasticsearch.log` for installations -from source. +This file logs information related to the Elasticsearch Integration, including +errors during indexing or searching Elasticsearch. It's stored at: -It logs information related to the Elasticsearch Integration including -errors during indexing or searching Elasticsearch. +- `/var/log/gitlab/gitlab-rails/elasticsearch.log` for Omnibus GitLab packages. +- `/home/git/gitlab/log/elasticsearch.log` for installations from source. Each line contains a JSON line that can be ingested by services like Elasticsearch and Splunk. Line breaks have been added to the following example line for clarity: @@ -779,12 +788,12 @@ Line breaks have been added to the following example line for clarity: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17819) in GitLab 12.6. -This file lives in -`/var/log/gitlab/gitlab-rails/exceptions_json.log` for Omnibus GitLab -packages or in `/home/git/gitlab/log/exceptions_json.log` for installations -from source. +This file logs the information about exceptions being tracked by +`Gitlab::ErrorTracking`, which provides a standard and consistent way of +[processing rescued exceptions](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/development/logging.md#exception-handling). This file is stored in: -It logs the information about exceptions being tracked by `Gitlab::ErrorTracking` which provides a standard and consistent way of [processing rescued exceptions](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/development/logging.md#exception-handling). +- `/var/log/gitlab/gitlab-rails/exceptions_json.log` for Omnibus GitLab packages. +- `/home/git/gitlab/log/exceptions_json.log` for installations from source. Each line contains a JSON line that can be ingested by Elasticsearch. For example: @@ -814,7 +823,7 @@ Omnibus GitLab packages or in `/home/git/gitlab/log/service_measurement.log` for installations from source. It contains only a single structured log with measurements for each service execution. -It will contain measurements such as the number of SQL calls, `execution_time`, `gc_stats`, and `memory usage`. +It contains measurements such as the number of SQL calls, `execution_time`, `gc_stats`, and `memory usage`. For example: @@ -847,7 +856,9 @@ This file is stored in: - `/var/log/gitlab/gitlab-rails/update_mirror_service_json.log` for Omnibus GitLab installations. - `/home/git/gitlab/log/update_mirror_service_json.log` for installations from source. -This file contains information about any errors that occurred during project mirroring. +This file contains information about LFS errors that occurred during project mirroring. +While we work to move other project mirroring errors into this log, the [general log](#productionlog) +can be used. ```json { @@ -939,7 +950,7 @@ For Omnibus GitLab installations, Alertmanager logs reside in `/var/log/gitlab/a ## Crond Logs -For Omnibus GitLab installations, crond logs reside in `/var/log/gitlab/crond/`. +For Omnibus GitLab installations, `crond` logs reside in `/var/log/gitlab/crond/`. ## Grafana Logs @@ -957,6 +968,11 @@ For Omnibus GitLab installations, GitLab Monitor logs reside in `/var/log/gitlab For Omnibus GitLab installations, GitLab Exporter logs reside in `/var/log/gitlab/gitlab-exporter/`. +## GitLab Kubernetes Agent Server + +For Omnibus GitLab installations, GitLab Kubernetes Agent Server logs reside +in `/var/log/gitlab/gitlab-kas/`. + ## Gathering logs When [troubleshooting](troubleshooting/index.md) issues that aren't localized to one of the @@ -967,7 +983,7 @@ from a GitLab instance. If the bug or error is readily reproducible, save the main GitLab logs [to a file](troubleshooting/linux_cheat_sheet.md#files--dirs) while reproducing the -problem once or more times: +problem a few times: ```shell sudo gitlab-ctl tail | tee /tmp/<case-ID-and-keywords>.log @@ -980,7 +996,7 @@ Conclude the log gathering with <kbd>Ctrl</kbd> + <kbd>C</kbd>. If performance degradations or cascading errors occur that can't readily be attributed to one of the previously listed GitLab components, [GitLabSOS](https://gitlab.com/gitlab-com/support/toolbox/gitlabsos/) can provide a perspective spanning all of Omnibus GitLab. For more details and instructions -to run it, see [the GitLabSOS documentation](https://gitlab.com/gitlab-com/support/toolbox/gitlabsos/#gitlabsos). +to run it, read [the GitLabSOS documentation](https://gitlab.com/gitlab-com/support/toolbox/gitlabsos/#gitlabsos). NOTE: **Note:** GitLab Support likes to use this custom-made tool. @@ -989,5 +1005,5 @@ GitLab Support likes to use this custom-made tool. [Fast-stats](https://gitlab.com/gitlab-com/support/toolbox/fast-stats) is a tool for creating and comparing performance statistics from GitLab logs. -For more details and instructions to run it, see -[read the documentation for fast-stats](https://gitlab.com/gitlab-com/support/toolbox/fast-stats#usage). +For more details and instructions to run it, read the +[documentation for fast-stats](https://gitlab.com/gitlab-com/support/toolbox/fast-stats#usage). diff --git a/doc/administration/monitoring/github_imports.md b/doc/administration/monitoring/github_imports.md index 64f45001438..da7796c05f0 100644 --- a/doc/administration/monitoring/github_imports.md +++ b/doc/administration/monitoring/github_imports.md @@ -17,11 +17,10 @@ monitor the health and progress of the importer. |------------------------------------------|-----------| | `github_importer_total_duration_seconds` | histogram | -This metric tracks the total time spent (in seconds) importing a project (from +This metric tracks the total time, in seconds, spent importing a project (from project creation until the import process finishes), for every imported project. - The name of the project is stored in the `project` label in the format -`namespace/name` (e.g. `gitlab-org/gitlab`). +`namespace/name` (such as `gitlab-org/gitlab`). ## Number of imported projects @@ -59,7 +58,7 @@ projects. This metric does not expose any labels. This metric tracks the number of imported issues across all projects. The name of the project is stored in the `project` label in the format -`namespace/name` (e.g. `gitlab-org/gitlab`). +`namespace/name` (such as `gitlab-org/gitlab`). ## Number of imported pull requests @@ -70,7 +69,7 @@ The name of the project is stored in the `project` label in the format This metric tracks the number of imported pull requests across all projects. The name of the project is stored in the `project` label in the format -`namespace/name` (e.g. `gitlab-org/gitlab`). +`namespace/name` (such as `gitlab-org/gitlab`). ## Number of imported comments @@ -81,7 +80,7 @@ The name of the project is stored in the `project` label in the format This metric tracks the number of imported comments across all projects. The name of the project is stored in the `project` label in the format -`namespace/name` (e.g. `gitlab-org/gitlab`). +`namespace/name` (such as `gitlab-org/gitlab`). ## Number of imported pull request review comments @@ -92,7 +91,7 @@ The name of the project is stored in the `project` label in the format This metric tracks the number of imported comments across all projects. The name of the project is stored in the `project` label in the format -`namespace/name` (e.g. `gitlab-org/gitlab`). +`namespace/name` (such as `gitlab-org/gitlab`). ## Number of imported repositories diff --git a/doc/administration/monitoring/performance/gitlab_configuration.md b/doc/administration/monitoring/performance/gitlab_configuration.md index 6677eb73664..eb9dab1af59 100644 --- a/doc/administration/monitoring/performance/gitlab_configuration.md +++ b/doc/administration/monitoring/performance/gitlab_configuration.md @@ -7,21 +7,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Configuration GitLab Performance Monitoring is disabled by default. To enable it and change any of its -settings, navigate to **Admin Area > Settings > Metrics and profiling** -(`/admin/application_settings/metrics_and_profiling`). +settings: - +1. Navigate to **Admin Area > Settings > Metrics and profiling** + (`/admin/application_settings/metrics_and_profiling`): -Finally, a restart of all GitLab processes is required for the changes to take -effect: +  -```shell -# For Omnibus installations -sudo gitlab-ctl restart +1. You must restart all GitLab processes for the changes to take effect: -# For installations from source -sudo service gitlab restart -``` + - For Omnibus GitLab installations: `sudo gitlab-ctl restart` + - For installations from source: `sudo service gitlab restart` ## Pending Migrations diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index 77ed5d442e6..dc77a35e44b 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -113,7 +113,7 @@ If you require access to your old Grafana data but don't meet one of these crite 1. [Exporting the dashboards](https://grafana.com/docs/grafana/latest/reference/export_import/#exporting-a-dashboard) you need. 1. Refreshing the data and [re-importing your dashboards](https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard). -DANGER: **Danger:** +DANGER: **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. diff --git a/doc/administration/monitoring/performance/index.md b/doc/administration/monitoring/performance/index.md index 68b89b837ac..6ea756619f5 100644 --- a/doc/administration/monitoring/performance/index.md +++ b/doc/administration/monitoring/performance/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Performance Monitoring GitLab comes with its own application performance measuring system as of GitLab -8.4, simply called "GitLab Performance Monitoring". GitLab Performance Monitoring is available in both the +8.4, called "GitLab Performance Monitoring". GitLab Performance Monitoring is available in both the Community and Enterprise editions. Apart from this introduction, you are advised to read through the following @@ -42,7 +42,7 @@ Two types of metrics are collected: Transaction metrics are metrics that can be associated with a single transaction. This includes statistics such as the transaction duration, timings -of any executed SQL queries, time spent rendering HAML views, etc. These metrics +of any executed SQL queries, time spent rendering HAML views, and so on. These metrics are collected for every Rack request and Sidekiq job processed. ### Sampled Metrics @@ -59,5 +59,5 @@ parts: The actual interval can be anywhere between a half of the defined interval and a half above the interval. For example, for a user defined interval of 15 seconds the actual interval can be anywhere between 7.5 and 22.5. The interval is -re-generated for every sampling run instead of being generated once and re-used +re-generated for every sampling run instead of being generated one time and reused for the duration of the process' lifetime. diff --git a/doc/administration/monitoring/prometheus/gitlab_exporter.md b/doc/administration/monitoring/prometheus/gitlab_exporter.md index 971dafb4ba2..aa2eb9f3415 100644 --- a/doc/administration/monitoring/prometheus/gitlab_exporter.md +++ b/doc/administration/monitoring/prometheus/gitlab_exporter.md @@ -13,7 +13,6 @@ The [GitLab exporter](https://gitlab.com/gitlab-org/gitlab-exporter) enables you measure various GitLab metrics pulled from Redis and the database in Omnibus GitLab instances. -NOTE: **Note:** For installations from source you must install and configure it yourself. To enable the GitLab exporter in an Omnibus GitLab instance: diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index adb1f719f3c..5c9268b54e1 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -13,7 +13,6 @@ To enable the GitLab Prometheus metrics: 1. Find the **Metrics - Prometheus** section, and click **Enable Prometheus Metrics**. 1. [Restart GitLab](../../restart_gitlab.md#omnibus-gitlab-restart) for the changes to take effect. -NOTE: **Note:** For installations from source you must configure it yourself. ## Collecting the metrics @@ -124,8 +123,6 @@ The following metrics can be controlled by feature flags: |:---------------------------------------------------------------|:-------------------------------------------------------------------| | `gitlab_method_call_duration_seconds` | `prometheus_metrics_method_instrumentation` | | `gitlab_view_rendering_duration_seconds` | `prometheus_metrics_view_instrumentation` | -| `gitlab_issuable_fast_count_by_state_total` | `soft_fail_count_by_state` | -| `gitlab_issuable_fast_count_by_state_failures_total` | `soft_fail_count_by_state` | ## Sidekiq metrics @@ -211,6 +208,7 @@ configuration option in `gitlab.yml`. These metrics are served from the | `limited_capacity_worker_running_jobs` | Gauge | 13.5 | Number of running jobs | `worker` | | `limited_capacity_worker_max_running_jobs` | Gauge | 13.5 | Maximum number of running jobs | `worker` | | `limited_capacity_worker_remaining_work_count` | Gauge | 13.5 | Number of jobs waiting to be enqueued | `worker` | +| `destroyed_job_artifacts_count_total` | Counter | 13.6 | Number of destroyed expired job artifacts | | ## Database load balancing metrics **(PREMIUM ONLY)** diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index 63231996dcc..91f810dc681 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -26,12 +26,11 @@ access to high quality time-series monitoring of GitLab services. Prometheus works by periodically connecting to data sources and collecting their performance metrics through the [various exporters](#bundled-software-metrics). To view and work with the monitoring data, you can either -[connect directly to Prometheus](#viewing-performance-metrics) or utilize a +[connect directly to Prometheus](#viewing-performance-metrics) or use a dashboard tool like [Grafana](https://grafana.com). ## Configuring Prometheus -NOTE: **Note:** For installations from source, you must install and configure it yourself. Prometheus and its exporters are on by default, starting with GitLab 9.0. @@ -54,7 +53,7 @@ To disable Prometheus and all of its exporters, as well as any added in the futu ### Changing the port and address Prometheus listens on -NOTE: **Note:** +CAUTION: **Caution:** The following change was added in [Omnibus GitLab 8.17](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/1261). Although possible, it's not recommended to change the port Prometheus listens on, as this might affect or conflict with other services running on the GitLab @@ -178,7 +177,6 @@ The next step is to tell all the other nodes where the monitoring node is: 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -NOTE: **Note:** After monitoring using Service Discovery is enabled with `consul['monitoring_service_discovery'] = true`, ensure that `prometheus['scrape_configs']` is not set in `/etc/gitlab/gitlab.rb`. Setting both `consul['monitoring_service_discovery'] = true` and `prometheus['scrape_configs']` in `/etc/gitlab/gitlab.rb` @@ -186,7 +184,7 @@ will result in errors. ### Using an external Prometheus server -NOTE: **Note:** +CAUTION: **Caution:** Prometheus and most exporters don't support authentication. We don't recommend exposing them outside the local network. A few configuration changes are required to allow GitLab to be monitored by an external Prometheus server. External servers are recommended for [GitLab deployments with multiple nodes](../../reference_architectures/index.md). diff --git a/doc/administration/monitoring/prometheus/node_exporter.md b/doc/administration/monitoring/prometheus/node_exporter.md index dae1f02b196..fea78a3685c 100644 --- a/doc/administration/monitoring/prometheus/node_exporter.md +++ b/doc/administration/monitoring/prometheus/node_exporter.md @@ -9,7 +9,6 @@ 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. -NOTE: **Note:** For installations from source 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 4554bc06401..ff0cfc65e10 100644 --- a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md +++ b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md @@ -11,7 +11,6 @@ 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. -NOTE: **Note:** For installations from source 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 9eb9ba3c59f..f7368556235 100644 --- a/doc/administration/monitoring/prometheus/postgres_exporter.md +++ b/doc/administration/monitoring/prometheus/postgres_exporter.md @@ -8,7 +8,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w The [PostgreSQL Server Exporter](https://github.com/wrouesnel/postgres_exporter) allows you to export various PostgreSQL metrics. -NOTE: **Note:** For installations from source 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 16a758c9804..41a84f1f3ed 100644 --- a/doc/administration/monitoring/prometheus/redis_exporter.md +++ b/doc/administration/monitoring/prometheus/redis_exporter.md @@ -10,7 +10,6 @@ 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). -NOTE: **Note:** For installations from source 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 fabbfb2552e..3e16b173003 100644 --- a/doc/administration/nfs.md +++ b/doc/administration/nfs.md @@ -19,11 +19,10 @@ From GitLab 13.0, using NFS for Git repositories is deprecated. In GitLab 14.0, support for NFS for Git repositories is scheduled to be removed. Upgrade to [Gitaly Cluster](gitaly/praefect.md) as soon as possible. -NOTE: **Note:** -Filesystem performance has a big impact on overall GitLab -performance, especially for actions that read or write to Git repositories. See -[Filesystem Performance Benchmarking](operations/filesystem_benchmarking.md) -for steps to test filesystem performance. +Filesystem performance can impact overall GitLab performance, especially for +actions that read or write to Git repositories. For steps you can use to test +filesystem performance, see +[Filesystem Performance Benchmarking](operations/filesystem_benchmarking.md). ## Known kernel version incompatibilities @@ -119,7 +118,7 @@ To disable NFS server delegation, do the following: 1. Restart the NFS server process. For example, on CentOS run `service nfs restart`. -NOTE: **Important note:** +NOTE: **Note:** The kernel bug may be fixed in [more recent kernels with this commit](https://github.com/torvalds/linux/commit/95da1b3a5aded124dd1bda1e3cdb876184813140). Red Hat Enterprise 7 [shipped a kernel update](https://access.redhat.com/errata/RHSA-2019:2029) @@ -250,9 +249,9 @@ gitlab_rails['shared_path'] = '/gitlab-nfs/gitlab-data/shared' gitlab_ci['builds_directory'] = '/gitlab-nfs/gitlab-data/builds' ``` -Run `sudo gitlab-ctl reconfigure` to start using the central location. Please -be aware that if you had existing data you will need to manually copy/rsync it -to these new locations and then restart GitLab. +Run `sudo gitlab-ctl reconfigure` to start using the central location. Be aware +that if you had existing data, you'll need to manually copy or rsync it to +these new locations, and then restart GitLab. ### Bind mounts @@ -307,8 +306,12 @@ by testing the following commands: ```shell sudo mkdir /gitlab-nfs/test-dir sudo chown git /gitlab-nfs/test-dir -sudo chgrp gitlab-www /gitlab-nfs/test-dir sudo chgrp root /gitlab-nfs/test-dir +sudo chmod 0700 /gitlab-nfs/test-dir +sudo chgrp gitlab-www /gitlab-nfs/test-dir +sudo chmod 0751 /gitlab-nfs/test-dir +sudo chgrp git /gitlab-nfs/test-dir +sudo chmod 2770 /gitlab-nfs/test-dir sudo chmod 2755 /gitlab-nfs/test-dir sudo -u git mkdir /gitlab-nfs/test-dir/test2 sudo -u git chmod 2755 /gitlab-nfs/test-dir/test2 @@ -323,7 +326,7 @@ Any `Operation not permitted` errors means you should investigate your NFS serve If the traffic between your NFS server and NFS client(s) is subject to port filtering by a firewall, then you will need to reconfigure that firewall to allow NFS communication. -[This guide from TDLP](http://tldp.org/HOWTO/NFS-HOWTO/security.html#FIREWALLS) +[This guide from TDLP](https://tldp.org/HOWTO/NFS-HOWTO/security.html#FIREWALLS) covers the basics of using NFS in a firewalled environment. Additionally, we encourage you to search for and review the specific documentation for your operating system or distribution and your firewall software. @@ -396,8 +399,8 @@ Additionally, this configuration is specifically warned against in the >system semantics, this can cause reliability problems. Specifically, delayed (asynchronous) writes >to the NFS server can cause data corruption problems. -For supported database architecture, please see our documentation on -[Configuring a Database for GitLab HA](postgresql/replication_and_failover.md). +For supported database architecture, see our documentation about +[configuring a database for replication and failover](postgresql/replication_and_failover.md). <!-- ## Troubleshooting diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md index 0ce1ff447ec..2b714c36d93 100644 --- a/doc/administration/object_storage.md +++ b/doc/administration/object_storage.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Enablement +group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- @@ -61,18 +61,17 @@ must be enabled, only the following providers can be used: - [Google Cloud Storage](#google-cloud-storage-gcs) - [Azure Blob storage](#azure-blob-storage) -Background upload is not supported with the consolidated object storage -configuration. We recommend enabling direct upload mode because it does -not require a shared folder, and [this setting may become the +Background upload isn't supported with the consolidated object storage +configuration. We recommend enabling direct upload mode because it doesn't +require a shared folder, and [this setting may become the default](https://gitlab.com/gitlab-org/gitlab/-/issues/27331). -NOTE: **Note:** -Consolidated object storage configuration cannot be used for -backups or Mattermost. See [the full table for a complete list](#storage-specific-configuration). +Consolidated object storage configuration can't be used for backups or +Mattermost. See the [full table for a complete list](#storage-specific-configuration). -NOTE: **Note:** -Enabling consolidated object storage will enable object storage for all object types. -If you wish to use local storage for specific object types, you can [selectively disable object storages](#selectively-disabling-object-storage). +Enabling consolidated object storage enables object storage for all object +types. If you want to use local storage for specific object types, you can +[selectively disable object storages](#selectively-disabling-object-storage). Most types of objects, such as CI artifacts, LFS files, upload attachments, and so on can be saved in object storage by specifying a single @@ -117,7 +116,7 @@ See the section on [ETag mismatch errors](#etag-mismatch) for more details. gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = '<terraform-state>' ``` - NOTE: For GitLab 9.4 or later, if you're using AWS IAM profiles, be sure to omit the + For GitLab 9.4 or later, if you're using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs. For example: ```ruby @@ -262,10 +261,11 @@ Here are the valid connection parameters for GCS: | `google_project` | GCP project name | `gcp-project-12345` | | `google_client_email` | The email address of the service account | `foo@gcp-project-12345.iam.gserviceaccount.com` | | `google_json_key_location` | The JSON key path | `/path/to/gcp-project-12345-abcde.json` | +| `google_application_default` | Set to `true` to use [Google Cloud Application Default Credentials](https://cloud.google.com/docs/authentication/production#automatically) to locate service account credentials. | -NOTE: **Note:** -The service account must have permission to access the bucket. -[See more](https://cloud.google.com/storage/docs/authentication) +The service account must have permission to access the bucket. Learn more +in Google's +[Cloud Storage authentication documentation](https://cloud.google.com/storage/docs/authentication). ##### Google example (consolidated form) @@ -280,6 +280,33 @@ gitlab_rails['object_store']['connection'] = { } ``` +##### Google example with ADC (consolidated form) + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275979) in GitLab 13.6. + +Google Cloud Application Default Credentials (ADC) are typically +used with GitLab to use the default service account. This eliminates the +need to supply credentials for the instance. For example: + +```ruby +gitlab_rails['object_store']['connection'] = { + 'provider' => 'Google', + 'google_project' => '<GOOGLE PROJECT>', + 'google_application_default' => true +} +``` + +If you use ADC, be sure that: + +- The service account that you use has the +[`iam.serviceAccounts.signBlob` permission](https://cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/signBlob). + Typically this is done by granting the `Service Account Token Creator` role to the service account. +- Your virtual machines have the [correct access scopes to access Google Cloud APIs](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances#changeserviceaccountandscopes). If the machines do not have the right scope, the error logs may show: + + ```markdown + Google::Apis::ClientError (insufficientPermissions: Request had insufficient authentication scopes.) + ``` + #### Azure Blob storage > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25877) in GitLab 13.4. @@ -288,6 +315,11 @@ Although Azure uses the word `container` to denote a collection of blobs, GitLab standardizes on the term `bucket`. Be sure to configure Azure container names in the `bucket` settings. +Azure Blob storage can only be used with the [consolidated form](#consolidated-object-storage-configuration) +because a single set of credentials are used to access multiple +containers. The [storage-specific form](#storage-specific-configuration) +is not supported. For more details, see [how to transition to consolidated form](#transition-to-consolidated-form). + The following are the valid connection parameters for Azure. Read the [Azure Blob storage documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) to learn more. @@ -314,10 +346,9 @@ gitlab_rails['object_store']['connection'] = { ###### Azure Workhorse settings (source installs only) -NOTE: **Note:** -For source installations, Workhorse needs to be configured with the -Azure credentials as well. This is not needed in Omnibus installs because -the Workhorse settings are populated from the settings above. +For source installations, Workhorse also needs to be configured with Azure +credentials. This isn't needed in Omnibus installs, because the Workhorse +settings are populated from the previous settings. 1. Edit `/home/git/gitlab-workhorse/config.toml` and add or amend the following lines: @@ -337,14 +368,14 @@ GitLab Rails and Workhorse. #### OpenStack-compatible connection settings -NOTE: **Note:** -This is not compatible with the consolidated object storage form. -OpenStack Swift is only supported with the storage-specific form. See the -[S3 settings](#s3-compatible-connection-settings) if you want to use the consolidated form. +Although OpenStack Swift provides S3 compatibility, some users may want to use +the [Swift API](https://docs.openstack.org/swift/latest/api/object_api_v1_overview.html). + +This isn't compatible with the consolidated object storage form. OpenStack Swift +is supported only with the storage-specific form. If you want to use the +consolidated form, see the [S3 settings](#s3-compatible-connection-settings). -While OpenStack Swift provides S3 compatibility, some users may want to use the -[Swift API](https://docs.openstack.org/swift/latest/api/object_api_v1_overview.html). -Here are the valid connection settings below for the Swift API, provided by +Here are the valid connection settings for the Swift API, provided by [fog-openstack](https://github.com/fog/fog-openstack): | Setting | Description | Default | @@ -359,12 +390,11 @@ Here are the valid connection settings below for the Swift API, provided by #### Rackspace Cloud Files -NOTE: **Note:** -This is not compatible with the consolidated object -storage form. Rackspace Cloud is only supported with the storage-specific form. +The following table describes the valid connection parameters for +Rackspace Cloud, provided by [fog-rackspace](https://github.com/fog/fog-rackspace/). -Here are the valid connection parameters for Rackspace Cloud, provided by -[fog-rackspace](https://github.com/fog/fog-rackspace/): +This isn't compatible with the consolidated object storage form. +Rackspace Cloud is supported only with the storage-specific form. | Setting | Description | example | |---------|-------------|---------| @@ -374,13 +404,13 @@ Here are the valid connection parameters for Rackspace Cloud, provided by | `rackspace_region` | The Rackspace storage region to use, a three letter code from the [list of service access endpoints](https://developer.rackspace.com/docs/cloud-files/v1/general-api-info/service-access/) | `iad` | | `rackspace_temp_url_key` | The private key you have set in the Rackspace API for [temporary URLs](https://developer.rackspace.com/docs/cloud-files/v1/use-cases/public-access-to-your-cloud-files-account/#tempurl). | `ABC123DEF456ABC123DEF456ABC123DE` | -NOTE: **Note:** -Regardless of whether the container has public access enabled or disabled, Fog will -use the TempURL method to grant access to LFS objects. If you see errors in logs referencing -instantiating storage with a `temp-url-key`, ensure that you have set the key properly -on the Rackspace API and in `gitlab.rb`. You can verify the value of the key Rackspace -has set by sending a GET request with token header to the service access endpoint URL -and comparing the output of the returned headers. +Regardless of whether the container has public access enabled or disabled, Fog +uses the TempURL method to grant access to LFS objects. If you see error +messages in logs that refer to instantiating storage with a `temp-url-key`, +be sure you have set the key properly both in the Rackspace API and in +`gitlab.rb`. You can verify the value of the key Rackspace has set by sending a +GET request with token header to the service access endpoint URL and comparing +the output of the returned headers. ### Object-specific configuration @@ -488,15 +518,16 @@ gitlab_rails['uploads_object_store_remote_directory'] = 'uploads' gitlab_rails['uploads_object_store_connection'] = { 'provider' => 'AWS', 'aws_access_key_id' => 'access_key', 'aws_secret_access_key' => 'secret' } ``` -While this provides flexibility in that it makes it possible for GitLab +Although this provides flexibility in that it makes it possible for GitLab to store objects across different cloud providers, it also creates additional complexity and unnecessary redundancy. Since both GitLab Rails and Workhorse components need access to object storage, the consolidated form avoids excessive duplication of credentials. -NOTE: **Note:** -The consolidated object storage configuration is **only** used if all -lines from the original form is omitted. To move to the consolidated form, remove the original configuration (for example, `artifacts_object_store_enabled`, `uploads_object_store_connection`, and so on.) +The consolidated object storage configuration is used _only_ if all lines from +the original form is omitted. To move to the consolidated form, remove the +original configuration (for example, `artifacts_object_store_enabled`, or +`uploads_object_store_connection`) ## Storage-specific configuration diff --git a/doc/administration/operations/cleaning_up_redis_sessions.md b/doc/administration/operations/cleaning_up_redis_sessions.md index a94f88439f2..8f90231a713 100644 --- a/doc/administration/operations/cleaning_up_redis_sessions.md +++ b/doc/administration/operations/cleaning_up_redis_sessions.md @@ -34,7 +34,7 @@ rcli() { # This example works for Omnibus installations of GitLab 7.3 or newer. For an # installation from source you will have to change the socket path and the # path to redis-cli. - sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.shared_state.socket "$@" + sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket "$@" } # test the new shell function; the response should be PONG diff --git a/doc/administration/operations/extra_sidekiq_processes.md b/doc/administration/operations/extra_sidekiq_processes.md index 76dc9bf5510..5de79882083 100644 --- a/doc/administration/operations/extra_sidekiq_processes.md +++ b/doc/administration/operations/extra_sidekiq_processes.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Enablement +group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -38,7 +38,7 @@ To start multiple processes: process, and values in each item determine the queues it works on. For example, the following setting creates three Sidekiq processes, one to run on - `elastic_indexer`, one to run on `mailers`, and one process running all on queues: + `elastic_indexer`, one to run on `mailers`, and one process running on all queues: ```ruby sidekiq['queue_groups'] = [ @@ -110,34 +110,29 @@ you list: sudo gitlab-ctl reconfigure ``` -## Queue selector (experimental) +## Queue selector -> [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/45) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. +> - [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/45) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. +> - [Sidekiq cluster including queue selector moved](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/181) to GitLab [Core](https://about.gitlab.com/pricing/#self-managed) in GitLab 12.10. +> - [Marked as supported](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/147) in GitLab [Core](https://about.gitlab.com/pricing/#self-managed) in GitLab 13.6. Renamed from `experimental_queue_selector` to `queue_selector`. -CAUTION: **Caution:** -As this is marked as **experimental**, it is subject to change at any -time, including **breaking backwards compatibility**. This is so that we -can react to changes we need for our GitLab.com deployment. We have a -tracking issue open to [remove the experimental -designation](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/147) -from this feature; please comment there if you are interested in using -this in your own deployment. - -In addition to selecting queues by name, as above, the -`experimental_queue_selector` option allows queue groups to be selected -in a more general way using the following components: +In addition to selecting queues by name, as above, the `queue_selector` +option allows queue groups to be selected in a more general way using +the following components: - Attributes that can be selected. - Operators used to construct a query. +When `queue_selector` is set, all `queue_groups` must be in the queue +selector syntax. + ### Available attributes - [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/261) in GitLab 13.1, `tags`. From the [list of all available attributes](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/workers/all_queues.yml), -`experimental_queue_selector` allows selecting of queues by the -following attributes: +`queue_selector` allows selecting of queues by the following attributes: - `feature_category` - the [GitLab feature category](https://about.gitlab.com/direction/maturity/#category-maturity) the @@ -169,8 +164,8 @@ neither of those tags. ### Available operators -`experimental_queue_selector` supports the following operators, listed -from highest to lowest precedence: +`queue_selector` supports the following operators, listed from highest +to lowest precedence: - `|` - the logical OR operator. For example, `query_a|query_b` (where `query_a` and `query_b` are queries made up of the other operators here) will include @@ -201,7 +196,7 @@ In `/etc/gitlab/gitlab.rb`: ```ruby sidekiq['enable'] = true -sidekiq['experimental_queue_selector'] = true +sidekiq['queue_selector'] = true sidekiq['queue_groups'] = [ # Run all non-CPU-bound queues that are high urgency 'resource_boundary!=cpu&urgency=high', @@ -230,7 +225,7 @@ All of the aforementioned configuration options for `sidekiq` are available. By default, they will be configured as follows: ```ruby -sidekiq['experimental_queue_selector'] = false +sidekiq['queue_selector'] = false sidekiq['interval'] = nil sidekiq['max_concurrency'] = 50 sidekiq['min_concurrency'] = nil @@ -327,9 +322,9 @@ Running Sidekiq cluster is the default in GitLab 13.0 and later. ``` `min_concurrency` and `max_concurrency` are independent; one can be set without -the other. Setting `min_concurrency` to 0 will disable the limit. +the other. Setting `min_concurrency` to `0` will disable the limit. -For each queue group, let N be one more than the number of queues. The +For each queue group, let `N` be one more than the number of queues. The concurrency factor will be set to: 1. `N`, if it's between `min_concurrency` and `max_concurrency`. diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index 88ef69b29f2..c8830a45fb2 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -196,7 +196,8 @@ the database. The following instructions can be used to build OpenSSH 7.5: yes | cp pam-ssh-conf-$timestamp /etc/pam.d/sshd ``` -1. Verify the installed version. In another window, attempt to login to the server: +1. Verify the installed version. In another window, attempt to sign in to the + server: ```shell ssh -v <your-centos-machine> @@ -204,7 +205,7 @@ the database. The following instructions can be used to build OpenSSH 7.5: You should see a line that reads: "debug1: Remote protocol version 2.0, remote software version OpenSSH_7.5" - If not, you may need to restart `sshd` (e.g. `systemctl restart sshd.service`). + If not, you may need to restart `sshd` (for example, `systemctl restart sshd.service`). 1. *IMPORTANT!* Open a new SSH session to your server before exiting to make sure everything is working! If you need to downgrade, simple install the diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index aaeb8c723d0..864bbb3233e 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/index.md @@ -13,6 +13,9 @@ Keep your GitLab instance up and running smoothly. you have been running a large GitLab server (thousands of users) since before GitLab 7.3 we recommend cleaning up stale sessions to compact the Redis database after you upgrade to GitLab 7.3. +- [Rake tasks](../../raketasks/README.md): Tasks for common administration and operational processes such as + [cleaning up unneeded items from GitLab instance](../../raketasks/cleanup.md), integrity checks, + and more. - [Moving repositories](moving_repositories.md): Moving all repositories managed by GitLab to another file system or another server. - [Sidekiq MemoryKiller](sidekiq_memory_killer.md): Configure Sidekiq MemoryKiller @@ -28,6 +31,8 @@ Keep your GitLab instance up and running smoothly. performance can have a big impact on GitLab performance, especially for actions that read or write Git repositories. This information will help benchmark filesystem performance against known good and bad real-world systems. +- [The Rails Console](rails_console.md): Provides a way to interact with your GitLab instance from the command line. + Used for troubleshooting a problem or retrieving some data that can only be done through direct access to GitLab. - [ChatOps Scripts](https://gitlab.com/gitlab-com/chatops): The GitLab.com Infrastructure team uses this repository to house common ChatOps scripts they use to troubleshoot and maintain the production instance of GitLab.com. These scripts are likely useful to administrators of GitLab instances of all sizes. diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index 94eea1e25b8..b311bee1a5b 100644 --- a/doc/administration/operations/moving_repositories.md +++ b/doc/administration/operations/moving_repositories.md @@ -1,26 +1,69 @@ --- -stage: none -group: unassigned +stage: Create +group: Gitaly info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +type: reference --- -# Moving repositories managed by GitLab +# Moving repositories managed by GitLab **(CORE ONLY)** Sometimes you need to move all repositories managed by GitLab to -another filesystem or another server. In this document we will look +another file system or another server. + +## Moving data within a GitLab instance + +The GitLab API is the recommended way to move Git repositories: + +- Between servers. +- Between different storage. +- From single-node Gitaly to Gitaly Cluster. + +For more information, see: + +- [Configuring additional storage for Gitaly](../gitaly/index.md#network-architecture). Within this + example, additional storage called `storage1` and `storage2` is configured. +- [The API documentation](../../api/project_repository_storage_moves.md) details the endpoints for + querying and scheduling repository moves. +- [Migrate existing repositories to Gitaly Cluster](../gitaly/praefect.md#migrate-existing-repositories-to-gitaly-cluster). + +### Limitations + +Read more in the [API documentation](../../api/project_repository_storage_moves.md#limitations). + +## Migrating to another GitLab instance + +[Using the API](#moving-data-within-a-gitlab-instance) isn't an option if you are migrating to a new +GitLab environment, for example: + +- From a single-node GitLab to a scaled-out architecture. +- From a GitLab instance in your private datacenter to a cloud provider. + +The rest of the document looks at some of the ways you can copy all your repositories from `/var/opt/gitlab/git-data/repositories` to `/mnt/gitlab/repositories`. -We will look at three scenarios: the target directory is empty, the -target directory contains an outdated copy of the repositories, and -how to deal with thousands of repositories. +We look at three scenarios: + +- The target directory is empty. +- The target directory contains an outdated copy of the repositories. +- How to deal with thousands of repositories. + +DANGER: **Warning:** +Each of the approaches we list can or does overwrite data in the target directory +`/mnt/gitlab/repositories`. Do not mix up the source and the target. + +### Recommended approach in all cases + +GitLab's [backup and restore capability](../../raketasks/backup_restore.md) should be used. Git +repositories are accessed, managed, and stored on GitLab servers by Gitaly as a database. Data loss +can result from directly accessing and copying Gitaly's files using tools like `rsync`. -DANGER: **Danger:** -Each of the approaches we list can/will overwrite data in the -target directory `/mnt/gitlab/repositories`. Do not mix up the -source and the target. +- From GitLab 13.3, backup performance can be improved by + [processing multiple repositories concurrently](../../raketasks/backup_restore.md#back-up-git-repositories-concurrently). +- Backups can be created of just the repositories using the + [skip feature](../../raketasks/backup_restore.md#excluding-specific-directories-from-the-backup). -## Target directory is empty: use a `tar` pipe +### Target directory is empty: use a `tar` pipe If the target directory `/mnt/gitlab/repositories` is empty the simplest thing to do is to use a `tar` pipe. This method has low @@ -35,7 +78,7 @@ sudo -u git sh -c 'tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ If you want to see progress, replace `-xf` with `-xvf`. -### `tar` pipe to another server +#### `tar` pipe to another server You can also use a `tar` pipe to copy data to another server. If your `git` user has SSH access to the new server as `git@newserver`, you @@ -47,15 +90,19 @@ sudo -u git sh -c 'tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ ``` If you want to compress the data before it goes over the network -(which will cost you CPU cycles) you can replace `ssh` with `ssh -C`. +(which costs you CPU cycles) you can replace `ssh` with `ssh -C`. -## The target directory contains an outdated copy of the repositories: use `rsync` +### The target directory contains an outdated copy of the repositories: use `rsync` + +DANGER: **Warning:** +Using `rsync` to migrate Git data can cause data loss and repository corruption. +[These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422). If the target directory already contains a partial / outdated copy of the repositories it may be wasteful to copy all the data again with `tar`. In this scenario it is better to use `rsync`. This utility is either already installed on your system or easily installable -via `apt`, `yum`, etc. +via `apt`, `yum`, and so on. ```shell sudo -u git sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ @@ -66,7 +113,11 @@ The `/.` in the command above is very important, without it you can easily get the wrong directory structure in the target directory. If you want to see progress, replace `-a` with `-av`. -### Single `rsync` to another server +#### Single `rsync` to another server + +DANGER: **Warning:** +Using `rsync` to migrate Git data can cause data loss and repository corruption. +[These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422). If the `git` user on your source system has SSH access to the target server you can send the repositories over the network with `rsync`. @@ -76,7 +127,11 @@ sudo -u git sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ git@newserver:/mnt/gitlab/repositories' ``` -## Thousands of Git repositories: use one `rsync` per repository +### Thousands of Git repositories: use one `rsync` per repository + +DANGER: **Warning:** +Using `rsync` to migrate Git data can cause data loss and repository corruption. +[These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422). Every time you start an `rsync` job it has to inspect all files in the source directory, all files in the target directory, and then @@ -86,20 +141,20 @@ for your GitLab server. In cases like this you can make `rsync`'s life easier by dividing its work in smaller pieces, and sync one repository at a time. -In addition to `rsync` we will use [GNU -Parallel](http://www.gnu.org/software/parallel/). This utility is -not included in GitLab so you need to install it yourself with `apt` -or `yum`. Also note that the GitLab scripts we used below were added -in GitLab 8.1. +In addition to `rsync` we use [GNU Parallel](http://www.gnu.org/software/parallel/). +This utility is not included in GitLab so you need to install it yourself with `apt` +or `yum`. Also note that the GitLab scripts we used below were added in GitLab 8.1. **This process does not clean up repositories at the target location that no -longer exist at the source.** If you start using your GitLab instance with -`/mnt/gitlab/repositories`, you need to run `gitlab-rake gitlab:cleanup:repos` -after switching to the new repository storage directory. +longer exist at the source.** -### Parallel `rsync` for all repositories known to GitLab +#### Parallel `rsync` for all repositories known to GitLab -This will sync repositories with 10 `rsync` processes at a time. We keep +DANGER: **Warning:** +Using `rsync` to migrate Git data can cause data loss and repository corruption. +[These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422). + +This syncs repositories with 10 `rsync` processes at a time. We keep track of progress so that the transfer can be restarted if necessary. First we create a new directory, owned by `git`, to hold transfer @@ -154,7 +209,11 @@ cat /home/git/transfer-logs/* | sort | uniq -u |\ ` ``` -### Parallel `rsync` only for repositories with recent activity +#### Parallel `rsync` only for repositories with recent activity + +DANGER: **Warning:** +Using `rsync` to migrate Git data can cause data loss and repository corruption. +[These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422). Suppose you have already done one sync that started after 2015-10-1 12:00 UTC. Then you might only want to sync repositories that were changed via GitLab diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md index 2d53a790428..5104b65c86d 100644 --- a/doc/administration/operations/puma.md +++ b/doc/administration/operations/puma.md @@ -33,7 +33,7 @@ will _not_ carry over automatically, due to differences between the two applicat deployments, see [Configuring Puma Settings](https://docs.gitlab.com/omnibus/settings/puma.html#configuring-puma-settings). For Helm based deployments, see the [Webservice Chart documentation](https://docs.gitlab.com/charts/charts/gitlab/webservice/index.html). -Additionally we strongly recommend that multi-node deployments [configure their load balancers to utilize the readiness check](../load_balancer.md#readiness-check) due to a difference between Unicorn and Puma in how they handle connections during a restart of the service. +Additionally we strongly recommend that multi-node deployments [configure their load balancers to use the readiness check](../load_balancer.md#readiness-check) due to a difference between Unicorn and Puma in how they handle connections during a restart of the service. ## Performance caveat when using Puma with Rugged diff --git a/doc/administration/operations/rails_console.md b/doc/administration/operations/rails_console.md index 9db9a885baf..dac36135a8e 100644 --- a/doc/administration/operations/rails_console.md +++ b/doc/administration/operations/rails_console.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # The Rails Console The [Rails console](https://guides.rubyonrails.org/command_line.html#rails-console). diff --git a/doc/administration/operations/sidekiq_memory_killer.md b/doc/administration/operations/sidekiq_memory_killer.md index d99468411e3..0de8b681dd8 100644 --- a/doc/administration/operations/sidekiq_memory_killer.md +++ b/doc/administration/operations/sidekiq_memory_killer.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Enablement +group: Memory info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index 56b7f01e1ad..541bd99084c 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -170,7 +170,7 @@ If your certificate provider provides the CA Bundle certificates, append them to 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. 1. Make the relevant changes in NGINX as well (domain, port, TLS certificates path). -Users should now be able to login to the Container Registry with their GitLab +Users should now be able to sign in to the Container Registry with their GitLab credentials using: ```shell @@ -234,7 +234,7 @@ registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key" 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. 1. Make the relevant changes in NGINX as well (domain, port, TLS certificates path). -Users should now be able to login to the Container Registry using their GitLab +Users should now be able to sign in to the Container Registry using their GitLab credentials: ```shell @@ -397,6 +397,20 @@ To configure the `s3` storage driver in Omnibus: } ``` + To avoid using static credentials, use an + [IAM role](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) + and omit `accesskey` and `secretkey`. Make sure that your IAM profile follows + [the permissions documented by Docker](https://docs.docker.com/registry/storage-drivers/s3/#s3-permission-scopes). + + ```ruby + registry['storage'] = { + 's3' => { + 'bucket' => 'your-s3-bucket', + 'region' => 'your-s3-region' + } + } + ``` + - `regionendpoint` is only required when configuring an S3 compatible service such as MinIO. It takes a URL such as `http://127.0.0.1:9000`. - `your-s3-bucket` should be the name of a bucket that exists, and can't include subdirectories. @@ -412,8 +426,8 @@ when you [deployed your Docker registry](https://docs.docker.com/registry/deploy ```yaml storage: s3: - accesskey: 's3-access-key' - secretkey: 's3-secret-key-for-access-key' + accesskey: 's3-access-key' # Not needed if IAM role used + secretkey: 's3-secret-key-for-access-key' # Not needed if IAM role used bucket: 'your-s3-bucket' region: 'your-s3-region' regionendpoint: 'your-s3-regionendpoint' @@ -471,7 +485,7 @@ you can pull from the Container Registry, but you cannot push. [`--dryrun`](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html) flag and run the command. - DANGER: **Danger:** + DANGER: **Warning:** The [`--delete`](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html) flag deletes files that exist in the destination but not in the source. If you swap the source and destination, all data in the Registry is deleted. @@ -584,7 +598,7 @@ on how to achieve that. ## Use an external container registry with GitLab as an auth endpoint If you use an external container registry, some features associated with the -container registry may be unavailable or have [inherent risks](./../../user/packages/container_registry/index.md#use-with-external-container-registries). +container registry may be unavailable or have [inherent risks](../../user/packages/container_registry/index.md#use-with-external-container-registries). **Omnibus GitLab** @@ -815,23 +829,23 @@ If you changed the location of the Container Registry `config.yml`: sudo gitlab-ctl registry-garbage-collect /path/to/config.yml ``` -You may also [remove all unreferenced manifests](#removing-unused-layers-not-referenced-by-manifests), +You may also [remove all untagged manifests and unreferenced layers](#removing-untagged-manifests-and-unreferenced-layers), although this is a way more destructive operation, and you should first understand the implications. -### Removing unused layers not referenced by manifests +### Removing untagged manifests and unreferenced layers > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/3097) in Omnibus GitLab 11.10. -DANGER: **Danger:** +DANGER: **Warning:** This is a destructive operation. The GitLab Container Registry follows the same default workflow as Docker Distribution: -retain all layers, even ones that are unreferenced directly to allow all content -to be accessed using context addressable identifiers. +retain untagged manifests and all layers, even ones that are not referenced directly. All content +can be accessed by using context addressable identifiers. -However, in most workflows, you don't care about old layers if they are not directly -referenced by the registry tag. The `registry-garbage-collect` command supports the +However, in most workflows, you don't care about untagged manifests and old layers if they are not directly +referenced by a tagged manifest. The `registry-garbage-collect` command supports the `-m` switch to allow you to remove all unreferenced manifests and layers that are not directly accessible via `tag`: @@ -839,6 +853,8 @@ not directly accessible via `tag`: sudo gitlab-ctl registry-garbage-collect -m ``` +Without the `-m` flag, the Container Registry only removes layers that are not referenced by any manifest, tagged or not. + Since this is a way more destructive operation, this behavior is disabled by default. You are likely expecting this way of operation, but before doing that, ensure that you have backed up all registry data. @@ -932,6 +948,8 @@ PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin 5 4 * * 0 root gitlab-ctl registry-garbage-collect ``` +You may want to add the `-m` flag to [remove untagged manifests and unreferenced layers](#removing-untagged-manifests-and-unreferenced-layers). + ## Troubleshooting Before diving in to the following sections, here's some basic troubleshooting: @@ -1234,8 +1252,8 @@ This will launch the Docker daemon and proxy all connections through mitmproxy. #### Running the Docker client -Now that we have mitmproxy and Docker running, we can attempt to login and push -a container image. You may need to run as root to do this. For example: +Now that we have mitmproxy and Docker running, we can attempt to sign in and +push a container image. You may need to run as root to do this. For example: ```shell docker login s3-testing.myregistry.com:5050 diff --git a/doc/administration/packages/dependency_proxy.md b/doc/administration/packages/dependency_proxy.md index fba3d51f741..56b39658dc2 100644 --- a/doc/administration/packages/dependency_proxy.md +++ b/doc/administration/packages/dependency_proxy.md @@ -4,11 +4,12 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# GitLab Dependency Proxy administration **(PREMIUM ONLY)** +# GitLab Dependency Proxy administration -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 13.6. -GitLab can be utilized as a dependency proxy for a variety of common package managers. +GitLab can be used as a dependency proxy for a variety of common package managers. This is the administration documentation. If you want to learn how to use the dependency proxies, see the [user guide](../../user/packages/dependency_proxy/index.md). diff --git a/doc/administration/packages/index.md b/doc/administration/packages/index.md index 0b3a7ae9fa5..4af0de864ca 100644 --- a/doc/administration/packages/index.md +++ b/doc/administration/packages/index.md @@ -6,26 +6,50 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Package Registry administration -GitLab Packages allows organizations to utilize GitLab as a private repository +GitLab Packages allows organizations to use GitLab as a private repository for a variety of common package managers. Users are able to build and publish packages, which can be easily consumed as a dependency in downstream projects. The Packages feature allows GitLab to act as a repository for the following: -| Software repository | Description | Available in GitLab version | -| ------------------- | ----------- | --------------------------- | -| [PyPI Repository](../../user/packages/pypi_repository/index.md) | The GitLab PyPI Repository enables every project in GitLab to have its own space to store [PyPI](https://pypi.org/) packages. | 12.10+ | -| [Composer Repository](../../user/packages/composer_repository/index.md) | The GitLab Composer Repository enables every project in GitLab to have its own space to store [Composer](https://getcomposer.org/) packages. | 13.1+ | -| [NuGet Repository](../../user/packages/nuget_repository/index.md) | The GitLab NuGet Repository enables every project in GitLab to have its own space to store [NuGet](https://www.nuget.org/) packages. | 12.8+ | -| [Conan Repository](../../user/packages/conan_repository/index.md) | The GitLab Conan Repository enables every project in GitLab to have its own space to store [Conan](https://conan.io/) packages. | 12.4+ | -| [Maven Repository](../../user/packages/maven_repository/index.md) | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. | 11.3+ | -| [NPM Registry](../../user/packages/npm_registry/index.md) | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. | 11.7+ | -| [Go Proxy](../../user/packages/go_proxy/index.md) | The Go proxy for GitLab enables every project in GitLab to be fetched with the [Go proxy protocol](https://proxy.golang.org/). | 13.1+ | -| [Generic packages](../../user/packages/generic_packages/index.md) | Store arbitrary files, like release binaries. | 13.5+ | - -Don't you see your package management system supported yet? -Please consider contributing -to GitLab. This [development documentation](../../development/packages.md) will guide you through the process. +The Package Registry supports the following formats: + +<div class="row"> +<div class="col-md-9"> +<table align="left" style="width:50%"> +<tr style="background:#dfdfdf"><th>Package type</th><th>GitLab version</th></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/composer_repository/index.html">Composer</a></td><td>13.2+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/conan_repository/index.html">Conan</a></td><td>12.6+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/go_proxy/index.html">Go</a></td><td>13.1+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/maven_repository/index.html">Maven</a></td><td>11.3+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/npm_registry/index.html">NPM</a></td><td>11.7+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/nuget_repository/index.html">NuGet</a></td><td>12.8+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/pypi_repository/index.html">PyPI</a></td><td>12.10+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/generic_packages/index.html">Generic packages</a></td><td>13.5+</td></tr> +</table> +</div> +</div> + +## Accepting contributions + +The below table lists formats that are not supported, but are accepting Community contributions for. Consider contributing to GitLab. This [development documentation](../../development/packages.md) will +guide you through the process. + +| Format | Status | +| ------ | ------ | +| Chef | [#36889](https://gitlab.com/gitlab-org/gitlab/-/issues/36889) | +| CocoaPods | [#36890](https://gitlab.com/gitlab-org/gitlab/-/issues/36890) | +| Conda | [#36891](https://gitlab.com/gitlab-org/gitlab/-/issues/36891) | +| CRAN | [#36892](https://gitlab.com/gitlab-org/gitlab/-/issues/36892) | +| Debian | [WIP: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44746) | +| Opkg | [#36894](https://gitlab.com/gitlab-org/gitlab/-/issues/36894) | +| P2 | [#36895](https://gitlab.com/gitlab-org/gitlab/-/issues/36895) | +| Puppet | [#36897](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | +| RPM | [#5932](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) | +| RubyGems | [#803](https://gitlab.com/gitlab-org/gitlab/-/issues/803) | +| SBT | [#36898](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | +| Terraform | [WIP: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) | +| Vagrant | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | ## Enabling the Packages feature @@ -58,6 +82,18 @@ To enable the Packages feature: 1. [Restart GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab") for the changes to take effect. +**Helm Chart installations** + +1. After the installation is complete, you will have to configure the `packages` + section in `global.appConfig.packages`. Set to `true` to enable it: + + ```yaml + packages: + enabled: true + ``` + +1. [Restart GitLab](../restart_gitlab.md#helm-chart-installations "How to reconfigure Helm GitLab") for the changes to take effect. + ## Changing the storage path By default, the packages are stored locally, but you can change the default diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 9f72293a730..0ebeb96d247 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -415,9 +415,6 @@ internet connectivity is gated by a proxy. To use a proxy for GitLab Pages: ### Using a custom Certificate Authority (CA) -NOTE: **Note:** -[Before 13.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4411), when using Omnibus, a [workaround was required](https://docs.gitlab.com/13.1/ee/administration/pages/index.html#using-a-custom-certificate-authority-ca). - When using certificates issued by a custom CA, [Access Control](../../user/project/pages/pages_access_control.md#gitlab-pages-access-control) and the [online view of HTML job artifacts](../../ci/pipelines/job_artifacts.md#browsing-artifacts) will fail to work if the custom CA is not recognized. @@ -462,6 +459,34 @@ are stored. 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +Alternatively, if you have existing Pages deployed you can follow +the below steps to do a no downtime transfer to a new storage location. + +1. Pause Pages deployments by setting the following in `/etc/gitlab/gitlab.rb`: + + ```ruby + sidekiq['experimental_queue_selector'] = true + sidekiq['queue_groups'] = [ + "feature_category!=pages" + ] + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. `rsync` contents from the current storage location to the new storage location: `sudo rsync -avzh --progress /var/opt/gitlab/gitlab-rails/shared/pages/ /mnt/storage/pages` +1. Set the new storage location in `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['pages_path'] = "/mnt/storage/pages" + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. Verify Pages are still being served up as expected. +1. Unpause Pages deployments by removing from `/etc/gitlab/gitlab.rb` the `sidekiq` setting set above. +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. Trigger a new Pages deployment and verify it's working as expected. +1. Remove the old Pages storage location: `sudo rm -rf /var/opt/gitlab/gitlab-rails/shared/pages` +1. Verify Pages are still being served up as expected. + ## Configure listener for reverse proxy requests Follow the steps below to configure the proxy listener of GitLab Pages. [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/2533) in @@ -514,7 +539,7 @@ your main application server. To configure GitLab Pages on a separate server: -DANGER: **Danger:** +DANGER: **Warning:** The following procedure includes steps to back up and edit the `gitlab-secrets.json` file. This file contains secrets that control database encryption. Proceed with caution. @@ -528,7 +553,6 @@ database encryption. Proceed with caution. 1. On the **GitLab server**, to enable Pages, add the following to `/etc/gitlab/gitlab.rb`: ```ruby - gitlab_pages['enable'] = true pages_external_url "http://<pages_server_URL>" ``` @@ -559,18 +583,11 @@ database encryption. Proceed with caution. to include: ```ruby - external_url 'http://<gitlab_server_IP_or_URL>' + roles ['pages_role'] + pages_external_url "http://<pages_server_URL>" - postgresql['enable'] = false - redis['enable'] = false - prometheus['enable'] = false - puma['enable'] = false - sidekiq['enable'] = false - gitlab_workhorse['enable'] = false - gitaly['enable'] = false - alertmanager['enable'] = false - node_exporter['enable'] = false - gitlab_rails['auto_migrate'] = false + + gitlab_pages['gitlab_server'] = 'http://<gitlab_server_IP_or_URL>' ``` 1. Create a backup of the secrets file on the **Pages server**: diff --git a/doc/administration/polling.md b/doc/administration/polling.md index a1077614677..17b8045b51f 100644 --- a/doc/administration/polling.md +++ b/doc/administration/polling.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Polling configuration The GitLab UI polls for updates for different resources (issue notes, issue diff --git a/doc/administration/postgresql/replication_and_failover.md b/doc/administration/postgresql/replication_and_failover.md index 0a40b61fd3c..a29815672e5 100644 --- a/doc/administration/postgresql/replication_and_failover.md +++ b/doc/administration/postgresql/replication_and_failover.md @@ -579,18 +579,19 @@ in the Troubleshooting section before proceeding. ### Ensure GitLab is running -At this point, your GitLab instance should be up and running. Verify you are -able to login, and create issues and merge requests. If you have troubles check +At this point, your GitLab instance should be up and running. Verify you're able +to sign in, and create issues and merge requests. If you encounter issues, see the [Troubleshooting section](#troubleshooting). ## Example configuration -Here we'll show you some fully expanded example configurations. +This section describes several fully expanded example configurations. ### Example recommended setup -This example uses 3 Consul servers, 3 PgBouncer servers (with associated internal load balancer), -3 PostgreSQL servers, and 1 application node. +This example uses three Consul servers, three PgBouncer servers (with an +associated internal load balancer), three PostgreSQL servers, and one +application node. We start with all servers on the same 10.6.0.0/16 private network range, they can connect to each freely other on those addresses. diff --git a/doc/administration/pseudonymizer.md b/doc/administration/pseudonymizer.md index 22543a5c743..41a7ec087ac 100644 --- a/doc/administration/pseudonymizer.md +++ b/doc/administration/pseudonymizer.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Pseudonymizer **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5532) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. @@ -44,7 +50,6 @@ To configure the pseudonymizer, you need to: } ``` - NOTE: **Note:** If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs. ```ruby diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md index bdccd6d5fe9..f61a3107b3d 100644 --- a/doc/administration/raketasks/check.md +++ b/doc/administration/raketasks/check.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Integrity check Rake task **(CORE ONLY)** GitLab provides Rake tasks to check the integrity of various components. diff --git a/doc/administration/raketasks/doctor.md b/doc/administration/raketasks/doctor.md index c97aa5a4de1..e6a6751f199 100644 --- a/doc/administration/raketasks/doctor.md +++ b/doc/administration/raketasks/doctor.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Geo +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Doctor Rake tasks **(CORE ONLY)** This is a collection of tasks to help investigate and repair @@ -15,7 +21,6 @@ Automatic resolution is not yet implemented. If you have values that cannot be decrypted, you can follow steps to reset them, see our docs on what to do [when the secrets file is lost](../../raketasks/backup_restore.md#when-the-secrets-file-is-lost). -NOTE: **Note:** This can take a very long time, depending on the size of your database, as it checks all rows in all tables. diff --git a/doc/administration/raketasks/geo.md b/doc/administration/raketasks/geo.md index 885d19903ed..0ee6fd8fc75 100644 --- a/doc/administration/raketasks/geo.md +++ b/doc/administration/raketasks/geo.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Geo +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Geo Rake Tasks **(PREMIUM ONLY)** The following Rake tasks are for [Geo installations](../geo/index.md). diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index 7f673a2c850..d549110c32f 100644 --- a/doc/administration/raketasks/github_import.md +++ b/doc/administration/raketasks/github_import.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitHub import **(CORE ONLY)** > [Introduced]( https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10308) in GitLab 9.1. diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md index 6d04a786d3a..821a72291fd 100644 --- a/doc/administration/raketasks/ldap.md +++ b/doc/administration/raketasks/ldap.md @@ -1,3 +1,9 @@ +--- +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # LDAP Rake tasks **(CORE ONLY)** The following are LDAP-related Rake tasks. diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index 553afba78e3..b93442be0a1 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Maintenance Rake tasks **(CORE ONLY)** GitLab provides Rake tasks for general maintenance. @@ -124,7 +130,6 @@ sudo gitlab-rake gitlab:check bundle exec rake gitlab:check RAILS_ENV=production ``` -NOTE: **Note:** Use `SANITIZE=true` for `gitlab:check` if you want to omit project names from the output. Example output: @@ -267,7 +272,7 @@ clear it. To clear all exclusive leases: -DANGER: **Danger:** +DANGER: **Warning:** Don't run it while GitLab or Sidekiq is running ```shell diff --git a/doc/administration/raketasks/project_import_export.md b/doc/administration/raketasks/project_import_export.md index 51e0e2e46b6..d83ab6e5cee 100644 --- a/doc/administration/raketasks/project_import_export.md +++ b/doc/administration/raketasks/project_import_export.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Project import/export administration **(CORE ONLY)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3050) in GitLab 8.9. diff --git a/doc/administration/raketasks/storage.md b/doc/administration/raketasks/storage.md index 896eafeb5f3..9b15f5ed4de 100644 --- a/doc/administration/raketasks/storage.md +++ b/doc/administration/raketasks/storage.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Repository storage Rake tasks **(CORE ONLY)** This is a collection of Rake tasks to help you list and migrate @@ -68,7 +74,7 @@ To have a summary and then a list of projects and their attachments using hashed ## Migrate to hashed storage -NOTE: **Note:** +DANGER: **Deprecated:** In GitLab 13.0, [hashed storage](../repository_storage_types.md#hashed-storage) is enabled by default and the legacy storage is deprecated. Support for legacy storage will be removed in GitLab 14.0. If you're on GitLab @@ -109,7 +115,6 @@ If you find it necessary, you can run this migration script again to schedule mi Any error or warning will be logged in Sidekiq's log file. -NOTE: **Note:** If [Geo](../geo/index.md) is enabled, each project that is successfully migrated generates an event to replicate the changes on any **secondary** nodes. @@ -118,7 +123,7 @@ commands below that helps you inspect projects and attachments in both legacy an ## Rollback from hashed storage to legacy storage -NOTE: **Deprecated:** +DANGER: **Deprecated:** In GitLab 13.0, [hashed storage](../repository_storage_types.md#hashed-storage) is enabled by default and the legacy storage is deprecated. Support for legacy storage will be removed in GitLab 14.0. If you're on GitLab diff --git a/doc/administration/raketasks/uploads/migrate.md b/doc/administration/raketasks/uploads/migrate.md index 8d61beea597..075b27fb70d 100644 --- a/doc/administration/raketasks/uploads/migrate.md +++ b/doc/administration/raketasks/uploads/migrate.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Uploads migrate Rake tasks **(CORE ONLY)** There is a Rake task for migrating uploads between different storage types. @@ -10,11 +16,10 @@ There is a Rake task for migrating uploads between different storage types. After [configuring the object storage](../../uploads.md#using-object-storage) for GitLab's uploads, use this task to migrate existing uploads from the local storage to the remote storage. -Read more about using [object storage with GitLab](../../object_storage.md). - -NOTE: **Note:** All of the processing will be done in a background worker and requires **no downtime**. +Read more about using [object storage with GitLab](../../object_storage.md). + ### All-in-one Rake task GitLab provides a wrapper Rake task that migrates all uploaded files (for example avatars, logos, @@ -93,7 +98,6 @@ gitlab-rake "gitlab:uploads:migrate[DesignManagement::DesignV432x230Uploader, De **Source Installation** -NOTE: **Note:** Use `RAILS_ENV=production` for every task. ```shell diff --git a/doc/administration/raketasks/uploads/sanitize.md b/doc/administration/raketasks/uploads/sanitize.md index 54aa62059cf..4f7c99babd8 100644 --- a/doc/administration/raketasks/uploads/sanitize.md +++ b/doc/administration/raketasks/uploads/sanitize.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Uploads sanitize Rake tasks **(CORE ONLY)** In GitLab 11.9 and later, EXIF data is automatically stripped from JPG or TIFF image uploads. diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index 7910905ce54..9f522e0d599 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -836,6 +836,12 @@ a node and change its status from primary to replica (and vice versa). # Set up password authentication for Redis (use the same password in all nodes). redis['password'] = 'REDIS_PRIMARY_PASSWORD_OF_FIRST_CLUSTER' + # Set the Redis Cache instance as an LRU + # 90% of available RAM in MB + redis['maxmemory'] = '13500mb' + redis['maxmemory_policy'] = "allkeys-lru" + redis['maxmemory_samples'] = 5 + ## Enable service discovery for Prometheus consul['enable'] = true consul['monitoring_service_discovery'] = true @@ -897,6 +903,12 @@ You can specify multiple roles, like sentinel and Redis, as: # to `6379`. #redis['master_port'] = 6379 + # Set the Redis Cache instance as an LRU + # 90% of available RAM in MB + redis['maxmemory'] = '13500mb' + redis['maxmemory_policy'] = "allkeys-lru" + redis['maxmemory_samples'] = 5 + ## Enable service discovery for Prometheus consul['enable'] = true consul['monitoring_service_discovery'] = true @@ -1335,6 +1347,13 @@ To configure the Sentinel Queues server: ## Configure Gitaly +NOTE: **Note:** +[Gitaly Cluster](../gitaly/praefect.md) support +for the Reference Architectures is being +worked on as a [collaborative effort](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/1) between the Quality Engineering and Gitaly teams. When this component has been verified +some Architecture specs will likely change as a result to support the new +and improved designed. + [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended that a Gitaly server node stores no more than 5 TB of data. Although this @@ -1988,7 +2007,7 @@ on what features you intend to use: | [Merge request diffs](../merge_request_diffs.md#using-object-storage) | Yes | | [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | | [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | -| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | +| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes | | [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | | [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No | | [Terraform state files](../terraform_state.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index bb6e2eb4376..b106f7bced1 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -836,6 +836,12 @@ a node and change its status from primary to replica (and vice versa). # Set up password authentication for Redis (use the same password in all nodes). redis['password'] = 'REDIS_PRIMARY_PASSWORD_OF_FIRST_CLUSTER' + # Set the Redis Cache instance as an LRU + # 90% of available RAM in MB + redis['maxmemory'] = '13500mb' + redis['maxmemory_policy'] = "allkeys-lru" + redis['maxmemory_samples'] = 5 + ## Enable service discovery for Prometheus consul['enable'] = true consul['monitoring_service_discovery'] = true @@ -897,6 +903,12 @@ You can specify multiple roles, like sentinel and Redis, as: # to `6379`. #redis['master_port'] = 6379 + # Set the Redis Cache instance as an LRU + # 90% of available RAM in MB + redis['maxmemory'] = '13500mb' + redis['maxmemory_policy'] = "allkeys-lru" + redis['maxmemory_samples'] = 5 + ## Enable service discovery for Prometheus consul['enable'] = true consul['monitoring_service_discovery'] = true @@ -1225,7 +1237,7 @@ To configure the Sentinel Queues server: 1. SSH in to the server that will host Sentinel. 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 package, with the same version + on the page, and to select the correct Omnibus GitLab 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: @@ -1335,6 +1347,13 @@ To configure the Sentinel Queues server: ## Configure Gitaly +NOTE: **Note:** +[Gitaly Cluster](../gitaly/praefect.md) support +for the Reference Architectures is being +worked on as a [collaborative effort](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/1) between the Quality Engineering and Gitaly teams. When this component has been verified +some Architecture specs will likely change as a result to support the new +and improved designed. + [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended that a Gitaly server node stores no more than 5 TB of data. Although this @@ -1988,7 +2007,7 @@ on what features you intend to use: | [Merge request diffs](../merge_request_diffs.md#using-object-storage) | Yes | | [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | | [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | -| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | +| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes | | [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | | [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No | | [Terraform state files](../terraform_state.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index 4863329b695..f4842a8568b 100644 --- a/doc/administration/reference_architectures/2k_users.md +++ b/doc/administration/reference_architectures/2k_users.md @@ -356,6 +356,13 @@ are supported and can be added if needed. ## Configure Gitaly +NOTE: **Note:** +[Gitaly Cluster](../gitaly/praefect.md) support +for the Reference Architectures is being +worked on as a [collaborative effort](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/1) between the Quality Engineering and Gitaly teams. When this component has been verified +some Architecture specs will likely change as a result to support the new +and improved designed. + [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended that a Gitaly server node stores no more than 5TB of data. Although this @@ -859,7 +866,7 @@ on what features you intend to use: | [Merge request diffs](../merge_request_diffs.md#using-object-storage) | Yes | | [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | | [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | -| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | +| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes | | [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | | [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No | | [Terraform state files](../terraform_state.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index 70d0cae6dfd..b5b3e4e0300 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -1058,6 +1058,13 @@ Refer to your preferred Load Balancer's documentation for further guidance. ## Configure Gitaly +NOTE: **Note:** +[Gitaly Cluster](../gitaly/praefect.md) support +for the Reference Architectures is being +worked on as a [collaborative effort](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/1) between the Quality Engineering and Gitaly teams. When this component has been verified +some Architecture specs will likely change as a result to support the new +and improved designed. + [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended that a Gitaly server node stores no more than 5 TB of data. Although this @@ -1735,7 +1742,7 @@ on what features you intend to use: | [Merge request diffs](../merge_request_diffs.md#using-object-storage) | Yes | | [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | | [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | -| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | +| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes | | [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | | [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No | | [Terraform state files](../terraform_state.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index 44fbe2db504..152eb9cb90d 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -836,6 +836,12 @@ a node and change its status from primary to replica (and vice versa). # Set up password authentication for Redis (use the same password in all nodes). redis['password'] = 'REDIS_PRIMARY_PASSWORD_OF_FIRST_CLUSTER' + # Set the Redis Cache instance as an LRU + # 90% of available RAM in MB + redis['maxmemory'] = '13500mb' + redis['maxmemory_policy'] = "allkeys-lru" + redis['maxmemory_samples'] = 5 + ## Enable service discovery for Prometheus consul['enable'] = true consul['monitoring_service_discovery'] = true @@ -897,6 +903,12 @@ You can specify multiple roles, like sentinel and Redis, as: # to `6379`. #redis['master_port'] = 6379 + # Set the Redis Cache instance as an LRU + # 90% of available RAM in MB + redis['maxmemory'] = '13500mb' + redis['maxmemory_policy'] = "allkeys-lru" + redis['maxmemory_samples'] = 5 + ## Enable service discovery for Prometheus consul['enable'] = true consul['monitoring_service_discovery'] = true @@ -1335,6 +1347,13 @@ To configure the Sentinel Queues server: ## Configure Gitaly +NOTE: **Note:** +[Gitaly Cluster](../gitaly/praefect.md) support +for the Reference Architectures is being +worked on as a [collaborative effort](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/1) between the Quality Engineering and Gitaly teams. When this component has been verified +some Architecture specs will likely change as a result to support the new +and improved designed. + [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended that a Gitaly server node stores no more than 5 TB of data. Although this @@ -1988,7 +2007,7 @@ on what features you intend to use: | [Merge request diffs](../merge_request_diffs.md#using-object-storage) | Yes | | [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | | [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | -| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | +| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes | | [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | | [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No | | [Terraform state files](../terraform_state.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index 9f83950a927..f023971bdc0 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -1057,6 +1057,13 @@ Refer to your preferred Load Balancer's documentation for further guidance. ## Configure Gitaly +NOTE: **Note:** +[Gitaly Cluster](../gitaly/praefect.md) support +for the Reference Architectures is being +worked on as a [collaborative effort](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/1) between the Quality Engineering and Gitaly teams. When this component has been verified +some Architecture specs will likely change as a result to support the new +and improved designed. + [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended that a Gitaly server node stores no more than 5 TB of data. Although this @@ -1734,7 +1741,7 @@ on what features you intend to use: | [Merge request diffs](../merge_request_diffs.md#using-object-storage) | Yes | | [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | | [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | -| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | +| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) | Yes | | [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | | [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No | | [Terraform state files](../terraform_state.md#using-object-storage) | Yes | diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md index 62645ad17a1..4108635ba2c 100644 --- a/doc/administration/reply_by_email.md +++ b/doc/administration/reply_by_email.md @@ -46,4 +46,4 @@ If it finds a reply key, it will be able to leave your reply as a comment on the entity the notification was about (issue, merge request, commit...). For more details about the `Message-ID`, `In-Reply-To`, and `References headers`, -please consult [RFC 5322](https://tools.ietf.org/html/rfc5322#section-3.6.4). +see [RFC 5322](https://tools.ietf.org/html/rfc5322#section-3.6.4). diff --git a/doc/administration/reply_by_email_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md index f4fcbefa403..aaadeef8bf5 100644 --- a/doc/administration/reply_by_email_postfix_setup.md +++ b/doc/administration/reply_by_email_postfix_setup.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Set up Postfix for incoming email This document will take you through the steps of setting up a basic Postfix mail @@ -85,9 +91,10 @@ The instructions make the assumption that you will be using the email address `i quit ``` - _**Note:** The `.` is a literal period on its own line._ + NOTE: **Note:** + The `.` is a literal period on its own line. - _**Note:** If you receive an error after entering `rcpt to: incoming@localhost` + If you receive an error after entering `rcpt to: incoming@localhost` then your Postfix `my_network` configuration is not correct. The error will say 'Temporary lookup failure'. See [Configure Postfix to receive email from the Internet](#configure-postfix-to-receive-email-from-the-internet)._ @@ -158,11 +165,11 @@ Courier, which we will install later to add IMAP authentication, requires mailbo q ``` - _**Note:** If `mail` returns an error `Maildir: Is a directory` then your + If `mail` returns an error `Maildir: Is a directory` then your version of `mail` doesn't support Maildir style mailboxes. Install `heirloom-mailx` by running `sudo apt-get install heirloom-mailx`. Then, try the above steps again, substituting `heirloom-mailx` for the `mail` - command._ + command. 1. Sign out of the `incoming` account, and go back to being `root`: @@ -265,7 +272,8 @@ Courier, which we will install later to add IMAP authentication, requires mailbo quit ``` - (Note: The `.` is a literal period on its own line) + NOTE: **Note:** + The `.` is a literal period on its own line. 1. Check if the `incoming` user received the email: diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index b272c4b463e..d2d492c8f1a 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -117,7 +117,7 @@ The output includes the project ID and the project name: > [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/1606) in GitLab 12.1. -DANGER: **Danger:** +DANGER: **Warning:** Do not run `git prune` or `git gc` in pool repositories! This can cause data loss in "real" repositories that depend on the pool in question. diff --git a/doc/administration/restart_gitlab.md b/doc/administration/restart_gitlab.md index 57f53fd6cc4..f6a4a39ad60 100644 --- a/doc/administration/restart_gitlab.md +++ b/doc/administration/restart_gitlab.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # How to restart GitLab Depending on how you installed GitLab, there are different methods to restart diff --git a/doc/administration/sidekiq.md b/doc/administration/sidekiq.md index 23e870dbb82..2cc6acc8c87 100644 --- a/doc/administration/sidekiq.md +++ b/doc/administration/sidekiq.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- @@ -92,7 +95,6 @@ you want using steps 1 and 2 from the GitLab downloads page. 1. Run `gitlab-ctl reconfigure`. -NOTE: **Note:** You will need to restart the Sidekiq nodes after an update has occurred and database migrations performed. @@ -111,7 +113,6 @@ prometheus['enable'] = false gitlab_rails['auto_migrate'] = false alertmanager['enable'] = false gitaly['enable'] = false -gitlab_monitor['enable'] = false gitlab_workhorse['enable'] = false nginx['enable'] = false postgres_exporter['enable'] = false diff --git a/doc/administration/smime_signing_email.md b/doc/administration/smime_signing_email.md index 6ded7fdd7d0..f5b40210e62 100644 --- a/doc/administration/smime_signing_email.md +++ b/doc/administration/smime_signing_email.md @@ -1,10 +1,15 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Signing outgoing email with S/MIME Notification emails sent by GitLab can be signed with S/MIME for improved security. -NOTE: **Note:** -Please be aware that S/MIME certificates and TLS/SSL certificates are not the +Be aware that S/MIME certificates and TLS/SSL certificates are not the same and are used for different purposes: TLS creates a secure channel, whereas S/MIME signs and/or encrypts the message itself @@ -21,7 +26,7 @@ files must be provided: Optionally, you can also provide a bundle of CA certs (PEM-encoded) to be included on each signature. This will typically be an intermediate CA. -NOTE: **Note:** +CAUTION: **Caution:** Be mindful of the access levels for your private keys and visibility to third parties. @@ -39,7 +44,6 @@ third parties. 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -NOTE: **Note:** The key needs to be readable by the GitLab system user (`git` by default). **For installations from source:** @@ -63,7 +67,6 @@ The key needs to be readable by the GitLab system user (`git` by default). 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. -NOTE: **Note:** The key needs to be readable by the GitLab system user (`git` by default). ### How to convert S/MIME PKCS#12 / PFX format to PEM encoding diff --git a/doc/administration/timezone.md b/doc/administration/timezone.md index 3cfee8630b7..bec82f66948 100644 --- a/doc/administration/timezone.md +++ b/doc/administration/timezone.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Changing your time zone The global time zone configuration parameter can be changed in `config/gitlab.yml`: @@ -15,7 +21,7 @@ To see all available time zones, run `bundle exec rake time:zones:all`. For Omnibus installations, run `gitlab-rake time:zones:all`. NOTE: **Note:** -Currently, this Rake task does not list timezones in TZInfo format required by Omnibus GitLab during a reconfigure: [#27209](https://gitlab.com/gitlab-org/gitlab/-/issues/27209). +This Rake task does not list timezones in TZInfo format required by Omnibus GitLab during a reconfigure: [#27209](https://gitlab.com/gitlab-org/gitlab/-/issues/27209). ## Changing time zone in Omnibus installations diff --git a/doc/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md index ef95bdc8602..d67c9963092 100644 --- a/doc/administration/troubleshooting/debug.md +++ b/doc/administration/troubleshooting/debug.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Debugging Tips Sometimes things don't work the way they should. Here are some tips on debugging issues out diff --git a/doc/administration/troubleshooting/diagnostics_tools.md b/doc/administration/troubleshooting/diagnostics_tools.md index 5912981ba6e..132f8524ca1 100644 --- a/doc/administration/troubleshooting/diagnostics_tools.md +++ b/doc/administration/troubleshooting/diagnostics_tools.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/administration/troubleshooting/elasticsearch.md b/doc/administration/troubleshooting/elasticsearch.md index 6de5bb71d75..12aa91e6f14 100644 --- a/doc/administration/troubleshooting/elasticsearch.md +++ b/doc/administration/troubleshooting/elasticsearch.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +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/#designated-technical-writers +--- + # Troubleshooting Elasticsearch To install and configure Elasticsearch, and for common and known issues, @@ -165,7 +171,7 @@ The first step is to confirm GitLab is using Elasticsearch for the search functi To do this: 1. Confirm the integration is enabled in **Admin Area > Settings > General**. -1. Confirm searches utilize Elasticsearch by accessing the rails console +1. Confirm searches use Elasticsearch by accessing the rails console (`sudo gitlab-rails console`) and running the following commands: ```rails diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index dbda889d370..cae4aa96f75 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -1,8 +1,11 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- -# GitLab Rails Console Cheat Sheet +# GitLab Rails Console Cheat Sheet **(CORE ONLY)** This is the GitLab Support Team's collection of information regarding the GitLab Rails console, for use while troubleshooting. It is listed here for transparency, @@ -43,6 +46,40 @@ instance_of_object.method(:foo).source_location project.method(:private?).source_location ``` +## Attributes + +View available attributes, formatted using pretty print (`pp`). + +For example, determine what attributes contain users' names and email addresses: + +```ruby +u = User.find_by_username('someuser') +pp u.attributes +``` + +Partial output: + +```plaintext +{"id"=>1234, + "email"=>"someuser@example.com", + "sign_in_count"=>99, + "name"=>"S User", + "username"=>"someuser", + "first_name"=>nil, + "last_name"=>nil, + "bot_type"=>nil} +``` + +Then make use of the attributes, [testing SMTP, for example](https://docs.gitlab.com/omnibus/settings/smtp.html#testing-the-smtp-configuration): + +```ruby +e = u.email +n = u.name +Notify.test_email(e, "Test email for #{n}", 'Test email').deliver_now +# +Notify.test_email(u.email, "Test email for #{u.name}", 'Test email').deliver_now +``` + ## Query the database using an ActiveRecord Model ```ruby @@ -145,7 +182,7 @@ project.repository.expire_exists_cache Project.update_all(visibility_level: 0) ``` -### Find & remove projects that are pending deletion +### Find projects that are pending deletion ```ruby # @@ -174,8 +211,6 @@ project = Project.find_by_full_path('group-changeme/project-changeme') ::Projects::DestroyService.new(project, user, {}).execute ``` -Next, run `sudo gitlab-rake gitlab:cleanup:repos` on the command line to finish. - ### Destroy a project ```ruby @@ -273,11 +308,11 @@ pp p.statistics # compare with earlier values ### Recreate -A Projects Wiki can be recreated by - -NOTE: **Note:** +CAUTION: **Caution:** This is a destructive operation, the Wiki will be empty. +A Projects Wiki can be recreated by this command: + ```ruby p = Project.find_by_full_path('<username-or-group>/<project-name>') ### enter your projects path @@ -423,7 +458,7 @@ user.skip_reconfirmation! User.active.count # Users taking a seat on the instance -License.current.current_active_users_count +User.billable.count # The historical max on the instance as of the past year ::HistoricalData.max_historical_user_count @@ -484,6 +519,16 @@ user.max_member_access_for_group group.id ## Groups +### Transfer group to another location + +```ruby +user = User.find_by_username('<username>') +group = Group.find_by_name("<group_name>") +parent_group = Group.find_by(id: "") # empty string amounts to root as parent +service = ::Groups::TransferService.new(group, user) +service.execute(parent_group) +``` + ### Count unique users in a group and sub-groups ```ruby @@ -813,7 +858,7 @@ Find this content in the [Container Registry troubleshooting docs](../packages/c ## Sidekiq -This content has been moved to the [Troubleshooting Sidekiq docs](./sidekiq.md). +This content has been moved to the [Troubleshooting Sidekiq docs](sidekiq.md). ## Redis @@ -954,3 +999,19 @@ project = Project.find_by_full_path('<group/project>') Geo::RepositorySyncService.new(project).execute ``` + +### Generate usage ping + +#### Generate or get the cached usage ping + +```ruby +Gitlab::UsageData.to_json +``` + +#### Generate a fresh new usage ping + +This will also refresh the cached usage ping displayed in the admin area + +```ruby +Gitlab::UsageData.to_json(force_refresh: true) +``` diff --git a/doc/administration/troubleshooting/group_saml_scim.md b/doc/administration/troubleshooting/group_saml_scim.md index 7492688ded0..efc8eaab198 100644 --- a/doc/administration/troubleshooting/group_saml_scim.md +++ b/doc/administration/troubleshooting/group_saml_scim.md @@ -1,4 +1,7 @@ --- +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/administration/troubleshooting/img/ADFS-determine-token-signing-certificate-fingerprint.png b/doc/administration/troubleshooting/img/ADFS-determine-token-signing-certificate-fingerprint.png Binary files differindex cd1b9db31d9..e24c994e996 100644 --- a/doc/administration/troubleshooting/img/ADFS-determine-token-signing-certificate-fingerprint.png +++ b/doc/administration/troubleshooting/img/ADFS-determine-token-signing-certificate-fingerprint.png diff --git a/doc/administration/troubleshooting/img/OneLogin-encryption.png b/doc/administration/troubleshooting/img/OneLogin-encryption.png Binary files differdeleted file mode 100644 index 2b811409bd0..00000000000 --- a/doc/administration/troubleshooting/img/OneLogin-encryption.png +++ /dev/null diff --git a/doc/administration/troubleshooting/img/network_monitor_xid.png b/doc/administration/troubleshooting/img/network_monitor_xid.png Binary files differindex 5392f77327f..7fc2cf47ea0 100644 --- a/doc/administration/troubleshooting/img/network_monitor_xid.png +++ b/doc/administration/troubleshooting/img/network_monitor_xid.png diff --git a/doc/administration/troubleshooting/index.md b/doc/administration/troubleshooting/index.md index 50f192b1983..8a4a0a4caac 100644 --- a/doc/administration/troubleshooting/index.md +++ b/doc/administration/troubleshooting/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Troubleshooting a GitLab installation Below are some resources to help you troubleshoot a GitLab installation diff --git a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md index 7c5a9e0d79f..21fd183dfd0 100644 --- a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md +++ b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- @@ -67,8 +70,7 @@ and they will assist you with any issues you are having. kubectl logs <pod-name> --previous ``` - NOTE: **Note:** - No logs are kept in the containers/pods themselves, everything is written to stdout. + No logs are kept in the containers/pods themselves. Everything is written to stdout. This is the principle of Kubernetes, read [Twelve-factor app](https://12factor.net/) for details. diff --git a/doc/administration/troubleshooting/linux_cheat_sheet.md b/doc/administration/troubleshooting/linux_cheat_sheet.md index f24234e1aff..b1042a9402b 100644 --- a/doc/administration/troubleshooting/linux_cheat_sheet.md +++ b/doc/administration/troubleshooting/linux_cheat_sheet.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- @@ -15,7 +18,6 @@ If you are administering GitLab you are expected to know these commands for your of choice. If you are a GitLab Support Engineer, consider this a cross-reference to translate `yum` -> `apt-get` and the like. -Note: **Note:** Most of the commands below have not been labeled as to which distribution they work on. Contributions are welcome to help add them. diff --git a/doc/administration/troubleshooting/log_parsing.md b/doc/administration/troubleshooting/log_parsing.md index 7914628a756..4e9e8cd591f 100644 --- a/doc/administration/troubleshooting/log_parsing.md +++ b/doc/administration/troubleshooting/log_parsing.md @@ -1,8 +1,14 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Parsing GitLab logs with `jq` We recommend using log aggregation and search tools like Kibana and Splunk whenever possible, but if they are not available you can still quickly parse -[GitLab logs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26311) in JSON format +[GitLab logs](../logs.md) in JSON format (the default in GitLab 12.0 and later) using [`jq`](https://stedolan.github.io/jq/). ## What is JQ? diff --git a/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md b/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md index a1485249b0e..475f3d56836 100644 --- a/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md +++ b/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Navigating GitLab via Rails console At the heart of GitLab is a web application [built using the Ruby on Rails @@ -379,7 +385,7 @@ User.find_by(username: 'root') User.find_by_any_email('user@example.com') ``` -Note: `find_by_any_email` is a custom method added by GitLab developers rather +The `find_by_any_email` method is a custom method added by GitLab developers rather than a Rails-provided default method. **Get a collection of admin users:** @@ -388,7 +394,7 @@ than a Rails-provided default method. User.admins ``` -Note: `admins` is a [scope convenience method](https://guides.rubyonrails.org/active_record_querying.html#scopes) +`admins` is a [scope convenience method](https://guides.rubyonrails.org/active_record_querying.html#scopes) which does `where(admin: true)` under the hood. **Get a project by its path:** @@ -397,7 +403,7 @@ which does `where(admin: true)` under the hood. Project.find_by_full_path('group/subgroup/project') ``` -Note: `find_by_full_path` is a custom method added by GitLab developers rather +`find_by_full_path` is a custom method added by GitLab developers rather than a Rails-provided default method. **Get a project's issue or merge request by its numeric ID:** @@ -408,7 +414,7 @@ project.issues.find_by(iid: 42) project.merge_requests.find_by(iid: 42) ``` -Note: `iid` means "internal ID" and is how we keep issue and merge request IDs +`iid` means "internal ID" and is how we keep issue and merge request IDs scoped to each GitLab project. **Get a group by its path:** @@ -448,7 +454,7 @@ Ci::Pipeline.find(4151) Ci::Build.find(66124) ``` -Note: The pipeline and job #ID numbers increment globally across your GitLab +The pipeline and job ID numbers increment globally across your GitLab instance, so there's no need to use an internal ID attribute to look them up, unlike with issues or merge requests. diff --git a/doc/administration/troubleshooting/postgresql.md b/doc/administration/troubleshooting/postgresql.md index 91ff6f6524a..d22e76a505a 100644 --- a/doc/administration/troubleshooting/postgresql.md +++ b/doc/administration/troubleshooting/postgresql.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- @@ -145,4 +148,4 @@ It may take a little while to respond. ``` NOTE: **Note:** -These are Omnibus 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 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. diff --git a/doc/administration/troubleshooting/sidekiq.md b/doc/administration/troubleshooting/sidekiq.md index b7762f8ac3e..d415aa0d980 100644 --- a/doc/administration/troubleshooting/sidekiq.md +++ b/doc/administration/troubleshooting/sidekiq.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Troubleshooting Sidekiq Sidekiq is the background job processor GitLab uses to asynchronously run @@ -7,12 +13,10 @@ may be filling up. Users will notice when this happens because new branches may not show up and merge requests may not be updated. The following are some troubleshooting steps that will help you diagnose the bottleneck. -NOTE: **Note:** GitLab administrators/users should consider working through these debug steps with GitLab Support so the backtraces can be analyzed by our team. It may reveal a bug or necessary improvement in GitLab. -NOTE: **Note:** In any of the backtraces, be wary of suspecting cases where every thread appears to be waiting in the database, Redis, or waiting to acquire a mutex. This **may** mean there's contention in the database, for example, @@ -22,19 +26,11 @@ preventing other threads from continuing. ## Log arguments to Sidekiq jobs -If you want to see what arguments are being passed to Sidekiq jobs you can set -the `SIDEKIQ_LOG_ARGUMENTS` [environment variable](https://docs.gitlab.com/omnibus/settings/environment-variables.html) to `1` (true). - -Example: - -```ruby -gitlab_rails['env'] = {"SIDEKIQ_LOG_ARGUMENTS" => "1"} -``` - -This does not log all job arguments. To avoid logging sensitive -information (for instance, password reset tokens), it logs numeric -arguments for all workers, with overrides for some specific workers -where their arguments are not sensitive. +[In GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44853) +some arguments passed to Sidekiq jobs are logged by default. +To avoid logging sensitive information (for instance, password reset tokens), +GitLab logs numeric arguments for all workers, with overrides for some specific +workers where their arguments are not sensitive. Example log output: @@ -49,6 +45,17 @@ arguments logs are limited to a maximum size of 10 kilobytes of text; any arguments after this limit will be discarded and replaced with a single argument containing the string `"..."`. +You can set `SIDEKIQ_LOG_ARGUMENTS` [environment variable](https://docs.gitlab.com/omnibus/settings/environment-variables.html) +to `0` (false) to disable argument logging. + +Example: + +```ruby +gitlab_rails['env'] = {"SIDEKIQ_LOG_ARGUMENTS" => "0"} +``` + +In GitLab 13.5 and earlier, set `SIDEKIQ_LOG_ARGUMENTS` to `1` to start logging arguments passed to Sidekiq. + ## Thread dump Send the Sidekiq process ID the `TTIN` signal and it will output thread @@ -127,7 +134,6 @@ corresponding Ruby code where this is happening. `gdb` can be another effective tool for debugging Sidekiq. It gives you a little more interactive way to look at each thread and see what's causing problems. -NOTE: **Note:** Attaching to a process with `gdb` will suspends the normal operation of the process (Sidekiq will not process jobs while `gdb` is attached). @@ -278,15 +284,15 @@ end ### Remove Sidekiq jobs for given parameters (destructive) -The general method to kill jobs conditionally is the following: +The general method to kill jobs conditionally is the following command, which +will remove jobs that are queued but not started. Running jobs will not be killed. ```ruby queue = Sidekiq::Queue.new('<queue name>') queue.each { |job| job.delete if <condition>} ``` -NOTE: **Note:** -This will remove jobs that are queued but not started, running jobs will not be killed. Have a look at the section below for cancelling running jobs. +Have a look at the section below for cancelling running jobs. In the method above, `<queue-name>` is the name of the queue that contains the job(s) you want to delete and `<condition>` will decide which jobs get deleted. @@ -294,7 +300,6 @@ Commonly, `<condition>` references the job arguments, which depend on the type o For example, `repository_import` has `project_id` as the job argument, while `update_merge_requests` has `project_id, user_id, oldrev, newrev, ref`. -NOTE: **Note:** Arguments need to be referenced by their sequence ID using `job.args[<id>]` because `job.args` is a list of all arguments provided to the Sidekiq job. Here are some examples: diff --git a/doc/administration/troubleshooting/ssl.md b/doc/administration/troubleshooting/ssl.md index 4d4b9755fa9..996856521b7 100644 --- a/doc/administration/troubleshooting/ssl.md +++ b/doc/administration/troubleshooting/ssl.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/administration/troubleshooting/test_environments.md b/doc/administration/troubleshooting/test_environments.md index 80ccd15aa22..9855a27ca30 100644 --- a/doc/administration/troubleshooting/test_environments.md +++ b/doc/administration/troubleshooting/test_environments.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/administration/troubleshooting/tracing_correlation_id.md b/doc/administration/troubleshooting/tracing_correlation_id.md index ae9ebd90951..8840c2706d6 100644 --- a/doc/administration/troubleshooting/tracing_correlation_id.md +++ b/doc/administration/troubleshooting/tracing_correlation_id.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index 91de089c45e..cd15301edf6 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Uploads administration **(CORE ONLY)** Uploads represent all user data that may be sent to GitLab as a single file. As an example, avatars and notes' attachments are uploads. Uploads are integral to GitLab functionality, and therefore cannot be disabled. @@ -16,7 +22,7 @@ were before. This change is deployed behind a feature flag that is **enabled by default**. If you experience any issues with upload, -[GitLab administrators with access to the GitLab Rails console](./feature_flags.md) +[GitLab administrators with access to the GitLab Rails console](feature_flags.md) can opt to disable it. To enable it: @@ -33,16 +39,15 @@ Feature.disable(:upload_middleware_jwt_params_handler) ## Using local storage -NOTE: **Note:** -This is the default configuration +This is the default configuration. To change the location where the uploads are +stored locally, use the steps in this section based on your installation method: -To change the location where the uploads are stored locally, follow the steps -below. - -**In Omnibus installations:** +**In Omnibus GitLab installations:** NOTE: **Note:** -For historical reasons, uploads are stored into a base directory, which by default is `uploads/-/system`. It is strongly discouraged to change this configuration option on an existing GitLab installation. +For historical reasons, uploads are stored into a base directory, which by +default is `uploads/-/system`. It's strongly discouraged to change this +configuration option for an existing GitLab installation. _The uploads are stored by default in `/var/opt/gitlab/gitlab-rails/uploads`._ @@ -86,7 +91,6 @@ This configuration relies on valid AWS credentials to be configured already. [Read more about using object storage with GitLab](object_storage.md). -NOTE: **Note:** We recommend using the [consolidated object storage settings](object_storage.md#consolidated-object-storage-configuration). The following instructions apply to the original configuration format. ## Object Storage Settings @@ -125,7 +129,6 @@ _The uploads are stored by default in } ``` - NOTE: **Note:** If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs. ```ruby diff --git a/doc/administration/user_settings.md b/doc/administration/user_settings.md index 7a3e1d86712..94ce1debfea 100644 --- a/doc/administration/user_settings.md +++ b/doc/administration/user_settings.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Modifying global user settings GitLab administrators can modify user settings for the entire GitLab instance. diff --git a/doc/api/README.md b/doc/api/README.md index 3f7dae055e2..3933431407c 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -1,10 +1,20 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # API Docs -Automate GitLab via a simple and powerful API. +Automate GitLab by using a simple and powerful API. -The main GitLab API is a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API. Therefore, documentation in this section assumes knowledge of REST concepts. +The main GitLab API is a [REST](http://spec.openapis.org/oas/v3.0.3) +API. Because of this, the documentation in this section assumes that you're +familiar with REST concepts. -There is also a partial [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/api/openapi/openapi.yaml), which allows you to test the API directly from the GitLab user interface. Contributions are welcome. +There's also a partial [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/api/openapi/openapi.yaml), +which allows you to test the API directly from the GitLab user interface. +Contributions are welcome. ## Available API resources @@ -13,21 +23,22 @@ For a list of the available resources and their endpoints, see ## SCIM **(SILVER ONLY)** -[GitLab.com Silver and above](https://about.gitlab.com/pricing/) provides an [SCIM API](scim.md) that implements [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644) and provides -the `/Users` endpoint. The base URL is: `/api/scim/v2/groups/:group_path/Users/`. +[GitLab.com Silver and higher](https://about.gitlab.com/pricing/) provides an +[SCIM API](scim.md) that both implements [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644) +and provides the `/Users` endpoint. The base URL is: `/api/scim/v2/groups/:group_path/Users/`. ## Road to GraphQL -[GraphQL](graphql/index.md) is available in GitLab, which will -allow deprecation of controller-specific endpoints. +[GraphQL](graphql/index.md) is available in GitLab, which allows for the +deprecation of controller-specific endpoints. -GraphQL has a number of benefits: +GraphQL has several benefits, including: -1. We avoid having to maintain two different APIs. -1. Callers of the API can request only what they need. -1. It is versioned by default. +- We avoid having to maintain two different APIs. +- Callers of the API can request only what they need. +- It's versioned by default. -It will co-exist with the current v4 REST API. If we have a v5 API, this should +GraphQL co-exists with the current v4 REST API. If we have a v5 API, this should be a compatibility layer on top of GraphQL. Although there were some patenting and licensing concerns with GraphQL, these @@ -37,33 +48,35 @@ specification. ## Compatibility guidelines -The HTTP API is versioned using a single number, the current one being 4. This -number symbolizes the same as the major version number as described by -[SemVer](https://semver.org/). This mean that backward incompatible changes -will require this version number to change. However, the minor version is -not explicit. This allows for a stable API endpoint, but also means new -features can be added to the API in the same version number. +The HTTP API is versioned using a single number, (currently _4_). This number +symbolizes the major version number, as described by [SemVer](https://semver.org/). +Because of this, backwards-incompatible changes require this version number to +change. However, the minor version isn't explicit, allowing for a stable API +endpoint. This also means that new features can be added to the API in the same +version number. New features and bug fixes are released in tandem with a new GitLab, and apart from incidental patch and security releases, are released on the 22nd of each -month. Backward incompatible changes (e.g. endpoints removal, parameters -removal etc.), as well as removal of entire API versions are done in tandem -with a major point release of GitLab itself. All deprecations and changes -between two versions should be listed in the documentation. For the changes -between v3 and v4; please read the [v3 to v4 documentation](v3_to_v4.md) +month. Backward incompatible changes (for example, endpoints removal and +parameters removal), and removal of entire API versions are done in tandem with +a major point release of GitLab itself. All deprecations and changes between two +versions should be listed in the documentation. For the changes between v3 and +v4, see the [v3 to v4 documentation](v3_to_v4.md). ### Current status -Currently only API version v4 is available. Version v3 was removed in +Only API version v4 is available. Version v3 was removed in [GitLab 11.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36819). ## Basic usage -API requests should be prefixed with `api` and the API version. The API version -is defined in [`lib/api.rb`](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/api/api.rb). For example, the root of the v4 API -is at `/api/v4`. +API requests should be prefixed with both `api` and the API version. The API +version is defined in [`lib/api.rb`](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/api/api.rb). +For example, the root of the v4 API is at `/api/v4`. The following sections illustrate different uses: + +### Valid API request -Example of a valid API request using cURL: +If you have a GitLab instance at `gitlab.example.com`: ```shell curl "https://gitlab.example.com/api/v4/projects" @@ -72,32 +85,56 @@ curl "https://gitlab.example.com/api/v4/projects" The API uses JSON to serialize data. You don't need to specify `.json` at the end of an API URL. +### API request to expose HTTP response headers + +If you want to expose HTTP response headers, use the `--include` option: + +```shell +curl --include "https://gitlab.example.com/api/v4/projects" +HTTP/2 200 +... +``` + +This can help you investigate an unexpected response. + +### API Request that includes the exit code + +If you want to expose the HTTP exit code, include the `--fail` option: + +```shell script +curl --fail "https://gitlab.example.com/api/v4/does-not-exist" +curl: (22) The requested URL returned error: 404 +``` + +The HTTP exit code can help you diagnose the success or failure of your REST call. + ## Authentication -Most API requests require authentication, or will only return public data when -authentication is not provided. For -those cases where it is not required, this will be mentioned in the documentation -for each individual endpoint. For example, the [`/projects/:id` endpoint](projects.md#get-single-project). +Most API requests require authentication, or will return public data only when +authentication isn't provided. For cases where it isn't required, this will be +mentioned in the documentation for each individual endpoint (for example, the +[`/projects/:id` endpoint](projects.md#get-single-project)). -There are several ways to authenticate with the GitLab API: +There are several methods you can use to authenticate with the GitLab API: -1. [OAuth2 tokens](#oauth2-tokens) -1. [Personal access tokens](../user/profile/personal_access_tokens.md) -1. [Project access tokens](../user/project/settings/project_access_tokens.md) +- [OAuth2 tokens](#oauth2-tokens) +- [Personal access tokens](../user/profile/personal_access_tokens.md) +- [Project access tokens](../user/project/settings/project_access_tokens.md) +- [Session cookie](#session-cookie) +- [GitLab CI/CD job token](#gitlab-ci-job-token) **(Specific endpoints only)** NOTE: **Note:** -Project access tokens are supported for self-managed instances on Core and above. They are also supported on GitLab.com Bronze and above. +Project access tokens are supported for self-managed instances on Core and +higher. They're also supported on GitLab.com Bronze and higher. -1. [Session cookie](#session-cookie) -1. [GitLab CI/CD job token](#gitlab-ci-job-token) **(Specific endpoints only)** +For administrators who want to authenticate with the API as a specific user, or who want +to build applications or scripts that do so, the following options are available: -For admins who want to authenticate with the API as a specific user, or who want to build applications or scripts that do so, two options are available: +- [Impersonation tokens](#impersonation-tokens) +- [Sudo](#sudo) -1. [Impersonation tokens](#impersonation-tokens) -1. [Sudo](#sudo) - -If authentication information is invalid or omitted, an error message will be -returned with status code `401`: +If authentication information is invalid or omitted, GitLab will return an error +message with a status code of `401`: ```json { @@ -107,8 +144,8 @@ returned with status code `401`: ### OAuth2 tokens -You can use an [OAuth2 token](oauth2.md) to authenticate with the API by passing it in either the -`access_token` parameter or the `Authorization` header. +You can use an [OAuth2 token](oauth2.md) to authenticate with the API by passing +it in either the `access_token` parameter or the `Authorization` header. Example of using the OAuth2 token in a parameter: @@ -126,22 +163,22 @@ Read more about [GitLab as an OAuth2 provider](oauth2.md). ### Personal/project access tokens -Access tokens can be used to authenticate with the API by passing it in either the `private_token` parameter -or the `PRIVATE-TOKEN` header. +You can use access tokens to authenticate with the API by passing it in either +the `private_token` parameter or the `PRIVATE-TOKEN` header. -Example of using the personal/project access token in a parameter: +Example of using the personal or project access token in a parameter: ```shell curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>" ``` -Example of using the personal/project access token in a header: +Example of using the personal or project access token in a header: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects" ``` -You can also use personal/project access tokens with OAuth-compliant headers: +You can also use personal or project access tokens with OAuth-compliant headers: ```shell curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/projects" @@ -150,12 +187,12 @@ curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.exampl ### Session cookie When signing in to the main GitLab application, a `_gitlab_session` cookie is -set. The API will use this cookie for authentication if it is present, but using -the API to generate a new session cookie is currently not supported. +set. The API uses this cookie for authentication if it's present. Using the +API to generate a new session cookie isn't supported. -The primary user of this authentication method is the web frontend of GitLab itself, -which can use the API as the authenticated user to get a list of their projects, -for example, without needing to explicitly pass an access token. +The primary user of this authentication method is the web frontend of GitLab +itself, which can, for example, use the API as the authenticated user to get a +list of their projects without needing to explicitly pass an access token. ### GitLab CI job token @@ -165,15 +202,17 @@ to authenticate with the API: - Packages: - [Composer Repository](../user/packages/composer_repository/index.md) - [Conan Repository](../user/packages/conan_repository/index.md) - - [Container Registry](../user/packages/container_registry/index.md) (`$CI_REGISTRY_PASSWORD` is actually `$CI_JOB_TOKEN`, but this may change in the future) + - [Container Registry](../user/packages/container_registry/index.md) + (`$CI_REGISTRY_PASSWORD` is actually `$CI_JOB_TOKEN`, but this may change in + the future) - [Go Proxy](../user/packages/go_proxy/index.md) - - [Maven Repository](../user/packages/maven_repository/index.md#authenticate-with-a-ci-job-token) - - [NPM Repository](../user/packages/npm_registry/index.md#authenticating-with-a-ci-job-token) + - [Maven Repository](../user/packages/maven_repository/index.md#authenticate-with-a-ci-job-token-in-maven) + - [NPM Repository](../user/packages/npm_registry/index.md#authenticate-with-a-ci-job-token) - [Nuget Repository](../user/packages/nuget_repository/index.md) - - [PyPI Repository](../user/packages/pypi_repository/index.md#using-gitlab-ci-with-pypi-packages) + - [PyPI Repository](../user/packages/pypi_repository/index.md#authenticate-with-a-ci-job-token) - [Generic packages](../user/packages/generic_packages/index.md#publish-a-generic-package-by-using-cicd) - [Get job artifacts](job_artifacts.md#get-job-artifacts) -- [Pipeline triggers](pipeline_triggers.md) (via `token=` parameter) +- [Pipeline triggers](pipeline_triggers.md) (using the `token=` parameter) - [Release creation](releases/index.md#create-a-release) - [Terraform plan](../user/infrastructure/index.md) @@ -181,21 +220,22 @@ The token is valid as long as the job is running. ### Impersonation tokens -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9099) in GitLab 9.0. Needs admin permissions. - Impersonation tokens are a type of [personal access token](../user/profile/personal_access_tokens.md) that can only be created by an admin for a specific user. They are a great fit -if you want to build applications or scripts that authenticate with the API as a specific user. +if you want to build applications or scripts that authenticate with the API as a +specific user. -They are an alternative to directly using the user's password or one of their -personal access tokens, and to using the [Sudo](#sudo) feature, since the user's (or admin's, in the case of Sudo) -password/token may not be known or may change over time. +They're an alternative to directly using the user's password or one of their +personal access tokens, and to using the [Sudo](#sudo) feature, as the user's +(or admin's, in the case of Sudo) password or token may not be known, or may +change over time. -For more information, refer to the -[users API](users.md#create-an-impersonation-token) docs. +For more information, see the [users API](users.md#create-an-impersonation-token) +documentation. -Impersonation tokens are used exactly like regular personal access tokens, and can be passed in either the -`private_token` parameter or the `PRIVATE-TOKEN` header. +Impersonation tokens are used exactly like regular personal access tokens, and +can be passed in either the `private_token` parameter or the `PRIVATE-TOKEN` +header. #### Disable impersonation @@ -214,7 +254,8 @@ By default, impersonation is enabled. To disable impersonation: 1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect. -To re-enable impersonation, remove this configuration and reconfigure GitLab. +To re-enable impersonation, remove this configuration, and then reconfigure +GitLab. **For installations from source** @@ -228,26 +269,22 @@ To re-enable impersonation, remove this configuration and reconfigure GitLab. 1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect. -To re-enable impersonation, remove this configuration and restart GitLab. +To re-enable impersonation, remove this configuration, and then restart GitLab. ### Sudo -NOTE: **Note:** -Only available to [administrators](../user/permissions.md). - All API requests support performing an API call as if you were another user, -provided you are authenticated as an administrator with an OAuth or Personal Access Token that has the `sudo` scope. -The API requests are executed with the permissions of the impersonated user. +provided you're authenticated as an administrator with an OAuth or personal +access token that has the `sudo` scope. The API requests are executed with the +permissions of the impersonated user. -You need to pass the `sudo` parameter either via query string or a header with an ID/username of -the user you want to perform the operation as. If passed as a header, the -header name must be `Sudo`. +As an [administrator](../user/permissions.md), pass the `sudo` parameter either +by using query string or a header with an ID or username (case insensitive) of +the user you want to perform the operation as. If passed as a header, the header +name must be `Sudo`. -NOTE: **Note:** -Usernames are case insensitive. - -If a non administrative access token is provided, an error message will -be returned with status code `403`: +If a non administrative access token is provided, GitLab returns an error +message with a status code of `403`: ```json { @@ -256,7 +293,7 @@ be returned with status code `403`: ``` If an access token without the `sudo` scope is provided, an error message will -be returned with status code `403`: +be returned with a status code of `403`: ```json { @@ -267,7 +304,7 @@ be returned with status code `403`: ``` If the sudo user ID or username cannot be found, an error message will be -returned with status code `404`: +returned with a status code of `404`: ```json { @@ -305,27 +342,27 @@ insight into what went wrong. The following table gives an overview of how the API functions generally behave. -| Request type | Description | -| ------------ | ----------- | -| `GET` | Access one or more resources and return the result as JSON. | -| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. | +| Request type | Description | +|---------------|-------------| +| `GET` | Access one or more resources and return the result as JSON. | +| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. | | `GET` / `PUT` | Return `200 OK` if the resource is accessed or modified successfully. The (modified) result is returned as JSON. | -| `DELETE` | Returns `204 No Content` if the resource was deleted successfully. | +| `DELETE` | Returns `204 No Content` if the resource was deleted successfully. | The following table shows the possible return codes for API requests. | Return values | Description | -| ------------------------ | ----------- | +|--------------------------|-------------| | `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. | | `204 No Content` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. | | `201 Created` | The `POST` request was successful and the resource is returned as JSON. | | `304 Not Modified` | Indicates that the resource has not been modified since the last request. | | `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. | | `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. | -| `403 Forbidden` | The request is not allowed, e.g., the user is not allowed to delete a project. | -| `404 Not Found` | A resource could not be accessed, e.g., an ID for a resource could not be found. | +| `403 Forbidden` | The request is not allowed. For example, the user is not allowed to delete a project. | +| `404 Not Found` | A resource could not be accessed. For example, an ID for a resource could not be found. | | `405 Method Not Allowed` | The request is not supported. | -| `409 Conflict` | A conflicting resource already exists, e.g., creating a project with a name that already exists. | +| `409 Conflict` | A conflicting resource already exists. For example, creating a project with a name that already exists. | | `412` | Indicates the request was denied. May happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. | | `422 Unprocessable` | The entity could not be processed. | | `429 Too Many Requests` | The user exceeded the [application rate limits](../administration/instance_limits.md#rate-limits). | @@ -333,26 +370,26 @@ The following table shows the possible return codes for API requests. ## Pagination -We support two kinds of pagination methods: +GitLab supports the following pagination methods: - Offset-based pagination. This is the default method and available on all endpoints. - Keyset-based pagination. Added to selected endpoints but being [progressively rolled out](https://gitlab.com/groups/gitlab-org/-/epics/2039). -For large collections, we recommend keyset pagination (when available) over offset -pagination for performance reasons. +For large collections, we recommend keyset pagination (when available) instead +of offset pagination for performance reasons. ### Offset-based pagination -Sometimes the returned result will span across many pages. When listing -resources you can pass the following parameters: +Sometimes, the returned result spans many pages. When listing resources, you can +pass the following parameters: | Parameter | Description | -| --------- | ----------- | -| `page` | Page number (default: `1`) | -| `per_page`| Number of items to list per page (default: `20`, max: `100`) | +|-----------|-------------| +| `page` | Page number (default: `1`). | +| `per_page`| Number of items to list per page (default: `20`, max: `100`). | -In the example below, we list 50 [namespaces](namespaces.md) per page. +In the following example, we list 50 [namespaces](namespaces.md) per page: ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces?per_page=50" @@ -361,15 +398,14 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab #### Pagination `Link` header [`Link` headers](https://www.w3.org/wiki/LinkHeader) are returned with each -response. They have `rel` set to `prev`/`next`/`first`/`last` and contain the -relevant URL. Be sure to use these links instead of generating your own URLs. +response. They have `rel` set to `prev`, `next`, `first`, or `last` and contain +the relevant URL. Be sure to use these links instead of generating your own URLs. -NOTE: **Note:** For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers). -In the cURL example below, we limit the output to 3 items per page (`per_page=3`) -and we request the second page (`page=2`) of [comments](notes.md) of the issue -with ID `8` which belongs to the project with ID `9`: +In the following cURL example, we limit the output to three items per page +(`per_page=3`) and we request the second page (`page=2`) of [comments](notes.md) +of the issue with ID `8` which belongs to the project with ID `9`: ```shell curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2" @@ -400,31 +436,32 @@ x-total-pages: 3 GitLab also returns the following additional pagination headers: -| Header | Description | -| --------------- | --------------------------------------------- | -| `x-total` | The total number of items | -| `x-total-pages` | The total number of pages | -| `x-per-page` | The number of items per page | -| `x-page` | The index of the current page (starting at 1) | -| `x-next-page` | The index of the next page | -| `X-prev-page` | The index of the previous page | +| Header | Description | +|-----------------|-------------| +| `x-next-page` | The index of the next page. | +| `x-page` | The index of the current page (starting at 1). | +| `x-per-page` | The number of items per page. | +| `X-prev-page` | The index of the previous page. | +| `x-total` | The total number of items. | +| `x-total-pages` | The total number of pages. | -NOTE: **Note:** For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers). ### Keyset-based pagination -Keyset-pagination allows for more efficient retrieval of pages and - in contrast to offset-based pagination - runtime -is independent of the size of the collection. +Keyset-pagination allows for more efficient retrieval of pages and - in contrast +to offset-based pagination - runtime is independent of the size of the +collection. This method is controlled by the following parameters: -| Parameter | Description | -| ------------ | -------------------------------------- | -| `pagination` | `keyset` (to enable keyset pagination) | -| `per_page` | Number of items to list per page (default: `20`, max: `100`) | +| Parameter | Description | +|--------------| ------------| +| `pagination` | `keyset` (to enable keyset pagination). | +| `per_page` | Number of items to list per page (default: `20`, max: `100`). | -In the example below, we list 50 [projects](projects.md) per page, ordered by `id` ascending. +In the following example, we list 50 [projects](projects.md) per page, ordered +by `id` ascending. ```shell curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc" @@ -442,27 +479,34 @@ Status: 200 OK ``` CAUTION: **Deprecation:** -The `Links` header will be removed in GitLab 14.0 to be aligned with the [W3C `Link` specification](https://www.w3.org/wiki/LinkHeader). -The `Link` header was [added in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714) +The `Links` header will be removed in GitLab 14.0 to be aligned with the +[W3C `Link` specification](https://www.w3.org/wiki/LinkHeader). The `Link` +header was [added in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714) and should be used instead. -The link to the next page contains an additional filter `id_after=42` which excludes records we have retrieved already. -Note the type of filter depends on the `order_by` option used and we may have more than one additional filter. +The link to the next page contains an additional filter `id_after=42` that +excludes already-retrieved records. Note the type of filter depends on the +`order_by` option used, and we may have more than one additional filter. -When the end of the collection has been reached and there are no additional records to retrieve, the `Link` header is absent and the resulting array is empty. +When the end of the collection has been reached and there are no additional +records to retrieve, the `Link` header is absent and the resulting array is +empty. -We recommend using only the given link to retrieve the next page instead of building your own URL. Apart from the headers shown, -we don't expose additional pagination headers. +We recommend using only the given link to retrieve the next page instead of +building your own URL. Apart from the headers shown, we don't expose additional +pagination headers. -Keyset-based pagination is only supported for selected resources and ordering options: +Keyset-based pagination is supported only for selected resources and ordering +options: -| Resource | Order | -| ------------------------- | -------------------------- | -| [Projects](projects.md) | `order_by=id` only | +| Resource | Order | +|-------------------------|-------| +| [Projects](projects.md) | `order_by=id` only. | ## Path parameters -If an endpoint has path parameters, the documentation shows them with a preceding colon. +If an endpoint has path parameters, the documentation displays them with a +preceding colon. For example: @@ -470,7 +514,9 @@ For example: DELETE /projects/:id/share/:group_id ``` -The `:id` path parameter needs to be replaced with the project ID, and the `:group_id` needs to be replaced with the ID of the group. The colons `:` should not be included. +The `:id` path parameter needs to be replaced with the project ID, and the +`:group_id` needs to be replaced with the ID of the group. The colons `:` +shouldn't be included. The resulting cURL call for a project with ID `5` and a group ID of `17` is then: @@ -478,11 +524,10 @@ The resulting cURL call for a project with ID `5` and a group ID of `17` is then curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17" ``` -NOTE: **Note:** Path parameters that are required to be URL-encoded must be followed. If not, -it will not match an API endpoint and respond with a 404. If there's something -in front of the API (for example, Apache), ensure that it won't decode the URL-encoded -path parameters. +it won't match an API endpoint, and will respond with a 404. If there's +something in front of the API (for example, Apache), ensure that it won't decode +the URL-encoded path parameters. ## Namespaced path encoding @@ -495,10 +540,9 @@ For example, `/` is represented by `%2F`: GET /api/v4/projects/diaspora%2Fdiaspora ``` -NOTE: **Note:** -A project's **path** is not necessarily the same as its **name**. A -project's path can be found in the project's URL or in the project's settings -under **General > Advanced > Change path**. +A project's _path_ isn't necessarily the same as its _name_. A project's path is +found in the project's URL or in the project's settings, under +**General > Advanced > Change path**. ## File path, branches, and tags name encoding @@ -516,7 +560,8 @@ GET /api/v4/projects/1/repository/tags/my%2Ftag API Requests can use parameters sent as [query strings](https://en.wikipedia.org/wiki/Query_string) or as a [payload body](https://tools.ietf.org/html/draft-ietf-httpbis-p3-payload-14#section-3.2). -GET requests usually send a query string, while PUT/POST requests usually send the payload body: +GET requests usually send a query string, while PUT or POST requests usually +send the payload body: - Query string: @@ -530,13 +575,13 @@ GET requests usually send a query string, while PUT/POST requests usually send t curl --request POST --header "Content-Type: application/json" --data '{"name":"<example-name>", "description":"<example-description"}' "https://gitlab/api/v4/projects" ``` -URL encoded query strings have a length limitation. Requests that are too large will -result in a `414 Request-URI Too Large` error message. This can be resolved by using -a payload body instead. +URL encoded query strings have a length limitation. Requests that are too large +result in a `414 Request-URI Too Large` error message. This can be resolved by +using a payload body instead. ## Encoding API parameters of `array` and `hash` types -We can call the API with `array` and `hash` types parameters as shown below: +We can call the API with `array` and `hash` types parameters as follows: ### `array` @@ -565,7 +610,8 @@ https://gitlab.example.com/api/v4/projects/import ### Array of hashes -`variables` is a parameter of type `array` containing hash key/value pairs `[{ 'key': 'UPLOAD_TO_S3', 'value': 'true' }]`: +`variables` is a parameter of type `array` containing hash key/value pairs +`[{ 'key': 'UPLOAD_TO_S3', 'value': 'true' }]`: ```shell curl --globoff --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -579,34 +625,37 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ ## `id` vs `iid` - Some resources have two similarly-named fields. For example, [issues](issues.md), [merge requests](merge_requests.md), and [project milestones](merge_requests.md). The fields are: +Some resources have two similarly-named fields. For example, [issues](issues.md), +[merge requests](merge_requests.md), and [project milestones](merge_requests.md). +The fields are: - `id`: ID that is unique across all projects. -- `iid`: additional, internal ID that is unique in the scope of a single project. +- `iid`: Additional, internal ID (displayed in the web UI) that's unique in the + scope of a single project. -NOTE: **Note:** -The `iid` is displayed in the web UI. - -If a resource has the `iid` field and the `id` field, the `iid` field is usually used instead of `id` to fetch the resource. +If a resource has both the `iid` field and the `id` field, the `iid` field is +usually used instead of `id` to fetch the resource. -For example, suppose a project with `id: 42` has an issue with `id: 46` and `iid: 5`. In this case: +For example, suppose a project with `id: 42` has an issue with `id: 46` and +`iid: 5`. In this case: -- A valid API call to retrieve the issue is `GET /projects/42/issues/5` +- A valid API call to retrieve the issue is `GET /projects/42/issues/5`. - An invalid API call to retrieve the issue is `GET /projects/42/issues/46`. -NOTE: **Note:** -Not all resources with the `iid` field are fetched by `iid`. For guidance on which field to use, see the documentation for the specific resource. +Not all resources with the `iid` field are fetched by `iid`. For guidance +regarding which field to use, see the documentation for the specific resource. ## Data validation and error reporting When working with the API you may encounter validation errors, in which case -the API will answer with an HTTP `400` status. +the API returns an HTTP `400` error. -Such errors appear in two cases: +Such errors appear in the following cases: -- A required attribute of the API request is missing, e.g., the title of an - issue is not given -- An attribute did not pass the validation, e.g., the user bio is too long +- A required attribute of the API request is missing (for example, the title of + an issue isn't given). +- An attribute did not pass the validation (for example, the user bio is too + long). When an attribute is missing, you will get something like: @@ -618,8 +667,8 @@ Content-Type: application/json } ``` -When a validation error occurs, error messages will be different. They will -hold all details of validation errors: +When a validation error occurs, error messages will be different. They will hold +all details of validation errors: ```http HTTP/1.1 400 Bad Request @@ -657,7 +706,8 @@ follows: ## Unknown route -When you try to access an API URL that does not exist, you will receive 404 Not Found. +When you attempt to access an API URL that doesn't exist, you will receive +404 Not Found message. ```http HTTP/1.1 404 Not Found @@ -669,10 +719,10 @@ Content-Type: application/json ## Encoding `+` in ISO 8601 dates -If you need to include a `+` in a query parameter, you may need to use `%2B` instead due -to a [W3 recommendation](http://www.w3.org/Addressing/URL/4_URI_Recommentations.html) that -causes a `+` to be interpreted as a space. For example, in an ISO 8601 date, you may want to pass -a time in Mountain Standard Time, such as: +If you need to include a `+` in a query parameter, you may need to use `%2B` +instead, due to a [W3 recommendation](http://www.w3.org/Addressing/URL/4_URI_Recommentations.html) +that causes a `+` to be interpreted as a space. For example, in an ISO 8601 date, +you may want to include a specific time in ISO 8601 format, such as: ```plaintext 2017-10-17T23:11:13.000+05:30 @@ -686,8 +736,8 @@ The correct encoding for the query parameter would be: ## Clients -There are many unofficial GitLab API Clients for most of the popular -programming languages. Visit the [GitLab website](https://about.gitlab.com/partners/#api-clients) for a complete list. +There are many unofficial GitLab API Clients for most of the popular programming +languages. For a complete list, visit the [GitLab website](https://about.gitlab.com/partners/#api-clients). ## Rate limits diff --git a/doc/api/admin_sidekiq_queues.md b/doc/api/admin_sidekiq_queues.md index 22488d053b4..8e1f7260208 100644 --- a/doc/api/admin_sidekiq_queues.md +++ b/doc/api/admin_sidekiq_queues.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Sidekiq queues administration API **(CORE ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25998) in GitLab 12.9 diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index 199b244b2c3..7ef3b5fcbb6 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # API resources Available resources for the [GitLab API](README.md) can be grouped in the following contexts: @@ -34,6 +40,7 @@ The following API resources are available in the project context: | [Events](events.md) | `/projects/:id/events` (also available for users and standalone) | | [Feature Flags](feature_flags.md) | `/projects/:id/feature_flags` | | [Feature Flag User Lists](feature_flag_user_lists.md) | `/projects/:id/feature_flags_user_lists` | +| [Invitations](invitations.md) | `/projects/:id/invitations` (also available for groups) | | [Issues](issues.md) | `/projects/:id/issues` (also available for groups and standalone) | | [Issues Statistics](issues_statistics.md) | `/projects/:id/issues_statistics` (also available for groups and standalone) | | [Issue boards](boards.md) | `/projects/:id/boards` | @@ -102,6 +109,7 @@ The following API resources are available in the group context: | [Group labels](group_labels.md) | `/groups/:id/labels` | | [Group-level variables](group_level_variables.md) | `/groups/:id/variables` | | [Group milestones](group_milestones.md) | `/groups/:id/milestones` | +| [Invitations](invitations.md) | `/groups/:id/invitations` (also available for projects) | | [Issues](issues.md) | `/groups/:id/issues` (also available for projects and standalone) | | [Issues Statistics](issues_statistics.md) | `/groups/:id/issues_statistics` (also available for projects and standalone) | | [Members](members.md) | `/groups/:id/members` (also available for projects) | diff --git a/doc/api/appearance.md b/doc/api/appearance.md index 47a9d48a4ae..07d26b1a643 100644 --- a/doc/api/appearance.md +++ b/doc/api/appearance.md @@ -1,3 +1,9 @@ +--- +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Appearance API **(CORE ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16647) in GitLab 12.7. diff --git a/doc/api/applications.md b/doc/api/applications.md index 379f346c019..a3216bdddde 100644 --- a/doc/api/applications.md +++ b/doc/api/applications.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Applications API > [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 5f31919c52b..5fdf0c20f1a 100644 --- a/doc/api/audit_events.md +++ b/doc/api/audit_events.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Audit Events API ## Instance Audit Events **(PREMIUM ONLY)** diff --git a/doc/api/avatar.md b/doc/api/avatar.md index 223704d3e6c..aec1ba67d45 100644 --- a/doc/api/avatar.md +++ b/doc/api/avatar.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Avatar API > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19121) in GitLab 11.0. diff --git a/doc/api/boards.md b/doc/api/boards.md index 12ebbcf916a..228c0ca322b 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -4,16 +4,16 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Issue Boards API +# Project Issue Boards API Every API call to boards must be authenticated. If a user is not a member of a project and the project is private, a `GET` request on that project will result to a `404` status code. -## Project Board +## List project issue boards -Lists Issue Boards in the given project. +Lists project issue boards in the given project. ```plaintext GET /projects/:id/boards @@ -33,6 +33,7 @@ Example response: [ { "id" : 1, + "name": "board1", "project": { "id": 5, "name": "Diaspora Project Site", @@ -88,9 +89,15 @@ Example response: ] ``` -## Single board +Another example response when no board has been activated or exist in the project: -Get a single board. +```json +[] +``` + +## Show a single issue board + +Get a single project issue board. ```plaintext GET /projects/:id/boards/:board_id @@ -165,9 +172,9 @@ Example response: } ``` -## Create a board **(STARTER)** +## Create an issue board -Creates a board. +Creates a project issue board. ```plaintext POST /projects/:id/boards @@ -197,70 +204,34 @@ Example response: "web_url": "http://example.com/diaspora/diaspora-project-site" }, "name": "newboard", - "milestone": { - "id": 12 - "title": "10.0" - }, - "lists" : [ - { - "id" : 1, - "label" : { - "name" : "Testing", - "color" : "#F0AD4E", - "description" : null - }, - "position" : 1, - "max_issue_count": 0, - "max_issue_weight": 0, - "limit_metric": null - }, - { - "id" : 2, - "label" : { - "name" : "Ready", - "color" : "#FF0000", - "description" : null - }, - "position" : 2, - "max_issue_count": 0, - "max_issue_weight": 0, - "limit_metric": null - }, - { - "id" : 3, - "label" : { - "name" : "Production", - "color" : "#FF5F00", - "description" : null - }, - "position" : 3, - "max_issue_count": 0, - "max_issue_weight": 0, - "limit_metric": null - } - ] + "lists" : [], + "group": null, + "milestone": null, + "assignee" : null, + "labels" : [], + "weight" : null } ``` -## Update a board **(STARTER)** +## Update an issue board > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5954) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.1. -Updates a board. +Updates a project issue board. ```plaintext PUT /projects/:id/boards/:board_id ``` -| Attribute | Type | Required | Description | -| ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `board_id` | integer | yes | The ID of a board | -| `name` | string | no | The new name of the board | -| `assignee_id` | integer | no | The assignee the board should be scoped to | -| `milestone_id` | integer | no | The milestone the board should be scoped to | -| `labels` | string | no | Comma-separated list of label names which the board should be scoped to | -| `weight` | integer | no | The weight range from 0 to 9, to which the board should be scoped to | +| Attribute | Type | Required | Description | +| ---------------------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `board_id` | integer | yes | The ID of a board | +| `name` | string | no | The new name of the board | +| `assignee_id` **(STARTER)** | integer | no | The assignee the board should be scoped to | +| `milestone_id` **(STARTER)** | integer | no | The milestone the board should be scoped to | +| `labels` **(STARTER)** | string | no | Comma-separated list of label names which the board should be scoped to | +| `weight` **(STARTER)** | integer | no | The weight range from 0 to 9, to which the board should be scoped to | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards/1?name=new_name&milestone_id=43&assignee_id=1&labels=Doing&weight=4" @@ -323,9 +294,9 @@ Example response: } ``` -## Delete a board **(STARTER)** +## Delete an issue board -Deletes a board. +Deletes a project issue board. ```plaintext DELETE /projects/:id/boards/:board_id @@ -340,10 +311,10 @@ DELETE /projects/:id/boards/:board_id curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards/1" ``` -## List board lists +## List board lists in a project issue board Get a list of the board's lists. -Does not include `open` and `closed` lists +Does not include `open` and `closed` lists. ```plaintext GET /projects/:id/boards/:board_id/lists @@ -401,7 +372,7 @@ Example response: ] ``` -## Single board list +## Show a single board list Get a single board list. @@ -436,9 +407,9 @@ Example response: } ``` -## New board list +## Create a board list -Creates a new Issue Board list. +Creates a new issue board list. ```plaintext POST /projects/:id/boards/:board_id/lists @@ -479,9 +450,9 @@ Example response: } ``` -## Edit board list +## Reorder a list in a board -Updates an existing Issue Board list. This call is used to change list position. +Updates an existing issue board list. This call is used to change list position. ```plaintext PUT /projects/:id/boards/:board_id/lists/:list_id @@ -515,7 +486,7 @@ Example response: } ``` -## Delete a board list +## Delete a board list from a board Only for admins and project owners. Deletes the board list in question. diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md index 37156186d03..f7253da297d 100644 --- a/doc/api/broadcast_messages.md +++ b/doc/api/broadcast_messages.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Broadcast Messages API > Introduced in GitLab 8.12. @@ -92,8 +98,8 @@ Parameters: | Attribute | Type | Required | Description | |:----------------|:---------|:---------|:------------------------------------------------------| | `message` | string | yes | Message to display. | -| `starts_at` | datetime | no | Starting time (defaults to current time). | -| `ends_at` | datetime | no | Ending time (defaults to one hour from current time). | +| `starts_at` | datetime | no | Starting time (defaults to current time). Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `ends_at` | datetime | no | Ending time (defaults to one hour from current time). Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `color` | string | no | Background color hex code. | | `font` | string | no | Foreground color hex code. | | `target_path` | string | no | Target path of the broadcast message. | @@ -137,8 +143,8 @@ Parameters: |:----------------|:---------|:---------|:--------------------------------------| | `id` | integer | yes | ID of broadcast message to update. | | `message` | string | no | Message to display. | -| `starts_at` | datetime | no | Starting time. | -| `ends_at` | datetime | no | Ending time. | +| `starts_at` | datetime | no | Starting time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `ends_at` | datetime | no | Ending time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `color` | string | no | Background color hex code. | | `font` | string | no | Foreground color hex code. | | `target_path` | string | no | Target path of the broadcast message. | diff --git a/doc/api/commits.md b/doc/api/commits.md index 66b34d4bc75..d60acaad94d 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -631,7 +631,7 @@ GET /projects/:id/repository/commits/:sha/statuses | `sha` | string | yes | The commit SHA | `ref` | string | no | The name of a repository branch or tag or, if not given, the default branch | `stage` | string | no | Filter by [build stage](../ci/yaml/README.md#stages), e.g., `test` -| `name` | string | no | Filter by [job name](../ci/yaml/README.md#introduction), e.g., `bundler:audit` +| `name` | string | no | Filter by [job name](../ci/yaml/README.md#job-keywords), e.g., `bundler:audit` | `all` | boolean | no | Return all statuses, not only the latest ones ```shell @@ -842,7 +842,8 @@ Example response if commit is GPG signed: "gpg_key_primary_keyid": "8254AAB3FBD54AC9", "gpg_key_user_name": "John Doe", "gpg_key_user_email": "johndoe@example.com", - "gpg_key_subkey_id": null + "gpg_key_subkey_id": null, + "commit_source": "gitaly" } ``` @@ -865,7 +866,8 @@ Example response if commit is X.509 signed: "subject_key_identifier": "AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB", "crl_url": "http://example.com/pki.crl" } - } + }, + "commit_source": "gitaly" } ``` diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index 3a7ebf9a2aa..ddfe5d3f238 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -124,6 +124,48 @@ Example response: ] ``` +## Get details of a single repository + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209916) in GitLab 13.6. + +Get details of a registry repository. + +```plaintext +GET /registry/repositories/:id +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the registry repository accessible by the authenticated user. | +| `tags` | boolean | no | If the parameter is included as `true`, the response includes an array of `"tags"`. | +| `tags_count` | boolean | no | If the parameter is included as `true`, the response includes `"tags_count"`. | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/registry/repositories/2?tags=true&tags_count=true" +``` + +Example response: + +```json +{ + "id": 2, + "name": "", + "path": "group/project", + "project_id": 9, + "location": "gitlab.example.com:5000/group/project", + "created_at": "2019-01-10T13:38:57.391Z", + "cleanup_policy_started_at": "2020-08-17T03:12:35.489Z", + "tags_count": 1, + "tags": [ + { + "name": "0.0.1", + "path": "group/project:0.0.1", + "location": "gitlab.example.com:5000/group/project:0.0.1" + } + ] +} +``` + ## Delete registry repository Delete a repository in registry. @@ -238,7 +280,7 @@ This action doesn't delete blobs. To delete them and recycle disk space, Delete registry repository tags in bulk based on given criteria. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Utilize the Container Registry API to delete all tags except *](https://youtu.be/Hi19bKe_xsg). +For an overview, see [Use the Container Registry API to delete all tags except *](https://youtu.be/Hi19bKe_xsg). ```plaintext DELETE /projects/:id/registry/repositories/:repository_id/tags diff --git a/doc/api/custom_attributes.md b/doc/api/custom_attributes.md index 07ece99f9b1..76c8474ee95 100644 --- a/doc/api/custom_attributes.md +++ b/doc/api/custom_attributes.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Custom Attributes API Every API call to custom attributes must be authenticated as administrator. diff --git a/doc/api/dependencies.md b/doc/api/dependencies.md index 56d33bf151a..2f65ff7b8d9 100644 --- a/doc/api/dependencies.md +++ b/doc/api/dependencies.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Dependencies API **(ULTIMATE)** CAUTION: **Caution:** diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md index a379f1481c1..4d937027dec 100644 --- a/doc/api/dependency_proxy.md +++ b/doc/api/dependency_proxy.md @@ -1,11 +1,21 @@ -# Dependency Proxy API **(PREMIUM)** +--- +stage: Package +group: Package +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Dependency Proxy API ## Purge the dependency proxy for a group -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11631) in GitLab 12.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11631) in GitLab 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 13.6. Deletes the cached blobs for a group. This endpoint requires group admin access. +CAUTION: **Warning:** +[A bug exists](https://gitlab.com/gitlab-org/gitlab/-/issues/277161) for this API. + ```plaintext DELETE /groups/:id/dependency_proxy/cache ``` diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index f11f88ab5c9..ce55657ce27 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.md @@ -96,7 +96,7 @@ POST /projects/:id/deploy_tokens | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | New deploy token's name | -| `expires_at` | datetime | no | Expiration date for the deploy token. Does not expire if no value is provided. | +| `expires_at` | datetime | no | Expiration date for the deploy token. Does not expire if no value is provided. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `username` | string | no | Username for deploy token. Default is `gitlab+deploy-token-{n}` | | `scopes` | array of strings | yes | Indicates the deploy token scopes. Must be at least one of `read_repository`, `read_registry`, `write_registry`, `read_package_registry`, or `write_package_registry`. | @@ -198,7 +198,7 @@ POST /groups/:id/deploy_tokens | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | New deploy token's name | -| `expires_at` | datetime | no | Expiration date for the deploy token. Does not expire if no value is provided. | +| `expires_at` | datetime | no | Expiration date for the deploy token. Does not expire if no value is provided. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `username` | string | no | Username for deploy token. Default is `gitlab+deploy-token-{n}` | | `scopes` | array of strings | yes | Indicates the deploy token scopes. Must be at least one of `read_repository`, `read_registry`, `write_registry`, `read_package_registry`, or `write_package_registry`. | diff --git a/doc/api/deployments.md b/doc/api/deployments.md index b0de972160b..0bc72c93be7 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -20,8 +20,8 @@ GET /projects/:id/deployments | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `order_by` | string | no | Return deployments ordered by `id` or `iid` or `created_at` or `updated_at` or `ref` fields. Default is `id` | | `sort` | string | no | Return deployments sorted in `asc` or `desc` order. Default is `asc` | -| `updated_after` | datetime | no | Return deployments updated after the specified date | -| `updated_before` | datetime | no | Return deployments updated before the specified date | +| `updated_after` | datetime | no | Return deployments updated after the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_before` | datetime | no | Return deployments updated before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `environment` | string | no | The [name of the environment](../ci/environments/index.md#defining-environments) to filter deployments by | | `status` | string | no | The status to filter deployments by | @@ -379,7 +379,7 @@ This API retrieves the list of merge requests shipped with a given deployment: GET /projects/:id/deployments/:deployment_id/merge_requests ``` -It supports the same parameters as the [Merge Requests API](./merge_requests.md#list-merge-requests) and will return a response using the same format: +It supports the same parameters as the [Merge Requests API](merge_requests.md#list-merge-requests) and will return a response using the same format: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/42" diff --git a/doc/api/epic_issues.md b/doc/api/epic_issues.md index 4ab505f3627..21ba75d37a5 100644 --- a/doc/api/epic_issues.md +++ b/doc/api/epic_issues.md @@ -1,6 +1,6 @@ --- stage: Plan -group: Portfolio Management +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/#designated-technical-writers --- diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md index 19c8dc78aed..a368b806f75 100644 --- a/doc/api/epic_links.md +++ b/doc/api/epic_links.md @@ -1,3 +1,9 @@ +--- +stage: Plan +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/#designated-technical-writers +--- + # Epic Links API **(ULTIMATE)** > [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 5c7366c8457..74cde87bb91 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -1,6 +1,6 @@ --- stage: Plan -group: Portfolio Management +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/#designated-technical-writers --- @@ -67,10 +67,10 @@ GET /groups/:id/epics?state=opened | `sort` | string | no | Return epics sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search epics against their `title` and `description` | | `state` | string | no | Search epics against their `state`, possible filters: `opened`, `closed` and `all`, default: `all` | -| `created_after` | datetime | no | Return epics created on or after the given time | -| `created_before` | datetime | no | Return epics created on or before the given time | -| `updated_after` | datetime | no | Return epics updated on or after the given time | -| `updated_before` | datetime | no | Return epics updated on or before the given time | +| `created_after` | datetime | no | Return epics created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `created_before` | datetime | no | Return epics created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_after` | datetime | no | Return epics updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_before` | datetime | no | Return epics updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `include_ancestor_groups` | boolean | no | Include epics from the requested group's ancestors. Default is `false` | | `include_descendant_groups` | boolean | no | Include epics from the requested group's descendants. Default is `true` | | `my_reaction_emoji` | string | no | Return epics reacted by the authenticated user by the given emoji. `None` returns epics not given a reaction. `Any` returns epics given at least one reaction. Introduced in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31479)| @@ -349,7 +349,9 @@ PUT /groups/:id/epics/:epic_iid | `title` | string | no | The title of an epic | | `description` | string | no | The description of an epic. Limited to 1,048,576 characters. | | `confidential` | boolean | no | Whether the epic should be confidential | -| `labels` | string | no | The comma separated list of labels | +| `labels` | string | no | Comma-separated label names for an issue. Set to an empty string to unassign all labels. | +| `add_labels` | string | no | Comma-separated label names to add to an issue. | +| `remove_labels` | string | no | Comma-separated label names to remove from an issue. | | `updated_at` | string | no | When the epic was updated. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` . Requires administrator or project/group owner privileges ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255309) in GitLab 13.5) | | `start_date_is_fixed` | boolean | no | Whether start date should be sourced from `start_date_fixed` or from milestones (since 11.3) | | `start_date_fixed` | string | no | The fixed start date of an epic (since 11.3) | @@ -424,10 +426,10 @@ DELETE /groups/:id/epics/:epic_iid curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5" ``` -## Create a to do +## Create a to-do item -Manually creates a to do for the current user on an epic. If -there already exists a to do for the user on that epic, status code `304` is +Manually creates a to-do item for the current user on an epic. If +there already exists a to-do item for the user on that epic, status code `304` is returned. ```plaintext diff --git a/doc/api/events.md b/doc/api/events.md index 3f4f11b9786..e59630d1358 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Events ## Filter parameters @@ -6,6 +12,7 @@ Available action types for the `action` parameter are: +- `approved` - `created` - `updated` - `closed` diff --git a/doc/api/experiments.md b/doc/api/experiments.md index 66c444e54ce..7e2cad1070b 100644 --- a/doc/api/experiments.md +++ b/doc/api/experiments.md @@ -8,13 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/262725) in GitLab 13.5. -This API is for listing Experiments [experiment use in development of GitLab](../development/experiment_guide/index.md). +This API is for listing A/B experiments [defined in GitLab](../development/experiment_guide/index.md). -All methods require user be a [GitLab team member](https://gitlab.com/groups/gitlab-com/-/group_members) for authorization. +The user must be a [GitLab team member](https://gitlab.com/groups/gitlab-com/-/group_members) to access the API. ## List all experiments -Get a list of all experiments, with its enabled status. +Get a list of all experiments. Each experiment has an `enabled` status that indicates whether the experiment is enabled globally, or only in specific contexts. ```plaintext GET /experiments diff --git a/doc/api/feature_flag_user_lists.md b/doc/api/feature_flag_user_lists.md index b44cb1fb9f2..7cdfcb8d074 100644 --- a/doc/api/feature_flag_user_lists.md +++ b/doc/api/feature_flag_user_lists.md @@ -25,9 +25,10 @@ Gets all feature flag user lists for the requested project. GET /projects/:id/feature_flags_user_lists ``` -| Attribute | Type | Required | Description | -| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| Attribute | Type | Required | Description | +| --------- | -------------- | -------- | -------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `search` | string | no | Return user lists matching the search criteria. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags_user_lists" diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index 064bd26ee72..c9b86320a9f 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Geo +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Geo Nodes API **(PREMIUM ONLY)** To interact with Geo node endpoints, you need to authenticate yourself as an diff --git a/doc/api/graphql/audit_report.md b/doc/api/graphql/audit_report.md index 36c3f44ff89..12663654026 100644 --- a/doc/api/graphql/audit_report.md +++ b/doc/api/graphql/audit_report.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Set up an Audit Report with GraphQL This page describes how you can use the GraphiQL explorer to set up an audit report diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index c2220403461..8501e76b5aa 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Getting started with GitLab GraphQL API This guide demonstrates basic usage of GitLab's GraphQL API. diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index bda24a7e90a..91917ea47a4 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GraphQL API > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19008) in GitLab 11.0 (enabled by feature flag `graphql`). @@ -76,6 +82,10 @@ The process is as follows: release post (at or prior to X.11 and X.5 releases). 1. Fields meeting criteria are removed in X.0 or X.6. +### List of removed items + +View the [fields, enums, and other items we removed](removed_items.md) from the GraphQL API. + ## Available queries The GraphQL API includes the following queries at the root level: diff --git a/doc/api/graphql/reference/gitlab_schema.graphql b/doc/api/graphql/reference/gitlab_schema.graphql index a44f8f70311..58f7d8ecdcf 100644 --- a/doc/api/graphql/reference/gitlab_schema.graphql +++ b/doc/api/graphql/reference/gitlab_schema.graphql @@ -591,6 +591,178 @@ type AlertManagementAlertStatusCountsType { } """ +An endpoint and credentials used to accept alerts for a project +""" +type AlertManagementHttpIntegration implements AlertManagementIntegration { + """ + Whether the endpoint is currently accepting alerts + """ + active: Boolean + + """ + URL at which Prometheus metrics can be queried to populate the metrics dashboard + """ + apiUrl: String + + """ + ID of the integration + """ + id: ID! + + """ + Name of the integration + """ + name: String + + """ + Token used to authenticate alert notification requests + """ + token: String + + """ + Type of integration + """ + type: AlertManagementIntegrationType! + + """ + Endpoint which accepts alert notifications + """ + url: String +} + +""" +Identifier of AlertManagement::HttpIntegration +""" +scalar AlertManagementHttpIntegrationID + +interface AlertManagementIntegration { + """ + Whether the endpoint is currently accepting alerts + """ + active: Boolean + + """ + URL at which Prometheus metrics can be queried to populate the metrics dashboard + """ + apiUrl: String + + """ + ID of the integration + """ + id: ID! + + """ + Name of the integration + """ + name: String + + """ + Token used to authenticate alert notification requests + """ + token: String + + """ + Type of integration + """ + type: AlertManagementIntegrationType! + + """ + Endpoint which accepts alert notifications + """ + url: String +} + +""" +The connection type for AlertManagementIntegration. +""" +type AlertManagementIntegrationConnection { + """ + A list of edges. + """ + edges: [AlertManagementIntegrationEdge] + + """ + A list of nodes. + """ + nodes: [AlertManagementIntegration] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type AlertManagementIntegrationEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: AlertManagementIntegration +} + +""" +Values of types of integrations +""" +enum AlertManagementIntegrationType { + """ + Integration with any monitoring tool + """ + HTTP + + """ + Prometheus integration + """ + PROMETHEUS +} + +""" +An endpoint and credentials used to accept Prometheus alerts for a project +""" +type AlertManagementPrometheusIntegration implements AlertManagementIntegration { + """ + Whether the endpoint is currently accepting alerts + """ + active: Boolean + + """ + URL at which Prometheus metrics can be queried to populate the metrics dashboard + """ + apiUrl: String + + """ + ID of the integration + """ + id: ID! + + """ + Name of the integration + """ + name: String + + """ + Token used to authenticate alert notification requests + """ + token: String + + """ + Type of integration + """ + type: AlertManagementIntegrationType! + + """ + Endpoint which accepts alert notifications + """ + url: String +} + +""" Alert severity values """ enum AlertManagementSeverity { @@ -761,6 +933,21 @@ type AlertTodoCreatePayload { } """ +User availability status +""" +enum AvailabilityEnum { + """ + Busy + """ + BUSY + + """ + Not Set + """ + NOT_SET +} + +""" An emoji awarded by a user """ type AwardEmoji { @@ -1134,7 +1321,7 @@ type Board { """ Find a list by its global ID """ - id: ID + id: ListID """ Filters applied when getting issue metadata in the board list @@ -1253,6 +1440,11 @@ type BoardEpic implements CurrentUserTodos & Noteable { iids: [ID!] """ + Include epics from descendant groups + """ + includeDescendantGroups: Boolean = true + + """ Filter epics by labels """ labelName: [String!] @@ -1611,6 +1803,16 @@ type BoardEpic implements CurrentUserTodos & Noteable { upvotes: Int! """ + Number of user discussions in the epic + """ + userDiscussionsCount: Int! + + """ + Number of user notes of the epic + """ + userNotesCount: Int! + + """ Permissions for the current user on the resource """ userPermissions: EpicPermissions! @@ -1695,7 +1897,7 @@ input BoardIssueInput { """ Filter by epic ID. Incompatible with epicWildcardId """ - epicId: ID + epicId: EpicID """ Filter by epic ID wildcard. Incompatible with epicId @@ -1703,6 +1905,16 @@ input BoardIssueInput { epicWildcardId: EpicWildcardId """ + Filter by iteration title + """ + iterationTitle: String + + """ + Filter by iteration ID wildcard + """ + iterationWildcardId: IterationWildcardId + + """ Filter by label name """ labelName: [String] @@ -2134,6 +2346,11 @@ type CiJob { ): CiJobConnection """ + Pipeline the job belongs to + """ + pipeline: Pipeline! + + """ Schedule for the build """ scheduledAt: Time @@ -2308,6 +2525,11 @@ The connection type for ClusterAgent. """ type ClusterAgentConnection { """ + Total count of collection + """ + count: Int! + + """ A list of edges. """ edges: [ClusterAgentEdge] @@ -2390,6 +2612,11 @@ The connection type for ClusterAgentToken. """ type ClusterAgentTokenConnection { """ + Total count of collection + """ + count: Int! + + """ A list of edges. """ edges: [ClusterAgentTokenEdge] @@ -2505,6 +2732,86 @@ Identifier of Clusters::Cluster """ scalar ClustersClusterID +""" +Represents the code coverage activity for a group +""" +type CodeCoverageActivity { + """ + Average percentage of the different code coverage results available for the group. + """ + averageCoverage: Float + + """ + Number of different code coverage results available for the group. + """ + coverageCount: Int + + """ + Date when the code coverage was created. + """ + date: Date! + + """ + Number of projects with code coverage results for the group. + """ + projectCount: Int +} + +""" +The connection type for CodeCoverageActivity. +""" +type CodeCoverageActivityConnection { + """ + A list of edges. + """ + edges: [CodeCoverageActivityEdge] + + """ + A list of nodes. + """ + nodes: [CodeCoverageActivity] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type CodeCoverageActivityEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: CodeCoverageActivity +} + +""" +Represents the code coverage summary for a project +""" +type CodeCoverageSummary { + """ + Average percentage of the different code coverage results available for the project. + """ + averageCoverage: Float + + """ + Number of different code coverage results available. + """ + coverageCount: Int + + """ + Latest date when the code coverage was created for the project. + """ + lastUpdatedOn: Date +} + type Commit { """ Author of the commit @@ -2542,26 +2849,6 @@ type Commit { id: ID! """ - Latest pipeline of the commit. Deprecated in 12.5: Use `pipelines` - """ - latestPipeline( - """ - Filter pipelines by the ref they are run for - """ - ref: String - - """ - Filter pipelines by the sha of the commit they are run for - """ - sha: String - - """ - Filter pipelines by their status - """ - status: PipelineStatusEnum - ): Pipeline @deprecated(reason: "Use `pipelines`. Deprecated in 12.5") - - """ Raw commit message """ message: String @@ -2714,7 +3001,7 @@ input CommitCreateInput { actions: [CommitAction!]! """ - Name of the branch + Name of the branch to commit into, it can be a new branch """ branch: String! @@ -2732,6 +3019,11 @@ input CommitCreateInput { Project full path the branch is associated with """ projectPath: ID! + + """ + If on a new branch, name of the original branch + """ + startBranch: String } """ @@ -2773,7 +3065,7 @@ type ComplianceFramework { """ Name of the compliance framework """ - name: ProjectSettingEnum! + name: String! } """ @@ -2988,6 +3280,316 @@ enum ContainerExpirationPolicyOlderThanEnum { } """ +A container repository +""" +type ContainerRepository { + """ + Can the current user delete the container repository. + """ + canDelete: Boolean! + + """ + Timestamp when the container repository was created. + """ + createdAt: Time! + + """ + The tags cleanup status for the container repository. + """ + expirationPolicyCleanupStatus: ContainerRepositoryCleanupStatus + + """ + Timestamp when the cleanup done by the expiration policy was started on the container repository. + """ + expirationPolicyStartedAt: Time + + """ + ID of the container repository. + """ + id: ID! + + """ + URL of the container repository. + """ + location: String! + + """ + Name of the container repository. + """ + name: String! + + """ + Path of the container repository. + """ + path: String! + + """ + Status of the container repository. + """ + status: ContainerRepositoryStatus + + """ + Number of tags associated with this image. + """ + tagsCount: Int! + + """ + Timestamp when the container repository was updated. + """ + updatedAt: Time! +} + +""" +Status of the tags cleanup of a container repository +""" +enum ContainerRepositoryCleanupStatus { + """ + The tags cleanup is ongoing. + """ + ONGOING + + """ + The tags cleanup is scheduled and is going to be executed shortly. + """ + SCHEDULED + + """ + The tags cleanup has been partially executed. There are still remaining tags to delete. + """ + UNFINISHED + + """ + The tags cleanup is not scheduled. This is the default state. + """ + UNSCHEDULED +} + +""" +The connection type for ContainerRepository. +""" +type ContainerRepositoryConnection { + """ + A list of edges. + """ + edges: [ContainerRepositoryEdge] + + """ + A list of nodes. + """ + nodes: [ContainerRepository] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +Details of a container repository +""" +type ContainerRepositoryDetails { + """ + Can the current user delete the container repository. + """ + canDelete: Boolean! + + """ + Timestamp when the container repository was created. + """ + createdAt: Time! + + """ + The tags cleanup status for the container repository. + """ + expirationPolicyCleanupStatus: ContainerRepositoryCleanupStatus + + """ + Timestamp when the cleanup done by the expiration policy was started on the container repository. + """ + expirationPolicyStartedAt: Time + + """ + ID of the container repository. + """ + id: ID! + + """ + URL of the container repository. + """ + location: String! + + """ + Name of the container repository. + """ + name: String! + + """ + Path of the container repository. + """ + path: String! + + """ + Status of the container repository. + """ + status: ContainerRepositoryStatus + + """ + Tags of the container repository + """ + tags( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): ContainerRepositoryTagConnection + + """ + Number of tags associated with this image. + """ + tagsCount: Int! + + """ + Timestamp when the container repository was updated. + """ + updatedAt: Time! +} + +""" +An edge in a connection. +""" +type ContainerRepositoryEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: ContainerRepository +} + +""" +Identifier of ContainerRepository +""" +scalar ContainerRepositoryID + +""" +Status of a container repository +""" +enum ContainerRepositoryStatus { + """ + Delete Failed status. + """ + DELETE_FAILED + + """ + Delete Scheduled status. + """ + DELETE_SCHEDULED +} + +""" +A tag from a container repository +""" +type ContainerRepositoryTag { + """ + Can the current user delete this tag. + """ + canDelete: Boolean! + + """ + Timestamp when the tag was created. + """ + createdAt: Time! + + """ + Digest of the tag. + """ + digest: String! + + """ + URL of the tag. + """ + location: String! + + """ + Name of the tag. + """ + name: String! + + """ + Path of the tag. + """ + path: String! + + """ + Revision of the tag. + """ + revision: String! + + """ + Short revision of the tag. + """ + shortRevision: String! + + """ + The size of the tag. + """ + totalSize: Int! +} + +""" +The connection type for ContainerRepositoryTag. +""" +type ContainerRepositoryTagConnection { + """ + A list of edges. + """ + edges: [ContainerRepositoryTagEdge] + + """ + A list of nodes. + """ + nodes: [ContainerRepositoryTag] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type ContainerRepositoryTagEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: ContainerRepositoryTag +} + +""" Autogenerated input type of CreateAlertIssue """ input CreateAlertIssueInput { @@ -3112,19 +3714,19 @@ input CreateBoardInput { clientMutationId: String """ - The group full path the board is associated with. + The group full path the resource is associated with """ groupPath: ID """ The IDs of labels to be added to the board. """ - labelIds: [ID!] + labelIds: [LabelID!] """ The ID of the milestone to be assigned to the board. """ - milestoneId: ID + milestoneId: MilestoneID """ The board name. @@ -3132,7 +3734,7 @@ input CreateBoardInput { name: String """ - The project full path the board is associated with. + The project full path the resource is associated with """ projectPath: ID @@ -3248,6 +3850,51 @@ type CreateClusterAgentPayload { } """ +Autogenerated input type of CreateCustomEmoji +""" +input CreateCustomEmojiInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Namespace full path the emoji is associated with + """ + groupPath: ID! + + """ + Name of the emoji + """ + name: String! + + """ + Location of the emoji file + """ + url: String! +} + +""" +Autogenerated return type of CreateCustomEmoji +""" +type CreateCustomEmojiPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The new custom emoji + """ + customEmoji: CustomEmoji + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" Autogenerated input type of CreateDiffNote """ input CreateDiffNoteInput { @@ -3845,6 +4492,71 @@ interface CurrentUserTodos { } """ +A custom emoji uploaded by user +""" +type CustomEmoji { + """ + Whether the emoji is an external link + """ + external: Boolean! + + """ + The ID of the emoji + """ + id: CustomEmojiID! + + """ + The name of the emoji + """ + name: String! + + """ + The link to file of the emoji + """ + url: String! +} + +""" +The connection type for CustomEmoji. +""" +type CustomEmojiConnection { + """ + A list of edges. + """ + edges: [CustomEmojiEdge] + + """ + A list of nodes. + """ + nodes: [CustomEmoji] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type CustomEmojiEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: CustomEmoji +} + +""" +Identifier of CustomEmoji +""" +scalar CustomEmojiID + +""" Autogenerated input type of DastOnDemandScanCreate """ input DastOnDemandScanCreateInput { @@ -3911,14 +4623,14 @@ type DastScannerProfile { editPath: String """ - ID of the DAST scanner profile + ID of the DAST scanner profile. Deprecated in 13.6: Use `id` """ - globalId: DastScannerProfileID! + globalId: DastScannerProfileID! @deprecated(reason: "Use `id`. Deprecated in 13.6") """ - ID of the DAST scanner profile. Deprecated in 13.4: Use `global_id` + ID of the DAST scanner profile """ - id: ID! @deprecated(reason: "Use `global_id`. Deprecated in 13.4") + id: DastScannerProfileID! """ Name of the DAST scanner profile @@ -4035,14 +4747,14 @@ type DastScannerProfileCreatePayload { errors: [String!]! """ - ID of the scanner profile. + ID of the scanner profile.. Deprecated in 13.6: Use `id` """ - globalId: DastScannerProfileID + globalId: DastScannerProfileID @deprecated(reason: "Use `id`. Deprecated in 13.6") """ - ID of the scanner profile.. Deprecated in 13.4: Use `global_id` + ID of the scanner profile. """ - id: ID @deprecated(reason: "Use `global_id`. Deprecated in 13.4") + id: DastScannerProfileID } """ @@ -4465,6 +5177,93 @@ Identifier of DastSiteToken scalar DastSiteTokenID """ +Represents a DAST Site Validation +""" +type DastSiteValidation { + """ + ID of the site validation + """ + id: DastSiteValidationID! + + """ + The status of the validation + """ + status: DastSiteProfileValidationStatusEnum! +} + +""" +Autogenerated input type of DastSiteValidationCreate +""" +input DastSiteValidationCreateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + ID of the site token. + """ + dastSiteTokenId: DastSiteTokenID! + + """ + The project the site profile belongs to. + """ + fullPath: ID! + + """ + The validation strategy to be used. + """ + strategy: DastSiteValidationStrategyEnum + + """ + The path to be requested during validation. + """ + validationPath: String! +} + +""" +Autogenerated return type of DastSiteValidationCreate +""" +type DastSiteValidationCreatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + ID of the site validation. + """ + id: DastSiteValidationID + + """ + The current validation status. + """ + status: DastSiteProfileValidationStatusEnum +} + +""" +Identifier of DastSiteValidation +""" +scalar DastSiteValidationID + +enum DastSiteValidationStrategyEnum { + """ + Header validation + """ + HEADER + + """ + Text file validation + """ + TEXT_FILE +} + +""" Date represented in ISO 8601 """ scalar Date @@ -4481,7 +5280,7 @@ input DeleteAnnotationInput { """ The global ID of the annotation to delete """ - id: ID! + id: MetricsDashboardAnnotationID! } """ @@ -4670,7 +5469,7 @@ type Design implements CurrentUserTodos & DesignFields & Noteable { """ The Global ID of the most recent acceptable version """ - earlierOrEqualToId: ID + earlierOrEqualToId: DesignManagementVersionID """ The SHA256 of the most recent acceptable version @@ -4810,7 +5609,7 @@ type DesignCollection { """ Find a design by its ID """ - id: ID + id: DesignManagementDesignID ): Design """ @@ -4820,7 +5619,7 @@ type DesignCollection { """ The Global ID of the design at this version """ - id: ID! + id: DesignManagementDesignAtVersionID! ): DesignAtVersion """ @@ -4836,7 +5635,7 @@ type DesignCollection { Filters designs to only those that existed at the version. If argument is omitted or nil then all designs will reflect the latest version """ - atVersion: ID + atVersion: DesignManagementVersionID """ Returns the elements in the list that come before the specified cursor. @@ -4856,7 +5655,7 @@ type DesignCollection { """ Filters designs by their ID """ - ids: [ID!] + ids: [DesignManagementDesignID!] """ Returns the last _n_ elements from the list. @@ -4881,7 +5680,7 @@ type DesignCollection { """ The Global ID of the version """ - id: ID + id: DesignManagementVersionID """ The SHA256 of a specific version @@ -4906,7 +5705,7 @@ type DesignCollection { """ The Global ID of the most recent acceptable version """ - earlierOrEqualToId: ID + earlierOrEqualToId: DesignManagementVersionID """ The SHA256 of the most recent acceptable version @@ -5040,7 +5839,7 @@ type DesignManagement { """ The Global ID of the design at this version """ - id: ID! + id: DesignManagementDesignAtVersionID! ): DesignAtVersion """ @@ -5050,7 +5849,7 @@ type DesignManagement { """ The Global ID of the version """ - id: ID! + id: DesignManagementVersionID! ): DesignVersion } @@ -5100,6 +5899,11 @@ type DesignManagementDeletePayload { } """ +Identifier of DesignManagement::DesignAtVersion +""" +scalar DesignManagementDesignAtVersionID + +""" Identifier of DesignManagement::Design """ scalar DesignManagementDesignID @@ -5200,6 +6004,11 @@ type DesignManagementUploadPayload { } """ +Identifier of DesignManagement::Version +""" +scalar DesignManagementVersionID + +""" A specific version in which designs were added, modified or deleted """ type DesignVersion { @@ -5210,7 +6019,7 @@ type DesignVersion { """ The ID of a specific design """ - designId: ID + designId: DesignManagementDesignID """ The filename of a specific design @@ -5220,7 +6029,7 @@ type DesignVersion { """ The ID of the DesignAtVersion """ - id: ID + id: DesignManagementDesignAtVersionID ): DesignAtVersion! """ @@ -5275,7 +6084,7 @@ type DesignVersion { """ Filters designs by their ID """ - ids: [ID!] + ids: [DesignManagementDesignID!] """ Returns the last _n_ elements from the list. @@ -5425,6 +6234,41 @@ type DestroyBoardPayload { } """ +Autogenerated input type of DestroyContainerRepository +""" +input DestroyContainerRepositoryInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + ID of the container repository. + """ + id: ContainerRepositoryID! +} + +""" +Autogenerated return type of DestroyContainerRepository +""" +type DestroyContainerRepositoryPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The container repository policy after scheduling the deletion. + """ + containerRepository: ContainerRepository! + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" Autogenerated input type of DestroyNote """ input DestroyNoteInput { @@ -5471,7 +6315,7 @@ input DestroySnippetInput { """ The global id of the snippet to destroy """ - id: ID! + id: SnippetID! } """ @@ -5541,6 +6385,81 @@ type DetailedStatus { tooltip: String } +""" +Segment +""" +type DevopsAdoptionSegment { + """ + Assigned groups + """ + groups( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): GroupConnection + + """ + ID of the segment + """ + id: ID! + + """ + Name of the segment + """ + name: String! +} + +""" +The connection type for DevopsAdoptionSegment. +""" +type DevopsAdoptionSegmentConnection { + """ + A list of edges. + """ + edges: [DevopsAdoptionSegmentEdge] + + """ + A list of nodes. + """ + nodes: [DevopsAdoptionSegment] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type DevopsAdoptionSegmentEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: DevopsAdoptionSegment +} + input DiffImagePositionInput { """ Merge base of the branch the comment was made on @@ -5584,6 +6503,11 @@ input DiffImagePositionInput { y: Int! } +""" +Identifier of DiffNote +""" +scalar DiffNoteID + input DiffPathsInput { """ The path of the file on the head sha @@ -6009,10 +6933,9 @@ type Environment { name: String! """ - The path to the environment. Will always return null if - `expose_environment_path_in_alert_details` feature flag is disabled + The path to the environment. """ - path: String + path: String! """ State of the environment, for example: available/stopped @@ -6061,6 +6984,41 @@ Identifier of Environment scalar EnvironmentID """ +Autogenerated input type of EnvironmentsCanaryIngressUpdate +""" +input EnvironmentsCanaryIngressUpdateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The global ID of the environment to update + """ + id: EnvironmentID! + + """ + The weight of the Canary Ingress + """ + weight: Int! +} + +""" +Autogenerated return type of EnvironmentsCanaryIngressUpdate +""" +type EnvironmentsCanaryIngressUpdatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" Represents an epic """ type Epic implements CurrentUserTodos & Noteable { @@ -6115,6 +7073,11 @@ type Epic implements CurrentUserTodos & Noteable { iids: [ID!] """ + Include epics from descendant groups + """ + includeDescendantGroups: Boolean = true + + """ Filter epics by labels """ labelName: [String!] @@ -6473,6 +7436,16 @@ type Epic implements CurrentUserTodos & Noteable { upvotes: Int! """ + Number of user discussions in the epic + """ + userDiscussionsCount: Int! + + """ + Number of user notes of the epic + """ + userNotesCount: Int! + + """ Permissions for the current user on the resource """ userPermissions: EpicPermissions! @@ -6688,6 +7661,11 @@ type EpicIssue implements CurrentUserTodos & Noteable { blocked: Boolean! """ + Count of issues blocking this issue + """ + blockedByCount: Int + + """ Timestamp of when the issue was closed """ closedAt: Time @@ -6748,11 +7726,6 @@ type EpicIssue implements CurrentUserTodos & Noteable { designCollection: DesignCollection """ - The designs associated with this issue. Deprecated in 12.2: Use `designCollection` - """ - designs: DesignCollection @deprecated(reason: "Use `designCollection`. Deprecated in 12.2") - - """ Indicates discussion is locked on the issue """ discussionLocked: Boolean! @@ -6793,6 +7766,11 @@ type EpicIssue implements CurrentUserTodos & Noteable { dueDate: Time """ + Indicates if a project has email notifications disabled: `true` if email notifications are disabled + """ + emailsDisabled: Boolean! + + """ Epic to which this issue belongs """ epic: Epic @@ -6808,6 +7786,16 @@ type EpicIssue implements CurrentUserTodos & Noteable { healthStatus: HealthStatus """ + Human-readable time estimate of the issue + """ + humanTimeEstimate: String + + """ + Human-readable total time reported as spent on the issue + """ + humanTotalTimeSpent: String + + """ Global ID of the epic-issue relation """ id: ID @@ -6853,6 +7841,16 @@ type EpicIssue implements CurrentUserTodos & Noteable { milestone: Milestone """ + Indicates if issue got moved from other project + """ + moved: Boolean + + """ + Updated Issue after it got moved to another project + """ + movedTo: Issue + + """ All notes on this noteable """ notes( @@ -6983,11 +7981,21 @@ type EpicIssue implements CurrentUserTodos & Noteable { updatedAt: Time! """ + User that last updated the issue + """ + updatedBy: User + + """ Number of upvotes the issue has received """ upvotes: Int! """ + Number of user discussions in the issue + """ + userDiscussionsCount: Int! + + """ Number of user notes of the issue """ userNotesCount: Int! @@ -7036,6 +8044,11 @@ type EpicIssueConnection { Information to aid in pagination. """ pageInfo: PageInfo! + + """ + Total weight of issues collection + """ + weight: Int! } """ @@ -7414,6 +8427,37 @@ type GeoNode { selectiveSyncType: String """ + Find snippet repository registries on this Geo node. Available only when + feature flag `geo_snippet_repository_replication` is enabled + """ + snippetRepositoryRegistries( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Filters registries by their ID + """ + ids: [ID!] + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): SnippetRepositoryRegistryConnection + + """ Indicates if this secondary node will replicate blobs in Object Storage """ syncObjectStorage: Boolean @@ -7459,6 +8503,11 @@ type GeoNode { verificationMaxCapacity: Int } +""" +Identifier of Gitlab::ErrorTracking::DetailedError +""" +scalar GitlabErrorTrackingDetailedErrorID + type GrafanaIntegration { """ Timestamp of the issue's creation @@ -7481,11 +8530,6 @@ type GrafanaIntegration { id: ID! """ - API token for the Grafana integration. Deprecated in 12.7: Plain text token has been masked for security reasons - """ - token: String! @deprecated(reason: "Plain text token has been masked for security reasons. Deprecated in 12.7") - - """ Timestamp of the issue's last activity """ updatedAt: Time! @@ -7544,7 +8588,7 @@ type Group { """ Find a board by its ID """ - id: ID + id: BoardID """ Returns the last _n_ elements from the list. @@ -7553,11 +8597,97 @@ type Group { ): BoardConnection """ + Represents the code coverage activity for this group. Available only when + feature flag `group_coverage_data_report_graph` is enabled + """ + codeCoverageActivities( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + First day for which to fetch code coverage activity (maximum time window is set to 90 days) + """ + startDate: Date! + ): CodeCoverageActivityConnection + + """ + Container repositories of the project + """ + containerRepositories( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + Filter the container repositories by their name + """ + name: String + ): ContainerRepositoryConnection + + """ Includes at least one project where the repository size exceeds the limit """ containsLockedProjects: Boolean! """ + Custom emoji within this namespace. Available only when feature flag `custom_emoji` is enabled + """ + customEmoji( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): CustomEmojiConnection + + """ Description of the namespace """ description: String @@ -7603,6 +8733,11 @@ type Group { iids: [ID!] """ + Include epics from descendant groups + """ + includeDescendantGroups: Boolean = true + + """ Filter epics by labels """ labelName: [String!] @@ -7686,6 +8821,11 @@ type Group { iids: [ID!] """ + Include epics from descendant groups + """ + includeDescendantGroups: Boolean = true + + """ Filter epics by labels """ labelName: [String!] @@ -7798,7 +8938,7 @@ type Group { after: String """ - ID of a user assigned to the issues, "none" and "any" values supported + ID of a user assigned to the issues, "none" and "any" values are supported """ assigneeId: String @@ -7843,6 +8983,11 @@ type Group { createdBefore: Time """ + ID of an epic associated with the issues, "none" and "any" values are supported + """ + epicId: String + + """ Returns the first _n_ elements from the list. """ first: Int @@ -8280,6 +9425,11 @@ type Group { shareWithGroupLock: Boolean """ + Group statistics + """ + stats: GroupStats + + """ Total storage limit of the root namespace in bytes """ storageSizeLimit: Float @@ -8503,7 +9653,12 @@ type Group { """ Represents vulnerable project counts for each grade """ - vulnerabilityGrades: [VulnerableProjectsByGrade!]! + vulnerabilityGrades( + """ + Include grades belonging to subgroups + """ + includeSubgroups: Boolean = false + ): [VulnerableProjectsByGrade!]! """ Vulnerability scanners reported on the project vulnerabilties of the group and its subgroups @@ -8567,6 +9722,46 @@ type Group { } """ +The connection type for Group. +""" +type GroupConnection { + """ + A list of edges. + """ + edges: [GroupEdge] + + """ + A list of nodes. + """ + nodes: [Group] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type GroupEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: Group +} + +""" +Identifier of Group +""" +scalar GroupID + +""" Represents a Group Membership """ type GroupMember implements MemberInterface { @@ -8659,6 +9854,33 @@ type GroupPermissions { } """ +Contains release-related statistics about a group +""" +type GroupReleaseStats { + """ + Total number of releases in all descendant projects of the group. Will always + return `null` if `group_level_release_statistics` feature flag is disabled + """ + releasesCount: Int + + """ + Percentage of the group's descendant projects that have at least one release. + Will always return `null` if `group_level_release_statistics` feature flag is disabled + """ + releasesPercentage: Int +} + +""" +Contains statistics about a group +""" +type GroupStats { + """ + Statistics related to releases within the group + """ + releaseStats: GroupReleaseStats +} + +""" Health status of an issue or epic """ enum HealthStatus { @@ -8668,6 +9890,166 @@ enum HealthStatus { } """ +Autogenerated input type of HttpIntegrationCreate +""" +input HttpIntegrationCreateInput { + """ + Whether the integration is receiving alerts + """ + active: Boolean! + + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The name of the integration + """ + name: String! + + """ + The project to create the integration in + """ + projectPath: ID! +} + +""" +Autogenerated return type of HttpIntegrationCreate +""" +type HttpIntegrationCreatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The HTTP integration + """ + integration: AlertManagementHttpIntegration +} + +""" +Autogenerated input type of HttpIntegrationDestroy +""" +input HttpIntegrationDestroyInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The id of the integration to remove + """ + id: AlertManagementHttpIntegrationID! +} + +""" +Autogenerated return type of HttpIntegrationDestroy +""" +type HttpIntegrationDestroyPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The HTTP integration + """ + integration: AlertManagementHttpIntegration +} + +""" +Autogenerated input type of HttpIntegrationResetToken +""" +input HttpIntegrationResetTokenInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The id of the integration to mutate + """ + id: AlertManagementHttpIntegrationID! +} + +""" +Autogenerated return type of HttpIntegrationResetToken +""" +type HttpIntegrationResetTokenPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The HTTP integration + """ + integration: AlertManagementHttpIntegration +} + +""" +Autogenerated input type of HttpIntegrationUpdate +""" +input HttpIntegrationUpdateInput { + """ + Whether the integration is receiving alerts + """ + active: Boolean + + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The id of the integration to mutate + """ + id: AlertManagementHttpIntegrationID! + + """ + The name of the integration + """ + name: String +} + +""" +Autogenerated return type of HttpIntegrationUpdate +""" +type HttpIntegrationUpdatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The HTTP integration + """ + integration: AlertManagementHttpIntegration +} + +""" An ISO 8601-encoded date """ scalar ISO8601Date @@ -8896,6 +10278,11 @@ type Issue implements CurrentUserTodos & Noteable { blocked: Boolean! """ + Count of issues blocking this issue + """ + blockedByCount: Int + + """ Timestamp of when the issue was closed """ closedAt: Time @@ -8956,11 +10343,6 @@ type Issue implements CurrentUserTodos & Noteable { designCollection: DesignCollection """ - The designs associated with this issue. Deprecated in 12.2: Use `designCollection` - """ - designs: DesignCollection @deprecated(reason: "Use `designCollection`. Deprecated in 12.2") - - """ Indicates discussion is locked on the issue """ discussionLocked: Boolean! @@ -9001,6 +10383,11 @@ type Issue implements CurrentUserTodos & Noteable { dueDate: Time """ + Indicates if a project has email notifications disabled: `true` if email notifications are disabled + """ + emailsDisabled: Boolean! + + """ Epic to which this issue belongs """ epic: Epic @@ -9011,6 +10398,16 @@ type Issue implements CurrentUserTodos & Noteable { healthStatus: HealthStatus """ + Human-readable time estimate of the issue + """ + humanTimeEstimate: String + + """ + Human-readable total time reported as spent on the issue + """ + humanTotalTimeSpent: String + + """ ID of the issue """ id: ID! @@ -9056,6 +10453,16 @@ type Issue implements CurrentUserTodos & Noteable { milestone: Milestone """ + Indicates if issue got moved from other project + """ + moved: Boolean + + """ + Updated Issue after it got moved to another project + """ + movedTo: Issue + + """ All notes on this noteable """ notes( @@ -9181,11 +10588,21 @@ type Issue implements CurrentUserTodos & Noteable { updatedAt: Time! """ + User that last updated the issue + """ + updatedBy: User + + """ Number of upvotes the issue has received """ upvotes: Int! """ + Number of user discussions in the issue + """ + userDiscussionsCount: Int! + + """ Number of user notes of the issue """ userNotesCount: Int! @@ -9234,6 +10651,11 @@ type IssueConnection { Information to aid in pagination. """ pageInfo: PageInfo! + + """ + Total weight of issues collection + """ + weight: Int! } """ @@ -9568,7 +10990,7 @@ input IssueSetEpicInput { """ Global ID of the epic to be assigned to the issue, epic will be removed if absent or set to null """ - epicId: ID + epicId: EpicID """ The IID of the issue to mutate @@ -9906,6 +11328,16 @@ enum IssueSort { SEVERITY_DESC """ + Issues with earliest SLA due time shown first + """ + SLA_DUE_AT_ASC + + """ + Issues with latest SLA due time shown first + """ + SLA_DUE_AT_DESC + + """ Updated at ascending order """ UPDATED_ASC @@ -10014,12 +11446,7 @@ enum IssueType { """ Represents an iteration object """ -type Iteration implements TimeboxBurnupTimeSeriesInterface { - """ - Daily scope and completed totals for burnup charts - """ - burnupTimeSeries: [BurnupChartDailyTotals!] - +type Iteration implements TimeboxReportInterface { """ Timestamp of iteration creation """ @@ -10051,6 +11478,11 @@ type Iteration implements TimeboxBurnupTimeSeriesInterface { iid: ID! """ + Historically accurate report about the timebox + """ + report: TimeboxReport + + """ Web path of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts """ scopedPath: String @@ -10143,6 +11575,21 @@ enum IterationState { } """ +Iteration ID wildcard values +""" +enum IterationWildcardId { + """ + An iteration is assigned + """ + ANY + + """ + No iteration is assigned + """ + NONE +} + +""" Represents untyped JSON """ scalar JSON @@ -10505,6 +11952,63 @@ type LabelConnection { } """ +Autogenerated input type of LabelCreate +""" +input LabelCreateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The color of the label given in 6-digit hex notation with leading '#' sign + (e.g. #FFAABB) or one of the CSS color names in + https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords + """ + color: String = "#428BCA" + + """ + Description of the label + """ + description: String + + """ + The group full path the resource is associated with + """ + groupPath: ID + + """ + The project full path the resource is associated with + """ + projectPath: ID + + """ + Title of the label + """ + title: String! +} + +""" +Autogenerated return type of LabelCreate +""" +type LabelCreatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The label after mutation + """ + label: Label +} + +""" An edge in a connection. """ type LabelEdge { @@ -10550,7 +12054,7 @@ input MarkAsSpamSnippetInput { """ The global id of the snippet to update """ - id: ID! + id: SnippetID! } """ @@ -10952,11 +12456,6 @@ type MergeRequest implements CurrentUserTodos & Noteable { ): LabelConnection """ - Default merge commit message of the merge request. Deprecated in 11.8: Use `defaultMergeCommitMessage` - """ - mergeCommitMessage: String @deprecated(reason: "Use `defaultMergeCommitMessage`. Deprecated in 11.8") - - """ SHA of the merge request commit (set once merged) """ mergeCommitSha: String @@ -11212,6 +12711,11 @@ type MergeRequest implements CurrentUserTodos & Noteable { upvotes: Int! """ + Number of user discussions in the merge request + """ + userDiscussionsCount: Int + + """ User notes count of the merge request """ userNotesCount: Int @@ -11534,7 +13038,7 @@ input MergeRequestSetLabelsInput { """ The Label IDs to set. Replaces existing labels by default. """ - labelIds: [ID!]! + labelIds: [LabelID!]! """ Changes the operation mode. Defaults to REPLACE. @@ -12020,14 +13524,14 @@ type MetricsDashboardAnnotationEdge { } """ -Represents a milestone +Identifier of Metrics::Dashboard::Annotation """ -type Milestone implements TimeboxBurnupTimeSeriesInterface { - """ - Daily scope and completed totals for burnup charts - """ - burnupTimeSeries: [BurnupChartDailyTotals!] +scalar MetricsDashboardAnnotationID +""" +Represents a milestone +""" +type Milestone implements TimeboxReportInterface { """ Timestamp of milestone creation """ @@ -12059,6 +13563,11 @@ type Milestone implements TimeboxBurnupTimeSeriesInterface { projectMilestone: Boolean! """ + Historically accurate report about the timebox + """ + report: TimeboxReport + + """ Timestamp of the milestone start date """ startDate: Time @@ -12190,6 +13699,11 @@ type Mutation { createBoard(input: CreateBoardInput!): CreateBoardPayload createBranch(input: CreateBranchInput!): CreateBranchPayload createClusterAgent(input: CreateClusterAgentInput!): CreateClusterAgentPayload + + """ + . Available only when feature flag `custom_emoji` is enabled + """ + createCustomEmoji(input: CreateCustomEmojiInput!): CreateCustomEmojiPayload createDiffNote(input: CreateDiffNoteInput!): CreateDiffNotePayload createEpic(input: CreateEpicInput!): CreateEpicPayload createImageDiffNote(input: CreateImageDiffNoteInput!): CreateImageDiffNotePayload @@ -12207,12 +13721,14 @@ type Mutation { dastSiteProfileDelete(input: DastSiteProfileDeleteInput!): DastSiteProfileDeletePayload dastSiteProfileUpdate(input: DastSiteProfileUpdateInput!): DastSiteProfileUpdatePayload dastSiteTokenCreate(input: DastSiteTokenCreateInput!): DastSiteTokenCreatePayload + dastSiteValidationCreate(input: DastSiteValidationCreateInput!): DastSiteValidationCreatePayload deleteAnnotation(input: DeleteAnnotationInput!): DeleteAnnotationPayload designManagementDelete(input: DesignManagementDeleteInput!): DesignManagementDeletePayload designManagementMove(input: DesignManagementMoveInput!): DesignManagementMovePayload designManagementUpload(input: DesignManagementUploadInput!): DesignManagementUploadPayload destroyBoard(input: DestroyBoardInput!): DestroyBoardPayload destroyBoardList(input: DestroyBoardListInput!): DestroyBoardListPayload + destroyContainerRepository(input: DestroyContainerRepositoryInput!): DestroyContainerRepositoryPayload destroyNote(input: DestroyNoteInput!): DestroyNotePayload destroySnippet(input: DestroySnippetInput!): DestroySnippetPayload @@ -12221,9 +13737,14 @@ type Mutation { """ discussionToggleResolve(input: DiscussionToggleResolveInput!): DiscussionToggleResolvePayload dismissVulnerability(input: DismissVulnerabilityInput!): DismissVulnerabilityPayload @deprecated(reason: "Use vulnerabilityDismiss. Deprecated in 13.5") + environmentsCanaryIngressUpdate(input: EnvironmentsCanaryIngressUpdateInput!): EnvironmentsCanaryIngressUpdatePayload epicAddIssue(input: EpicAddIssueInput!): EpicAddIssuePayload epicSetSubscription(input: EpicSetSubscriptionInput!): EpicSetSubscriptionPayload epicTreeReorder(input: EpicTreeReorderInput!): EpicTreeReorderPayload + httpIntegrationCreate(input: HttpIntegrationCreateInput!): HttpIntegrationCreatePayload + httpIntegrationDestroy(input: HttpIntegrationDestroyInput!): HttpIntegrationDestroyPayload + httpIntegrationResetToken(input: HttpIntegrationResetTokenInput!): HttpIntegrationResetTokenPayload + httpIntegrationUpdate(input: HttpIntegrationUpdateInput!): HttpIntegrationUpdatePayload issueMove(input: IssueMoveInput!): IssueMovePayload issueMoveList(input: IssueMoveListInput!): IssueMoveListPayload issueSetAssignees(input: IssueSetAssigneesInput!): IssueSetAssigneesPayload @@ -12237,6 +13758,7 @@ type Mutation { issueSetWeight(input: IssueSetWeightInput!): IssueSetWeightPayload jiraImportStart(input: JiraImportStartInput!): JiraImportStartPayload jiraImportUsers(input: JiraImportUsersInput!): JiraImportUsersPayload + labelCreate(input: LabelCreateInput!): LabelCreatePayload markAsSpamSnippet(input: MarkAsSpamSnippetInput!): MarkAsSpamSnippetPayload mergeRequestCreate(input: MergeRequestCreateInput!): MergeRequestCreatePayload mergeRequestSetAssignees(input: MergeRequestSetAssigneesInput!): MergeRequestSetAssigneesPayload @@ -12254,10 +13776,24 @@ type Mutation { pipelineCancel(input: PipelineCancelInput!): PipelineCancelPayload pipelineDestroy(input: PipelineDestroyInput!): PipelineDestroyPayload pipelineRetry(input: PipelineRetryInput!): PipelineRetryPayload + prometheusIntegrationCreate(input: PrometheusIntegrationCreateInput!): PrometheusIntegrationCreatePayload + prometheusIntegrationResetToken(input: PrometheusIntegrationResetTokenInput!): PrometheusIntegrationResetTokenPayload + prometheusIntegrationUpdate(input: PrometheusIntegrationUpdateInput!): PrometheusIntegrationUpdatePayload + promoteToEpic(input: PromoteToEpicInput!): PromoteToEpicPayload + releaseCreate(input: ReleaseCreateInput!): ReleaseCreatePayload removeAwardEmoji(input: RemoveAwardEmojiInput!): RemoveAwardEmojiPayload @deprecated(reason: "Use awardEmojiRemove. Deprecated in 13.2") removeProjectFromSecurityDashboard(input: RemoveProjectFromSecurityDashboardInput!): RemoveProjectFromSecurityDashboardPayload + + """ + Repositions a DiffNote on an image (a `Note` where the `position.positionType` is `"image"`) + """ + repositionImageDiffNote(input: RepositionImageDiffNoteInput!): RepositionImageDiffNotePayload revertVulnerabilityToDetected(input: RevertVulnerabilityToDetectedInput!): RevertVulnerabilityToDetectedPayload @deprecated(reason: "Use vulnerabilityRevertToDetected. Deprecated in 13.5") runDastScan(input: RunDASTScanInput!): RunDASTScanPayload @deprecated(reason: "Use DastOnDemandScanCreate. Deprecated in 13.4") + terraformStateDelete(input: TerraformStateDeleteInput!): TerraformStateDeletePayload + terraformStateLock(input: TerraformStateLockInput!): TerraformStateLockPayload + terraformStateUnlock(input: TerraformStateUnlockInput!): TerraformStateUnlockPayload + todoCreate(input: TodoCreateInput!): TodoCreatePayload todoMarkDone(input: TodoMarkDoneInput!): TodoMarkDonePayload todoRestore(input: TodoRestoreInput!): TodoRestorePayload todoRestoreMany(input: TodoRestoreManyInput!): TodoRestoreManyPayload @@ -12542,6 +14078,11 @@ enum NamespaceProjectSort { Most similar to the search query """ SIMILARITY + + """ + Sort by storage size + """ + STORAGE } input NegatedBoardIssueInput { @@ -12558,7 +14099,12 @@ input NegatedBoardIssueInput { """ Filter by epic ID. Incompatible with epicWildcardId """ - epicId: ID + epicId: EpicID + + """ + Filter by iteration title + """ + iterationTitle: String """ Filter by label name @@ -12735,6 +14281,11 @@ type NotePermissions { readNote: Boolean! """ + Indicates the user can perform `reposition_note` on this resource + """ + repositionNote: Boolean! + + """ Indicates the user can perform `resolve_note` on this resource """ resolveNote: Boolean! @@ -13058,6 +14609,31 @@ type Pipeline { detailedStatus: DetailedStatus! """ + Pipelines this pipeline will trigger + """ + downstream( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): PipelineConnection + + """ Duration of the pipeline in seconds """ duration: Int @@ -13078,6 +14654,46 @@ type Pipeline { iid: String! """ + Jobs belonging to the pipeline + """ + jobs( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + Filter jobs by the type of security report they produce + """ + securityReportTypes: [SecurityReportTypeEnum!] + ): CiJobConnection + + """ + Relative path to the pipeline's page + """ + path: String + + """ + Project the pipeline belongs to + """ + project: Project + + """ Specifies if a pipeline can be retried """ retryable: Boolean! @@ -13093,6 +14709,11 @@ type Pipeline { sha: String! """ + Job where pipeline was triggered from + """ + sourceJob: CiJob + + """ Stages of the pipeline """ stages( @@ -13134,6 +14755,11 @@ type Pipeline { updatedAt: Time! """ + Pipeline that triggered the pipeline + """ + upstream: Pipeline + + """ Pipeline user """ user: User @@ -13342,7 +14968,7 @@ type Project { iid: String """ - Search criteria for filtering alerts. This will search on title, description, service, monitoring_tool. + Search query for title, description, service, or monitoring_tool. """ search: String @@ -13367,7 +14993,7 @@ type Project { assigneeUsername: String """ - Search criteria for filtering alerts. This will search on title, description, service, monitoring_tool. + Search query for title, description, service, or monitoring_tool. """ search: String ): AlertManagementAlertStatusCountsType @@ -13407,7 +15033,7 @@ type Project { last: Int """ - Search criteria for filtering alerts. This will search on title, description, service, monitoring_tool. + Search query for title, description, service, or monitoring_tool. """ search: String @@ -13423,6 +15049,31 @@ type Project { ): AlertManagementAlertConnection """ + Integrations which can receive alerts for the project + """ + alertManagementIntegrations( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): AlertManagementIntegrationConnection + + """ If `only_allow_merge_if_pipeline_succeeds` is true, indicates if merge requests of the project can also be merged with skipped jobs """ @@ -13475,7 +15126,7 @@ type Project { """ Find a board by its ID """ - id: ID + id: BoardID """ Returns the last _n_ elements from the list. @@ -13519,6 +15170,11 @@ type Project { ): ClusterAgentConnection """ + Code coverage summary associated with the project + """ + codeCoverageSummary: CodeCoverageSummary + + """ Compliance frameworks associated with the project """ complianceFrameworks( @@ -13554,6 +15210,36 @@ type Project { containerRegistryEnabled: Boolean """ + Container repositories of the project + """ + containerRepositories( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + Filter the container repositories by their name + """ + name: String + ): ContainerRepositoryConnection + + """ Timestamp of the project creation """ createdAt: Time @@ -13619,6 +15305,16 @@ type Project { ): DastSiteProfileConnection """ + DAST Site Validation associated with the project + """ + dastSiteValidation( + """ + target URL of the DAST Site Validation + """ + targetUrl: String! + ): DastSiteValidation + + """ Short description of the project """ description: String @@ -13728,7 +15424,7 @@ type Project { """ issue( """ - ID of a user assigned to the issues, "none" and "any" values supported + ID of a user assigned to the issues, "none" and "any" values are supported """ assigneeId: String @@ -13768,6 +15464,11 @@ type Project { createdBefore: Time """ + ID of an epic associated with the issues, "none" and "any" values are supported + """ + epicId: String + + """ IID of the issue. For example, "1" """ iid: String @@ -13828,7 +15529,7 @@ type Project { """ issueStatusCounts( """ - ID of a user assigned to the issues, "none" and "any" values supported + ID of a user assigned to the issues, "none" and "any" values are supported """ assigneeId: String @@ -13918,7 +15619,7 @@ type Project { after: String """ - ID of a user assigned to the issues, "none" and "any" values supported + ID of a user assigned to the issues, "none" and "any" values are supported """ assigneeId: String @@ -13963,6 +15664,11 @@ type Project { createdBefore: Time """ + ID of an epic associated with the issues, "none" and "any" values are supported + """ + epicId: String + + """ Returns the first _n_ elements from the list. """ first: Int @@ -14545,6 +16251,11 @@ type Project { Returns the last _n_ elements from the list. """ last: Int + + """ + Sort releases by this criteria + """ + sort: ReleaseSort = RELEASED_AT_DESC ): ReleaseConnection """ @@ -14684,7 +16395,7 @@ type Project { """ ID of the Sentry issue """ - id: ID! + id: GitlabErrorTrackingDetailedErrorID! ): SentryDetailedError """ @@ -14764,7 +16475,7 @@ type Project { """ Array of global snippet ids, e.g., "gid://gitlab/ProjectSnippet/1" """ - ids: [ID!] + ids: [SnippetID!] """ Returns the last _n_ elements from the list. @@ -15345,20 +17056,9 @@ type ProjectPermissions { uploadFile: Boolean! } -""" -Names of compliance frameworks that can be assigned to a Project -""" -enum ProjectSettingEnum { - gdpr - hipaa - pci_dss - soc_2 - sox -} - type ProjectStatistics { """ - Build artifacts size of the project + Build artifacts size of the project in bytes """ buildArtifactsSize: Float! @@ -15368,32 +17068,37 @@ type ProjectStatistics { commitCount: Float! """ - Large File Storage (LFS) object size of the project + Large File Storage (LFS) object size of the project in bytes """ lfsObjectsSize: Float! """ - Packages size of the project + Packages size of the project in bytes """ packagesSize: Float! """ - Repository size of the project + Repository size of the project in bytes """ repositorySize: Float! """ - Snippets size of the project + Snippets size of the project in bytes """ snippetsSize: Float """ - Storage size of the project + Storage size of the project in bytes """ storageSize: Float! """ - Wiki size of the project + Uploads size of the project in bytes + """ + uploadsSize: Float + + """ + Wiki size of the project in bytes """ wikiSize: Float } @@ -15413,8 +17118,198 @@ type PrometheusAlert { id: ID! } +""" +Autogenerated input type of PrometheusIntegrationCreate +""" +input PrometheusIntegrationCreateInput { + """ + Whether the integration is receiving alerts + """ + active: Boolean! + + """ + Endpoint at which prometheus can be queried + """ + apiUrl: String! + + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The project to create the integration in + """ + projectPath: ID! +} + +""" +Autogenerated return type of PrometheusIntegrationCreate +""" +type PrometheusIntegrationCreatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The newly created integration + """ + integration: AlertManagementPrometheusIntegration +} + +""" +Autogenerated input type of PrometheusIntegrationResetToken +""" +input PrometheusIntegrationResetTokenInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The id of the integration to mutate + """ + id: PrometheusServiceID! +} + +""" +Autogenerated return type of PrometheusIntegrationResetToken +""" +type PrometheusIntegrationResetTokenPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The newly created integration + """ + integration: AlertManagementPrometheusIntegration +} + +""" +Autogenerated input type of PrometheusIntegrationUpdate +""" +input PrometheusIntegrationUpdateInput { + """ + Whether the integration is receiving alerts + """ + active: Boolean + + """ + Endpoint at which prometheus can be queried + """ + apiUrl: String + + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The id of the integration to mutate + """ + id: PrometheusServiceID! +} + +""" +Autogenerated return type of PrometheusIntegrationUpdate +""" +type PrometheusIntegrationUpdatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The newly created integration + """ + integration: AlertManagementPrometheusIntegration +} + +""" +Identifier of PrometheusService +""" +scalar PrometheusServiceID + +""" +Autogenerated input type of PromoteToEpic +""" +input PromoteToEpicInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The group the promoted epic will belong to + """ + groupPath: ID + + """ + The IID of the issue to mutate + """ + iid: String! + + """ + The project the issue to mutate is in + """ + projectPath: ID! +} + +""" +Autogenerated return type of PromoteToEpic +""" +type PromoteToEpicPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The epic after issue promotion + """ + epic: Epic + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The issue after mutation + """ + issue: Issue +} + type Query { """ + Find a container repository + """ + containerRepository( + """ + The global ID of the container repository + """ + id: ContainerRepositoryID! + ): ContainerRepositoryDetails + + """ Get information about current user """ currentUser: User @@ -15425,6 +17320,31 @@ type Query { designManagement: DesignManagement! """ + Get configured DevOps adoption segments on the instance + """ + devopsAdoptionSegments( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): DevopsAdoptionSegmentConnection + + """ Text to echo back """ echo( @@ -15487,6 +17407,16 @@ type Query { Returns the last _n_ elements from the list. """ last: Int + + """ + Measurement recorded after this date + """ + recordedAfter: Time + + """ + Measurement recorded before this date + """ + recordedBefore: Time ): InstanceStatisticsMeasurementConnection """ @@ -15620,6 +17550,31 @@ type Query { ): RunnerPlatformConnection """ + Get runner setup instructions + """ + runnerSetup( + """ + Architecture to generate the instructions for + """ + architecture: String! + + """ + Group to register the runner for + """ + groupId: GroupID + + """ + Platform to generate the instructions for + """ + platform: String! + + """ + Project to register the runner for + """ + projectId: ProjectID + ): RunnerSetup + + """ Find Snippets visible to the current user """ snippets( @@ -15631,7 +17586,7 @@ type Query { """ The ID of an author """ - authorId: ID + authorId: UserID """ Returns the elements in the list that come before the specified cursor. @@ -15651,7 +17606,7 @@ type Query { """ Array of global snippet ids, e.g., "gid://gitlab/ProjectSnippet/1" """ - ids: [ID!] + ids: [SnippetID!] """ Returns the last _n_ elements from the list. @@ -15661,7 +17616,7 @@ type Query { """ The ID of a project """ - projectId: ID + projectId: ProjectID """ The type of snippet @@ -15681,7 +17636,7 @@ type Query { """ ID of the User """ - id: ID + id: UserID """ Username of the User @@ -15719,6 +17674,11 @@ type Query { last: Int """ + Query to search users by name, username, or primary email. + """ + search: String + + """ Sort users by this criteria """ sort: Sort = created_desc @@ -16088,7 +18048,32 @@ type ReleaseAssetLinkEdge { } """ -Type of the link: `other`, `runbook`, `image`, `package`; defaults to `other` +Fields that are available when modifying a release asset link +""" +input ReleaseAssetLinkInput { + """ + Relative path for a direct asset link + """ + directAssetPath: String + + """ + The type of the asset link + """ + linkType: ReleaseAssetLinkType = OTHER + + """ + Name of the asset link + """ + name: String! + + """ + URL of the asset link + """ + url: String! +} + +""" +Type of the link: `other`, `runbook`, `image`, `package` """ enum ReleaseAssetLinkType { """ @@ -16173,6 +18158,16 @@ type ReleaseAssets { } """ +Fields that are available when modifying release assets +""" +input ReleaseAssetsInput { + """ + A list of asset links to associate to the release + """ + links: [ReleaseAssetLinkInput!] +} + +""" The connection type for Release. """ type ReleaseConnection { @@ -16198,6 +18193,76 @@ type ReleaseConnection { } """ +Autogenerated input type of ReleaseCreate +""" +input ReleaseCreateInput { + """ + Assets associated to the release + """ + assets: ReleaseAssetsInput + + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Description (also known as "release notes") of the release + """ + description: String + + """ + The title of each milestone the release is associated with. GitLab Premium customers can specify group milestones. + """ + milestones: [String!] + + """ + Name of the release + """ + name: String + + """ + Full path of the project the release is associated with + """ + projectPath: ID! + + """ + The commit SHA or branch name to use if creating a new tag + """ + ref: String + + """ + The date when the release will be/was ready. Defaults to the current time. + """ + releasedAt: Time + + """ + Name of the tag to associate with the release + """ + tagName: String! +} + +""" +Autogenerated return type of ReleaseCreate +""" +type ReleaseCreatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The release after mutation + """ + release: Release +} + +""" An edge in a connection. """ type ReleaseEdge { @@ -16274,19 +18339,34 @@ type ReleaseEvidenceEdge { type ReleaseLinks { """ + HTTP URL of the issues page, filtered by this release and `state=closed` + """ + closedIssuesUrl: String + + """ + HTTP URL of the merge request page , filtered by this release and `state=closed` + """ + closedMergeRequestsUrl: String + + """ HTTP URL of the release's edit page """ editUrl: String """ - HTTP URL of the issues page filtered by this release + HTTP URL of the merge request page , filtered by this release and `state=merged` + """ + mergedMergeRequestsUrl: String + + """ + HTTP URL of the issues page, filtered by this release and `state=open` """ - issuesUrl: String + openedIssuesUrl: String """ - HTTP URL of the merge request page filtered by this release + HTTP URL of the merge request page, filtered by this release and `state=open` """ - mergeRequestsUrl: String + openedMergeRequestsUrl: String """ HTTP URL of the release @@ -16295,6 +18375,31 @@ type ReleaseLinks { } """ +Values for sorting releases +""" +enum ReleaseSort { + """ + Created at ascending order + """ + CREATED_ASC + + """ + Created at descending order + """ + CREATED_DESC + + """ + Released at by ascending order + """ + RELEASED_AT_ASC + + """ + Released at by descending order + """ + RELEASED_AT_DESC +} + +""" Represents the source code attached to a release in a particular format """ type ReleaseSource { @@ -16414,6 +18519,46 @@ type RemoveProjectFromSecurityDashboardPayload { errors: [String!]! } +""" +Autogenerated input type of RepositionImageDiffNote +""" +input RepositionImageDiffNoteInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The global id of the DiffNote to update + """ + id: DiffNoteID! + + """ + The position of this note on a diff + """ + position: UpdateDiffImagePositionInput! +} + +""" +Autogenerated return type of RepositionImageDiffNote +""" +type RepositionImageDiffNotePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The note after mutation + """ + note: Note +} + type Repository { """ Indicates repository has no visible content @@ -16738,6 +18883,11 @@ type RootStorageStatistics { storageSize: Float! """ + The uploads size in bytes + """ + uploadsSize: Float! + + """ The wiki size in bytes """ wikiSize: Float! @@ -16912,6 +19062,18 @@ type RunnerPlatformEdge { node: RunnerPlatform } +type RunnerSetup { + """ + Instructions for installing the runner on the specified architecture + """ + installInstructions: String! + + """ + Instructions for registering the runner + """ + registerInstructions: String +} + """ Represents a CI configuration of SAST """ @@ -17431,6 +19593,43 @@ type SecurityReportSummarySection { vulnerabilitiesCount: Int } +enum SecurityReportTypeEnum { + """ + API FUZZING scan report + """ + API_FUZZING + + """ + CONTAINER SCANNING scan report + """ + CONTAINER_SCANNING + + """ + COVERAGE FUZZING scan report + """ + COVERAGE_FUZZING + + """ + DAST scan report + """ + DAST + + """ + DEPENDENCY SCANNING scan report + """ + DEPENDENCY_SCANNING + + """ + SAST scan report + """ + SAST + + """ + SECRET DETECTION scan report + """ + SECRET_DETECTION +} + """ The type of the security scanner """ @@ -17710,7 +19909,7 @@ type SentryErrorCollection { """ ID of the Sentry issue """ - id: ID! + id: GitlabErrorTrackingDetailedErrorID! ): SentryDetailedError """ @@ -17720,7 +19919,7 @@ type SentryErrorCollection { """ ID of the Sentry issue """ - id: ID! + id: GitlabErrorTrackingDetailedErrorID! ): SentryErrorStackTrace """ @@ -18099,7 +20298,7 @@ type Snippet implements Noteable { """ ID of the snippet """ - id: ID! + id: SnippetID! """ All notes on this noteable @@ -18377,6 +20576,11 @@ type SnippetEdge { node: Snippet } +""" +Identifier of Snippet +""" +scalar SnippetID + type SnippetPermissions { """ Indicates the user can perform `admin_snippet` on this resource @@ -18410,6 +20614,86 @@ type SnippetPermissions { } """ +Represents the Geo sync and verification state of a snippet repository +""" +type SnippetRepositoryRegistry { + """ + Timestamp when the SnippetRepositoryRegistry was created + """ + createdAt: Time + + """ + ID of the SnippetRepositoryRegistry + """ + id: ID! + + """ + Error message during sync of the SnippetRepositoryRegistry + """ + lastSyncFailure: String + + """ + Timestamp of the most recent successful sync of the SnippetRepositoryRegistry + """ + lastSyncedAt: Time + + """ + Timestamp after which the SnippetRepositoryRegistry should be resynced + """ + retryAt: Time + + """ + Number of consecutive failed sync attempts of the SnippetRepositoryRegistry + """ + retryCount: Int + + """ + ID of the Snippet Repository + """ + snippetRepositoryId: ID! + + """ + Sync state of the SnippetRepositoryRegistry + """ + state: RegistryState +} + +""" +The connection type for SnippetRepositoryRegistry. +""" +type SnippetRepositoryRegistryConnection { + """ + A list of edges. + """ + edges: [SnippetRepositoryRegistryEdge] + + """ + A list of nodes. + """ + nodes: [SnippetRepositoryRegistry] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type SnippetRepositoryRegistryEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: SnippetRepositoryRegistry +} + +""" Common sort values """ enum Sort { @@ -18585,6 +20869,11 @@ type TerraformState { id: ID! """ + The latest version of the Terraform state + """ + latestVersion: TerraformStateVersion + + """ Timestamp the Terraform state was locked """ lockedAt: Time @@ -18610,6 +20899,11 @@ The connection type for TerraformState. """ type TerraformStateConnection { """ + Total count of collection + """ + count: Int! + + """ A list of edges. """ edges: [TerraformStateEdge] @@ -18626,6 +20920,36 @@ type TerraformStateConnection { } """ +Autogenerated input type of TerraformStateDelete +""" +input TerraformStateDeleteInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Global ID of the Terraform state + """ + id: TerraformStateID! +} + +""" +Autogenerated return type of TerraformStateDelete +""" +type TerraformStateDeletePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" An edge in a connection. """ type TerraformStateEdge { @@ -18641,6 +20965,98 @@ type TerraformStateEdge { } """ +Identifier of Terraform::State +""" +scalar TerraformStateID + +""" +Autogenerated input type of TerraformStateLock +""" +input TerraformStateLockInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Global ID of the Terraform state + """ + id: TerraformStateID! +} + +""" +Autogenerated return type of TerraformStateLock +""" +type TerraformStateLockPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" +Autogenerated input type of TerraformStateUnlock +""" +input TerraformStateUnlockInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Global ID of the Terraform state + """ + id: TerraformStateID! +} + +""" +Autogenerated return type of TerraformStateUnlock +""" +type TerraformStateUnlockPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +type TerraformStateVersion { + """ + Timestamp the version was created + """ + createdAt: Time! + + """ + The user that created this version + """ + createdByUser: User + + """ + ID of the Terraform state version + """ + id: ID! + + """ + The job that created this version + """ + job: CiJob + + """ + Timestamp the version was updated + """ + updatedAt: Time! +} + +""" Represents the Geo sync and verification state of a terraform state version """ type TerraformStateVersionRegistry { @@ -18793,11 +21209,61 @@ Time represented in ISO 8601 """ scalar Time -interface TimeboxBurnupTimeSeriesInterface { +""" +Represents the time report stats for timeboxes +""" +type TimeReportStats { + """ + Completed issues metrics + """ + complete: TimeboxMetrics + + """ + Incomplete issues metrics + """ + incomplete: TimeboxMetrics + + """ + Total issues metrics + """ + total: TimeboxMetrics +} + +""" +Represents measured stats metrics for timeboxes +""" +type TimeboxMetrics { + """ + The count metric + """ + count: Int! + + """ + The weight metric + """ + weight: Int! +} + +""" +Represents a historically accurate report about the timebox +""" +type TimeboxReport { """ Daily scope and completed totals for burnup charts """ burnupTimeSeries: [BurnupChartDailyTotals!] + + """ + Represents the time report stats for the timebox + """ + stats: TimeReportStats +} + +interface TimeboxReportInterface { + """ + Historically accurate report about the timebox + """ + report: TimeboxReport } """ @@ -18817,11 +21283,6 @@ input Timeframe { type Timelog { """ - Timestamp of when the time tracked was spent at. Deprecated in 12.10: Use `spentAt` - """ - date: Time! @deprecated(reason: "Use `spentAt`. Deprecated in 12.10") - - """ The issue that logged time was added to """ issue: Issue @@ -18963,6 +21424,41 @@ type TodoConnection { } """ +Autogenerated input type of TodoCreate +""" +input TodoCreateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The global ID of the to-do item's parent. Issues, merge requests, designs and epics are supported + """ + targetId: TodoableID! +} + +""" +Autogenerated return type of TodoCreate +""" +type TodoCreatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The to-do created + """ + todo: Todo +} + +""" An edge in a connection. """ type TodoEdge { @@ -19069,7 +21565,7 @@ type TodoRestoreManyPayload { """ The ids of the updated todo items. Deprecated in 13.2: Use todos """ - updatedIds: [ID!]! @deprecated(reason: "Use todos. Deprecated in 13.2") + updatedIds: [TodoID!]! @deprecated(reason: "Use todos. Deprecated in 13.2") } """ @@ -19130,6 +21626,11 @@ enum TodoTargetEnum { } """ +Identifier of Todoable +""" +scalar TodoableID + +""" Autogenerated input type of TodosMarkAllDone """ input TodosMarkAllDoneInput { @@ -19161,7 +21662,7 @@ type TodosMarkAllDonePayload { """ Ids of the updated todos. Deprecated in 13.2: Use todos """ - updatedIds: [ID!]! @deprecated(reason: "Use todos. Deprecated in 13.2") + updatedIds: [TodoID!]! @deprecated(reason: "Use todos. Deprecated in 13.2") } """ @@ -19553,7 +22054,7 @@ input UpdateBoardListInput { """ Global ID of the list. """ - listId: ID! + listId: ListID! """ Position of list within the board @@ -19855,7 +22356,7 @@ input UpdateIssueInput { """ The ID of the parent epic. NULL when removing the association """ - epicId: ID + epicId: EpicID """ The desired health status @@ -20110,7 +22611,7 @@ input UpdateSnippetInput { """ The global id of the snippet to update """ - id: ID! + id: SnippetID! """ Title of the snippet @@ -20208,7 +22709,7 @@ type User { """ The global ID of the project the authored merge requests should be in. Incompatible with projectPath. """ - projectId: ID + projectId: ProjectID """ The full-path of the project the authored merge requests should be in. Incompatible with projectId. @@ -20293,7 +22794,7 @@ type User { """ The global ID of the project the authored merge requests should be in. Incompatible with projectPath. """ - projectId: ID + projectId: ProjectID """ The full-path of the project the authored merge requests should be in. Incompatible with projectId. @@ -20332,6 +22833,11 @@ type User { email: String """ + Group count for the user. Available only when feature flag `user_group_counts` is enabled + """ + groupCount: Int + + """ Group memberships of the user """ groupMemberships( @@ -20413,7 +22919,7 @@ type User { """ Array of global snippet ids, e.g., "gid://gitlab/ProjectSnippet/1" """ - ids: [ID!] + ids: [SnippetID!] """ Returns the last _n_ elements from the list. @@ -20616,6 +23122,11 @@ enum UserState { type UserStatus { """ + User availability status + """ + availability: AvailabilityEnum! + + """ String representation of emoji """ emoji: String @@ -20644,7 +23155,7 @@ enum VisibilityScopesEnum { } """ -Represents the count of vulnerabilities by severity on a particular day +Represents the count of vulnerabilities by severity on a particular day. This data is retained for 365 days """ type VulnerabilitiesCountByDay { """ @@ -20689,7 +23200,7 @@ type VulnerabilitiesCountByDay { } """ -Represents the number of vulnerabilities for a particular severity on a particular day +Represents the number of vulnerabilities for a particular severity on a particular day. This data is retained for 365 days """ type VulnerabilitiesCountByDayAndSeverity { """ diff --git a/doc/api/graphql/reference/gitlab_schema.json b/doc/api/graphql/reference/gitlab_schema.json index 6914ba29c57..de3f9c2665f 100644 --- a/doc/api/graphql/reference/gitlab_schema.json +++ b/doc/api/graphql/reference/gitlab_schema.json @@ -1481,6 +1481,525 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "AlertManagementHttpIntegration", + "description": "An endpoint and credentials used to accept alerts for a project", + "fields": [ + { + "name": "active", + "description": "Whether the endpoint is currently accepting alerts", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "apiUrl", + "description": "URL at which Prometheus metrics can be queried to populate the metrics dashboard", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the integration", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the integration", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "token", + "description": "Token used to authenticate alert notification requests", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "type", + "description": "Type of integration", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "AlertManagementIntegrationType", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "url", + "description": "Endpoint which accepts alert notifications", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + { + "kind": "INTERFACE", + "name": "AlertManagementIntegration", + "ofType": null + } + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "SCALAR", + "name": "AlertManagementHttpIntegrationID", + "description": "Identifier of AlertManagement::HttpIntegration", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INTERFACE", + "name": "AlertManagementIntegration", + "description": null, + "fields": [ + { + "name": "active", + "description": "Whether the endpoint is currently accepting alerts", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "apiUrl", + "description": "URL at which Prometheus metrics can be queried to populate the metrics dashboard", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the integration", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the integration", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "token", + "description": "Token used to authenticate alert notification requests", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "type", + "description": "Type of integration", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "AlertManagementIntegrationType", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "url", + "description": "Endpoint which accepts alert notifications", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": [ + { + "kind": "OBJECT", + "name": "AlertManagementHttpIntegration", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "AlertManagementPrometheusIntegration", + "ofType": null + } + ] + }, + { + "kind": "OBJECT", + "name": "AlertManagementIntegrationConnection", + "description": "The connection type for AlertManagementIntegration.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "AlertManagementIntegrationEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "INTERFACE", + "name": "AlertManagementIntegration", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "AlertManagementIntegrationEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "INTERFACE", + "name": "AlertManagementIntegration", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "ENUM", + "name": "AlertManagementIntegrationType", + "description": "Values of types of integrations", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "PROMETHEUS", + "description": "Prometheus integration", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "HTTP", + "description": "Integration with any monitoring tool", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "AlertManagementPrometheusIntegration", + "description": "An endpoint and credentials used to accept Prometheus alerts for a project", + "fields": [ + { + "name": "active", + "description": "Whether the endpoint is currently accepting alerts", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "apiUrl", + "description": "URL at which Prometheus metrics can be queried to populate the metrics dashboard", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the integration", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the integration", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "token", + "description": "Token used to authenticate alert notification requests", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "type", + "description": "Type of integration", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "AlertManagementIntegrationType", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "url", + "description": "Endpoint which accepts alert notifications", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + { + "kind": "INTERFACE", + "name": "AlertManagementIntegration", + "ofType": null + } + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "ENUM", "name": "AlertManagementSeverity", "description": "Alert severity values", @@ -1883,6 +2402,29 @@ "possibleTypes": null }, { + "kind": "ENUM", + "name": "AvailabilityEnum", + "description": "User availability status", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "NOT_SET", + "description": "Not Set", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "BUSY", + "description": "Busy", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "AwardEmoji", "description": "An emoji awarded by a user", @@ -2936,7 +3478,7 @@ "description": "Find a list by its global ID", "type": { "kind": "SCALAR", - "name": "ID", + "name": "ListID", "ofType": null }, "defaultValue": null @@ -3326,6 +3868,16 @@ "defaultValue": null }, { + "name": "includeDescendantGroups", + "description": "Include epics from descendant groups", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "true" + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -4202,6 +4754,42 @@ "deprecationReason": null }, { + "name": "userDiscussionsCount", + "description": "Number of user discussions in the epic", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "userNotesCount", + "description": "Number of user notes of the epic", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "userPermissions", "description": "Permissions for the current user on the resource", "args": [ @@ -4518,7 +5106,17 @@ "description": "Filter by epic ID. Incompatible with epicWildcardId", "type": { "kind": "SCALAR", - "name": "ID", + "name": "EpicID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "iterationTitle", + "description": "Filter by iteration title", + "type": { + "kind": "SCALAR", + "name": "String", "ofType": null }, "defaultValue": null @@ -4562,6 +5160,16 @@ "ofType": null }, "defaultValue": null + }, + { + "name": "iterationWildcardId", + "description": "Filter by iteration ID wildcard", + "type": { + "kind": "ENUM", + "name": "IterationWildcardId", + "ofType": null + }, + "defaultValue": null } ], "interfaces": null, @@ -5689,6 +6297,24 @@ "deprecationReason": null }, { + "name": "pipeline", + "description": "Pipeline the job belongs to", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "Pipeline", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "scheduledAt", "description": "Schedule for the build", "args": [ @@ -6184,6 +6810,24 @@ "description": "The connection type for ClusterAgent.", "fields": [ { + "name": "count", + "description": "Total count of collection", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "edges", "description": "A list of edges.", "args": [ @@ -6443,6 +7087,24 @@ "description": "The connection type for ClusterAgentToken.", "fields": [ { + "name": "count", + "description": "Total count of collection", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "edges", "description": "A list of edges.", "args": [ @@ -6785,6 +7447,246 @@ }, { "kind": "OBJECT", + "name": "CodeCoverageActivity", + "description": "Represents the code coverage activity for a group", + "fields": [ + { + "name": "averageCoverage", + "description": "Average percentage of the different code coverage results available for the group.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "coverageCount", + "description": "Number of different code coverage results available for the group.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "date", + "description": "Date when the code coverage was created.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Date", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "projectCount", + "description": "Number of projects with code coverage results for the group.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CodeCoverageActivityConnection", + "description": "The connection type for CodeCoverageActivity.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CodeCoverageActivityEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CodeCoverageActivity", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CodeCoverageActivityEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "CodeCoverageActivity", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CodeCoverageSummary", + "description": "Represents the code coverage summary for a project", + "fields": [ + { + "name": "averageCoverage", + "description": "Average percentage of the different code coverage results available for the project.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "coverageCount", + "description": "Number of different code coverage results available.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "lastUpdatedOn", + "description": "Latest date when the code coverage was created for the project.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Date", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "Commit", "description": null, "fields": [ @@ -6891,49 +7793,6 @@ "deprecationReason": null }, { - "name": "latestPipeline", - "description": "Latest pipeline of the commit. Deprecated in 12.5: Use `pipelines`", - "args": [ - { - "name": "status", - "description": "Filter pipelines by their status", - "type": { - "kind": "ENUM", - "name": "PipelineStatusEnum", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "ref", - "description": "Filter pipelines by the ref they are run for", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "sha", - "description": "Filter pipelines by the sha of the commit they are run for", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - } - ], - "type": { - "kind": "OBJECT", - "name": "Pipeline", - "ofType": null - }, - "isDeprecated": true, - "deprecationReason": "Use `pipelines`. Deprecated in 12.5" - }, - { "name": "message", "description": "Raw commit message", "args": [ @@ -7286,7 +8145,7 @@ }, { "name": "branch", - "description": "Name of the branch", + "description": "Name of the branch to commit into, it can be a new branch", "type": { "kind": "NON_NULL", "name": null, @@ -7299,6 +8158,16 @@ "defaultValue": null }, { + "name": "startBranch", + "description": "If on a new branch, name of the original branch", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { "name": "message", "description": "Raw commit message", "type": { @@ -7454,8 +8323,8 @@ "kind": "NON_NULL", "name": null, "ofType": { - "kind": "ENUM", - "name": "ProjectSettingEnum", + "kind": "SCALAR", + "name": "String", "ofType": null } }, @@ -7995,6 +8864,924 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "ContainerRepository", + "description": "A container repository", + "fields": [ + { + "name": "canDelete", + "description": "Can the current user delete the container repository.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "createdAt", + "description": "Timestamp when the container repository was created.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "expirationPolicyCleanupStatus", + "description": "The tags cleanup status for the container repository.", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "ContainerRepositoryCleanupStatus", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "expirationPolicyStartedAt", + "description": "Timestamp when the cleanup done by the expiration policy was started on the container repository.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the container repository.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "location", + "description": "URL of the container repository.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the container repository.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "path", + "description": "Path of the container repository.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "status", + "description": "Status of the container repository.", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "ContainerRepositoryStatus", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "tagsCount", + "description": "Number of tags associated with this image.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "updatedAt", + "description": "Timestamp when the container repository was updated.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "ENUM", + "name": "ContainerRepositoryCleanupStatus", + "description": "Status of the tags cleanup of a container repository", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "UNSCHEDULED", + "description": "The tags cleanup is not scheduled. This is the default state.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "SCHEDULED", + "description": "The tags cleanup is scheduled and is going to be executed shortly.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "UNFINISHED", + "description": "The tags cleanup has been partially executed. There are still remaining tags to delete.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "ONGOING", + "description": "The tags cleanup is ongoing.", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ContainerRepositoryConnection", + "description": "The connection type for ContainerRepository.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "ContainerRepositoryEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "ContainerRepository", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ContainerRepositoryDetails", + "description": "Details of a container repository", + "fields": [ + { + "name": "canDelete", + "description": "Can the current user delete the container repository.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "createdAt", + "description": "Timestamp when the container repository was created.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "expirationPolicyCleanupStatus", + "description": "The tags cleanup status for the container repository.", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "ContainerRepositoryCleanupStatus", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "expirationPolicyStartedAt", + "description": "Timestamp when the cleanup done by the expiration policy was started on the container repository.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the container repository.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "location", + "description": "URL of the container repository.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the container repository.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "path", + "description": "Path of the container repository.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "status", + "description": "Status of the container repository.", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "ContainerRepositoryStatus", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "tags", + "description": "Tags of the container repository", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ContainerRepositoryTagConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "tagsCount", + "description": "Number of tags associated with this image.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "updatedAt", + "description": "Timestamp when the container repository was updated.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ContainerRepositoryEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "ContainerRepository", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "SCALAR", + "name": "ContainerRepositoryID", + "description": "Identifier of ContainerRepository", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "ENUM", + "name": "ContainerRepositoryStatus", + "description": "Status of a container repository", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "DELETE_SCHEDULED", + "description": "Delete Scheduled status.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "DELETE_FAILED", + "description": "Delete Failed status.", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ContainerRepositoryTag", + "description": "A tag from a container repository", + "fields": [ + { + "name": "canDelete", + "description": "Can the current user delete this tag.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "createdAt", + "description": "Timestamp when the tag was created.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "digest", + "description": "Digest of the tag.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "location", + "description": "URL of the tag.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the tag.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "path", + "description": "Path of the tag.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "revision", + "description": "Revision of the tag.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "shortRevision", + "description": "Short revision of the tag.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "totalSize", + "description": "The size of the tag.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ContainerRepositoryTagConnection", + "description": "The connection type for ContainerRepositoryTag.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "ContainerRepositoryTagEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "ContainerRepositoryTag", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ContainerRepositoryTagEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "ContainerRepositoryTag", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "INPUT_OBJECT", "name": "CreateAlertIssueInput", "description": "Autogenerated input type of CreateAlertIssue", @@ -8306,7 +10093,7 @@ "inputFields": [ { "name": "projectPath", - "description": "The project full path the board is associated with.", + "description": "The project full path the resource is associated with", "type": { "kind": "SCALAR", "name": "ID", @@ -8316,7 +10103,7 @@ }, { "name": "groupPath", - "description": "The group full path the board is associated with.", + "description": "The group full path the resource is associated with", "type": { "kind": "SCALAR", "name": "ID", @@ -8349,7 +10136,7 @@ "description": "The ID of the milestone to be assigned to the board.", "type": { "kind": "SCALAR", - "name": "ID", + "name": "MilestoneID", "ofType": null }, "defaultValue": null @@ -8375,7 +10162,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "LabelID", "ofType": null } } @@ -8712,6 +10499,136 @@ }, { "kind": "INPUT_OBJECT", + "name": "CreateCustomEmojiInput", + "description": "Autogenerated input type of CreateCustomEmoji", + "fields": null, + "inputFields": [ + { + "name": "groupPath", + "description": "Namespace full path the emoji is associated with", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "name", + "description": "Name of the emoji", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "url", + "description": "Location of the emoji file", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CreateCustomEmojiPayload", + "description": "Autogenerated return type of CreateCustomEmoji", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "customEmoji", + "description": "The new custom emoji", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "CustomEmoji", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", "name": "CreateDiffNoteInput", "description": "Autogenerated input type of CreateDiffNote", "fields": null, @@ -10334,6 +12251,213 @@ ] }, { + "kind": "OBJECT", + "name": "CustomEmoji", + "description": "A custom emoji uploaded by user", + "fields": [ + { + "name": "external", + "description": "Whether the emoji is an external link", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "The ID of the emoji", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "CustomEmojiID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "The name of the emoji", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "url", + "description": "The link to file of the emoji", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CustomEmojiConnection", + "description": "The connection type for CustomEmoji.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CustomEmojiEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CustomEmoji", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CustomEmojiEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "CustomEmoji", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "SCALAR", + "name": "CustomEmojiID", + "description": "Identifier of CustomEmoji", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "INPUT_OBJECT", "name": "DastOnDemandScanCreateInput", "description": "Autogenerated input type of DastOnDemandScanCreate", @@ -10503,7 +12627,7 @@ }, { "name": "globalId", - "description": "ID of the DAST scanner profile", + "description": "ID of the DAST scanner profile. Deprecated in 13.6: Use `id`", "args": [ ], @@ -10516,12 +12640,12 @@ "ofType": null } }, - "isDeprecated": false, - "deprecationReason": null + "isDeprecated": true, + "deprecationReason": "Use `id`. Deprecated in 13.6" }, { "name": "id", - "description": "ID of the DAST scanner profile. Deprecated in 13.4: Use `global_id`", + "description": "ID of the DAST scanner profile", "args": [ ], @@ -10530,12 +12654,12 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "DastScannerProfileID", "ofType": null } }, - "isDeprecated": true, - "deprecationReason": "Use `global_id`. Deprecated in 13.4" + "isDeprecated": false, + "deprecationReason": null }, { "name": "profileName", @@ -10850,7 +12974,7 @@ }, { "name": "globalId", - "description": "ID of the scanner profile.", + "description": "ID of the scanner profile.. Deprecated in 13.6: Use `id`", "args": [ ], @@ -10859,22 +12983,22 @@ "name": "DastScannerProfileID", "ofType": null }, - "isDeprecated": false, - "deprecationReason": null + "isDeprecated": true, + "deprecationReason": "Use `id`. Deprecated in 13.6" }, { "name": "id", - "description": "ID of the scanner profile.. Deprecated in 13.4: Use `global_id`", + "description": "ID of the scanner profile.", "args": [ ], "type": { "kind": "SCALAR", - "name": "ID", + "name": "DastScannerProfileID", "ofType": null }, - "isDeprecated": true, - "deprecationReason": "Use `global_id`. Deprecated in 13.4" + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -12041,6 +14165,242 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "DastSiteValidation", + "description": "Represents a DAST Site Validation", + "fields": [ + { + "name": "id", + "description": "ID of the site validation", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "DastSiteValidationID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "status", + "description": "The status of the validation", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "DastSiteProfileValidationStatusEnum", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "DastSiteValidationCreateInput", + "description": "Autogenerated input type of DastSiteValidationCreate", + "fields": null, + "inputFields": [ + { + "name": "fullPath", + "description": "The project the site profile belongs to.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "dastSiteTokenId", + "description": "ID of the site token.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "DastSiteTokenID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "validationPath", + "description": "The path to be requested during validation.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "strategy", + "description": "The validation strategy to be used.", + "type": { + "kind": "ENUM", + "name": "DastSiteValidationStrategyEnum", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "DastSiteValidationCreatePayload", + "description": "Autogenerated return type of DastSiteValidationCreate", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the site validation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "DastSiteValidationID", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "status", + "description": "The current validation status.", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "DastSiteProfileValidationStatusEnum", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "SCALAR", + "name": "DastSiteValidationID", + "description": "Identifier of DastSiteValidation", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "ENUM", + "name": "DastSiteValidationStrategyEnum", + "description": null, + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "TEXT_FILE", + "description": "Text file validation", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "HEADER", + "description": "Header validation", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { "kind": "SCALAR", "name": "Date", "description": "Date represented in ISO 8601", @@ -12064,7 +14424,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "MetricsDashboardAnnotationID", "ofType": null } }, @@ -12574,7 +14934,7 @@ "description": "The Global ID of the most recent acceptable version", "type": { "kind": "SCALAR", - "name": "ID", + "name": "DesignManagementVersionID", "ofType": null }, "defaultValue": null @@ -13023,7 +15383,7 @@ "description": "Find a design by its ID", "type": { "kind": "SCALAR", - "name": "ID", + "name": "DesignManagementDesignID", "ofType": null }, "defaultValue": null @@ -13059,7 +15419,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "DesignManagementDesignAtVersionID", "ofType": null } }, @@ -13089,7 +15449,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "DesignManagementDesignID", "ofType": null } } @@ -13119,7 +15479,7 @@ "description": "Filters designs to only those that existed at the version. If argument is omitted or nil then all designs will reflect the latest version", "type": { "kind": "SCALAR", - "name": "ID", + "name": "DesignManagementVersionID", "ofType": null }, "defaultValue": null @@ -13232,7 +15592,7 @@ "description": "The Global ID of the version", "type": { "kind": "SCALAR", - "name": "ID", + "name": "DesignManagementVersionID", "ofType": null }, "defaultValue": null @@ -13265,7 +15625,7 @@ "description": "The Global ID of the most recent acceptable version", "type": { "kind": "SCALAR", - "name": "ID", + "name": "DesignManagementVersionID", "ofType": null }, "defaultValue": null @@ -13687,7 +16047,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "DesignManagementDesignAtVersionID", "ofType": null } }, @@ -13714,7 +16074,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "DesignManagementVersionID", "ofType": null } }, @@ -13877,6 +16237,16 @@ }, { "kind": "SCALAR", + "name": "DesignManagementDesignAtVersionID", + "description": "Identifier of DesignManagement::DesignAtVersion", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "SCALAR", "name": "DesignManagementDesignID", "description": "Identifier of DesignManagement::Design", "fields": null, @@ -14184,6 +16554,16 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "DesignManagementVersionID", + "description": "Identifier of DesignManagement::Version", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "DesignVersion", "description": "A specific version in which designs were added, modified or deleted", @@ -14197,7 +16577,7 @@ "description": "The ID of the DesignAtVersion", "type": { "kind": "SCALAR", - "name": "ID", + "name": "DesignManagementDesignAtVersionID", "ofType": null }, "defaultValue": null @@ -14207,7 +16587,7 @@ "description": "The ID of a specific design", "type": { "kind": "SCALAR", - "name": "ID", + "name": "DesignManagementDesignID", "ofType": null }, "defaultValue": null @@ -14307,7 +16687,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "DesignManagementDesignID", "ofType": null } } @@ -14782,6 +17162,112 @@ }, { "kind": "INPUT_OBJECT", + "name": "DestroyContainerRepositoryInput", + "description": "Autogenerated input type of DestroyContainerRepository", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "ID of the container repository.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ContainerRepositoryID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "DestroyContainerRepositoryPayload", + "description": "Autogenerated return type of DestroyContainerRepository", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "containerRepository", + "description": "The container repository policy after scheduling the deletion.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "ContainerRepository", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", "name": "DestroyNoteInput", "description": "Autogenerated input type of DestroyNote", "fields": null, @@ -14896,7 +17382,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "SnippetID", "ofType": null } }, @@ -15124,6 +17610,220 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "DevopsAdoptionSegment", + "description": "Segment", + "fields": [ + { + "name": "groups", + "description": "Assigned groups", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "GroupConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the segment", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the segment", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "DevopsAdoptionSegmentConnection", + "description": "The connection type for DevopsAdoptionSegment.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "DevopsAdoptionSegmentEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "DevopsAdoptionSegment", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "DevopsAdoptionSegmentEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "DevopsAdoptionSegment", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "INPUT_OBJECT", "name": "DiffImagePositionInput", "description": null, @@ -15243,6 +17943,16 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "DiffNoteID", + "description": "Identifier of DiffNote", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "INPUT_OBJECT", "name": "DiffPathsInput", "description": null, @@ -16567,14 +19277,18 @@ }, { "name": "path", - "description": "The path to the environment. Will always return null if `expose_environment_path_in_alert_details` feature flag is disabled", + "description": "The path to the environment.", "args": [ ], "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } }, "isDeprecated": false, "deprecationReason": null @@ -16728,6 +19442,108 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "EnvironmentsCanaryIngressUpdateInput", + "description": "Autogenerated input type of EnvironmentsCanaryIngressUpdate", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "The global ID of the environment to update", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "EnvironmentID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "weight", + "description": "The weight of the Canary Ingress", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "EnvironmentsCanaryIngressUpdatePayload", + "description": "Autogenerated return type of EnvironmentsCanaryIngressUpdate", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "Epic", "description": "Represents an epic", @@ -16891,6 +19707,16 @@ "defaultValue": null }, { + "name": "includeDescendantGroups", + "description": "Include epics from descendant groups", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "true" + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -17767,6 +20593,42 @@ "deprecationReason": null }, { + "name": "userDiscussionsCount", + "description": "Number of user discussions in the epic", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "userNotesCount", + "description": "Number of user notes of the epic", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "userPermissions", "description": "Permissions for the current user on the resource", "args": [ @@ -18391,6 +21253,20 @@ "deprecationReason": null }, { + "name": "blockedByCount", + "description": "Count of issues blocking this issue", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "closedAt", "description": "Timestamp of when the issue was closed", "args": [ @@ -18550,20 +21426,6 @@ "deprecationReason": null }, { - "name": "designs", - "description": "The designs associated with this issue. Deprecated in 12.2: Use `designCollection`", - "args": [ - - ], - "type": { - "kind": "OBJECT", - "name": "DesignCollection", - "ofType": null - }, - "isDeprecated": true, - "deprecationReason": "Use `designCollection`. Deprecated in 12.2" - }, - { "name": "discussionLocked", "description": "Indicates discussion is locked on the issue", "args": [ @@ -18671,6 +21533,24 @@ "deprecationReason": null }, { + "name": "emailsDisabled", + "description": "Indicates if a project has email notifications disabled: `true` if email notifications are disabled", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "epic", "description": "Epic to which this issue belongs", "args": [ @@ -18717,6 +21597,34 @@ "deprecationReason": null }, { + "name": "humanTimeEstimate", + "description": "Human-readable time estimate of the issue", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "humanTotalTimeSpent", + "description": "Human-readable total time reported as spent on the issue", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "id", "description": "Global ID of the epic-issue relation", "args": [ @@ -18830,6 +21738,34 @@ "deprecationReason": null }, { + "name": "moved", + "description": "Indicates if issue got moved from other project", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "movedTo", + "description": "Updated Issue after it got moved to another project", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Issue", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "notes", "description": "All notes on this noteable", "args": [ @@ -19191,6 +22127,20 @@ "deprecationReason": null }, { + "name": "updatedBy", + "description": "User that last updated the issue", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "User", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "upvotes", "description": "Number of upvotes the issue has received", "args": [ @@ -19209,6 +22159,24 @@ "deprecationReason": null }, { + "name": "userDiscussionsCount", + "description": "Number of user discussions in the issue", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "userNotesCount", "description": "Number of user notes of the issue", "args": [ @@ -19387,6 +22355,24 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "weight", + "description": "Total weight of issues collection", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -20382,6 +23368,77 @@ "deprecationReason": null }, { + "name": "snippetRepositoryRegistries", + "description": "Find snippet repository registries on this Geo node. Available only when feature flag `geo_snippet_repository_replication` is enabled", + "args": [ + { + "name": "ids", + "description": "Filters registries by their ID", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "SnippetRepositoryRegistryConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "syncObjectStorage", "description": "Indicates if this secondary node will replicate blobs in Object Storage", "args": [ @@ -20503,6 +23560,16 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "GitlabErrorTrackingDetailedErrorID", + "description": "Identifier of Gitlab::ErrorTracking::DetailedError", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "GrafanaIntegration", "description": null, @@ -20580,24 +23647,6 @@ "deprecationReason": null }, { - "name": "token", - "description": "API token for the Grafana integration. Deprecated in 12.7: Plain text token has been masked for security reasons", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } - }, - "isDeprecated": true, - "deprecationReason": "Plain text token has been masked for security reasons. Deprecated in 12.7" - }, - { "name": "updatedAt", "description": "Timestamp of the issue's last activity", "args": [ @@ -20720,7 +23769,7 @@ "description": "Find a board by its ID", "type": { "kind": "SCALAR", - "name": "ID", + "name": "BoardID", "ofType": null }, "defaultValue": null @@ -20775,6 +23824,136 @@ "deprecationReason": null }, { + "name": "codeCoverageActivities", + "description": "Represents the code coverage activity for this group. Available only when feature flag `group_coverage_data_report_graph` is enabled", + "args": [ + { + "name": "startDate", + "description": "First day for which to fetch code coverage activity (maximum time window is set to 90 days)", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Date", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "CodeCoverageActivityConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "containerRepositories", + "description": "Container repositories of the project", + "args": [ + { + "name": "name", + "description": "Filter the container repositories by their name", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ContainerRepositoryConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "containsLockedProjects", "description": "Includes at least one project where the repository size exceeds the limit", "args": [ @@ -20793,6 +23972,59 @@ "deprecationReason": null }, { + "name": "customEmoji", + "description": "Custom emoji within this namespace. Available only when feature flag `custom_emoji` is enabled", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "CustomEmojiConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "description", "description": "Description of the namespace", "args": [ @@ -20973,6 +24205,16 @@ "ofType": null }, "defaultValue": null + }, + { + "name": "includeDescendantGroups", + "description": "Include epics from descendant groups", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "true" } ], "type": { @@ -21124,6 +24366,16 @@ "defaultValue": null }, { + "name": "includeDescendantGroups", + "description": "Include epics from descendant groups", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "true" + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -21435,7 +24687,7 @@ }, { "name": "assigneeId", - "description": "ID of a user assigned to the issues, \"none\" and \"any\" values supported", + "description": "ID of a user assigned to the issues, \"none\" and \"any\" values are supported", "type": { "kind": "SCALAR", "name": "String", @@ -21566,6 +24818,16 @@ "defaultValue": null }, { + "name": "epicId", + "description": "ID of an epic associated with the issues, \"none\" and \"any\" values are supported", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { "name": "includeSubgroups", "description": "Include issues belonging to subgroups", "type": { @@ -22467,6 +25729,20 @@ "deprecationReason": null }, { + "name": "stats", + "description": "Group statistics", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "GroupStats", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "storageSizeLimit", "description": "Total storage limit of the root namespace in bytes", "args": [ @@ -23018,7 +26294,16 @@ "name": "vulnerabilityGrades", "description": "Represents vulnerable project counts for each grade", "args": [ - + { + "name": "includeSubgroups", + "description": "Include grades belonging to subgroups", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "false" + } ], "type": { "kind": "NON_NULL", @@ -23224,6 +26509,128 @@ }, { "kind": "OBJECT", + "name": "GroupConnection", + "description": "The connection type for Group.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "GroupEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "Group", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "GroupEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Group", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "SCALAR", + "name": "GroupID", + "description": "Identifier of Group", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "GroupMember", "description": "Represents a Group Membership", "fields": [ @@ -23521,6 +26928,74 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "GroupReleaseStats", + "description": "Contains release-related statistics about a group", + "fields": [ + { + "name": "releasesCount", + "description": "Total number of releases in all descendant projects of the group. Will always return `null` if `group_level_release_statistics` feature flag is disabled", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "releasesPercentage", + "description": "Percentage of the group's descendant projects that have at least one release. Will always return `null` if `group_level_release_statistics` feature flag is disabled", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "GroupStats", + "description": "Contains statistics about a group", + "fields": [ + { + "name": "releaseStats", + "description": "Statistics related to releases within the group", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "GroupReleaseStats", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "ENUM", "name": "HealthStatus", "description": "Health status of an issue or epic", @@ -23550,6 +27025,462 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "HttpIntegrationCreateInput", + "description": "Autogenerated input type of HttpIntegrationCreate", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "The project to create the integration in", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "name", + "description": "The name of the integration", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "active", + "description": "Whether the integration is receiving alerts", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "HttpIntegrationCreatePayload", + "description": "Autogenerated return type of HttpIntegrationCreate", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "integration", + "description": "The HTTP integration", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "AlertManagementHttpIntegration", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "HttpIntegrationDestroyInput", + "description": "Autogenerated input type of HttpIntegrationDestroy", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "The id of the integration to remove", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "AlertManagementHttpIntegrationID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "HttpIntegrationDestroyPayload", + "description": "Autogenerated return type of HttpIntegrationDestroy", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "integration", + "description": "The HTTP integration", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "AlertManagementHttpIntegration", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "HttpIntegrationResetTokenInput", + "description": "Autogenerated input type of HttpIntegrationResetToken", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "The id of the integration to mutate", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "AlertManagementHttpIntegrationID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "HttpIntegrationResetTokenPayload", + "description": "Autogenerated return type of HttpIntegrationResetToken", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "integration", + "description": "The HTTP integration", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "AlertManagementHttpIntegration", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "HttpIntegrationUpdateInput", + "description": "Autogenerated input type of HttpIntegrationUpdate", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "The id of the integration to mutate", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "AlertManagementHttpIntegrationID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "name", + "description": "The name of the integration", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "active", + "description": "Whether the integration is receiving alerts", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "HttpIntegrationUpdatePayload", + "description": "Autogenerated return type of HttpIntegrationUpdate", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "integration", + "description": "The HTTP integration", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "AlertManagementHttpIntegration", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "SCALAR", "name": "ID", "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", @@ -24191,6 +28122,20 @@ "deprecationReason": null }, { + "name": "blockedByCount", + "description": "Count of issues blocking this issue", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "closedAt", "description": "Timestamp of when the issue was closed", "args": [ @@ -24350,20 +28295,6 @@ "deprecationReason": null }, { - "name": "designs", - "description": "The designs associated with this issue. Deprecated in 12.2: Use `designCollection`", - "args": [ - - ], - "type": { - "kind": "OBJECT", - "name": "DesignCollection", - "ofType": null - }, - "isDeprecated": true, - "deprecationReason": "Use `designCollection`. Deprecated in 12.2" - }, - { "name": "discussionLocked", "description": "Indicates discussion is locked on the issue", "args": [ @@ -24471,6 +28402,24 @@ "deprecationReason": null }, { + "name": "emailsDisabled", + "description": "Indicates if a project has email notifications disabled: `true` if email notifications are disabled", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "epic", "description": "Epic to which this issue belongs", "args": [ @@ -24499,6 +28448,34 @@ "deprecationReason": null }, { + "name": "humanTimeEstimate", + "description": "Human-readable time estimate of the issue", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "humanTotalTimeSpent", + "description": "Human-readable total time reported as spent on the issue", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "id", "description": "ID of the issue", "args": [ @@ -24616,6 +28593,34 @@ "deprecationReason": null }, { + "name": "moved", + "description": "Indicates if issue got moved from other project", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "movedTo", + "description": "Updated Issue after it got moved to another project", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Issue", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "notes", "description": "All notes on this noteable", "args": [ @@ -24963,6 +28968,20 @@ "deprecationReason": null }, { + "name": "updatedBy", + "description": "User that last updated the issue", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "User", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "upvotes", "description": "Number of upvotes the issue has received", "args": [ @@ -24981,6 +29000,24 @@ "deprecationReason": null }, { + "name": "userDiscussionsCount", + "description": "Number of user discussions in the issue", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "userNotesCount", "description": "Number of user notes of the issue", "args": [ @@ -25159,6 +29196,24 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "weight", + "description": "Total weight of issues collection", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -26137,7 +30192,7 @@ "description": "Global ID of the epic to be assigned to the issue, epic will be removed if absent or set to null", "type": { "kind": "SCALAR", - "name": "ID", + "name": "EpicID", "ofType": null }, "defaultValue": null @@ -27015,6 +31070,18 @@ "description": "Published issues shown first", "isDeprecated": false, "deprecationReason": null + }, + { + "name": "SLA_DUE_AT_ASC", + "description": "Issues with earliest SLA due time shown first", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "SLA_DUE_AT_DESC", + "description": "Issues with latest SLA due time shown first", + "isDeprecated": false, + "deprecationReason": null } ], "possibleTypes": null @@ -27167,28 +31234,6 @@ "description": "Represents an iteration object", "fields": [ { - "name": "burnupTimeSeries", - "description": "Daily scope and completed totals for burnup charts", - "args": [ - - ], - "type": { - "kind": "LIST", - "name": null, - "ofType": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "OBJECT", - "name": "BurnupChartDailyTotals", - "ofType": null - } - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { "name": "createdAt", "description": "Timestamp of iteration creation", "args": [ @@ -27285,6 +31330,20 @@ "deprecationReason": null }, { + "name": "report", + "description": "Historically accurate report about the timebox", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "TimeboxReport", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "scopedPath", "description": "Web path of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts", "args": [ @@ -27421,7 +31480,7 @@ "interfaces": [ { "kind": "INTERFACE", - "name": "TimeboxBurnupTimeSeriesInterface", + "name": "TimeboxReportInterface", "ofType": null } ], @@ -27592,6 +31651,29 @@ "possibleTypes": null }, { + "kind": "ENUM", + "name": "IterationWildcardId", + "description": "Iteration ID wildcard values", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "NONE", + "description": "No iteration is assigned", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "ANY", + "description": "An iteration is assigned", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { "kind": "SCALAR", "name": "JSON", "description": "Represents untyped JSON", @@ -28726,6 +32808,148 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "LabelCreateInput", + "description": "Autogenerated input type of LabelCreate", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "The project full path the resource is associated with", + "type": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "groupPath", + "description": "The group full path the resource is associated with", + "type": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "title", + "description": "Title of the label", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "description", + "description": "Description of the label", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "color", + "description": "The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the CSS color names in https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": "\"#428BCA\"" + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "LabelCreatePayload", + "description": "Autogenerated return type of LabelCreate", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "label", + "description": "The label after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Label", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "LabelEdge", "description": "An edge in a connection.", @@ -28833,7 +33057,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "SnippetID", "ofType": null } }, @@ -29892,20 +34116,6 @@ "deprecationReason": null }, { - "name": "mergeCommitMessage", - "description": "Default merge commit message of the merge request. Deprecated in 11.8: Use `defaultMergeCommitMessage`", - "args": [ - - ], - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "isDeprecated": true, - "deprecationReason": "Use `defaultMergeCommitMessage`. Deprecated in 11.8" - }, - { "name": "mergeCommitSha", "description": "SHA of the merge request commit (set once merged)", "args": [ @@ -30636,6 +34846,20 @@ "deprecationReason": null }, { + "name": "userDiscussionsCount", + "description": "Number of user discussions in the merge request", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "userNotesCount", "description": "User notes count of the merge request", "args": [ @@ -31644,7 +35868,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "LabelID", "ofType": null } } @@ -32929,33 +37153,21 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "MetricsDashboardAnnotationID", + "description": "Identifier of Metrics::Dashboard::Annotation", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "Milestone", "description": "Represents a milestone", "fields": [ { - "name": "burnupTimeSeries", - "description": "Daily scope and completed totals for burnup charts", - "args": [ - - ], - "type": { - "kind": "LIST", - "name": null, - "ofType": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "OBJECT", - "name": "BurnupChartDailyTotals", - "ofType": null - } - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { "name": "createdAt", "description": "Timestamp of milestone creation", "args": [ @@ -33056,6 +37268,20 @@ "deprecationReason": null }, { + "name": "report", + "description": "Historically accurate report about the timebox", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "TimeboxReport", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "startDate", "description": "Timestamp of the milestone start date", "args": [ @@ -33178,7 +37404,7 @@ "interfaces": [ { "kind": "INTERFACE", - "name": "TimeboxBurnupTimeSeriesInterface", + "name": "TimeboxReportInterface", "ofType": null } ], @@ -33940,6 +38166,33 @@ "deprecationReason": null }, { + "name": "createCustomEmoji", + "description": ". Available only when feature flag `custom_emoji` is enabled", + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "CreateCustomEmojiInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "CreateCustomEmojiPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "createDiffNote", "description": null, "args": [ @@ -34399,6 +38652,33 @@ "deprecationReason": null }, { + "name": "dastSiteValidationCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DastSiteValidationCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DastSiteValidationCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "deleteAnnotation", "description": null, "args": [ @@ -34561,6 +38841,33 @@ "deprecationReason": null }, { + "name": "destroyContainerRepository", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DestroyContainerRepositoryInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DestroyContainerRepositoryPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "destroyNote", "description": null, "args": [ @@ -34669,6 +38976,33 @@ "deprecationReason": "Use vulnerabilityDismiss. Deprecated in 13.5" }, { + "name": "environmentsCanaryIngressUpdate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "EnvironmentsCanaryIngressUpdateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "EnvironmentsCanaryIngressUpdatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "epicAddIssue", "description": null, "args": [ @@ -34750,6 +39084,114 @@ "deprecationReason": null }, { + "name": "httpIntegrationCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "HttpIntegrationCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "HttpIntegrationCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "httpIntegrationDestroy", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "HttpIntegrationDestroyInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "HttpIntegrationDestroyPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "httpIntegrationResetToken", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "HttpIntegrationResetTokenInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "HttpIntegrationResetTokenPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "httpIntegrationUpdate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "HttpIntegrationUpdateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "HttpIntegrationUpdatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "issueMove", "description": null, "args": [ @@ -35101,6 +39543,33 @@ "deprecationReason": null }, { + "name": "labelCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "LabelCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "LabelCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "markAsSpamSnippet", "description": null, "args": [ @@ -35452,6 +39921,141 @@ "deprecationReason": null }, { + "name": "prometheusIntegrationCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "PrometheusIntegrationCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "PrometheusIntegrationCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "prometheusIntegrationResetToken", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "PrometheusIntegrationResetTokenInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "PrometheusIntegrationResetTokenPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "prometheusIntegrationUpdate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "PrometheusIntegrationUpdateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "PrometheusIntegrationUpdatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "promoteToEpic", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "PromoteToEpicInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "PromoteToEpicPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "releaseCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "ReleaseCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ReleaseCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "removeAwardEmoji", "description": null, "args": [ @@ -35506,6 +40110,33 @@ "deprecationReason": null }, { + "name": "repositionImageDiffNote", + "description": "Repositions a DiffNote on an image (a `Note` where the `position.positionType` is `\"image\"`)", + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "RepositionImageDiffNoteInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "RepositionImageDiffNotePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "revertVulnerabilityToDetected", "description": null, "args": [ @@ -35560,6 +40191,114 @@ "deprecationReason": "Use DastOnDemandScanCreate. Deprecated in 13.4" }, { + "name": "terraformStateDelete", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "TerraformStateDeleteInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "TerraformStateDeletePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "terraformStateLock", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "TerraformStateLockInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "TerraformStateLockPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "terraformStateUnlock", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "TerraformStateUnlockInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "TerraformStateUnlockPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "todoCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "TodoCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "TodoCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "todoMarkDone", "description": null, "args": [ @@ -36822,6 +41561,12 @@ "description": "Most similar to the search query", "isDeprecated": false, "deprecationReason": null + }, + { + "name": "STORAGE", + "description": "Sort by storage size", + "isDeprecated": false, + "deprecationReason": null } ], "possibleTypes": null @@ -36905,7 +41650,17 @@ "description": "Filter by epic ID. Incompatible with epicWildcardId", "type": { "kind": "SCALAR", - "name": "ID", + "name": "EpicID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "iterationTitle", + "description": "Filter by iteration title", + "type": { + "kind": "SCALAR", + "name": "String", "ofType": null }, "defaultValue": null @@ -37416,6 +42171,24 @@ "deprecationReason": null }, { + "name": "repositionNote", + "description": "Indicates the user can perform `reposition_note` on this resource", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "resolveNote", "description": "Indicates the user can perform `resolve_note` on this resource", "args": [ @@ -38354,6 +43127,59 @@ "deprecationReason": null }, { + "name": "downstream", + "description": "Pipelines this pipeline will trigger", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "PipelineConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "duration", "description": "Duration of the pipeline in seconds", "args": [ @@ -38418,6 +43244,105 @@ "deprecationReason": null }, { + "name": "jobs", + "description": "Jobs belonging to the pipeline", + "args": [ + { + "name": "securityReportTypes", + "description": "Filter jobs by the type of security report they produce", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "SecurityReportTypeEnum", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "CiJobConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "path", + "description": "Relative path to the pipeline's page", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "project", + "description": "Project the pipeline belongs to", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Project", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "retryable", "description": "Specifies if a pipeline can be retried", "args": [ @@ -38468,6 +43393,20 @@ "deprecationReason": null }, { + "name": "sourceJob", + "description": "Job where pipeline was triggered from", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "CiJob", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "stages", "description": "Stages of the pipeline", "args": [ @@ -38571,6 +43510,20 @@ "deprecationReason": null }, { + "name": "upstream", + "description": "Pipeline that triggered the pipeline", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Pipeline", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "user", "description": "Pipeline user", "args": [ @@ -39284,7 +44237,7 @@ }, { "name": "search", - "description": "Search criteria for filtering alerts. This will search on title, description, service, monitoring_tool.", + "description": "Search query for title, description, service, or monitoring_tool.", "type": { "kind": "SCALAR", "name": "String", @@ -39317,7 +44270,7 @@ "args": [ { "name": "search", - "description": "Search criteria for filtering alerts. This will search on title, description, service, monitoring_tool.", + "description": "Search query for title, description, service, or monitoring_tool.", "type": { "kind": "SCALAR", "name": "String", @@ -39388,7 +44341,7 @@ }, { "name": "search", - "description": "Search criteria for filtering alerts. This will search on title, description, service, monitoring_tool.", + "description": "Search query for title, description, service, or monitoring_tool.", "type": { "kind": "SCALAR", "name": "String", @@ -39456,6 +44409,59 @@ "deprecationReason": null }, { + "name": "alertManagementIntegrations", + "description": "Integrations which can receive alerts for the project", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "AlertManagementIntegrationConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "allowMergeOnSkippedPipeline", "description": "If `only_allow_merge_if_pipeline_succeeds` is true, indicates if merge requests of the project can also be merged with skipped jobs", "args": [ @@ -39547,7 +44553,7 @@ "description": "Find a board by its ID", "type": { "kind": "SCALAR", - "name": "ID", + "name": "BoardID", "ofType": null }, "defaultValue": null @@ -39682,6 +44688,20 @@ "deprecationReason": null }, { + "name": "codeCoverageSummary", + "description": "Code coverage summary associated with the project", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "CodeCoverageSummary", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "complianceFrameworks", "description": "Compliance frameworks associated with the project", "args": [ @@ -39763,6 +44783,69 @@ "deprecationReason": null }, { + "name": "containerRepositories", + "description": "Container repositories of the project", + "args": [ + { + "name": "name", + "description": "Filter the container repositories by their name", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ContainerRepositoryConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "createdAt", "description": "Timestamp of the project creation", "args": [ @@ -39910,6 +44993,33 @@ "deprecationReason": null }, { + "name": "dastSiteValidation", + "description": "DAST Site Validation associated with the project", + "args": [ + { + "name": "targetUrl", + "description": "target URL of the DAST Site Validation", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DastSiteValidation", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "description", "description": "Short description of the project", "args": [ @@ -40289,7 +45399,7 @@ }, { "name": "assigneeId", - "description": "ID of a user assigned to the issues, \"none\" and \"any\" values supported", + "description": "ID of a user assigned to the issues, \"none\" and \"any\" values are supported", "type": { "kind": "SCALAR", "name": "String", @@ -40418,6 +45528,16 @@ } }, "defaultValue": null + }, + { + "name": "epicId", + "description": "ID of an epic associated with the issues, \"none\" and \"any\" values are supported", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null } ], "type": { @@ -40528,7 +45648,7 @@ }, { "name": "assigneeId", - "description": "ID of a user assigned to the issues, \"none\" and \"any\" values supported", + "description": "ID of a user assigned to the issues, \"none\" and \"any\" values are supported", "type": { "kind": "SCALAR", "name": "String", @@ -40733,7 +45853,7 @@ }, { "name": "assigneeId", - "description": "ID of a user assigned to the issues, \"none\" and \"any\" values supported", + "description": "ID of a user assigned to the issues, \"none\" and \"any\" values are supported", "type": { "kind": "SCALAR", "name": "String", @@ -40864,6 +45984,16 @@ "defaultValue": null }, { + "name": "epicId", + "description": "ID of an epic associated with the issues, \"none\" and \"any\" values are supported", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -42055,6 +47185,16 @@ "description": "Releases of the project", "args": [ { + "name": "sort", + "description": "Sort releases by this criteria", + "type": { + "kind": "ENUM", + "name": "ReleaseSort", + "ofType": null + }, + "defaultValue": "RELEASED_AT_DESC" + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -42445,7 +47585,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "GitlabErrorTrackingDetailedErrorID", "ofType": null } }, @@ -42604,7 +47744,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "SnippetID", "ofType": null } } @@ -44448,54 +49588,13 @@ "possibleTypes": null }, { - "kind": "ENUM", - "name": "ProjectSettingEnum", - "description": "Names of compliance frameworks that can be assigned to a Project", - "fields": null, - "inputFields": null, - "interfaces": null, - "enumValues": [ - { - "name": "gdpr", - "description": null, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "hipaa", - "description": null, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "pci_dss", - "description": null, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "soc_2", - "description": null, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "sox", - "description": null, - "isDeprecated": false, - "deprecationReason": null - } - ], - "possibleTypes": null - }, - { "kind": "OBJECT", "name": "ProjectStatistics", "description": null, "fields": [ { "name": "buildArtifactsSize", - "description": "Build artifacts size of the project", + "description": "Build artifacts size of the project in bytes", "args": [ ], @@ -44531,7 +49630,7 @@ }, { "name": "lfsObjectsSize", - "description": "Large File Storage (LFS) object size of the project", + "description": "Large File Storage (LFS) object size of the project in bytes", "args": [ ], @@ -44549,7 +49648,7 @@ }, { "name": "packagesSize", - "description": "Packages size of the project", + "description": "Packages size of the project in bytes", "args": [ ], @@ -44567,7 +49666,7 @@ }, { "name": "repositorySize", - "description": "Repository size of the project", + "description": "Repository size of the project in bytes", "args": [ ], @@ -44585,7 +49684,7 @@ }, { "name": "snippetsSize", - "description": "Snippets size of the project", + "description": "Snippets size of the project in bytes", "args": [ ], @@ -44599,7 +49698,7 @@ }, { "name": "storageSize", - "description": "Storage size of the project", + "description": "Storage size of the project in bytes", "args": [ ], @@ -44616,8 +49715,22 @@ "deprecationReason": null }, { + "name": "uploadsSize", + "description": "Uploads size of the project in bytes", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "wikiSize", - "description": "Wiki size of the project", + "description": "Wiki size of the project in bytes", "args": [ ], @@ -44687,11 +49800,542 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "PrometheusIntegrationCreateInput", + "description": "Autogenerated input type of PrometheusIntegrationCreate", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "The project to create the integration in", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "active", + "description": "Whether the integration is receiving alerts", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "apiUrl", + "description": "Endpoint at which prometheus can be queried", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "PrometheusIntegrationCreatePayload", + "description": "Autogenerated return type of PrometheusIntegrationCreate", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "integration", + "description": "The newly created integration", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "AlertManagementPrometheusIntegration", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "PrometheusIntegrationResetTokenInput", + "description": "Autogenerated input type of PrometheusIntegrationResetToken", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "The id of the integration to mutate", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "PrometheusServiceID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "PrometheusIntegrationResetTokenPayload", + "description": "Autogenerated return type of PrometheusIntegrationResetToken", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "integration", + "description": "The newly created integration", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "AlertManagementPrometheusIntegration", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "PrometheusIntegrationUpdateInput", + "description": "Autogenerated input type of PrometheusIntegrationUpdate", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "The id of the integration to mutate", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "PrometheusServiceID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "active", + "description": "Whether the integration is receiving alerts", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "apiUrl", + "description": "Endpoint at which prometheus can be queried", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "PrometheusIntegrationUpdatePayload", + "description": "Autogenerated return type of PrometheusIntegrationUpdate", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "integration", + "description": "The newly created integration", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "AlertManagementPrometheusIntegration", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "SCALAR", + "name": "PrometheusServiceID", + "description": "Identifier of PrometheusService", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "PromoteToEpicInput", + "description": "Autogenerated input type of PromoteToEpic", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "The project the issue to mutate is in", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "iid", + "description": "The IID of the issue to mutate", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "groupPath", + "description": "The group the promoted epic will belong to", + "type": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "PromoteToEpicPayload", + "description": "Autogenerated return type of PromoteToEpic", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "epic", + "description": "The epic after issue promotion", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Epic", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "issue", + "description": "The issue after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Issue", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "Query", "description": null, "fields": [ { + "name": "containerRepository", + "description": "Find a container repository", + "args": [ + { + "name": "id", + "description": "The global ID of the container repository", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ContainerRepositoryID", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ContainerRepositoryDetails", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "currentUser", "description": "Get information about current user", "args": [ @@ -44724,6 +50368,59 @@ "deprecationReason": null }, { + "name": "devopsAdoptionSegments", + "description": "Get configured DevOps adoption segments on the instance", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DevopsAdoptionSegmentConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "echo", "description": "Text to echo back", "args": [ @@ -44837,6 +50534,26 @@ "defaultValue": null }, { + "name": "recordedAfter", + "description": "Measurement recorded after this date", + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "recordedBefore", + "description": "Measurement recorded before this date", + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "defaultValue": null + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -45199,6 +50916,67 @@ "deprecationReason": null }, { + "name": "runnerSetup", + "description": "Get runner setup instructions", + "args": [ + { + "name": "platform", + "description": "Platform to generate the instructions for", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "architecture", + "description": "Architecture to generate the instructions for", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "projectId", + "description": "Project to register the runner for", + "type": { + "kind": "SCALAR", + "name": "ProjectID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "groupId", + "description": "Group to register the runner for", + "type": { + "kind": "SCALAR", + "name": "GroupID", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "RunnerSetup", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "snippets", "description": "Find Snippets visible to the current user", "args": [ @@ -45213,7 +50991,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "SnippetID", "ofType": null } } @@ -45235,7 +51013,7 @@ "description": "The ID of an author", "type": { "kind": "SCALAR", - "name": "ID", + "name": "UserID", "ofType": null }, "defaultValue": null @@ -45245,7 +51023,7 @@ "description": "The ID of a project", "type": { "kind": "SCALAR", - "name": "ID", + "name": "ProjectID", "ofType": null }, "defaultValue": null @@ -45328,7 +51106,7 @@ "description": "ID of the User", "type": { "kind": "SCALAR", - "name": "ID", + "name": "UserID", "ofType": null }, "defaultValue": null @@ -45403,6 +51181,16 @@ "defaultValue": "created_desc" }, { + "name": "search", + "description": "Query to search users by name, username, or primary email.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -46357,9 +52145,68 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "ReleaseAssetLinkInput", + "description": "Fields that are available when modifying a release asset link", + "fields": null, + "inputFields": [ + { + "name": "name", + "description": "Name of the asset link", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "url", + "description": "URL of the asset link", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "directAssetPath", + "description": "Relative path for a direct asset link", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "linkType", + "description": "The type of the asset link", + "type": { + "kind": "ENUM", + "name": "ReleaseAssetLinkType", + "ofType": null + }, + "defaultValue": "OTHER" + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "ENUM", "name": "ReleaseAssetLinkType", - "description": "Type of the link: `other`, `runbook`, `image`, `package`; defaults to `other`", + "description": "Type of the link: `other`, `runbook`, `image`, `package`", "fields": null, "inputFields": null, "interfaces": null, @@ -46525,6 +52372,35 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "ReleaseAssetsInput", + "description": "Fields that are available when modifying release assets", + "fields": null, + "inputFields": [ + { + "name": "links", + "description": "A list of asset links to associate to the release", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "ReleaseAssetLinkInput", + "ofType": null + } + } + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "ReleaseConnection", "description": "The connection type for Release.", @@ -46610,6 +52486,190 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "ReleaseCreateInput", + "description": "Autogenerated input type of ReleaseCreate", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "Full path of the project the release is associated with", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "tagName", + "description": "Name of the tag to associate with the release", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "ref", + "description": "The commit SHA or branch name to use if creating a new tag", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "name", + "description": "Name of the release", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "description", + "description": "Description (also known as \"release notes\") of the release", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "releasedAt", + "description": "The date when the release will be/was ready. Defaults to the current time.", + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "milestones", + "description": "The title of each milestone the release is associated with. GitLab Premium customers can specify group milestones.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "assets", + "description": "Assets associated to the release", + "type": { + "kind": "INPUT_OBJECT", + "name": "ReleaseAssetsInput", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ReleaseCreatePayload", + "description": "Autogenerated return type of ReleaseCreate", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "release", + "description": "The release after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Release", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "ReleaseEdge", "description": "An edge in a connection.", @@ -46845,6 +52905,34 @@ "description": null, "fields": [ { + "name": "closedIssuesUrl", + "description": "HTTP URL of the issues page, filtered by this release and `state=closed`", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "closedMergeRequestsUrl", + "description": "HTTP URL of the merge request page , filtered by this release and `state=closed`", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "editUrl", "description": "HTTP URL of the release's edit page", "args": [ @@ -46859,8 +52947,22 @@ "deprecationReason": null }, { - "name": "issuesUrl", - "description": "HTTP URL of the issues page filtered by this release", + "name": "mergedMergeRequestsUrl", + "description": "HTTP URL of the merge request page , filtered by this release and `state=merged`", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "openedIssuesUrl", + "description": "HTTP URL of the issues page, filtered by this release and `state=open`", "args": [ ], @@ -46873,8 +52975,8 @@ "deprecationReason": null }, { - "name": "mergeRequestsUrl", - "description": "HTTP URL of the merge request page filtered by this release", + "name": "openedMergeRequestsUrl", + "description": "HTTP URL of the merge request page, filtered by this release and `state=open`", "args": [ ], @@ -46909,6 +53011,41 @@ "possibleTypes": null }, { + "kind": "ENUM", + "name": "ReleaseSort", + "description": "Values for sorting releases", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "CREATED_DESC", + "description": "Created at descending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "CREATED_ASC", + "description": "Created at ascending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "RELEASED_AT_DESC", + "description": "Released at by descending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "RELEASED_AT_ASC", + "description": "Released at by ascending order", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "ReleaseSource", "description": "Represents the source code attached to a release in a particular format", @@ -47266,6 +53403,122 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "RepositionImageDiffNoteInput", + "description": "Autogenerated input type of RepositionImageDiffNote", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "The global id of the DiffNote to update", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "DiffNoteID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "position", + "description": "The position of this note on a diff", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "UpdateDiffImagePositionInput", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "RepositionImageDiffNotePayload", + "description": "Autogenerated return type of RepositionImageDiffNote", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "note", + "description": "The note after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Note", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "Repository", "description": null, @@ -48274,6 +54527,24 @@ "deprecationReason": null }, { + "name": "uploadsSize", + "description": "The uploads size in bytes", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "wikiSize", "description": "The wiki size in bytes", "args": [ @@ -48820,6 +55091,51 @@ }, { "kind": "OBJECT", + "name": "RunnerSetup", + "description": null, + "fields": [ + { + "name": "installInstructions", + "description": "Instructions for installing the runner on the specified architecture", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "registerInstructions", + "description": "Instructions for registering the runner", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "SastCiConfiguration", "description": "Represents a CI configuration of SAST", "fields": [ @@ -50231,6 +56547,59 @@ }, { "kind": "ENUM", + "name": "SecurityReportTypeEnum", + "description": null, + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "SAST", + "description": "SAST scan report", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "DAST", + "description": "DAST scan report", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "DEPENDENCY_SCANNING", + "description": "DEPENDENCY SCANNING scan report", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "CONTAINER_SCANNING", + "description": "CONTAINER SCANNING scan report", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "SECRET_DETECTION", + "description": "SECRET DETECTION scan report", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "COVERAGE_FUZZING", + "description": "COVERAGE FUZZING scan report", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "API_FUZZING", + "description": "API FUZZING scan report", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { + "kind": "ENUM", "name": "SecurityScannerType", "description": "The type of the security scanner", "fields": null, @@ -51186,7 +57555,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "GitlabErrorTrackingDetailedErrorID", "ofType": null } }, @@ -51213,7 +57582,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "GitlabErrorTrackingDetailedErrorID", "ofType": null } }, @@ -52036,6 +58405,12 @@ "deprecationReason": null }, { + "name": "GITHUB_SERVICE", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "HANGOUTS_CHAT_SERVICE", "description": null, "isDeprecated": false, @@ -52054,6 +58429,12 @@ "deprecationReason": null }, { + "name": "JENKINS_SERVICE", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "JIRA_SERVICE", "description": null, "isDeprecated": false, @@ -52148,18 +58529,6 @@ "description": null, "isDeprecated": false, "deprecationReason": null - }, - { - "name": "GITHUB_SERVICE", - "description": null, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "JENKINS_SERVICE", - "description": null, - "isDeprecated": false, - "deprecationReason": null } ], "possibleTypes": null @@ -52414,7 +58783,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "SnippetID", "ofType": null } }, @@ -53281,6 +59650,16 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "SnippetID", + "description": "Identifier of Snippet", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "SnippetPermissions", "description": null, @@ -53402,6 +59781,251 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "SnippetRepositoryRegistry", + "description": "Represents the Geo sync and verification state of a snippet repository", + "fields": [ + { + "name": "createdAt", + "description": "Timestamp when the SnippetRepositoryRegistry was created", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the SnippetRepositoryRegistry", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "lastSyncFailure", + "description": "Error message during sync of the SnippetRepositoryRegistry", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "lastSyncedAt", + "description": "Timestamp of the most recent successful sync of the SnippetRepositoryRegistry", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "retryAt", + "description": "Timestamp after which the SnippetRepositoryRegistry should be resynced", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "retryCount", + "description": "Number of consecutive failed sync attempts of the SnippetRepositoryRegistry", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "snippetRepositoryId", + "description": "ID of the Snippet Repository", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "state", + "description": "Sync state of the SnippetRepositoryRegistry", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "RegistryState", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "SnippetRepositoryRegistryConnection", + "description": "The connection type for SnippetRepositoryRegistry.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "SnippetRepositoryRegistryEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "SnippetRepositoryRegistry", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "SnippetRepositoryRegistryEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "SnippetRepositoryRegistry", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "ENUM", "name": "Sort", "description": "Common sort values", @@ -53909,6 +60533,20 @@ "deprecationReason": null }, { + "name": "latestVersion", + "description": "The latest version of the Terraform state", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "TerraformStateVersion", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "lockedAt", "description": "Timestamp the Terraform state was locked", "args": [ @@ -53986,6 +60624,24 @@ "description": "The connection type for TerraformState.", "fields": [ { + "name": "count", + "description": "Total count of collection", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "edges", "description": "A list of edges.", "args": [ @@ -54048,6 +60704,94 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "TerraformStateDeleteInput", + "description": "Autogenerated input type of TerraformStateDelete", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "Global ID of the Terraform state", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "TerraformStateID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "TerraformStateDeletePayload", + "description": "Autogenerated return type of TerraformStateDelete", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "TerraformStateEdge", "description": "An edge in a connection.", @@ -54093,6 +60837,287 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "TerraformStateID", + "description": "Identifier of Terraform::State", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "TerraformStateLockInput", + "description": "Autogenerated input type of TerraformStateLock", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "Global ID of the Terraform state", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "TerraformStateID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "TerraformStateLockPayload", + "description": "Autogenerated return type of TerraformStateLock", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "TerraformStateUnlockInput", + "description": "Autogenerated input type of TerraformStateUnlock", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "Global ID of the Terraform state", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "TerraformStateID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "TerraformStateUnlockPayload", + "description": "Autogenerated return type of TerraformStateUnlock", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "TerraformStateVersion", + "description": null, + "fields": [ + { + "name": "createdAt", + "description": "Timestamp the version was created", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "createdByUser", + "description": "The user that created this version", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "User", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the Terraform state version", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "job", + "description": "The job that created this version", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "CiJob", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "updatedAt", + "description": "Timestamp the version was updated", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "TerraformStateVersionRegistry", "description": "Represents the Geo sync and verification state of a terraform state version", @@ -54564,9 +61589,113 @@ "possibleTypes": null }, { - "kind": "INTERFACE", - "name": "TimeboxBurnupTimeSeriesInterface", - "description": null, + "kind": "OBJECT", + "name": "TimeReportStats", + "description": "Represents the time report stats for timeboxes", + "fields": [ + { + "name": "complete", + "description": "Completed issues metrics", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "TimeboxMetrics", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "incomplete", + "description": "Incomplete issues metrics", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "TimeboxMetrics", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "total", + "description": "Total issues metrics", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "TimeboxMetrics", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "TimeboxMetrics", + "description": "Represents measured stats metrics for timeboxes", + "fields": [ + { + "name": "count", + "description": "The count metric", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "weight", + "description": "The weight metric", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "TimeboxReport", + "description": "Represents a historically accurate report about the timebox", "fields": [ { "name": "burnupTimeSeries", @@ -54589,6 +61718,47 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "stats", + "description": "Represents the time report stats for the timebox", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "TimeReportStats", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INTERFACE", + "name": "TimeboxReportInterface", + "description": null, + "fields": [ + { + "name": "report", + "description": "Historically accurate report about the timebox", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "TimeboxReport", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -54652,24 +61822,6 @@ "description": null, "fields": [ { - "name": "date", - "description": "Timestamp of when the time tracked was spent at. Deprecated in 12.10: Use `spentAt`", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "Time", - "ofType": null - } - }, - "isDeprecated": true, - "deprecationReason": "Use `spentAt`. Deprecated in 12.10" - }, - { "name": "issue", "description": "The issue that logged time was added to", "args": [ @@ -55155,6 +62307,108 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "TodoCreateInput", + "description": "Autogenerated input type of TodoCreate", + "fields": null, + "inputFields": [ + { + "name": "targetId", + "description": "The global ID of the to-do item's parent. Issues, merge requests, designs and epics are supported", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "TodoableID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "TodoCreatePayload", + "description": "Autogenerated return type of TodoCreate", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "todo", + "description": "The to-do created", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Todo", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "TodoEdge", "description": "An edge in a connection.", @@ -55481,7 +62735,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "TodoID", "ofType": null } } @@ -55640,6 +62894,16 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "TodoableID", + "description": "Identifier of Todoable", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "INPUT_OBJECT", "name": "TodosMarkAllDoneInput", "description": "Autogenerated input type of TodosMarkAllDone", @@ -55748,7 +63012,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "TodoID", "ofType": null } } @@ -56828,7 +64092,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "ListID", "ofType": null } }, @@ -57735,7 +64999,7 @@ "description": "The ID of the parent epic. NULL when removing the association", "type": { "kind": "SCALAR", - "name": "ID", + "name": "EpicID", "ofType": null }, "defaultValue": null @@ -58270,7 +65534,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "SnippetID", "ofType": null } }, @@ -58576,7 +65840,7 @@ "description": "The global ID of the project the authored merge requests should be in. Incompatible with projectPath.", "type": { "kind": "SCALAR", - "name": "ID", + "name": "ProjectID", "ofType": null }, "defaultValue": null @@ -58781,7 +66045,7 @@ "description": "The global ID of the project the authored merge requests should be in. Incompatible with projectPath.", "type": { "kind": "SCALAR", - "name": "ID", + "name": "ProjectID", "ofType": null }, "defaultValue": null @@ -58874,6 +66138,20 @@ "deprecationReason": null }, { + "name": "groupCount", + "description": "Group count for the user. Available only when feature flag `user_group_counts` is enabled", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "groupMemberships", "description": "Group memberships of the user", "args": [ @@ -59030,7 +66308,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "SnippetID", "ofType": null } } @@ -59634,6 +66912,24 @@ "description": null, "fields": [ { + "name": "availability", + "description": "User availability status", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "AvailabilityEnum", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "emoji", "description": "String representation of emoji", "args": [ @@ -59744,7 +67040,7 @@ { "kind": "OBJECT", "name": "VulnerabilitiesCountByDay", - "description": "Represents the count of vulnerabilities by severity on a particular day", + "description": "Represents the count of vulnerabilities by severity on a particular day. This data is retained for 365 days", "fields": [ { "name": "critical", @@ -59901,7 +67197,7 @@ { "kind": "OBJECT", "name": "VulnerabilitiesCountByDayAndSeverity", - "description": "Represents the number of vulnerabilities for a particular severity on a particular day", + "description": "Represents the number of vulnerabilities for a particular severity on a particular day. This data is retained for 365 days", "fields": [ { "name": "count", diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index dca00fc1286..c46f12bcdcd 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -15,6 +15,8 @@ fields and methods on a model are available via GraphQL. CAUTION: **Caution:** Fields that are deprecated are marked with **{warning-solid}**. +Items (fields, enums, etc) that have been removed according to our [deprecation process](../index.md#deprecation-process) can be found +in [Removed Items](../removed_items.md). ## Object types @@ -72,10 +74,12 @@ Describes an alert from the project's Alert Management. | Field | Type | Description | | ----- | ---- | ----------- | +| `assignees` | UserConnection | Assignees of the alert | | `createdAt` | Time | Timestamp the alert was created | | `description` | String | Description of the alert | | `details` | JSON | Alert details | | `detailsUrl` | String! | The URL of the alert detail page | +| `discussions` | DiscussionConnection! | All discussions on this noteable | | `endedAt` | Time | Timestamp the alert ended | | `environment` | Environment | Environment for the alert | | `eventCount` | Int | Number of events of this alert | @@ -84,6 +88,7 @@ Describes an alert from the project's Alert Management. | `issueIid` | ID | Internal ID of the GitLab issue attached to the alert | | `metricsDashboardUrl` | String | URL for metrics embed for the alert | | `monitoringTool` | String | Monitoring tool the alert came from | +| `notes` | NoteConnection! | All notes on this noteable | | `prometheusAlert` | PrometheusAlert | The alert condition for Prometheus | | `runbook` | String | Runbook for the alert as defined in alert details | | `service` | String | Service the alert came from | @@ -91,6 +96,7 @@ Describes an alert from the project's Alert Management. | `startedAt` | Time | Timestamp the alert was raised | | `status` | AlertManagementStatus | Status of the alert | | `title` | String | Title of the alert | +| `todos` | TodoConnection | Todos of the current user for the alert | | `updatedAt` | Time | Timestamp the alert was last updated | ### AlertManagementAlertStatusCountsType @@ -106,6 +112,34 @@ Represents total number of alerts for the represented categories. | `resolved` | Int | Number of alerts with status RESOLVED for the project | | `triggered` | Int | Number of alerts with status TRIGGERED for the project | +### AlertManagementHttpIntegration + +An endpoint and credentials used to accept alerts for a project. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `active` | Boolean | Whether the endpoint is currently accepting alerts | +| `apiUrl` | String | URL at which Prometheus metrics can be queried to populate the metrics dashboard | +| `id` | ID! | ID of the integration | +| `name` | String | Name of the integration | +| `token` | String | Token used to authenticate alert notification requests | +| `type` | AlertManagementIntegrationType! | Type of integration | +| `url` | String | Endpoint which accepts alert notifications | + +### AlertManagementPrometheusIntegration + +An endpoint and credentials used to accept Prometheus alerts for a project. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `active` | Boolean | Whether the endpoint is currently accepting alerts | +| `apiUrl` | String | URL at which Prometheus metrics can be queried to populate the metrics dashboard | +| `id` | ID! | ID of the integration | +| `name` | String | Name of the integration | +| `token` | String | Token used to authenticate alert notification requests | +| `type` | AlertManagementIntegrationType! | Type of integration | +| `url` | String | Endpoint which accepts alert notifications | + ### AlertSetAssigneesPayload Autogenerated return type of AlertSetAssignees. @@ -203,9 +237,12 @@ Represents a project or group board. | Field | Type | Description | | ----- | ---- | ----------- | | `assignee` | User | The board assignee. | +| `epics` | BoardEpicConnection | Epics associated with board issues. | | `hideBacklogList` | Boolean | Whether or not backlog list is hidden. | | `hideClosedList` | Boolean | Whether or not closed list is hidden. | | `id` | ID! | ID (global ID) of the board | +| `labels` | LabelConnection | Labels of the board | +| `lists` | BoardListConnection | Lists of the board | | `milestone` | Milestone | The board milestone. | | `name` | String | Name of the board | | `weight` | Int | Weight of the board. | @@ -217,12 +254,15 @@ Represents an epic on an issue board. | Field | Type | Description | | ----- | ---- | ----------- | | `author` | User! | Author of the epic | +| `children` | EpicConnection | Children (sub-epics) of the epic | | `closedAt` | Time | Timestamp of when the epic was closed | | `confidential` | Boolean | Indicates if the epic is confidential | | `createdAt` | Time | Timestamp of when the epic was created | +| `currentUserTodos` | TodoConnection! | Todos for the current user | | `descendantCounts` | EpicDescendantCount | Number of open and closed descendant epics and issues | | `descendantWeightSum` | EpicDescendantWeights | Total weight of open and closed issues in the epic and its descendants | | `description` | String | Description of the epic | +| `discussions` | DiscussionConnection! | All discussions on this noteable | | `downvotes` | Int! | Number of downvotes the epic has received | | `dueDate` | Time | Due date of the epic | | `dueDateFixed` | Time | Fixed due date of the epic | @@ -235,7 +275,11 @@ Represents an epic on an issue board. | `healthStatus` | EpicHealthStatus | Current health status of the epic | | `id` | ID! | ID of the epic | | `iid` | ID! | Internal ID of the epic | +| `issues` | EpicIssueConnection | A list of issues associated with the epic | +| `labels` | LabelConnection | Labels assigned to the epic | +| `notes` | NoteConnection! | All notes on this noteable | | `parent` | Epic | Parent epic of the epic | +| `participants` | UserConnection | List of participants for the epic | | `reference` | String! | Internal reference of the epic. Returned in shortened format by default | | `relationPath` | String | URI path of the epic-issue relationship | | `relativePosition` | Int | The relative position of the epic in the epic tree | @@ -248,6 +292,8 @@ Represents an epic on an issue board. | `title` | String | Title of the epic | | `updatedAt` | Time | Timestamp of when the epic was updated | | `upvotes` | Int! | Number of upvotes the epic has received | +| `userDiscussionsCount` | Int! | Number of user discussions in the epic | +| `userNotesCount` | Int! | Number of user notes of the epic | | `userPermissions` | EpicPermissions! | Permissions for the current user on the resource | | `userPreferences` | BoardEpicUserPreferences | User preferences for the epic on the issue board | | `webPath` | String! | Web path of the epic | @@ -270,6 +316,7 @@ Represents a list for an issue board. | `assignee` | User | Assignee in the list | | `collapsed` | Boolean | Indicates if list is collapsed for this user | | `id` | ID! | ID (global ID) of the list | +| `issues` | IssueConnection | Board issues | | `issuesCount` | Int | Count of issues in the list | | `label` | Label | Label of the list | | `limitMetric` | ListLimitMetric | The current limit metric for the list | @@ -325,6 +372,7 @@ Represents the total number of issues and their weights for a particular day. | Field | Type | Description | | ----- | ---- | ----------- | | `detailedStatus` | DetailedStatus | Detailed status of the group | +| `jobs` | CiJobConnection | Jobs in group | | `name` | String | Name of the job group | | `size` | Int | Size of the group | @@ -334,6 +382,8 @@ Represents the total number of issues and their weights for a particular day. | ----- | ---- | ----------- | | `detailedStatus` | DetailedStatus | Detailed status of the job | | `name` | String | Name of the job | +| `needs` | CiJobConnection | Builds that must complete before the jobs run | +| `pipeline` | Pipeline! | Pipeline the job belongs to | | `scheduledAt` | Time | Schedule for the build | ### CiStage @@ -341,6 +391,7 @@ Represents the total number of issues and their weights for a particular day. | Field | Type | Description | | ----- | ---- | ----------- | | `detailedStatus` | DetailedStatus | Detailed status of the stage | +| `groups` | CiGroupConnection | Group of jobs for the stage | | `name` | String | Name of the stage | ### ClusterAgent @@ -351,6 +402,7 @@ Represents the total number of issues and their weights for a particular day. | `id` | ID! | ID of the cluster agent | | `name` | String | Name of the cluster agent | | `project` | Project | The project this cluster agent is associated with | +| `tokens` | ClusterAgentTokenConnection | Tokens associated with the cluster agent | | `updatedAt` | Time | Timestamp the cluster agent was updated | ### ClusterAgentDeletePayload @@ -390,6 +442,27 @@ Autogenerated return type of ClusterAgentTokenDelete. | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### CodeCoverageActivity + +Represents the code coverage activity for a group. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `averageCoverage` | Float | Average percentage of the different code coverage results available for the group. | +| `coverageCount` | Int | Number of different code coverage results available for the group. | +| `date` | Date! | Date when the code coverage was created. | +| `projectCount` | Int | Number of projects with code coverage results for the group. | + +### CodeCoverageSummary + +Represents the code coverage summary for a project. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `averageCoverage` | Float | Average percentage of the different code coverage results available for the project. | +| `coverageCount` | Int | Number of different code coverage results available. | +| `lastUpdatedOn` | Date | Latest date when the code coverage was created for the project. | + ### Commit | Field | Type | Description | @@ -401,8 +474,8 @@ Autogenerated return type of ClusterAgentTokenDelete. | `description` | String | Description of the commit message | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `id` | ID! | ID (global ID) of the commit | -| `latestPipeline` **{warning-solid}** | Pipeline | **Deprecated:** Use `pipelines`. Deprecated in 12.5 | | `message` | String | Raw commit message | +| `pipelines` | PipelineConnection | Pipelines of the commit ordered latest first | | `sha` | String! | SHA1 ID of the commit | | `signatureHtml` | String | Rendered HTML of the commit signature | | `title` | String | Title of the commit message | @@ -426,7 +499,7 @@ Represents a ComplianceFramework associated with a Project. | Field | Type | Description | | ----- | ---- | ----------- | -| `name` | ProjectSettingEnum! | Name of the compliance framework | +| `name` | String! | Name of the compliance framework | ### ConfigureSastPayload @@ -455,6 +528,59 @@ A tag expiration policy designed to keep only the images that matter most. | `olderThan` | ContainerExpirationPolicyOlderThanEnum | Tags older that this will expire | | `updatedAt` | Time! | Timestamp of when the container expiration policy was updated | +### ContainerRepository + +A container repository. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `canDelete` | Boolean! | Can the current user delete the container repository. | +| `createdAt` | Time! | Timestamp when the container repository was created. | +| `expirationPolicyCleanupStatus` | ContainerRepositoryCleanupStatus | The tags cleanup status for the container repository. | +| `expirationPolicyStartedAt` | Time | Timestamp when the cleanup done by the expiration policy was started on the container repository. | +| `id` | ID! | ID of the container repository. | +| `location` | String! | URL of the container repository. | +| `name` | String! | Name of the container repository. | +| `path` | String! | Path of the container repository. | +| `status` | ContainerRepositoryStatus | Status of the container repository. | +| `tagsCount` | Int! | Number of tags associated with this image. | +| `updatedAt` | Time! | Timestamp when the container repository was updated. | + +### ContainerRepositoryDetails + +Details of a container repository. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `canDelete` | Boolean! | Can the current user delete the container repository. | +| `createdAt` | Time! | Timestamp when the container repository was created. | +| `expirationPolicyCleanupStatus` | ContainerRepositoryCleanupStatus | The tags cleanup status for the container repository. | +| `expirationPolicyStartedAt` | Time | Timestamp when the cleanup done by the expiration policy was started on the container repository. | +| `id` | ID! | ID of the container repository. | +| `location` | String! | URL of the container repository. | +| `name` | String! | Name of the container repository. | +| `path` | String! | Path of the container repository. | +| `status` | ContainerRepositoryStatus | Status of the container repository. | +| `tags` | ContainerRepositoryTagConnection | Tags of the container repository | +| `tagsCount` | Int! | Number of tags associated with this image. | +| `updatedAt` | Time! | Timestamp when the container repository was updated. | + +### ContainerRepositoryTag + +A tag from a container repository. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `canDelete` | Boolean! | Can the current user delete this tag. | +| `createdAt` | Time! | Timestamp when the tag was created. | +| `digest` | String! | Digest of the tag. | +| `location` | String! | URL of the tag. | +| `name` | String! | Name of the tag. | +| `path` | String! | Path of the tag. | +| `revision` | String! | Revision of the tag. | +| `shortRevision` | String! | Short revision of the tag. | +| `totalSize` | Int! | The size of the tag. | + ### CreateAlertIssuePayload Autogenerated return type of CreateAlertIssue. @@ -507,6 +633,16 @@ Autogenerated return type of CreateClusterAgent. | `clusterAgent` | ClusterAgent | Cluster agent created after mutation | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### CreateCustomEmojiPayload + +Autogenerated return type of CreateCustomEmoji. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `customEmoji` | CustomEmoji | The new custom emoji | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + ### CreateDiffNotePayload Autogenerated return type of CreateDiffNote. @@ -598,6 +734,17 @@ Autogenerated return type of CreateTestCase. | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `testCase` | Issue | The test case created | +### CustomEmoji + +A custom emoji uploaded by user. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `external` | Boolean! | Whether the emoji is an external link | +| `id` | CustomEmojiID! | The ID of the emoji | +| `name` | String! | The name of the emoji | +| `url` | String! | The link to file of the emoji | + ### DastOnDemandScanCreatePayload Autogenerated return type of DastOnDemandScanCreate. @@ -615,8 +762,8 @@ Represents a DAST scanner profile. | Field | Type | Description | | ----- | ---- | ----------- | | `editPath` | String | Relative web path to the edit page of a scanner profile | -| `globalId` | DastScannerProfileID! | ID of the DAST scanner profile | -| `id` **{warning-solid}** | ID! | **Deprecated:** Use `global_id`. Deprecated in 13.4 | +| `globalId` **{warning-solid}** | DastScannerProfileID! | **Deprecated:** Use `id`. Deprecated in 13.6 | +| `id` | DastScannerProfileID! | ID of the DAST scanner profile | | `profileName` | String | Name of the DAST scanner profile | | `scanType` | DastScanTypeEnum | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | | `showDebugMessages` | Boolean! | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | @@ -632,8 +779,8 @@ Autogenerated return type of DastScannerProfileCreate. | ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -| `globalId` | DastScannerProfileID | ID of the scanner profile. | -| `id` **{warning-solid}** | ID | **Deprecated:** Use `global_id`. Deprecated in 13.4 | +| `globalId` **{warning-solid}** | DastScannerProfileID | **Deprecated:** Use `id`. Deprecated in 13.6 | +| `id` | DastScannerProfileID | ID of the scanner profile. | ### DastScannerProfileDeletePayload @@ -716,6 +863,26 @@ Autogenerated return type of DastSiteTokenCreate. | `status` | DastSiteProfileValidationStatusEnum | The current validation status of the target. | | `token` | String | Token string. | +### DastSiteValidation + +Represents a DAST Site Validation. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `id` | DastSiteValidationID! | ID of the site validation | +| `status` | DastSiteProfileValidationStatusEnum! | The status of the validation | + +### DastSiteValidationCreatePayload + +Autogenerated return type of DastSiteValidationCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `id` | DastSiteValidationID | ID of the site validation. | +| `status` | DastSiteProfileValidationStatusEnum | The current validation status. | + ### DeleteAnnotationPayload Autogenerated return type of DeleteAnnotation. @@ -741,7 +908,9 @@ A single design. | Field | Type | Description | | ----- | ---- | ----------- | +| `currentUserTodos` | TodoConnection! | Todos for the current user | | `diffRefs` | DiffRefs! | The diff refs for this design | +| `discussions` | DiscussionConnection! | All discussions on this noteable | | `event` | DesignVersionEvent! | How this design was changed in the current version | | `filename` | String! | The filename of the design | | `fullPath` | String! | The full path to the design file | @@ -749,8 +918,10 @@ A single design. | `image` | String! | The URL of the full-sized image | | `imageV432x230` | String | The URL of the design resized to fit within the bounds of 432x230. This will be `null` if the image has not been generated | | `issue` | Issue! | The issue the design belongs to | +| `notes` | NoteConnection! | All notes on this noteable | | `notesCount` | Int! | The total count of user-created notes for this design | | `project` | Project! | The project the design belongs to | +| `versions` | DesignVersionConnection! | All versions related to this design ordered newest first | ### DesignAtVersion @@ -780,9 +951,11 @@ A collection of designs. | `copyState` | DesignCollectionCopyState | Copy state of the design collection | | `design` | Design | Find a specific design | | `designAtVersion` | DesignAtVersion | Find a design as of a version | +| `designs` | DesignConnection! | All designs for the design collection | | `issue` | Issue! | Issue associated with the design collection | | `project` | Project! | Project associated with the design collection | | `version` | DesignVersion | A specific version | +| `versions` | DesignVersionConnection! | All versions related to all designs, ordered newest first | ### DesignManagement @@ -829,6 +1002,8 @@ A specific version in which designs were added, modified or deleted. | Field | Type | Description | | ----- | ---- | ----------- | | `designAtVersion` | DesignAtVersion! | A particular design as of this version, provided it is visible at this version | +| `designs` | DesignConnection! | All designs that were changed in the version | +| `designsAtVersion` | DesignAtVersionConnection! | All designs that are visible at this version, as of this version | | `id` | ID! | ID of the design version | | `sha` | ID! | SHA of the design version | @@ -852,6 +1027,16 @@ Autogenerated return type of DestroyBoard. | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### DestroyContainerRepositoryPayload + +Autogenerated return type of DestroyContainerRepository. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `containerRepository` | ContainerRepository! | The container repository policy after scheduling the deletion. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + ### DestroyNotePayload Autogenerated return type of DestroyNote. @@ -886,6 +1071,16 @@ Autogenerated return type of DestroySnippet. | `text` | String | Text of the status | | `tooltip` | String | Tooltip associated with the status | +### DevopsAdoptionSegment + +Segment. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `groups` | GroupConnection | Assigned groups | +| `id` | ID! | ID of the segment | +| `name` | String! | Name of the segment | + ### DiffPosition | Field | Type | Description | @@ -937,6 +1132,7 @@ Aggregated summary of changes. | ----- | ---- | ----------- | | `createdAt` | Time! | Timestamp of the discussion's creation | | `id` | ID! | ID of this discussion | +| `notes` | NoteConnection! | All notes in the discussion | | `replyId` | ID! | ID used to reply to this discussion | | `resolvable` | Boolean! | Indicates if the object can be resolved | | `resolved` | Boolean! | Indicates if the object is resolved | @@ -973,9 +1169,18 @@ Describes where code is deployed for a project. | `latestOpenedMostSevereAlert` | AlertManagementAlert | The most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned | | `metricsDashboard` | MetricsDashboard | Metrics dashboard schema for the environment | | `name` | String! | Human-readable name of the environment | -| `path` | String | The path to the environment. Will always return null if `expose_environment_path_in_alert_details` feature flag is disabled | +| `path` | String! | The path to the environment. | | `state` | String! | State of the environment, for example: available/stopped | +### EnvironmentsCanaryIngressUpdatePayload + +Autogenerated return type of EnvironmentsCanaryIngressUpdate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + ### Epic Represents an epic. @@ -983,12 +1188,15 @@ Represents an epic. | Field | Type | Description | | ----- | ---- | ----------- | | `author` | User! | Author of the epic | +| `children` | EpicConnection | Children (sub-epics) of the epic | | `closedAt` | Time | Timestamp of when the epic was closed | | `confidential` | Boolean | Indicates if the epic is confidential | | `createdAt` | Time | Timestamp of when the epic was created | +| `currentUserTodos` | TodoConnection! | Todos for the current user | | `descendantCounts` | EpicDescendantCount | Number of open and closed descendant epics and issues | | `descendantWeightSum` | EpicDescendantWeights | Total weight of open and closed issues in the epic and its descendants | | `description` | String | Description of the epic | +| `discussions` | DiscussionConnection! | All discussions on this noteable | | `downvotes` | Int! | Number of downvotes the epic has received | | `dueDate` | Time | Due date of the epic | | `dueDateFixed` | Time | Fixed due date of the epic | @@ -1001,7 +1209,11 @@ Represents an epic. | `healthStatus` | EpicHealthStatus | Current health status of the epic | | `id` | ID! | ID of the epic | | `iid` | ID! | Internal ID of the epic | +| `issues` | EpicIssueConnection | A list of issues associated with the epic | +| `labels` | LabelConnection | Labels assigned to the epic | +| `notes` | NoteConnection! | All notes on this noteable | | `parent` | Epic | Parent epic of the epic | +| `participants` | UserConnection | List of participants for the epic | | `reference` | String! | Internal reference of the epic. Returned in shortened format by default | | `relationPath` | String | URI path of the epic-issue relationship | | `relativePosition` | Int | The relative position of the epic in the epic tree | @@ -1014,6 +1226,8 @@ Represents an epic. | `title` | String | Title of the epic | | `updatedAt` | Time | Timestamp of when the epic was updated | | `upvotes` | Int! | Number of upvotes the epic has received | +| `userDiscussionsCount` | Int! | Number of user discussions in the epic | +| `userNotesCount` | Int! | Number of user notes of the epic | | `userPermissions` | EpicPermissions! | Permissions for the current user on the resource | | `webPath` | String! | Web path of the epic | | `webUrl` | String! | Web URL of the epic | @@ -1066,25 +1280,36 @@ Relationship between an epic and an issue. | Field | Type | Description | | ----- | ---- | ----------- | | `alertManagementAlert` | AlertManagementAlert | Alert associated to this issue | +| `assignees` | UserConnection | Assignees of the issue | | `author` | User! | User that created the issue | | `blocked` | Boolean! | Indicates the issue is blocked | +| `blockedByCount` | Int | Count of issues blocking this issue | | `closedAt` | Time | Timestamp of when the issue was closed | | `confidential` | Boolean! | Indicates the issue is confidential | | `createdAt` | Time! | Timestamp of when the issue was created | +| `currentUserTodos` | TodoConnection! | Todos for the current user | | `description` | String | Description of the issue | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `designCollection` | DesignCollection | Collection of design images associated with this issue | -| `designs` **{warning-solid}** | DesignCollection | **Deprecated:** Use `designCollection`. Deprecated in 12.2 | | `discussionLocked` | Boolean! | Indicates discussion is locked on the issue | +| `discussions` | DiscussionConnection! | All discussions on this noteable | | `downvotes` | Int! | Number of downvotes the issue has received | | `dueDate` | Time | Due date of the issue | +| `emailsDisabled` | Boolean! | Indicates if a project has email notifications disabled: `true` if email notifications are disabled | | `epic` | Epic | Epic to which this issue belongs | | `epicIssueId` | ID! | ID of the epic-issue relation | | `healthStatus` | HealthStatus | Current health status. Returns null if `save_issuable_health_status` feature flag is disabled. | +| `humanTimeEstimate` | String | Human-readable time estimate of the issue | +| `humanTotalTimeSpent` | String | Human-readable total time reported as spent on the issue | | `id` | ID | Global ID of the epic-issue relation | | `iid` | ID! | Internal ID of the issue | | `iteration` | Iteration | Iteration of the issue | +| `labels` | LabelConnection | Labels of the issue | | `milestone` | Milestone | Milestone of the issue | +| `moved` | Boolean | Indicates if issue got moved from other project | +| `movedTo` | Issue | Updated Issue after it got moved to another project | +| `notes` | NoteConnection! | All notes on this noteable | +| `participants` | UserConnection | List of participants in the issue | | `reference` | String! | Internal reference of the issue. Returned in shortened format by default | | `relationPath` | String | URI path of the epic-issue relation | | `relativePosition` | Int | Relative position of the issue (used for positioning in epic tree and issue boards) | @@ -1100,7 +1325,9 @@ Relationship between an epic and an issue. | `totalTimeSpent` | Int! | Total time reported as spent on the issue | | `type` | IssueType | Type of the issue | | `updatedAt` | Time! | Timestamp of when the issue was last updated | +| `updatedBy` | User | User that last updated the issue | | `upvotes` | Int! | Number of upvotes the issue has received | +| `userDiscussionsCount` | Int! | Number of user discussions in the issue | | `userNotesCount` | Int! | Number of user notes of the issue | | `userPermissions` | IssuePermissions! | Permissions for the current user on the resource | | `webPath` | String! | Web path of the issue | @@ -1150,13 +1377,18 @@ Autogenerated return type of EpicTreeReorder. | `filesMaxCapacity` | Int | The maximum concurrency of LFS/attachment backfill for this secondary node | | `id` | ID! | ID of this GeoNode | | `internalUrl` | String | The URL defined on the primary node that secondary nodes should use to contact it | +| `mergeRequestDiffRegistries` | MergeRequestDiffRegistryConnection | Find merge request diff registries on this Geo node | | `minimumReverificationInterval` | Int | The interval (in days) in which the repository verification is valid. Once expired, it will be reverified | | `name` | String | The unique identifier for this Geo node | +| `packageFileRegistries` | PackageFileRegistryConnection | Package file registries of the GeoNode | | `primary` | Boolean | Indicates whether this Geo node is the primary | | `reposMaxCapacity` | Int | The maximum concurrency of repository backfill for this secondary node | +| `selectiveSyncNamespaces` | NamespaceConnection | The namespaces that should be synced, if `selective_sync_type` == `namespaces` | | `selectiveSyncShards` | String! => Array | The repository storages whose projects should be synced, if `selective_sync_type` == `shards` | | `selectiveSyncType` | String | Indicates if syncing is limited to only specific groups, or shards | +| `snippetRepositoryRegistries` | SnippetRepositoryRegistryConnection | Find snippet repository registries on this Geo node. Available only when feature flag `geo_snippet_repository_replication` is enabled | | `syncObjectStorage` | Boolean | Indicates if this secondary node will replicate blobs in Object Storage | +| `terraformStateVersionRegistries` | TerraformStateVersionRegistryConnection | Find terraform state version registries on this Geo node | | `url` | String | The user-facing URL for this Geo node | | `verificationMaxCapacity` | Int | The maximum concurrency of repository verification for this secondary node | @@ -1168,7 +1400,6 @@ Autogenerated return type of EpicTreeReorder. | `enabled` | Boolean! | Indicates whether Grafana integration is enabled | | `grafanaUrl` | String! | URL for the Grafana host for the Grafana integration | | `id` | ID! | Internal ID of the Grafana integration | -| `token` **{warning-solid}** | String! | **Deprecated:** Plain text token has been masked for security reasons. Deprecated in 12.7 | | `updatedAt` | Time! | Timestamp of the issue's last activity | ### Group @@ -1180,38 +1411,56 @@ Autogenerated return type of EpicTreeReorder. | `autoDevopsEnabled` | Boolean | Indicates whether Auto DevOps is enabled for all projects within this group | | `avatarUrl` | String | Avatar URL of the group | | `board` | Board | A single board of the group | +| `boards` | BoardConnection | Boards of the group | +| `codeCoverageActivities` | CodeCoverageActivityConnection | Represents the code coverage activity for this group. Available only when feature flag `group_coverage_data_report_graph` is enabled | +| `containerRepositories` | ContainerRepositoryConnection | Container repositories of the project | | `containsLockedProjects` | Boolean! | Includes at least one project where the repository size exceeds the limit | +| `customEmoji` | CustomEmojiConnection | Custom emoji within this namespace. Available only when feature flag `custom_emoji` is enabled | | `description` | String | Description of the namespace | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `emailsDisabled` | Boolean | Indicates if a group has email notifications disabled | | `epic` | Epic | Find a single epic | +| `epics` | EpicConnection | Find epics | | `epicsEnabled` | Boolean | Indicates if Epics are enabled for namespace | | `fullName` | String! | Full name of the namespace | | `fullPath` | ID! | Full path of the namespace | +| `groupMembers` | GroupMemberConnection | A membership of a user within this group | | `groupTimelogsEnabled` | Boolean | Indicates if Group timelogs are enabled for namespace | | `id` | ID! | ID of the namespace | | `isTemporaryStorageIncreaseEnabled` | Boolean! | Status of the temporary storage increase | +| `issues` | IssueConnection | Issues for projects in this group | +| `iterations` | IterationConnection | Find iterations | | `label` | Label | A label available on this group | +| `labels` | LabelConnection | Labels available on this group | | `lfsEnabled` | Boolean | Indicates if Large File Storage (LFS) is enabled for namespace | | `mentionsDisabled` | Boolean | Indicates if a group is disabled from getting mentioned | +| `mergeRequests` | MergeRequestConnection | Merge requests for projects in this group | +| `milestones` | MilestoneConnection | Milestones of the group | | `name` | String! | Name of the namespace | | `parent` | Group | Parent group | | `path` | String! | Path of the namespace | | `projectCreationLevel` | String | The permission level required to create projects in the group | +| `projects` | ProjectConnection! | Projects within this namespace | | `repositorySizeExcessProjectCount` | Int! | Number of projects in the root namespace where the repository size exceeds the limit | | `requestAccessEnabled` | Boolean | Indicates if users can request access to namespace | | `requireTwoFactorAuthentication` | Boolean | Indicates if all users in this group are required to set up two-factor authentication | | `rootStorageStatistics` | RootStorageStatistics | Aggregated storage statistics of the namespace. Only available for root namespaces | | `shareWithGroupLock` | Boolean | Indicates if sharing a project with another group within this group is prevented | +| `stats` | GroupStats | Group statistics | | `storageSizeLimit` | Float | Total storage limit of the root namespace in bytes | | `subgroupCreationLevel` | String | The permission level required to create subgroups within the group | | `temporaryStorageIncreaseEndsOn` | Time | Date until the temporary storage increase is active | +| `timelogs` | TimelogConnection! | Time logged in issues by group members | | `totalRepositorySize` | Float | Total repository size of all projects in the root namespace in bytes | | `totalRepositorySizeExcess` | Float | Total excess repository size of all projects in the root namespace in bytes | | `twoFactorGracePeriod` | Int | Time before two-factor authentication is enforced | | `userPermissions` | GroupPermissions! | Permissions for the current user on the resource | | `visibility` | String | Visibility of the namespace | +| `vulnerabilities` | VulnerabilityConnection | Vulnerabilities reported on the projects in the group and its subgroups | +| `vulnerabilitiesCountByDay` | VulnerabilitiesCountByDayConnection | Number of vulnerabilities per day for the projects in the group and its subgroups | +| `vulnerabilitiesCountByDayAndSeverity` **{warning-solid}** | VulnerabilitiesCountByDayAndSeverityConnection | **Deprecated:** Use `vulnerabilitiesCountByDay`. Deprecated in 13.3 | | `vulnerabilityGrades` | VulnerableProjectsByGrade! => Array | Represents vulnerable project counts for each grade | +| `vulnerabilityScanners` | VulnerabilityScannerConnection | Vulnerability scanners reported on the project vulnerabilties of the group and its subgroups | | `vulnerabilitySeveritiesCount` | VulnerabilitySeveritiesCount | Counts for each vulnerability severity in the group and its subgroups | | `webUrl` | String! | Web URL of the group | @@ -1237,11 +1486,70 @@ Represents a Group Membership. | ----- | ---- | ----------- | | `readGroup` | Boolean! | Indicates the user can perform `read_group` on this resource | +### GroupReleaseStats + +Contains release-related statistics about a group. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `releasesCount` | Int | Total number of releases in all descendant projects of the group. Will always return `null` if `group_level_release_statistics` feature flag is disabled | +| `releasesPercentage` | Int | Percentage of the group's descendant projects that have at least one release. Will always return `null` if `group_level_release_statistics` feature flag is disabled | + +### GroupStats + +Contains statistics about a group. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `releaseStats` | GroupReleaseStats | Statistics related to releases within the group | + +### HttpIntegrationCreatePayload + +Autogenerated return type of HttpIntegrationCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `integration` | AlertManagementHttpIntegration | The HTTP integration | + +### HttpIntegrationDestroyPayload + +Autogenerated return type of HttpIntegrationDestroy. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `integration` | AlertManagementHttpIntegration | The HTTP integration | + +### HttpIntegrationResetTokenPayload + +Autogenerated return type of HttpIntegrationResetToken. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `integration` | AlertManagementHttpIntegration | The HTTP integration | + +### HttpIntegrationUpdatePayload + +Autogenerated return type of HttpIntegrationUpdate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `integration` | AlertManagementHttpIntegration | The HTTP integration | + ### InstanceSecurityDashboard | Field | Type | Description | | ----- | ---- | ----------- | +| `projects` | ProjectConnection! | Projects selected in Instance Security Dashboard | | `vulnerabilityGrades` | VulnerableProjectsByGrade! => Array | Represents vulnerable project counts for each grade | +| `vulnerabilityScanners` | VulnerabilityScannerConnection | Vulnerability scanners reported on the vulnerabilties from projects selected in Instance Security Dashboard | | `vulnerabilitySeveritiesCount` | VulnerabilitySeveritiesCount | Counts for each vulnerability severity from projects selected in Instance Security Dashboard | ### InstanceStatisticsMeasurement @@ -1259,24 +1567,35 @@ Represents a recorded measurement (object count) for the Admins. | Field | Type | Description | | ----- | ---- | ----------- | | `alertManagementAlert` | AlertManagementAlert | Alert associated to this issue | +| `assignees` | UserConnection | Assignees of the issue | | `author` | User! | User that created the issue | | `blocked` | Boolean! | Indicates the issue is blocked | +| `blockedByCount` | Int | Count of issues blocking this issue | | `closedAt` | Time | Timestamp of when the issue was closed | | `confidential` | Boolean! | Indicates the issue is confidential | | `createdAt` | Time! | Timestamp of when the issue was created | +| `currentUserTodos` | TodoConnection! | Todos for the current user | | `description` | String | Description of the issue | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `designCollection` | DesignCollection | Collection of design images associated with this issue | -| `designs` **{warning-solid}** | DesignCollection | **Deprecated:** Use `designCollection`. Deprecated in 12.2 | | `discussionLocked` | Boolean! | Indicates discussion is locked on the issue | +| `discussions` | DiscussionConnection! | All discussions on this noteable | | `downvotes` | Int! | Number of downvotes the issue has received | | `dueDate` | Time | Due date of the issue | +| `emailsDisabled` | Boolean! | Indicates if a project has email notifications disabled: `true` if email notifications are disabled | | `epic` | Epic | Epic to which this issue belongs | | `healthStatus` | HealthStatus | Current health status. Returns null if `save_issuable_health_status` feature flag is disabled. | +| `humanTimeEstimate` | String | Human-readable time estimate of the issue | +| `humanTotalTimeSpent` | String | Human-readable total time reported as spent on the issue | | `id` | ID! | ID of the issue | | `iid` | ID! | Internal ID of the issue | | `iteration` | Iteration | Iteration of the issue | +| `labels` | LabelConnection | Labels of the issue | | `milestone` | Milestone | Milestone of the issue | +| `moved` | Boolean | Indicates if issue got moved from other project | +| `movedTo` | Issue | Updated Issue after it got moved to another project | +| `notes` | NoteConnection! | All notes on this noteable | +| `participants` | UserConnection | List of participants in the issue | | `reference` | String! | Internal reference of the issue. Returned in shortened format by default | | `relativePosition` | Int | Relative position of the issue (used for positioning in epic tree and issue boards) | | `severity` | IssuableSeverity | Severity level of the incident | @@ -1291,7 +1610,9 @@ Represents a recorded measurement (object count) for the Admins. | `totalTimeSpent` | Int! | Total time reported as spent on the issue | | `type` | IssueType | Type of the issue | | `updatedAt` | Time! | Timestamp of when the issue was last updated | +| `updatedBy` | User | User that last updated the issue | | `upvotes` | Int! | Number of upvotes the issue has received | +| `userDiscussionsCount` | Int! | Number of user discussions in the issue | | `userNotesCount` | Int! | Number of user notes of the issue | | `userPermissions` | IssuePermissions! | Permissions for the current user on the resource | | `webPath` | String! | Web path of the issue | @@ -1439,13 +1760,13 @@ Represents an iteration object. | Field | Type | Description | | ----- | ---- | ----------- | -| `burnupTimeSeries` | BurnupChartDailyTotals! => Array | Daily scope and completed totals for burnup charts | | `createdAt` | Time! | Timestamp of iteration creation | | `description` | String | Description of the iteration | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `dueDate` | Time | Timestamp of the iteration due date | | `id` | ID! | ID of the iteration | | `iid` | ID! | Internal ID of the iteration | +| `report` | TimeboxReport | Historically accurate report about the timebox | | `scopedPath` | String | Web path of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts | | `scopedUrl` | String | Web URL of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts | | `startDate` | Time | Timestamp of the iteration start date | @@ -1500,6 +1821,7 @@ Autogenerated return type of JiraImportUsers. | Field | Type | Description | | ----- | ---- | ----------- | | `active` | Boolean | Indicates if the service is active | +| `projects` | JiraProjectConnection | List of all Jira projects fetched through Jira REST API | | `type` | String | Class name of the service | ### JiraUser @@ -1524,6 +1846,16 @@ Autogenerated return type of JiraImportUsers. | `textColor` | String! | Text color of the label | | `title` | String! | Content of the label | +### LabelCreatePayload + +Autogenerated return type of LabelCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `label` | Label | The label after mutation | + ### MarkAsSpamSnippetPayload Autogenerated return type of MarkAsSpamSnippet. @@ -1542,11 +1874,14 @@ Autogenerated return type of MarkAsSpamSnippet. | `approvalsLeft` | Int | Number of approvals left | | `approvalsRequired` | Int | Number of approvals required | | `approved` | Boolean! | Indicates if the merge request has all the required approvals. Returns true if no required approvals are configured. | +| `approvedBy` | UserConnection | Users who approved the merge request | +| `assignees` | UserConnection | Assignees of the merge request | | `author` | User | User who created this merge request | | `autoMergeEnabled` | Boolean! | Indicates if auto merge is enabled for the merge request | | `commitCount` | Int | Number of commits in the merge request | | `conflicts` | Boolean! | Indicates if the merge request has conflicts | | `createdAt` | Time! | Timestamp of when the merge request was created | +| `currentUserTodos` | TodoConnection! | Todos for the current user | | `defaultMergeCommitMessage` | String | Default merge commit message of the merge request | | `description` | String | Description of the merge request (Markdown rendered as HTML for caching) | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | @@ -1555,13 +1890,14 @@ Autogenerated return type of MarkAsSpamSnippet. | `diffStats` | DiffStats! => Array | Details about which files were changed in this merge request | | `diffStatsSummary` | DiffStatsSummary | Summary of which files were changed in this merge request | | `discussionLocked` | Boolean! | Indicates if comments on the merge request are locked to members only | +| `discussions` | DiscussionConnection! | All discussions on this noteable | | `downvotes` | Int! | Number of downvotes for the merge request | | `forceRemoveSourceBranch` | Boolean | Indicates if the project settings will lead to source branch deletion after merge | | `headPipeline` | Pipeline | The pipeline running on the branch HEAD of the merge request | | `id` | ID! | ID of the merge request | | `iid` | String! | Internal ID of the merge request | | `inProgressMergeCommitSha` | String | Commit SHA of the merge request if merge is in progress | -| `mergeCommitMessage` **{warning-solid}** | String | **Deprecated:** Use `defaultMergeCommitMessage`. Deprecated in 11.8 | +| `labels` | LabelConnection | Labels of the merge request | | `mergeCommitSha` | String | SHA of the merge request commit (set once merged) | | `mergeError` | String | Error message due to a merge error | | `mergeOngoing` | Boolean! | Indicates if a merge is currently occurring | @@ -1570,6 +1906,9 @@ Autogenerated return type of MarkAsSpamSnippet. | `mergeableDiscussionsState` | Boolean | Indicates if all discussions in the merge request have been resolved, allowing the merge request to be merged | | `mergedAt` | Time | Timestamp of when the merge request was merged, null if not merged | | `milestone` | Milestone | The milestone of the merge request | +| `notes` | NoteConnection! | All notes on this noteable | +| `participants` | UserConnection | Participants in the merge request | +| `pipelines` | PipelineConnection | Pipelines for the merge request | | `project` | Project! | Alias for target_project | | `projectId` | Int! | ID of the merge request project | | `rebaseCommitSha` | String | Rebase commit SHA of the merge request | @@ -1594,6 +1933,7 @@ Autogenerated return type of MarkAsSpamSnippet. | `totalTimeSpent` | Int! | Total time reported as spent on the merge request | | `updatedAt` | Time! | Timestamp of when the merge request was last updated | | `upvotes` | Int! | Number of upvotes for the merge request | +| `userDiscussionsCount` | Int | Number of user discussions in the merge request | | `userNotesCount` | Int | User notes count of the merge request | | `userPermissions` | MergeRequestPermissions! | Permissions for the current user on the resource | | `webUrl` | String | Web URL of the merge request | @@ -1721,6 +2061,7 @@ Autogenerated return type of MergeRequestUpdate. | Field | Type | Description | | ----- | ---- | ----------- | +| `annotations` | MetricsDashboardAnnotationConnection | Annotations added to the dashboard | | `path` | String | Path to a file with the dashboard definition | | `schemaValidationWarnings` | String! => Array | Dashboard schema validation warnings | @@ -1740,13 +2081,13 @@ Represents a milestone. | Field | Type | Description | | ----- | ---- | ----------- | -| `burnupTimeSeries` | BurnupChartDailyTotals! => Array | Daily scope and completed totals for burnup charts | | `createdAt` | Time! | Timestamp of milestone creation | | `description` | String | Description of the milestone | | `dueDate` | Time | Timestamp of the milestone due date | | `groupMilestone` | Boolean! | Indicates if milestone is at group level | | `id` | ID! | ID of the milestone | | `projectMilestone` | Boolean! | Indicates if milestone is at project level | +| `report` | TimeboxReport | Historically accurate report about the timebox | | `startDate` | Time | Timestamp of the milestone start date | | `state` | MilestoneStateEnum! | State of the milestone | | `stats` | MilestoneStats | Milestone statistics | @@ -1780,6 +2121,7 @@ Contains statistics about a milestone. | `lfsEnabled` | Boolean | Indicates if Large File Storage (LFS) is enabled for namespace | | `name` | String! | Name of the namespace | | `path` | String! | Path of the namespace | +| `projects` | ProjectConnection! | Projects within this namespace | | `repositorySizeExcessProjectCount` | Int! | Number of projects in the root namespace where the repository size exceeds the limit | | `requestAccessEnabled` | Boolean | Indicates if users can request access to namespace | | `rootStorageStatistics` | RootStorageStatistics | Aggregated storage statistics of the namespace. Only available for root namespaces | @@ -1829,6 +2171,7 @@ Autogenerated return type of NamespaceIncreaseStorageTemporarily. | `awardEmoji` | Boolean! | Indicates the user can perform `award_emoji` on this resource | | `createNote` | Boolean! | Indicates the user can perform `create_note` on this resource | | `readNote` | Boolean! | Indicates the user can perform `read_note` on this resource | +| `repositionNote` | Boolean! | Indicates the user can perform `reposition_note` on this resource | | `resolveNote` | Boolean! | Indicates the user can perform `resolve_note` on this resource | ### Package @@ -1881,16 +2224,23 @@ Information about pagination in a connection.. | `coverage` | Float | Coverage percentage | | `createdAt` | Time! | Timestamp of the pipeline's creation | | `detailedStatus` | DetailedStatus! | Detailed status of the pipeline | +| `downstream` | PipelineConnection | Pipelines this pipeline will trigger | | `duration` | Int | Duration of the pipeline in seconds | | `finishedAt` | Time | Timestamp of the pipeline's completion | | `id` | ID! | ID of the pipeline | | `iid` | String! | Internal ID of the pipeline | +| `jobs` | CiJobConnection | Jobs belonging to the pipeline | +| `path` | String | Relative path to the pipeline's page | +| `project` | Project | Project the pipeline belongs to | | `retryable` | Boolean! | Specifies if a pipeline can be retried | | `securityReportSummary` | SecurityReportSummary | Vulnerability and scanned resource counts for each security scanner of the pipeline | | `sha` | String! | SHA of the pipeline's commit | +| `sourceJob` | CiJob | Job where pipeline was triggered from | +| `stages` | CiStageConnection | Stages of the pipeline | | `startedAt` | Time | Timestamp when the pipeline was started | | `status` | PipelineStatusEnum! | Status of the pipeline (CREATED, WAITING_FOR_RESOURCE, PREPARING, PENDING, RUNNING, FAILED, SUCCESS, CANCELED, SKIPPED, MANUAL, SCHEDULED) | | `updatedAt` | Time! | Timestamp of the pipeline's last activity | +| `upstream` | Pipeline | Pipeline that triggered the pipeline | | `user` | User | Pipeline user | | `userPermissions` | PipelinePermissions! | Permissions for the current user on the resource | @@ -1937,19 +2287,30 @@ Autogenerated return type of PipelineRetry. | `actualRepositorySizeLimit` | Float | Size limit for the repository in bytes | | `alertManagementAlert` | AlertManagementAlert | A single Alert Management alert of the project | | `alertManagementAlertStatusCounts` | AlertManagementAlertStatusCountsType | Counts of alerts by status for the project | +| `alertManagementAlerts` | AlertManagementAlertConnection | Alert Management alerts of the project | +| `alertManagementIntegrations` | AlertManagementIntegrationConnection | Integrations which can receive alerts for the project | | `allowMergeOnSkippedPipeline` | Boolean | If `only_allow_merge_if_pipeline_succeeds` is true, indicates if merge requests of the project can also be merged with skipped jobs | | `archived` | Boolean | Indicates the archived status of the project | | `autocloseReferencedIssues` | Boolean | Indicates if issues referenced by merge requests and commits within the default branch are closed automatically | | `avatarUrl` | String | URL to avatar image file of the project | | `board` | Board | A single board of the project | +| `boards` | BoardConnection | Boards of the project | | `clusterAgent` | ClusterAgent | Find a single cluster agent by name | +| `clusterAgents` | ClusterAgentConnection | Cluster agents associated with the project | +| `codeCoverageSummary` | CodeCoverageSummary | Code coverage summary associated with the project | +| `complianceFrameworks` | ComplianceFrameworkConnection | Compliance frameworks associated with the project | | `containerExpirationPolicy` | ContainerExpirationPolicy | The container expiration policy of the project | | `containerRegistryEnabled` | Boolean | Indicates if the project stores Docker container images in a container registry | +| `containerRepositories` | ContainerRepositoryConnection | Container repositories of the project | | `createdAt` | Time | Timestamp of the project creation | +| `dastScannerProfiles` | DastScannerProfileConnection | The DAST scanner profiles associated with the project | | `dastSiteProfile` | DastSiteProfile | DAST Site Profile associated with the project | +| `dastSiteProfiles` | DastSiteProfileConnection | DAST Site Profiles associated with the project | +| `dastSiteValidation` | DastSiteValidation | DAST Site Validation associated with the project | | `description` | String | Short description of the project | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `environment` | Environment | A single environment of the project | +| `environments` | EnvironmentConnection | Environments of the project | | `forksCount` | Int! | Number of times the project has been forked | | `fullPath` | ID! | Full path of the project | | `grafanaIntegration` | GrafanaIntegration | Grafana integration details for the project | @@ -1959,32 +2320,43 @@ Autogenerated return type of PipelineRetry. | `importStatus` | String | Status of import background job of the project | | `issue` | Issue | A single issue of the project | | `issueStatusCounts` | IssueStatusCountsType | Counts of issues by status for the project | +| `issues` | IssueConnection | Issues of the project | | `issuesEnabled` | Boolean | Indicates if Issues are enabled for the current user | +| `iterations` | IterationConnection | Find iterations | | `jiraImportStatus` | String | Status of Jira import background job of the project | +| `jiraImports` | JiraImportConnection | Jira imports into the project | | `jobsEnabled` | Boolean | Indicates if CI/CD pipeline jobs are enabled for the current user | | `label` | Label | A label available on this project | +| `labels` | LabelConnection | Labels available on this project | | `lastActivityAt` | Time | Timestamp of the project last activity | | `lfsEnabled` | Boolean | Indicates if the project has Large File Storage (LFS) enabled | | `mergeRequest` | MergeRequest | A single merge request of the project | +| `mergeRequests` | MergeRequestConnection | Merge requests of the project | | `mergeRequestsEnabled` | Boolean | Indicates if Merge Requests are enabled for the current user | | `mergeRequestsFfOnlyEnabled` | Boolean | Indicates if no merge commits should be created and all merges should instead be fast-forwarded, which means that merging is only allowed if the branch could be fast-forwarded. | +| `milestones` | MilestoneConnection | Milestones of the project | | `name` | String! | Name of the project (without namespace) | | `nameWithNamespace` | String! | Full name of the project with its namespace | | `namespace` | Namespace | Namespace of the project | | `onlyAllowMergeIfAllDiscussionsAreResolved` | Boolean | Indicates if merge requests of the project can only be merged when all the discussions are resolved | | `onlyAllowMergeIfPipelineSucceeds` | Boolean | Indicates if merge requests of the project can only be merged with successful jobs | | `openIssuesCount` | Int | Number of open issues for the project | +| `packages` | PackageConnection | Packages of the project | | `path` | String! | Path of the project | | `pipeline` | Pipeline | Build pipeline of the project | +| `pipelines` | PipelineConnection | Build pipelines of the project | | `printingMergeRequestLinkEnabled` | 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 | +| `projectMembers` | MemberInterfaceConnection | Members of the project | | `publicJobs` | Boolean | Indicates if there is public access to pipelines and job details of the project, including output logs and artifacts | | `release` | Release | A single release of the project | +| `releases` | ReleaseConnection | Releases of the project | | `removeSourceBranchAfterMerge` | Boolean | Indicates if `Delete source branch` option should be enabled by default for all new merge requests of the project | | `repository` | Repository | Git repository of the project | | `repositorySizeExcess` | Float | Size of repository that exceeds the limit in bytes | | `requestAccessEnabled` | Boolean | Indicates if users can request member access to the project | | `requirement` | Requirement | Find a single requirement | | `requirementStatesCount` | RequirementStatesCount | Number of requirements for the project by their state | +| `requirements` | RequirementConnection | Find requirements | | `sastCiConfiguration` | SastCiConfiguration | SAST CI configuration for the project | | `securityDashboardPath` | String | Path to project's security dashboard | | `securityScanners` | SecurityScanners | Information about security analyzers used in the project | @@ -1992,15 +2364,21 @@ Autogenerated return type of PipelineRetry. | `sentryErrors` | SentryErrorCollection | Paginated collection of Sentry errors on the project | | `serviceDeskAddress` | String | E-mail address of the service desk. | | `serviceDeskEnabled` | Boolean | Indicates if the project has service desk enabled. | +| `services` | ServiceConnection | Project services | | `sharedRunnersEnabled` | Boolean | Indicates if shared runners are enabled for the project | +| `snippets` | SnippetConnection | Snippets of the project | | `snippetsEnabled` | Boolean | Indicates if Snippets are enabled for the current user | | `sshUrlToRepo` | String | URL to connect to the project via SSH | | `starCount` | Int! | Number of times the project has been starred | | `statistics` | ProjectStatistics | Statistics of the project | | `suggestionCommitMessage` | String | The commit message used to apply merge request suggestions | | `tagList` | String | List of project topics (not Git tags) | +| `terraformStates` | TerraformStateConnection | Terraform states associated with the project | | `userPermissions` | ProjectPermissions! | Permissions for the current user on the resource | | `visibility` | String | Visibility of the project | +| `vulnerabilities` | VulnerabilityConnection | Vulnerabilities reported on the project | +| `vulnerabilitiesCountByDay` | VulnerabilitiesCountByDayConnection | Number of vulnerabilities per day for the project | +| `vulnerabilityScanners` | VulnerabilityScannerConnection | Vulnerability scanners reported on the project vulnerabilties | | `vulnerabilitySeveritiesCount` | VulnerabilitySeveritiesCount | Counts for each vulnerability severity in the project | | `webUrl` | String | Web URL of the project | | `wikiEnabled` | Boolean | Indicates if Wikis are enabled for the current user | @@ -2072,14 +2450,15 @@ Represents a Project Membership. | Field | Type | Description | | ----- | ---- | ----------- | -| `buildArtifactsSize` | Float! | Build artifacts size of the project | +| `buildArtifactsSize` | Float! | Build artifacts size of the project in bytes | | `commitCount` | Float! | Commit count of the project | -| `lfsObjectsSize` | Float! | Large File Storage (LFS) object size of the project | -| `packagesSize` | Float! | Packages size of the project | -| `repositorySize` | Float! | Repository size of the project | -| `snippetsSize` | Float | Snippets size of the project | -| `storageSize` | Float! | Storage size of the project | -| `wikiSize` | Float | Wiki size of the project | +| `lfsObjectsSize` | Float! | Large File Storage (LFS) object size of the project in bytes | +| `packagesSize` | Float! | Packages size of the project in bytes | +| `repositorySize` | Float! | Repository size of the project in bytes | +| `snippetsSize` | Float | Snippets size of the project in bytes | +| `storageSize` | Float! | Storage size of the project in bytes | +| `uploadsSize` | Float | Uploads size of the project in bytes | +| `wikiSize` | Float | Wiki size of the project in bytes | ### PrometheusAlert @@ -2090,6 +2469,47 @@ The alert condition for Prometheus. | `humanizedText` | String! | The human-readable text of the alert condition | | `id` | ID! | ID of the alert condition | +### PrometheusIntegrationCreatePayload + +Autogenerated return type of PrometheusIntegrationCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `integration` | AlertManagementPrometheusIntegration | The newly created integration | + +### PrometheusIntegrationResetTokenPayload + +Autogenerated return type of PrometheusIntegrationResetToken. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `integration` | AlertManagementPrometheusIntegration | The newly created integration | + +### PrometheusIntegrationUpdatePayload + +Autogenerated return type of PrometheusIntegrationUpdate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `integration` | AlertManagementPrometheusIntegration | The newly created integration | + +### PromoteToEpicPayload + +Autogenerated return type of PromoteToEpic. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `epic` | Epic | The epic after issue promotion | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `issue` | Issue | The issue after mutation | + ### Release Represents a release. @@ -2102,7 +2522,9 @@ Represents a release. | `createdAt` | Time | Timestamp of when the release was created | | `description` | String | Description (also known as "release notes") of the release | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | +| `evidences` | ReleaseEvidenceConnection | Evidence for the release | | `links` | ReleaseLinks | Links of the release | +| `milestones` | MilestoneConnection | Milestones associated to the release | | `name` | String | Name of the release | | `releasedAt` | Time | Timestamp of when the release was released | | `tagName` | String | Name of the tag associated with the release | @@ -2129,6 +2551,18 @@ A container for all assets associated with a release. | Field | Type | Description | | ----- | ---- | ----------- | | `count` | Int | Number of assets of the release | +| `links` | ReleaseAssetLinkConnection | Asset links of the release | +| `sources` | ReleaseSourceConnection | Sources of the release | + +### ReleaseCreatePayload + +Autogenerated return type of ReleaseCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `release` | Release | The release after mutation | ### ReleaseEvidence @@ -2145,9 +2579,12 @@ Evidence for a release. | Field | Type | Description | | ----- | ---- | ----------- | +| `closedIssuesUrl` | String | HTTP URL of the issues page, filtered by this release and `state=closed` | +| `closedMergeRequestsUrl` | String | HTTP URL of the merge request page , filtered by this release and `state=closed` | | `editUrl` | String | HTTP URL of the release's edit page | -| `issuesUrl` | String | HTTP URL of the issues page filtered by this release | -| `mergeRequestsUrl` | String | HTTP URL of the merge request page filtered by this release | +| `mergedMergeRequestsUrl` | String | HTTP URL of the merge request page , filtered by this release and `state=merged` | +| `openedIssuesUrl` | String | HTTP URL of the issues page, filtered by this release and `state=open` | +| `openedMergeRequestsUrl` | String | HTTP URL of the merge request page, filtered by this release and `state=open` | | `selfUrl` | String | HTTP URL of the release | ### ReleaseSource @@ -2178,6 +2615,16 @@ Autogenerated return type of RemoveProjectFromSecurityDashboard. | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### RepositionImageDiffNotePayload + +Autogenerated return type of RepositionImageDiffNote. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `note` | Note | The note after mutation | + ### Repository | Field | Type | Description | @@ -2203,6 +2650,7 @@ Represents a requirement. | `lastTestReportState` | TestReportState | Latest requirement test report state | | `project` | Project! | Project to which the requirement belongs | | `state` | RequirementState! | State of the requirement | +| `testReports` | TestReportConnection | Test reports of the requirement | | `title` | String | Title of the requirement | | `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` | | `updatedAt` | Time! | Timestamp of when the requirement was last updated | @@ -2250,6 +2698,7 @@ Autogenerated return type of RevertVulnerabilityToDetected. | `repositorySize` | Float! | The Git repository size in bytes | | `snippetsSize` | Float! | The snippets size in bytes | | `storageSize` | Float! | The total storage in bytes | +| `uploadsSize` | Float! | The uploads size in bytes | | `wikiSize` | Float! | The wiki size in bytes | ### RunDASTScanPayload @@ -2273,9 +2722,27 @@ Autogenerated return type of RunDASTScan. | Field | Type | Description | | ----- | ---- | ----------- | +| `architectures` | RunnerArchitectureConnection | Runner architectures supported for the platform | | `humanReadableName` | String! | Human readable name of the runner platform | | `name` | String! | Name slug of the runner platform | +### RunnerSetup + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `installInstructions` | String! | Instructions for installing the runner on the specified architecture | +| `registerInstructions` | String | Instructions for registering the runner | + +### SastCiConfiguration + +Represents a CI configuration of SAST. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `analyzers` | SastCiConfigurationAnalyzersEntityConnection | List of analyzers entities attached to SAST configuration. | +| `global` | SastCiConfigurationEntityConnection | List of global entities related to SAST configuration. | +| `pipeline` | SastCiConfigurationEntityConnection | List of pipeline entities related to SAST configuration. | + ### SastCiConfigurationAnalyzersEntity Represents an analyzer entity in SAST CI configuration. @@ -2286,6 +2753,7 @@ Represents an analyzer entity in SAST CI configuration. | `enabled` | Boolean | Indicates whether an analyzer is enabled | | `label` | String | Analyzer label used in the config UI | | `name` | String | Name of the analyzer | +| `variables` | SastCiConfigurationEntityConnection | List of supported variables | ### SastCiConfigurationEntity @@ -2297,6 +2765,7 @@ Represents an entity in SAST CI configuration. | `description` | String | Entity description that is displayed on the form. | | `field` | String | CI keyword of entity. | | `label` | String | Label for entity used in the form. | +| `options` | SastCiConfigurationOptionsEntityConnection | Different possible values of the field. | | `size` | SastUiComponentSize | Size of the UI component. | | `type` | String | Type of the field value. | | `value` | String | Current value of the entity. | @@ -2339,6 +2808,7 @@ Represents a section of a summary of a security report. | Field | Type | Description | | ----- | ---- | ----------- | +| `scannedResources` | ScannedResourceConnection | A list of the first 20 scanned resources | | `scannedResourcesCount` | Int | Total number of scanned resources | | `scannedResourcesCsvPath` | String | Path to download all the scanned resources in CSV format | | `vulnerabilitiesCount` | Int | Total number of vulnerabilities | @@ -2478,12 +2948,15 @@ Represents a snippet entry. | ----- | ---- | ----------- | | `author` | User | The owner of the snippet | | `blob` **{warning-solid}** | SnippetBlob! | **Deprecated:** Use `blobs`. Deprecated in 13.3 | +| `blobs` | SnippetBlobConnection | Snippet blobs | | `createdAt` | Time! | Timestamp this snippet was created | | `description` | String | Description of the snippet | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | +| `discussions` | DiscussionConnection! | All discussions on this noteable | | `fileName` | String | File Name of the snippet | | `httpUrlToRepo` | String | HTTP URL to the snippet repository | -| `id` | ID! | ID of the snippet | +| `id` | SnippetID! | ID of the snippet | +| `notes` | NoteConnection! | All notes on this noteable | | `project` | Project | The project the snippet is associated with | | `rawUrl` | String! | Raw URL of the snippet | | `sshUrlToRepo` | String | SSH URL to the snippet repository | @@ -2537,6 +3010,21 @@ Represents how the blob content should be displayed. | `reportSnippet` | Boolean! | Indicates the user can perform `report_snippet` on this resource | | `updateSnippet` | Boolean! | Indicates the user can perform `update_snippet` on this resource | +### SnippetRepositoryRegistry + +Represents the Geo sync and verification state of a snippet repository. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `createdAt` | Time | Timestamp when the SnippetRepositoryRegistry was created | +| `id` | ID! | ID of the SnippetRepositoryRegistry | +| `lastSyncFailure` | String | Error message during sync of the SnippetRepositoryRegistry | +| `lastSyncedAt` | Time | Timestamp of the most recent successful sync of the SnippetRepositoryRegistry | +| `retryAt` | Time | Timestamp after which the SnippetRepositoryRegistry should be resynced | +| `retryCount` | Int | Number of consecutive failed sync attempts of the SnippetRepositoryRegistry | +| `snippetRepositoryId` | ID! | ID of the Snippet Repository | +| `state` | RegistryState | Sync state of the SnippetRepositoryRegistry | + ### StatusAction | Field | Type | Description | @@ -2575,11 +3063,49 @@ Completion status of tasks. | ----- | ---- | ----------- | | `createdAt` | Time! | Timestamp the Terraform state was created | | `id` | ID! | ID of the Terraform state | +| `latestVersion` | TerraformStateVersion | The latest version of the Terraform state | | `lockedAt` | Time | Timestamp the Terraform state was locked | | `lockedByUser` | User | The user currently holding a lock on the Terraform state | | `name` | String! | Name of the Terraform state | | `updatedAt` | Time! | Timestamp the Terraform state was updated | +### TerraformStateDeletePayload + +Autogenerated return type of TerraformStateDelete. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + +### TerraformStateLockPayload + +Autogenerated return type of TerraformStateLock. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + +### TerraformStateUnlockPayload + +Autogenerated return type of TerraformStateUnlock. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + +### TerraformStateVersion + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `createdAt` | Time! | Timestamp the version was created | +| `createdByUser` | User | The user that created this version | +| `id` | ID! | ID of the Terraform state version | +| `job` | CiJob | The job that created this version | +| `updatedAt` | Time! | Timestamp the version was updated | + ### TerraformStateVersionRegistry Represents the Geo sync and verification state of a terraform state version. @@ -2606,11 +3132,38 @@ Represents a requirement test report. | `id` | ID! | ID of the test report | | `state` | TestReportState! | State of the test report | +### TimeReportStats + +Represents the time report stats for timeboxes. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `complete` | TimeboxMetrics | Completed issues metrics | +| `incomplete` | TimeboxMetrics | Incomplete issues metrics | +| `total` | TimeboxMetrics | Total issues metrics | + +### TimeboxMetrics + +Represents measured stats metrics for timeboxes. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `count` | Int! | The count metric | +| `weight` | Int! | The weight metric | + +### TimeboxReport + +Represents a historically accurate report about the timebox. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `burnupTimeSeries` | BurnupChartDailyTotals! => Array | Daily scope and completed totals for burnup charts | +| `stats` | TimeReportStats | Represents the time report stats for the timebox | + ### Timelog | Field | Type | Description | | ----- | ---- | ----------- | -| `date` **{warning-solid}** | Time! | **Deprecated:** Use `spentAt`. Deprecated in 12.10 | | `issue` | Issue | The issue that logged time was added to | | `note` | Note | The note where the quick action to add the logged time was executed | | `spentAt` | Time | Timestamp of when the time tracked was spent at | @@ -2633,6 +3186,16 @@ Representing a todo entry. | `state` | TodoStateEnum! | State of the todo | | `targetType` | TodoTargetEnum! | Target type of the todo | +### TodoCreatePayload + +Autogenerated return type of TodoCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `todo` | Todo | The to-do created | + ### TodoMarkDonePayload Autogenerated return type of TodoMarkDone. @@ -2652,7 +3215,7 @@ Autogenerated return type of TodoRestoreMany. | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `todos` | Todo! => Array | Updated todos | -| `updatedIds` **{warning-solid}** | ID! => Array | **Deprecated:** Use todos. Deprecated in 13.2 | +| `updatedIds` **{warning-solid}** | TodoID! => Array | **Deprecated:** Use todos. Deprecated in 13.2 | ### TodoRestorePayload @@ -2673,7 +3236,7 @@ Autogenerated return type of TodosMarkAllDone. | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `todos` | Todo! => Array | Updated todos | -| `updatedIds` **{warning-solid}** | ID! => Array | **Deprecated:** Use todos. Deprecated in 13.2 | +| `updatedIds` **{warning-solid}** | TodoID! => Array | **Deprecated:** Use todos. Deprecated in 13.2 | ### ToggleAwardEmojiPayload @@ -2690,7 +3253,10 @@ Autogenerated return type of ToggleAwardEmoji. | Field | Type | Description | | ----- | ---- | ----------- | +| `blobs` | BlobConnection! | Blobs of the tree | | `lastCommit` | Commit | Last commit for the tree | +| `submodules` | SubmoduleConnection! | Sub-modules of the tree | +| `trees` | TreeEntryConnection! | Trees of the tree | ### TreeEntry @@ -2834,12 +3400,20 @@ Autogenerated return type of UpdateSnippet. | Field | Type | Description | | ----- | ---- | ----------- | +| `assignedMergeRequests` | MergeRequestConnection | Merge Requests assigned to the user | +| `authoredMergeRequests` | MergeRequestConnection | Merge Requests authored by the user | | `avatarUrl` | String | URL of the user's avatar | | `email` | String | User email | +| `groupCount` | Int | Group count for the user. Available only when feature flag `user_group_counts` is enabled | +| `groupMemberships` | GroupMemberConnection | Group memberships of the user | | `id` | ID! | ID of the user | | `name` | String! | Human-readable name of the user | +| `projectMemberships` | ProjectMemberConnection | Project memberships of the user | +| `snippets` | SnippetConnection | Snippets authored by the user | +| `starredProjects` | ProjectConnection | Projects starred by the user | | `state` | UserState! | State of the user | | `status` | UserStatus | User status | +| `todos` | TodoConnection! | Todos of the user | | `userPermissions` | UserPermissions! | Permissions for the current user on the resource | | `username` | String! | Username of the user. Unique within this instance of GitLab | | `webPath` | String! | Web path of the user | @@ -2855,13 +3429,14 @@ Autogenerated return type of UpdateSnippet. | Field | Type | Description | | ----- | ---- | ----------- | +| `availability` | AvailabilityEnum! | User availability status | | `emoji` | String | String representation of emoji | | `message` | String | User status message | | `messageHtml` | String | HTML of the user status message | ### VulnerabilitiesCountByDay -Represents the count of vulnerabilities by severity on a particular day. +Represents the count of vulnerabilities by severity on a particular day. This data is retained for 365 days. | Field | Type | Description | | ----- | ---- | ----------- | @@ -2876,7 +3451,7 @@ Represents the count of vulnerabilities by severity on a particular day. ### VulnerabilitiesCountByDayAndSeverity -Represents the number of vulnerabilities for a particular severity on a particular day. +Represents the number of vulnerabilities for a particular severity on a particular day. This data is retained for 365 days. | Field | Type | Description | | ----- | ---- | ----------- | @@ -2892,9 +3467,12 @@ Represents a vulnerability. | ----- | ---- | ----------- | | `description` | String | Description of the vulnerability | | `detectedAt` | Time! | Timestamp of when the vulnerability was first detected | +| `discussions` | DiscussionConnection! | All discussions on this noteable | | `id` | ID! | GraphQL ID of the vulnerability | | `identifiers` | VulnerabilityIdentifier! => Array | Identifiers of the vulnerability. | +| `issueLinks` | VulnerabilityIssueLinkConnection! | List of issue links related to the vulnerability | | `location` | VulnerabilityLocation | Location metadata for the vulnerability. Its fields depend on the type of security scan that found the vulnerability | +| `notes` | NoteConnection! | All notes on this noteable | | `primaryIdentifier` | VulnerabilityIdentifier | Primary identifier of the vulnerability. | | `project` | Project | The project on which the vulnerability was found | | `reportType` | VulnerabilityReportType | Type of the security report that found the vulnerability (SAST, DEPENDENCY_SCANNING, CONTAINER_SCANNING, DAST, SECRET_DETECTION, COVERAGE_FUZZING, API_FUZZING) | @@ -3098,6 +3676,7 @@ Represents vulnerability letter grades with associated projects. | ----- | ---- | ----------- | | `count` | Int! | Number of projects within this grade | | `grade` | VulnerabilityGrade! | Grade based on the highest severity vulnerability present | +| `projects` | ProjectConnection! | Projects within this grade | ## Enumeration types @@ -3150,6 +3729,15 @@ Values for sorting alerts. | `updated_asc` **{warning-solid}** | **Deprecated:** Use UPDATED_ASC. Deprecated in 13.5 | | `updated_desc` **{warning-solid}** | **Deprecated:** Use UPDATED_DESC. Deprecated in 13.5 | +### AlertManagementIntegrationType + +Values of types of integrations. + +| Value | Description | +| ----- | ----------- | +| `HTTP` | Integration with any monitoring tool | +| `PROMETHEUS` | Prometheus integration | + ### AlertManagementSeverity Alert severity values. @@ -3174,6 +3762,15 @@ Alert status values. | `RESOLVED` | Resolved status | | `TRIGGERED` | Triggered status | +### AvailabilityEnum + +User availability status. + +| Value | Description | +| ----- | ----------- | +| `BUSY` | Busy | +| `NOT_SET` | Not Set | + ### BlobViewersType Types of blob viewers. @@ -3233,6 +3830,26 @@ Mode of a commit action. | `SEVEN_DAYS` | 7 days until tags are automatically removed | | `THIRTY_DAYS` | 30 days until tags are automatically removed | +### ContainerRepositoryCleanupStatus + +Status of the tags cleanup of a container repository. + +| Value | Description | +| ----- | ----------- | +| `ONGOING` | The tags cleanup is ongoing. | +| `SCHEDULED` | The tags cleanup is scheduled and is going to be executed shortly. | +| `UNFINISHED` | The tags cleanup has been partially executed. There are still remaining tags to delete. | +| `UNSCHEDULED` | The tags cleanup is not scheduled. This is the default state. | + +### ContainerRepositoryStatus + +Status of a container repository. + +| Value | Description | +| ----- | ----------- | +| `DELETE_FAILED` | Delete Failed status. | +| `DELETE_SCHEDULED` | Delete Scheduled status. | + ### DastScanTypeEnum | Value | Description | @@ -3249,6 +3866,13 @@ Mode of a commit action. | `PASSED_VALIDATION` | Site validation process finished successfully | | `PENDING_VALIDATION` | Site validation process has not started | +### DastSiteValidationStrategyEnum + +| Value | Description | +| ----- | ----------- | +| `HEADER` | Header validation | +| `TEXT_FILE` | Text file validation | + ### DesignCollectionCopyState Copy state of a DesignCollection. @@ -3382,6 +4006,8 @@ Values for sorting issues. | `RELATIVE_POSITION_ASC` | Relative position by ascending order | | `SEVERITY_ASC` | Severity from less critical to more critical | | `SEVERITY_DESC` | Severity from more critical to less critical | +| `SLA_DUE_AT_ASC` | Issues with earliest SLA due time shown first | +| `SLA_DUE_AT_DESC` | Issues with latest SLA due time shown first | | `UPDATED_ASC` | Updated at ascending order | | `UPDATED_DESC` | Updated at descending order | | `WEIGHT_ASC` | Weight by ascending order | @@ -3433,6 +4059,15 @@ State of a GitLab iteration. | `started` | | | `upcoming` | | +### IterationWildcardId + +Iteration ID wildcard values. + +| Value | Description | +| ----- | ----------- | +| `ANY` | An iteration is assigned | +| `NONE` | No iteration is assigned | + ### ListLimitMetric List limit metric setting. @@ -3528,6 +4163,7 @@ Values for sorting projects. | Value | Description | | ----- | ----------- | | `SIMILARITY` | Most similar to the search query | +| `STORAGE` | Sort by storage size | ### PackageTypeEnum @@ -3572,18 +4208,6 @@ Values for sorting projects. | `SUCCESS` | | | `WAITING_FOR_RESOURCE` | | -### ProjectSettingEnum - -Names of compliance frameworks that can be assigned to a Project. - -| Value | Description | -| ----- | ----------- | -| `gdpr` | | -| `hipaa` | | -| `pci_dss` | | -| `soc_2` | | -| `sox` | | - ### RegistryState State of a Geo registry. @@ -3597,7 +4221,7 @@ State of a Geo registry. ### ReleaseAssetLinkType -Type of the link: `other`, `runbook`, `image`, `package`; defaults to `other`. +Type of the link: `other`, `runbook`, `image`, `package`. | Value | Description | | ----- | ----------- | @@ -3606,6 +4230,17 @@ Type of the link: `other`, `runbook`, `image`, `package`; defaults to `other`. | `PACKAGE` | Package link type | | `RUNBOOK` | Runbook link type | +### ReleaseSort + +Values for sorting releases. + +| Value | Description | +| ----- | ----------- | +| `CREATED_ASC` | Created at ascending order | +| `CREATED_DESC` | Created at descending order | +| `RELEASED_AT_ASC` | Released at by ascending order | +| `RELEASED_AT_DESC` | Released at by descending order | + ### RequirementState State of a requirement. @@ -3625,6 +4260,18 @@ Size of UI component in SAST configuration page. | `MEDIUM` | | | `SMALL` | | +### SecurityReportTypeEnum + +| Value | Description | +| ----- | ----------- | +| `API_FUZZING` | API FUZZING scan report | +| `CONTAINER_SCANNING` | CONTAINER SCANNING scan report | +| `COVERAGE_FUZZING` | COVERAGE FUZZING scan report | +| `DAST` | DAST scan report | +| `DEPENDENCY_SCANNING` | DEPENDENCY SCANNING scan report | +| `SAST` | SAST scan report | +| `SECRET_DETECTION` | SECRET DETECTION scan report | + ### SecurityScannerType The type of the security scanner. diff --git a/doc/api/graphql/removed_items.md b/doc/api/graphql/removed_items.md new file mode 100644 index 00000000000..f05b23495bb --- /dev/null +++ b/doc/api/graphql/removed_items.md @@ -0,0 +1,17 @@ +# GraphQL API removed items + +GraphQL is a versionless API, unlike the REST API. +Occasionally, items have to be updated or removed from the GraphQL API. +According to our [process for removing items](index.md#deprecation-process), here are the items that have been removed. + +## GitLab 13.6 + +Fields removed in [GitLab 13.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44866): + +| Field name | GraphQL type | Deprecated in | Use instead | +| -------------------- | -------------------- | ------------- | -------------------------- | +| `date` | `Timelog` **(STARTER)** | 12.10 | `spentAt` | +| `designs` | `Issue`, `EpicIssue` | 12.2 | `designCollection` | +| `latestPipeline` | `Commit` | 12.5 | `pipelines` | +| `mergeCommitMessage` | `MergeRequest` | 11.8 | `latestMergeCommitMessage` | +| `token` | `GrafanaIntegration` | 12.7 | None. Plaintext tokens no longer supported for security reasons. | diff --git a/doc/api/graphql/sample_issue_boards.md b/doc/api/graphql/sample_issue_boards.md index 4ac9317b01a..27fd1f48aec 100644 --- a/doc/api/graphql/sample_issue_boards.md +++ b/doc/api/graphql/sample_issue_boards.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Identify issue boards with GraphQL This page describes how you can use the GraphiQL explorer to identify diff --git a/doc/api/group_activity_analytics.md b/doc/api/group_activity_analytics.md index 90920d1b25c..ea2527e6c4a 100644 --- a/doc/api/group_activity_analytics.md +++ b/doc/api/group_activity_analytics.md @@ -1,3 +1,9 @@ +--- +stage: Manage +group: Optimize +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Group Activity Analytics API > [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 43e1944226d..e13b9633da9 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Group badges API > [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 4ff373ce583..6158400f882 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -265,44 +265,17 @@ Example response: { "id": 1, "name": "newboard", + "project": null, + "lists" : [], "group": { "id": 5, "name": "Documentcloud", "web_url": "http://example.com/groups/documentcloud" }, - "milestone": { - "id": 12 - "title": "10.0" - }, - "lists" : [ - { - "id" : 1, - "label" : { - "name" : "Testing", - "color" : "#F0AD4E", - "description" : null - }, - "position" : 1 - }, - { - "id" : 2, - "label" : { - "name" : "Ready", - "color" : "#FF0000", - "description" : null - }, - "position" : 2 - }, - { - "id" : 3, - "label" : { - "name" : "Production", - "color" : "#FF5F00", - "description" : null - }, - "position" : 3 - } - ] + "milestone": null, + "assignee" : null, + "labels" : [], + "weight" : null } ``` diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md index 01d81eb62ac..5677cb51c37 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -1,3 +1,9 @@ +--- +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Group Import/Export API > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20353) in GitLab 12.8. diff --git a/doc/api/group_iterations.md b/doc/api/group_iterations.md index 62431244d78..eb6a99a430e 100644 --- a/doc/api/group_iterations.md +++ b/doc/api/group_iterations.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. This page describes the group iterations API. -There's a separate [project iterations API](./iterations.md) page. +There's a separate [project iterations API](iterations.md) page. ## List group iterations diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index 260ee669e08..f11a4d8ccc9 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.md @@ -26,6 +26,9 @@ GET /groups/:id/labels | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | | `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced in GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543))_ | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | +| `include_descendant_groups` | boolean | no | Include descendant groups. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | +| `only_group_labels` | boolean | no | Toggle to include only group labels or also project labels. Defaults to `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | +| `search` | string | no | Keyword to filter labels by. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels?with_counts=true" @@ -75,6 +78,8 @@ GET /groups/:id/labels/:label_id | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | | `label_id` | integer or string | yes | The ID or title of a group's label. | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | +| `include_descendant_groups` | boolean | no | Include descendant groups. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | +| `only_group_labels` | boolean | no | Toggle to include only group labels or also project labels. Defaults to `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/bug" diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index aa5f0b3db72..6997ebdede4 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Group-level Variables API > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34519) in GitLab 9.5 diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index 3220707e9e3..a2acf2c8fb1 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12819) in GitLab 9.5. This page describes the group milestones API. -There's a separate [project milestones API](./milestones.md) page. +There's a separate [project milestones API](milestones.md) page. ## List group milestones diff --git a/doc/api/groups.md b/doc/api/groups.md index 53c92cf85ec..0a584795d21 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Groups API ## List groups @@ -89,7 +95,7 @@ GET /groups?statistics=true "parent_id": null, "created_at": "2020-01-15T12:36:29.590Z", "statistics": { - "storage_size" : 212, + "storage_size" : 363, "repository_size" : 33, "wiki_size" : 100, "lfs_objects_size" : 123, @@ -1037,6 +1043,7 @@ GET /groups/:id/hooks/:hook_id "pipeline_events": true, "wiki_page_events": true, "deployment_events": true, + "releases_events": true, "enable_ssl_verification": true, "created_at": "2012-10-12T17:04:47Z" } @@ -1065,6 +1072,7 @@ POST /groups/:id/hooks | `pipeline_events` | boolean | no | Trigger hook on pipeline events | | `wiki_page_events` | boolean | no | Trigger hook on wiki events | | `deployment_events` | boolean | no | Trigger hook on deployment events | +| `releases_events` | boolean | no | Trigger hook on release events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | | `token` | string | no | Secret token to validate received payloads; this will not be returned in the response | @@ -1092,6 +1100,7 @@ PUT /groups/:id/hooks/:hook_id | `pipeline_events` | boolean | no | Trigger hook on pipeline events | | `wiki_events` | boolean | no | Trigger hook on wiki events | | `deployment_events` | boolean | no | Trigger hook on deployment events | +| `releases_events` | boolean | no | Trigger hook on release events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | | `token` | string | no | Secret token to validate received payloads; this will not be returned in the response | @@ -1113,7 +1122,7 @@ DELETE /groups/:id/hooks/:hook_id Group audit events can be accessed via the [Group Audit Events API](audit_events.md#group-audit-events) -## Sync group with LDAP **(STARTER)** +## Sync group with LDAP **(STARTER ONLY)** Syncs the group with its linked LDAP group. Only available to group owners and administrators. @@ -1133,7 +1142,7 @@ Please consult the [Group Members](members.md) documentation. List, add, and delete LDAP group links. -### List LDAP group links **(STARTER)** +### List LDAP group links **(STARTER ONLY)** Lists LDAP group links. @@ -1145,7 +1154,7 @@ GET /groups/:id/ldap_group_links | --------- | -------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -### Add LDAP group link with CN or filter **(STARTER)** +### Add LDAP group link with CN or filter **(STARTER ONLY)** Adds an LDAP group link using a CN or filter. Adding a group link by filter is only supported in the Premium tier and above. @@ -1164,7 +1173,7 @@ POST /groups/:id/ldap_group_links NOTE: **Note:** To define the LDAP group link, provide either a `cn` or a `filter`, but not both. -### Delete LDAP group link **(STARTER)** +### Delete LDAP group link **(STARTER ONLY)** Deletes an LDAP group link. Deprecated. Will be removed in a future release. @@ -1189,7 +1198,7 @@ DELETE /groups/:id/ldap_group_links/:provider/:cn | `cn` | string | yes | The CN of an LDAP group | | `provider` | string | yes | LDAP provider for the LDAP group link | -### Delete LDAP group link with CN or filter **(STARTER)** +### Delete LDAP group link with CN or filter **(STARTER ONLY)** Deletes an LDAP group link using a CN or filter. Deleting by filter is only supported in the Premium tier and above. diff --git a/doc/api/import.md b/doc/api/import.md index e377853ade0..27f5915b206 100644 --- a/doc/api/import.md +++ b/doc/api/import.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Import API ## Import repository from GitHub @@ -13,10 +19,20 @@ POST /import/github | `personal_access_token` | string | yes | GitHub personal access token | | `repo_id` | integer | yes | GitHub repository ID | | `new_name` | string | no | New repository name | -| `target_namespace` | string | yes | Namespace to import repository into | +| `target_namespace` | string | yes | Namespace to import repository into. Supports subgroups like `/namespace/subgroup`. | +| `github_hostname` | string | no | Custom GitHub enterprise hostname. Defaults to GitHub.com if `github_hostname` is not set. | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "personal_access_token=abc123&repo_id=12345&target_namespace=root" "https://gitlab.example.com/api/v4/import/github" +curl --request POST \ + --url "https://gitlab.example.com/api/v4/import/github" \ + --header "content-type: application/json" \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --data '{ + "personal_access_token": "aBc123abC12aBc123abC12abC123+_A/c123", + "repo_id": "12345", + "target_namespace": "group/subgroup", + "new_name": "NEW-NAME" +}' ``` Example response: @@ -51,7 +67,7 @@ POST /import/bitbucket_server | `bitbucket_server_project` | string | yes | Bitbucket Project Key | | `bitbucket_server_repo` | string | yes | Bitbucket Repository Name | | `new_name` | string | no | New repository name | -| `target_namespace` | string | no | Namespace to import repository into | +| `target_namespace` | string | no | Namespace to import repository into. Supports subgroups like `/namespace/subgroup` | ```shell curl --request POST \ diff --git a/doc/api/instance_clusters.md b/doc/api/instance_clusters.md index 1108550eee7..bc4eca5abfd 100644 --- a/doc/api/instance_clusters.md +++ b/doc/api/instance_clusters.md @@ -1,3 +1,9 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Instance clusters API > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36001) in GitLab 13.2. diff --git a/doc/api/invitations.md b/doc/api/invitations.md new file mode 100644 index 00000000000..6fd2b26d80f --- /dev/null +++ b/doc/api/invitations.md @@ -0,0 +1,107 @@ +--- +stage: Growth +group: Expansion +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Invitations API + +Use the Invitations API to send email to users you want to join a group or project, and to list pending +invitations. + +## Valid access levels + +To send an invitation, you must have access to the project or group you are sending email for. Valid access +levels are defined in the `Gitlab::Access` module. Currently, these levels are valid: + +- No access (`0`) +- Guest (`10`) +- Reporter (`20`) +- Developer (`30`) +- Maintainer (`40`) +- Owner (`50`) - Only valid to set for groups + +CAUTION: **Caution:** +Due to [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/219299), +projects in personal namespaces will not show owner (`50`) permission. + +## Invite by email to group or project + +Invites a new user by email to join a group or project. + +```plaintext +POST /groups/:id/invitations +POST /projects/:id/invitations +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `email` | integer/string | yes | The email of the new member or multiple emails separated by commas | +| `access_level` | integer | yes | A valid access level | +| `expires_at` | string | no | A date string in the format YEAR-MONTH-DAY | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "email=test@example.com&access_level=30" "https://gitlab.example.com/api/v4/groups/:id/invitations" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "email=test@example.com&access_level=30" "https://gitlab.example.com/api/v4/projects/:id/invitations" +``` + +Example responses: + +When all emails were successfully sent: + +```json +{ "status": "success" } +``` + +When there was any error sending the email: + +```json +{ + "status": "error", + "message": { + "test@example.com": "Already invited", + "test2@example.com": "Member already exsists" + } +} +``` + +## List all invitations pending for a group or project + +Gets a list of invited group or project members viewable by the authenticated user. +Returns invitations to direct members only, and not through inherited ancestors' groups. + +This function takes pagination parameters `page` and `per_page` to restrict the list of users. + +```plaintext +GET /groups/:id/invitations +GET /projects/:id/invitations +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `page` | integer | no | Page to retrieve | +| `per_page`| integer | no | Number of member invitations to return per page | +| `query` | string | no | A query string to search for invited members by invite email. Query text must match email address exactly. When empty, returns all invitations. | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/invitations?query=member@example.org" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/invitations?query=member@example.org" +``` + +Example response: + +```json + [ + { + "id": 1, + "invite_email": "member@example.org", + "invited_at": "2020-10-22T14:13:35Z", + "access_level": 30, + "expires_at": "2020-11-22T14:13:35Z", + "user_name": "Raymond Smith", + "created_by_name": "Administrator" + }, +] +``` diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index 757910d0946..41e2dd7c147 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Issue links API **(CORE)** > The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4. diff --git a/doc/api/issues.md b/doc/api/issues.md index b50ea7b42be..ad5990f4a37 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -55,11 +55,14 @@ GET /issues?state=opened | `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | | `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | | `confidential` | boolean | no | Filter confidential or public issues. | -| `created_after` | datetime | no | Return issues created on or after the given time | -| `created_before` | datetime | no | Return issues created on or before the given time | +| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `due_date` | string | no | Return issues that have no due date (`0`) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | +| `iteration_id` **(STARTER)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6)_ | +| `iteration_title` **(STARTER)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6)_ | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | @@ -70,8 +73,8 @@ GET /issues?state=opened | `search` | string | no | Search issues against their `title` and `description` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `state` | string | no | Return `all` issues or just those that are `opened` or `closed` | -| `updated_after` | datetime | no | Return issues updated on or after the given time | -| `updated_before` | datetime | no | Return issues updated on or before the given time | +| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | | `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413)| @@ -234,8 +237,8 @@ GET /groups/:id/issues?state=opened | `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | | `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | | `confidential` | boolean | no | Filter confidential or public issues. | -| `created_after` | datetime | no | Return issues created on or after the given time | -| `created_before` | datetime | no | Return issues created on or before the given time | +| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `due_date` | string | no | Return issues that have no due date (`0`) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | @@ -249,8 +252,8 @@ GET /groups/:id/issues?state=opened | `search` | string | no | Search group issues against their `title` and `description` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | -| `updated_after` | datetime | no | Return issues updated on or after the given time | -| `updated_before` | datetime | no | Return issues updated on or before the given time | +| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | | `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | @@ -411,8 +414,8 @@ GET /projects/:id/issues?state=opened | `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | | `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | | `confidential` | boolean | no | Filter confidential or public issues. | -| `created_after` | datetime | no | Return issues created on or after the given time | -| `created_before` | datetime | no | Return issues created on or before the given time | +| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `due_date` | string | no | Return issues that have no due date (`0`) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | @@ -425,8 +428,8 @@ GET /projects/:id/issues?state=opened | `search` | string | no | Search project issues against their `title` and `description` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | -| `updated_after` | datetime | no | Return issues updated on or after the given time | -| `updated_before` | datetime | no | Return issues updated on or before the given time | +| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | | `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. `description_html` was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | @@ -1507,10 +1510,10 @@ Example response: } ``` -## Create a to do +## Create a to-do item -Manually creates a to do for the current user on an issue. If -there already exists a to do for the user on that issue, status code `304` is +Manually creates a to-do item for the current user on an issue. If +there already exists a to-do item for the user on that issue, status code `304` is returned. ```plaintext @@ -1941,7 +1944,7 @@ GET /projects/:id/issues/:issue_iid/closed_by | Attribute | Type | Required | Description | | ----------- | ---------------| -------- | ---------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](./README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project issue | ```shell @@ -2081,4 +2084,4 @@ Example response: ## List issue state events To track which state was set, who did it, and when it happened, check out -[Resource state events API](./resource_state_events.md#issues). +[Resource state events API](resource_state_events.md#issues). diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md index 8e2dcc07af8..3f0b22cca4c 100644 --- a/doc/api/issues_statistics.md +++ b/doc/api/issues_statistics.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Issues Statistics API Every API call to issues_statistics must be authenticated. @@ -39,10 +45,10 @@ GET /issues_statistics?confidential=true | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `search` | string | no | Search issues against their `title` and `description` | | `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | -| `created_after` | datetime | no | Return issues created on or after the given time | -| `created_before` | datetime | no | Return issues created on or before the given time | -| `updated_after` | datetime | no | Return issues updated on or after the given time | -| `updated_before` | datetime | no | Return issues updated on or before the given time | +| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `confidential` | boolean | no | Filter confidential or public issues. | ```shell @@ -95,10 +101,10 @@ GET /groups/:id/issues_statistics?confidential=true | `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE `assignee_username` array should only contain a single value or an invalid parameter error will be returned otherwise. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | | `search` | string | no | Search group issues against their `title` and `description` | -| `created_after` | datetime | no | Return issues created on or after the given time | -| `created_before` | datetime | no | Return issues created on or before the given time | -| `updated_after` | datetime | no | Return issues updated on or after the given time | -| `updated_before` | datetime | no | Return issues updated on or before the given time | +| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `confidential` | boolean | no | Filter confidential or public issues. | ```shell @@ -151,10 +157,10 @@ GET /projects/:id/issues_statistics?confidential=true | `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE `assignee_username` array should only contain a single value or an invalid parameter error will be returned otherwise. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | | `search` | string | no | Search project issues against their `title` and `description` | -| `created_after` | datetime | no | Return issues created on or after the given time | -| `created_before` | datetime | no | Return issues created on or before the given time | -| `updated_after` | datetime | no | Return issues updated on or after the given time | -| `updated_before` | datetime | no | Return issues updated on or before the given time | +| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `confidential` | boolean | no | Filter confidential or public issues. | ```shell diff --git a/doc/api/iterations.md b/doc/api/iterations.md index 53a6bb00f23..9f1585eed79 100644 --- a/doc/api/iterations.md +++ b/doc/api/iterations.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. This page describes the project iterations API. -There's a separate [group iterations API](./group_iterations.md) page. +There's a separate [group iterations API](group_iterations.md) page. As of GitLab 13.5, we don't have project-level iterations, but you can use this endpoint to fetch the iterations of the project's ancestor groups. diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index f5510f6ee91..54085e6f508 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Job Artifacts API ## Get job artifacts diff --git a/doc/api/labels.md b/doc/api/labels.md index 30290f18653..acc80badd11 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -24,6 +24,7 @@ GET /projects/:id/labels | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced in GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543))_ | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | +| `search` | string | no | Keyword to filter labels by. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels?with_counts=true" @@ -248,9 +249,12 @@ An older endpoint `PUT /projects/:id/labels` with `name` or `label_id` in the pa ## Promote a project label to a group label -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25218) in GitLab 12.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25218) in GitLab 12.3. +> - In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/231472), promoting a +> project label keeps that label's ID and changes it into a group label. Previously, promoting a +> project label created a new group label with a new ID and deleted the old label. -Promotes a project label to a group label. +Promotes a project label to a group label. The label keeps its ID. ```plaintext PUT /projects/:id/labels/:label_id/promote diff --git a/doc/api/license.md b/doc/api/license.md index dcdf019059b..8c92a46a975 100644 --- a/doc/api/license.md +++ b/doc/api/license.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # License **(CORE ONLY)** To interact with license endpoints, you need to authenticate yourself as an diff --git a/doc/api/lint.md b/doc/api/lint.md index c82e0845f99..24de4a24ff1 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -36,7 +36,20 @@ Example responses: ```json { "status": "valid", - "errors": [] + "errors": [], + "warnings": [] + } + ``` + +- Valid content with warnings: + + ```json + { + "status": "valid", + "errors": [], + "warnings": ["jobs:job may allow multiple pipelines to run for a single action due to + `rules:when` clause with no `workflow:rules` - read more: + https://docs.gitlab.com/ee/ci/troubleshooting.html#pipeline-warnings"] } ``` @@ -47,7 +60,8 @@ Example responses: "status": "invalid", "errors": [ "variables config should be a hash of key value pairs" - ] + ], + "warnings": [] } ``` @@ -99,6 +113,54 @@ Example response: } ``` +## Validate a CI YAML configuration with a namespace + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231352) in GitLab 13.6. + +Checks if CI/CD YAML configuration is valid. This endpoint has namespace +specific context. + +```plaintext +POST /projects/:id/ci/lint +``` + +| Attribute | Type | Required | Description | +| ---------- | ------- | -------- | -------- | +| `content` | string | yes | The CI/CD configuration content. | +| `dry_run` | boolean | no | Run [pipeline creation simulation](../ci/lint.md#pipeline-simulation), or only do static check. This is false by default. | + +Example request: + +```shell +curl --header "Content-Type: application/json" "https://gitlab.example.com/api/v4/projects/:id/ci/lint" --data '{"content": "{ \"image\": \"ruby:2.6\", \"services\": [\"postgres\"], \"before_script\": [\"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}' +``` + +Example responses: + +- Valid configuration: + + ```json + { + "valid": true, + "merged_yaml": "---\n:test_job:\n :script: echo 1\n", + "errors": [], + "warnings": [] + } + ``` + +- Invalid configuration: + + ```json + { + "valid": false, + "merged_yaml": "---\n:test_job:\n :script: echo 1\n", + "errors": [ + "jobs config should contain at least one visible job" + ], + "warnings": [] + } + ``` + ## Validate a project's CI configuration > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231352) in GitLab 13.5. diff --git a/doc/api/managed_licenses.md b/doc/api/managed_licenses.md index 984cfa92d3a..f7f6fbfbc47 100644 --- a/doc/api/managed_licenses.md +++ b/doc/api/managed_licenses.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Managed Licenses API **(ULTIMATE)** ## List managed licenses diff --git a/doc/api/members.md b/doc/api/members.md index 4440b70c512..d616dfdd85c 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Group and project members API ## Valid access levels diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 194f48c6e84..44c59fd497b 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -55,10 +55,10 @@ Parameters: | `labels` | string | no | Return 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. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | | `with_labels_details` | boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | | `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 in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) | -| `created_after` | datetime | no | Return merge requests created on or after the given time | -| `created_before` | datetime | no | Return merge requests created on or before the given time | -| `updated_after` | datetime | no | Return merge requests updated on or after the given time | -| `updated_before` | datetime | no | Return merge requests updated on or before the given time | +| `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `created_before` | datetime | no | Return merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_after` | datetime | no | Return merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_before` | datetime | no | Return merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. | | `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`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 12.10)_ | | @@ -72,9 +72,9 @@ Parameters: | `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | | `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests | | `not` | Hash | no | Return merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji` | -| `environment` | string | no | Returns merge requests deployed to the given environment -| `deployed_before` | datetime | no | Return merge requests deployed before the given date/time -| `deployed_after` | datetime | no | Return merge requests deployed after the given date/time +| `environment` | string | no | Returns merge requests deployed to the given environment. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `deployed_before` | datetime | no | Return merge requests deployed before the given date/time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `deployed_after` | datetime | no | Return merge requests deployed after the given date/time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | NOTE: **Note:** [Starting in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890), @@ -246,10 +246,10 @@ Parameters: | `labels` | string | no | Return 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. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | | `with_labels_details` | boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | | `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 in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) | -| `created_after` | datetime | no | Return merge requests created on or after the given time | -| `created_before` | datetime | no | Return merge requests created on or before the given time | -| `updated_after` | datetime | no | Return merge requests updated on or after the given time | -| `updated_before` | datetime | no | Return merge requests updated on or before the given time | +| `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `created_before` | datetime | no | Return merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_after` | datetime | no | Return merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_before` | datetime | no | Return merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | | `author_id` | integer | no | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 9.5)_ | `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 12.10)_ | | @@ -410,10 +410,10 @@ Parameters: | `labels` | string | no | Return 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. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | | `with_labels_details` | boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413)| | `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 in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) | -| `created_after` | datetime | no | Return merge requests created on or after the given time | -| `created_before` | datetime | no | Return merge requests created on or before the given time | -| `updated_after` | datetime | no | Return merge requests updated on or after the given time | -| `updated_before` | datetime | no | Return merge requests updated on or before the given time | +| `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `created_before` | datetime | no | Return merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_after` | datetime | no | Return merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `updated_before` | datetime | no | Return merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> | | `author_id` | integer | no | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 9.5)_ | `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 12.10)_ | | @@ -787,10 +787,17 @@ Shows information about the merge request including its files and changes. GET /projects/:id/merge_requests/:merge_request_iid/changes ``` +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46190) in GitLab 13.6, +diffs associated with the set of changes will have the same size limitations applied as other diffs +returned by the API or viewed via the UI. When these limits impact the results, the `overflow` +field will contain a value of `true`. Diff data without these limits applied can be retrieved by +adding the `access_raw_diffs` parameter, however, it will be slower and more resource-intensive. + Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `merge_request_iid` (required) - The internal ID of the merge request +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. +- `merge_request_iid` (required) - The internal ID of the merge request. +- `access_raw_diffs` (optional) - Retrieve change diffs without size limitations. ```json { @@ -884,7 +891,8 @@ Parameters: "renamed_file": false, "deleted_file": false } - ] + ], + "overflow": false } ``` @@ -2089,10 +2097,10 @@ the `approvals_before_merge` parameter: } ``` -## Create a to do +## Create a to-do item -Manually creates a to do for the current user on a merge request. -If there already exists a to do for the user on that merge request, +Manually creates a to-do item for the current user on a merge request. +If there already exists a to-do item for the user on that merge request, status code `304` is returned. ```plaintext @@ -2464,4 +2472,4 @@ For approvals, please see [Merge Request Approvals](merge_request_approvals.md) ## List merge request state events To track which state was set, who did it, and when it happened, check out -[Resource state events API](./resource_state_events.md#merge-requests). +[Resource state events API](resource_state_events.md#merge-requests). diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 7b26dbadad4..161b3b81499 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Project milestones API This page describes the project milestones API. -There's a separate [group milestones API](./group_milestones.md) page. +There's a separate [group milestones API](group_milestones.md) page. ## List project milestones diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 0792c6d4a3b..f61400dfddb 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Namespaces API Usernames and groupnames fall under a special category called namespaces. diff --git a/doc/api/notes.md b/doc/api/notes.md index aaff28757bb..70aa4923b97 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -1,3 +1,9 @@ +--- +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/engineering/ux/technical-writing/#designated-technical-writers +--- + # Notes API Notes are comments on: diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 8442e371a56..cbe5aa46a5d 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Notification settings API > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5632) in GitLab 8.12. diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index 5fbb7913ff4..b1c81ff20b6 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technica l-writing/#designated-technical-writers +--- + # GitLab as an OAuth2 provider This document covers using the [OAuth2](https://oauth.net/2/) protocol to allow @@ -28,12 +35,24 @@ During registration, by enabling proper scopes, you can limit the range of resources which the `application` can access. Upon creation, you'll obtain the `application` credentials: _Application ID_ and _Client Secret_ - **keep them secure**. -CAUTION: **Important:** -OAuth specification advises sending the `state` parameter with each request to -`/oauth/authorize`. We highly recommended sending a unique value with each request -and validate it against the one in the redirect request. This is important in -order to prevent [CSRF attacks](https://wiki.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)). -The `state` parameter really should have been a requirement in the standard! +### Prevent CSRF attacks + +To [protect redirect-based flows](https://tools.ietf.org/id/draft-ietf-oauth-security-topics-13.html#rec_redirect), +the OAuth specification recommends the use of "One-time use CSRF tokens carried in the state +parameter, which are securely bound to the user agent", with each request to the +`/oauth/authorize` endpoint. This can prevent +[CSRF attacks](https://wiki.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)). + +### Use HTTPS in production + +For production, please use HTTPS for your `redirect_uri`. +For development, GitLab allows insecure HTTP redirect URIs. + +As OAuth2 bases its security entirely on the transport layer, you should not use unprotected +URIs. For more information, see the [OAuth 2.0 RFC](https://tools.ietf.org/html/rfc6749#section-3.1.2.1) +and the [OAuth 2.0 Threat Model RFC](https://tools.ietf.org/html/rfc6819#section-4.4.2.1). +These factors are particularly important when using the +[Implicit grant flow](#implicit-grant-flow), where actual credentials are included in the `redirect_uri`. In the following sections you will find detailed instructions on how to obtain authorization with each flow. diff --git a/doc/api/packages.md b/doc/api/packages.md index d4e69b9bc66..8124b081506 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -93,9 +93,10 @@ GET /groups/:id/packages curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/packages?exclude_subgroups=true" ``` -CAUTION: **Deprecation:** -> The `build_info` attribute in the response is deprecated in favour of `pipeline`. -> Introduced [GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28040). +> **Deprecation:** +> +> The `pipeline` attribute in the response is deprecated in favor of `pipelines`, which was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44348) in GitLab 13.6. Both are available until 13.7. +> The `build_info` attribute in the response is deprecated in favor of `pipeline`, which was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28040) in GitLab 12.10. Example response: @@ -111,19 +112,21 @@ Example response: "delete_api_path": "/namespace1/project1/-/packages/1" }, "created_at": "2019-11-27T03:37:38.711Z", - "pipeline": { - "id": 123, - "status": "pending", - "ref": "new-pipeline", - "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", - "web_url": "https://example.com/foo/bar/pipelines/47", - "created_at": "2016-08-11T11:28:34.085Z", - "updated_at": "2016-08-11T11:32:35.169Z", - "user": { - "name": "Administrator", - "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon" + "pipelines": [ + { + "id": 123, + "status": "pending", + "ref": "new-pipeline", + "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", + "web_url": "https://example.com/foo/bar/pipelines/47", + "created_at": "2016-08-11T11:28:34.085Z", + "updated_at": "2016-08-11T11:32:35.169Z", + "user": { + "name": "Administrator", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon" + } } - } + ] }, { "id": 2, @@ -135,19 +138,21 @@ Example response: "delete_api_path": "/namespace1/project1/-/packages/1" }, "created_at": "2019-11-27T03:37:38.711Z", - "pipeline": { - "id": 123, - "status": "pending", - "ref": "new-pipeline", - "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", - "web_url": "https://example.com/foo/bar/pipelines/47", - "created_at": "2016-08-11T11:28:34.085Z", - "updated_at": "2016-08-11T11:32:35.169Z", - "user": { - "name": "Administrator", - "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon" + "pipelines": [ + { + "id": 123, + "status": "pending", + "ref": "new-pipeline", + "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", + "web_url": "https://example.com/foo/bar/pipelines/47", + "created_at": "2016-08-11T11:28:34.085Z", + "updated_at": "2016-08-11T11:32:35.169Z", + "user": { + "name": "Administrator", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon" + } } - } + ] } ] ``` @@ -178,9 +183,10 @@ GET /projects/:id/packages/:package_id curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/packages/:package_id" ``` -CAUTION: **Deprecation:** -> The `build_info` attribute in the response is deprecated in favour of `pipeline`. -> Introduced [GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28040). +> **Deprecation:** +> +> The `pipeline` attribute in the response is deprecated in favor of `pipelines`, which was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44348) in GitLab 13.6. Both are available until 13.7. +> The `build_info` attribute in the response is deprecated in favor of `pipeline`, which was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28040) in GitLab 12.10. Example response: @@ -195,37 +201,41 @@ Example response: "delete_api_path": "/namespace1/project1/-/packages/1" }, "created_at": "2019-11-27T03:37:38.711Z", - "pipeline": { - "id": 123, - "status": "pending", - "ref": "new-pipeline", - "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", - "web_url": "https://example.com/foo/bar/pipelines/47", - "created_at": "2016-08-11T11:28:34.085Z", - "updated_at": "2016-08-11T11:32:35.169Z", - "user": { - "name": "Administrator", - "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon" + "pipelines": [ + { + "id": 123, + "status": "pending", + "ref": "new-pipeline", + "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", + "web_url": "https://example.com/foo/bar/pipelines/47", + "created_at": "2016-08-11T11:28:34.085Z", + "updated_at": "2016-08-11T11:32:35.169Z", + "user": { + "name": "Administrator", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon" + } } - }, + ], "versions": [ { "id":2, "version":"2.0-SNAPSHOT", "created_at":"2020-04-28T04:42:11.573Z", - "pipeline": { - "id": 234, - "status": "pending", - "ref": "new-pipeline", - "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", - "web_url": "https://example.com/foo/bar/pipelines/58", - "created_at": "2016-08-11T11:28:34.085Z", - "updated_at": "2016-08-11T11:32:35.169Z", - "user": { - "name": "Administrator", - "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon" + "pipelines": [ + { + "id": 234, + "status": "pending", + "ref": "new-pipeline", + "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", + "web_url": "https://example.com/foo/bar/pipelines/58", + "created_at": "2016-08-11T11:28:34.085Z", + "updated_at": "2016-08-11T11:32:35.169Z", + "user": { + "name": "Administrator", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon" + } } - } + ] } ] } @@ -266,7 +276,22 @@ Example response: "file_name": "my-app-1.5-20181107.152550-1.jar", "size": 2421, "file_md5": "58e6a45a629910c6ff99145a688971ac", - "file_sha1": "ebd193463d3915d7e22219f52740056dfd26cbfe" + "file_sha1": "ebd193463d3915d7e22219f52740056dfd26cbfe", + "pipelines": [ + { + "id": 123, + "status": "pending", + "ref": "new-pipeline", + "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", + "web_url": "https://example.com/foo/bar/pipelines/47", + "created_at": "2016-08-11T11:28:34.085Z", + "updated_at": "2016-08-11T11:32:35.169Z", + "user": { + "name": "Administrator", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon" + } + } + ] }, { "id": 26, diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index 43310570fe8..f7cbaeba438 100644 --- a/doc/api/personal_access_tokens.md +++ b/doc/api/personal_access_tokens.md @@ -1,10 +1,17 @@ -# Personal access tokens API **(ULTIMATE)** +--- +stage: Manage +group: Compliance +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Personal access tokens API You can read more about [personal access tokens](../user/profile/personal_access_tokens.md#personal-access-tokens). ## List personal access tokens -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227264) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227264) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.6. Get a list of personal access tokens. @@ -86,3 +93,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git - `204: No Content` if successfully revoked. - `400 Bad Request` if not revoked successfully. + +## Create a personal access token (admin only) + +See the [Users API documentation](users.md#create-a-personal-access-token-admin-only) for information on creating a personal access token. diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 95a7787e029..145a0a5ab7e 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -39,8 +39,8 @@ GET /projects/:id/pipelines | `yaml_errors`| boolean | no | Returns pipelines with invalid configurations | | `name`| string | no | The name of the user who triggered pipelines | | `username`| string | no | The username of the user who triggered pipelines | -| `updated_after` | datetime | no | Return pipelines updated after the specified date. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ | -| `updated_before` | datetime | no | Return pipelines updated before the specified date. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ | +| `updated_after` | datetime | no | Return pipelines updated after the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `updated_before` | datetime | no | Return pipelines updated before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `order_by`| string | no | Order pipelines by `id`, `status`, `ref`, `updated_at` or `user_id` (default: `id`) | | `sort` | string | no | Sort pipelines in `asc` or `desc` order (default: `desc`) | diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md index b490b6235b1..c1ba421e73e 100644 --- a/doc/api/project_repository_storage_moves.md +++ b/doc/api/project_repository_storage_moves.md @@ -9,7 +9,7 @@ type: reference > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31285) in GitLab 13.0. -Project repositories can be moved between storages. This can be useful when +Project repositories including wiki and design repositories can be moved between storages. This can be useful when [migrating to Gitaly Cluster](../administration/gitaly/praefect.md#migrate-existing-repositories-to-gitaly-cluster), for example. @@ -22,10 +22,19 @@ of `state` are: - `finished` - `failed` - `replicated` -- `cleanup_failed` +- `cleanup failed` + +To ensure data integrity, projects are put in a temporary read-only state for the +duration of the move. During this time, users receive a `The repository is temporarily +read-only. Please try again later.` message if they try to push new commits. This API requires you to [authenticate yourself](README.md#authentication) as an administrator. +## Limitations + +- The repositories associated with snippets [can't be moved with the API](https://gitlab.com/groups/gitlab-org/-/epics/3393). +- Group-level wikis [can't be moved with the API](https://gitlab.com/gitlab-org/gitlab/-/issues/219003). + ## Retrieve all project repository storage moves ```plaintext @@ -185,6 +194,14 @@ Example response: ## Schedule a repository storage move for a project +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34119) in GitLab 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/2618) in GitLab 13.3, original repository is automatically removed after successful move and integrity check. + +CAUTION: **Caution:** +Before GitLab 13.3, a repository move worked more like a repository copy as the +original repository was not deleted from the original storage disk location and +had to be manually cleaned up. + ```plaintext POST /projects/:project_id/repository_storage_moves ``` @@ -194,12 +211,12 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `project_id` | integer | yes | ID of the project | -| `destination_storage_name` | string | no | Name of the destination storage shard. If not provided the storage will be selected automatically. | +| `destination_storage_name` | string | no | Name of the destination storage shard. In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitaly/-/issues/3209), the storage is selected automatically if not provided | Example request: ```shell -curl --request POST --header "PRIVATE_TOKEN: <your_access_token>" --header "Content-Type: application/json" \ +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ --data '{"destination_storage_name":"storage2"}' "https://gitlab.example.com/api/v4/projects/1/repository_storage_moves" ``` diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index cc8bb20b003..7955050e716 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -17,7 +17,7 @@ Constants for snippet visibility levels are: | visibility | Description | | ---------- | ----------- | | `private` | The snippet is visible only the snippet creator | -| `internal` | The snippet is visible for any logged in user | +| `internal` | The snippet is visible for any logged in user except [external users](../user/permissions.md#external-users) | | `public` | The snippet can be accessed without any authentication | NOTE: **Note:** diff --git a/doc/api/projects.md b/doc/api/projects.md index f6ed905cda1..1c162e0bbd3 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -13,62 +13,61 @@ This is determined by the `visibility` field in the project. Values for the project visibility level are: -- `private`: - Project access must be granted explicitly for each user. -- `internal`: - The project can be cloned by any logged in user. -- `public`: - The project can be accessed without any authentication. +- `private`: project access must be granted explicitly for each user. +- `internal`: the project can be cloned by any signed-in user except [external users](../user/permissions.md#external-users). +- `public`: the project can be accessed without any authentication. ## Project merge method There are three options for `merge_method` to choose from: -- `merge`: - A merge commit is created for every merge, and merging is allowed as long as there are no conflicts. -- `rebase_merge`: - A merge commit is created for every merge, but merging is only allowed if fast-forward merge is possible. - This way you could make sure that if this merge request would build, after merging to target branch it would also build. -- `ff`: - No merge commits are created and all merges are fast-forwarded, which means that merging is only allowed if the branch could be fast-forwarded. +- `merge`: a merge commit is created for every merge, and merging is allowed if + there are no conflicts. +- `rebase_merge`: a merge commit is created for every merge, but merging is only + allowed if fast-forward merge is possible. This way you could make sure that + if this merge request would build, after merging to target branch it would + also build. +- `ff`: no merge commits are created and all merges are fast-forwarded, which + means that merging is only allowed if the branch could be fast-forwarded. ## List all projects Get a list of all visible projects across GitLab for the authenticated user. -When accessed without authentication, only public projects with "simple" fields are returned. +When accessed without authentication, only public projects with _simple_ fields +are returned. ```plaintext GET /projects ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `archived` | boolean | no | Limit by archived status | -| `id_after` | integer | no | Limit results to projects with IDs greater than the specified ID | -| `id_before` | integer | no | Limit results to projects with IDs less than the specified ID | -| `last_activity_after` | datetime | no | Limit results to projects with last_activity after specified time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ | -| `last_activity_before` | datetime | no | Limit results to projects with last_activity before specified time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ | -| `membership` | boolean | no | Limit by projects that the current user is a member of | -| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md#valid-access-levels) | -| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. `repository_size`, `storage_size`, or `wiki_size` fields are only allowed for admins. Default is `created_at` | -| `owned` | boolean | no | Limit by projects explicitly owned by the current user | -| `repository_checksum_failed` | boolean | no | **(PREMIUM)** Limit projects where the repository checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2) | -| `repository_storage` | string | no | Limit results to projects stored on repository_storage. Available for admins only. | -| `search_namespaces` | boolean | no | Include ancestor namespaces when matching search criteria. Default is `false` | -| `search` | string | no | Return list of projects matching the search criteria | -| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | -| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | -| `starred` | boolean | no | Limit by projects starred by the current user | -| `statistics` | boolean | no | Include project statistics | -| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | -| `wiki_checksum_failed` | boolean | no | **(PREMIUM)** Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2) | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | -| `with_issues_enabled` | boolean | no | Limit by enabled issues feature | -| `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature | -| `with_programming_language` | string | no | Limit by projects which use the given programming language | - -NOTE: **Note:** -This endpoint supports [keyset pagination](README.md#keyset-based-pagination) for selected `order_by` options. +| Attribute | Type | Required | Description | +|--------------------------------------------|----------|------------------------|-------------| +| `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | +| `id_after` | integer | **{dotted-circle}** No | Limit results to projects with IDs greater than the specified ID. | +| `id_before` | integer | **{dotted-circle}** No | Limit results to projects with IDs less than the specified ID. | +| `last_activity_after` | datetime | **{dotted-circle}** No | Limit results to projects with last_activity after specified time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ | +| `last_activity_before` | datetime | **{dotted-circle}** No | Limit results to projects with last_activity before specified time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ | +| `membership` | boolean | **{dotted-circle}** No | Limit by projects that the current user is a member of. | +| `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [access level](members.md#valid-access-levels). | +| `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. `repository_size`, `storage_size`, or `wiki_size` fields are only allowed for admins. Default is `created_at`. | +| `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | +| `repository_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the repository checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2). | +| `repository_storage` | string | **{dotted-circle}** No | Limit results to projects stored on `repository_storage`. _(admins only)_ | +| `search_namespaces` | boolean | **{dotted-circle}** No | Include ancestor namespaces when matching search criteria. Default is `false`. | +| `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | +| `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | +| `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | +| `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | +| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. | +| `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | +| `wiki_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2). | +| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | +| `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | +| `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | +| `with_programming_language` | string | **{dotted-circle}** No | Limit by projects which use the given programming language. | + +This endpoint supports [keyset pagination](README.md#keyset-based-pagination) +for selected `order_by` options. When `simple=true` or the user is unauthenticated this returns something like: @@ -297,11 +296,12 @@ When the user is authenticated and `simple` is not set this returns something li ``` NOTE: **Note:** -For users on GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/) the `marked_for_deletion_at` -attribute has been deprecated and will be removed in API v5 in favor of the `marked_for_deletion_on` attribute. +For users of GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/), +the `marked_for_deletion_at` attribute has been deprecated, and will be removed +in API v5 in favor of the `marked_for_deletion_on` attribute. -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see -the `approvals_before_merge` parameter: +Users of GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) +can also see the `approvals_before_merge` parameter: ```json [ @@ -322,44 +322,45 @@ GET /projects?custom_attributes[key]=value&custom_attributes[other_key]=other_va ### Pagination limits -In GitLab 13.0 and later, [offset-based pagination](README.md#offset-based-pagination) is -[limited to 50,000 records](https://gitlab.com/gitlab-org/gitlab/-/issues/34565). -[Keyset pagination](README.md#keyset-based-pagination) is required to retrieve projects -beyond this limit. +In GitLab 13.0 and later, [offset-based pagination](README.md#offset-based-pagination) +is [limited to 50,000 records](https://gitlab.com/gitlab-org/gitlab/-/issues/34565). +[Keyset pagination](README.md#keyset-based-pagination) is required to retrieve +projects beyond this limit. -Note that keyset pagination only supports `order_by=id`. Other sorting options are not available. +Keyset pagination supports only `order_by=id`. Other sorting options aren't available. ## List user projects -Get a list of visible projects owned by the given user. When accessed without authentication, only public projects are returned. +Get a list of visible projects owned by the given user. When accessed without +authentication, only public projects are returned. + +This endpoint supports [keyset pagination](README.md#keyset-based-pagination) +for selected `order_by` options. ```plaintext GET /users/:user_id/projects ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `user_id` | string | yes | The ID or username of the user | -| `archived` | boolean | no | Limit by archived status | -| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | -| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | -| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | -| `search` | string | no | Return list of projects matching the search criteria | -| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | -| `owned` | boolean | no | Limit by projects explicitly owned by the current user | -| `membership` | boolean | no | Limit by projects that the current user is a member of | -| `starred` | boolean | no | Limit by projects starred by the current user | -| `statistics` | boolean | no | Include project statistics | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | -| `with_issues_enabled` | boolean | no | Limit by enabled issues feature | -| `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature | -| `with_programming_language` | string | no | Limit by projects which use the given programming language | -| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md#valid-access-levels) | -| `id_after` | integer | no | Limit results to projects with IDs greater than the specified ID | -| `id_before` | integer | no | Limit results to projects with IDs less than the specified ID | - -NOTE: **Note:** -This endpoint supports [keyset pagination](README.md#keyset-based-pagination) for selected `order_by` options. +| Attribute | Type | Required | Description | +|-------------------------------|---------|------------------------|-------------| +| `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | +| `id_after` | integer | **{dotted-circle}** No | Limit results to projects with IDs greater than the specified ID. | +| `id_before` | integer | **{dotted-circle}** No | Limit results to projects with IDs less than the specified ID. | +| `membership` | boolean | **{dotted-circle}** No | Limit by projects that the current user is a member of. | +| `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [access level](members.md#valid-access-levels). | +| `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. | +| `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | +| `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | +| `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | +| `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | +| `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | +| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. | +| `user_id` | string | **{check-circle}** Yes | The ID or username of the user. | +| `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | +| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | +| `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | +| `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | +| `with_programming_language` | string | **{dotted-circle}** No | Limit by projects which use the given programming language. | ```json [ @@ -554,29 +555,30 @@ This endpoint supports [keyset pagination](README.md#keyset-based-pagination) fo ## List projects starred by a user -Get a list of visible projects owned by the given user. When accessed without authentication, only public projects are returned. +Get a list of visible projects owned by the given user. When accessed without +authentication, only public projects are returned. ```plaintext GET /users/:user_id/starred_projects ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `user_id` | string | yes | The ID or username of the user. | -| `archived` | boolean | no | Limit by archived status. | -| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private`. | -| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. | -| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc`. | -| `search` | string | no | Return list of projects matching the search criteria. | -| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned.. | -| `owned` | boolean | no | Limit by projects explicitly owned by the current user. | -| `membership` | boolean | no | Limit by projects that the current user is a member of. | -| `starred` | boolean | no | Limit by projects starred by the current user. | -| `statistics` | boolean | no | Include project statistics. | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only). | -| `with_issues_enabled` | boolean | no | Limit by enabled issues feature. | -| `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature. | -| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md#valid-access-levels). | +| Attribute | Type | Required | Description | +|-------------------------------|---------|------------------------|-------------| +| `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | +| `membership` | boolean | **{dotted-circle}** No | Limit by projects that the current user is a member of. | +| `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [access level](members.md#valid-access-levels). | +| `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. | +| `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | +| `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | +| `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned.. | +| `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | +| `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | +| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. | +| `user_id` | string | **{check-circle}** Yes | The ID or username of the user. | +| `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | +| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | +| `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | +| `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/5/starred_projects" @@ -772,12 +774,12 @@ the project is publicly accessible. GET /projects/:id ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `statistics` | boolean | no | Include project statistics | -| `license` | boolean | no | Include project license data | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | +| Attribute | Type | Required | Description | +|--------------------------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `license` | boolean | **{dotted-circle}** No | Include project license data. | +| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. | +| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | ```json { @@ -924,8 +926,8 @@ GET /projects/:id } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see -the `approvals_before_merge` parameter: +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) +can also see the `approvals_before_merge` parameter: ```json { @@ -936,7 +938,9 @@ the `approvals_before_merge` parameter: } ``` -**Note**: The `web_url` and `avatar_url` attributes on `namespace` were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27427) in GitLab 11.11. +The `web_url` and `avatar_url` attributes on `namespace` were +[introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27427) +in GitLab 11.11. If the project is a fork, and you provide a valid token to authenticate, the `forked_from_project` field appears in the response. @@ -995,11 +999,11 @@ Get the users list of a project. GET /projects/:id/users ``` -| Attribute | Type | Required | Description | -| ------------ | ------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `search` | string | no | Search for specific users | -| `skip_users` | integer array | no | Filter out users with the specified IDs | +| Attribute | Type | Required | Description | +|--------------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `search` | string | **{dotted-circle}** No | Search for specific users. | +| `skip_users` | integer array | **{dotted-circle}** No | Filter out users with the specified IDs. | ```json [ @@ -1024,223 +1028,223 @@ GET /projects/:id/users ## Get project events -Please refer to the [Events API documentation](events.md#list-a-projects-visible-events). +Refer to the [Events API documentation](events.md#list-a-projects-visible-events). ## Create project Creates a new project owned by the authenticated user. +If your HTTP repository isn't publicly accessible, add authentication information +to the URL `https://username:password@gitlab.company.com/group/project.git`, +where `password` is a public access key with the `api` scope enabled. + ```plaintext POST /projects ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `name` | string | yes if path is not provided | The name of the new project. Equals path if not provided. | -| `path` | string | yes if name is not provided | Repository name for new project. Generated based on name if not provided (generated as lowercase with dashes). | -| `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) | -| `default_branch` | string | no | `master` by default | -| `description` | string | no | Short project description | -| `issues_enabled` | boolean | no | (deprecated) Enable issues for this project. Use `issues_access_level` instead | -| `merge_requests_enabled` | boolean | no | (deprecated) Enable merge requests for this project. Use `merge_requests_access_level` instead | -| `jobs_enabled` | boolean | no | (deprecated) Enable jobs for this project. Use `builds_access_level` instead | -| `wiki_enabled` | boolean | no | (deprecated) Enable wiki for this project. Use `wiki_access_level` instead | -| `snippets_enabled` | boolean | no | (deprecated) Enable snippets for this project. Use `snippets_access_level` instead | -| `issues_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `repository_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `merge_requests_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `forking_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `builds_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `wiki_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `snippets_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `pages_access_level` | string | no | One of `disabled`, `private`, `enabled` or `public` | -| `emails_disabled` | boolean | no | Disable email notifications | -| `show_default_award_emojis` | boolean | no | Show default award emojis | -| `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push | -| `container_registry_enabled` | boolean | no | Enable container registry for this project | -| `container_expiration_policy_attributes` | hash | no | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (string), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean) | -| `shared_runners_enabled` | boolean | no | Enable shared runners for this project | -| `visibility` | string | no | See [project visibility level](#project-visibility-level) | -| `import_url` | string | no | URL to import repository from | -| `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members | -| `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | -| `allow_merge_on_skipped_pipeline` | boolean | no | Set whether or not merge requests can be merged with skipped jobs | -| `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | -| `merge_method` | string | no | Set the [merge method](#project-merge-method) used | -| `autoclose_referenced_issues` | boolean | no | Set whether auto-closing referenced issues on default branch | -| `remove_source_branch_after_merge` | boolean | no | Enable `Delete source branch` option by default for all new merge requests | -| `lfs_enabled` | boolean | no | Enable LFS | -| `request_access_enabled` | boolean | no | Allow users to request member access | -| `tag_list` | array | no | The list of tags for a project; put array of tags, that should be finally assigned to a project | -| `avatar` | mixed | no | Image file for avatar of the project | -| `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line | -| `build_git_strategy` | string | no | The Git strategy. Defaults to `fetch` | -| `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) | -| `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled | -| `build_coverage_regex` | string | no | Test coverage parsing | -| `ci_config_path` | string | no | The path to CI configuration file | -| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project | -| `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) | -| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins | -| `approvals_before_merge` | integer | no | **(STARTER)** How many approvers should approve merge requests by default | -| `external_authorization_classification_label` | string | no | **(PREMIUM)** The classification label for the project | -| `mirror` | boolean | no | **(STARTER)** Enables pull mirroring in a project | -| `mirror_trigger_builds` | boolean | no | **(STARTER)** Pull mirroring triggers builds | -| `initialize_with_readme` | boolean | no | `false` by default | -| `template_name` | string | no | When used without `use_custom_template`, name of a [built-in project template](../gitlab-basics/create-project.md#built-in-templates). When used with `use_custom_template`, name of a custom project template | -| `template_project_id` | integer | no | **(PREMIUM)** When used with `use_custom_template`, project ID of a custom project template. This is preferable to using `template_name` since `template_name` may be ambiguous. | -| `use_custom_template` | boolean | no | **(PREMIUM)** Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template | -| `group_with_project_templates_id` | integer | no | **(PREMIUM)** 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 | -| `packages_enabled` | boolean | no | Enable or disable packages repository feature | - -NOTE: **Note:** -If your HTTP repository is not publicly accessible, -add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git` -where `password` is a public access key with the `api` scope enabled. +| Attribute | Type | Required | Description | +|-------------------------------------------------------------|---------|------------------------|-------------| +| `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | +| `approvals_before_merge` **(STARTER)** | integer | **{dotted-circle}** No | How many approvers should approve merge requests by default. | +| `auto_cancel_pending_pipelines` | string | **{dotted-circle}** No | Auto-cancel pending pipelines. This isn't a boolean, but enabled/disabled. | +| `auto_devops_deploy_strategy` | string | **{dotted-circle}** No | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`). | +| `auto_devops_enabled` | boolean | **{dotted-circle}** No | Enable Auto DevOps for this project. | +| `autoclose_referenced_issues` | boolean | **{dotted-circle}** No | Set whether auto-closing referenced issues on default branch. | +| `avatar` | mixed | **{dotted-circle}** No | Image file for avatar of the project. | +| `build_coverage_regex` | string | **{dotted-circle}** No | Test coverage parsing. | +| `build_git_strategy` | string | **{dotted-circle}** No | The Git strategy. Defaults to `fetch`. | +| `build_timeout` | integer | **{dotted-circle}** No | The maximum amount of time in minutes that a job is able run (in seconds). | +| `builds_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `ci_config_path` | string | **{dotted-circle}** No | The path to CI configuration file. | +| `container_expiration_policy_attributes` | hash | **{dotted-circle}** No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (string), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). | +| `container_registry_enabled` | boolean | **{dotted-circle}** No | Enable container registry for this project. | +| `default_branch` | string | **{dotted-circle}** No | `master` by default. | +| `description` | string | **{dotted-circle}** No | Short project description. | +| `emails_disabled` | boolean | **{dotted-circle}** No | Disable 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_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. | +| `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. | +| `jobs_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable jobs for this project. Use `builds_access_level` instead. | +| `lfs_enabled` | boolean | **{dotted-circle}** No | Enable LFS. | +| `merge_method` | string | **{dotted-circle}** No | Set the [merge method](#project-merge-method) used. | +| `merge_requests_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `merge_requests_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable merge requests for this project. Use `merge_requests_access_level` instead. | +| `mirror_trigger_builds` **(STARTER)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | +| `mirror` **(STARTER)** | boolean | **{dotted-circle}** No | Enables pull mirroring in a project. | +| `name` | string | **{check-circle}** Yes (if path isn't provided) | The name of the new project. Equals path if not provided. | +| `namespace_id` | integer | **{dotted-circle}** No | Namespace for the new project (defaults to the current user's namespace). | +| `only_allow_merge_if_all_discussions_are_resolved` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged when all the discussions are resolved. | +| `only_allow_merge_if_pipeline_succeeds` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged with successful jobs. | +| `packages_enabled` | boolean | **{dotted-circle}** No | Enable or disable packages repository feature. | +| `pages_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled`, or `public`. | +| `requirements_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled` or `public` | +| `path` | string | **{check-circle}** Yes (if name isn't provided) | Repository name for new project. Generated based on name if not provided (generated as lowercase with dashes). | +| `printing_merge_request_link_enabled` | boolean | **{dotted-circle}** No | Show link to create/view merge request when pushing from the command line. | +| `public_builds` | boolean | **{dotted-circle}** No | If `true`, jobs can be viewed by non-project members. | +| `remove_source_branch_after_merge` | boolean | **{dotted-circle}** No | Enable `Delete source branch` option by default for all new merge requests. | +| `repository_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(admins only)_ | +| `request_access_enabled` | boolean | **{dotted-circle}** No | Allow users to request member access. | +| `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | +| `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared 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. | +| `tag_list` | array | **{dotted-circle}** No | The list of tags for a project; put array of tags, that should be finally assigned to a project. | +| `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../gitlab-basics/create-project.md#built-in-templates). When used with `use_custom_template`, name of a custom project template. | +| `template_project_id` **(PREMIUM)** | integer | **{dotted-circle}** No | When used with `use_custom_template`, project ID of a custom project template. This is preferable to using `template_name` since `template_name` may be ambiguous. | +| `use_custom_template` **(PREMIUM)** | boolean | **{dotted-circle}** No | Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template. | +| `visibility` | string | **{dotted-circle}** No | See [project visibility level](#project-visibility-level). | +| `wiki_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `wiki_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable wiki for this project. Use `wiki_access_level` instead. | ## Create project for user Creates a new project owned by the specified user. Available only for admins. +If your HTTP repository isn't publicly accessible, add authentication information +to the URL `https://username:password@gitlab.company.com/group/project.git`, +where `password` is a public access key with the `api` scope enabled. + ```plaintext POST /projects/user/:user_id ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `user_id` | integer | yes | The user ID of the project owner | -| `name` | string | yes | The name of the new project | -| `path` | string | no | Custom repository name for new project. By default generated based on name | -| `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) | -| `description` | string | no | Short project description | -| `issues_enabled` | boolean | no | (deprecated) Enable issues for this project. Use `issues_access_level` instead | -| `merge_requests_enabled` | boolean | no | (deprecated) Enable merge requests for this project. Use `merge_requests_access_level` instead | -| `jobs_enabled` | boolean | no | (deprecated) Enable jobs for this project. Use `builds_access_level` instead | -| `wiki_enabled` | boolean | no | (deprecated) Enable wiki for this project. Use `wiki_access_level` instead | -| `snippets_enabled` | boolean | no | (deprecated) Enable snippets for this project. Use `snippets_access_level` instead | -| `issues_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `repository_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `merge_requests_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `forking_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `builds_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `wiki_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `snippets_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `pages_access_level` | string | no | One of `disabled`, `private`, `enabled` or `public` | -| `emails_disabled` | boolean | no | Disable email notifications | -| `show_default_award_emojis` | boolean | no | Show default award emojis | -| `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push | -| `container_registry_enabled` | boolean | no | Enable container registry for this project | -| `shared_runners_enabled` | boolean | no | Enable shared runners for this project | -| `visibility` | string | no | See [project visibility level](#project-visibility-level) | -| `import_url` | string | no | URL to import repository from | -| `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members | -| `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | -| `allow_merge_on_skipped_pipeline` | boolean | no | Set whether or not merge requests can be merged with skipped jobs | -| `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | -| `merge_method` | string | no | Set the [merge method](#project-merge-method) used | -| `autoclose_referenced_issues` | boolean | no | Set whether auto-closing referenced issues on default branch | -| `suggestion_commit_message` | string | no | The commit message used to apply merge request suggestions | -| `remove_source_branch_after_merge` | boolean | no | Enable `Delete source branch` option by default for all new merge requests | -| `lfs_enabled` | boolean | no | Enable LFS | -| `request_access_enabled` | boolean | no | Allow users to request member access | -| `tag_list` | array | no | The list of tags for a project; put array of tags, that should be finally assigned to a project | -| `avatar` | mixed | no | Image file for avatar of the project | -| `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line | -| `build_git_strategy` | string | no | The Git strategy. Defaults to `fetch` | -| `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) | -| `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled | -| `build_coverage_regex` | string | no | Test coverage parsing | -| `ci_config_path` | string | no | The path to CI configuration file | -| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project | -| `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) | -| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins | -| `approvals_before_merge` | integer | no | **(STARTER)** How many approvers should approve merge requests by default | -| `external_authorization_classification_label` | string | no | **(PREMIUM)** The classification label for the project | -| `mirror` | boolean | no | **(STARTER)** Enables pull mirroring in a project | -| `mirror_trigger_builds` | boolean | no | **(STARTER)** Pull mirroring triggers builds | -| `initialize_with_readme` | boolean | no | `false` by default | -| `template_name` | string | no | When used without `use_custom_template`, name of a [built-in project template](../gitlab-basics/create-project.md#built-in-templates). When used with `use_custom_template`, name of a custom project template | -| `use_custom_template` | boolean | no | **(PREMIUM)** Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template | -| `group_with_project_templates_id` | integer | no | **(PREMIUM)** 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 | -| `packages_enabled` | boolean | no | Enable or disable packages repository feature | - -NOTE: **Note:** -If your HTTP repository is not publicly accessible, -add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git` -where `password` is a public access key with the `api` scope enabled. +| Attribute | Type | Required | Description | +|-------------------------------------------------------------|---------|------------------------|-------------| +| `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | +| `approvals_before_merge` **(STARTER)** | integer | **{dotted-circle}** No | How many approvers should approve merge requests by default. | +| `auto_cancel_pending_pipelines` | string | **{dotted-circle}** No | Auto-cancel pending pipelines. This isn't a boolean, but enabled/disabled. | +| `auto_devops_deploy_strategy` | string | **{dotted-circle}** No | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`). | +| `auto_devops_enabled` | boolean | **{dotted-circle}** No | Enable Auto DevOps for this project. | +| `autoclose_referenced_issues` | boolean | **{dotted-circle}** No | Set whether auto-closing referenced issues on default branch. | +| `avatar` | mixed | **{dotted-circle}** No | Image file for avatar of the project. | +| `build_coverage_regex` | string | **{dotted-circle}** No | Test coverage parsing. | +| `build_git_strategy` | string | **{dotted-circle}** No | The Git strategy. Defaults to `fetch`. | +| `build_timeout` | integer | **{dotted-circle}** No | The maximum amount of time in minutes that a job is able run (in seconds). | +| `builds_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `ci_config_path` | string | **{dotted-circle}** No | The path to CI configuration file. | +| `container_registry_enabled` | boolean | **{dotted-circle}** No | Enable container registry for this project. | +| `description` | string | **{dotted-circle}** No | Short project description. | +| `emails_disabled` | boolean | **{dotted-circle}** No | Disable 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_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. | +| `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. | +| `jobs_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable jobs for this project. Use `builds_access_level` instead. | +| `lfs_enabled` | boolean | **{dotted-circle}** No | Enable LFS. | +| `merge_method` | string | **{dotted-circle}** No | Set the [merge method](#project-merge-method) used. | +| `merge_requests_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `merge_requests_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable merge requests for this project. Use `merge_requests_access_level` instead. | +| `mirror_trigger_builds` **(STARTER)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | +| `mirror` **(STARTER)** | boolean | **{dotted-circle}** No | Enables pull mirroring in a project. | +| `name` | string | **{check-circle}** Yes | The name of the new project. | +| `namespace_id` | integer | **{dotted-circle}** No | Namespace for the new project (defaults to the current user's namespace). | +| `only_allow_merge_if_all_discussions_are_resolved` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged when all the discussions are resolved. | +| `only_allow_merge_if_pipeline_succeeds` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged with successful jobs. | +| `packages_enabled` | boolean | **{dotted-circle}** No | Enable or disable packages repository feature. | +| `pages_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled`, or `public`. | +| `requirements_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled` or `public` | +| `path` | string | **{dotted-circle}** No | Custom repository name for new project. By default generated based on name. | +| `printing_merge_request_link_enabled` | boolean | **{dotted-circle}** No | Show link to create/view merge request when pushing from the command line. | +| `public_builds` | boolean | **{dotted-circle}** No | If `true`, jobs can be viewed by non-project-members. | +| `remove_source_branch_after_merge` | boolean | **{dotted-circle}** No | Enable `Delete source branch` option by default for all new merge requests. | +| `repository_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(admins only)_ | +| `request_access_enabled` | boolean | **{dotted-circle}** No | Allow users to request member access. | +| `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | +| `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared 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. | +| `suggestion_commit_message` | string | **{dotted-circle}** No | The commit message used to apply merge request suggestions. | +| `tag_list` | array | **{dotted-circle}** No | The list of tags for a project; put array of tags, that should be finally assigned to a project. | +| `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../gitlab-basics/create-project.md#built-in-templates). When used with `use_custom_template`, name of a custom project template. | +| `use_custom_template` **(PREMIUM)** | boolean | **{dotted-circle}** No | Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template. | +| `user_id` | integer | **{check-circle}** Yes | The user ID of the project owner. | +| `visibility` | string | **{dotted-circle}** No | See [project visibility level](#project-visibility-level). | +| `wiki_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `wiki_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable wiki for this project. Use `wiki_access_level` instead. | ## Edit project Updates an existing project. +If your HTTP repository isn't publicly accessible, add authentication information +to the URL `https://username:password@gitlab.company.com/group/project.git`, +where `password` is a public access key with the `api` scope enabled. + ```plaintext PUT /projects/:id ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `name` | string | no | The name of the project | -| `path` | string | no | Custom repository name for the project. By default generated based on name | -| `default_branch` | string | no | `master` by default | -| `description` | string | no | Short project description | -| `issues_enabled` | boolean | no | (deprecated) Enable issues for this project. Use `issues_access_level` instead | -| `merge_requests_enabled` | boolean | no | (deprecated) Enable merge requests for this project. Use `merge_requests_access_level` instead | -| `jobs_enabled` | boolean | no | (deprecated) Enable jobs for this project. Use `builds_access_level` instead | -| `wiki_enabled` | boolean | no | (deprecated) Enable wiki for this project. Use `wiki_access_level` instead | -| `snippets_enabled` | boolean | no | (deprecated) Enable snippets for this project. Use `snippets_access_level` instead | -| `issues_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `repository_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `merge_requests_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `forking_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `builds_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `wiki_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `snippets_access_level` | string | no | One of `disabled`, `private` or `enabled` | -| `pages_access_level` | string | no | One of `disabled`, `private`, `enabled` or `public` | -| `emails_disabled` | boolean | no | Disable email notifications | -| `show_default_award_emojis` | boolean | no | Show default award emojis | -| `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push | -| `container_registry_enabled` | boolean | no | Enable container registry for this project | -| `container_expiration_policy_attributes` | hash | no | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (string), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean) | -| `shared_runners_enabled` | boolean | no | Enable shared runners for this project | -| `visibility` | string | no | See [project visibility level](#project-visibility-level) | -| `import_url` | string | no | URL to import repository from | -| `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members | -| `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | -| `allow_merge_on_skipped_pipeline` | boolean | no | Set whether or not merge requests can be merged with skipped jobs | -| `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | -| `merge_method` | string | no | Set the [merge method](#project-merge-method) used | -| `autoclose_referenced_issues` | boolean | no | Set whether auto-closing referenced issues on default branch | -| `suggestion_commit_message` | string | no | The commit message used to apply merge request suggestions | -| `remove_source_branch_after_merge` | boolean | no | Enable `Delete source branch` option by default for all new merge requests | -| `lfs_enabled` | boolean | no | Enable LFS | -| `request_access_enabled` | boolean | no | Allow users to request member access | -| `tag_list` | array | no | The list of tags for a project; put array of tags, that should be finally assigned to a project | -| `avatar` | mixed | no | Image file for avatar of the project | -| `build_git_strategy` | string | no | The Git strategy. Defaults to `fetch` | -| `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) | -| `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled | -| `build_coverage_regex` | string | no | Test coverage parsing | -| `ci_config_path` | string | no | The path to CI configuration file | -| `ci_default_git_depth` | integer | no | Default number of revisions for [shallow cloning](../ci/pipelines/settings.md#git-shallow-clone) | -| `ci_forward_deployment_enabled` | boolean | no | When a new deployment job starts, [skip older deployment jobs](../ci/pipelines/settings.md#skip-outdated-deployment-jobs) that are still pending | -| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project | -| `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) | -| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins | -| `approvals_before_merge` | integer | no | **(STARTER)** How many approvers should approve merge request by default | -| `external_authorization_classification_label` | string | no | **(PREMIUM)** The classification label for the project | -| `mirror` | boolean | no | **(STARTER)** Enables pull mirroring in a project | -| `mirror_user_id` | integer | no | **(STARTER)** User responsible for all the activity surrounding a pull mirror event. Can only be set by admins. | -| `mirror_trigger_builds` | boolean | no | **(STARTER)** Pull mirroring triggers builds | -| `only_mirror_protected_branches` | boolean | no | **(STARTER)** Only mirror protected branches | -| `mirror_overwrites_diverged_branches` | boolean | no | **(STARTER)** Pull mirror overwrites diverged branches | -| `packages_enabled` | boolean | no | Enable or disable packages repository feature | -| `service_desk_enabled` | boolean | no | Enable or disable Service Desk feature | - -NOTE: **Note:** -If your HTTP repository is not publicly accessible, -add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git` -where `password` is a public access key with the `api` scope enabled. +| Attribute | Type | Required | Description | +|-------------------------------------------------------------|----------------|------------------------|-------------| +| `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | +| `approvals_before_merge` **(STARTER)** | integer | **{dotted-circle}** No | How many approvers should approve merge request by default. | +| `auto_cancel_pending_pipelines` | string | **{dotted-circle}** No | Auto-cancel pending pipelines. This isn't a boolean, but enabled/disabled. | +| `auto_devops_deploy_strategy` | string | **{dotted-circle}** No | Auto Deploy strategy (`continuous`, `manual`, or `timed_incremental`). | +| `auto_devops_enabled` | boolean | **{dotted-circle}** No | Enable Auto DevOps for this project. | +| `autoclose_referenced_issues` | boolean | **{dotted-circle}** No | Set whether auto-closing referenced issues on default branch. | +| `avatar` | mixed | **{dotted-circle}** No | Image file for avatar of the project. | +| `build_coverage_regex` | string | **{dotted-circle}** No | Test coverage parsing. | +| `build_git_strategy` | string | **{dotted-circle}** No | The Git strategy. Defaults to `fetch`. | +| `build_timeout` | integer | **{dotted-circle}** No | The maximum amount of time in minutes that a job is able run (in seconds). | +| `builds_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `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#git-shallow-clone). | +| `ci_forward_deployment_enabled` | boolean | **{dotted-circle}** No | When a new deployment job starts, [skip older deployment jobs](../ci/pipelines/settings.md#skip-outdated-deployment-jobs) that are still pending | +| `container_expiration_policy_attributes` | hash | **{dotted-circle}** No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (string), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). | +| `container_registry_enabled` | boolean | **{dotted-circle}** No | Enable container registry for this project. | +| `default_branch` | string | **{dotted-circle}** No | `master` by default. | +| `description` | string | **{dotted-circle}** No | Short project description. | +| `emails_disabled` | boolean | **{dotted-circle}** No | Disable 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`. | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `import_url` | string | **{dotted-circle}** No | URL to import repository 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. | +| `jobs_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable jobs for this project. Use `builds_access_level` instead. | +| `lfs_enabled` | boolean | **{dotted-circle}** No | Enable LFS. | +| `merge_method` | string | **{dotted-circle}** No | Set the [merge method](#project-merge-method) used. | +| `merge_requests_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `merge_requests_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable merge requests for this project. Use `merge_requests_access_level` instead. | +| `mirror_overwrites_diverged_branches` **(STARTER)** | boolean | **{dotted-circle}** No | Pull mirror overwrites diverged branches. | +| `mirror_trigger_builds` **(STARTER)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | +| `mirror_user_id` **(STARTER)** | integer | **{dotted-circle}** No | User responsible for all the activity surrounding a pull mirror event. _(admins only)_ | +| `mirror` **(STARTER)** | boolean | **{dotted-circle}** No | Enables pull mirroring in a project. | +| `name` | string | **{dotted-circle}** No | The name of the project. | +| `only_allow_merge_if_all_discussions_are_resolved` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged when all the discussions are resolved. | +| `only_allow_merge_if_pipeline_succeeds` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged with successful jobs. | +| `only_mirror_protected_branches` **(STARTER)** | boolean | **{dotted-circle}** No | Only mirror protected branches. | +| `packages_enabled` | boolean | **{dotted-circle}** No | Enable or disable packages repository feature. | +| `pages_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled`, or `public`. | +| `requirements_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled` or `public` | +| `path` | string | **{dotted-circle}** No | Custom repository name for the project. By default generated based on name. | +| `public_builds` | boolean | **{dotted-circle}** No | If `true`, jobs can be viewed by non-project members. | +| `remove_source_branch_after_merge` | boolean | **{dotted-circle}** No | Enable `Delete source branch` option by default for all new merge requests. | +| `repository_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(admins only)_ | +| `request_access_enabled` | boolean | **{dotted-circle}** No | Allow users to request member access. | +| `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | +| `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. | +| `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. | +| `suggestion_commit_message` | string | **{dotted-circle}** No | The commit message used to apply merge request suggestions. | +| `tag_list` | array | **{dotted-circle}** No | The list of tags for a project; put array of tags, that should be finally assigned to a project. | +| `visibility` | string | **{dotted-circle}** No | See [project visibility level](#project-visibility-level). | +| `wiki_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `wiki_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable wiki for this project. Use `wiki_access_level` instead. | ## Fork project @@ -1254,42 +1258,43 @@ fork of the project has completed, query the `import_status` for the new project POST /projects/:id/fork ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `namespace` | integer/string | no | (deprecated) The ID or path of the namespace that the project is forked to | -| `namespace_id` | integer | no | The ID of the namespace that the project is forked to | -| `namespace_path` | string | no | The path of the namespace that the project is forked to | -| `path` | string | no | The path assigned to the resultant project after forking | -| `name` | string | no | The name assigned to the resultant project after forking | +| Attribute | Type | Required | Description | +|------------------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `name` | string | **{dotted-circle}** No | The name assigned to the resultant project after forking. | +| `namespace_id` | integer | **{dotted-circle}** No | The ID of the namespace that the project is forked to. | +| `namespace_path` | string | **{dotted-circle}** No | The path of the namespace that the project is forked to. | +| `namespace` | integer/string | **{dotted-circle}** No | _(Deprecated)_ The ID or path of the namespace that the project is forked to. | +| `path` | string | **{dotted-circle}** No | The path assigned to the resultant project after forking. | ## List Forks of a project > Introduced in GitLab 10.1. -List the projects accessible to the calling user that have an established, forked relationship with the specified project +List the projects accessible to the calling user that have an established, +forked relationship with the specified project ```plaintext GET /projects/:id/forks ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `archived` | boolean | no | Limit by archived status | -| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | -| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | -| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | -| `search` | string | no | Return list of projects matching the search criteria | -| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | -| `owned` | boolean | no | Limit by projects explicitly owned by the current user | -| `membership` | boolean | no | Limit by projects that the current user is a member of | -| `starred` | boolean | no | Limit by projects starred by the current user | -| `statistics` | boolean | no | Include project statistics | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | -| `with_issues_enabled` | boolean | no | Limit by enabled issues feature | -| `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature | -| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md#valid-access-levels) | +| Attribute | Type | Required | Description | +|-------------------------------|----------------|------------------------|-------------| +| `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `membership` | boolean | **{dotted-circle}** No | Limit by projects that the current user is a member of. | +| `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [access level](members.md#valid-access-levels). | +| `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. | +| `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | +| `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | +| `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | +| `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | +| `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | +| `statistics` | boolean | **{dotted-circle}** No | Include project statistics. | +| `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | +| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | +| `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | +| `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/forks" @@ -1366,15 +1371,16 @@ Example responses: ## Star a project -Stars a given project. Returns status code `304` if the project is already starred. +Stars a given project. Returns status code `304` if the project is already +starred. ```plaintext POST /projects/:id/star ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/star" @@ -1463,9 +1469,9 @@ Unstars a given project. Returns status code `304` if the project is not starred POST /projects/:id/unstar ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unstar" @@ -1554,10 +1560,10 @@ List the users who starred the specified project. GET /projects/:id/starrers ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `search` | string | no | Search for specific users. | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `search` | string | **{dotted-circle}** No | Search for specific users. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/starrers" @@ -1600,9 +1606,9 @@ Get languages used in a project with percentage value. GET /projects/:id/languages ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/languages" @@ -1621,16 +1627,17 @@ Example response: ## Archive a project -Archives the project if the user is either an administrator or the owner of this project. This action is -idempotent, thus archiving an already archived project does not change the project. +Archives the project if the user is either an administrator or the owner of this +project. This action is idempotent, thus archiving an already archived project +does not change the project. ```plaintext POST /projects/:id/archive ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/archive" @@ -1732,16 +1739,17 @@ Example response: ## Unarchive a project -Unarchives the project if the user is either an administrator or the owner of this project. This action is -idempotent, thus unarchiving a non-archived project does not change the project. +Unarchives the project if the user is either an administrator or the owner of +this project. This action is idempotent, thus unarchiving a non-archived project +doesn't change the project. ```plaintext POST /projects/:id/unarchive ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unarchive" @@ -1845,25 +1853,27 @@ Example response: This endpoint: -- Deletes a project including all associated resources (issues, merge requests etc). -- From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, -group admins can [configure](../user/group/index.md#enabling-delayed-project-removal) projects within a group -to be deleted after a delayed period. -When enabled, actual deletion happens after the number of days -specified in the [default deletion delay](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +- Deletes a project including all associated resources (including issues and + merge requests). +- From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on + [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, group + admins can [configure](../user/group/index.md#enabling-delayed-project-removal) + projects within a group to be deleted after a delayed period. When enabled, + actual deletion happens after the number of days specified in the + [default deletion delay](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). CAUTION: **Warning:** -The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 -was changed to [Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) +The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) +in GitLab 12.6 was changed to [Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2, as discussed in [Enabling delayed project removal](../user/group/index.md#enabling-delayed-project-removal). ```plaintext DELETE /projects/:id ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ## Restore project marked for deletion **(PREMIUM)** @@ -1875,27 +1885,28 @@ Restores project marked for deletion. POST /projects/:id/restore ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ## Upload a file -Uploads a file to the specified project to be used in an issue or merge request description, or a comment. +Uploads a file to the specified project to be used in an issue or merge request +description, or a comment. ```plaintext POST /projects/:id/uploads ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `file` | string | yes | The file to be uploaded | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `file` | string | **{check-circle}** Yes | The file to be uploaded. | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | To upload a file from your file system, use the `--form` argument. This causes -cURL to post data using the header `Content-Type: multipart/form-data`. -The `file=` parameter must point to a file on your file system and be preceded -by `@`. For example: +cURL to post data using the header `Content-Type: multipart/form-data`. The +`file=` parameter must point to a file on your file system and be preceded by +`@`. For example: ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "file=@dk.png" "https://gitlab.example.com/api/v4/projects/5/uploads" @@ -1912,9 +1923,41 @@ Returned object: } ``` ->**Note**: The returned `url` is relative to the project path. The returned `full_path` is the absolute path to the file. -In Markdown contexts, the link is automatically expanded when the format in -`markdown` is used. +The returned `url` is relative to the project path. The returned `full_path` is +the absolute path to the file. In Markdown contexts, the link is expanded when +the format in `markdown` is used. + +## Upload a project avatar + +Uploads an avatar to the specified project. + +```plaintext +PUT /projects/:id +``` + +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `avatar` | string | **{check-circle}** Yes | The file to be uploaded. | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | + +To upload an avatar from your file system, use the `--form` argument. This causes +cURL to post data using the header `Content-Type: multipart/form-data`. The +`file=` parameter must point to an image file on your file system and be +preceded by `@`. For example: + +Example request: + +```shell +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "avatar=@dk.png" "https://gitlab.example.com/api/v4/projects/5" +``` + +Returned object: + +```json +{ + "avatar_url": "https://gitlab.example.com/uploads/-/system/project/avatar/2/dk.png" +} +``` ## Share project with group @@ -1924,12 +1967,12 @@ Allow to share project with group. POST /projects/:id/share ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 | -| `group_access` | integer | yes | The [access level](members.md#valid-access-levels) to grant the group | -| `group_id` | integer | yes | The ID of the group to share with | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|----------------|----------------|------------------------|-------------| +| `expires_at` | string | **{dotted-circle}** No | Share expiration date in ISO 8601 format: 2016-09-26 | +| `group_access` | integer | **{check-circle}** Yes | The [access level](members.md#valid-access-levels) to grant the group. | +| `group_id` | integer | **{check-circle}** Yes | The ID of the group to share with. | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ## Delete a shared project link within a group @@ -1939,10 +1982,10 @@ Unshare the project from the group. Returns `204` and no content on success. DELETE /projects/:id/share/:group_id ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `group_id` | integer | yes | The ID of the group | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|------------|----------------|------------------------|-------------| +| `group_id` | integer | **{check-circle}** Yes | The ID of the group. | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17" @@ -1950,8 +1993,8 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git ## Hooks -Also called Project Hooks and Webhooks. -These are different for [System Hooks](system_hooks.md) that are system wide. +Also called Project Hooks and Webhooks. These are different for [System Hooks](system_hooks.md) +that are system-wide. ### List project hooks @@ -1961,9 +2004,9 @@ Get a list of project hooks. GET /projects/:id/hooks ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ### Get project hook @@ -1973,10 +2016,10 @@ Get a specific hook for a project. GET /projects/:id/hooks/:hook_id ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `hook_id` | integer | yes | The ID of a project hook | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|---------------------------| +| `hook_id` | integer | **{check-circle}** Yes | The ID of a project hook. | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```json { @@ -1995,6 +2038,7 @@ GET /projects/:id/hooks/:hook_id "pipeline_events": true, "wiki_page_events": true, "deployment_events": true, + "releases_events": true, "enable_ssl_verification": true, "created_at": "2012-10-12T17:04:47Z" } @@ -2008,24 +2052,24 @@ Adds a hook to a specified project. POST /projects/:id/hooks ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events | -| `confidential_note_events` | boolean | no | Trigger hook on confidential note events | -| `deployment_events` | boolean | no | Trigger hook on deployment events | -| `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `issues_events` | boolean | no | Trigger hook on issues events | -| `job_events` | boolean | no | Trigger hook on job events | -| `merge_requests_events` | boolean | no | Trigger hook on merge requests events | -| `note_events` | boolean | no | Trigger hook on note events | -| `pipeline_events` | boolean | no | Trigger hook on pipeline events | -| `push_events_branch_filter` | string | no | Trigger hook on push events for matching branches only | -| `push_events` | boolean | no | Trigger hook on push events | -| `tag_push_events` | boolean | no | Trigger hook on tag push events | -| `token` | string | no | Secret token to validate received payloads; this is not returned in the response | -| `url` | string | yes | The hook URL | -| `wiki_page_events` | boolean | no | Trigger hook on wiki events | +| Attribute | Type | Required | Description | +|------------------------------|----------------|------------------------|-------------| +| `confidential_issues_events` | boolean | **{dotted-circle}** No | Trigger hook on confidential issues events. | +| `confidential_note_events` | boolean | **{dotted-circle}** No | Trigger hook on confidential note events. | +| `deployment_events` | boolean | **{dotted-circle}** No | Trigger hook on deployment events. | +| `enable_ssl_verification` | boolean | **{dotted-circle}** No | Do SSL verification when triggering the hook. | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `issues_events` | boolean | **{dotted-circle}** No | Trigger hook on issues events. | +| `job_events` | boolean | **{dotted-circle}** No | Trigger hook on job events. | +| `merge_requests_events` | boolean | **{dotted-circle}** No | Trigger hook on merge requests events. | +| `note_events` | boolean | **{dotted-circle}** No | Trigger hook on note events. | +| `pipeline_events` | boolean | **{dotted-circle}** No | Trigger hook on pipeline events. | +| `push_events_branch_filter` | string | **{dotted-circle}** No | Trigger hook on push events for matching branches only. | +| `push_events` | boolean | **{dotted-circle}** No | Trigger hook on push events. | +| `tag_push_events` | boolean | **{dotted-circle}** No | Trigger hook on tag push events. | +| `token` | string | **{dotted-circle}** No | Secret token to validate received payloads; this isn't returned in the response. | +| `url` | string | **{check-circle}** Yes | The hook URL. | +| `wiki_page_events` | boolean | **{dotted-circle}** No | Trigger hook on wiki events. | ### Edit project hook @@ -2035,46 +2079,49 @@ Edits a hook for a specified project. PUT /projects/:id/hooks/:hook_id ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events | -| `confidential_note_events` | boolean | no | Trigger hook on confidential note events | -| `deployment_events` | boolean | no | Trigger hook on deployment events | -| `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | -| `hook_id` | integer | yes | The ID of the project hook | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `issues_events` | boolean | no | Trigger hook on issues events | -| `job_events` | boolean | no | Trigger hook on job events | -| `merge_requests_events` | boolean | no | Trigger hook on merge requests events | -| `note_events` | boolean | no | Trigger hook on note events | -| `pipeline_events` | boolean | no | Trigger hook on pipeline events | -| `push_events_branch_filter` | string | no | Trigger hook on push events for matching branches only | -| `push_events` | boolean | no | Trigger hook on push events | -| `tag_push_events` | boolean | no | Trigger hook on tag push events | -| `token` | string | no | Secret token to validate received payloads; this is not returned in the response | -| `url` | string | yes | The hook URL | -| `wiki_events` | boolean | no | Trigger hook on wiki events | +| Attribute | Type | Required | Description | +|------------------------------|----------------|------------------------|-------------| +| `confidential_issues_events` | boolean | **{dotted-circle}** No | Trigger hook on confidential issues events. | +| `confidential_note_events` | boolean | **{dotted-circle}** No | Trigger hook on confidential note events. | +| `deployment_events` | boolean | **{dotted-circle}** No | Trigger hook on deployment events. | +| `enable_ssl_verification` | boolean | **{dotted-circle}** No | Do SSL verification when triggering the hook. | +| `hook_id` | integer | **{check-circle}** Yes | The ID of the project hook. | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `issues_events` | boolean | **{dotted-circle}** No | Trigger hook on issues events. | +| `job_events` | boolean | **{dotted-circle}** No | Trigger hook on job events. | +| `merge_requests_events` | boolean | **{dotted-circle}** No | Trigger hook on merge requests events. | +| `note_events` | boolean | **{dotted-circle}** No | Trigger hook on note events. | +| `pipeline_events` | boolean | **{dotted-circle}** No | Trigger hook on pipeline events. | +| `push_events_branch_filter` | string | **{dotted-circle}** No | Trigger hook on push events for matching branches only. | +| `push_events` | boolean | **{dotted-circle}** No | Trigger hook on push events. | +| `tag_push_events` | boolean | **{dotted-circle}** No | Trigger hook on tag push events. | +| `token` | string | **{dotted-circle}** No | Secret token to validate received payloads; this isn't returned in the response. | +| `url` | string | **{check-circle}** Yes | The hook URL. | +| `wiki_events` | boolean | **{dotted-circle}** No | Trigger hook on wiki events. | +| `releases_events` | boolean | **{dotted-circle}** No | Trigger hook on release events. | ### Delete project hook -Removes a hook from a project. This is an idempotent method and can be called multiple times. -Either the hook is available or not. +Removes a hook from a project. This is an idempotent method and can be called +multiple times. Either the hook is available or not. ```plaintext DELETE /projects/:id/hooks/:hook_id ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `hook_id` | integer | yes | The ID of the project hook | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `hook_id` | integer | **{check-circle}** Yes | The ID of the project hook. | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -Note the JSON response differs if the hook is available or not. If the project hook -is available before it's returned in the JSON response or an empty response is returned. +Note the JSON response differs if the hook is available or not. If the project +hook is available before it's returned in the JSON response or an empty response +is returned. ## Fork relationship -Allows modification of the forked relationship between existing projects. Available only for project owners and admins. +Allows modification of the forked relationship between existing projects. +Available only for project owners and admins. ### Create a forked from/to relation between existing projects @@ -2082,10 +2129,10 @@ Allows modification of the forked relationship between existing projects. Availa POST /projects/:id/fork/:forked_from_id ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `forked_from_id` | ID | yes | The ID of the project that was forked from | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|------------------|----------------|------------------------|-------------| +| `forked_from_id` | ID | **{check-circle}** Yes | The ID of the project that was forked from. | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ### Delete an existing forked from relationship @@ -2093,9 +2140,9 @@ POST /projects/:id/fork/:forked_from_id DELETE /projects/:id/fork ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ## Search for projects by name @@ -2107,11 +2154,11 @@ accessible. GET /projects ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `order_by` | string | no | Return requests ordered by `id`, `name`, `created_at` or `last_activity_at` fields | -| `search` | string | yes | A string contained in the project name | -| `sort` | string | no | Return requests sorted in `asc` or `desc` order | +| Attribute | Type | Required | Description | +|------------|--------|------------------------|-------------| +| `order_by` | string | **{dotted-circle}** No | Return requests ordered by `id`, `name`, `created_at` or `last_activity_at` fields. | +| `search` | string | **{check-circle}** Yes | A string contained in the project name. | +| `sort` | string | **{dotted-circle}** No | Return requests sorted in `asc` or `desc` order. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?search=test" @@ -2125,23 +2172,24 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a POST /projects/:id/housekeeping ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID of the project or NAMESPACE/PROJECT_NAME. | ## Push Rules **(STARTER)** ### Get project push rules -Get the [push rules](../push_rules/push_rules.md#enabling-push-rules) of a project. +Get the [push rules](../push_rules/push_rules.md#enabling-push-rules) of a +project. ```plaintext GET /projects/:id/push_rule ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID of the project or NAMESPACE/PROJECT_NAME. | ```json { @@ -2162,8 +2210,9 @@ GET /projects/:id/push_rule } ``` -Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) can also see -the `commit_committer_check` and `reject_unsigned_commits` parameters: +Users of GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) +can also see the `commit_committer_check` and `reject_unsigned_commits` +parameters: ```json { @@ -2183,20 +2232,20 @@ Adds a push rule to a specified project. POST /projects/:id/push_rule ``` -| Attribute | Type | Required | Description | -| --------------------------------------------- | -------------- | -------- | ----------- | -| `author_email_regex` **(STARTER)** | string | no | All commit author emails must match this, for example `@my-company.com$` | -| `branch_name_regex` **(STARTER)** | string | no | All branch names must match this, for example `(feature|hotfix)\/*` | -| `commit_committer_check` **(PREMIUM)** | boolean | no | Users can only push commits to this repository that were committed with one of their own verified emails. | -| `commit_message_negative_regex` **(STARTER)** | string | no | No commit message is allowed to match this, for example `ssh\:\/\/` | -| `commit_message_regex` **(STARTER)** | string | no | All commit messages must match this, for example `Fixed \d+\..*` | -| `deny_delete_tag` **(STARTER)** | boolean | no | Deny deleting a tag | -| `file_name_regex` **(STARTER)** | string | no | All committed filenames must **not** match this, for example `(jar|exe)$` | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | -| `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) | -| `member_check` **(STARTER)** | boolean | no | Restrict commits by author (email) to existing GitLab users | -| `prevent_secrets` **(STARTER)** | boolean | no | GitLab will reject any files that are likely to contain secrets | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Reject commit when it's not signed through GPG. | +| Attribute | Type | Required | Description | +|-----------------------------------------------|----------------|------------------------|-------------| +| `author_email_regex` **(STARTER)** | string | **{dotted-circle}** No | All commit author emails must match this, for example `@my-company.com$`. | +| `branch_name_regex` **(STARTER)** | string | **{dotted-circle}** No | All branch names must match this, for example `(feature|hotfix)\/*`. | +| `commit_committer_check` **(PREMIUM)** | boolean | **{dotted-circle}** No | Users can only push commits to this repository that were committed with one of their own verified emails. | +| `commit_message_negative_regex` **(STARTER)** | string | **{dotted-circle}** No | No commit message is allowed to match this, for example `ssh\:\/\/`. | +| `commit_message_regex` **(STARTER)** | string | **{dotted-circle}** No | All commit messages must match this, for example `Fixed \d+\..*`. | +| `deny_delete_tag` **(STARTER)** | boolean | **{dotted-circle}** No | Deny deleting a tag. | +| `file_name_regex` **(STARTER)** | string | **{dotted-circle}** No | All committed filenames must **not** match this, for example `(jar|exe)$`. | +| `id` | integer/string | **{check-circle}** Yes | The ID of the project or NAMESPACE/PROJECT_NAME. | +| `max_file_size` **(STARTER)** | integer | **{dotted-circle}** No | Maximum file size (MB). | +| `member_check` **(STARTER)** | boolean | **{dotted-circle}** No | Restrict commits by author (email) to existing GitLab users. | +| `prevent_secrets` **(STARTER)** | boolean | **{dotted-circle}** No | GitLab will reject any files that are likely to contain secrets. | +| `reject_unsigned_commits` **(PREMIUM)** | boolean | **{dotted-circle}** No | Reject commit when it's not signed through GPG. | ### Edit project push rule @@ -2206,35 +2255,35 @@ Edits a push rule for a specified project. PUT /projects/:id/push_rule ``` -| Attribute | Type | Required | Description | -| --------------------------------------------- | -------------- | -------- | ----------- | -| `author_email_regex` **(STARTER)** | string | no | All commit author emails must match this, for example `@my-company.com$` | -| `branch_name_regex` **(STARTER)** | string | no | All branch names must match this, for example `(feature|hotfix)\/*` | -| `commit_committer_check` **(PREMIUM)** | boolean | no | Users can only push commits to this repository that were committed with one of their own verified emails. | -| `commit_message_negative_regex` **(STARTER)** | string | no | No commit message is allowed to match this, for example `ssh\:\/\/` | -| `commit_message_regex` **(STARTER)** | string | no | All commit messages must match this, for example `Fixed \d+\..*` | -| `deny_delete_tag` **(STARTER)** | boolean | no | Deny deleting a tag | -| `file_name_regex` **(STARTER)** | string | no | All committed filenames must **not** match this, for example `(jar|exe)$` | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | -| `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) | -| `member_check` **(STARTER)** | boolean | no | Restrict commits by author (email) to existing GitLab users | -| `prevent_secrets` **(STARTER)** | boolean | no | GitLab will reject any files that are likely to contain secrets | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Reject commits when they are not GPG signed. | +| Attribute | Type | Required | Description | +|-----------------------------------------------|----------------|------------------------|-------------| +| `author_email_regex` **(STARTER)** | string | **{dotted-circle}** No | All commit author emails must match this, for example `@my-company.com$`. | +| `branch_name_regex` **(STARTER)** | string | **{dotted-circle}** No | All branch names must match this, for example `(feature|hotfix)\/*`. | +| `commit_committer_check` **(PREMIUM)** | boolean | **{dotted-circle}** No | Users can only push commits to this repository that were committed with one of their own verified emails. | +| `commit_message_negative_regex` **(STARTER)** | string | **{dotted-circle}** No | No commit message is allowed to match this, for example `ssh\:\/\/`. | +| `commit_message_regex` **(STARTER)** | string | **{dotted-circle}** No | All commit messages must match this, for example `Fixed \d+\..*`. | +| `deny_delete_tag` **(STARTER)** | boolean | **{dotted-circle}** No | Deny deleting a tag. | +| `file_name_regex` **(STARTER)** | string | **{dotted-circle}** No | All committed filenames must **not** match this, for example `(jar|exe)$`. | +| `id` | integer/string | **{check-circle}** Yes | The ID of the project or NAMESPACE/PROJECT_NAME. | +| `max_file_size` **(STARTER)** | integer | **{dotted-circle}** No | Maximum file size (MB). | +| `member_check` **(STARTER)** | boolean | **{dotted-circle}** No | Restrict commits by author (email) to existing GitLab users. | +| `prevent_secrets` **(STARTER)** | boolean | **{dotted-circle}** No | GitLab will reject any files that are likely to contain secrets. | +| `reject_unsigned_commits` **(PREMIUM)** | boolean | **{dotted-circle}** No | Reject commits when they are not GPG signed. | ### Delete project push rule > Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 9.0. -Removes a push rule from a project. This is an idempotent method and can be called multiple times. -Either the push rule is available or not. +Removes a push rule from a project. This is an idempotent method and can be +called multiple times. Either the push rule is available or not. ```plaintext DELETE /projects/:id/push_rule ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ## Transfer a project to a new namespace @@ -2244,10 +2293,10 @@ DELETE /projects/:id/push_rule PUT /projects/:id/transfer ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `namespace` | integer/string | yes | The ID or path of the namespace to transfer to project to | +| Attribute | Type | Required | Description | +|-------------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `namespace` | integer/string | **{check-circle}** Yes | The ID or path of the namespace to transfer to project to. | Example request: @@ -2376,9 +2425,9 @@ Read more in the [Project members](members.md) documentation. POST /projects/:id/mirror/pull ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/mirror/pull" @@ -2390,7 +2439,9 @@ Read more in the [Project Badges](project_badges.md) documentation. ## Issue and merge request description templates -The non-default [issue and merge request description templates](../user/project/description_templates.md) are managed inside the project's repository. So you can manage them via the API through the [Repositories API](repositories.md) and the [Repository Files API](repository_files.md). +The non-default [issue and merge request description templates](../user/project/description_templates.md) +are managed inside the project's repository. So you can manage them with the API +through the [Repositories API](repositories.md) and the [Repository Files API](repository_files.md). ## Download snapshot of a Git repository @@ -2402,14 +2453,14 @@ Download a snapshot of the project (or wiki, if requested) Git repository. This snapshot is always in uncompressed [tar](https://en.wikipedia.org/wiki/Tar_(computing)) format. -If a repository is corrupted to the point where `git clone` does not work, the +If a repository is corrupted to the point where `git clone` doesn't work, the snapshot may allow some of the data to be retrieved. ```plaintext GET /projects/:id/snapshot ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `wiki` | boolean | no | Whether to download the wiki, rather than project, repository | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `wiki` | boolean | **{dotted-circle}** No | Whether to download the wiki, rather than project, repository. | diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index 56b399cec9b..c42d6776341 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -96,7 +96,7 @@ POST /projects/:id/protected_environments ``` ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_environments?name=staging&deploy_access_levels%5B%5D%5Buser_id%5D=1" +curl --header 'Content-Type: application/json' --request POST --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}]}' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/22034114/protected_environments" ``` | Attribute | Type | Required | Description | @@ -105,21 +105,22 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla | `name` | string | yes | The name of the environment. | | `deploy_access_levels` | array | yes | Array of access levels allowed to deploy, with each described by a hash. | -Elements in the `deploy_access_levels` array should take the -form `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}`. +Elements in the `deploy_access_levels` array should be one of `user_id`, `group_id` or +`access_level`, and 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). Example response: ```json { - "name":"staging", + "name":"production", "deploy_access_levels":[ { - "access_level":null, - "access_level_description":"Administrator", - "user_id":1, - "group_id":null + "access_level":40, + "access_level_description":"protected-access-group", + "user_id":null, + "group_id":9899826 } ] } diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index 4dac9f61469..7c65e9da74b 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -228,7 +228,7 @@ GET /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | -| `tag_name` | string | yes | The tag where the release will be created from. | +| `tag_name` | string | yes | The Git tag the release is associated with. | Example request: @@ -367,7 +367,7 @@ POST /projects/:id/releases | `assets:links` | array of hash | no | An array of assets links. | | `assets:links:name`| string | required by: `assets:links` | The name of the link. | | `assets:links:url` | string | required by: `assets:links` | The URL of the link. | -| `assets:links:filepath` | string | no | Optional path for a [Direct Asset link](../../user/project/releases/index.md). +| `assets:links:filepath` | string | no | Optional path for a [Direct Asset link](../../user/project/releases/index.md#permanent-links-to-release-assets). | `assets:links:link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. | `released_at` | datetime | no | The date when the release will be/was ready. Defaults to the current time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | @@ -508,7 +508,7 @@ POST /projects/:id/releases/:tag_name/evidence | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | -| `tag_name` | string | yes | The tag where the release will be created from. | +| `tag_name` | string | yes | The Git tag the release is associated with. | Example request: @@ -533,7 +533,7 @@ PUT /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | | ------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | -| `tag_name` | string | yes | The tag where the release will be created from. | +| `tag_name` | string | yes | The Git tag the release is associated with. | | `name` | string | no | The release name. | | `description` | string | no | The description of the release. You can use [Markdown](../../user/markdown.md). | | `milestones` | array of string | no | The title of each milestone to associate with the release. [GitLab Premium](https://about.gitlab.com/pricing/) customers can specify group milestones. To remove all milestones from the release, specify `[]`. | @@ -584,7 +584,7 @@ Example response: "id":53, "iid":3, "project_id":24, - "title":"v1.0", + "title":"v1.2", "description":"Voluptate fugiat possimus quis quod aliquam expedita.", "state":"active", "created_at":"2019-09-01T13:00:00.256Z", @@ -640,7 +640,7 @@ DELETE /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | -| `tag_name` | string | yes | The tag where the release will be created from. | +| `tag_name` | string | yes | The Git tag the release is associated with. | Example request: diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md index 242b5eb41f5..2b33f6a4dc7 100644 --- a/doc/api/releases/links.md +++ b/doc/api/releases/links.md @@ -97,26 +97,29 @@ POST /projects/:id/releases/:tag_name/assets/links | `tag_name` | string | yes | The tag associated with the Release. | | `name` | string | yes | The name of the link. | | `url` | string | yes | The URL of the link. | +| `filepath` | string | no | Optional path for a [Direct Asset link](../../user/project/releases/index.md#permanent-links-to-release-assets). | `link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. | Example request: ```shell curl --request POST \ - --header "PRIVATE-TOKEN: n671WNGecHugsdEDPsyo" \ - --data name="awesome-v0.2.dmg" \ - --data url="http://192.168.10.15:3000" \ - "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links" + --header "PRIVATE-TOKEN: tkhfG7HgG-LiZd3zfdDC" \ + --data name="hellodarwin-amd64" \ + --data url="https://gitlab.example.com/mynamespace/hello/-/jobs/688/artifacts/raw/bin/hello-darwin-amd64" \ + --data filepath="/bin/hellodarwin-amd64" \ + "https://gitlab.example.com/api/v4/projects/20/releases/v1.7.0/assets/links" ``` Example response: ```json { - "id":1, - "name":"awesome-v0.2.dmg", - "url":"http://192.168.10.15:3000", - "external":true, + "id":2, + "name":"hellodarwin-amd64", + "url":"https://gitlab.example.com/mynamespace/hello/-/jobs/688/artifacts/raw/bin/hello-darwin-amd64", + "direct_asset_url":"https://gitlab.example.com/mynamespace/hello/-/releases/v1.7.0/downloads/bin/hellodarwin-amd64", + "external":false, "link_type":"other" } ``` @@ -136,6 +139,7 @@ PUT /projects/:id/releases/:tag_name/assets/links/:link_id | `link_id` | integer | yes | The ID of the link. | | `name` | string | no | The name of the link. | | `url` | string | no | The URL of the link. | +| `filepath` | string | no | Optional path for a [Direct Asset link](../../user/project/releases/index.md#permanent-links-to-release-assets). | `link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. | NOTE: **Note:** diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md index 275614a1449..b088c06b342 100644 --- a/doc/api/resource_label_events.md +++ b/doc/api/resource_label_events.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Resource label events API Resource label events keep track about who, when, and which label was added to, or removed from, an issuable. diff --git a/doc/api/scim.md b/doc/api/scim.md index 350f992779e..653d56f3e06 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -1,19 +1,23 @@ -# SCIM API **(SILVER ONLY)** +--- +type: reference, howto +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in [GitLab Silver](https://about.gitlab.com/pricing/) 11.10. +# SCIM API (SYSTEM ONLY) **(SILVER ONLY)** -The SCIM API implements the [RFC7644 protocol](https://tools.ietf.org/html/rfc7644). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.10. -CAUTION: **Caution:** -This API is for internal system use for connecting with a SCIM provider. While it can be used directly, it is subject to change without notice. +The SCIM API implements the [RFC7644 protocol](https://tools.ietf.org/html/rfc7644). As this API is for +**system** use for SCIM provider integration, it is subject to change without notice. -NOTE: **Note:** -[Group SSO](../user/group/saml_sso/index.md) must be enabled for the group. For more information, see [SCIM setup documentation](../user/group/saml_sso/scim_setup.md#requirements). +To use this API, [Group SSO](../user/group/saml_sso/index.md) must be enabled for the group. +This API is only in use where [SCIM for Group SSO](../user/group/saml_sso/scim_setup.md) is enabled. It's a prerequisite to the creation of SCIM identities. ## Get a list of SAML users -NOTE: **Note:** -This endpoint is used as part of the SCIM syncing mechanism and it only returns +This endpoint is used as part of the SCIM syncing mechanism. It only returns a single user based on a unique ID which should match the `extern_uid` of the user. ```plaintext diff --git a/doc/api/search.md b/doc/api/search.md index bdf5bdd4924..8de93ce0d32 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -7,7 +7,8 @@ type: reference, api # Search API -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41763) in GitLab 10.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41763) in GitLab 10.5. +> - [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. @@ -24,7 +25,9 @@ GET /search | `scope` | string | yes | The scope to search in | | `search` | string | yes | The search query | | `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | -| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. This parameter is behind a [feature flag (`search_filter_by_confidential`)](../administration/feature_flags.md). | +| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. | +| `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results will either be sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| +| `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results will either be sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, snippet_titles, users. @@ -434,7 +437,9 @@ GET /groups/:id/search | `scope` | string | yes | The scope to search in | | `search` | string | yes | The search query | | `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | -| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. This parameter is behind a [feature flag (`search_filter_by_confidential`)](../administration/feature_flags.md). | +| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. | +| `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results will either be sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| +| `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results will either be sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, users. @@ -814,7 +819,9 @@ GET /projects/:id/search | `search` | string | yes | The search query | | `ref` | string | no | The name of a repository branch or tag to search on. The project's default branch is used by default. This is only applicable for scopes: commits, blobs, and wiki_blobs. | | `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | -| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. This parameter is behind a [feature flag (`search_filter_by_confidential`)](../administration/feature_flags.md). | +| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. | +| `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results will either be sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| +| `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results will either be sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| Search the expression within the specified scope. Currently these scopes are supported: issues, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users. diff --git a/doc/api/services.md b/doc/api/services.md index 7c01e43a4d8..a60eacef1d8 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Services API NOTE: **Note:** @@ -305,7 +311,7 @@ Parameters: | --------- | ---- | -------- | ----------- | | `webhook` | string | true | The Unify Circuit webhook. For example, `https://circuit.com/rest/v2/webhooks/incoming/...`. | | `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | -| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" | +| `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" | | `push_events` | boolean | false | Enable notifications for push events | | `issues_events` | boolean | false | Enable notifications for issue events | | `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | @@ -350,7 +356,7 @@ Parameters: | --------- | ---- | -------- | ----------- | | `webhook` | string | true | The Webex Teams webhook. For example, `https://api.ciscospark.com/v1/webhooks/incoming/...`. | | `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | -| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" | +| `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" | | `push_events` | boolean | false | Enable notifications for push events | | `issues_events` | boolean | false | Enable notifications for issue events | | `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | @@ -476,7 +482,7 @@ Parameters: | `send_from_committer_email` | boolean | false | Send from committer | | `push_events` | boolean | false | Enable notifications for push events | | `tag_push_events` | boolean | false | Enable notifications for tag push events | -| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". Notifications will be always fired for tag pushes. | +| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". Notifications will be always fired for tag pushes. The default value is "all" | ### Delete Emails on push service @@ -659,7 +665,7 @@ Parameters: | `webhook` | string | true | The Hangouts Chat webhook. For example, `https://chat.googleapis.com/v1/spaces...`. | | `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | | `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` | -| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" | +| `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" | | `push_events` | boolean | false | Enable notifications for push events | | `issues_events` | boolean | false | Enable notifications for issue events | | `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | @@ -972,7 +978,7 @@ Parameters: | `recipients` | string | yes | Comma-separated list of recipient email addresses | | `add_pusher` | boolean | no | Add pusher to recipients list | | `notify_only_broken_pipelines` | boolean | no | Notify only broken pipelines | -| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" | +| `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" | | `notify_only_default_branch` | boolean | no | Send notifications only for the default branch ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28271)) | | `pipeline_events` | boolean | false | Enable notifications for pipeline events | @@ -1165,7 +1171,7 @@ Parameters: | `channel` | string | false | Default channel to use if others are not configured | | `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | | `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` | -| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" | +| `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" | | `commit_events` | boolean | false | Enable notifications for commit events | | `confidential_issue_channel` | string | false | The name of the channel to receive confidential issues events notifications | | `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | @@ -1224,7 +1230,7 @@ Parameters: | `webhook` | string | true | The Microsoft Teams webhook. For example, `https://outlook.office.com/webhook/...` | | `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | | `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` | -| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" | +| `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" | | `push_events` | boolean | false | Enable notifications for push events | | `issues_events` | boolean | false | Enable notifications for issue events | | `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | @@ -1275,7 +1281,7 @@ Parameters: | `channel` | string | false | Default channel to use if others are not configured | | `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | | `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` | -| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" | +| `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" | | `push_events` | boolean | false | Enable notifications for push events | | `issues_events` | boolean | false | Enable notifications for issue events | | `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | diff --git a/doc/api/settings.md b/doc/api/settings.md index 236cd10a30e..5b04ee9d368 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Application settings API **(CORE ONLY)** These API calls allow you to read and modify GitLab instance @@ -37,9 +43,9 @@ Example response: "home_page_url" : null, "default_snippet_visibility" : "private", "outbound_local_requests_whitelist": [], - "domain_whitelist" : [], - "domain_blacklist_enabled" : false, - "domain_blacklist" : [], + "domain_allowlist" : [], + "domain_denylist_enabled" : false, + "domain_denylist" : [], "created_at" : "2016-01-04T15:44:55.176Z", "default_ci_config_path" : null, "default_project_visibility" : "private", @@ -73,7 +79,8 @@ Example response: "snippet_size_limit": 52428800, "issues_create_limit": 300, "raw_blob_request_limit": 300, - "wiki_page_max_content_bytes": 52428800 + "wiki_page_max_content_bytes": 52428800, + "require_admin_approval_after_user_signup": false } ``` @@ -127,9 +134,9 @@ Example response: "default_snippet_visibility": "private", "default_group_visibility": "private", "outbound_local_requests_whitelist": [], - "domain_whitelist": [], - "domain_blacklist_enabled" : false, - "domain_blacklist" : [], + "domain_allowlist": [], + "domain_denylist_enabled" : false, + "domain_denylist" : [], "external_authorization_service_enabled": true, "external_authorization_service_url": "https://authorize.me", "external_authorization_service_default_label": "default", @@ -164,7 +171,8 @@ Example response: "snippet_size_limit": 52428800, "issues_create_limit": 300, "raw_blob_request_limit": 300, - "wiki_page_max_content_bytes": 52428800 + "wiki_page_max_content_bytes": 52428800, + "require_admin_approval_after_user_signup": false } ``` @@ -225,9 +233,9 @@ listed in the descriptions of the relevant settings. | `diff_max_patch_bytes` | integer | no | Maximum diff patch size (Bytes). | | `disabled_oauth_sign_in_sources` | array of strings | no | Disabled OAuth sign-in sources. | | `dns_rebinding_protection_enabled` | boolean | no | Enforce DNS rebinding attack protection. | -| `domain_blacklist_enabled` | boolean | no | (**If enabled, requires:** `domain_blacklist`) Allows blocking sign-ups from emails from specific domains. | -| `domain_blacklist` | array of strings | no | Users with e-mail addresses that match these domain(s) will NOT be able to sign-up. Wildcards allowed. Use separate lines for multiple entries. Ex: `domain.com`, `*.domain.com`. | -| `domain_whitelist` | array of strings | no | Force people to use only corporate emails for sign-up. Default is `null`, meaning there is no restriction. | +| `domain_denylist_enabled` | boolean | no | (**If enabled, requires:** `domain_denylist`) Allows blocking sign-ups from emails from specific domains. | +| `domain_denylist` | array of strings | no | Users with e-mail addresses that match these domain(s) will NOT be able to sign-up. Wildcards allowed. Use separate lines for multiple entries. Ex: `domain.com`, `*.domain.com`. | +| `domain_allowlist` | array of strings | no | Force people to use only corporate emails for sign-up. Default is `null`, meaning there is no restriction. | | `dsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded DSA key. Default is `0` (no restriction). `-1` disables DSA keys. | | `ecdsa_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ECDSA key. Default is `0` (no restriction). `-1` disables ECDSA keys. | | `ed25519_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ED25519 key. Default is `0` (no restriction). `-1` disables ED25519 keys. | @@ -325,6 +333,7 @@ listed in the descriptions of the relevant settings. | `repository_size_limit` | integer | no | **(PREMIUM)** Size limit per repository (MB) | | `repository_storages_weighted` | hash of strings to integers | no | (GitLab 13.1 and later) Hash of names of taken from `gitlab.yml` to [weights](../administration/repository_storage_paths.md#choose-where-new-repositories-will-be-stored). New projects are created in one of these stores, chosen by a weighted random selection. | | `repository_storages` | array of strings | no | (GitLab 13.0 and earlier) List of names of enabled storage paths, taken from `gitlab.yml`. New projects are created in one of these stores, chosen at random. | +| `require_admin_approval_after_user_signup` | boolean | no | When enabled, any user that signs up for an account using the registration form is placed under a **Pending approval** state and has to be explicitly [approved](../user/admin_area/approving_users.md) by an administrator. | | `require_two_factor_authentication` | boolean | no | (**If enabled, requires:** `two_factor_grace_period`) Require all users to set up Two-factor authentication. | | `restricted_visibility_levels` | array of strings | no | Selected levels cannot be used by non-admin users for groups, projects or snippets. Can take `private`, `internal` and `public` as a parameter. Default is `null` which means there is no restriction. | | `rsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded RSA key. Default is `0` (no restriction). `-1` disables RSA keys. | diff --git a/doc/api/sidekiq_metrics.md b/doc/api/sidekiq_metrics.md index caa02412a28..914f5fbf42a 100644 --- a/doc/api/sidekiq_metrics.md +++ b/doc/api/sidekiq_metrics.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Sidekiq Metrics API **(CORE ONLY)** > Introduced in GitLab 8.9. diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 431d745ac84..c2812de5dd7 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -21,7 +21,7 @@ Valid values for snippet visibility levels are: | Visibility | Description | |:-----------|:----------------------------------------------------| | `private` | Snippet is visible only to the snippet creator. | -| `internal` | Snippet is visible for any logged in user. | +| `internal` | Snippet is visible for any logged in user except [external users](../user/permissions.md#external-users). | | `public` | Snippet can be accessed without any authentication. | ## List all snippets for a user diff --git a/doc/api/statistics.md b/doc/api/statistics.md index 890c6f68898..6a41a960eba 100644 --- a/doc/api/statistics.md +++ b/doc/api/statistics.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Application statistics API ## Get current application statistics diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index 3e0d2151428..00cd88c88dd 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # System hooks API All methods require administrator authorization. diff --git a/doc/api/templates/dockerfiles.md b/doc/api/templates/dockerfiles.md index e579300a2fd..fd0edfce8e5 100644 --- a/doc/api/templates/dockerfiles.md +++ b/doc/api/templates/dockerfiles.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/api/templates/gitignores.md b/doc/api/templates/gitignores.md index 3acd666ad66..b957c582755 100644 --- a/doc/api/templates/gitignores.md +++ b/doc/api/templates/gitignores.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/api/templates/licenses.md b/doc/api/templates/licenses.md index 4eb3c0f6111..d1044b23306 100644 --- a/doc/api/templates/licenses.md +++ b/doc/api/templates/licenses.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/api/todos.md b/doc/api/todos.md index ab36021d694..06b99ab8c53 100644 --- a/doc/api/todos.md +++ b/doc/api/todos.md @@ -26,7 +26,7 @@ Parameters: | `project_id` | integer | no | The ID of a project | | `group_id` | integer | no | The ID of a group | | `state` | string | no | The state of the to do. Can be either `pending` or `done` | -| `type` | string | no | The type of a to do. Can be either `Issue`, `MergeRequest`, `DesignManagement::Design` or `AlertManagement::Alert` | +| `type` | string | no | The type of to-do item. Can be either `Issue`, `MergeRequest`, `DesignManagement::Design` or `AlertManagement::Alert` | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/todos" @@ -187,7 +187,7 @@ Example Response: ] ``` -## Mark a to do as done +## Mark a to-do item as done Marks a single pending to do given by its ID for the current user as done. The to do marked as done is returned in the response. @@ -200,7 +200,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a to do | +| `id` | integer | yes | The ID of to-do item | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/todos/130/mark_as_done" diff --git a/doc/api/users.md b/doc/api/users.md index beaea689fb7..e1fa97765df 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Users API ## List users @@ -1435,7 +1441,54 @@ Parameters: | `user_id` | integer | yes | The ID of the user | | `impersonation_token_id` | integer | yes | The ID of the impersonation token | -### Get user activities (admin only) +## Create a personal access token (admin only) + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17176) in GitLab 13.6. +> - It's [deployed behind a feature flag](../user/feature_flags.md), disabled by default. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-an-administrators-ability-to-use-the-api-to-create-personal-access-tokens). **(CORE)** + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +> Requires admin permissions. +> Token values are returned once. Make sure you save it - you won't be able to access it again. + +It creates a new personal access token. + +```plaintext +POST /users/:user_id/personal_access_tokens +``` + +| Attribute | Type | Required | Description | +| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | +| `user_id` | integer | yes | The ID of the user | +| `name` | string | yes | The name of the personal access token | +| `expires_at` | date | no | The expiration date of the personal access token in ISO format (`YYYY-MM-DD`) | +| `scopes` | array | yes | The array of scopes of the personal access token (`api`, `read_user`, `read_api`, `read_repository`, `write_repository`) | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" --data "scopes[]=api" "https://gitlab.example.com/api/v4/users/42/personal_access_tokens" +``` + +Example response: + +```json +{ + "id": 3, + "name": "mytoken", + "revoked": false, + "created_at": "2020-10-14T11:58:53.526Z", + "scopes": [ + "api" + ], + "user_id": 42, + "active": true, + "expires_at": "2020-12-31", + "token": "ggbfKkC4n-Lujy8jwCR2" +} +``` + +## Get user activities (admin only) NOTE: **Note:** This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above. @@ -1540,3 +1593,22 @@ Example response: }, ] ``` + +## Enable or disable an administrator's ability to use the API to create personal access tokens **(CORE)** + +An administrator's ability to create personal access tokens through the API is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:pat_creation_api_for_admin) +``` + +To disable it: + +```ruby +Feature.disable(:pat_creation_api_for_admin) +``` diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index c351c14e24c..2dd4376413b 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # API V3 to API V4 In GitLab 9.0 and later, API V4 is the preferred version to be used. diff --git a/doc/api/version.md b/doc/api/version.md index 3c6feaae071..d1582cf63cd 100644 --- a/doc/api/version.md +++ b/doc/api/version.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Version API > Introduced in GitLab 8.13. diff --git a/doc/architecture/blueprints/cloud_native_build_logs/index.md b/doc/architecture/blueprints/cloud_native_build_logs/index.md index 25abfe36e88..f901a724653 100644 --- a/doc/architecture/blueprints/cloud_native_build_logs/index.md +++ b/doc/architecture/blueprints/cloud_native_build_logs/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false description: 'Next iteration of build logs architecture at GitLab' --- diff --git a/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md b/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md index 37e69d46ae1..27d2f1362e5 100644 --- a/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md +++ b/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false description: 'Making GitLab Pages a Cloud Native application - architecture blueprint.' --- diff --git a/doc/architecture/blueprints/feature_flags_development/index.md b/doc/architecture/blueprints/feature_flags_development/index.md index 0aeb2b51b39..76fb5f5c7db 100644 --- a/doc/architecture/blueprints/feature_flags_development/index.md +++ b/doc/architecture/blueprints/feature_flags_development/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false description: 'Internal usage of Feature Flags for GitLab development' --- diff --git a/doc/architecture/blueprints/image_resizing/index.md b/doc/architecture/blueprints/image_resizing/index.md new file mode 100644 index 00000000000..47e2ad24960 --- /dev/null +++ b/doc/architecture/blueprints/image_resizing/index.md @@ -0,0 +1,76 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +comments: false +description: 'Image Resizing' +--- + +# Image resizing for avatars and content images + +Currently, we are showing all uploaded images 1:1, which is of course not ideal. To improve performance greatly we will add image resizing to the backend. There are two main areas of image resizing to consider; avatars and content images. The MVC for this implementation will focus on Avatars. Avatars requests consist of approximately 70% of total image requests. There is an identified set of sizes we intend to support which makes the scope of this first MVC very narrow. Content image resizing has many more considerations for size and features. It is entirely possible that we have two separate development efforts with the same goal of increasing performance via image resizing. + +## MVC Avatar Resizing + +We will implement a dynamic image resizing solution. This means image should be resized and optimized on the fly so that if we define new targeted sizes later we can add them dynamically. This would mean a huge improvement in performance as some of the measurements suggest that we can save up to 95% of our current load size. Our initial investigations indicate that we have uploaded approximately 1.65 million avatars totaling approximately 80GB in size and averaging approximately 48kb each. Early measurements indicate we can reduce the most common avatar dimensions to between 1-3kb in size, netting us a greater than 90% size reduction. For the MVC we will not consider application level caching and rely purely on HTTP based caches as implemented in CDNs and browsers, but might revisit this decision later on. To easily mitigate performance issues with avatar resizing, especially in the case of self managed, an operations feature flag will be implemented to disable dynamic image resizing. + +```mermaid +sequenceDiagram + autonumber + Requester->>Workhorse: Incoming request + Workhorse->>RailsApp: Incoming request + alt All is true: 1.Avatar is requested, 2.Requested Width is allowed, 3.Feature is enabled + Note right of RailsApp: Width Allowlist: https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/concerns/avatarable.rb#L10 + RailsApp->>Workhorse: `send-scaled-img:` request + Note right of RailsApp: Set `send-scaled-img:` Header + Workhorse->>Workhorse: Image resizing using Go lib + Workhorse->>Requester: Serve the resized image + else All other cases + RailsApp->>Workhorse: Usual request scenario + Workhorse->>Requester: Usual request scenario + end +``` + +## Content Image Resizing + +Content image resizing is a more complex problem to tackle. There are no set size restrictions and there are additional features or requirements to consider. + +- Dynamic WebP support - the WebP format typically achieves an average of 30% more compression than JPEG without the loss of image quality. More details [here](https://developers.google.com/speed/webp/docs/c_study) +- Extract first image of GIF's so we can prevent from loading 10MB pixels +- Check Device Pixel Ratio to deliver nice images on High DPI screens +- Progressive image loading, similar to what is described [here](https://www.sitepoint.com/how-to-build-your-own-progressive-image-loader/) +- Resizing recommendations (size, clarity, etc.) +- Storage + +The MVC Avatar resizing implementation is integrated into Workhorse. With the extra requirements for content image resizing, this may require further use of GraphicsMagik (GM) or a similar library and breaking it out of Workhorse. + +## Iterations + +1. ✓ POC on different image resizing solutions +1. ✓ Review solutions with security team +1. ✓ Implement avatar resizing MVC +1. Deploy, measure, monitor +1. Clarify features for content image resizing +1. Weigh options between using current implementation of image resizing vs new solution +1. Implement content image resizing MVC +1. Deploy, measure, monitor + +## Who + +Proposal: + +| Role | Who +|------------------------------|-------------------------| +| Author | Craig Gomes | +| Architecture Evolution Coach | Kamil Trzciński | +| Engineering Leader | Tim Zallmann | +| Domain Expert | Matthias Kaeppler | +| Domain Expert | Aleksei Lipniagov | + +DRIs: + +| Role | Who +|------------------------------|------------------------| +| Product | Josh Lambert | +| Leadership | Craig Gomes | +| Engineering | Matthias Kaeppler | diff --git a/doc/architecture/index.md b/doc/architecture/index.md index 0a2ade6b7b0..0cac646ea83 100644 --- a/doc/architecture/index.md +++ b/doc/architecture/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false description: 'Architecture Practice at GitLab' --- diff --git a/doc/ci/README.md b/doc/ci/README.md index dca6d8baa79..45cf56df894 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -77,7 +77,7 @@ While building your `.gitlab-ci.yml`, you can use the [CI/CD configuration visua For a broader overview, see the [CI/CD getting started](quick_start/README.md) guide. -Once you're familiar with how GitLab CI/CD works, see the +After you're familiar with how GitLab CI/CD works, see the [`.gitlab-ci.yml` full reference](yaml/README.md) for all the attributes you can set and use. diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index df41f7da2d9..dfa92d469bc 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -411,6 +411,8 @@ job B: - cat vendor/hello.txt cache: key: build-cache + paths: + - vendor/ ``` Here's what happens behind the scenes: 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 7ee9f98bd39..b6f885ff220 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -22,7 +22,7 @@ cannot be used to authenticate with GitHub as an external CI/CD repository. ## Connect with Personal Access Token Personal access tokens can only be used to connect GitHub.com -repositories to GitLab, and the GitHub user must have the [owner role](https://docs.github.com/en/github/getting-started-with-github/access-permissions-on-github). +repositories to GitLab, and the GitHub user must have the [owner role](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/access-permissions-on-github). To perform a one-off authorization with GitHub to grant GitLab access your repositories: diff --git a/doc/ci/ci_cd_for_external_repos/img/github_omniauth.png b/doc/ci/ci_cd_for_external_repos/img/github_omniauth.png Binary files differdeleted file mode 100644 index 71a3a057a41..00000000000 --- a/doc/ci/ci_cd_for_external_repos/img/github_omniauth.png +++ /dev/null diff --git a/doc/ci/ci_cd_for_external_repos/img/github_push_webhook.png b/doc/ci/ci_cd_for_external_repos/img/github_push_webhook.png Binary files differdeleted file mode 100644 index e8c17d664e1..00000000000 --- a/doc/ci/ci_cd_for_external_repos/img/github_push_webhook.png +++ /dev/null diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index c6590599849..ae6cb759d23 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -77,7 +77,7 @@ created. GitLab CI/CD will create 2 pipelines in this case. One for the branch push and one for the external pull request. -Once the Pull Request is closed, no pipelines are created for the external pull +After the Pull Request is closed, no pipelines are created for the external pull request, even if new changes are pushed to the same branch. ### Additional predefined variables diff --git a/doc/ci/cloud_deployment/index.md b/doc/ci/cloud_deployment/index.md index af7df0e1153..cbaebde0b00 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -239,7 +239,7 @@ pass three JSON input objects, based on existing templates: - [Template for the _Deploy to EC2_ step on AWS](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_CreateDeployment.html). -1. Once you have completed these three templates based on your requirements, you +1. After you have completed these three templates based on your requirements, you have two ways to pass in these JSON objects: - They can be three actual files located in your project. You must specify their path relative to @@ -281,3 +281,40 @@ When running your project pipeline at this point: - Your built application is pushed to your S3 bucket then and deployed to your EC2 instance, based on the related JSON object's content. The deployment job finishes whenever the deployment to EC2 is done or has failed. + +#### Custom build job for Auto DevOps + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216008) in GitLab 13.6. + +To leverage [Auto DevOps](../../topics/autodevops/index.md) for your project when deploying to +AWS EC2, first you must define [your AWS credentials as environment variables](#run-aws-commands-from-gitlab-cicd). + +Next, define a job for the `build` stage. To do so, you must reference the +`Auto-DevOps.gitlab-ci.yml` template and include a job named `build_artifact` in your +`.gitlab-ci.yml` file. For example: + +```yaml +# .gitlab-ci.yml + +include: + - template: Auto-DevOps.gitlab-ci.yml + +variables: + - AUTO_DEVOPS_PLATFORM_TARGET: EC2 + +build_artifact: + stage: build + script: + - <your build script goes here> + artifacts: + paths: + - <built artifact> +``` + +### Deploy to Amazon EKS + +- [How to deploy your application to a GitLab-managed Amazon EKS cluster with Auto DevOps](https://about.gitlab.com/blog/2020/05/05/deploying-application-eks/) + +## Deploy to Google Cloud + +- [Deploying with GitLab on Google Cloud](https://about.gitlab.com/solutions/google-cloud-platform/) diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index 19da0496f8a..04f27c584b7 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -79,26 +79,28 @@ are certain use cases that you may need to work around. For more information: - [`needs` requirements and limitations](../yaml/README.md#requirements-and-limitations). - Related epic [tracking planned improvements](https://gitlab.com/groups/gitlab-org/-/epics/1716). -## DAG Visualization +## Needs Visualization > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215517) in GitLab 13.1 as a [Beta feature](https://about.gitlab.com/handbook/product/#beta). > - It was deployed behind a feature flag, disabled by default. > - It became [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36802) in 13.2. > - It became a [standard feature](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38517) in 13.3. > - It's enabled on GitLab.com. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-dag-visualization). +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-needs-visualization). -The DAG visualization makes it easier to visualize the relationships between dependent jobs in a DAG. This graph will display all the jobs in a pipeline that need or are needed by other jobs. Jobs with no relationships are not displayed in this view. +The needs visualization makes it easier to visualize the relationships between dependent jobs in a DAG. This graph will display all the jobs in a pipeline that need or are needed by other jobs. Jobs with no relationships are not displayed in this view. - +To see the needs visualization, click on the **Needs** tab when viewing a pipeline that uses the `needs:` keyword. + + Clicking a node will highlight all the job paths it depends on. - + -### Enable or disable DAG Visualization **(CORE ONLY)** +### Enable or disable Needs Visualization **(CORE ONLY)** -DAG Visualization is deployed behind a feature flag that is **enabled by default**. +The needs visualization is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can opt to disable it for your instance: diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index e3123cde1cd..ebbfde09c67 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -90,7 +90,7 @@ GitLab Runner then executes job scripts as the `gitlab-runner` user. 1. You can now use `docker` command (and **install** `docker-compose` if needed). By adding `gitlab-runner` to the `docker` group you are effectively granting `gitlab-runner` full root permissions. -For more information please read [On Docker security: `docker` group considered harmful](https://www.andreas-jung.com/contents/on-docker-security-docker-group-considered-harmful). +For more information please read [On Docker security: `docker` group considered harmful](https://blog.zopyx.com/on-docker-security-docker-group-considered-harmful/). ### Use Docker-in-Docker workflow with Docker executor @@ -103,7 +103,7 @@ image in privileged mode. CI builds, follow the `docker-compose` [installation instructions](https://docs.docker.com/compose/install/). -DANGER: **Danger:** +DANGER: **Warning:** By enabling `--docker-privileged`, you are effectively disabling all of the security mechanisms of containers and exposing your host to privilege escalation which can lead to container breakout. For more information, check @@ -302,7 +302,149 @@ build: - docker run my-docker-image /script/to/run/tests ``` -### Use Docker socket binding +#### Enable registry mirror for `docker:dind` service + +When the Docker daemon starts inside of the service container, it uses +the default configuration. You may want to configure a [registry +mirror](https://docs.docker.com/registry/recipes/mirror/) for +performance improvements and ensuring you don't reach DockerHub rate limits. + +##### Inside `.gitlab-ci.yml` + +You can append extra CLI flags to the `dind` service to set the registry +mirror: + +```yaml +services: + - name: docker:19.03.13-dind + command: ["--registry-mirror", "https://registry-mirror.example.com"] # Specify the registry mirror to use. +``` + +##### DinD service defined inside of GitLab Runner configuration + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27173) in GitLab Runner 13.6. + +If you are an administrator of GitLab Runner and you have the `dind` +service defined for the [Docker +executor](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersdockerservices-section), +or the [Kubernetes +executor](https://docs.gitlab.com/runner/executors/kubernetes.html#using-services) +you can specify the `command` to configure the registry mirror for the +Docker daemon. + +Docker: + +```toml +[[runners]] + ... + executor = "docker" + [runners.docker] + ... + privileged = true + [[runners.docker.services]] + name = "docker:19.03.13-dind" + command = ["--registry-mirror", "https://registry-mirror.example.com"] +``` + +Kubernetes: + +```toml +[[runners]] + ... + name = "kubernetes" + [runners.kubernetes] + ... + privileged = true + [[runners.kubernetes.services]] + name = "docker:19.03.13-dind" + command = ["--registry-mirror", "https://registry-mirror.example.com"] +``` + +##### Docker executor inside GitLab Runner configuration + +If you are an administrator of GitLab Runner and you want to use +the mirror for every `dind` service, update the +[configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) +to specify a [volume +mount](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#volumes-in-the-runnersdocker-section). + +For example, if you have a `/opt/docker/daemon.json` file with the following +content: + +```json +{ + "registry-mirrors": [ + "https://registry-mirror.example.com" + ] +} +``` + +Update the `config.toml` file to mount the file to +`/etc/docker/daemon.json`. This would mount the file for **every** +container that is created by GitLab Runner. The configuration will be +picked up by the `dind` service. + +```toml +[[runners]] + ... + executor = "docker" + [runners.docker] + image = "alpine:3.12" + privileged = true + volumes = ["/opt/docker/daemon.json:/etc/docker/daemon.json:ro"] +``` + +##### Kubernetes executor inside GitLab Runner configuration + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3223) in GitLab Runner 13.6. + +If you are an administrator of GitLab Runner and you want to use +the mirror for every `dind` service, update the +[configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) +to specify a [ConfigMap volume +mount](https://docs.gitlab.com/runner/executors/kubernetes.html#using-volumes). + +For example, if you have a `/tmp/daemon.json` file with the following +content: + +```json +{ + "registry-mirrors": [ + "https://registry-mirror.example.com" + ] +} +``` + +Create a [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) with the content +of this file. You can do this with a command like: + +```shell +kubectl create configmap docker-daemon --namespace gitlab-runner --from-file /tmp/daemon.json +``` + +NOTE: **Note:** +Make sure to use the namespace that GitLab Runner Kubernetes executor uses +to create job pods in. + +After the ConfigMap is created, you can update the `config.toml` +file to mount the file to `/etc/docker/daemon.json`. This update +mounts the file for **every** container that is created by GitLab Runner. +The configuration is picked up by the `dind` service. + +```toml +[[runners]] + ... + executor = "kubernetes" + [runners.kubernetes] + image = "alpine:3.12" + privileged = true + [[runners.kubernetes.volumes.config_map]] + name = "docker-daemon" + mount_path = "/etc/docker/daemon.json" + sub_path = "daemon.json" +``` + +#### Use Docker socket binding The third approach is to bind-mount `/var/run/docker.sock` into the container so that Docker is available in the context of that image. @@ -502,7 +644,7 @@ and [using the OverlayFS storage driver](https://docs.docker.com/engine/userguid ## Using the GitLab Container Registry -Once you've built a Docker image, you can push it up to the built-in +After you've built a Docker image, you can push it up to the built-in [GitLab Container Registry](../../user/packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd). ## Troubleshooting diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index f7d54aa7d78..b8563182bd9 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -452,9 +452,9 @@ CI jobs: from `Dockerfile` that may be overridden in `.gitlab-ci.yml`) 1. The runner attaches itself to a running container. 1. The runner prepares a script (the combination of - [`before_script`](../yaml/README.md#before_script-and-after_script), + [`before_script`](../yaml/README.md#before_script), [`script`](../yaml/README.md#script), - and [`after_script`](../yaml/README.md#before_script-and-after_script)). + and [`after_script`](../yaml/README.md#after_script)). 1. The runner sends the script to the container's shell STDIN and receives the output. @@ -561,10 +561,11 @@ See below for examples of each. #### Determining your `DOCKER_AUTH_CONFIG` data -As an example, let's assume that you want to use the `registry.example.com:5000/private/image:latest` -image which is private and requires you to login into a private container registry. +As an example, let's assume you want to use the `registry.example.com:5000/private/image:latest` +image, which is private and requires you to sign in to a private container +registry. -Let's also assume that these are the login credentials: +Let's also assume that these are the sign-in credentials: | Key | Value | |:---------|:----------------------------| @@ -572,9 +573,9 @@ Let's also assume that these are the login credentials: | username | `my_username` | | password | `my_password` | -There are two ways to determine the value of `DOCKER_AUTH_CONFIG`: +Use one of the following methods to determine the value of `DOCKER_AUTH_CONFIG`: -- **First way -** Do a `docker login` on your local machine: +- Do a `docker login` on your local machine: ```shell docker login registry.example.com:5000 --username my_username --password my_password @@ -589,12 +590,11 @@ There are two ways to determine the value of `DOCKER_AUTH_CONFIG`: docker logout registry.example.com:5000 ``` -- **Second way -** In some setups, it's possible that Docker client - uses the available system key store to store the result of `docker - login`. In that case, it's impossible to read `~/.docker/config.json`, - so you need to prepare the required base64-encoded version of - `${username}:${password}` and create the Docker configuration JSON manually. - Open a terminal and execute the following command: +- In some setups, it's possible that Docker client uses the available system key + store to store the result of `docker login`. In that case, it's impossible to + read `~/.docker/config.json`, so you need to prepare the required + base64-encoded version of `${username}:${password}` and create the Docker + configuration JSON manually. Open a terminal and execute the following command: ```shell # The use of "-n" - prevents encoding a newline in the password. diff --git a/doc/ci/environments/img/protected_access_group_v13_6.png b/doc/ci/environments/img/protected_access_group_v13_6.png Binary files differnew file mode 100644 index 00000000000..9c39e4362e8 --- /dev/null +++ b/doc/ci/environments/img/protected_access_group_v13_6.png diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index baf2156e64a..361b7217d17 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -34,8 +34,7 @@ currently being deployed or has been deployed on your servers. It's important to know that: - Environments are like tags for your CI jobs, describing where code gets deployed. -- Deployments are created when [jobs](../yaml/README.md#introduction) deploy versions of code to environments, - so every environment can have one or more deployments. +- Deployments are created when [GitLab CI/CD](../yaml/README.md) is used to deploy versions of code to environments. GitLab: @@ -219,10 +218,17 @@ You can also specify a static part of the URL at `environment:url:`, such as The assigned URL for the `review/your-branch-name` environment is [visible in the UI](#using-the-environment-url). -> **Notes:** -> -> - `stop_review` doesn't generate a dotenv report artifact, so it won't recognize the `DYNAMIC_ENVIRONMENT_URL` variable. Therefore you should not set `environment:url:` in the `stop_review` job. -> - If the environment URL is not valid (for example, the URL is malformed), the system doesn't update the environment URL. +Note the following: + +- `stop_review` doesn't generate a dotenv report artifact, so it won't recognize the + `DYNAMIC_ENVIRONMENT_URL` variable. Therefore you shouldn't set `environment:url:` in the + `stop_review` job. +- If the environment URL isn't valid (for example, the URL is malformed), the system doesn't update + the environment URL. +- If the script that runs in `stop_review` exists only in your repository and therefore can't use + `GIT_STRATEGY: none`, configure [pipelines for merge requests](../../ci/merge_request_pipelines/index.md) + for these jobs. This ensures that runners can fetch the repository even after a feature branch is + deleted. For more information, see [Ref Specs for Runners](../pipelines/index.md#ref-specs-for-runners). ### Configuring manual deployments @@ -304,7 +310,7 @@ Dynamic environments are a fundamental part of [Review apps](../review_apps/inde #### Allowed variables -The `name` and `url` parameters for dynamic environments can use most available CI/CD variables, +The `name` and `url` keywords for dynamic environments can use most available CI/CD variables, including: - [Predefined environment variables](../variables/README.md#predefined-environment-variables) @@ -436,7 +442,7 @@ The configuration in this section provides a full development workflow where you - Tested. - Built. - Deployed as a Review App. -- Deployed to a staging server once the merge request is merged. +- Deployed to a staging server after the merge request is merged. - Finally, able to be manually deployed to the production server. The following combines the previous configuration examples, including: @@ -675,24 +681,23 @@ deploy_review: name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com on_stop: stop_review - only: - - branches - except: - - master + rules: + - if: $CI_MERGE_REQUEST_ID stop_review: stage: deploy - variables: - GIT_STRATEGY: none script: - echo "Remove review app" - when: manual environment: name: review/$CI_COMMIT_REF_NAME action: stop + rules: + - if: $CI_MERGE_REQUEST_ID + when: manual ``` -Setting the [`GIT_STRATEGY`](../yaml/README.md#git-strategy) to `none` is necessary in the +If you can't use [Pipelines for merge requests](../merge_request_pipelines/index.md), +setting the [`GIT_STRATEGY`](../runners/README.md#git-strategy) to `none` is necessary in the `stop_review` job so that the [runner](https://docs.gitlab.com/runner/) won't try to check out the code after the branch is deleted. @@ -748,13 +753,17 @@ review_app: name: review/$CI_COMMIT_REF_NAME on_stop: stop_review_app auto_stop_in: 1 week + rules: + - if: $CI_MERGE_REQUEST_ID stop_review_app: script: stop-review-app environment: name: review/$CI_COMMIT_REF_NAME action: stop - when: manual + rules: + - if: $CI_MERGE_REQUEST_ID + when: manual ``` As long as a merge request is active and keeps getting new commits, @@ -923,11 +932,10 @@ the [Kubernetes integration](../../user/project/clusters/index.md)), GitLab can a terminal session to your environment. This is a powerful feature that allows you to debug issues without leaving the comfort -of your web browser. To enable it, just follow the instructions given in the service integration +of your web browser. To enable it, follow the instructions given in the service integration documentation. -NOTE: **Note:** -Container-based deployments often lack basic tools (like an editor), and may +Note that container-based deployments often lack basic tools (like an editor), and may be stopped or restarted at any time. If this happens, you will lose all your changes. Treat this as a debugging tool, not a comprehensive online IDE. diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index 87bced29906..eeb95947ba1 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -45,6 +45,61 @@ To protect an environment: The protected environment will now appear in the list of protected environments. +### Use the API to protect an environment + +Alternatively, you can use the API to protect an environment: + +1. Use a project with a CI that creates an environment. For example: + + ```yaml + stages: + - test + - deploy + + test: + stage: test + script: + - 'echo "Testing Application: ${CI_PROJECT_NAME}"' + + production: + stage: deploy + when: manual + script: + - 'echo "Deploying to ${CI_ENVIRONMENT_NAME}"' + environment: + name: ${CI_JOB_NAME} + ``` + +1. Use the UI to [create a new group](../../user/group/index.md#create-a-new-group). + For example, this group is called `protected-access-group` and has the group ID `9899826`. Note + that the rest of the examples in these steps use this group. + +  + +1. Use the API to add a user to the group as a reporter: + + ```shell + $ curl --request POST --header "PRIVATE-TOKEN: xxxxxxxxxxxx" --data "user_id=3222377&access_level=20" "https://gitlab.com/api/v4/groups/9899826/members" + + {"id":3222377,"name":"Sean Carroll","username":"sfcarroll","state":"active","avatar_url":"https://assets.gitlab-static.net/uploads/-/system/user/avatar/3222377/avatar.png","web_url":"https://gitlab.com/sfcarroll","access_level":20,"created_at":"2020-10-26T17:37:50.309Z","expires_at":null} + ``` + +1. Use the API to add the group to the project as a reporter: + + ```shell + $ curl --request POST --header "PRIVATE-TOKEN: xxxxxxxxxxxx" --request POST "https://gitlab.com/api/v4/projects/22034114/share?group_id=9899826&group_access=20" + + {"id":1233335,"project_id":22034114,"group_id":9899826,"group_access":20,"expires_at":null} + ``` + +1. Use the API to add the group with protected environment access: + + ```shell + curl --header 'Content-Type: application/json' --request POST --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}]}' --header "PRIVATE-TOKEN: xxxxxxxxxxx" "https://gitlab.com/api/v4/projects/22034114/protected_environments" + ``` + +The group now has access and can be seen in the UI. + ## Environment access by group membership A user may be granted access to protected environments as part of @@ -72,8 +127,7 @@ they have the following privileges: Users granted access to a protected environment, but not push or merge access to the branch deployed to it, are only granted access to deploy the environment. -NOTE: **Note:** -Deployment-only access is the only possible access level for users with +Note that deployment-only access is the only possible access level for users with [Reporter permissions](../../user/permissions.md). ## Modifying and unprotecting environments @@ -84,7 +138,6 @@ Maintainers can: **Allowed to Deploy** dropdown menu. - Unprotect a protected environment by clicking the **Unprotect** button for that environment. -NOTE: **Note:** After an environment is unprotected, all access entries are deleted and must be re-entered if the environment is re-protected. diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md index 34e3b276d3e..1abb33005ca 100644 --- a/doc/ci/examples/README.md +++ b/doc/ci/examples/README.md @@ -15,7 +15,7 @@ Examples are available in several forms. As a collection of: - `.gitlab-ci.yml` [template files](#cicd-templates) maintained in GitLab, for many common frameworks and programming languages. -- Repositories with [example projects](https://gitlab.com/gitlab-examples) for various languages. You can fork and adjust them to your own needs. Projects include demonstrations of [multi-project pipelines](https://gitlab.com/gitlab-examples/multi-project-pipelines) and using [Review Apps with a static site served by NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx/). +- Repositories with [example projects](https://gitlab.com/gitlab-examples) for various languages. You can fork and adjust them to your own needs. Projects include an example of using [Review Apps with a static site served by NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx/). - Examples and [other resources](#other-resources) listed below. ## CI/CD examples @@ -42,6 +42,7 @@ The following table lists examples with step-by-step tutorials that are containe | Scala on Heroku | [Test and deploy a Scala application to Heroku](test-scala-application.md). | | Parallel testing Ruby & JS | [GitLab CI/CD parallel jobs testing for Ruby & JavaScript projects](https://docs.knapsackpro.com/2019/how-to-run-parallel-jobs-for-rspec-tests-on-gitlab-ci-pipeline-and-speed-up-ruby-javascript-testing). | | Secrets management with Vault | [Authenticating and Reading Secrets With Hashicorp Vault](authenticating-with-hashicorp-vault/index.md). | +| Multi project pipeline | [Build, test deploy using multi project pipeline](https://gitlab.com/gitlab-examples/upstream-project). | ### Contributing examples diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md index 4a0ff2fa6ac..c0fb94acdf2 100644 --- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md +++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md @@ -22,7 +22,8 @@ This tutorial assumes you are familiar with GitLab CI/CD and Vault. To follow along, you will need: - An account on GitLab. -- A running Vault server and the access required to configure authentication and create roles and policies. +- A running Vault server and access to it is required to configure authentication and create roles + and policies. For HashiCorp Vaults, this can be the Open Source or Enterprise version. NOTE: **Note:** You will need to replace the `vault.example.com` URL below with the URL of your Vault server and `gitlab.example.com` with the URL of your GitLab instance. @@ -55,7 +56,7 @@ The JWT's payload looks like this: } ``` -The JWT is encoded by using RS256 and signed with your GitLab instance's OpenID Connect private key. The expire time for the token will be set to job's timeout, if specified, or 5 minutes if it is not. The key used to sign this token may change without any notice. In such case retrying the job will generate new JWT using the current signing key. +The JWT is encoded by using RS256 and signed with a dedicated private key. The expire time for the token will be set to job's timeout, if specified, or 5 minutes if it is not. The key used to sign this token may change without any notice. In such case retrying the job will generate new JWT using the current signing key. You can use this JWT and your instance's JWKS endpoint (`https://gitlab.example.com/-/jwks`) to authenticate with a Vault server that is configured to allow the JWT Authentication method for authentication. diff --git a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md index b113b10f2e3..25b866a08ed 100644 --- a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md +++ b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md @@ -103,27 +103,27 @@ Hub](https://hub.docker.com/). We've also added the [`only` clause](../../yaml/README.md#onlyexcept-basic) to ensure our deployments only happen when we push to the master branch. -Now, since the steps defined in `.gitlab-ci.yml` require credentials to login -to CF, you'll need to add your CF credentials as [environment -variables](../../variables/README.md#predefined-environment-variables) -on GitLab CI/CD. To set the environment variables, navigate to your project's -**Settings > CI/CD** and expand **Variables**. Name the variables +Because the steps defined in `.gitlab-ci.yml` require credentials to sign in to +CF, you'll need to add your CF credentials as +[environment variables](../../variables/README.md#predefined-environment-variables) +in GitLab CI/CD. To set the environment variables, navigate to your project's +**Settings > CI/CD**, and then expand **Variables**. Name the variables `CF_USERNAME` and `CF_PASSWORD` and set them to the correct values.  -Once set up, GitLab CI/CD will deploy your app to CF at every push to your -repository's default branch. To see the build logs or watch your builds running -live, navigate to **CI/CD > Pipelines**. +After set up, GitLab CI/CD deploys your app to CF at every push to your +repository's default branch. To review the build logs or watch your builds +running live, navigate to **CI/CD > Pipelines**. CAUTION: **Caution:** -It is considered best practice for security to create a separate deploy -user for your application and add its credentials to GitLab instead of using -a developer's credentials. +It's considered best practice for security to create a separate deploy user for +your application and add its credentials to GitLab instead of using a +developer's credentials. To start a manual deployment in GitLab go to **CI/CD > Pipelines** then click -on **Run Pipeline**. Once the app is finished deploying it will display the URL -of your application in the logs for the `production` job like: +on **Run Pipeline**. After the app is finished deploying, it will display the +URL of your application in the logs for the `production` job like: ```shell requested state: started diff --git a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md index 836141af91e..39cad3a0c93 100644 --- a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md @@ -249,7 +249,7 @@ pipeline to include running the tests along with the existing build job. ## Continuous Integration -To ensure our changes don't break the build and all tests still pass, we utilize +To ensure our changes don't break the build and all tests still pass, we use Continuous Integration (CI) to run these checks automatically for every push. Read through this article to understand [Continuous Integration, Continuous Delivery, and Continuous Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/), and how these methods are leveraged by GitLab. @@ -261,7 +261,7 @@ Please read through the [documentation on CI/CD configuration](../../../ci/yaml/ ### Build your game with GitLab CI/CD We need to update our build job to ensure tests get run as well. Add `gulp build-test` -to the end of the `script` array for the existing `build` job. Once these commands run, +to the end of the `script` array for the existing `build` job. After these commands run, we know we will need to access everything in the `built` folder, given by GitLab CI/CD's `artifacts`. We'll also cache `node_modules` to avoid having to do a full re-pull of those dependencies: just pack them up in the cache. Here is the full `build` job: 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 aa6e6f73a0d..42725e8aef9 100644 --- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -14,7 +14,7 @@ environment, reducing the effort to assess the impact of changes. Thus, when we and it will immediately be clear that the application can still be properly built and deployed. After all, you can _see_ it running! -<img src="img/deployed_dependency_update.png" alt="dependencies.io" class="image-noshadow"> +<img src="img/deployed_dependency_update.png" alt="dependencies.io"> However, looking at the freshly deployed code to check whether it still looks and behaves as expected is repetitive manual work, which means it is a prime candidate for automation. This is @@ -140,7 +140,7 @@ new browser window interacting with your app as you specified. Which brings us to the exciting part: how do we run this in GitLab CI/CD? There are two things we need to do for this: -1. Set up [CI/CD jobs](../../yaml/README.md#introduction) that actually have a browser available. +1. Set up [CI/CD jobs](../../yaml/README.md) that actually have a browser available. 1. Update our WebdriverIO configuration to use those browsers to visit the review apps. For the scope of this article, we've defined an additional [CI/CD stage](../../yaml/README.md#stages) 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 aaa34afeddf..f692a8042f5 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -632,7 +632,7 @@ After our code passed through the pipeline successfully, we can deploy to our pr  -Once the deploy pipeline passed successfully, navigate to **Pipelines > Environments**. +After the deploy pipeline passed successfully, navigate to **Pipelines > Environments**.  diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md index c62f0dec598..9bc9ac5423e 100644 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md @@ -298,7 +298,7 @@ project. - mix ecto.migrate ``` - This ensures that [rebar3](https://www.rebar3.org) and [hex](https://hex.pm) are both installed + This ensures that [rebar3](https://rebar3.org) and [hex](https://hex.pm) are both installed before attempting to fetch the dependencies that are required to run the tests. Next, the `postgres` db is created and migrated with `ecto`, to ensure it's up-to-date. diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index 5bcfe8fa3f1..c28febd15d7 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -78,7 +78,7 @@ correctly with your CI jobs: GIT_SUBMODULE_STRATEGY: recursive ``` - See the [`.gitlab-ci.yml` reference](yaml/README.md#git-submodule-strategy) + See the [GitLab Runner documentation](runners/README.md#git-submodule-strategy) for more details about `GIT_SUBMODULE_STRATEGY`. 1. If you are using an older version of `gitlab-runner`, then use diff --git a/doc/ci/interactive_web_terminal/img/interactive_web_terminal_running_job.png b/doc/ci/interactive_web_terminal/img/interactive_web_terminal_running_job.png Binary files differindex 3ee5e39afc0..8082d17ae6a 100644 --- a/doc/ci/interactive_web_terminal/img/interactive_web_terminal_running_job.png +++ b/doc/ci/interactive_web_terminal/img/interactive_web_terminal_running_job.png diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 125e7dabecf..a131d21039d 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -16,7 +16,7 @@ is deployed, some [security precautions](../../administration/integration/termin taken to protect the users. NOTE: **Note:** -[Shared runners on GitLab.com](../quick_start/README.md#shared-runners) do not +[Shared runners on GitLab.com](../runners/README.md#shared-runners) do not provide an interactive web terminal. Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/24674) for progress on adding support. For groups and projects hosted on GitLab.com, interactive web diff --git a/doc/ci/introduction/img/gitlab_workflow_example_11_9.png b/doc/ci/introduction/img/gitlab_workflow_example_11_9.png Binary files differindex f3fb9444b55..1f11db55f81 100644 --- a/doc/ci/introduction/img/gitlab_workflow_example_11_9.png +++ b/doc/ci/introduction/img/gitlab_workflow_example_11_9.png diff --git a/doc/ci/introduction/img/job_running.png b/doc/ci/introduction/img/job_running.png Binary files differindex d5f922ceb8c..efd138fd4f8 100644 --- a/doc/ci/introduction/img/job_running.png +++ b/doc/ci/introduction/img/job_running.png diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index d1f3e449e5b..b24ee66fdba 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/index.md @@ -17,6 +17,14 @@ Out-of-the-box management systems can decrease hours spent on maintaining toolch Watch our ["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/) webcast to learn about continuous methods and how GitLab’s built-in CI can help you simplify and scale software development. +> For some additional information about GitLab CI/CD: +> +> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch the [CI/CD Ease of configuration](https://www.youtube.com/embed/opdLqwz6tcE) video. +> - Watch the [Making the case for CI/CD in your organization](https://about.gitlab.com/compare/github-actions-alternative/) +> webcast to learn the benefits of CI/CD and how to measure the results of CI/CD automation. +> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Learn how [Verizon reduced rebuilds](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/) +> from 30 days to under 8 hours with GitLab. + ## Introduction to CI/CD methodologies The continuous methodologies of software development are based on @@ -93,7 +101,7 @@ In this file, you can define the scripts you want to run, define include and cache dependencies, choose commands you want to run in sequence and those you want to run in parallel, define where you want to deploy your app, and specify whether you will want to run the scripts automatically -or trigger any of them manually. Once you're familiar with +or trigger any of them manually. After you're familiar with GitLab CI/CD you can add more advanced steps into the configuration file. To add scripts to that file, you'll need to organize them in a @@ -102,7 +110,7 @@ the tests you wish to perform. To visualize the process, imagine that all the scripts you add to the configuration file are the same as the commands you run on a terminal on your computer. -Once you've added your `.gitlab-ci.yml` configuration file to your +After you've added your `.gitlab-ci.yml` configuration file to your repository, GitLab will detect it and run your scripts with the tool called [GitLab Runner](https://docs.gitlab.com/runner/), which works similarly to your terminal. @@ -149,7 +157,7 @@ Consider the following example for how GitLab CI/CD fits in a common development workflow. Assume that you have discussed a code implementation in an issue -and worked locally on your proposed changes. Once you push your +and worked locally on your proposed changes. After you push your commits to a feature branch in a remote repository in GitLab, the CI/CD pipeline set for your project is triggered. By doing so, GitLab CI/CD: @@ -159,7 +167,7 @@ so, GitLab CI/CD: - Preview the changes per merge request with Review Apps, as you would see in your `localhost`. -Once you're happy with your implementation: +After you're happy with your implementation: - Get your code reviewed and approved. - Merge the feature branch into the default branch. diff --git a/doc/ci/pipelines/img/collapsible_log_v12_6.png b/doc/ci/jobs/img/collapsible_log_v12_6.png Binary files differindex a1e9aeb244a..a1e9aeb244a 100644 --- a/doc/ci/pipelines/img/collapsible_log_v12_6.png +++ b/doc/ci/jobs/img/collapsible_log_v12_6.png diff --git a/doc/ci/pipelines/img/job_failure_reason.png b/doc/ci/jobs/img/job_failure_reason.png Binary files differindex d44b8e6d1be..d44b8e6d1be 100644 --- a/doc/ci/pipelines/img/job_failure_reason.png +++ b/doc/ci/jobs/img/job_failure_reason.png diff --git a/doc/ci/pipelines/img/job_group_v12_10.png b/doc/ci/jobs/img/job_group_v12_10.png Binary files differindex 27e6bfbfc0f..27e6bfbfc0f 100644 --- a/doc/ci/pipelines/img/job_group_v12_10.png +++ b/doc/ci/jobs/img/job_group_v12_10.png diff --git a/doc/ci/jobs/img/manual_job_variables.png b/doc/ci/jobs/img/manual_job_variables.png Binary files differnew file mode 100644 index 00000000000..63801ade21f --- /dev/null +++ b/doc/ci/jobs/img/manual_job_variables.png diff --git a/doc/ci/pipelines/img/pipeline_incremental_rollout.png b/doc/ci/jobs/img/pipeline_incremental_rollout.png Binary files differindex b3498e9a5a5..b3498e9a5a5 100644 --- a/doc/ci/pipelines/img/pipeline_incremental_rollout.png +++ b/doc/ci/jobs/img/pipeline_incremental_rollout.png diff --git a/doc/ci/pipelines/img/pipelines_grouped.png b/doc/ci/jobs/img/pipelines_grouped.png Binary files differindex 82814754747..82814754747 100644 --- a/doc/ci/pipelines/img/pipelines_grouped.png +++ b/doc/ci/jobs/img/pipelines_grouped.png diff --git a/doc/ci/pipelines/img/pipelines_mini_graph_sorting.png b/doc/ci/jobs/img/pipelines_mini_graph_sorting.png Binary files differindex 3a4e5453360..3a4e5453360 100644 --- a/doc/ci/pipelines/img/pipelines_mini_graph_sorting.png +++ b/doc/ci/jobs/img/pipelines_mini_graph_sorting.png diff --git a/doc/ci/jobs/index.md b/doc/ci/jobs/index.md new file mode 100644 index 00000000000..dc306ac7ecb --- /dev/null +++ b/doc/ci/jobs/index.md @@ -0,0 +1,251 @@ +--- +stage: Verify +group: Continuous Integration +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Jobs + +Pipeline configuration begins with jobs. Jobs are the most fundamental element of a `.gitlab-ci.yml` file. + +Jobs are: + +- Defined with constraints stating under what conditions they should be executed. +- Top-level elements with an arbitrary name and must contain at least the [`script`](../yaml/README.md#script) clause. +- Not limited in how many can be defined. + +For example: + +```yaml +job1: + script: "execute-script-for-job1" + +job2: + script: "execute-script-for-job2" +``` + +The above example is the simplest possible CI/CD configuration with two separate +jobs, where each of the jobs executes a different command. +Of course a command can execute code directly (`./configure;make;make install`) +or run a script (`test.sh`) in the repository. + +Jobs are picked up by [runners](../runners/README.md) and executed within the +environment of the runner. What is important is that each job is run +independently from each other. + +## View jobs in a pipeline + +When you access a pipeline, you can see the related jobs for that pipeline. + +Clicking an individual job shows you its job log, and allows you to: + +- Cancel the job. +- Retry the job. +- Erase the job log. + +## See why a job failed + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17782) in GitLab 10.7. + +When a pipeline fails or is allowed to fail, there are several places where you +can find the reason: + +- In the [pipeline graph](../pipelines/index.md#visualize-pipelines), on the pipeline detail view. +- In the pipeline widgets, in the merge requests and commit pages. +- In the job views, in the global and detailed views of a job. + +In each place, if you hover over the failed job you can see the reason it failed. + + + +In [GitLab 10.8](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17814) and later, +you can also see the reason it failed on the Job detail page. + +## The order of jobs in a pipeline + +The order of jobs in a pipeline depends on the type of pipeline graph. + +- For [regular pipeline graphs](../pipelines/index.md#regular-pipeline-graphs), jobs are sorted by name. +- For [pipeline mini graphs](../pipelines/index.md#pipeline-mini-graphs), jobs are sorted by severity and then by name. + +The order of severity is: + +- failed +- warning +- pending +- running +- manual +- scheduled +- canceled +- success +- skipped +- created + +For example: + + + +## Group jobs in a pipeline + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6242) in GitLab 8.12. + +If you have many similar jobs, your [pipeline graph](../pipelines/index.md#visualize-pipelines) becomes long and hard +to read. + +You can automatically group similar jobs together. If the job names are formatted in a certain way, +they are collapsed into a single group in regular pipeline graphs (not the mini graphs). + +You can recognize when a pipeline has grouped jobs if you don't see the retry or +cancel button inside them. Hovering over them shows the number of grouped +jobs. Click to expand them. + + + +To create a group of jobs, in the [CI/CD pipeline configuration file](../yaml/README.md), +separate each job name with a number and one of the following: + +- A slash (`/`), for example, `test 1/3`, `test 2/3`, `test 3/3`. +- A colon (`:`), for example, `test 1:3`, `test 2:3`, `test 3:3`. +- A space, for example `test 0 3`, `test 1 3`, `test 2 3`. + +You can use these symbols interchangeably. + +In the example below, these three jobs are in a group named `build ruby`: + +```yaml +build ruby 1/3: + stage: build + script: + - echo "ruby1" + +build ruby 2/3: + stage: build + script: + - echo "ruby2" + +build ruby 3/3: + stage: build + script: + - echo "ruby3" +``` + +In the pipeline, the result is a group named `build ruby` with three jobs: + + + +The jobs are be ordered by comparing the numbers from left to right. You +usually want the first number to be the index and the second number to be the total. + +[This regular expression](https://gitlab.com/gitlab-org/gitlab/blob/2f3dc314f42dbd79813e6251792853bc231e69dd/app/models/commit_status.rb#L99) +evaluates the job names: `\d+[\s:\/\\]+\d+\s*`. + +## Specifying variables when running manual jobs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30485) in GitLab 12.2. + +When running manual jobs you can supply additional job specific variables. + +You can do this from the job page of the manual job you want to run with +additional variables. To access this page, click on the **name** of the manual job in +the pipeline view, *not* the play (**{play}**) button. + +This is useful when you want to alter the execution of a job that uses +[custom environment variables](../variables/README.md#custom-environment-variables). +Add a variable name (key) and value here to override the value defined in +[the UI or `.gitlab-ci.yml`](../variables/README.md#custom-environment-variables), +for a single run of the manual job. + + + +## Delay a job + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21767) in GitLab 11.4. + +When you do not want to run a job immediately, you can use the [`when:delayed`](../yaml/README.md#whendelayed) keyword to +delay a job's execution for a certain period. + +This is especially useful for timed incremental rollout where new code is rolled out gradually. + +For example, if you start rolling out new code and: + +- Users do not experience trouble, GitLab can automatically complete the deployment from 0% to 100%. +- Users experience trouble with the new code, you can stop the timed incremental rollout by canceling the pipeline + and [rolling](../environments/index.md#retrying-and-rolling-back) back to the last stable version. + + + +## Expand and collapse job log sections + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14664) in GitLab 12.0. + +Job logs are divided into sections that can be collapsed or expanded. Each section displays +the duration. + +In the following example: + +- Two sections are collapsed and can be expanded. +- Three sections are expanded and can be collapsed. + + + +### Custom collapsible sections + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14664) in GitLab 12.0. + +You can create [collapsible sections in job logs](#expand-and-collapse-job-log-sections) +by manually outputting special codes +that GitLab uses to determine what sections to collapse: + +- Section start marker: `section_start:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` + `TEXT_OF_SECTION_HEADER` +- Section end marker: `section_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` + +You must add these codes to the script section of the CI configuration. For example, +using `echo`: + +```yaml +job1: + script: + - echo -e "section_start:`date +%s`:my_first_section\r\e[0KHeader of the 1st collapsible section" + - echo 'this line should be hidden when collapsed' + - echo -e "section_end:`date +%s`:my_first_section\r\e[0K" +``` + +In the example above: + +- `date +%s`: The Unix timestamp (for example `1560896352`). +- `my_first_section`: The name given to the section. +- `\r\e[0K`: Prevents the section markers from displaying in the rendered (colored) + job log, but they are displayed in the raw job log. To see them, in the top right + of the job log, click **{doc-text}** (**Show complete raw**). + - `\r`: carriage return. + - `\e[0K`: clear line ANSI escape code. + +Sample raw job log: + +```plaintext +section_start:1560896352:my_first_section\r\e[0KHeader of the 1st collapsible section +this line should be hidden when collapsed +section_end:1560896353:my_first_section\r\e[0K +``` + +### Pre-collapse sections + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198413) in GitLab 13.5. + +You can make the job log automatically collapse collapsible sections by adding the `collapsed` option to the section start. +Add `[collapsed=true]` after the section name and before the `\r`. The section end marker +remains unchanged: + +- Section start marker with `[collapsed=true]`: `section_start:UNIX_TIMESTAMP:SECTION_NAME[collapsed=true]\r\e[0K` + `TEXT_OF_SECTION_HEADER` +- Section end marker: `section_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` + +Add the updated section start text to the CI configuration. For example, +using `echo`: + +```yaml +job1: + script: + - echo -e "section_start:`date +%s`:my_first_section[collapsed=true]\r\e[0KHeader of the 1st collapsible section" + - echo 'this line should be hidden automatically after loading the job log' + - echo -e "section_end:`date +%s`:my_first_section\r\e[0K" +``` diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md index 0019eb5f40c..f25ef7c725a 100644 --- a/doc/ci/large_repositories/index.md +++ b/doc/ci/large_repositories/index.md @@ -56,29 +56,16 @@ test: > Introduced in GitLab Runner 8.9. -By default, GitLab is configured to always prefer the `GIT_STRATEGY: fetch` strategy. -The `GIT_STRATEGY: fetch` strategy will re-use existing worktrees if found -on disk. This is different to the `GIT_STRATEGY: clone` strategy -as in case of clones, if a worktree is found, it is removed before clone. - -Usage of `fetch` is preferred because it reduces the amount of data to transfer and +By default, GitLab is configured to use the [`fetch` Git strategy](../runners/README.md#git-strategy), +which is recommended for large repositories. +This strategy reduces the amount of data to transfer and does not really impact the operations that you might do on a repository from CI. -However, `fetch` does require access to the previous worktree. This works -well when using the `shell` or `docker` executor because these -try to preserve worktrees and try to re-use them by default. - -This does not work today for `kubernetes` executor and has limitations when using -`docker+machine`. `kubernetes` executor today always clones into ephemeral directory. - -GitLab also offers the `GIT_STRATEGY: none` strategy. This disables any `fetch` and `checkout` commands -done by GitLab, requiring you to do them. - ## Git clone path > Introduced in GitLab Runner 11.10. -[`GIT_CLONE_PATH`](../yaml/README.md#custom-build-directories) allows you to +[`GIT_CLONE_PATH`](../runners/README.md#custom-build-directories) allows you to control where you clone your sources. This can have implications if you heavily use big repositories with fork workflow. @@ -90,7 +77,7 @@ In such cases, ideally you want to make the GitLab Runner executor be used only for the given project and not shared across different projects to make this process more efficient. -The [`GIT_CLONE_PATH`](../yaml/README.md#custom-build-directories) has to be +The [`GIT_CLONE_PATH`](../runners/README.md#custom-build-directories) has to be within the `$CI_BUILDS_DIR`. Currently, it is impossible to pick any path from disk. @@ -98,12 +85,12 @@ from disk. > Introduced in GitLab Runner 11.10. -[`GIT_CLEAN_FLAGS`](../yaml/README.md#git-clean-flags) allows you to control +[`GIT_CLEAN_FLAGS`](../runners/README.md#git-clean-flags) allows you to control whether or not you require the `git clean` command to be executed for each CI job. By default, GitLab ensures that you have your worktree on the given SHA, and that your repository is clean. -[`GIT_CLEAN_FLAGS`](../yaml/README.md#git-clean-flags) is disabled when set +[`GIT_CLEAN_FLAGS`](../runners/README.md#git-clean-flags) is disabled when set to `none`. On very big repositories, this might be desired because `git clean` is disk I/O intensive. Controlling that with `GIT_CLEAN_FLAGS: -ffdx -e .build/` (for example) allows you to control and disable removal of some @@ -112,7 +99,7 @@ the incremental builds. This has the biggest effect if you re-use existing machines and have an existing worktree that you can re-use for builds. For exact parameters accepted by -[`GIT_CLEAN_FLAGS`](../yaml/README.md#git-clean-flags), see the documentation +[`GIT_CLEAN_FLAGS`](../runners/README.md#git-clean-flags), see the documentation for [`git clean`](https://git-scm.com/docs/git-clean). The available parameters are dependent on Git version. @@ -120,14 +107,14 @@ are dependent on Git version. > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4142) in GitLab Runner 13.1. -[`GIT_FETCH_EXTRA_FLAGS`](../yaml/README.md#git-fetch-extra-flags) allows you +[`GIT_FETCH_EXTRA_FLAGS`](../runners/README.md#git-fetch-extra-flags) allows you to modify `git fetch` behavior by passing extra flags. For example, if your project contains a large number of tags that your CI jobs don't rely on, you could add [`--no-tags`](https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---no-tags) to the extra flags to make your fetches faster and more compact. -See the [`GIT_FETCH_EXTRA_FLAGS` documentation](../yaml/README.md#git-fetch-extra-flags) +See the [`GIT_FETCH_EXTRA_FLAGS` documentation](../runners/README.md#git-fetch-extra-flags) for more information. ## Fork-based workflow diff --git a/doc/ci/lint.md b/doc/ci/lint.md index 716a4218d97..cef71a68d72 100644 --- a/doc/ci/lint.md +++ b/doc/ci/lint.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # CI Lint If you want to test the validity of your GitLab CI/CD configuration before committing @@ -11,7 +17,8 @@ in your project and click **CI lint**. ## Validate basic logic and syntax By default, the CI lint checks the syntax of your CI YAML configuration and also runs -some basic logical validations. +some basic logical validations. Configuration added with the [`includes` keyword](yaml/README.md#include), +is also validated. To use the CI lint, paste a complete CI configuration (`.gitlab-ci.yml` for example) into the text box and click **Validate**: diff --git a/doc/ci/merge_request_pipelines/img/merge_request_pipelines_doubled_MR_v12_09.png b/doc/ci/merge_request_pipelines/img/merge_request_pipelines_doubled_MR_v12_09.png Binary files differdeleted file mode 100644 index 3e4c72b9279..00000000000 --- a/doc/ci/merge_request_pipelines/img/merge_request_pipelines_doubled_MR_v12_09.png +++ /dev/null diff --git a/doc/ci/merge_request_pipelines/img/merge_request_pipelines_doubled_branch_v12_09.png b/doc/ci/merge_request_pipelines/img/merge_request_pipelines_doubled_branch_v12_09.png Binary files differdeleted file mode 100644 index dd70c3f8c20..00000000000 --- a/doc/ci/merge_request_pipelines/img/merge_request_pipelines_doubled_branch_v12_09.png +++ /dev/null diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index cc0b4ac1f86..ac9cda4e46c 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -56,7 +56,7 @@ below. When you use this method, you have to specify `only: - merge_requests` for each job. In this example, the pipeline contains a `test` job that is configured to run on merge requests. -The `build` and `deploy` jobs don't have the `only: - merge_requests` parameter, +The `build` and `deploy` jobs don't have the `only: - merge_requests` keyword, so they will not run on merge requests. ```yaml @@ -81,8 +81,8 @@ deploy: #### Excluding certain jobs -The behavior of the `only: [merge_requests]` parameter is such that _only_ jobs with -that parameter are run in the context of a merge request; no other jobs will be run. +The behavior of the `only: [merge_requests]` keyword is such that _only_ jobs with +that keyword are run in the context of a merge request; no other jobs will be run. However, you can invert this behavior and have all of your jobs run _except_ for one or two. diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline_config.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline_config.png Binary files differdeleted file mode 100644 index 3ee9d8ec93b..00000000000 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline_config.png +++ /dev/null diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md index 2330bdb4c7c..9c6fbba1337 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md @@ -56,7 +56,7 @@ To enable pipelines for merged results for your project: 1. [Configure your CI/CD configuration file](../index.md#configuring-pipelines-for-merge-requests) so that the pipeline or individual jobs run for merge requests. 1. Visit your project's **Settings > General** and expand **Merge requests**. -1. Check **Enable merge trains and pipelines for merged results**. +1. Check **Enable merged results pipelines.**. 1. Click **Save changes**. CAUTION: **Caution:** diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_config_v12_0.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_config_v12_0.png Binary files differdeleted file mode 100644 index 9da959ad440..00000000000 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_config_v12_0.png +++ /dev/null diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_immediate_merge.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_immediate_merge.png Binary files differdeleted file mode 100644 index 03bc61129ba..00000000000 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_immediate_merge.png +++ /dev/null diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md index 45cae49377f..d4099cdeafd 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md @@ -82,9 +82,13 @@ To enable merge trains for your project: 1. If you are on a self-managed GitLab instance, ensure the [feature flag](#merge-trains-feature-flag) is set correctly. 1. [Configure your CI/CD configuration file](../../index.md#configuring-pipelines-for-merge-requests) so that the pipeline or individual jobs run for merge requests. -1. Visit your project's **Settings > General** and expand **Merge requests**. -1. Check **Enable merge trains and pipelines for merged results**. -1. Click **Save changes**. +1. Visit your project's **Settings > General** and expand **Merge requests** +1. Check **Enable merged results pipelines.** (if not enabled) +1. Check **Enable merge trains.** +1. Click **Save changes** + +In GitLab 13.5 and earlier, there is only one checkbox, named +**Enable merge trains and pipelines for merged results**. CAUTION: **Caution:** If you select the check box but don't configure your CI/CD to use @@ -200,17 +204,26 @@ for more information. ### Merge Trains feature flag **(PREMIUM ONLY)** -To enable and disable the Merge Trains feature, use the `:disable_merge_trains` feature flag. +In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/244831), +you can [enable or disable merge trains in the project settings](#enable-merge-trains). + +In GitLab 13.5 and earlier, merge trains are automatically enabled when +[pipelines for merged results](../index.md#pipelines-for-merged-results) are enabled. +To use pipelines for merged results without using merge trains, you can enable a +[feature flag](../../../../user/feature_flags.md) that blocks the merge trains feature. -To check if the feature flag is enabled on your GitLab instance, -ask an administrator to execute the following commands: +[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md) +can enable the feature flag to disable merge trains: -```shell -> sudo gitlab-rails console # Login to Rails console of GitLab instance. -> Feature.enabled?(:disable_merge_trains) # Check if it's disabled or not. -> Feature.enable(:disable_merge_trains) # Disable Merge Trains. -> Feature.disable(:disable_merge_trains) # Enable Merge Trains. +```ruby +Feature.enable(:disable_merge_trains) ``` -When you disable this feature, all existing merge trains are cancelled and +After you enable this feature flag, all existing merge trains are cancelled and the **Start/Add to Merge Train** button no longer appears in merge requests. + +To disable the feature flag, and enable merge trains again: + +```ruby +Feature.disable(:disable_merge_trains) +``` diff --git a/doc/ci/metrics_reports.md b/doc/ci/metrics_reports.md index 53e097760e6..dbc0397bb0b 100644 --- a/doc/ci/metrics_reports.md +++ b/doc/ci/metrics_reports.md @@ -17,7 +17,7 @@ You can configure your job to use custom Metrics Reports, and GitLab will displa ## Use cases -Consider the following examples of data that can utilize Metrics Reports: +Consider the following examples of data that can use Metrics Reports: 1. Memory usage 1. Load testing results diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md index 6de494bceaf..13190c15cca 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.md @@ -10,7 +10,7 @@ type: index, howto 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 -[CircleCI vs GitLab](https://about.gitlab.com/devops-tools/circle-ci-vs-gitlab.html) +[CircleCI vs GitLab](https://about.gitlab.com/devops-tools/circle-ci-vs-gitlab/) comparison to see what's different. We have collected several resources that you may find useful before starting to migrate. @@ -27,7 +27,7 @@ CircleCI's `config.yml` configuration file defines scripts, jobs, and workflows ### Jobs -In CircleCI, jobs are a collection of steps to perform a specific task. In GitLab, [jobs](../yaml/README.md#introduction) are also a fundamental element in the configuration file. The `checkout` parameter is not necessary in GitLab CI/CD as the repository is automatically fetched. +In CircleCI, jobs are a collection of steps to perform a specific task. In GitLab, [jobs](../jobs/index.md) are also a fundamental element in the configuration file. The `checkout` keyword is not necessary in GitLab CI/CD as the repository is automatically fetched. CircleCI example job definition: diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index 1130c11f472..afec94ca91c 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -258,7 +258,7 @@ stages: ``` Setting a step to be performed before and after any job can be done via the -[`before_script` and `after_script` keywords](../yaml/README.md#before_script-and-after_script): +[`before_script`](../yaml/README.md#before_script) and [`after_script`](../yaml/README.md#after_script) keywords: ```yaml default: diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index 378adcd35e9..5837bf6cf6b 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -305,7 +305,7 @@ Some features are not implemented yet. For example, support for environments. - `when` (only with `on_success`, `on_failure`, and `always` values) - `extends` -## Trigger a pipeline when an upstream project is rebuilt +## Trigger a pipeline when an upstream project is rebuilt **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9045) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. @@ -322,6 +322,9 @@ will now trigger a pipeline on the current project's default branch. The maximum number of upstream pipeline subscriptions is 2 by default, for both the upstream and downstream projects. This [application limit](../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) can be changed on self-managed instances by a GitLab administrator. +The upstream project needs to be [public](../public_access/public_access.md) for +pipeline subscription to work. + ## Downstream private projects confidentiality concern If you trigger a pipeline in a downstream private project, the name of the project diff --git a/doc/ci/pipelines/img/manual_job_variables.png b/doc/ci/pipelines/img/manual_job_variables.png Binary files differdeleted file mode 100644 index a5ed351fdcd..00000000000 --- a/doc/ci/pipelines/img/manual_job_variables.png +++ /dev/null diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index f7e3698b6d4..f22d2373e5f 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -68,7 +68,7 @@ Pipelines can be configured in many different ways: Pipelines and their component jobs and stages are defined in the CI/CD pipeline configuration file for each project. -- Jobs are the [basic configuration](../yaml/README.md#introduction) component. +- [Jobs](../jobs/index.md) are the basic configuration component. - Stages are defined by using the [`stages`](../yaml/README.md#stages) keyword. For a list of configuration options in the CI pipeline file, see the [GitLab CI/CD Pipeline Configuration Reference](../yaml/README.md). @@ -79,6 +79,27 @@ You can also configure specific aspects of your pipelines through the GitLab UI. - [Pipeline schedules](schedules.md). - [Custom CI/CD variables](../variables/README.md#custom-environment-variables). +### Ref Specs for Runners + +When a runner picks a pipeline job, GitLab provides that job's metadata. This includes the [Git refspecs](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec), +which indicate which ref (branch, tag, and so on) and commit (SHA1) are checked out from your +project repository. + +This table lists the refspecs injected for each pipeline type: + +| Pipeline type | Refspecs | +|--------------- |---------------------------------------- | +| Pipeline for Branches | `+refs/pipelines/<id>:refs/pipelines/<id>` and `+refs/heads/<name>:refs/remotes/origin/<name>` | +| pipeline for Tags | `+refs/pipelines/<id>:refs/pipelines/<id>` and `+refs/tags/<name>:refs/tags/<name>` | +| [Pipeline for Merge Requests](../merge_request_pipelines/index.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 +running pipeline job. This ref can be created even after the associated branch or tag has been +deleted. It's therefore useful in some features such as [automatically stopping an environment](../environments/index.md#automatically-stopping-an-environment), +and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md) +that might run pipelines after branch deletion. + ### View pipelines You can find the current and historical pipeline runs under your project's @@ -157,7 +178,7 @@ For each `var` or `file_var`, a key and value are required. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7931) in GitLab 8.15. -Manual actions, configured using the [`when:manual`](../yaml/README.md#whenmanual) parameter, +Manual actions, configured using the [`when:manual`](../yaml/README.md#whenmanual) keyword, allow you to require manual interaction before moving forward in the pipeline. You can do this straight from the pipeline graph. Just click the play button @@ -174,7 +195,7 @@ stage has a job with a manual action. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27188) in GitLab 11.11. Multiple manual actions in a single stage can be started at the same time using the "Play all manual" button. -Once you click this button, each individual manual action is triggered and refreshed +After you click this button, each individual manual action is triggered and refreshed to an updated status. This functionality is only available: @@ -266,223 +287,6 @@ preserving deployment keys and other credentials from being unintentionally accessed. In order to ensure that jobs intended to be executed on protected runners do not use regular runners, they must be tagged accordingly. -## View jobs in a pipeline - -When you access a pipeline, you can see the related jobs for that pipeline. - -Clicking an individual job shows you its job log, and allows you to: - -- Cancel the job. -- Retry the job. -- Erase the job log. - -### See why a job failed - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17782) in GitLab 10.7. - -When a pipeline fails or is allowed to fail, there are several places where you -can find the reason: - -- In the [pipeline graph](#visualize-pipelines), on the pipeline detail view. -- In the pipeline widgets, in the merge requests and commit pages. -- In the job views, in the global and detailed views of a job. - -In each place, if you hover over the failed job you can see the reason it failed. - - - -In [GitLab 10.8](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17814) and later, -you can also see the reason it failed on the Job detail page. - -### The order of jobs in a pipeline - -The order of jobs in a pipeline depends on the type of pipeline graph. - -- For [regular pipeline graphs](#regular-pipeline-graphs), jobs are sorted by name. -- For [pipeline mini graphs](#pipeline-mini-graphs), jobs are sorted by severity and then by name. - -The order of severity is: - -- failed -- warning -- pending -- running -- manual -- scheduled -- canceled -- success -- skipped -- created - -For example: - - - -### Group jobs in a pipeline - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6242) in GitLab 8.12. - -If you have many similar jobs, your [pipeline graph](#visualize-pipelines) becomes long and hard -to read. - -You can automatically group similar jobs together. If the job names are formatted in a certain way, -they are collapsed into a single group in regular pipeline graphs (not the mini graphs). - -You can recognize when a pipeline has grouped jobs if you don't see the retry or -cancel button inside them. Hovering over them shows the number of grouped -jobs. Click to expand them. - - - -To create a group of jobs, in the [CI/CD pipeline configuration file](../yaml/README.md), -separate each job name with a number and one of the following: - -- A slash (`/`), for example, `test 1/3`, `test 2/3`, `test 3/3`. -- A colon (`:`), for example, `test 1:3`, `test 2:3`, `test 3:3`. -- A space, for example `test 0 3`, `test 1 3`, `test 2 3`. - -You can use these symbols interchangeably. - -In the example below, these three jobs are in a group named `build ruby`: - -```yaml -build ruby 1/3: - stage: build - script: - - echo "ruby1" - -build ruby 2/3: - stage: build - script: - - echo "ruby2" - -build ruby 3/3: - stage: build - script: - - echo "ruby3" -``` - -In the pipeline, the result is a group named `build ruby` with three jobs: - - - -The jobs are be ordered by comparing the numbers from left to right. You -usually want the first number to be the index and the second number to be the total. - -[This regular expression](https://gitlab.com/gitlab-org/gitlab/blob/2f3dc314f42dbd79813e6251792853bc231e69dd/app/models/commit_status.rb#L99) -evaluates the job names: `\d+[\s:\/\\]+\d+\s*`. - -### Specifying variables when running manual jobs - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30485) in GitLab 12.2. - -When running manual jobs you can supply additional job specific variables. - -You can do this from the job page of the manual job you want to run with -additional variables. To access this page, click on the **name** of the manual job in -the pipeline view, *not* the play (**{play}**) button. - -This is useful when you want to alter the execution of a job that uses -[custom environment variables](../variables/README.md#custom-environment-variables). -Add a variable name (key) and value here to override the value defined in -[the UI or `.gitlab-ci.yml`](../variables/README.md#custom-environment-variables), -for a single run of the manual job. - - - -### Delay a job - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21767) in GitLab 11.4. - -When you do not want to run a job immediately, you can use the [`when:delayed`](../yaml/README.md#whendelayed) parameter to -delay a job's execution for a certain period. - -This is especially useful for timed incremental rollout where new code is rolled out gradually. - -For example, if you start rolling out new code and: - -- Users do not experience trouble, GitLab can automatically complete the deployment from 0% to 100%. -- Users experience trouble with the new code, you can stop the timed incremental rollout by canceling the pipeline - and [rolling](../environments/index.md#retrying-and-rolling-back) back to the last stable version. - - - -### Expand and collapse job log sections - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14664) in GitLab 12.0. - -Job logs are divided into sections that can be collapsed or expanded. Each section displays -the duration. - -In the following example: - -- Two sections are collapsed and can be expanded. -- Three sections are expanded and can be collapsed. - - - -#### Custom collapsible sections - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14664) in GitLab 12.0. - -You can create [collapsible sections in job logs](../pipelines/index.md#expand-and-collapse-job-log-sections) -by manually outputting special codes -that GitLab uses to determine what sections to collapse: - -- Section start marker: `section_start:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` + `TEXT_OF_SECTION_HEADER` -- Section end marker: `section_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` - -You must add these codes to the script section of the CI configuration. For example, -using `echo`: - -```yaml -job1: - script: - - echo -e "section_start:`date +%s`:my_first_section\r\e[0KHeader of the 1st collapsible section" - - echo 'this line should be hidden when collapsed' - - echo -e "section_end:`date +%s`:my_first_section\r\e[0K" -``` - -In the example above: - -- `date +%s`: The Unix timestamp (for example `1560896352`). -- `my_first_section`: The name given to the section. -- `\r\e[0K`: Prevents the section markers from displaying in the rendered (colored) - job log, but they are displayed in the raw job log. To see them, in the top right - of the job log, click **{doc-text}** (**Show complete raw**). - - `\r`: carriage return. - - `\e[0K`: clear line ANSI escape code. - -Sample raw job log: - -```plaintext -section_start:1560896352:my_first_section\r\e[0KHeader of the 1st collapsible section -this line should be hidden when collapsed -section_end:1560896353:my_first_section\r\e[0K -``` - -#### Pre-collapse sections - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198413) in GitLab 13.5. - -You can make the job log automatically collapse collapsible sections by adding the `collapsed` option to the section start. -Add `[collapsed=true]` after the section name and before the `\r`. The section end marker -remains unchanged: - -- Section start marker with `[collapsed=true]`: `section_start:UNIX_TIMESTAMP:SECTION_NAME[collapsed=true]\r\e[0K` + `TEXT_OF_SECTION_HEADER` -- Section end marker: `section_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` - -Add the updated section start text to the CI configuration. For example, -using `echo`: - -```yaml -job1: - script: - - echo -e "section_start:`date +%s`:my_first_section[collapsed=true]\r\e[0KHeader of the 1st collapsible section" - - echo 'this line should be hidden automatically after loading the job log' - - echo -e "section_end:`date +%s`:my_first_section\r\e[0K" -``` - ## Visualize pipelines > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5742) in GitLab 8.11. diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md index d904452a011..160399e4bc4 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -44,7 +44,7 @@ are relative to the repository that was cloned during the build. By default, the artifacts upload when the job succeeds. You can also set artifacts to upload when the job fails, or always, by using [`artifacts:when`](../yaml/README.md#artifactswhen) -parameter. GitLab keeps these uploaded artifacts for 1 week, as defined +keyword. GitLab keeps these uploaded artifacts for 1 week, as defined by the `expire_in` definition. You can keep the artifacts from expiring via the [web interface](#browsing-artifacts). If the expiry time is not defined, it defaults to the [instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration). @@ -114,7 +114,9 @@ There are a couple of exceptions to the [original dotenv rules](https://github.c - The variable key can contain only letters, digits, and underscores (`_`). - The maximum size of the `.env` file is 5 KB. -- The maximum number of variables is 10. +- In GitLab 13.5 and older, the maximum number of inherited variables is 10. +- In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/247913), + the maximum number of inherited variables is 20. - Variable substitution in the `.env` file is not supported. - The `.env` file can't have empty lines or comments (starting with `#`). - Key values in the `env` file cannot have spaces or newline characters (`\n`), including when using single or double quotes. @@ -137,10 +139,10 @@ third party ports for other languages like JavaScript, Python, Ruby, and so on. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207528) in GitLab 13.0. > - Requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 and above. -The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/index.md#output-terraform-plan-information-into-a-merge-request). The collected Terraform +The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/mr_integration.md#setup). The collected Terraform plan report uploads to GitLab as an artifact and displays in merge requests. For more information, see -[Output `terraform plan` information into a merge request](../../user/infrastructure/index.md#output-terraform-plan-information-into-a-merge-request). +[Output `terraform plan` information into a merge request](../../user/infrastructure/mr_integration.md). #### `artifacts:reports:codequality` @@ -414,7 +416,7 @@ information in the UI. ## Erasing artifacts -DANGER: **Danger:** +DANGER: **Warning:** This is a destructive action that leads to data loss. Use with caution. You can erase a single job via the UI, which also removes the job's diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index c4febba8f44..149c596430c 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -222,6 +222,8 @@ Methods to reduce Docker image size: - Create a dedicated development image. - Disable man pages and docs installed by packages to save space. - Reduce the `RUN` layers and combine software installation steps. +- Use [multi-stage builds](https://blog.alexellis.io/mutli-stage-docker-builds/) + to merge multiple Dockerfiles that use the builder pattern into one Dockerfile, which can reduce image size. - If using `apt`, add `--no-install-recommends` to avoid unnecessary packages. - Clean up caches and files that are no longer needed at the end. For example `rm -rf /var/lib/apt/lists/*` for Debian and Ubuntu, or `yum clean all` for RHEL and CentOS. diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md index bcdb7c4c8b6..9df73957293 100644 --- a/doc/ci/pipelines/schedules.md +++ b/doc/ci/pipelines/schedules.md @@ -85,10 +85,10 @@ job: ### Advanced configuration -The pipelines won't be executed exactly on schedule because schedules are handled by +The pipelines are not executed exactly on schedule because schedules are handled by Sidekiq, which runs according to its interval. -For example, only two pipelines will be created per day if: +For example, only two pipelines are created per day if: - You set a schedule to create a pipeline every minute (`* * * * *`). - The Sidekiq worker runs on 00:00 and 12:00 every day (`0 */12 * * *`). @@ -112,8 +112,8 @@ To trigger a pipeline schedule manually, click the "Play" button:  -This will schedule a background job to run the pipeline schedule. A flash -message will provide a link to the CI/CD Pipeline index page. +This schedules a background job to run the pipeline schedule. A flash +message provides a link to the CI/CD Pipeline index page. NOTE: **Note:** To help avoid abuse, users are rate limited to triggering a pipeline once per @@ -124,12 +124,12 @@ minute. Pipelines are executed as a user, who owns a schedule. This influences what projects and other resources the pipeline has access to. If a user does not own a pipeline, you can take ownership by clicking the **Take ownership** button. -The next time a pipeline is scheduled, your credentials will be used. +The next time a pipeline is scheduled, your credentials are used.  -If the owner of a pipeline schedule doesn't have the ability to create -pipelines on the target branch, the schedule will stop creating new +If the owner of a pipeline schedule does not have the ability to create +pipelines on the target branch, the schedule stops creating new pipelines. This can happen if, for example: diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index 143a5346e88..d2d2cb26256 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -26,10 +26,11 @@ There are two options. Using: - `git clone`, which is slower since it clones the repository from scratch for every job, ensuring that the local working copy is always pristine. -- `git fetch`, which is faster as it re-uses the local working copy (falling +- `git fetch`, which is GitLab's default and faster as it re-uses the local working copy (falling back to clone if it doesn't exist). + This is recommended, especially for [large repositories](../large_repositories/index.md#git-strategy). -The default Git strategy can be overridden by the [GIT_STRATEGY variable](../yaml/README.md#git-strategy) +The configured Git strategy can be overridden by the [`GIT_STRATEGY` variable](../runners/README.md#git-strategy) in `.gitlab-ci.yml`. ## Git shallow clone @@ -183,7 +184,7 @@ Job logs and artifacts are [not visible for guest users and non-project members] If **Public pipelines** is enabled (default): - For **public** projects, anyone can view the pipelines and related features. -- For **internal** projects, any logged in user can view the pipelines +- For **internal** projects, any logged in user except [external users](../../user/permissions.md#external-users) can view the pipelines and related features. - For **private** projects, any project member (guest or higher) can view the pipelines and related features. @@ -192,7 +193,7 @@ If **Public pipelines** is disabled: - For **public** projects, anyone can view the pipelines, but only members (reporter or higher) can access the related features. -- For **internal** projects, any logged in user can view the pipelines. +- For **internal** projects, any logged in user except [external users](../../user/permissions.md#external-users) can view the pipelines. However, only members (reporter or higher) can access the job related features. - For **private** projects, only project members (reporter or higher) can view the pipelines or access the related features. @@ -231,6 +232,16 @@ When enabled, any older deployments job are skipped when a new deployment starts For more information, see [Deployment safety](../environments/deployment_safety.md). +## Retry outdated jobs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211339) in GitLab 13.6. + +A deployment job can fail because a newer one has run. If you retry the failed deployment job, the +environment could be overwritten with older source code. If you click **Retry**, a modal warns you +about this and asks for confirmation. + +For more information, see [Deployment safety](../environments/deployment_safety.md). + ## Pipeline Badges In the pipelines settings page you can find pipeline status and test coverage diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 246430a6458..f3e60fae13a 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -5,224 +5,153 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Getting started with GitLab CI/CD +# Get started with GitLab CI/CD -GitLab offers a [continuous integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) service. For each commit or push to trigger your CI -[pipeline](../pipelines/index.md), you must: +Use this document to get started with +GitLab [continuous integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/). -- Add a [`.gitlab-ci.yml` file](#creating-a-gitlab-ciyml-file) to your repository's root directory. -- Ensure your project is configured to use a [runner](#configuring-a-runner). +Before you start, make sure you have: -The `.gitlab-ci.yml` file tells the runner what to do. A simple pipeline commonly has -three [stages](../yaml/README.md#stages): +- A project in GitLab that you would like to use CI/CD for. +- Maintainer or owner access for the project. -- `build` -- `test` -- `deploy` +If you are migrating from another CI/CD tool, view this documentation: -You do not need to use all three stages; stages with no jobs are ignored. +- [Migrate from CircleCI](../migration/circleci.md). +- [Migrate from Jenkins](../migration/jenkins.md). -The pipeline appears under the project's **CI/CD > Pipelines** page. If everything runs OK (no non-zero -return values), you get a green check mark associated with the commit. This makes it easy to see -whether a commit caused any of the tests to fail before you even look at the job (test) log. Many projects use -GitLab's CI service to run the test suite, so developers get immediate feedback if they broke -something. +## CI/CD process overview -It's also common to use pipelines to automatically deploy -tested code to staging and production environments. +To use GitLab CI/CD: -If you're already familiar with general CI/CD concepts, you can review which -[pipeline architectures](../pipelines/pipeline_architectures.md) can be used -in your projects. If you're coming over to GitLab from Jenkins, you can check out -our [reference](../migration/jenkins.md) for converting your pre-existing pipelines -over to our format. +1. [Ensure you have runners available](#ensure-you-have-runners-available) to run your jobs. + If you don't have a runner, [install GitLab Runner](https://docs.gitlab.com/runner/install/) + and [register a runner](https://docs.gitlab.com/runner/register/) for your instance, project, or group. +1. [Create a `.gitlab-ci.yml` file](#create-a-gitlab-ciyml-file) + at the root of your repository. This file is where you define your CI/CD jobs. -This guide assumes that you have: +When you commit the file to your repository, the runner runs your jobs. +The job results [are displayed in a pipeline](#view-the-status-of-your-pipeline-and-jobs). -- A working GitLab instance of version 8.0+ or are using - [GitLab.com](https://gitlab.com). -- A project in GitLab that you would like to use CI for. -- Maintainer or owner access to the project +### Ensure you have runners available -Let's break it down to pieces and work on solving the GitLab CI/CD puzzle. +In GitLab, runners are agents that run your CI/CD jobs. -## Creating a `.gitlab-ci.yml` file +You might already have runners available for your project, including +[shared runners](../runners/README.md#shared-runners), which are +available to all projects in your GitLab instance. -Before you create `.gitlab-ci.yml` let's first explain in brief what this is -all about. +To view available runners: -### What is `.gitlab-ci.yml` +- Go to **Settings > CI/CD** and expand **Runners**. -The `.gitlab-ci.yml` file is where you configure what CI does with your project. -It lives in the root of your repository. +As long as you have at least one runner that's active, with a green circle next to it, +you have a runner available to process your jobs. -On any push to your repository, GitLab will look for the `.gitlab-ci.yml` -file and start jobs on _runners_ according to the contents of the file, -for that commit. +If no runners are listed on the **Runners** page in the UI, you or an administrator +must [install GitLab Runner](https://docs.gitlab.com/runner/install/) and +[register](https://docs.gitlab.com/runner/register/) at least one runner. -Because `.gitlab-ci.yml` is in the repository and is version controlled, old -versions still build successfully, forks can easily make use of CI, branches can -have different pipelines and jobs, and you have a single source of truth for CI. -You can read more about the reasons why we are using `.gitlab-ci.yml` [in our -blog about it](https://about.gitlab.com/blog/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/). +If you are testing CI/CD, you can install GitLab Runner and register runners on your local machine. +When your CI/CD jobs run, they will run on your local machine. -### Creating a simple `.gitlab-ci.yml` file +### Create a `.gitlab-ci.yml` file -You need to create a file named `.gitlab-ci.yml` in the root directory of your -repository. This is a [YAML](https://en.wikipedia.org/wiki/YAML) file -so you have to pay extra attention to indentation. Always use spaces, not tabs. +The `.gitlab-ci.yml` file is a [YAML](https://en.wikipedia.org/wiki/YAML) file where +you configure specific instructions for GitLab CI/CD. -Below is an example for a Ruby on Rails project: +In this file, you define: -```yaml -default: - image: ruby:2.5 - before_script: - - apt-get update - - apt-get install -y sqlite3 libsqlite3-dev nodejs - - ruby -v - - which ruby - - gem install bundler --no-document - - bundle install --jobs $(nproc) "${FLAGS[@]}" +- The structure and order of jobs that the runner should execute. +- The decisions the runner should make when specific conditions are encountered. -rspec: - script: - - bundle exec rspec +For example, you might want to run a suite of tests when you commit to +any branch except `master`. When you commit to `master`, you want +to run the same suite, but also publish your application. -rubocop: - script: - - bundle exec rubocop -``` +All of this is defined in the `.gitlab-ci.yml` file. -This is the simplest possible configuration that will work for most Ruby -applications: +To create a `.gitlab-ci.yml` file: -1. Define two jobs `rspec` and `rubocop` (the names are arbitrary) with - different commands to be executed. -1. Before every job, the commands defined by `before_script` are executed. +1. Go to **Project overview > Details**. +1. Above the file list, select the branch you want to commit to, + click the plus icon, then select **New file**: -The `.gitlab-ci.yml` file defines sets of jobs with constraints of how and when -they should be run. The jobs are defined as top-level elements with a name (in -our case `rspec` and `rubocop`) and always have to contain the `script` keyword. -Jobs are used to create jobs, which are then picked by -[runners](../runners/README.md) and executed within the environment of the runner. +  -What is important is that each job is run independently from each other. +1. For the **File name** type `.gitlab-ci.yml` and in the larger window, + paste this sample code: -If you want to check whether the `.gitlab-ci.yml` of your project is valid, there is a -[CI Lint tool](../lint.md) available in every project. + ```yaml + build-job: + stage: build + script: + - echo "Hello, $GITLAB_USER_LOGIN!" -You can use the [CI/CD configuration visualization](../yaml/visualization.md) to -see a graphical representation of your `.gitlab-ci.yml`. + test-job1: + stage: test + script: + - echo "This job tests something" -For more information and a complete `.gitlab-ci.yml` syntax, please read -[the reference documentation on `.gitlab-ci.yml`](../yaml/README.md). + test-job2: + stage: test + script: + - echo "This job tests something, but takes more time than test-job1." + - echo "After the echo commands complete, it runs the sleep command for 20 seconds" + - echo "which simulates a test that runs 20 seconds longer than test-job1" + - sleep 20 -TIP: **Tip:** -A GitLab team member has made an [unofficial visual pipeline editor](https://unofficial.gitlab.tools/visual-pipelines/). -There is a [plan to make it an official part of GitLab](https://gitlab.com/groups/gitlab-org/-/epics/4069) -in the future, but it's available for anyone who wants to try it at the above link. + deploy-prod: + stage: deploy + script: + - echo "This job deploys something from the $CI_COMMIT_BRANCH branch." + ``` -### Push `.gitlab-ci.yml` to GitLab + `$GITLAB_USER_LOGIN` and `$CI_COMMIT_BRANCH` are + [predefined variables](../variables/predefined_variables.md) + that populate when the job runs. -Once you've created `.gitlab-ci.yml`, you should add it to your Git repository -and push it to GitLab. +1. Click **Commit changes**. -```shell -git add .gitlab-ci.yml -git commit -m "Add .gitlab-ci.yml" -git push origin master -``` +The pipeline starts when the commit is committed. -Now if you go to the **Pipelines** page you will see that the pipeline is -pending. +#### `.gitlab-ci.yml` tips -NOTE: **Note:** -If you have a [mirrored repository where GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository), -you may need to enable pipeline triggering in your project's -**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. +- If you want the runner to use a Docker image to run the jobs, edit the `.gitlab-ci.yml` file + to include your image name: -You can also go to the **Commits** page and notice the little pause icon next -to the commit SHA. + ```yaml + default: + image: ruby:2.7.2 + ``` - + This command tells the runner to use a Ruby image from Docker Hub. -Clicking on it you will be directed to the jobs page for that specific commit. +- To validate your `.gitlab-ci.yml` file, use the + [CI Lint tool](../lint.md), which is available in every project. +- You can also use [CI/CD configuration visualization](../yaml/visualization.md) to + view a graphical representation of your `.gitlab-ci.yml` file. +- For the complete `.gitlab-ci.yml` syntax, see + [the `.gitlab-ci.yml` reference topic](../yaml/README.md). - +### View the status of your pipeline and jobs -Notice that there is a pending job which is named after what we wrote in -`.gitlab-ci.yml`. "stuck" indicates that there is no runner configured -yet for this job. +When you committed your changes, a pipeline started. -The next step is to configure a runner so that it picks the pending jobs. +To view your pipeline: -## Configuring a runner +- Go **CI/CD > Pipelines**. -In GitLab, runners run the jobs that you define in `.gitlab-ci.yml`. A runner -can be a virtual machine, a VPS, a bare-metal machine, a Docker container, or -even a cluster of containers. GitLab and the runner communicate through an API, -so the only requirement is that the runner's machine has network access to the -GitLab server. + A pipeline with three stages should be displayed: -A runner can be specific to a certain project or serve multiple projects in -GitLab. If it serves all projects, it's called a _shared runner_. +  -Find more information about runners in the -[runner](../runners/README.md) documentation. +- To view a visual representation of your pipeline, click the pipeline ID. -The official runner supported by GitLab is written in Go. -View [the documentation](https://docs.gitlab.com/runner/). +  -For a runner to be available in GitLab, you must: +- To view details of a job, click the job name, for example, `deploy-prod`. -1. [Install GitLab Runner](https://docs.gitlab.com/runner/install/). -1. [Register a runner for your group or project](https://docs.gitlab.com/runner/register/). +  -When a runner is available, you can view it by -clicking **Settings > CI/CD** and expanding **Runners**. - - - -### Shared runners - -If you use [GitLab.com](https://gitlab.com/), you can use the **shared runners** -provided by GitLab. - -These are special virtual machines that run on GitLab's infrastructure and can -build any project. - -To enable shared runners, go to your project's or group's -**Settings > CI/CD** and click **Enable shared runners**. - -[Read more about shared runners](../runners/README.md#shared-runners). - -## Viewing the status of your pipeline and jobs - -After configuring the runner successfully, you should see the status of your -last commit change from _pending_ to either _running_, _success_ or _failed_. - -You can view all pipelines by going to the **Pipelines** page in your project. - - - -Or you can view all jobs, by going to the **Pipelines ➔ Jobs** page. - - - -By clicking on a job's status, you will be able to see the log of that job. -This is important to diagnose why a job failed or acted differently than -you expected. - - - -You are also able to view the status of any commit in the various pages in -GitLab, such as **Commits** and **Merge requests**. - -## Additional resources - -Visit the [examples README](../examples/README.md) to see a list of examples using GitLab -CI with various languages. - -For help making your new pipelines faster and more efficient, see the -[pipeline efficiency documentation](../pipelines/pipeline_efficiency.md). +If the job status is `stuck`, check to ensure a runner is probably configured for the project. diff --git a/doc/ci/quick_start/img/build_log.png b/doc/ci/quick_start/img/build_log.png Binary files differdeleted file mode 100644 index 16698629edc..00000000000 --- a/doc/ci/quick_start/img/build_log.png +++ /dev/null diff --git a/doc/ci/quick_start/img/builds_status.png b/doc/ci/quick_start/img/builds_status.png Binary files differdeleted file mode 100644 index b4aeeb988d2..00000000000 --- a/doc/ci/quick_start/img/builds_status.png +++ /dev/null diff --git a/doc/ci/quick_start/img/job_details_v13_6.png b/doc/ci/quick_start/img/job_details_v13_6.png Binary files differnew file mode 100644 index 00000000000..e94287f90ba --- /dev/null +++ b/doc/ci/quick_start/img/job_details_v13_6.png diff --git a/doc/ci/quick_start/img/new_commit.png b/doc/ci/quick_start/img/new_commit.png Binary files differdeleted file mode 100644 index 507eb93ac0c..00000000000 --- a/doc/ci/quick_start/img/new_commit.png +++ /dev/null diff --git a/doc/ci/quick_start/img/new_file_v13_6.png b/doc/ci/quick_start/img/new_file_v13_6.png Binary files differnew file mode 100644 index 00000000000..c71923f9b90 --- /dev/null +++ b/doc/ci/quick_start/img/new_file_v13_6.png diff --git a/doc/ci/quick_start/img/pipeline_graph_v13_6.png b/doc/ci/quick_start/img/pipeline_graph_v13_6.png Binary files differnew file mode 100644 index 00000000000..fcf7e02d1f3 --- /dev/null +++ b/doc/ci/quick_start/img/pipeline_graph_v13_6.png diff --git a/doc/ci/quick_start/img/pipelines_status.png b/doc/ci/quick_start/img/pipelines_status.png Binary files differdeleted file mode 100644 index 39a77a26b25..00000000000 --- a/doc/ci/quick_start/img/pipelines_status.png +++ /dev/null diff --git a/doc/ci/quick_start/img/single_commit_status_pending.png b/doc/ci/quick_start/img/single_commit_status_pending.png Binary files differdeleted file mode 100644 index ffc7054d3b0..00000000000 --- a/doc/ci/quick_start/img/single_commit_status_pending.png +++ /dev/null diff --git a/doc/ci/quick_start/img/three_stages_v13_6.png b/doc/ci/quick_start/img/three_stages_v13_6.png Binary files differnew file mode 100644 index 00000000000..a6c049e3e6c --- /dev/null +++ b/doc/ci/quick_start/img/three_stages_v13_6.png diff --git a/doc/ci/review_apps/img/view_on_env_mr.png b/doc/ci/review_apps/img/view_on_env_mr.png Binary files differindex 2c0bd25a4f2..0e61814a65d 100644 --- a/doc/ci/review_apps/img/view_on_env_mr.png +++ b/doc/ci/review_apps/img/view_on_env_mr.png diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 7110117709f..ba23eff0434 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -27,7 +27,7 @@ In the above example: - A Review App is built every time a commit is pushed to `topic branch`. - The reviewer fails two reviews before passing the third review. -- Once the review has passed, `topic branch` is merged into `master` where it is deployed to staging. +- After the review has passed, `topic branch` is merged into `master` where it is deployed to staging. - After having been approved in staging, the changes that were merged into `master` are deployed in to production. ## How Review Apps work @@ -169,7 +169,7 @@ will match `/source\/(.+?\.html).*/` instead of `/source\/(.*)/`, and will result in a public path of `index.html`, instead of `index.html.haml`. -Once you have the route mapping set up, it will take effect in the following locations: +After you have the route mapping set up, it will take effect in the following locations: - In the merge request widget. The: - **View app** button will take you to the environment URL set in `.gitlab-ci.yml`. diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index a3cc46f59bf..4392fa3c78b 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -6,8 +6,6 @@ type: reference --- # Configuring runners in GitLab -<!-- This topic contains several commented-out sections that were accidentally added in 13.2.--> -<!-- The commented-out sections will be added back in a future release.--> In GitLab CI/CD, runners run the code defined in [`.gitlab-ci.yml`](../yaml/README.md). A runner is a lightweight, highly-scalable agent that picks up a CI job through @@ -16,6 +14,10 @@ the coordinator API of GitLab CI/CD, runs the job, and sends the result back to Runners are created by an administrator and are visible in the GitLab UI. Runners can be specific to certain projects or available to all projects. +This documentation is focused on using runners in GitLab. +If you need to install and configure GitLab Runner, see +[the GitLab Runner documentation](https://docs.gitlab.com/runner/). + ## Types of runners In the GitLab UI there are three types of runners, based on who you want to have access: @@ -36,7 +38,7 @@ multiple projects. If you are using a self-managed instance of GitLab: - Your administrator can install and register shared runners by [following the documentation](https://docs.gitlab.com/runner/install/index.html). - <!-- going to your project's + <!-- going to your project's--> <!-- **Settings > CI / CD**, expanding the **Runners** section, and clicking **Show runner installation instructions**.--> <!-- These instructions are also available [in the documentation](https://docs.gitlab.com/runner/install/index.html).--> - The administrator can also configure a maximum number of shared runner [pipeline minutes for @@ -390,6 +392,9 @@ 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. +GitLab CI tags are not the same as Git tags. GitLab CI 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/README.md#tags). @@ -450,6 +455,339 @@ Example 2: 1. A job that has no tags defined is executed and run. 1. A second job that has a `docker` tag defined is stuck. +## Configure runner behavior with variables + +You can use [CI/CD variables](../variables/README.md) to configure runner Git behavior +globally or for individual jobs: + +- [`GIT_STRATEGY`](#git-strategy) +- [`GIT_SUBMODULE_STRATEGY`](#git-submodule-strategy) +- [`GIT_CHECKOUT`](#git-checkout) +- [`GIT_CLEAN_FLAGS`](#git-clean-flags) +- [`GIT_FETCH_EXTRA_FLAGS`](#git-fetch-extra-flags) +- [`GIT_DEPTH`](#shallow-cloning) (shallow cloning) +- [`GIT_CLONE_PATH`](#custom-build-directories) (custom build directories) + +You can also use variables to configure how many times a runner +[attempts certain stages of job execution](#job-stages-attempts). + +### 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/README.md#variables) section: + +```yaml +variables: + GIT_STRATEGY: clone +``` + +There are three possible values: `clone`, `fetch`, and `none`. If left unspecified, +jobs use the [project's pipeline setting](../pipelines/settings.md#git-strategy). + +`clone` is the slowest option. It clones the repository from scratch for every +job, ensuring that the local working copy is always pristine. +If an existing worktree is found, it is removed before cloning. + +`fetch` is faster as it re-uses the local working copy (falling back to `clone` +if it does not exist). `git clean` is used to undo any changes made by the last +job, and `git fetch` is used to retrieve commits made after the last job ran. + +However, `fetch` does require access to the previous worktree. This works +well when using the `shell` or `docker` executor because these +try to preserve worktrees and try to re-use them by default. + +This has limitations when using the [Docker Machine executor](https://docs.gitlab.com/runner/executors/docker_machine.html). + +It does not work for [the `kubernetes` executor](https://docs.gitlab.com/runner/executors/kubernetes.html), +but a [feature proposal](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3847) exists. +The `kubernetes` executor always clones into an temporary directory. + +A Git strategy of `none` also re-uses the local working copy, but skips all Git +operations normally done by GitLab. GitLab Runner pre-clone scripts are also skipped, +if present. This strategy could mean you need to add `fetch` and `checkout` commands +to [your `.gitlab-ci.yml` script](../yaml/README.md#script). + +It can be used for jobs that operate exclusively on artifacts, like a deployment job. +Git repository data may be present, but it's likely out of date. You should only +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/README.md#variables) section. + +There are three possible values: `none`, `normal`, and `recursive`: + +- `none` means that submodules are not included when fetching the project + code. This is the default, which matches the pre-v1.10 behavior. + +- `normal` means that only the top-level submodules are included. It's + equivalent to: + + ```shell + git submodule sync + git submodule update --init + ``` + +- `recursive` means that all submodules (including submodules of submodules) + are included. This feature needs Git v1.8.1 and later. When using a + GitLab Runner with an executor not based on Docker, make sure the Git version + meets that requirement. It's equivalent to: + + ```shell + git submodule sync --recursive + git submodule update --init --recursive + ``` + +For this feature to work correctly, the submodules must be configured +(in `.gitmodules`) with either: + +- the HTTP(S) URL of a publicly-accessible repository, or +- a relative path to another repository on the same GitLab server. See the + [Git submodules](../git_submodules.md) documentation. + +### 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 +[`variables`](../yaml/README.md#variables) section. + +If set to `false`, the runner: + +- when doing `fetch` - updates the repository and leaves the working copy on + the current revision, +- when doing `clone` - clones the repository and leaves the working copy on the + default branch. + +If `GIT_CHECKOUT` is set to `true`, both `clone` and `fetch` work the same way. +The runner checks out the working copy of a revision related +to the CI pipeline: + +```yaml +variables: + GIT_STRATEGY: clone + GIT_CHECKOUT: "false" +script: + - git checkout -B master origin/master + - git merge $CI_COMMIT_SHA +``` + +### 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/README.md#variables) section. + +`GIT_CLEAN_FLAGS` accepts all possible options of the [`git clean`](https://git-scm.com/docs/git-clean) +command. + +`git clean` is disabled if `GIT_CHECKOUT: "false"` is specified. + +If `GIT_CLEAN_FLAGS` is: + +- Not specified, `git clean` flags default to `-ffdx`. +- Given the value `none`, `git clean` is not executed. + +For example: + +```yaml +variables: + GIT_CLEAN_FLAGS: -ffdx -e cache/ +script: + - ls -al cache/ +``` + +### Git fetch extra flags + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4142) in GitLab Runner 13.1. + +The `GIT_FETCH_EXTRA_FLAGS` variable is used to control the behavior of +`git fetch`. You can set it globally or per-job in the [`variables`](../yaml/README.md#variables) section. + +`GIT_FETCH_EXTRA_FLAGS` accepts all options of the [`git fetch`](https://git-scm.com/docs/git-fetch) command. However, `GIT_FETCH_EXTRA_FLAGS` flags are appended after the default flags that can't be modified. + +The default flags are: + +- [GIT_DEPTH](#shallow-cloning). +- The list of [refspecs](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec). +- A remote called `origin`. + +If `GIT_FETCH_EXTRA_FLAGS` is: + +- Not specified, `git fetch` flags default to `--prune --quiet` along with the default flags. +- Given the value `none`, `git fetch` is executed only with the default flags. + +For example, the default flags are `--prune --quiet`, so you can make `git fetch` more verbose by overriding this with just `--prune`: + +```yaml +variables: + GIT_FETCH_EXTRA_FLAGS: --prune +script: + - ls -al cache/ +``` + +The configuration above results in `git fetch` being called this way: + +```shell +git fetch origin $REFSPECS --depth 50 --prune +``` + +Where `$REFSPECS` is a value provided to the runner internally by GitLab. + +### 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 +passed to `git fetch` and `git clone`. + +In GitLab 12.0 and later, newly-created projects automatically have a +[default `git depth` value of `50`](../pipelines/settings.md#git-shallow-clone). + +If you use a depth of `1` and have a queue of jobs or retry +jobs, jobs may fail. + +Git fetching and cloning is based on a ref, such as a branch name, so runners +can't clone a specific commit SHA. If multiple jobs are in the queue, or +you're retrying an old job, the commit to be tested must be within the +Git history that is cloned. Setting too small a value for `GIT_DEPTH` can make +it impossible to run these old commits and `unresolved reference` is displayed in +job logs. You should then reconsider changing `GIT_DEPTH` to a higher value. + +Jobs that rely on `git describe` may not work correctly when `GIT_DEPTH` is +set since only part of the Git history is present. + +To fetch or clone only the last 3 commits: + +```yaml +variables: + GIT_DEPTH: "3" +``` + +You can set it globally or per-job in the [`variables`](../yaml/README.md#variables) section. + +### 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 +the `GIT_CLONE_PATH` variable to tell the runner the directory to clone the +repository in: + +```yaml +variables: + GIT_CLONE_PATH: $CI_BUILDS_DIR/project-name + +test: + script: + - pwd +``` + +The `GIT_CLONE_PATH` has to always be within `$CI_BUILDS_DIR`. The directory set in `$CI_BUILDS_DIR` +is dependent on executor and configuration of [runners.builds_dir](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) +setting. + +This can only be used when `custom_build_dir` is enabled in the +[runner's configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscustom_build_dir-section). +This is the default configuration for the `docker` and `kubernetes` executors. + +#### Handling concurrency + +An executor that uses a concurrency greater than `1` might lead +to failures. Multiple jobs might be working on the same directory if the `builds_dir` +is shared between jobs. + +The runner does not try to prevent this situation. It's up to the administrator +and developers to comply with the requirements of runner configuration. + +To avoid this scenario, you can use a unique path within `$CI_BUILDS_DIR`, because runner +exposes two additional variables that provide a unique `ID` of concurrency: + +- `$CI_CONCURRENT_ID`: Unique ID for all jobs running within the given executor. +- `$CI_CONCURRENT_PROJECT_ID`: Unique ID for all jobs running within the given executor and project. + +The most stable configuration that should work well in any scenario and on any executor +is to use `$CI_CONCURRENT_ID` in the `GIT_CLONE_PATH`. For example: + +```yaml +variables: + GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/project-name + +test: + script: + - pwd +``` + +The `$CI_CONCURRENT_PROJECT_ID` should be used in conjunction with `$CI_PROJECT_PATH` +as the `$CI_PROJECT_PATH` provides a path of a repository. That is, `group/subgroup/project`. For example: + +```yaml +variables: + GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_PATH + +test: + script: + - pwd +``` + +#### Nested paths + +The value of `GIT_CLONE_PATH` is expanded once and nesting variables +within is not supported. + +For example, you define both the variables below in your +`.gitlab-ci.yml` file: + +```yaml +variables: + GOPATH: $CI_BUILDS_DIR/go + GIT_CLONE_PATH: $GOPATH/src/namespace/project +``` + +The value of `GIT_CLONE_PATH` is expanded once into +`$CI_BUILDS_DIR/go/src/namespace/project`, and results in failure +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: + +| Variable | Description | +|---------------------------------|--------------------------------------------------------| +| `ARTIFACT_DOWNLOAD_ATTEMPTS` | Number of attempts to download artifacts running a job | +| `EXECUTOR_JOB_SECTION_ATTEMPTS` | [In GitLab 12.10](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) and later, the number of attempts to run a section in a job after a [`No Such Container`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) error ([Docker executor](https://docs.gitlab.com/runner/executors/docker.html) only). | +| `GET_SOURCES_ATTEMPTS` | Number of attempts to fetch sources running a job | +| `RESTORE_CACHE_ATTEMPTS` | Number of attempts to restore the cache running a job | + +The default is one single attempt. + +Example: + +```yaml +variables: + GET_SOURCES_ATTEMPTS: 3 +``` + +You can set them globally or per-job in the [`variables`](../yaml/README.md#variables) section. + ## System calls not available on GitLab.com shared runners GitLab.com shared runners run on CoreOS. This means that you cannot use some system calls, like `getlogin`, from the C standard library. diff --git a/doc/ci/runners/img/shared_runners_admin.png b/doc/ci/runners/img/shared_runners_admin.png Binary files differdeleted file mode 100644 index e049b339b36..00000000000 --- a/doc/ci/runners/img/shared_runners_admin.png +++ /dev/null diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index 12478000a0a..a329331df08 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -93,7 +93,7 @@ to access it. This is where an SSH key pair comes in handy. # - git config --global user.name "User name" ``` - The [`before_script`](../yaml/README.md#before_script-and-after_script) can be set globally + The [`before_script`](../yaml/README.md#before_script) can be set globally or per-job. 1. Make sure the private server's [SSH host keys are verified](#verifying-the-ssh-host-keys). diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index bcd19f0de6f..6fca482975c 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -32,7 +32,7 @@ This also applies when using the `pipelines` or `triggers` keywords with the leg A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger). -DANGER: **Danger:** +DANGER: **Warning:** Passing plain text tokens in public projects is a security issue. Potential attackers can impersonate the user that exposed their trigger token publicly in their `.gitlab-ci.yml` file. Use [variables](../variables/README.md#gitlab-cicd-environment-variables) @@ -50,7 +50,7 @@ with the [GitLab Container Registry](../../user/packages/container_registry/inde This way of triggering can only be used when invoked inside `.gitlab-ci.yml`, and it creates a dependent pipeline relation visible on the -[pipeline graph](../multi_project_pipelines.md#overview). For example: +[pipeline graph](../multi_project_pipelines.md). For example: ```yaml build_docs: diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md index 992b51b6b3d..5dc1d3663c5 100644 --- a/doc/ci/troubleshooting.md +++ b/doc/ci/troubleshooting.md @@ -225,7 +225,7 @@ should disable **Pipelines must succeed** so you can accept merge requests. Pipeline configuration warnings are shown when you: -- [Validate configuration with the CI Lint tool](yaml/README.md#validate-the-gitlab-ciyml). +- [Validate configuration with the CI Lint tool](yaml/README.md). - [Manually run a pipeline](pipelines/index.md#run-a-pipeline-manually). ### "Job may allow multiple pipelines to run for a single action" warning diff --git a/doc/ci/unit_test_reports.md b/doc/ci/unit_test_reports.md index b9c1809bf0d..0a1f0000969 100644 --- a/doc/ci/unit_test_reports.md +++ b/doc/ci/unit_test_reports.md @@ -244,6 +244,44 @@ Test: - ./**/*test-result.xml ``` +### JavaScript example + +There are a few tools that can produce JUnit report format XML files in JavaScript. + +#### Jest + +The [jest-junit](https://github.com/jest-community/jest-junit) npm package can generate test reports for JavaScript applications. +In the following `.gitlab-ci.yml` example, the `javascript` job uses Jest to generate the test reports: + +```yaml +javascript: + stage: test + script: + - 'jest --ci --reporters=default --reporters=jest-junit' + artifacts: + when: always + reports: + junit: + - junit.xml +``` + +#### Karma + +The [Karma-junit-reporter](https://github.com/karma-runner/karma-junit-reporter) npm package can generate test reports for JavaScript applications. +In the following `.gitlab-ci.yml` example, the `javascript` job uses Karma to generate the test reports: + +```yaml +javascript: + stage: test + script: + - karma start --reporters junit + artifacts: + when: always + reports: + junit: + - junit.xml +``` + ## Viewing Unit test reports on GitLab > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24792) in GitLab 12.5 behind a feature flag (`junit_pipeline_view`), disabled by default. diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 9c8fb994bf7..c5eee2ed960 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -70,7 +70,7 @@ When you need a specific custom environment variable, you can or directly [in the `.gitlab-ci.yml` file](#create-a-custom-variable-in-gitlab-ciyml). The variables are used by the runner any time the pipeline runs. -You can also [override variable values manually for a specific pipeline](../pipelines/index.md#specifying-variables-when-running-manual-jobs). +You can also [override variable values manually for a specific pipeline](../jobs/index.md#specifying-variables-when-running-manual-jobs). There are two types of variables: **Variable** and **File**. You cannot set types in the `.gitlab-ci.yml` file, but you can set them in the UI and API. @@ -423,7 +423,7 @@ Group-level variables can be added by: 1. Inputting variable types, keys, and values in the **Variables** section. Any variables of [subgroups](../../user/group/subgroups/index.md) are inherited recursively. -Once you set them, they are available for all subsequent pipelines. Any group-level user defined variables can be viewed in projects by: +After you set them, they are available for all subsequent pipelines. Any group-level user defined variables can be viewed in projects by: 1. Navigating to the project's **Settings > CI/CD** page. 1. Expanding the **Variables** section. @@ -841,7 +841,7 @@ Available on GitLab Runner v1.7+, this feature enables the shell's execution log Before enabling this, you should ensure jobs are visible to [team members only](../../user/permissions.md#project-features). You should -also [erase](../pipelines/index.md#view-jobs-in-a-pipeline) all generated job logs +also [erase](../jobs/index.md#view-jobs-in-a-pipeline) all generated job logs before making them visible again. To enable debug logs (traces), set the `CI_DEBUG_TRACE` variable to `true`: diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 08aaacd2620..055cb2f6a61 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -40,7 +40,7 @@ Kubernetes-specific environment variables are detailed in the | `CI_COMMIT_REF_SLUG` | 9.0 | all | `$CI_COMMIT_REF_NAME` lowercased, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in URLs, host names and domain names. | | `CI_COMMIT_SHA` | 9.0 | all | The commit revision for which project is built | | `CI_COMMIT_SHORT_SHA` | 11.7 | all | The first eight characters of `CI_COMMIT_SHA` | -| `CI_COMMIT_BRANCH` | 12.6 | 0.5 | The commit branch name. Present only when building branches. | +| `CI_COMMIT_BRANCH` | 12.6 | 0.5 | The commit branch name. Present in branch pipelines, including pipelines for the default branch. Not present in merge request pipelines. | | `CI_COMMIT_TAG` | 9.0 | 0.5 | The commit tag name. Present only when building tags. | | `CI_COMMIT_TITLE` | 10.8 | all | The title of the commit - the full first line of the message | | `CI_COMMIT_TIMESTAMP` | 13.4 | all | The timestamp of the commit in the ISO 8601 format. | @@ -69,14 +69,14 @@ Kubernetes-specific environment variables are detailed in the | `CI_JOB_MANUAL` | 8.12 | all | The flag to indicate that job was manually started | | `CI_JOB_NAME` | 9.0 | 0.5 | The name of the job as defined in `.gitlab-ci.yml` | | `CI_JOB_STAGE` | 9.0 | 0.5 | The name of the stage as defined in `.gitlab-ci.yml` | -| `CI_JOB_STATUS` | all | 13.5 | The state of the job as each runner stage is executed. Use with [`after_script`](../yaml/README.md#before_script-and-after_script) where `CI_JOB_STATUS` can be either: `success`, `failed` or `canceled`. | +| `CI_JOB_STATUS` | all | 13.5 | The state of the job as each runner stage is executed. Use with [`after_script`](../yaml/README.md#after_script) where `CI_JOB_STATUS` can be either: `success`, `failed` or `canceled`. | | `CI_JOB_TOKEN` | 9.0 | 1.2 | Token used for authenticating with [a few API endpoints](../../api/README.md#gitlab-ci-job-token) and downloading [dependent repositories](../../user/project/new_ci_build_permissions_model.md#dependent-repositories). The token is valid as long as the job is running. | | `CI_JOB_JWT` | 12.10 | all | RS256 JSON web token that can be used for authenticating with third party systems that support JWT authentication, for example [HashiCorp's Vault](../secrets/index.md). | | `CI_JOB_URL` | 11.1 | 0.5 | Job details URL | | `CI_KUBERNETES_ACTIVE` | 13.0 | all | Included with the value `true` only if the pipeline has a Kubernetes cluster available for deployments. Not included if no cluster is available. Can be used as an alternative to [`only:kubernetes`/`except:kubernetes`](../yaml/README.md#onlykubernetesexceptkubernetes) with [`rules:if`](../yaml/README.md#rulesif) | | `CI_MERGE_REQUEST_ASSIGNEES` | 11.9 | all | Comma-separated list of username(s) of assignee(s) for the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created. | -| `CI_MERGE_REQUEST_ID` | 11.6 | all | The instance-level ID of the merge request. Only available if [the pipelines are for merge requests](../merge_request_pipelines/index.md) and the merge request is created. | -| `CI_MERGE_REQUEST_IID` | 11.6 | all | The project-level IID (internal ID) of the merge request. Only available If [the pipelines are for merge requests](../merge_request_pipelines/index.md) and the merge request is created. | +| `CI_MERGE_REQUEST_ID` | 11.6 | all | The instance-level ID of the merge request. Only available if [the pipelines are for merge requests](../merge_request_pipelines/index.md) and the merge request is created. This is a unique ID across all projects on GitLab. | +| `CI_MERGE_REQUEST_IID` | 11.6 | all | The project-level IID (internal ID) of the merge request. Only available If [the pipelines are for merge requests](../merge_request_pipelines/index.md) and the merge request is created. This ID is unique for the current project. | | `CI_MERGE_REQUEST_LABELS` | 11.9 | all | Comma-separated label names of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created. | | `CI_MERGE_REQUEST_MILESTONE` | 11.9 | all | The milestone title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created. | | `CI_MERGE_REQUEST_PROJECT_ID` | 11.6 | all | The ID of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created. | @@ -96,8 +96,8 @@ Kubernetes-specific environment variables are detailed in the | `CI_NODE_TOTAL` | 11.5 | all | Total number of instances of this job running in parallel. If the job is not parallelized, this variable is set to `1`. | | `CI_PAGES_DOMAIN` | 11.8 | all | The configured domain that hosts GitLab Pages. | | `CI_PAGES_URL` | 11.8 | all | URL to GitLab Pages-built pages. Always belongs to a subdomain of `CI_PAGES_DOMAIN`. | -| `CI_PIPELINE_ID` | 8.10 | all | The instance-level ID of the current pipeline. | -| `CI_PIPELINE_IID` | 11.0 | all | The project-level IID (internal ID) of the current pipeline. | +| `CI_PIPELINE_ID` | 8.10 | all | The instance-level ID of the current pipeline. This is a unique ID across all projects on GitLab. | +| `CI_PIPELINE_IID` | 11.0 | all | The project-level IID (internal ID) of the current pipeline. This ID is unique for the current project. | | `CI_PIPELINE_SOURCE` | 10.0 | all | Indicates how the pipeline was triggered. Possible options are: `push`, `web`, `schedule`, `api`, `external`, `chat`, `webide`, `merge_request_event`, `external_pull_request_event`, `parent_pipeline`, [`trigger`, or `pipeline`](../triggers/README.md#authentication-tokens) (renamed to `cross_project_pipeline` since 13.0). For pipelines created before GitLab 9.5, this is displayed as `unknown`. | | `CI_PIPELINE_TRIGGERED` | all | all | The flag to indicate that job was [triggered](../triggers/README.md) | | `CI_PIPELINE_URL` | 11.1 | 0.5 | Pipeline details URL | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index b4236ca34c2..b914f3db572 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -99,7 +99,7 @@ In the case of `after_script` scripts, they can: - Not use variables defined in `before_script` and `script`. These restrictions are because `after_script` scripts are executed in a -[separated shell context](../yaml/README.md#before_script-and-after_script). +[separated shell context](../yaml/README.md#after_script). ## Persisted variables diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 2e4ab68a0e8..1057a1389de 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -7,105 +7,29 @@ type: reference # GitLab CI/CD pipeline configuration reference -GitLab CI/CD [pipelines](../pipelines/index.md) are configured using a YAML file called `.gitlab-ci.yml` within each project. +This document lists the configuration options for your GitLab `.gitlab-ci.yml` file. -The `.gitlab-ci.yml` file defines the structure and order of the pipelines and determines: - -- What to execute using [GitLab Runner](https://docs.gitlab.com/runner/). -- What decisions to make when specific conditions are encountered. For example, when a process succeeds or fails. - -This topic covers CI/CD pipeline configuration. For other CI/CD configuration information, see: - -- [GitLab CI/CD Variables](../variables/README.md), for configuring the environment the pipelines run in. -- [GitLab Runner advanced configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html), for configuring GitLab Runner. - -We have complete examples of configuring pipelines: - -- For a quick introduction to GitLab CI/CD, follow our [quick start guide](../quick_start/README.md). +- For a quick introduction to GitLab CI/CD, follow the [quick start guide](../quick_start/README.md). - For a collection of examples, see [GitLab CI/CD Examples](../examples/README.md). -- To see a large `.gitlab-ci.yml` file used in an enterprise, see the [`.gitlab-ci.yml` file for `gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml). - -> For some additional information about GitLab CI/CD: -> -> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch the [CI/CD Ease of configuration](https://www.youtube.com/embed/opdLqwz6tcE) video. -> - Watch the [Making the case for CI/CD in your organization](https://about.gitlab.com/compare/github-actions-alternative/) -> webcast to learn the benefits of CI/CD and how to measure the results of CI/CD automation. -> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Learn how [Verizon reduced rebuilds](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/) -> from 30 days to under 8 hours with GitLab. - -If you have a [mirrored repository that GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository), -you may need to enable pipeline triggering. Go to your project's **Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. +- To view a large `.gitlab-ci.yml` file used in an enterprise, see the [`.gitlab-ci.yml` file for `gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml). -## Introduction - -Pipeline configuration begins with jobs. Jobs are the most fundamental element of a `.gitlab-ci.yml` file. - -Jobs are: - -- Defined with constraints stating under what conditions they should be executed. -- Top-level elements with an arbitrary name and must contain at least the [`script`](#script) clause. -- Not limited in how many can be defined. - -For example: - -```yaml -job1: - script: "execute-script-for-job1" - -job2: - script: "execute-script-for-job2" -``` - -The above example is the simplest possible CI/CD configuration with two separate -jobs, where each of the jobs executes a different command. -Of course a command can execute code directly (`./configure;make;make install`) -or run a script (`test.sh`) in the repository. - -Jobs are picked up by [runners](../runners/README.md) and executed within the -environment of the runner. What is important is that each job is run -independently from each other. - -### Validate the `.gitlab-ci.yml` - -Each instance of GitLab CI/CD has an embedded debug tool called Lint, which validates the -content of your `.gitlab-ci.yml` files. You can find the Lint under the page `ci/lint` of your +While you are authoring your `.gitlab-ci.yml` file, you can validate it +by using the [CI Lint](../lint.md) tool. project namespace. For example, `https://gitlab.example.com/gitlab-org/project-123/-/ci/lint`. -### Unavailable names for jobs - -Each job must have a unique name, but there are a few **reserved `keywords` that -can't be used as job names**: - -- `image` -- `services` -- `stages` -- `types` -- `before_script` -- `after_script` -- `variables` -- `cache` -- `include` +## Job keywords -### Using reserved keywords +A job is defined as a list of keywords that define the job's behavior. -If you get validation error when using specific values (for example, `true` or `false`), try to: - -- Quote them. -- Change them to a different form. For example, `/bin/true`. - -## Configuration parameters - -A job is defined as a list of parameters that define the job's behavior. - -The following table lists available parameters for jobs: +The following table lists available keywords for jobs: | Keyword | Description | |:---------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`script`](#script) | Shell script that is executed by a runner. | -| [`after_script`](#before_script-and-after_script) | Override a set of commands that are executed after job. | +| [`after_script`](#after_script) | Override a set of commands that are executed after job. | | [`allow_failure`](#allow_failure) | Allow job to fail. Failed job does not contribute to commit status. | | [`artifacts`](#artifacts) | List of files and directories to attach to a job on success. Also available: `artifacts:paths`, `artifacts:exclude`, `artifacts:expose_as`, `artifacts:name`, `artifacts:untracked`, `artifacts:when`, `artifacts:expire_in`, and `artifacts:reports`. | -| [`before_script`](#before_script-and-after_script) | Override a set of commands that are executed before job. | +| [`before_script`](#before_script) | Override a set of commands that are executed before job. | | [`cache`](#cache) | List of files that should be cached between subsequent runs. Also available: `cache:paths`, `cache:key`, `cache:untracked`, `cache:when`, and `cache:policy`. | | [`coverage`](#coverage) | Code coverage settings for a given job. | | [`dependencies`](#dependencies) | Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from. | @@ -130,22 +54,44 @@ The following table lists available parameters for jobs: | [`variables`](#variables) | Define job variables on a job level. | | [`when`](#when) | When to run job. Also available: `when:manual` and `when:delayed`. | -## Global parameters +### Unavailable names for jobs -Some parameters must be defined at a global level, affecting all jobs in the pipeline. +Each job must have a unique name, but there are a few **reserved `keywords` that +can't be used as job names**: + +- `image` +- `services` +- `stages` +- `types` +- `before_script` +- `after_script` +- `variables` +- `cache` +- `include` + +## Global keywords + +Some keywords must be defined at a global level, affecting all jobs in the pipeline. + +### Using reserved keywords + +If you get validation error when using specific values (for example, `true` or `false`), try to: + +- Quote them. +- Change them to a different form. For example, `/bin/true`. ### Global defaults -Some parameters can be set globally as the default for all jobs using the -`default:` keyword. Default parameters can then be overridden by job-specific +Some keywords can be set globally as the default for all jobs using the +`default:` keyword. Default keywords can then be overridden by job-specific configuration. -The following job parameters can be defined inside a `default:` block: +The following job keywords can be defined inside a `default:` block: - [`image`](#image) - [`services`](#services) -- [`before_script`](#before_script-and-after_script) -- [`after_script`](#before_script-and-after_script) +- [`before_script`](#before_script) +- [`after_script`](#after_script) - [`tags`](#tags) - [`cache`](#cache) - [`artifacts`](#artifacts) @@ -173,20 +119,20 @@ rspec 2.6: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) in GitLab 12.9. You can disable inheritance of globally defined defaults -and variables with the `inherit:` parameter. +and variables with the `inherit:` keyword. -To enable or disable the inheritance of all `variables:` or `default:` parameters, use the following format: +To enable or disable the inheritance of all `variables:` or `default:` keywords, use the following format: - `default: true` or `default: false` - `variables: true` or `variables: false` -To inherit only a subset of `default:` parameters or `variables:`, specify what +To inherit only a subset of `default:` keywords or `variables:`, specify what you wish to inherit. Anything not listed is **not** inherited. Use one of the following formats: ```yaml inherit: - default: [parameter1, parameter2] + default: [keyword1, keyword2] variables: [VARIABLE1, VARIABLE2] ``` @@ -195,8 +141,8 @@ Or: ```yaml inherit: default: - - parameter1 - - parameter2 + - keyword1 + - keyword2 variables: - VARIABLE1 - VARIABLE2 @@ -288,23 +234,23 @@ There are also two edge cases worth mentioning: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5 -The top-level `workflow:` key applies to the entirety of a pipeline, and -determines whether or not a pipeline is created. It accepts a single -`rules:` key that operates similarly to [`rules:` defined within jobs](#rules), -enabling dynamic configuration of the pipeline. +The top-level `workflow:` keyword determines whether or not a pipeline is created. +It accepts a single `rules:` keyword that is similar to [`rules:` defined within jobs](#rules). +Use it to define what can trigger a new pipeline. -If you are new to GitLab CI/CD and `workflow: rules`, you may find the [`workflow:rules` templates](#workflowrules-templates) useful. +You can use the [`workflow:rules` templates](#workflowrules-templates) to import +a preconfigured `workflow: rules` entry. -To define your own `workflow: rules`, the available configuration options are: +`workflow: rules` accepts these keywords: -- [`if`](#rulesif): Define a rule. -- [`when`](#when): May be set to `always` or `never` only. If not provided, the default value is `always`. +- [`if`](#rulesif): Check this rule to determine when to run a pipeline. +- [`when`](#when): Specify what to do when the `if` rule evaluates to true. + - To run a pipeline, set to `always`. + - To prevent pipelines from running, set to `never`. -If a pipeline attempts to run but matches no rule, it's dropped and doesn't run. +When no rules evaluate to true, the pipeline does not run. -Use the example rules below exactly as written to allow pipelines that match the rule -to run. Add `when: never` to prevent pipelines that match the rule from running. See -the [common `if` clauses for `rules`](#common-if-clauses-for-rules) for more examples. +Some example `if` clauses for `workflow: rules`: | Example rules | Details | |------------------------------------------------------|-----------------------------------------------------------| @@ -313,9 +259,12 @@ the [common `if` clauses for `rules`](#common-if-clauses-for-rules) for more exa | `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`](#common-if-clauses-for-rules) for more examples. + For example, in the following configuration, pipelines run for all `push` events (changes to -branches and new tags). Only push events with `-wip` in the commit message are excluded. Scheduled -pipelines and merge request pipelines don't run, as there's no rule allowing them. +branches and new tags). Pipelines for push events with `-wip` in the commit message +don't run, because they are set to `when: never`. Pipelines for schedules or merge requests +don't run either, because no rules evaluate to true for them: ```yaml workflow: @@ -325,11 +274,11 @@ workflow: - if: '$CI_PIPELINE_SOURCE == "push"' ``` -This example has strict rules, and no other pipelines can run. +This example has strict rules, and pipelines do **not** run in any other case. -Alternatively, you can have loose rules by using only `when: never` rules, followed -by a final `when: always` rule. This allows all types of pipelines, except for any -that match the `when: never` rules: +Alternatively, all of the rules can be `when: never`, with a final +`when: always` rule. Pipelines that match the `when: never` rules do not run. +All other pipeline types run: ```yaml workflow: @@ -341,12 +290,13 @@ workflow: - when: always ``` -This example never allows pipelines for schedules or `push` (branches and tags) pipelines, -but does allow pipelines in **all** other cases, *including* merge request pipelines. +This example prevents pipelines for schedules or `push` (branches and tags) pipelines. +The final `when: always` rule lets all other pipeline types run, **including** merge +request pipelines. -Be careful not to use a configuration that might run -merge request pipelines and branch pipelines at the same time. As with `rules` defined in jobs, -it can cause [duplicate pipelines](#prevent-duplicate-pipelines). +Be careful not to have rules that match both branch pipelines +and merge request pipelines. Similar to `rules` defined in jobs, this can cause +[duplicate pipelines](#prevent-duplicate-pipelines). #### `workflow:rules` templates @@ -405,7 +355,7 @@ of using YAML anchors, you can use the [`extends` keyword](#extends). `include` supports the following inclusion methods: -| Method | Description | +| Keyword | Method | |:--------------------------------|:------------------------------------------------------------------| | [`local`](#includelocal) | Include a file from the local project repository. | | [`file`](#includefile) | Include a file from a different project repository. | @@ -471,7 +421,7 @@ include: file: '/templates/.gitlab-ci-template.yml' ``` -You can also specify `ref`, with the default being the `HEAD` of the project: +You can also specify a `ref`. If not specified, it defaults to the `HEAD` of the project: ```yaml include: @@ -492,11 +442,47 @@ All [nested includes](#nested-includes) are executed in the scope of the target This means you can use local (relative to target project), project, remote, or template includes. +##### Multiple files from a project + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26793) in GitLab 13.6. +> - It's [deployed behind a feature flag](../../user/feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to disable it. **(CORE ONLY)** + +You can include multiple files from the same project: + +```yaml +include: + - project: 'my-group/my-project' + ref: master + file: + - '/templates/.builds.yml' + - '/templates/.tests.yml' +``` + +Including multiple files from the same project is under development but ready for production use. It is +deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:ci_include_multiple_files_from_project) +``` + +To disable it: + +```ruby +Feature.disable(:ci_include_multiple_files_from_project) +``` + #### `include:remote` `include:remote` can be used to include a file from a different location, -using HTTP/HTTPS, referenced by using the full URL. The remote file must be -publicly accessible through a simple GET request as authentication schemas +using HTTP/HTTPS, referenced by the full URL. The remote file must be +publicly accessible by a GET request, because authentication schemas in the remote URL are not supported. For example: ```yaml @@ -542,15 +528,15 @@ Nested includes allow you to compose a set of includes. A total of 100 includes is allowed, but duplicate includes are considered a configuration error. In [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/28212) and later, the time limit -for resolving all files is 30 seconds. +to resolve all files is 30 seconds. #### Additional `includes` examples There is a list of [additional `includes` examples](includes.md) available. -## Parameter details +## Keyword details -The following are detailed explanations for parameters used to configure CI/CD pipelines. +The following are detailed explanations for keywords used to configure CI/CD pipelines. ### `image` @@ -558,7 +544,7 @@ Used to specify [a Docker image](../docker/using_docker_images.md#what-is-an-ima For: -- Simple definition examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml). +- Usage examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml). - Detailed usage information, refer to [Docker integration](../docker/README.md) documentation. #### `image:name` @@ -579,7 +565,7 @@ Used to specify a [service Docker image](../docker/using_docker_images.md#what-i For: -- Simple definition examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml). +- Usage examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml). - Detailed usage information, refer to [Docker integration](../docker/README.md) documentation. - For example services, see [GitLab CI/CD Services](../services/README.md). @@ -617,9 +603,9 @@ job: script: "bundle exec rspec" ``` -[YAML anchors for scripts](#yaml-anchors-for-script) are available. +You can use [YAML anchors with `script`](#yaml-anchors-for-scripts). -This parameter can also contain several commands using an array: +This keyword can also contain several commands in an array: ```yaml job: @@ -635,8 +621,8 @@ a "key: value" pair. Be careful when using special characters: `:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``. If any of the script commands return an exit code other than zero, the job -fails and further commands are not executed. You can avoid this behavior by -storing the exit code in a variable: +fails and further commands are not executed. Store the exit code in a variable to +avoid this behavior: ```yaml job: @@ -645,191 +631,86 @@ job: - if [ $exit_code -ne 0 ]; then echo "Previous command failed"; fi; ``` -#### `before_script` and `after_script` +#### `before_script` > Introduced in GitLab 8.7 and requires GitLab Runner v1.2. -`before_script` is used to define commands that should be run before each -job, including deploy jobs, but after the restoration of any [artifacts](#artifacts). -This must be an array. +`before_script` is used to define commands that should run before each job, including +deploy jobs, but after the restoration of any [artifacts](#artifacts). This must be an array. Scripts specified in `before_script` are concatenated with any scripts specified in the main [`script`](#script), and executed together in a single shell. -`after_script` is used to define commands that run after each -job, including failed jobs. This must be an array. If a job times out or is cancelled, -the `after_script` commands are not executed. Support for executing `after_script` -commands for timed-out or cancelled jobs -[is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/15603). - -Scripts specified in `after_script` are executed in a new shell, separate from any -`before_script` or `script` scripts. As a result, they: - -- Have a current working directory set back to the default. -- Have no access to changes done by scripts defined in `before_script` or `script`, including: - - Command aliases and variables exported in `script` scripts. - - Changes outside of the working tree (depending on the runner executor), like - software installed by a `before_script` or `script` script. -- Have a separate timeout, which is hard coded to 5 minutes. See - [related issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2716) for details. -- Don't affect the job's exit code. If the `script` section succeeds and the - `after_script` times out or fails, the job exits with code `0` (`Job Succeeded`). - -It's possible to overwrite a globally defined `before_script` or `after_script` -if you set it per-job: +It's possible to overwrite a globally defined `before_script` if you define it in a job: ```yaml default: before_script: - - global before script - -job: - before_script: - - execute this instead of global before script - script: - - my command - after_script: - - execute this after my script -``` - -[YAML anchors for `before_script` and `after_script`](#yaml-anchors-for-before_script-and-after_script) are available. + - echo "Execute this in all jobs that don't already have a before_script section." -#### Coloring script output - -Script output can be colored using [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors), -or by running commands or programs that output ANSI escape codes. - -For example, using [Bash with color codes](https://misc.flogisoft.com/bash/tip_colors_and_formatting): - -```yaml -job: +job1: script: - - echo -e "\e[31mThis text is red,\e[0m but this text isn't\e[31m however this text is red again." -``` + - echo "This executes after the global before_script." -You can define the color codes in Shell variables, or even [custom environment variables](../variables/README.md#custom-environment-variables), -which makes the commands easier to read and reusable. - -For example, using the same example as above and variables defined in a `before_script`: - -```yaml job: before_script: - - TXT_RED="\e[31m" && TXT_CLEAR="\e[0m" + - echo "Execute this instead of the global before_script." script: - - echo -e "${TXT_RED}This text is red,${TXT_CLEAR} but this part isn't${TXT_RED} however this part is again." - - echo "This text is not colored" + - echo "This executes after the job's `before_script`" ``` -Or with [PowerShell color codes](https://superuser.com/a/1259916): +You can use [YAML anchors with `before_script`](#yaml-anchors-for-scripts). -```yaml -job: - before_script: - - $esc="$([char]27)"; $TXT_RED="$esc[31m"; $TXT_CLEAR="$esc[0m" - script: - - Write-Host $TXT_RED"This text is red,"$TXT_CLEAR" but this text isn't"$TXT_RED" however this text is red again." - - Write-Host "This text is not colored" -``` - -#### Multi-line commands +#### `after_script` -You can split long commands into multi-line commands to improve readability -using [`|` (literal) and `>` (folded) YAML multi-line block scalar indicators](https://yaml-multiline.info/). - -CAUTION: **Warning:** -If multiple commands are combined into one command string, only the last command's -failure or success is reported. -[Failures from earlier commands are ignored due to a bug](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/25394). -To work around this, -run each command as a separate `script:` item, or add an `exit 1` command -to each command string. +Introduced in GitLab 8.7 and requires GitLab Runner v1.2. -You can use the `|` (literal) YAML multiline block scalar indicator to write -commands over multiple lines in the `script` section of a job description. -Each line is treated as a separate command. -Only the first command is repeated in the job log, but additional -commands are still executed: +`after_script` is used to define commands that run after each job, including failed +jobs. This must be an array. -```yaml -job: - script: - - | - echo "First command line." - echo "Second command line." - echo "Third command line." -``` - -The example above renders in the job log as: +If a job times out or is cancelled, the `after_script` commands are not executed. +Support for executing `after_script` commands for timed-out or cancelled jobs +[is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/15603). -```shell -$ echo First command line # collapsed multi-line command -First command line -Second command line. -Third command line. -``` +Scripts specified in `after_script` are executed in a new shell, separate from any +`before_script` or `script` scripts. As a result, they: -The `>` (folded) YAML multiline block scalar indicator treats empty lines between -sections as the start of a new command: +- Have a current working directory set back to the default. +- Have no access to changes done by scripts defined in `before_script` or `script`, including: + - Command aliases and variables exported in `script` scripts. + - Changes outside of the working tree (depending on the runner executor), like + software installed by a `before_script` or `script` script. +- Have a separate timeout, which is hard coded to 5 minutes. See the + [related issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2716) for details. +- Don't affect the job's exit code. If the `script` section succeeds and the + `after_script` times out or fails, the job exits with code `0` (`Job Succeeded`). ```yaml -job: - script: - - > - echo "First command line - is split over two lines." - - echo "Second command line." -``` - -This behaves similarly to writing multiline commands without the `>` or `|` block -scalar indicators: +default: + after_script: + - echo "Execute this in all jobs that don't already have an after_script section." -```yaml -job: +job1: script: - - echo "First command line - is split over two lines." - - echo "Second command line." -``` - -Both examples above render in the job log as: - -```shell -$ echo First command line is split over two lines. # collapsed multi-line command -First command line is split over two lines. -Second command line. -``` - -When you omit the `>` or `|` block scalar indicators, GitLab forms the command -by concatenating non-empty lines. Make sure the lines can run when concatenated. + - echo "This executes first. When it completes, the global after_script executes." -Shell [here documents](https://en.wikipedia.org/wiki/Here_document) work with the -`|` and `>` operators as well. The example below transliterates the lower case letters -to upper case: - -```yaml job: script: - - | - tr a-z A-Z << END_TEXT - one two three - four five six - END_TEXT + - echo "This executes first. When it completes, the job's `after_script` executes." + after_script: + - echo "Execute this instead of the global after_script." ``` -Results in: +You can use [YAML anchors with `after_script`](#yaml-anchors-for-scripts). -```shell -$ tr a-z A-Z << END_TEXT # collapsed multi-line command - ONE TWO THREE - FOUR FIVE SIX -``` +#### Script syntax -#### Custom collapsible sections +You can use special syntax in [`script`](README.md#script) sections to: -See [custom collapsible sections](../pipelines/index.md#custom-collapsible-sections). +- [Split long commands](script.md#split-long-commands) into multiline commands. +- [Use color codes](script.md#add-color-codes-to-script-output) to make job logs easier to review. +- [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections) + to simplify job log output. ### `stage` @@ -968,7 +849,7 @@ rspec: - $RSPEC ``` -If you do want to include the `rake test`, see [`before_script` and `after_script`](#before_script-and-after_script). +If you do want to include the `rake test`, see [`before_script`](#before_script) or [`after_script`](#after_script). `.tests` in this example is a [hidden job](#hide-jobs), but it's possible to inherit from regular jobs as well. @@ -1422,29 +1303,20 @@ Other commonly used variables for `if` clauses: #### `rules:changes` -To determine if jobs should be added to a pipeline, `rules: changes` clauses check -the files changed by Git push events. +`rules:changes` determines whether or not to add jobs to a pipeline by checking for +changes to specific files. `rules: changes` works exactly the same way as [`only: changes` and `except: changes`](#onlychangesexceptchanges), -accepting an array of paths. Similarly, it always returns true if there is no -Git push event, for example, when a new tag is created. It's recommended to use it -only with branch pipelines or merge request pipelines. For example, it's common to -use `rules: changes` with one of the following `if` clauses: - -- `if: $CI_COMMIT_BRANCH` -- `if: '$CI_PIPELINE_SOURCE == "merge_request_event"'` - -For example: +accepting an array of paths. It's recommended to only use `rules: changes` with branch +pipelines or merge request pipelines. For example, it's common to use `rules: changes` +with merge request pipelines: ```yaml -workflow: - rules: - - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - docker build: script: docker build -t my-image:$CI_COMMIT_REF_SLUG . rules: - - changes: + - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' + changes: - Dockerfile when: manual allow_failure: true @@ -1452,14 +1324,77 @@ docker build: In this example: -- [`workflow: rules`](#workflowrules) allows only pipelines for merge requests for all jobs. +- If the pipeline is a merge request pipeline, check `Dockerfile` for changes. - If `Dockerfile` has changed, add the job to the pipeline as a manual job, and allow the pipeline to continue running even if the job is not triggered (`allow_failure: true`). - If `Dockerfile` has not changed, do not add job to any pipeline (same as `when: never`). -To implement a rule similar to [`except: changes`](#onlychangesexceptchanges), +To use `rules: changes` with branch pipelines instead of merge request pipelines, +change the `if:` clause in the example above to: + +```yaml +rules: + - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH +``` + +To implement a rule similar to [`except:changes`](#onlychangesexceptchanges), use `when: never`. +CAUTION: **Caution:** +You can use `rules: changes` with other pipeline types, but it is not recommended +because `rules: changes` always evaluates to true when there is no Git `push` event. +Tag pipelines, scheduled pipelines, and so on do **not** have a Git `push` event +associated with them. A `rules: changes` job is **always** added to those pipeline +if there is no `if:` statement that limits the job to branch or merge request pipelines. + +##### Variables in `rules:changes` + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34272) in GitLab 13.6. +> - It was [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/267192) in GitLab 13.6. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-variables-support-in-ruleschanges). **(CORE ONLY)** + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +Environment variables can be used in `rules:changes` expressions to determine when +to add jobs to a pipeline: + +```yaml +docker build: + variables: + DOCKERFILES_DIR: 'path/to/files/' + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + rules: + - changes: + - $DOCKERFILES_DIR/* +``` + +The `$` character can be used for both variables and paths. For example, if the +`$DOCKERFILES_DIR` variable exists, its value is used. If it does not exist, the +`$` is interpreted as being part of a path. + +###### Enable or disable variables support in `rules:changes` **(CORE ONLY)** + +Variables support in `rules:changes` is under development, but is ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:ci_variable_expansion_in_rules_changes) +``` + +To disable it: + +```ruby +Feature.disable(:ci_variable_expansion_in_rules_changes) +``` + #### `rules:exists` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4. @@ -1567,7 +1502,7 @@ The [`rules`](#rules) syntax is an improved, more powerful solution for defining when jobs should run or not. Consider using `rules` instead of `only/except` to get the most out of your pipelines. -`only` and `except` are two parameters that set a job policy to limit when +`only` and `except` are two keywords that set a job policy to limit when jobs are created: 1. `only` defines the names of branches and tags the job runs for. @@ -1695,7 +1630,7 @@ while just `/issue/` would also match a branch called `severe-issues`. #### Supported `only`/`except` regexp syntax In GitLab 11.9.4, GitLab began internally converting the regexp used -in `only` and `except` parameters to [RE2](https://github.com/google/re2/wiki/Syntax). +in `only` and `except` keywords to [RE2](https://github.com/google/re2/wiki/Syntax). [RE2](https://github.com/google/re2/wiki/Syntax) limits the set of available features due to computational complexity, and some features, like negative lookaheads, became unavailable. @@ -2489,7 +2424,7 @@ deployment to the `production` environment. > - Before GitLab 8.11, the name of an environment could be defined as a string like > `environment: production`. The recommended way now is to define it under the > `name` keyword. -> - The `name` parameter can use any of the defined CI variables, +> - The `name` keyword can use any of the defined CI variables, > including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). > You however can't use variables defined under `script`. @@ -2525,7 +2460,7 @@ deploy to production: > - Introduced in GitLab 8.11. > - Before GitLab 8.11, the URL could be added only in GitLab's UI. The > recommended way now is to define it in `.gitlab-ci.yml`. -> - The `url` parameter can use any of the defined CI variables, +> - The `url` keyword can use any of the defined CI variables, > including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). > You however can't use variables defined under `script`. @@ -2624,7 +2559,7 @@ In the example above, if the configuration is not identical: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) in GitLab 12.8. -The `auto_stop_in` keyword is for specifying life period of the environment, +The `auto_stop_in` keyword is for specifying the lifetime of the environment, that when expired, GitLab automatically stops them. For example, @@ -2637,8 +2572,8 @@ review_app: auto_stop_in: 1 day ``` -When `review_app` job is executed and a review app is created, a life period of -the environment is set to `1 day`. +When the environment for `review_app` is created, the environment's lifetime is set to `1 day`. +Every time the review app is deployed, that lifetime is also reset to `1 day`. For more information, see [the environments auto-stop documentation](../environments/index.md#environments-auto-stop) @@ -2679,7 +2614,7 @@ To follow progress on support for GitLab-managed clusters, see the > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21971) in GitLab 8.12 and GitLab Runner 1.6. > - The `$CI_ENVIRONMENT_SLUG` was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22864) in GitLab 8.15. -> - The `name` and `url` parameters can use any of the defined CI variables, +> - The `name` and `url` keywords can use any of the defined CI variables, > including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). > You however can't use variables defined under `script`. @@ -2774,11 +2709,7 @@ Otherwise cache content can be overwritten. > Introduced in GitLab Runner v1.0.0. -The cache is shared between jobs, so if you're using different -paths for different jobs, you should also set a different `cache:key`. -Otherwise cache content can be overwritten. - -The `key` parameter defines the affinity of caching between jobs. +The `key` keyword defines the affinity of caching between jobs. You can have a single cache for all jobs, cache per-job, cache per-branch, or any other way that fits your workflow. This way, you can fine tune caching, including caching data between different jobs or even different branches. @@ -2812,6 +2743,32 @@ URI-encoded `%2F`. A value made only of dots (`.`, `%2E`) is also forbidden. You can specify a [fallback cache key](#fallback-cache-key) to use if the specified `cache:key` is not found. +#### Fallback cache key + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1534) in GitLab Runner 13.4. + +You can use the `$CI_COMMIT_REF_SLUG` [variable](#variables) to specify your [`cache:key`](#cachekey). +For example, if your `$CI_COMMIT_REF_SLUG` is `test` you can set a job +to download cache that's tagged with `test`. + +If a cache with this tag is not found, you can use `CACHE_FALLBACK_KEY` to +specify a cache to use when none exists. + +For example: + +```yaml +variables: + CACHE_FALLBACK_KEY: fallback-key + +cache: + key: "$CI_COMMIT_REF_SLUG" + paths: + - binaries/ +``` + +In this example, if the `$CI_COMMIT_REF_SLUG` is not found, the job uses the key defined +by the `CACHE_FALLBACK_KEY` variable. + ##### `cache:key:files` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5. @@ -2847,7 +2804,7 @@ use the new cache, instead of rebuilding the dependencies. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5. When you want to combine a prefix with the SHA computed for `cache:key:files`, -use the `prefix` parameter with `key:files`. +use the `prefix` keyword with `key:files`. For example, if you add a `prefix` of `test`, the resulting key is: `test-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5`. If neither file was changed in any commits, the prefix is added to `default`, so the key in the example would be `test-default`. @@ -3307,7 +3264,7 @@ It also exposes these reports in GitLab's UI (merge requests, pipeline views, an These are the available report types: -| Parameter | Description | +| Keyword | Description | |--------------------------------------------------------------------------------------------------------------------------------------|-------------| | [`artifacts:reports:cobertura`](../pipelines/job_artifacts.md#artifactsreportscobertura) | The `cobertura` report collects Cobertura coverage XML files. | | [`artifacts:reports:codequality`](../pipelines/job_artifacts.md#artifactsreportscodequality) | The `codequality` report collects CodeQuality issues. | @@ -3329,7 +3286,7 @@ These are the available report types: > Introduced in GitLab 8.6 and GitLab Runner v1.1.1. By default, all [`artifacts`](#artifacts) from previous [stages](#stages) -are passed to each job. However, you can use the `dependencies` parameter to +are passed to each job. However, you can use the `dependencies` keyword to define a limited list of jobs to fetch artifacts from. You can also set a job to download no artifacts at all. To use this feature, define `dependencies` in context of the job and pass @@ -3495,7 +3452,7 @@ Possible values for `when` are: - `scheduler_failure`: Retry if the scheduler failed to assign the job to a runner. - `data_integrity_failure`: Retry if there was a structural integrity problem detected. -You can specify the number of [retry attempts for certain stages of job execution](#job-stages-attempts) using variables. +You can specify the number of [retry attempts for certain stages of job execution](../runners/README.md#job-stages-attempts) using variables. ### `timeout` @@ -3522,7 +3479,7 @@ exceed the runner-specific timeout. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21480) in GitLab 11.5. Use `parallel` to configure how many instances of a job to run in -parallel. This value has to be greater than or equal to two (2) and less than or equal to 50. +parallel. This value can be from 2 to 50. This creates N instances of the same job that run in parallel. They are named sequentially from `job_name 1/N` to `job_name N/N`. @@ -3574,9 +3531,6 @@ There can be from 2 to 50 jobs. [In GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/26362) and later, you can have one-dimensional matrices with a single job. -The ability to have one-dimensional matrices is [deployed behind a feature flag](../../user/feature_flags.md), -enabled by default. It's enabled on GitLab.com. For self-managed GitLab instances, -administrators can opt to disable it by [disabling the `one_dimensional_matrix:` feature flag](../../administration/feature_flags.md). **(CORE ONLY)** Every job gets the same `CI_NODE_TOTAL` [environment variable](../variables/README.md#predefined-environment-variables) value, and a unique `CI_NODE_INDEX` value. @@ -3624,8 +3578,8 @@ Use `trigger` to define a downstream pipeline trigger. When GitLab starts a job with a `trigger` definition, a downstream pipeline is created. Jobs with `trigger` can only use a [limited set of keywords](../multi_project_pipelines.md#limitations). -For example, you can't run commands with [`script`](#script), [`before_script`](#before_script-and-after_script), -or [`after_script`](#before_script-and-after_script). +For example, you can't run commands with [`script`](#script), [`before_script`](#before_script), +or [`after_script`](#after_script). You can use this keyword to create two different types of downstream pipelines: @@ -3784,7 +3738,7 @@ starting, which reduces parallelization. To force a rebuild of a specific branch, tag, or commit, you can use an API call with a trigger token. -The trigger token is different than the [`trigger`](#trigger) parameter. +The trigger token is different than the [`trigger`](#trigger) keyword. [Read more in the triggers documentation.](../triggers/README.md) @@ -3884,8 +3838,8 @@ For more information, see [Deployments Safety](../environments/deployment_safety These methods are supported: - [`tag_name`](#releasetag_name) +- [`description`](#releasedescription) - [`name`](#releasename) (optional) -- [`description`](#releasedescription) (optional) - [`ref`](#releaseref) (optional) - [`milestones`](#releasemilestones) (optional) - [`released_at`](#releasereleased_at) (optional) @@ -3943,7 +3897,7 @@ For example, when creating a Release from a Git tag: job: release: tag_name: $CI_COMMIT_TAG - description: changelog.txt + description: 'Release description' ``` It is also possible to create any unique tag, in which case `only: tags` is not mandatory. @@ -3953,7 +3907,7 @@ A semantic versioning example: job: release: tag_name: ${MAJOR}_${MINOR}_${REVISION} - description: changelog.txt + description: 'Release description' ``` - The Release is created only if the job's main script succeeds. @@ -4160,8 +4114,8 @@ Read more on [GitLab Pages user documentation](../../user/project/pages/index.md > Introduced in GitLab Runner v0.5.0. -Variables are configurable values that are passed to jobs. They can be set -globally and per-job. +[CI/CD variables](../variables/README.md) are configurable values that are passed to jobs. +They can be set globally and per-job. There are two types of variables. @@ -4178,372 +4132,49 @@ Variables are meant for non-sensitive project configuration, for example: ```yaml variables: - DATABASE_URL: "postgres://postgres@postgres/my_database" + DEPLOY_SITE: "https://example.com/" + +deploy_job: + stage: deploy + script: + - deploy-script --url $DEPLOY_SITE --path "/" + +deploy_review_job: + stage: deploy + variables: + REVIEW_PATH: "/review" + script: + - deploy-review-script --url $DEPLOY_SITE --path $REVIEW_PATH ``` -You can use integers and strings for the variable's name and value. -You cannot use floats. +You can use only integers and strings for the variable's name and value. If you define a variable at the top level of the `gitlab-ci.yml` file, it is global, -meaning it applies to all jobs. - -If you define a variable within a job, it's available to that job only. +meaning it applies to all jobs. If you define a variable within a job, it's available +to that job only. If a variable of the same name is defined globally and for a specific job, the [job-specific variable is used](../variables/README.md#priority-of-environment-variables). All YAML-defined variables are also set to any linked -[service containers](../docker/using_docker_images.md#what-is-a-service). - -[YAML anchors for variables](#yaml-anchors-for-variables) are available. - -Learn more about [variables and their priority](../variables/README.md). - -### 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 for getting recent application code, either -globally or per-job in the [`variables`](#variables) section. If left -unspecified, the default from the project settings is used. - -There are three possible values: `clone`, `fetch`, and `none`. - -`clone` is the slowest option. It clones the repository from scratch for every -job, ensuring that the local working copy is always pristine. - -```yaml -variables: - GIT_STRATEGY: clone -``` - -`fetch` is faster as it re-uses the local working copy (falling back to `clone` -if it does not exist). `git clean` is used to undo any changes made by the last -job, and `git fetch` is used to retrieve commits made since the last job ran. - -```yaml -variables: - GIT_STRATEGY: fetch -``` - -`none` also re-uses the local working copy. However, it skips all Git operations, -including GitLab Runner's pre-clone script, if present. - -It's useful for jobs that operate exclusively on artifacts, like a deployment job. -Git repository data may be present, but it's likely out-of-date. You should only -rely on files brought into the local working copy from cache or artifacts. - -```yaml -variables: - GIT_STRATEGY: none -``` - -NOTE: **Note:** -`GIT_STRATEGY` is not supported for -[Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html), -but may be in the future. See the [support Git strategy with Kubernetes executor feature proposal](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3847) -for updates. - -### 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`](#variables) section. - -There are three possible values: `none`, `normal`, and `recursive`: - -- `none` means that submodules are not included when fetching the project - code. This is the default, which matches the pre-v1.10 behavior. - -- `normal` means that only the top-level submodules are included. It's - equivalent to: - - ```shell - git submodule sync - git submodule update --init - ``` - -- `recursive` means that all submodules (including submodules of submodules) - are included. This feature needs Git v1.8.1 and later. When using a - GitLab Runner with an executor not based on Docker, make sure the Git version - meets that requirement. It's equivalent to: - - ```shell - git submodule sync --recursive - git submodule update --init --recursive - ``` - -For this feature to work correctly, the submodules must be configured -(in `.gitmodules`) with either: - -- the HTTP(S) URL of a publicly-accessible repository, or -- a relative path to another repository on the same GitLab server. See the - [Git submodules](../git_submodules.md) documentation. - -### 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 -[`variables`](#variables) section. - -If set to `false`, the runner: - -- when doing `fetch` - updates the repository and leaves the working copy on - the current revision, -- when doing `clone` - clones the repository and leaves the working copy on the - default branch. - -If `GIT_CHECKOUT` is set to `true`, both `clone` and `fetch` work the same way. -The runner checks out the working copy of a revision related -to the CI pipeline: - -```yaml -variables: - GIT_STRATEGY: clone - GIT_CHECKOUT: "false" -script: - - git checkout -B master origin/master - - git merge $CI_COMMIT_SHA -``` - -### 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`](#variables) section. - -`GIT_CLEAN_FLAGS` accepts all possible options of the [`git clean`](https://git-scm.com/docs/git-clean) -command. - -`git clean` is disabled if `GIT_CHECKOUT: "false"` is specified. - -If `GIT_CLEAN_FLAGS` is: - -- Not specified, `git clean` flags default to `-ffdx`. -- Given the value `none`, `git clean` is not executed. - -For example: - -```yaml -variables: - GIT_CLEAN_FLAGS: -ffdx -e cache/ -script: - - ls -al cache/ -``` - -### Git fetch extra flags - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4142) in GitLab Runner 13.1. - -The `GIT_FETCH_EXTRA_FLAGS` variable is used to control the behavior of -`git fetch`. You can set it globally or per-job in the [`variables`](#variables) section. - -`GIT_FETCH_EXTRA_FLAGS` accepts all options of the [`git fetch`](https://git-scm.com/docs/git-fetch) command. However, `GIT_FETCH_EXTRA_FLAGS` flags are appended after the default flags that can't be modified. - -The default flags are: - -- [GIT_DEPTH](#shallow-cloning). -- The list of [refspecs](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec). -- A remote called `origin`. - -If `GIT_FETCH_EXTRA_FLAGS` is: - -- Not specified, `git fetch` flags default to `--prune --quiet` along with the default flags. -- Given the value `none`, `git fetch` is executed only with the default flags. - -For example, the default flags are `--prune --quiet`, so you can make `git fetch` more verbose by overriding this with just `--prune`: - -```yaml -variables: - GIT_FETCH_EXTRA_FLAGS: --prune -script: - - ls -al cache/ -``` - -The configuration above results in `git fetch` being called this way: +[Docker service containers](../docker/using_docker_images.md#what-is-a-service). -```shell -git fetch origin $REFSPECS --depth 50 --prune -``` - -Where `$REFSPECS` is a value provided to the runner internally by GitLab. - -### 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: - -| Variable | Description | -|-----------------------------------|--------------------------------------------------------| -| **ARTIFACT_DOWNLOAD_ATTEMPTS** | Number of attempts to download artifacts running a job | -| **EXECUTOR_JOB_SECTION_ATTEMPTS** | [In GitLab 12.10](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) and later, the number of attempts to run a section in a job after a [`No Such Container`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) error ([Docker executor](https://docs.gitlab.com/runner/executors/docker.html) only). | -| **GET_SOURCES_ATTEMPTS** | Number of attempts to fetch sources running a job | -| **RESTORE_CACHE_ATTEMPTS** | Number of attempts to restore the cache running a job | - -The default is one single attempt. - -Example: - -```yaml -variables: - GET_SOURCES_ATTEMPTS: 3 -``` - -You can set them globally or per-job in the [`variables`](#variables) section. - -### Fallback cache key - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1534) in GitLab Runner 13.4. - -You can use the `$CI_COMMIT_REF_SLUG` variable to specify your [`cache:key`](#cachekey). -For example, if your `$CI_COMMIT_REF_SLUG` is `test` you can set a job -to download cache that's tagged with `test`. - -If a cache with this tag is not found, you can use `CACHE_FALLBACK_KEY` to -specify a cache to use when none exists. - -For example: - -```yaml -variables: - CACHE_FALLBACK_KEY: fallback-key - -cache: - key: "$CI_COMMIT_REF_SLUG" - paths: - - binaries/ -``` - -In this example, if the `$CI_COMMIT_REF_SLUG` is not found, the job uses the key defined -by the `CACHE_FALLBACK_KEY` variable. - -### 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 -passed to `git fetch` and `git clone`. - -In GitLab 12.0 and later, newly-created projects automatically have a -[default `git depth` value of `50`](../pipelines/settings.md#git-shallow-clone). - -If you use a depth of `1` and have a queue of jobs or retry -jobs, jobs may fail. - -Git fetching and cloning is based on a ref, such as a branch name, so runners -can't clone a specific commit SHA. If multiple jobs are in the queue, or -you're retrying an old job, the commit to be tested must be within the -Git history that is cloned. Setting too small a value for `GIT_DEPTH` can make -it impossible to run these old commits and `unresolved reference` is displayed in -job logs. You should then reconsider changing `GIT_DEPTH` to a higher value. - -Jobs that rely on `git describe` may not work correctly when `GIT_DEPTH` is -set since only part of the Git history is present. - -To fetch or clone only the last 3 commits: - -```yaml -variables: - GIT_DEPTH: "3" -``` - -You can set it globally or per-job in the [`variables`](#variables) section. - -### Custom build directories +You can use [YAML anchors for variables](#yaml-anchors-for-variables). -> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2211) in GitLab Runner 11.10. +### Configure runner behavior with variables -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 -the `GIT_CLONE_PATH` variable to tell the runner the directory to clone the -repository in: +You can use [CI/CD variables](../variables/README.md) to configure runner Git behavior: -```yaml -variables: - GIT_CLONE_PATH: $CI_BUILDS_DIR/project-name - -test: - script: - - pwd -``` - -The `GIT_CLONE_PATH` has to always be within `$CI_BUILDS_DIR`. The directory set in `$CI_BUILDS_DIR` -is dependent on executor and configuration of [runners.builds_dir](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) -setting. +- [`GIT_STRATEGY`](../runners/README.md#git-strategy) +- [`GIT_SUBMODULE_STRATEGY`](../runners/README.md#git-submodule-strategy) +- [`GIT_CHECKOUT`](../runners/README.md#git-checkout) +- [`GIT_CLEAN_FLAGS`](../runners/README.md#git-clean-flags) +- [`GIT_FETCH_EXTRA_FLAGS`](../runners/README.md#git-fetch-extra-flags) +- [`GIT_DEPTH`](../runners/README.md#shallow-cloning) (shallow cloning) +- [`GIT_CLONE_PATH`](../runners/README.md#custom-build-directories) (custom build directories) -This can only be used when `custom_build_dir` is enabled in the -[runner's configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscustom_build_dir-section). -This is the default configuration for the `docker` and `kubernetes` executors. - -#### Handling concurrency - -An executor that uses a concurrency greater than `1` might lead -to failures. Multiple jobs might be working on the same directory if the `builds_dir` -is shared between jobs. - -The runner does not try to prevent this situation. It's up to the administrator -and developers to comply with the requirements of runner configuration. - -To avoid this scenario, you can use a unique path within `$CI_BUILDS_DIR`, because runner -exposes two additional variables that provide a unique `ID` of concurrency: - -- `$CI_CONCURRENT_ID`: Unique ID for all jobs running within the given executor. -- `$CI_CONCURRENT_PROJECT_ID`: Unique ID for all jobs running within the given executor and project. - -The most stable configuration that should work well in any scenario and on any executor -is to use `$CI_CONCURRENT_ID` in the `GIT_CLONE_PATH`. For example: - -```yaml -variables: - GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/project-name - -test: - script: - - pwd -``` - -The `$CI_CONCURRENT_PROJECT_ID` should be used in conjunction with `$CI_PROJECT_PATH` -as the `$CI_PROJECT_PATH` provides a path of a repository. That is, `group/subgroup/project`. For example: - -```yaml -variables: - GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_PATH - -test: - script: - - pwd -``` - -#### Nested paths - -The value of `GIT_CLONE_PATH` is expanded once and nesting variables -within is not supported. - -For example, you define both the variables below in your -`.gitlab-ci.yml` file: - -```yaml -variables: - GOPATH: $CI_BUILDS_DIR/go - GIT_CLONE_PATH: $GOPATH/src/namespace/project -``` - -The value of `GIT_CLONE_PATH` is expanded once into -`$CI_BUILDS_DIR/go/src/namespace/project`, and results in failure -because `$CI_BUILDS_DIR` is not expanded. +You can also use variables to configure how many times a runner +[attempts certain stages of job execution](../runners/README.md#job-stages-attempts). ## Special YAML features @@ -4573,7 +4204,7 @@ feature. Anchors are only valid within the file they were defined in. Instead of using YAML anchors, you can use the [`extends` keyword](#extends). The following example uses anchors and map merging. It creates two jobs, -`test1` and `test2`, that inherit the parameters of `.job_template`, each +`test1` and `test2`, that inherit the `.job_template` configuration, each with their own custom `script` defined: ```yaml @@ -4696,50 +4327,30 @@ test:mysql: You can see that the hidden jobs are conveniently used as templates, and `tags: [dev]` has been overwritten by `tags: [postgres]`. -#### YAML anchors for `before_script` and `after_script` +#### YAML anchors for scripts > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23005) in GitLab 12.5. -You can use [YAML anchors](#anchors) with `before_script` and `after_script`, -which makes it possible to include a predefined list of commands in multiple -jobs. - -Example: +You can use [YAML anchors](#anchors) with [script](#script), [`before_script`](#before_script), +and [`after_script`](#after_script) to use predefined commands in multiple jobs: ```yaml -.something_before: &something_before - - echo 'something before' - -.something_after: &something_after - - echo 'something after' - - echo 'another thing after' - -job_name: - before_script: - - *something_before - script: - - echo 'this is the script' - after_script: - - *something_after -``` - -#### YAML anchors for `script` +.some-script: &some-script + - echo "Execute this in `before_script` sections" -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23005) in GitLab 12.5. +.some-script-before: &some-script-before + - echo "Execute this in `script` sections" -You can use [YAML anchors](#anchors) with scripts, which makes it possible to -include a predefined list of commands in multiple jobs. - -For example: - -```yaml -.something: &something - - echo 'something' +.some-script-after: &some-script-after + - echo "Execute this in `after_script` sections" job_name: + before_script: + - *some-script-before script: - - *something - - echo 'this is the script' + - *some-script + before_script: + - *some-script-after ``` #### YAML anchors for variables @@ -4809,19 +4420,19 @@ This limitation does not affect any of the updated merge request pipelines. All updated merge requests have a pipeline created when using [pipelines for merge requests](../merge_request_pipelines/index.md). -## Deprecated parameters +## Deprecated keywords -The following parameters are deprecated. +The following keywords are deprecated. ### Globally-defined `types` -CAUTION: **Deprecated:** +DANGER: **Deprecated:** `types` is deprecated, and could be removed in a future release. Use [`stages`](#stages) instead. ### Job-defined `type` -CAUTION: **Deprecated:** +DANGER: **Deprecated:** `type` is deprecated, and could be removed in one of the future releases. Use [`stage`](#stage) instead. diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md new file mode 100644 index 00000000000..87885c8e548 --- /dev/null +++ b/doc/ci/yaml/script.md @@ -0,0 +1,147 @@ +--- +stage: Verify +group: Continuous Integration +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +type: reference +--- + +# GitLab CI/CD script syntax + +You can use special syntax in [`script`](README.md#script) sections to: + +- [Split long commands](#split-long-commands) into multiline commands. +- [Use color codes](#add-color-codes-to-script-output) to make job logs easier to review. +- [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections) + to simplify job log output. + +## Split long commands + +You can split long commands into multiline commands to improve readability with +`|` (literal) and `>` (folded) [YAML multiline block scalar indicators](https://yaml-multiline.info/). + +CAUTION: **Warning:** +If multiple commands are combined into one command string, only the last command's +failure or success is reported. +[Failures from earlier commands are ignored due to a bug](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/25394). +To work around this, run each command as a separate `script:` item, or add an `exit 1` +command to each command string. + +You can use the `|` (literal) YAML multiline block scalar indicator to write +commands over multiple lines in the `script` section of a job description. +Each line is treated as a separate command. +Only the first command is repeated in the job log, but additional +commands are still executed: + +```yaml +job: + script: + - | + echo "First command line." + echo "Second command line." + echo "Third command line." +``` + +The example above renders in the job log as: + +```shell +$ echo First command line # collapsed multiline command +First command line +Second command line. +Third command line. +``` + +The `>` (folded) YAML multiline block scalar indicator treats empty lines between +sections as the start of a new command: + +```yaml +job: + script: + - > + echo "First command line + is split over two lines." + + echo "Second command line." +``` + +This behaves similarly to multiline commands without the `>` or `|` block +scalar indicators: + +```yaml +job: + script: + - echo "First command line + is split over two lines." + + echo "Second command line." +``` + +Both examples above render in the job log as: + +```shell +$ echo First command line is split over two lines. # collapsed multiline command +First command line is split over two lines. +Second command line. +``` + +When you omit the `>` or `|` block scalar indicators, GitLab concatenates non-empty +lines to form the command. Make sure the lines can run when concatenated. + +[Shell here documents](https://en.wikipedia.org/wiki/Here_document) work with the +`|` and `>` operators as well. The example below transliterates lower case letters +to upper case: + +```yaml +job: + script: + - | + tr a-z A-Z << END_TEXT + one two three + four five six + END_TEXT +``` + +Results in: + +```shell +$ tr a-z A-Z << END_TEXT # collapsed multiline command + ONE TWO THREE + FOUR FIVE SIX +``` + +## Add color codes to script output + +Script output can be colored using [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors), +or by running commands or programs that output ANSI escape codes. + +For example, using [Bash with color codes](https://misc.flogisoft.com/bash/tip_colors_and_formatting): + +```yaml +job: + script: + - echo -e "\e[31mThis text is red,\e[0m but this text isn't\e[31m however this text is red again." +``` + +You can define the color codes in Shell variables, or even [custom environment variables](../variables/README.md#custom-environment-variables), +which makes the commands easier to read and reusable. + +For example, using the same example as above and variables defined in a `before_script`: + +```yaml +job: + before_script: + - TXT_RED="\e[31m" && TXT_CLEAR="\e[0m" + script: + - echo -e "${TXT_RED}This text is red,${TXT_CLEAR} but this part isn't${TXT_RED} however this part is again." + - echo "This text is not colored" +``` + +Or with [PowerShell color codes](https://superuser.com/a/1259916): + +```yaml +job: + before_script: + - $esc="$([char]27)"; $TXT_RED="$esc[31m"; $TXT_CLEAR="$esc[0m" + script: + - Write-Host $TXT_RED"This text is red,"$TXT_CLEAR" but this text isn't"$TXT_RED" however this text is red again." + - Write-Host "This text is not colored" +``` diff --git a/doc/ci/yaml/visualization.md b/doc/ci/yaml/visualization.md index ac5f5c8fd14..391ff9f852a 100644 --- a/doc/ci/yaml/visualization.md +++ b/doc/ci/yaml/visualization.md @@ -1,3 +1,9 @@ +--- +stage: Verify +group: Pipeline Authoring +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Visualize your CI/CD configuration > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241722) in GitLab 13.5. diff --git a/doc/development/README.md b/doc/development/README.md index 7b8a5cd5f75..75ea6ae5f3b 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -1,6 +1,10 @@ --- comments: false -description: 'Learn how to contribute to GitLab.' +type: index, dev +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +description: "Development Guidelines: learn how to contribute to GitLab." --- # Contributor and Development Docs @@ -60,6 +64,19 @@ Complementary reads: - [Patch release process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/patch/process.md#process-for-developers) - [Adding a new service component to GitLab](adding_service_component.md) +### Development guidelines review + +When you submit a change to GitLab's development guidelines, request a review +from: + +- A member of your team or group, to check for technical accuracy. +- For **significant** changes or proposals, request review from: + - Engineering managers (FE, BE, DB, Security, UX, and others), according to the subject or process you're proposing. + - The VP of Development (DRI) ([@clefelhocz1](https://gitlab.com/clefelhocz1)), for + final approval of the new or changed guidelines. +- The [Technical Writer assigned to dev guidelines](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines), + to review the content for consistency and adherence to documentation guidelines. + ## UX and Frontend guides - [GitLab Design System](https://design.gitlab.com/) for building GitLab with existing CSS styles and elements @@ -93,7 +110,6 @@ Complementary reads: - [Working with Merge Request diffs](diffs.md) - [Kubernetes integration guidelines](kubernetes.md) - [Permissions](permissions.md) -- [Prometheus](prometheus.md) - [Guidelines for reusing abstractions](reusing_abstractions.md) - [DeclarativePolicy framework](policies.md) - [How Git object deduplication works in GitLab](git_object_deduplication.md) @@ -117,17 +133,21 @@ Complementary reads: - [Approval Rules](approval_rules.md) - [Feature categorization](feature_categorization/index.md) - [Wikis development guide](wikis.md) +- [Newlines style guide](newlines_styleguide.md) +- [Image scaling guide](image_scaling.md) ## Performance guides - [Instrumentation](instrumentation.md) for Ruby code running in production - environments + environments. - [Performance guidelines](performance.md) for writing code, benchmarks, and - certain patterns to avoid + certain patterns to avoid. - [Merge request performance guidelines](merge_request_performance_guidelines.md) for ensuring merge requests do not negatively impact GitLab performance - [Profiling](profiling.md) a URL, measuring performance using Sherlock, or - tracking down N+1 queries using Bullet + tracking down N+1 queries using Bullet. +- [Cached queries guidelines](cached_queries.md), for tracking down N+1 queries masked by query caching, memory profiling and why should + we avoid cached queries. ## Database guides @@ -156,7 +176,7 @@ See [database guidelines](database/index.md). ## Documentation guides - [Writing documentation](documentation/index.md) -- [Documentation style guide](documentation/styleguide.md) +- [Documentation style guide](documentation/styleguide/index.md) - [Markdown](../user/markdown.md) ## Internationalization (i18n) guides @@ -167,7 +187,7 @@ See [database guidelines](database/index.md). ## Product Analytics guides -- [Product Analytics guide](product_analytics/index.md) +- [Product Analytics guide](https://about.gitlab.com/handbook/product/product-analytics-guide/) - [Usage Ping guide](product_analytics/usage_ping.md) - [Snowplow guide](product_analytics/snowplow.md) @@ -198,9 +218,9 @@ See [database guidelines](database/index.md). ## Other Development guides - [Defining relations between files using projections](projections.md) -- [Reference processing](./reference_processing.md) +- [Reference processing](reference_processing.md) - [Compatibility with multiple versions of the application running at the same time](multi_version_compatibility.md) -- [Features inside `.gitlab/`](./features_inside_dot_gitlab.md) +- [Features inside `.gitlab/`](features_inside_dot_gitlab.md) ## Other GitLab Development Kit (GDK) guides diff --git a/doc/development/adding_service_component.md b/doc/development/adding_service_component.md index bb5af286c1d..74309a5c616 100644 --- a/doc/development/adding_service_component.md +++ b/doc/development/adding_service_component.md @@ -1,10 +1,16 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Adding a new Service Component to GitLab The GitLab product is made up of several service components that run as independent system processes in communication with each other. These services can be run on the same instance, or spread across different instances. A list of the existing components can be found in the [GitLab architecture overview](architecture.md). ## Integration phases -The following outline re-uses the [maturity metric](https://about.gitlab.com/direction/maturity) naming as an example of the various phases of integrating a component. These are only loosely coupled to a components actual maturity, and are intended as a guide for implementation order (for example, a component does not need to be enabled by default to be Lovable, and being enabled by default does not on its own cause a component to be Lovable). +The following outline re-uses the [maturity metric](https://about.gitlab.com/direction/maturity/) naming as an example of the various phases of integrating a component. These are only loosely coupled to a components actual maturity, and are intended as a guide for implementation order (for example, a component does not need to be enabled by default to be Lovable, and being enabled by default does not on its own cause a component to be Lovable). - Proposed - [Proposing a new component](#proposing-a-new-component) @@ -53,10 +59,8 @@ TIP: **Tip:** ## Bundling a service with GitLab -NOTE: **Note:** Code shipped with GitLab needs to use a license approved by the Legal team. See the list of [existing approved licenses](https://about.gitlab.com/handbook/engineering/open-source/#using-open-source-libraries). -NOTE: **Note:** Notify the [Distribution team](https://about.gitlab.com/handbook/engineering/development/enablement/distribution/) when adding a new dependency that must be compiled. We must be able to compile the dependency on all supported platforms. New services to be bundled with GitLab need to be available in the following environments. diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 3d4c033e676..0e81a332d6c 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GraphQL API style guide This document outlines the style guide for GitLab's [GraphQL API](../api/graphql/index.md). @@ -126,8 +132,23 @@ Non-nullable fields should only be used when a field is required, very unlikely to become optional in the future, and very easy to calculate. An example would be `id` fields. +A non-nullable GraphQL schema field is an object type followed by the exclamation point (bang) `!`. Here's an example from the `gitlab_schema.graphql` file: + +```graphql + id: ProjectID! +``` + +Here's an example of a non-nullable GraphQL array: + +```graphql + + errors: [String!]! +``` + Further reading: +- [GraphQL Best Practices Guide](https://graphql.org/learn/best-practices/#nullability). +- GraphQL documentation on [Object types and fields](https://graphql.org/learn/schema/#object-types-and-fields). - [GraphQL Best Practices Guide](https://graphql.org/learn/best-practices/#nullability) - [Using nullability in GraphQL](https://www.apollographql.com/blog/using-nullability-in-graphql-2254f84c4ed7) @@ -376,7 +397,7 @@ field :foo, GraphQL::STRING_TYPE, 'if `my_feature_flag` feature flag is disabled' def foo - object.foo unless Feature.enabled?(:my_feature_flag, object) + object.foo if Feature.enabled?(:my_feature_flag, object) end ``` @@ -683,7 +704,7 @@ end ``` Fields can also be authorized against multiple abilities, in which case -all of ability checks must pass. **Note:** This requires explicitly +all of ability checks must pass. This requires explicitly passing a block to `field`: ```ruby @@ -696,7 +717,6 @@ module Types end ``` -NOTE: **Note:** If the field's type already [has a particular authorization](#type-authorization) then there is no need to add that same authorization to the field. @@ -736,7 +756,142 @@ To find objects to display in a field, we can add resolvers to Arguments can be defined within the resolver in the same way as in a mutation. See the [Mutation arguments](#object-identifier-arguments) section. -To limit the amount of queries performed, we can use `BatchLoader`. +To limit the amount of queries performed, we can use [BatchLoader](graphql_guide/batchloader.md). + +### Writing resolvers + +Our code should aim to be thin declarative wrappers around finders and services. You can +repeat lists of arguments, or extract them to concerns. Composition is preferred over +inheritance in most cases. Treat resolvers like controllers: resolvers should be a DSL +that compose other application abstractions. + +For example: + +```ruby +class PostResolver < BaseResolver + type Post.connection_type, null: true + authorize :read_blog + description 'Blog posts, optionally filtered by name' + + argument :name, [::GraphQL::STRING_TYPE], required: false, as: :slug + + alias_method :blog, :object + + def resolve(**args) + PostFinder.new(blog, current_user, args).execute + end +end +``` + +You should never re-use resolvers directly. Resolvers have a complex life-cycle, with +authorization, readiness and resolution orchestrated by the framework, and at +each stage lazy values can be returned to take advantage of batching +opportunities. Never instantiate a resolver or a mutation in application code. + +Instead, the units of code reuse are much the same as in the rest of the +application: + +- Finders in queries to look up data. +- Services in mutations to apply operations. +- Loaders (batch-aware finders) specific to queries. + +Note that there is never any reason to use batching in a mutation. Mutations are +executed in series, so there are no batching opportunities. All values are +evaluated eagerly as soon as they are requested, so batching is unnecessary +overhead. If you are writing: + +- A `Mutation`, feel free to lookup objects directly. +- A `Resolver` or methods on a `BaseObject`, then you want to allow for batching. + +### Deriving resolvers (`BaseResolver.single` and `BaseResolver.last`) + +For some simple use cases, we can derive resolvers from others. +The main use case for this is one resolver to find all items, and another to +find one specific one. For this, we supply convenience methods: + +- `BaseResolver.single`, which constructs a new resolver that selects the first item. +- `BaseResolver.last`, with constructs a resolver that selects the last item. + +The correct singular type is inferred from the collection type, so we don't have +to define the `type` here. + +Before you make use of these methods, consider if it would be simpler to either: + +- Write another resolver that defines its own arguments. +- Write a concern that abstracts out the query. + +Using `BaseResolver.single` too freely is an anti-pattern. It can lead to +non-sensical fields, such as a `Project.mergeRequest` field that just returns +the first MR if no arguments are given. Whenever we derive a single resolver +from a collection resolver, it must have more restrictive arguments. + +To make this possible, use the `when_single` block to customize the single +resolver. Every `when_single` block must: + +- Define (or re-define) at least one argument. +- Make optional filters required. + +For example, we can do this by redefining an existing optional argument, +changing its type and making it required: + +```ruby +class JobsResolver < BaseResolver + type JobType.connection_type, null: true + authorize :read_pipeline + + argument :name, [::GraphQL::STRING_TYPE], required: false + + when_single do + argument :name, ::GraphQL::STRING_TYPE, required: true + end + + def resolve(**args) + JobsFinder.new(pipeline, current_user, args.compact).execute + end +``` + +Here we have a simple resolver for getting pipeline jobs. The `name` argument is +optional when getting a list, but required when getting a single job. + +If there are multiple arguments, and neither can be made required, we can use +the block to add a ready condition: + +```ruby +class JobsResolver < BaseResolver + alias_method :pipeline, :object + + type JobType.connection_type, null: true + authorize :read_pipeline + + argument :name, [::GraphQL::STRING_TYPE], required: false + argument :id, [::Types::GlobalIDType[::Job]], + required: false, + prepare: ->(ids, ctx) { ids.map(&:model_id) } + + when_single do + argument :name, ::GraphQL::STRING_TYPE, required: false + argument :id, ::Types::GlobalIDType[::Job], + required: false + prepare: ->(id, ctx) { id.model_id } + + def ready?(**args) + raise ::Gitlab::Graphql::Errors::ArgumentError, 'Only one argument may be provided' unless args.size == 1 + end + end + + def resolve(**args) + JobsFinder.new(pipeline, current_user, args.compact).execute + end +``` + +Then we can use these resolver on fields: + +```ruby +# In PipelineType + +field :jobs, resolver: JobsResolver, description: 'All jobs' +field :job, resolver: JobsResolver.single, description: 'A single job' +``` ### Correct use of `Resolver#ready?` @@ -835,7 +990,29 @@ To avoid duplicated argument definitions, you can place these arguments in a reu class, if the arguments are nested). Alternatively, you can consider to add a [helper resolver method](https://gitlab.com/gitlab-org/gitlab/-/issues/258969). -## Pass a parent object into a child Presenter +### Metadata + +When using resolvers, they can and should serve as the SSoT for field metadata. +All field options (apart from the field name) can be declared on the resolver. +These include: + +- `type` (this is particularly important, and will soon be mandatory) +- `extras` +- `description` + +Example: + +```ruby +module Resolvers + MyResolver < BaseResolver + type Types::MyType, null: true + extras [:lookahead] + description 'Retrieve a single MyType' + end +end +``` + +### Pass a parent object into a child Presenter Sometimes you need to access the resolved query parent in a child context to compute fields. Usually the parent is only available in the `Resolver` class as `parent`. @@ -850,7 +1027,7 @@ To find the parent object in your `Presenter` class: end ``` -1. Declare that your fields require the `parent` field context. For example: +1. Declare that your resolver or fields require the `parent` field context. For example: ```ruby # in ChildType @@ -858,6 +1035,14 @@ To find the parent object in your `Presenter` class: method: :my_computing_method, extras: [:parent], # Necessary description: 'My field description' + + field :resolver_field, resolver: SomeTypeResolver + + # In SomeTypeResolver + + extras [:parent] + type SomeType, null: true + description 'My field description' ``` 1. Declare your field's method in your Presenter class and have it accept the `parent` keyword argument. @@ -869,6 +1054,12 @@ This argument contains the parent **GraphQL context**, so you have to access the def my_computing_method(parent:) # do something with `parent[:parent_object]` here end + + # In SomeTypeResolver + + def resolve(parent:) + # ... + end ``` For an example of real-world use, check [this MR that added `scopedPath` and `scopedUrl` to `IterationPresenter`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39543) @@ -1273,6 +1464,11 @@ tested for within the unit test of `Types::MutationType`. The merge request can be referred to as an example of this, including the method of testing deprecated aliased mutations. +#### Deprecating EE mutations + +EE mutations should follow the same process. For an example of the merge request +process, read [merge request !42588](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42588). + ## Pagination implementation To learn more, visit [GraphQL pagination](graphql_guide/pagination.md). @@ -1381,6 +1577,62 @@ it 'returns a successful response' do end ``` +### Testing tips and tricks + +- Avoid false positives: + + Authenticating a user with the `current_user:` argument for `post_graphql` + generates more queries on the first request than on subsequent requests on that + same user. If you are testing for N+1 queries using + [QueryRecorder](query_recorder.md), use a **different** user for each request. + + The below example shows how a test for avoiding N+1 queries should look: + + ```ruby + RSpec.describe 'Query.project(fullPath).pipelines' do + include GraphqlHelpers + + let(:project) { create(:project) } + + let(:query) do + %( + { + project(fullPath: "#{project.full_path}") { + pipelines { + nodes { + id + } + } + } + } + ) + end + + it 'avoids N+1 queries' do + first_user = create(:user) + second_user = create(:user) + create(:ci_pipeline, project: project) + + control_count = ActiveRecord::QueryRecorder.new do + post_graphql(query, current_user: first_user) + end + + create(:ci_pipeline, project: project) + + expect do + post_graphql(query, current_user: second_user) # use a different user to avoid a false positive from authentication queries + end.not_to exceed_query_limit(control_count) + end + end + ``` + +- Mimic the folder structure of `app/graphql/types`: + + For example, tests for fields on `Types::Ci::PipelineType` + in `app/graphql/types/ci/pipeline_type.rb` should live in + `spec/requests/api/graphql/ci/pipeline_spec.rb` regardless of the query being + used to fetch the pipeline data. + ## Notes about Query flow and GraphQL infrastructure GitLab's GraphQL infrastructure can be found in `lib/gitlab/graphql`. @@ -1446,3 +1698,7 @@ For information on generating GraphQL documentation and schema files, see To help our readers, you should also add a new page to our [GraphQL API](../api/graphql/index.md) documentation. For guidance, see the [GraphQL API](documentation/graphql_styleguide.md) page. + +## Include a changelog entry + +All client-facing changes **must** include a [changelog entry](changelog.md). diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index 47c06377d88..d21975a43d2 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # API style guide This style guide recommends best practices for API development. @@ -201,6 +207,12 @@ guide on how you can add a new custom validator. checks if the value of the given parameter is either an `Array`, `None`, or `Any`. It allows only either of these mentioned values to move forward in the request. +- `EmailOrEmailList`: + + The [`EmailOrEmailList` validator](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/validations/validators/email_or_email_list.rb) + checks if the value of a string or a list of strings contains only valid + email addresses. It allows only lists with all valid email addresses to move forward in the request. + ### Adding a new custom validator Custom validators are a great way to validate parameters before sending @@ -228,7 +240,7 @@ it's own file in the [`validators`](https://gitlab.com/gitlab-org/gitlab/-/blob/ ## Internal API -The [internal API](./internal_api.md) is documented for internal use. Please keep it up to date so we know what endpoints +The [internal API](internal_api.md) is documented for internal use. Please keep it up to date so we know what endpoints different components are making use of. ## Avoiding N+1 problems @@ -285,10 +297,15 @@ end ## Testing -When writing tests for new API endpoints, consider using a schema [fixture](./testing_guide/best_practices.md#fixtures) located in `/spec/fixtures/api/schemas`. You can `expect` a response to match a given schema: +When writing tests for new API endpoints, consider using a schema [fixture](testing_guide/best_practices.md#fixtures) located in `/spec/fixtures/api/schemas`. You can `expect` a response to match a given schema: ```ruby expect(response).to match_response_schema('merge_requests') ``` Also see [verifying N+1 performance](#verifying-with-tests) in tests. + +## Include a changelog entry + +All client-facing changes **must** include a [changelog entry](changelog.md). +This does not include internal APIs. diff --git a/doc/development/application_limits.md b/doc/development/application_limits.md index f96ed2e7f57..41fcf5301ad 100644 --- a/doc/development/application_limits.md +++ b/doc/development/application_limits.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Application limits development This document provides a development guide for contributors to add application @@ -27,7 +33,6 @@ It's recommended to create two separate migration script files. add_column(:plan_limits, :project_hooks, :integer, default: 100, null: false) ``` - NOTE: **Note:** Plan limits entries set to `0` mean that limits are not enabled. You should use this setting only in special and documented circumstances. @@ -58,7 +63,6 @@ It's recommended to create two separate migration script files. end ``` - NOTE: **Note:** Some plans exist only on GitLab.com. This will be a no-op for plans that do not exist. @@ -97,7 +101,6 @@ can be used to validate that a model does not exceed the limits. It ensures that the count of the records for the current model does not exceed the defined limit. -NOTE: **Note:** You must specify the limit scope of the object being validated and the limit name if it's different from the pluralized model name. @@ -146,5 +149,4 @@ GitLab.com: - `silver` - Namespaces and projects with a Silver subscription - `gold` - Namespaces and projects with a Gold subscription -NOTE: **Note:** -The test environment doesn't have any plans. +The `test` environment doesn't have any plans. diff --git a/doc/development/application_secrets.md b/doc/development/application_secrets.md index 24755586cf8..abc5ff7b985 100644 --- a/doc/development/application_secrets.md +++ b/doc/development/application_secrets.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Application secrets This page is a development guide for application secrets. diff --git a/doc/development/approval_rules.md b/doc/development/approval_rules.md index f295c20a36f..d190f2b7c63 100644 --- a/doc/development/approval_rules.md +++ b/doc/development/approval_rules.md @@ -1,3 +1,9 @@ +--- +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/engineering/ux/technical-writing/#designated-technical-writers +--- + # Approval Rules **(STARTER)** This document explains the backend design and flow of all related functionality @@ -14,7 +20,7 @@ feature to work. NOTE: **Note:** This is a living document and should be updated accordingly when parts -of the codebase touched in this document changed/removed or when new components +of the codebase touched in this document are changed or removed, or when new components are added. ## Data Model @@ -141,7 +147,7 @@ Whenever an approval is given/revoked, a record is created/deleted. ## Controllers and Services -The following controllers and services below are being utilized for the approval +The following controllers and services below are being used for the approval rules feature to work. ### `API::ProjectApprovalSettings` diff --git a/doc/development/architecture.md b/doc/development/architecture.md index 513af491576..a1097ad4ed6 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab architecture overview ## Software delivery @@ -252,6 +258,7 @@ Table description links: | [NGINX](#nginx) | Routes requests to appropriate components, terminates SSL | ✅ | ✅ | ⚙ | ✅ | ⤓ | ❌ | CE & EE | | [Node Exporter](#node-exporter) | Prometheus endpoint with system metrics | ✅ | N/A | N/A | ✅ | ❌ | ❌ | CE & EE | | [Outbound email (SMTP)](#outbound-email) | Send email messages to users | ⤓ | ⚙ | ⤓ | ✅ | ⤓ | ⤓ | CE & EE | +| [Patroni](#patroni) | Manage PostgreSQL HA cluster leader selection and replication | ⚙ | ❌ | ❌ | ✅ | ❌ | ❌ | EE Only | | [PgBouncer Exporter](#pgbouncer-exporter) | Prometheus endpoint with PgBouncer metrics | ⚙ | ❌ | ❌ | ✅ | ❌ | ❌ | CE & EE | | [PgBouncer](#pgbouncer) | Database connection pooling, failover | ⚙ | ❌ | ❌ | ✅ | ❌ | ❌ | EE Only | | [PostgreSQL Exporter](#postgresql-exporter) | Prometheus endpoint with PostgreSQL metrics | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | CE & EE | @@ -539,6 +546,15 @@ NGINX has an Ingress port for all HTTP requests and routes them to the appropria [Node Exporter](https://github.com/prometheus/node_exporter) is a Prometheus tool that gives us metrics on the underlying machine (think CPU/Disk/Load). It's just a packaged version of the common open source offering from the Prometheus project. +#### Patroni + +- [Project Page](https://github.com/zalando/patroni) +- Configuration: + - [Omnibus](../administration/postgresql/replication_and_failover.md#patroni) +- Layer: Core Service (Data) +- Process: `patroni` +- GitLab.com: [Database Architecture](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/#database-architecture) + #### PgBouncer - [Project page](https://github.com/pgbouncer/pgbouncer/blob/master/README.md) @@ -681,7 +697,6 @@ Sidekiq is a Ruby background job processor that pulls jobs from the Redis queue #### Puma -NOTE: **Note:** Starting with GitLab 13.0, Puma is the default web server and Unicorn has been disabled by default. @@ -699,7 +714,6 @@ disabled by default. #### Unicorn -NOTE: **Note:** Starting with GitLab 13.0, Puma is the default web server and Unicorn has been disabled by default. @@ -931,7 +945,7 @@ processes: `puma master` (1 process), `puma cluster worker` ### Repository access -Repositories get accessed via HTTP or SSH. HTTP cloning/push/pull utilizes the GitLab API and SSH cloning is handled by GitLab Shell (previously explained). +Repositories get accessed via HTTP or SSH. HTTP cloning/push/pull uses the GitLab API and SSH cloning is handled by GitLab Shell (previously explained). ## Troubleshooting @@ -1015,9 +1029,9 @@ PostgreSQL: GitLab has configuration files located in `/home/git/gitlab/config/*`. Commonly referenced configuration files include: -- `gitlab.yml` - GitLab configuration -- `puma.rb` - Puma web server settings -- `database.yml` - Database connection settings +- `gitlab.yml`: GitLab configuration +- `puma.rb`: Puma web server settings +- `database.yml`: Database connection settings GitLab Shell has a configuration file at `/home/git/gitlab-shell/config.yml`. @@ -1033,9 +1047,12 @@ bundle exec rake gitlab:env:info RAILS_ENV=production bundle exec rake gitlab:check RAILS_ENV=production ``` -Note: It is recommended to log into the `git` user using `sudo -i -u git` or `sudo su - git`. While -the `sudo` commands provided by GitLab work in Ubuntu they do not always work in RHEL. +It's recommended to sign in to the `git` user using either `sudo -i -u git` or +`sudo su - git`. Although the `sudo` commands provided by GitLab work in Ubuntu, +they don't always work in RHEL. ## GitLab.com -We've also detailed [our architecture of GitLab.com](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/) but this is probably over the top unless you have millions of users. +The [GitLab.com architecture](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/) +is detailed for your reference, but this architecture is only useful if you have +millions of users. diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index e5cc2ae4d1d..86a2aed5ea1 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -343,10 +343,32 @@ for more details. 1. Make sure that tests you write are not false positives. 1. Make sure that if the data being migrated is critical and cannot be lost, the clean-up migration also checks the final state of the data before completing. -1. Make sure to know how much time it'll take to run all scheduled migrations. 1. When migrating many columns, make sure it won't generate too many dead tuples in the process (you may need to directly query the number of dead tuples and adjust the scheduling according to this piece of data). 1. Make sure to 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. Make sure to know how much time it'll take to run all scheduled migrations. +1. Provide an estimation section in the description, explaining timings from the + linked query plans and batches as described in the migration. + + For example, assuming a migration that deletes data, include information similar to + the following section: + + ```ruby + Background Migration Details: + + 47600 items to delete + batch size = 1000 + 47600 / 1000 = 48 loops + + Estimated times per batch: + - 900ms for select statement with 1000 items + - 2100ms for delete statement with 1000 items + Total: ~3sec per batch + + 2 mins delay per loop (safe for the given total time per batch) + + 48 * ( 120 + 3) = ~98.4 mins to run all the scheduled jobs + ``` diff --git a/doc/development/cached_queries.md b/doc/development/cached_queries.md new file mode 100644 index 00000000000..812e5f88754 --- /dev/null +++ b/doc/development/cached_queries.md @@ -0,0 +1,139 @@ +# Cached queries guidelines + +Rails provides an [SQL query cache](https://guides.rubyonrails.org/caching_with_rails.html#sql-caching), +used to cache the results of database queries for the duration of the request. + +If Rails encounters the same query again for that request, +it will use the cached result set as opposed to running the query against the database again. + +The query results are only cached for the duration of that single request, it does not persist across multiple requests. + +## Why cached queries are considered bad + +The cached queries help with reducing DB load, but they still: + +- Consume memory. +- Require as to re-instantiate each `ActiveRecord` object. +- Require as to re-instantiate each relation of the object. +- Make us spend additional CPU-cycles to look into a list of cached queries. + +The Cached SQL queries are cheaper, but they are not cheap at all from `memory` perspective. +They could mask [N+1 query problem](https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations), +so we should threat them the same way we threat regular N+1 queries. + +In case of N+1 queries, masked with cached queries, we are executing the same query N times. +It will not hit the database N times, it will return the cached results instead. +This is still expensive since we need to re-initialize objects each time, and this is CPU/Memory expensive. +Instead, we should use the same in-memory objects, if possible. + +When we introduce a new feature, we should avoid N+1 problems, +minimize the [query count](merge_request_performance_guidelines.md#query-counts), and pay special attention that [cached +queries](merge_request_performance_guidelines.md#cached-queries) are not masking N+1 problems. + +## How to detect + +### Detect potential offenders by using Kibana + +On GitLab.com, we are logging entries with the number of executed cached queries in the +`pubsub-redis-inf-gprd*` index with the [`db_cached_count`](https://log.gprd.gitlab.net/goto/77d18d80ad84c5df1bf1da5c2cd35b82). +We can filter endpoints that have a large number of executed cached queries. For example, if we encounter an endpoint +that has 100+ `db_cached_count`, this could indicate that there is an N+1 problem masked with cached queries. +We should probably investigate this endpoint further, to check if we are executing duplicated cached queries. + +For more cached queries Kibana visualizations see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/259007). + +### Inspect suspicious endpoint using Performance Bar + +When building features, you could use the [performance bar](../administration/monitoring/performance/performance_bar.md) +to list database queries, which will include cached queries as well. The performance bar will show a warning +when threshold of total executed queries (including cached ones) has exceeded 100 queries. + +## What to look for + +Using [Kibana](cached_queries.md#detect-potential-offenders-by-using-kibana), you can look for a large number +of executed cached queries. End-points with large number of `db_cached_count` could indicate that there +are probably a lot of duplicated cached queries, which often indicates a masked N+1 problem. + +When you investigate specific endpoint, you could use +the [performance bar](cached_queries.md#inspect-suspicious-endpoint-using-performance-bar). +If you see a lot of similar queries, this often indicates an N+1 query issue (or a similar kind of query batching problem). +If you see same cached query executed multiple times, this often indicates a masked N+1 query problem. + +For example, let's say you wanted to debug `GroupMembers` page. + +In the left corner of the performance bar you could see **Database queries** showing the total number of database queries +and the number of executed cached queries: + + + +We can see that there are 55 cached queries. By clicking on the number, a modal window with more details is shown. +Cached queries are marked with the `cached` label, so they are easy to spot. We can see that there are multiple duplicated +cached queries: + + + +If we click on `...` for one of them, it will expand the actual stack trace: + +```shell +[ + "app/models/group.rb:305:in `has_owner?'", + "ee/app/views/shared/members/ee/_license_badge.html.haml:1", + "app/helpers/application_helper.rb:19:in `render_if_exists'", + "app/views/shared/members/_member.html.haml:31", + "app/views/groups/group_members/index.html.haml:75", + "app/controllers/application_controller.rb:134:in `render'", + "ee/lib/gitlab/ip_address_state.rb:10:in `with'", + "ee/app/controllers/ee/application_controller.rb:44:in `set_current_ip_address'", + "app/controllers/application_controller.rb:493:in `set_current_admin'", + "lib/gitlab/session.rb:11:in `with_session'", + "app/controllers/application_controller.rb:484:in `set_session_storage'", + "app/controllers/application_controller.rb:478:in `set_locale'", + "lib/gitlab/error_tracking.rb:52:in `with_context'", + "app/controllers/application_controller.rb:543:in `sentry_context'", + "app/controllers/application_controller.rb:471:in `block in set_current_context'", + "lib/gitlab/application_context.rb:54:in `block in use'", + "lib/gitlab/application_context.rb:54:in `use'", + "lib/gitlab/application_context.rb:21:in `with_context'", + "app/controllers/application_controller.rb:463:in `set_current_context'", + "lib/gitlab/jira/middleware.rb:19:in `call'" +] +``` + +The stack trace, shows us that we obviously have an N+1 problem, since we are repeatably executing for each group member: + +```ruby +group.has_owner?(current_user) +``` + +This is easily solvable by extracting this check, above the loop. + +After [the fix](https://gitlab.com/gitlab-org/gitlab/-/issues/231468), we now have: + + + +## How to measure the impact of the change + +We can use the [memory profiler](performance.md#using-memory-profiler) to profile our code. +For the previous example, we could wrap the profiler around the `Groups::GroupMembersController#index` action. + +We had: + +- Total allocated: 7133601 bytes (84858 objects) +- Total retained: 757595 bytes (6070 objects) +- `db_count`: 144 +- `db_cached_count`: 55 +- `db_duration`: 303ms + +After the fix, we can see that we have reduced the allocated memory as well as the number of cached queries and improved execution time: + +- Total allocated: 5313899 bytes (65290 objects), 1810KB (25%) less +- Total retained: 685593 bytes (5278 objects), 72KB (9%) less +- `db_count`: 95 (34% less) +- `db_cached_count`: 6 (89% less) +- `db_duration`: 162ms (87% faster) + +## See also + +- [Metrics that would help us detect the potential N+1 Cached SQL calls](https://gitlab.com/gitlab-org/gitlab/-/issues/259007) +- [Merge Request performance guidelines for cached queries](merge_request_performance_guidelines.md#cached-queries) +- [Improvements for biggest offenders](https://gitlab.com/groups/gitlab-org/-/epics/4508) diff --git a/doc/development/changelog.md b/doc/development/changelog.md index 922c4814d91..b8e879c1826 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Changelog entries This guide contains instructions for when and how to generate a changelog entry @@ -38,9 +44,10 @@ the `author` field. GitLab team members **should not**. - [Security fixes](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md) **must** have a changelog entry, without `merge_request` value and with `type` set to `security`. -- Any user-facing change **should** have a changelog entry. This includes both visual changes (regardless of how minor), and changes to the rendered DOM which impact how a screen reader may announce the content. +- Any user-facing change **must** have a changelog entry. This includes both visual changes (regardless of how minor), and changes to the rendered DOM which impact how a screen reader may announce the content. +- Any client-facing change to our REST and GraphQL APIs **must** have a changelog entry. - Performance improvements **should** have a changelog entry. -- Changes that need to be documented in the Product Analytics [Event Dictionary](product_analytics/event_dictionary.md) +- Changes that need to be documented in the Product Analytics [Event Dictionary](https://about.gitlab.com/handbook/product/product-analytics-guide#event-dictionary) also require a changelog entry. - _Any_ contribution from a community member, no matter how small, **may** have a changelog entry regardless of these guidelines if the contributor wants one. @@ -48,7 +55,8 @@ the `author` field. GitLab team members **should not**. - Any docs-only changes **should not** have a changelog entry. - Any change behind a disabled feature flag **should not** have a changelog entry. - Any change behind an enabled feature flag **should** have a changelog entry. -- Any change that adds new usage data metrics and changes that needs to be documented in Product Analytics [Event Dictionary](telemetry/event_dictionary.md) **should** have a changelog entry. +- Any change that adds new usage data metrics and changes that needs to be documented in Product Analytics [Event Dictionary](https://about.gitlab.com/handbook/product/product-analytics-guide#event-dictionary) **should** have a changelog entry. +- A change that adds snowplow events **should** have a changelog entry - - A change that [removes a feature flag](feature_flags/development.md) **should** have a changelog entry - only if the feature flag did not default to true already. - A fix for a regression introduced and then fixed in the same release (i.e., @@ -117,7 +125,6 @@ the `--ee` option: bin/changelog --ee 'Hey DZ, I added a feature to GitLab!' ``` -NOTE: **Note:** All entries in the `CHANGELOG.md` file apply to all editions of GitLab. Changelog updates are based on a common [GitLab codebase](https://gitlab.com/gitlab-org/gitlab/), and are mirrored without proprietary code to [GitLab FOSS](https://gitlab.com/gitlab-org/gitlab-foss/) (also known as GitLab Community Edition). diff --git a/doc/development/chaos_endpoints.md b/doc/development/chaos_endpoints.md index 26ff3d2def7..63218af857d 100644 --- a/doc/development/chaos_endpoints.md +++ b/doc/development/chaos_endpoints.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Generating chaos in a test GitLab instance As [Werner Vogels](https://twitter.com/Werner), the CTO at Amazon Web Services, famously put it, **Everything fails, all the time**. @@ -18,7 +24,7 @@ Currently, there are four endpoints for simulating the following conditions: For obvious reasons, these endpoints are not enabled by default on `production`. They are enabled by default on **development** environments. -DANGER: **Danger:** +DANGER: **Warning:** It is required that you secure access to the chaos endpoints using a secret token. You should not enable them in production unless you absolutely know what you're doing. @@ -44,8 +50,7 @@ each endpoint can be set to `true`. This will run the chaos process in a Sidekiq To simulate a memory leak in your application, use the `/-/chaos/leakmem` endpoint. -NOTE: **Note:** -The memory is not retained after the request finishes. Once the request has completed, the Ruby garbage collector will attempt to recover the memory. +The memory is not retained after the request finishes. After the request has completed, the Ruby garbage collector will attempt to recover the memory. ```plaintext GET /-/chaos/leakmem @@ -80,7 +85,7 @@ GET /-/chaos/cpu_spin?duration_s=50&async=true | Attribute | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------------------------------------------- | -| `duration_s` | integer | no | Duration, in seconds, that the core will be utilized. Defaults to 30s | +| `duration_s` | integer | no | Duration, in seconds, that the core will be used. Defaults to 30s | | `async` | boolean | no | Set to true to consume CPU in a Sidekiq background worker process | ```shell @@ -105,7 +110,7 @@ GET /-/chaos/db_spin?duration_s=50&async=true | Attribute | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------------------------------------------------- | | `interval_s` | float | no | Interval, in seconds, for every DB request. Defaults to 1s | -| `duration_s` | integer | no | Duration, in seconds, that the core will be utilized. Defaults to 30s | +| `duration_s` | integer | no | Duration, in seconds, that the core will be used. Defaults to 30s | | `async` | boolean | no | Set to true to perform the operation in a Sidekiq background worker process | ```shell @@ -139,8 +144,8 @@ curl http://localhost:3000/-/chaos/sleep?duration_s=60&token=secret This endpoint will simulate the unexpected death of a worker process using a `kill` signal. -NOTE: **Note:** -Since this endpoint uses the `KILL` signal, the worker is not given a chance to cleanup or shutdown. +Because this endpoint uses the `KILL` signal, the worker isn't given an +opportunity to cleanup or shutdown. ```plaintext GET /-/chaos/kill diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md index 7d522a55559..e4c3e622ede 100644 --- a/doc/development/cicd/templates.md +++ b/doc/development/cicd/templates.md @@ -174,3 +174,7 @@ is updated in a major version GitLab release. A template could contain malicious code. For example, a template that contains the `export` shell command in a job might accidentally expose project secret variables in a job log. If you're unsure if it's secure or not, you need to ask security experts for cross-validation. + +## Contribute CI/CD Template Merge Requests + +After your CI/CD Template MR is created and labeled with `ci::templates`, DangerBot suggests one reviewer and one maintainer that can review your code. When your merge request is ready for review, please `@mention` the reviewer and ask them to review your CI/CD Template changes. See details in the merge request that added [a DangerBot task for CI/CD Template MRs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44688). diff --git a/doc/development/code_comments.md b/doc/development/code_comments.md index b0e83b29cb0..d9ab719d18a 100644 --- a/doc/development/code_comments.md +++ b/doc/development/code_comments.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Code comments Whenever you add comment to the code that is expected to be addressed at any time diff --git a/doc/development/code_intelligence/index.md b/doc/development/code_intelligence/index.md index bd11f0bff79..24abf57e9d6 100644 --- a/doc/development/code_intelligence/index.md +++ b/doc/development/code_intelligence/index.md @@ -1,3 +1,9 @@ +--- +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/engineering/ux/technical-writing/#designated-technical-writers +--- + # Code Intelligence > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/1576) in GitLab 13.1. diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 3ff802d3b23..63a47240435 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Code Review Guidelines This guide contains advice and best practices for performing code review, and @@ -91,8 +97,14 @@ with [domain expertise](#domain-experts). **approved by a [frontend maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_maintainers_frontend)**. 1. If your merge request includes UX changes (*1*), it must be **approved by a [UX team member](https://about.gitlab.com/company/team/)**. -1. If your merge request includes adding a new JavaScript library (*1*), it must be - **approved by a [frontend lead](https://about.gitlab.com/company/team/)**. +1. If your merge request includes adding a new JavaScript library (*1*)... + - If the library significantly increases the + [bundle size](https://gitlab.com/gitlab-org/frontend/playground/webpack-memory-metrics/-/blob/master/doc/report.md), it must + be **approved by a [frontend foundations member](https://about.gitlab.com/direction/create/ecosystem/frontend-ux-foundations/)**. + - If the license used by the new library hasn't been approved for use in + GitLab, the license must be **approved by a [legal department member](https://about.gitlab.com/handbook/legal/)**. + More information about license compatiblity can be found in our + [GitLab Licensing and Compatibility documentation](licensing.md). 1. If your merge request includes adding a new UI/UX paradigm (*1*), it must be **approved by a [UX lead](https://about.gitlab.com/company/team/)**. 1. If your merge request includes a new dependency or a filesystem change, it must be @@ -378,8 +390,7 @@ When ready to merge: - When you set the MR to "Merge When Pipeline Succeeds", you should take over subsequent revisions for anything that would be spotted after that. -NOTE: **Note:** -Thanks to "Pipeline for Merged Results", authors won't have to rebase their +Thanks to **Pipeline for Merged Results**, authors won't have to rebase their branch as frequently anymore (only when there are conflicts) since the Merge Results Pipeline will already incorporate the latest changes from `master`. This results in faster review/merge cycles since maintainers don't have to ask diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 6cbe57bf926..17431195c3d 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -37,7 +37,7 @@ Report suspected security vulnerabilities in private to `support@gitlab.com`, also see the [disclosure section on the GitLab.com website](https://about.gitlab.com/security/disclosure/). -DANGER: **Danger:** +DANGER: **Warning:** Do **NOT** create publicly viewable issues for suspected security vulnerabilities. ## Code of conduct @@ -146,7 +146,7 @@ Keep the following in mind when submitting merge requests: reviewers. - If the code quality is found to not meet GitLab’s standards, the merge request reviewer will provide guidance and refer the author to our: - - [Documentation](../documentation/styleguide.md) style guide. + - [Documentation](../documentation/styleguide/index.md) style guide. - Code style guides. - Sometimes style guides will be followed but the code will lack structural integrity, or the reviewer will have reservations about the code’s overall quality. When there is a reservation, diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index b7c05a369f0..99650c24661 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -90,25 +90,6 @@ explain what falls under each type label. The GitLab handbook documents [when something is a bug](https://about.gitlab.com/handbook/product/product-processes/#bug-issues) and [when it is a feature request](https://about.gitlab.com/handbook/product/product-processes/#feature-issues). -### Facet labels - -Sometimes it's useful to refine the type of an issue. In those cases, you can -add facet labels. - -Following is a non-exhaustive list of facet labels: - -- ~enhancement: This label can refine an issue that has the ~feature label. -- ~"master:broken": This label can refine an issue that has the ~bug label. -- ~"failure::flaky-test": This label can refine an issue that has the ~bug label. -- ~"technical debt": This label can refine an issue that has the ~tooling label. -- ~"static analysis": This label can refine an issue that has the ~tooling label. -- ~"ci-build": This label can refine an issue that has the ~tooling label. -- ~performance: A performance issue could describe a ~bug or a ~feature. -- ~security: A security issue could describe a ~bug or a ~feature. -- ~database: A database issue could describe a ~bug or a ~feature. -- ~customer: This relates to an issue that was created by a customer, or that is of interest for a customer. -- ~"UI text": Issues that add or modify any text within the UI such as user-assistance microcopy, button/menu labels, or error messages. - ### Stage labels Stage labels specify which [stage](https://about.gitlab.com/handbook/product/product-categories/#hierarchy) the issue belongs to. @@ -226,6 +207,13 @@ Examples of feature labels are `~wiki`, `~ldap`, `~api`, `~issues`, `~"merge req Feature labels are all-lowercase. +### Facet labels + +To track additional information or context about created issues, developers may +add _facet labels_. Facet labels are also sometimes used for issue prioritization +or for measurements (such as time to close). An example of a facet label is the +~customer label, which indicates customer interest. + ### Department labels The current department labels are: diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 31f59ad875c..d5ffff7bfc8 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -123,24 +123,37 @@ document from the Kubernetes team also has some great points regarding this. ### Commit messages guidelines -When writing commit messages, please follow the guidelines below: +Commit messages should follow the guidelines below, for reasons explained by Chris Beams in [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/): -- The commit subject must contain at least 3 words. -- The commit subject must not be longer than 72 characters. +- The commit subject and body must be separated by a blank line. - The commit subject must start with a capital letter. +- The commit subject must not be longer than 72 characters. - The commit subject must not end with a period. -- The commit subject and body must be separated by a blank line. - The commit body must not contain more than 72 characters per line. - Commits that change 30 or more lines across at least 3 files must describe these changes in the commit body. - The commit subject or body must not contain Emojis. - Use issues and merge requests' full URLs instead of short references, as they are displayed as plain text outside of GitLab. -- The merge request must not contain more than 10 commit messages. +- The merge request should not contain more than 10 commit messages. +- The commit subject should contain at least 3 words. + +**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) + 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 + `[API] Improve the labels endpoint` are valid commit messages. + +#### Why these standards matter + +1. Consistent commit messages that follow these guidelines make the history more readable. +1. Concise standard commit messages helps to identify breaking changes for a deployment or ~"master:broken" quicker when + reviewing commits between two points in time. -If the guidelines are not met, the MR will not pass the -[Danger checks](https://gitlab.com/gitlab-org/gitlab/blob/master/danger/commit_messages/Dangerfile). -For more information see [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/). +#### Commit message template Example commit message template that can be used on your machine that embodies the above (guide for [how to apply template](https://codeinthehole.com/tips/a-useful-template-for-commit-messages/)): diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index 773c1a771cd..fd3fe239110 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -15,25 +15,49 @@ settings automatically by default. If your editor/IDE does not automatically sup we suggest investigating to see if a plugin exists. For instance here is the [plugin for vim](https://github.com/editorconfig/editorconfig-vim). -## Pre-commit static analysis +## Pre-push static analysis -You should install [`overcommit`](https://github.com/sds/overcommit) to automatically check for -static analysis offenses before committing locally. +We strongly recommend installing [Lefthook](https://github.com/Arkweid/lefthook) to automatically check +for static analysis offenses before pushing your changes. -After installing `overcommit`, run the following in your GitLab source directory: +To install `lefthook`, run the following in your GitLab source directory: ```shell -make -C tooling/overcommit +# 1. Make sure to uninstall Overcommit first +overcommit --uninstall + +# If using rbenv, at this point you may need to do: rbenv rehash + +# 2. Install lefthook... + +## With Homebrew (macOS) +brew install Arkweid/lefthook/lefthook + +## Or with Go +go get github.com/Arkweid/lefthook + +## Or with Rubygems +gem install lefthook + +# 3. Install the Git hooks +lefthook install -f ``` -Then before a commit is created, `overcommit` automatically checks for RuboCop (and other checks) -offenses on every modified file. +Before you push your changes, Lefthook then automatically run Danger checks, and other checks +for changed files. This saves you time as you don't have to wait for the same errors to be detected +by CI/CD. + +Lefthook relies on a pre-push hook to prevent commits that violate its ruleset. +To override this behavior, pass the environment variable `LEFTHOOK=0`. That is, +`LEFTHOOK=0 git push`. -This saves you time as you don't have to wait for the same errors to be detected by CI/CD. +You can also: -`overcommit` relies on a pre-commit hook to prevent commits that violate its ruleset. To override -this behavior, pass the `OVERCOMMIT_DISABLE` environment variable. For example, -`OVERCOMMIT_DISABLE=1 git rebase master` to rebase while disabling the Git hook. +- Define [local configuration](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#local-config). +- Skip [checks per tag on the fly](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#skip-some-tags-on-the-fly). + For example, `LEFTHOOK_EXCLUDE=frontend git push origin`. +- Run [hooks manually](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#run-githook-group-directly). + For example, `lefthook run pre-push`. ## Ruby, Rails, RSpec @@ -100,7 +124,7 @@ We're following [Ciro Santilli's Markdown Style Guide](https://cirosantilli.com/ ## Documentation -See the dedicated [Documentation Style Guide](../documentation/styleguide.md). +See the dedicated [Documentation Style Guide](../documentation/styleguide/index.md). ## Python diff --git a/doc/development/creating_enums.md b/doc/development/creating_enums.md index af9bf919b2b..fbf35171ecb 100644 --- a/doc/development/creating_enums.md +++ b/doc/development/creating_enums.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Creating enums When creating a new enum, it should use the database type `SMALLINT`. diff --git a/doc/development/dangerbot.md b/doc/development/dangerbot.md index 6fda394c10d..4feec5c093a 100644 --- a/doc/development/dangerbot.md +++ b/doc/development/dangerbot.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Danger bot The GitLab CI/CD pipeline includes a `danger-review` job that uses [Danger](https://github.com/danger/danger) diff --git a/doc/development/database/constraint_naming_convention.md b/doc/development/database/constraint_naming_convention.md new file mode 100644 index 00000000000..63a2d607ac5 --- /dev/null +++ b/doc/development/database/constraint_naming_convention.md @@ -0,0 +1,26 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Constraints naming conventions + +The most common option is to let Rails pick the name for database constraints and indexes or let PostgreSQL use the defaults (when applicable). However, when needing to define custom names in Rails or working in Go applications where no ORM is used, it is important to follow strict naming conventions to improve consistency and discoverability. + +The table below describes the naming conventions for custom PostgreSQL constraints. +Please note that the intent is not to retroactively change names in existing databases but rather ensure consistency of future changes. + +| Type | Syntax | Notes | Examples | +|--------------------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| +| **Primary Key** | `pk_<table name>` | | `pk_projects` | +| **Foreign Key** | `fk_<table name>_<column name>[_and_<column name>]*_<foreign table name>` | | `fk_projects_group_id_groups` | +| **Index** | `index_<table name>_on_<column name>[_and_<column name>]*[_and_<column name in partial clause>]*` | | `index_repositories_on_group_id` | +| **Unique Constraint** | `unique_<table name>_<column name>[_and_<column name>]*` | | `unique_projects_group_id_and_name` | +| **Check Constraint** | `check_<table name>_<column name>[_and_<column name>]*[_<suffix>]?` | The optional suffix should denote the type of validation, such as `length` and `enum`. It can also be used to desambiguate multiple `CHECK` constraints on the same column. | `check_projects_name_length`<br />`check_projects_type_enum`<br />`check_projects_admin1_id_and_admin2_id_differ` | +| **Exclusion Constraint** | `excl_<table name>_<column name>[_and_<column name>]*_[_<suffix>]?` | The optional suffix should denote the type of exclusion being performed. | `excl_reservations_start_at_end_at_no_overlap` | + +## Observations + +- Prefixes are preferred over suffices because they make it easier to identify the type of a given constraint quickly, as well as group them alphabetically; +- The `_and_` that joins column names can be omitted to keep the identifiers under the 63 characters' length limit defined by PostgreSQL. Additionally, the notation may be abbreviated to the best of our ability if struggling to keep under this limit. diff --git a/doc/development/database/index.md b/doc/development/database/index.md index 4bcefefe7a7..19159c6c0ff 100644 --- a/doc/development/database/index.md +++ b/doc/development/database/index.md @@ -57,9 +57,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w - [Query Count Limits](../query_count_limits.md) - [Creating enums](../creating_enums.md) - [Client-side connection-pool](client_side_connection_pool.md) -- [Updating multiple values](./setting_multiple_values.md) +- [Updating multiple values](setting_multiple_values.md) +- [Constraints naming conventions](constraint_naming_convention.md) ## Case studies - [Database case study: Filtering by label](../filtering_by_label.md) - [Database case study: Namespaces storage statistics](../namespaces_storage_statistics.md) + +## Miscellaneous + +- [Maintenance operations](maintenance_operations.md) diff --git a/doc/development/database/maintenance_operations.md b/doc/development/database/maintenance_operations.md new file mode 100644 index 00000000000..c84ec31471e --- /dev/null +++ b/doc/development/database/maintenance_operations.md @@ -0,0 +1,46 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Maintenance operations + +This page details various database related operations that may relate to development. + +## Disabling an index + +There are certain situations in which you might want to disable an index before removing it: + +- The index is on a large table and rebuilding it in the case of a revert would take a long time. +- It is uncertain whether or not the index is being used in ways that are not fully visible. + +To disable an index before removing it: + +1. Open a [production infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/new) +and use the "Production Change" template. +1. Inform the database team in the issue `@gl-database` or in Slack `#database`. +1. Add a step to verify the index is used (this would likely be an `EXPLAIN` command known to use the index). +1. Add the step to disable the index: + + ```sql + UPDATE pg_index SET indisvalid = false WHERE indexrelid = 'index_issues_on_foo'::regclass; + ``` + +1. Add a step to verify the index is invalid (this would likely be the same as used to verify before disabling the index). +1. Verify the index is invalid on replicas: + + ```sql + SELECT indisvalid FROM pg_index WHERE indexrelid = 'index_issues_on_foo'::regclass; + ``` + +1. Add steps for rolling back the invalidation: + 1. Rollback the index invalidation + + ```sql + UPDATE pg_index SET indisvalid = true WHERE indexrelid = 'index_issues_on_foo'::regclass; + ``` + + 1. Verify the index is being used again. + +See this [example infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/2795) for reference. diff --git a/doc/development/database/setting_multiple_values.md b/doc/development/database/setting_multiple_values.md index 5569a0e10b7..c354247a9f8 100644 --- a/doc/development/database/setting_multiple_values.md +++ b/doc/development/database/setting_multiple_values.md @@ -1,9 +1,15 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Setting Multiple Values > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32921) in GitLab 13.5. -Frequently, we will want to update multiple objects with new values for one -or more columns. The obvious way to do this is using `Relation#update_all`: +There's often a need to update multiple objects with new values for one +or more columns. One method of doing this is using `Relation#update_all`: ```ruby user.issues.open.update_all(due_date: 7.days.from_now) # (1) @@ -28,11 +34,11 @@ update issues where id = obj_id ``` -The bad news: There is no way to express this in ActiveRecord or even dropping -down to ARel - the `UpdateManager` just does not support `update from`, so this +The bad news: there is no way to express this in ActiveRecord or even dropping +down to ARel. The `UpdateManager` does not support `update from`, so this is not expressible. -The good news: We supply an abstraction to help you generate these kinds of +The good news: we supply an abstraction to help you generate these kinds of updates, called `Gitlab::Database::BulkUpdate`. This constructs queries such as the above, and uses binding parameters to avoid SQL injection. @@ -44,7 +50,7 @@ To use this, we need: - a mapping from object/ID to the new values to set for that object - a way to determine the table for each object -So for example, we can express the query above as: +For example, we can express the query above as: ```ruby issue_a = Issue.find(..) @@ -87,7 +93,7 @@ objects = Foo.from_union([ ]) # At this point, all the objects are instances of Foo, even the ones from the # Bar table -mapping = objects.to_h { |obj| [obj, bazzes[obj.id] } +mapping = objects.to_h { |obj| [obj, bazzes[obj.id]] } # Issues at most 2 queries ::Gitlab::Database::BulkUpdate.execute(%i[baz], mapping) do |obj| @@ -100,4 +106,4 @@ end Note that this is a **very low level** tool, and operates on the raw column values. Enumerations and state fields must be translated into their underlying representations, for example, and nested associations are not supported. No -validations or hooks will be called. +validations or hooks are called. diff --git a/doc/development/database_review.md b/doc/development/database_review.md index 3f5f36b0b6e..d1ec32af464 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -27,7 +27,7 @@ A database review is required for: database review. - Changes in usage data metrics that use `count` and `distinct_count`. These metrics could have complex queries over large tables. - See the [Product Analytics Guide](product_analytics/usage_ping.md#implementing-usage-ping) + See the [Product Analytics Guide](https://about.gitlab.com/handbook/product/product-analytics-guide/) for implementation details. A database reviewer is expected to look out for obviously complex @@ -106,7 +106,8 @@ test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slac - Write the raw SQL in the MR description. Preferably formatted nicely with [pgFormatter](https://sqlformat.darold.net) or - [paste.depesz.com](https://paste.depesz.com). + [paste.depesz.com](https://paste.depesz.com) and using regular quotes + (e.g. `"projects"."id"`) and avoiding smart quotes (e.g. `“projects”.“id”`). - Include the output of `EXPLAIN (ANALYZE, BUFFERS)` of the relevant queries in the description. If the output is too long, wrap it in `<details>` blocks, paste it in a GitLab Snippet, or provide the @@ -201,8 +202,8 @@ estimated to keep migration timing to a minimum. NOTE: **Note:** Keep in mind that all runtimes should be measured against GitLab.com. -| Migration Type | Execution Time Recommended | Notes | +| Migration Type | Execution Time Recommended | Notes | |----|----|---| | Regular migrations on `db/migrate` | `3 minutes` | A valid exception are index creation as this can take a long time. | -| Post migrations on `db/post_migrate` | `10 minutes` | | -| Background migrations | --- | Since these are suitable for larger tables, it's not possible to set a precise timing guideline, however, any single query must stay below `1 second` execution time with cold caches. | +| Post migrations on `db/post_migrate` | `10 minutes` | | +| Background migrations | --- | Since these are suitable for larger tables, it's not possible to set a precise timing guideline, however, any single query must stay below `1 second` execution time with cold caches. | diff --git a/doc/development/deleting_migrations.md b/doc/development/deleting_migrations.md index b8f23019ac2..df36715fa6a 100644 --- a/doc/development/deleting_migrations.md +++ b/doc/development/deleting_migrations.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Delete existing migrations When removing existing migrations from the GitLab project, you have to take into account diff --git a/doc/development/deprecation_guidelines/index.md b/doc/development/deprecation_guidelines/index.md index 1ee22644bbc..5cc408bb57b 100644 --- a/doc/development/deprecation_guidelines/index.md +++ b/doc/development/deprecation_guidelines/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Deprecation guidelines This page includes information about how and when to remove or make breaking diff --git a/doc/development/diffs.md b/doc/development/diffs.md index eb070cbf4d7..ece7bb9e9ee 100644 --- a/doc/development/diffs.md +++ b/doc/development/diffs.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Working with diffs Currently we rely on different sources to present diffs, these include: @@ -93,7 +99,6 @@ Gitlab::Git::DiffCollection.collection_limits[:max_bytes] = Gitlab::Git::DiffCol No more files will be rendered at all if 5 megabytes have already been rendered. -NOTE: **Note:** All collection limit parameters are currently sent and applied on Gitaly. That is, once the limit is surpassed, Gitaly will only return the safe amount of data to be persisted on `merge_request_diff_files`. @@ -108,7 +113,6 @@ That is, it's equivalent to 10kb if the maximum allowed value is 100kb. The diff will still be persisted and expandable if the patch size doesn't surpass `ApplicationSettings#diff_max_patch_bytes`. -NOTE: **Note:** Although this nomenclature (Collapsing) is also used on Gitaly, this limit is only used on GitLab (hardcoded - not sent to Gitaly). Gitaly will only return `Diff.Collapsed` (RPC) when surpassing collection limits. @@ -123,7 +127,6 @@ Commit::DIFF_SAFE_LINES = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines File diff will be suppressed (technically different from collapsed, but behaves the same, and is expandable) if it has more than 5000 lines. -NOTE: **Note:** This limit is currently hardcoded and only applied on GitLab. ## Viewers @@ -132,3 +135,51 @@ Diff Viewers, which can be found on `models/diff_viewer/*` are classes used to m whether it's a binary, which partial should be used to render it or which File extensions this class accounts for. `DiffViewer::Base` validates _blobs_ (old and new versions) content, extension and file type in order to check if it can be rendered. + +## Merge request diffs against the `HEAD` of the target branch + +Historically, merge request diffs have been calculated by `git diff target...source` which compares the +`HEAD` of the source branch with the merge base (or a common ancestor) of the target branch and the source's. +This solution works well until the target branch starts containing some of the +changes introduced by the source branch: Consider the following case, in which the source branch +is `feature_a` and the target is `master`: + +1. Checkout a new branch `feature_a` from `master` and remove `file_a` and `file_b` in it. +1. Add a commit that removes `file_a` to `master`. + +The merge request diff still contains the `file_a` removal while the actual diff compared to +`master`'s `HEAD` has only the `file_b` removal. The diff with such redundant +changes is harder to review. + +In order to display an up-to-date diff, in GitLab 12.9 we +[introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27008) merge request +diffs compared against `HEAD` of the target branch: the +target branch is artificially merged into the source branch, then the resulting +merge ref is compared to the source branch in order to calculate an accurate +diff. + +Until we complete the epics ["use merge refs for diffs"](https://gitlab.com/groups/gitlab-org/-/epics/854) +and ["merge conflicts in diffs"](https://gitlab.com/groups/gitlab-org/-/epics/4893), +both options `master (base)` and `master (HEAD)` are available to be displayed in merge requests: + + + +The `master (HEAD)` option is meant to replace `master (base)` in the future. + +In order to support comments for both options, diff note positions are stored for +both `master (base)` and `master (HEAD)` versions ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198457) in 12.10). +The position for `master (base)` version is stored in `Note#position` and +`Note#original_position` columns, for `master (HEAD)` version `DiffNotePosition` +has been introduced. + +One of the key challenges to deal with when working on merge ref diffs are merge +conflicts. If the target and source branch contains a merge conflict, the branches +cannot be automatically merged. The [recording on +YouTube](https://www.youtube.com/watch?v=GFXIFA4ZuZw&feature=youtu.be&ab_channel=GitLabUnfiltered) +is a quick introduction to the problem and the motivation behind the [epic](https://gitlab.com/groups/gitlab-org/-/epics/854). + +In 13.5 a solution for both-modified merge +conflict has been +[introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484). However, +there are more classes of merge conflicts that are to be +[addressed](https://gitlab.com/groups/gitlab-org/-/epics/4893) in the future. diff --git a/doc/development/distributed_tracing.md b/doc/development/distributed_tracing.md index 952435150d6..6d277f9ae99 100644 --- a/doc/development/distributed_tracing.md +++ b/doc/development/distributed_tracing.md @@ -178,6 +178,7 @@ This configuration string uses the Jaeger driver `opentracing://jaeger` with the | `udp_endpoint` | `localhost:6831` | This is the default. Configures Jaeger to send trace information to the UDP listener on port `6831` using compact thrift protocol. Note that we've experienced some issues with the [Jaeger Client for Ruby](https://github.com/salemove/jaeger-client-ruby) when using this protocol. | | `sampler` | `probabalistic` | Configures Jaeger to use a probabilistic random sampler. The rate of samples is configured by the `sampler_param` value. | | `sampler_param` | `0.01` | Use a ratio of `0.01` to configure the `probabalistic` sampler to randomly sample _1%_ of traces. | +| `service_name` | `api` | Override the service name used by the Jaeger backend. This parameter will take precedence over the application-supplied value. | NOTE: **Note:** The same `GITLAB_TRACING` value should to be configured in the environment @@ -185,7 +186,7 @@ variables for all GitLab processes, including Workhorse, Gitaly, Rails, and Side ### 3. Start the GitLab application -Once the `GITLAB_TRACING` environment variable is exported to all GitLab services, start the +After the `GITLAB_TRACING` environment variable is exported to all GitLab services, start the application. When `GITLAB_TRACING` is configured properly, the application will log this on startup: diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 0f03ceeb4b5..5bc3e1d59e2 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -30,8 +30,7 @@ See how to document them below, according to the state of the flag: - [Features that can be enabled or disabled for a single project](#features-enabled-by-project). - [Features with the feature flag removed](#features-with-flag-removed). -NOTE: **Note:** -The [`**(CORE ONLY)**`](styleguide.md#product-badges) badge or equivalent for +The [`**(CORE ONLY)**`](styleguide/index.md#product-badges) badge or equivalent for the feature's tier should be added to the line and heading that refers to enabling/disabling feature flags as Admin access is required to do so, therefore, it indicates that it cannot be done by regular users of GitLab.com. diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md index 11e6b159359..d658794f7e0 100644 --- a/doc/development/documentation/graphql_styleguide.md +++ b/doc/development/documentation/graphql_styleguide.md @@ -67,7 +67,7 @@ Set up the section with the following: ``` - Include a screenshot of the result in the GraphiQL explorer. Follow the naming - convention described in the [Save the image](styleguide.md#save-the-image) section of the Documentation style guide. + convention described in the [Save the image](styleguide/index.md#save-the-image) section of the Documentation style guide. - Follow up with an example of what you can do with the output. Make sure the example is something that readers can do on their own deployments. - Include a link to the [GraphQL API resources](../../api/graphql/reference/index.md). diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index e51f966ee6e..69a8ff10878 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -11,7 +11,7 @@ GitLab's documentation is [intended as the single source of truth (SSOT)](https: In addition to this page, the following resources can help you craft and contribute to documentation: -- [Style Guide](styleguide.md) - What belongs in the docs, language guidelines, Markdown standards to follow, links, and more. +- [Style Guide](styleguide/index.md) - What belongs in the docs, language guidelines, Markdown standards to follow, links, and more. - [Structure and template](structure.md) - Learn the typical parts of a doc page and how to write each one. - [Documentation process](workflow.md). - [Markdown Guide](../../user/markdown.md) - A reference for all Markdown syntax supported by GitLab. @@ -64,11 +64,11 @@ However, anyone can contribute [documentation improvements](workflow.md) that ar [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.md). If a style standard is missing, you are welcome to suggest one via a merge request. +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 [Structure](styleguide.md#structure) section of the [Documentation Style Guide](styleguide.md). +See the [Structure](styleguide/index.md#structure) section of the [Documentation Style Guide](styleguide/index.md). ## Metadata @@ -229,7 +229,7 @@ Things to note: it in for `workflow/lfs/lfs_administration` and `lfs/lfs_administration` and will print the file and the line where this file is mentioned. You may ask why the two greps. Since [we use relative paths to link to - documentation](styleguide.md#links), sometimes it might be useful to search a path deeper. + documentation](styleguide/index.md#links), sometimes it might be useful to search a path deeper. - The `*.md` extension is not used when a document is linked to GitLab's built-in help page, which is why we omit it in `git grep`. - Use the checklist on the "Change documentation location" MR description template. @@ -472,269 +472,7 @@ The following GitLab features are used among others: ## Testing -We treat documentation as code, and so use tests in our CI pipeline to maintain the -standards and quality of the docs. The current tests, which run in CI jobs when a -merge request with new or changed docs is submitted, are: - -- [`docs lint`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L41): - Runs several tests on the content of the docs themselves: - - [`lint-doc.sh` script](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) - runs the following checks and linters: - - All cURL examples use the long flags (ex: `--header`, not `-H`). - - The `CHANGELOG.md` does not contain duplicate versions. - - No files in `doc/` are executable. - - No new `README.md` was added. - - [markdownlint](#markdownlint). - - [Vale](#vale). - - Nanoc tests: - - [`internal_links`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L58) - checks that all internal links (ex: `[link](../index.md)`) are valid. - - [`internal_anchors`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L60) - checks that all internal anchors (ex: `[link](../index.md#internal_anchor)`) - are valid. - - [`ui-docs-links lint`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L62) - checks that all links to docs from UI elements (`app/views` files, for example) - are linking to valid docs and anchors. - -### Run tests locally - -Apart from [previewing your changes locally](#previewing-the-changes-live), you can also run all lint checks -and Nanoc tests locally. - -#### Lint checks - -Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) -script and can be executed as follows: - -1. Navigate to the `gitlab` directory. -1. Run: - - ```shell - MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh - ``` - -Where `MD_DOC_PATH` points to the file or directory you would like to run lint checks for. -If you omit it completely, it will default to the `doc/` directory. -The output should be similar to: - -```plaintext -=> Linting documents at path /path/to/gitlab as <user>... -=> Checking for cURL short options... -=> Checking for CHANGELOG.md duplicate entries... -=> Checking /path/to/gitlab/doc for executable permissions... -=> Checking for new README.md files... -=> Linting markdown style... -=> Linting prose... -✔ 0 errors, 0 warnings and 0 suggestions in 1 file. -✔ Linting passed -``` - -Note that this requires you to either have the required lint tools installed on your machine, -or a working Docker installation, in which case an image with these tools pre-installed will be used. - -#### Nanoc tests - -To execute Nanoc tests locally: - -1. Navigate to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. -1. Run: - - ```shell - # Check for broken internal links - bundle exec nanoc check internal_links - - # Check for broken external links (might take a lot of time to complete). - # This test is set to be allowed to fail and is run only in the gitlab-docs project CI - bundle exec nanoc check internal_anchors - ``` - -#### `ui-docs-links` test - -The `ui-docs-links lint` job uses `haml-lint` to test that all links to docs from -UI elements (`app/views` files, for example) are linking to valid docs and anchors. - -To run the `ui-docs-links` test locally: - -1. Open the `gitlab` directory in a terminal window. -1. Run: - - ```shell - bundle exec haml-lint -i DocumentationLinks - ``` - -If you receive an error the first time you run this test, run `bundle install`, which -installs GitLab's dependencies, and try again. - -If you don't want to install all of GitLab's dependencies to test the links, you can: - -1. Open the `gitlab` directory in a terminal window. -1. Install `haml-lint`: - - ```shell - gem install haml_lint - ``` - -1. Run: - - ```shell - haml-lint -i DocumentationLinks - ``` - -If you manually install `haml-lint` with this process, it will not update automatically -and you should make sure your version matches the version used by GitLab. - -### Local linters - -To help adhere to the [documentation style guidelines](styleguide.md), and improve the content -added to documentation, [install documentation linters](#install-linters) and -[integrate them with your code editor](#configure-editors). - -At GitLab, we mostly use: - -- [markdownlint](#markdownlint) -- [Vale](#vale) - -#### markdownlint - -[markdownlint](https://github.com/DavidAnson/markdownlint) checks that Markdown syntax follows -[certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules), and is -used by the [`docs-lint` test](#testing). - -Our [Documentation Style Guide](styleguide.md#markdown) and -[Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) elaborate on which choices must -be made when selecting Markdown syntax for GitLab documentation. This tool helps catch deviations -from those guidelines. - -markdownlint configuration is found in the following projects: - -- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.markdownlint.json) -- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/.markdownlint.json) -- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.markdownlint.json) -- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.markdownlint.json) -- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/.markdownlint.json) - -This configuration is also used within build pipelines. - -You can use markdownlint: - -- [On the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--). -- [Within a code editor](#configure-editors). -- [In a `pre-commit` hook](#configure-pre-commit-hooks). - -#### Vale - -[Vale](https://errata-ai.gitbook.io/vale/) is a grammar, style, and word usage linter for the -English language. Vale's configuration is stored in the -[`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) file located in the root -directory of projects. - -Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/) that extend any of -several types of checks, which we store in the `.linting/vale/styles/gitlab` directory within the -documentation directory of projects. - -Vale configuration is found in the following projects: - -- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab) -- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/master/docs/.vale/gitlab) -- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/tree/master/doc/.vale/gitlab) -- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/master/doc/.vale/gitlab) -- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/master/doc/.vale/gitlab) - -This configuration is also used within build pipelines. - -You can use Vale: - -- [On the command line](https://errata-ai.gitbook.io/vale/getting-started/usage). -- [Within a code editor](#configure-editors). -- [In a `pre-commit` hook](#configure-pre-commit-hooks). Vale only reports errors in the - `pre-commit` hook (the same configuration as the CI/CD pipelines), and does not report suggestions - or warnings. - -#### Install linters - -At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in -build pipelines: - -1. Install `markdownlint-cli`, using either: - - - `npm`: - - ```shell - npm install -g markdownlint-cli - ``` - - - `yarn`: - - ```shell - yarn global add markdownlint-cli - ``` - - We recommend installing the version of `markdownlint-cli` currently used in the documentation - linting [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L420). - -1. Install [`vale`](https://github.com/errata-ai/vale/releases). For example, to install using - `brew` for macOS, run: - - ```shell - brew install vale - ``` - - We recommend installing the version of Vale currently used in the documentation linting - [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L419). - -In addition to using markdownlint and Vale at the command line, these tools can be -[integrated with your code editor](#configure-editors). - -#### Configure editors - -To configure markdownlint within your editor, install one of the following as appropriate: - -- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) -- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) -- [Atom](https://atom.io/packages/linter-node-markdownlint) -- [Vim](https://github.com/dense-analysis/ale) - -To configure Vale within your editor, install one of the following as appropriate: - -- The Sublime Text [`SublimeLinter-contrib-vale` plugin](https://packagecontrol.io/packages/SublimeLinter-contrib-vale). -- The Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). You don't need Vale Server to use the plugin. -- [Vim](https://github.com/dense-analysis/ale). - -We don't use [Vale Server](https://errata-ai.github.io/vale/#using-vale-with-a-text-editor-or-another-third-party-application). - -#### Configure pre-commit hooks - -Git [pre-commit hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) allow Git users to -run tests or other processes before committing to a branch, with the ability to not commit to the branch if -failures occur with these tests. - -[`overcommit`](https://github.com/sds/overcommit) is a Git hooks manager, making configuring, -installing, and removing Git hooks easy. - -Sample configuration for `overcommit` is available in the -[`.overcommit.yml.example`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.overcommit.yml.example) -file for the [`gitlab`](https://gitlab.com/gitlab-org/gitlab) project. - -To set up `overcommit` for documentation linting, see -[Pre-commit static analysis](../contributing/style_guides.md#pre-commit-static-analysis). - -#### Disable Vale tests - -You can disable a specific Vale linting rule or all Vale linting rules for any portion of a -document: - -- To disable a specific rule, add a `<!-- vale gitlab.rulename = NO -->` tag before the text, and a - `<!-- vale gitlab.rulename = YES -->` tag after the text, replacing `rulename` with the filename - of a test in the - [GitLab styles](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.linting/vale/styles/gitlab) - directory. -- To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text, and a - `<!-- vale on -->` tag after the text. - -Whenever possible, exclude only the problematic rule and line(s). - -For more information, see -[Vale's documentation](https://errata-ai.gitbook.io/vale/getting-started/markup#markup-based-configuration). +For more information on documentation testing, see [Documentation testing](testing.md) ## Danger Bot diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index b12578b5d98..13c6140114f 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -38,12 +38,16 @@ The following can be used as a template to get started: ````markdown ## Descriptive title +> Version history note. + One or two sentence description of what endpoint does. ```plaintext METHOD /endpoint ``` +Supported attributes: + | Attribute | Type | Required | Description | |:------------|:---------|:---------|:----------------------| | `attribute` | datatype | yes/no | Detailed description. | @@ -65,6 +69,9 @@ Example response: ``` ```` +Adjust the [version history note accordingly](styleguide/index.md#version-text-in-the-version-history) +to describe the GitLab release that introduced the API call. + ## Method description Use the following table headers to describe the methods. Attributes should @@ -105,8 +112,8 @@ you can use in the API documentation. CAUTION: **Caution:** Do not use information for real users, URLs, or tokens. For documentation, refer to our -relevant style guide sections on [Fake user information](styleguide.md#fake-user-information), -[Fake URLs](styleguide.md#fake-urls), and [Fake tokens](styleguide.md#fake-tokens). +relevant style guide sections on [Fake user information](styleguide/index.md#fake-user-information), +[Fake URLs](styleguide/index.md#fake-urls), and [Fake tokens](styleguide/index.md#fake-tokens). ### Simple cURL command @@ -136,14 +143,26 @@ curl --data "name=foo" --header "PRIVATE-TOKEN: <your_access_token>" "https://gi ### Post data using JSON content -NOTE: **Note:** -In this example we create a new group. Watch carefully the single and double -quotes. +This example creates a new group. Be aware of the use of single (`'`) and double +(`"`) quotes. ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' "https://gitlab.example.com/api/v4/groups" ``` +For readability, you can also set up the `--data` by using the following format: + +```shell +curl --request POST \ +--url "https://gitlab.example.com/api/v4/groups" \ +--header "content-type: application/json" \ +--header "PRIVATE-TOKEN: <your_access_token>" \ +--data '{ + "path": "my-group", + "name": "My group" +}' +``` + ### Post data using form-data Instead of using JSON or urlencode you can use multipart/form-data which diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index 00cdc69d422..f101a669968 100644 --- a/doc/development/documentation/site_architecture/deployment_process.md +++ b/doc/development/documentation/site_architecture/deployment_process.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Documentation deployment process The [`dockerfiles` directory](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/) diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index 9fce9b4e4b3..21b0c4b6b43 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers description: "Learn how GitLab docs' global navigation works and how to add new items." --- @@ -67,7 +70,6 @@ With these groups in mind, the following are general rules for where new items s - Other documentation belongs at the top-level, but care must be taken to not create an enormously long top-level navigation, which defeats the purpose of it. -NOTE: **Note:** Making all documentation and navigation items adhere to these principles is being progressively rolled out. @@ -114,7 +116,6 @@ for clarity. To see the improvements planned, check the [global nav epic](https://gitlab.com/groups/gitlab-com/-/epics/21). -NOTE: **Note:** **Do not** [add items](#adding-new-items) to the global nav without the consent of one of the technical writers. diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 5d3af6721d1..3772746e25b 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers description: "Learn how GitLab's documentation website is architectured." --- @@ -227,8 +230,9 @@ for its search function. This is how it works: there's a JavaScript snippet which initiates DocSearch by using an API key and an index name (`gitlab`) that are needed for Algolia to show the results. -NOTE: **For GitLab Team Members:** -If you’re a GitLab Team Member, find credentials for the Algolia dashboard +### Algolia notes for GitLab team members + +If you’re a GitLab team member, find credentials for the Algolia dashboard in the shared [GitLab 1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams). To receive weekly reports of the search usage, search the Google doc with title `Email, Slack, and GitLab Groups and Aliases`, search for `docsearch`, diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md index d04d34ff786..547adc89a08 100644 --- a/doc/development/documentation/site_architecture/release_process.md +++ b/doc/development/documentation/site_architecture/release_process.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab Docs monthly release process When a new GitLab version is released on the 22nd, we need to create the respective @@ -9,7 +15,6 @@ Since the charts use a different version number than all the other GitLab products, we need to add a [version mapping](https://docs.gitlab.com/charts/installation/version_mappings.html): -NOTE: **Note:** The charts stable branch is not created automatically like the other products. There's an [issue to track this](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/1442). It is usually created on the 21st or the 22nd. @@ -158,7 +163,7 @@ Releasing a new version is a long process that involves many moving parts. ### `test_internal_links_and_anchors` failing on dropdown merge requests -NOTE: **Note:** +DANGER: **Deprecated:** We now pin versions in the `.gitlab-ci.yml` of the respective branch, so the steps below are deprecated. diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index e454a401a9d..3cc7f49f05e 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -10,7 +10,7 @@ description: What to include in GitLab documentation pages. Use these standards to contribute content to the GitLab documentation. Before getting started, familiarize yourself with [GitLab's Documentation guidelines](index.md) -and the [Documentation Style Guide](styleguide.md). +and the [Documentation Style Guide](styleguide/index.md). ## Components of a documentation page @@ -39,7 +39,7 @@ pre-deployment and post-deployment tasks. ## Template for new docs -Follow the [folder structure and file name guidelines](styleguide.md#folder-structure-overview) +Follow the [folder structure and file name guidelines](styleguide/index.md#folder-structure-overview) and create a new topic by using this template: ```markdown @@ -160,9 +160,9 @@ commented out to help encourage others to add to it in the future. --> Notes: -- (1): Apply the [tier badges](styleguide.md#product-badges) accordingly. +- (1): Apply the [tier badges](styleguide/index.md#product-badges) accordingly. - (2): Apply the correct format for the - [GitLab version that introduces the feature](styleguide.md#gitlab-versions-and-tiers). + [GitLab version that introduces the feature](styleguide/index.md#gitlab-versions-and-tiers). ``` ## Help and feedback section @@ -230,7 +230,6 @@ Consider the following guidelines when offering examples: - Better and best cases can be considered part of the good case(s) code block. In the same code block, precede each with comments: `# Better` and `# Best`. -NOTE: **Note:** Although the bad-then-good approach is acceptable for the GitLab development guidelines, do not use it for user documentation. For user documentation, use *Do* and *Don't*. For examples, see the [Pajamas Design System](https://design.gitlab.com/content/punctuation/). diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 6075124ef40..a12c2740083 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -1,2063 +1,5 @@ --- -stage: none -group: Style Guide -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers -description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' +redirect_to: 'styleguide/index.md' --- -# Documentation Style Guide - -This document defines the standards for GitLab's documentation content and -files. - -For broader information about the documentation, see the [Documentation guidelines](index.md). - -For guidelines specific to text in the GitLab interface, see the Pajamas [Content](https://design.gitlab.com/content/error-messages) section. - -For information on how to validate styles locally or by using GitLab CI/CD, see [Testing](index.md#testing). - -Use this guide for standards on grammar, formatting, word usage, and more. - -You can also view a list of [recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix). - -If you can't find what you need: - -- View the GitLab Handbook for [writing style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) that apply to all GitLab content. -- Refer to one of the following: - - - [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/). - - [Google Developer Documentation Style Guide](https://developers.google.com/style). - -If you have questions about style, mention `@tw-style` in an issue or merge request, or, if you have access to the GitLab Slack workspace, use `#docs-process`. - -## Documentation is the single source of truth (SSOT) - -### Why a single source of truth - -The documentation of GitLab products and features is the SSOT for all -information related to implementation, usage, and troubleshooting. It evolves -continuously, in keeping 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. - -### All information - -Include problem-solving actions that may address rare cases or be considered -*risky*, so long as proper context is provided in the form of 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. - -We will add all troubleshooting information to the documentation, no matter how -unlikely a user is to encounter a situation. For the [Troubleshooting sections](#troubleshooting), -people in GitLab Support can merge additions themselves. - -### All media types - -Include any media types/sources if the content is relevant to readers. You can -freely include or link presentations, diagrams, videos, and so on; no matter who -it was originally composed for, if it is helpful to any of our audiences, we can -include it. - -- 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 it may be reused or - updated by anyone. -- 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. - -### No special types - -In the software industry, it is a best practice to organize documentation in -different types. For example, [Divio recommends](https://www.divio.com/blog/documentation/): - -- Tutorials -- How-to guides -- Explanation -- Reference (for example, a glossary) - -At GitLab, we have so many product changes in our monthly releases that we can't -afford to continuously update multiple types of information. If we have multiple -types, the information will become outdated. Therefore, we have a -[single template](structure.md) for documentation. - -We currently do not distinguish specific document types, although we are open to -reconsidering this policy after the documentation has reached a future stage of -maturity and quality. If you are reading this, then despite our continuous -improvement efforts, that point hasn't been reached. - -### Link instead of summarize - -There is a temptation to summarize the information on another page. This will -cause the information to live in two places. Instead, link to the single source -of truth and explain why it is important to consume the information. - -### Organize by topic, not by type - -Beyond top-level audience-type folders (for example, `administration`), we -organize content by topic, not by type, so it can be located as easily as -possible within the single-source-of-truth (SSOT) section for the subject -matter. - -For example, do not create groupings of similar media types. For example: - -- Glossaries. -- FAQs. -- Sets of all articles or videos. - -Such grouping of content by type makes it difficult to browse for the information -you need and difficult to maintain up-to-date content. Instead, organize content -by its subject (for example, everything related to CI goes together) and -cross-link between any related content. - -### Docs-first methodology - -We employ a *documentation-first methodology* to help ensure the documentation -remains a complete and trusted resource, and to make communicating about the use -of GitLab more efficient. - -- 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’s 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 in order 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. Note -that among any other documentation changes, you can either: - -- Add a [Troubleshooting section](#troubleshooting) to a doc if none exists. -- Un-comment and use the placeholder Troubleshooting section included as part of - our [documentation template](structure.md#template-for-new-docs), if present. - -The more we reflexively add useful information to the documentation, the more -(and more successfully) the documentation will be used to efficiently accomplish -tasks and solve problems. - -If you have questions when considering, authoring, or editing documentation, ask -the Technical Writing team on Slack in `#docs` or in GitLab by mentioning the -writer for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/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. Please review the -[Documentation guidelines](index.md) before you begin your first documentation MR. - -Having a knowledge base in any form that is separate from the documentation would -be against the documentation-first methodology because the content would overlap with -the documentation. - -## Markdown - -All GitLab documentation is written using [Markdown](https://en.wikipedia.org/wiki/Markdown). - -The [documentation website](https://docs.gitlab.com) uses GitLab Kramdown as its -Markdown rendering engine. For a complete Kramdown reference, see the -[GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/markdown-guide/). - -The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) Ruby gem -will support all [GFM markup](../../user/markdown.md) in the future. That is, -all markup supported for display in the GitLab application itself. For now, use -regular Markdown markup, following the rules in the linked style guide. - -Note that Kramdown-specific markup (for example, `{:.class}`) will not render -properly on GitLab instances under [`/help`](index.md#gitlab-help). - -### HTML in Markdown - -Hard-coded HTML is valid, although it's discouraged from being used while we -have `/help`. HTML is permitted as long as: - -- There's no equivalent markup in Markdown. -- Advanced tables are necessary. -- Special styling is required. -- Reviewed and approved by a technical writer. - -### Markdown Rules - -GitLab ensures that the Markdown used across all documentation is consistent, as -well as easy to review and maintain, by [testing documentation changes](index.md#testing) -with [markdownlint](index.md#markdownlint). This lint test fails when any -document has an issue with Markdown formatting that may cause the page to render -incorrectly within GitLab. It will also fail when a document is using -non-standard Markdown (which may render correctly, but is not the current -standard for GitLab documentation). - -#### Markdown rule `MD044/proper-names` (capitalization) - -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.json` -file in each project, to verify proper use of capitalization and backticks. -Words in backticks will be ignored by markdownlint. - -In general, product names should follow the exact capitalization of the official -names of the products, protocols, and so on. See [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json) -for the words tested for proper capitalization in GitLab documentation. - -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.yml`..." - - `needs` is a parameter, and `.gitlab.yml` is a file, so both need backticks. - Additionally, `.gitlab.yml` will fail markdownlint without backticks as 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. - -## Structure - -Because we want documentation to be a SSOT, we should [organize by topic, not by -type](#organize-by-topic-not-by-type). - -### Folder structure overview - -The documentation is separated by top-level audience folders [`user`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/user), -[`administration`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/administration), -and [`development`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/development) -(contributing) folders. - -Beyond that, we primarily follow the structure of the GitLab user interface or -API. - -Our goal is to have a clear hierarchical structure with meaningful URLs like -`docs.gitlab.com/user/project/merge_requests/`. With this pattern, you can -immediately tell that you are navigating to user-related documentation about -Project features; specifically about Merge Requests. Our site's paths match -those of our repository, so the clear structure also makes documentation easier to update. - -The table below shows what kind of documentation goes where. - -| Directory | What belongs here | -|:----------------------|:----------------------------------------------------------------------------------------------------------------------------------------| -| `doc/user/` | User related documentation. Anything that can be done within the GitLab user interface goes here, including usage of the `/admin` interface. | -| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface exist under `doc/user/admin_area/`. | -| `doc/api/` | API related documentation. | -| `doc/development/` | Documentation related to the development of GitLab, whether contributing code or documentation. Related process and style guides should go here. | -| `doc/legal/` | Legal documents about contributing to GitLab. | -| `doc/install/` | Contains instructions for installing GitLab. | -| `doc/update/` | Contains instructions for updating GitLab. | -| `doc/topics/` | Indexes per topic (`doc/topics/topic_name/index.md`): all resources for that topic. | - -### Work with directories and files - -1. When you create a new directory, always start with an `index.md` file. - Do not use another file name and *do not* create `README.md` files. -1. *Do not* use special characters and spaces, or capital letters in file - names, directory names, branch names, and anything that generates a path. -1. When creating or renaming a file or directory and it has more than one word - in its name, use underscores (`_`) instead of spaces or dashes. For example, - proper naming would be `import_project/import_from_github.md`. This applies - to both image files and Markdown files. -1. For image files, do not exceed 100KB. -1. Do not upload video files to the product repositories. - [Link or embed videos](#videos) instead. -1. There are four main directories: `user`, `administration`, `api`, and - `development`. -1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`, - `profile/`, `dashboard/` and `admin_area/`. - 1. `doc/user/project/` should contain all project related documentation. - 1. `doc/user/group/` should contain all group related documentation. - 1. `doc/user/profile/` should contain all profile related documentation. - Every page you would navigate under `/profile` should have its own document, - for example, `account.md`, `applications.md`, or `emails.md`. - 1. `doc/user/dashboard/` should contain all dashboard related documentation. - 1. `doc/user/admin_area/` should contain all admin related documentation - describing what can be achieved by accessing GitLab's admin interface - (_not to be confused with `doc/administration` where server access is - required_). - 1. Every category under `/admin/application_settings/` should have its - own document located at `doc/user/admin_area/settings/`. For example, - the **Visibility and Access Controls** category should have a document - located at `doc/user/admin_area/settings/visibility_and_access_controls.md`. -1. The `doc/topics/` directory holds topic-related technical content. Create - `doc/topics/topic_name/subtopic_name/index.md` when subtopics become necessary. - General user- and admin- related documentation, should be placed accordingly. -1. The `/university/` directory is *deprecated* and the majority of its documentation - has been moved. - -If you are unsure where to place a document or a content addition, this should -not stop you from authoring and contributing. You can use your best judgment and -then ask the reviewer of your MR to confirm your decision, and/or ask a -technical writer at any stage in the process. The technical writing team will -review all documentation changes, regardless, and can move content if there is a -better place for it. - -### Avoid duplication - -Do not include the same information in multiple places. -[Link to a single source of truth instead.](#link-instead-of-summarize) - -### References across documents - -- Give each folder an `index.md` page that introduces the topic, introduces the - pages within, and links to the pages within (including to the index pages of - any next-level subpaths). -- To ensure discoverability, ensure each new or renamed doc is linked from its - higher-level index page and other related pages. -- When making reference to other GitLab products and features, link to their - respective documentation, at least on first mention. -- When making reference to third-party products or technologies, link out to - their external sites, documentation, and resources. - -### Structure within documents - -- Include any and all applicable subsections as described on the - [structure and template](structure.md) page. -- Structure content in alphabetical order in tables, lists, and so on, unless - there's a logical reason not to (for example, when mirroring the user - interface or an otherwise ordered sequence). - -## Language - -GitLab documentation should be clear and easy to understand. - -- Be clear, concise, and stick to the goal of the documentation. -- Write in US English with US grammar. (Tested in [`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml).) -- Use [inclusive language](#inclusive-language). - -### Point of view - -In most cases, it’s appropriate to use the second-person (you, yours) point of -view, because it’s friendly and easy to understand. (Tested in -[`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).) - -<!-- How do we harmonize the second person in Pajamas with our first person plural in our doc guide? --> - -### Capitalization - -#### Headings - -Use sentence case. For example: - -- `# Use variables to configure pipelines` -- `## Use the To-Do List` - -#### UI text - -When referring to specific user interface text, like a button label or menu -item, use the same capitalization that is displayed in the user interface. -Standards for this content are listed in the [Pajamas Design System Content section](https://design.gitlab.com/content/punctuation/) -and typically match what is called for in this Documentation Style Guide. - -If you think there is a mistake in the way the user interface text is styled, -create an issue or an MR to propose a change to the user interface text. - -#### Feature names - -- *Feature names are typically lowercase*, like those describing actions and - types of objects in GitLab. For example: - - epics - - issues - - issue weights - - merge requests - - milestones - - reorder issues - - runner, runners, shared runners - - a to-do item, to dos -- *Some features are capitalized*, typically nouns naming GitLab-specific - capabilities or tools. For example: - - GitLab CI/CD - - Repository Mirroring - - Value Stream Analytics - - the To-Do List - - the Web IDE - - Geo - - GitLab Runner (see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529) for details) - -Document any exceptions in this style guide. If you're not sure, ask a GitLab -Technical Writer so that they can help decide and document the result. - -Do not match the capitalization of terms or phrases on the [Features page](https://about.gitlab.com/features/) -or [features.yml](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml) -by default. - -#### Other terms - -Capitalize names of: - -- GitLab [product tiers](https://about.gitlab.com/pricing/). For example, - GitLab Core and GitLab Ultimate. (Tested in [`BadgeCapitalization.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/BadgeCapitalization.yml).) -- Third-party organizations, software, and products. For example, Prometheus, - Kubernetes, Git, and The Linux Foundation. -- Methods or methodologies. For example, Continuous Integration, - Continuous Deployment, Scrum, and Agile. (Tested in [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json).) - -Follow the capitalization style listed at the [authoritative source](#links-to-external-documentation) -for the entity, which may use non-standard case styles. For example: GitLab and -npm. - -Use forms of *sign in*, instead of *log in* or *login*. For example: - -- Sign in to GitLab. -- Open the sign-in page. - -Exceptions to this rule include the concept of *single sign-on* and -references to user interface elements. For example: - -- To sign in to product X, enter your credentials, and then select **Log in**. - -### Inclusive language - -We strive to create documentation that is inclusive. This section includes -guidance and examples in the following categories: - -- [Gender-specific wording](#avoid-gender-specific-wording). - (Tested in [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml).) -- [Ableist language](#avoid-ableist-language). - (Tested in [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml).) -- [Cultural sensitivity](#culturally-sensitive-language). - (Tested in [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml).) - -We write our developer documentation with inclusivity and diversity in mind. This -page is not an exhaustive reference, but describes some general guidelines and -examples that illustrate some best practices to follow. - -#### Avoid gender-specific wording - -When possible, use gender-neutral pronouns. For example, you can use a singular -[they](https://developers.google.com/style/pronouns#gender-neutral-pronouns) as -a gender-neutral pronoun. - -Avoid the use of gender-specific pronouns, unless referring to a specific person. - -<!-- vale gitlab.InclusionGender = NO --> - -| Use | Avoid | -|-----------------------------------|---------------------------------| -| People, humanity | Mankind | -| GitLab Team Members | Manpower | -| You can install; They can install | He can install; She can install | - -<!-- vale gitlab.InclusionGender = YES --> - -If you need to set up [Fake user information](#fake-user-information), use -diverse or non-gendered names with common surnames. - -#### Avoid ableist language - -Avoid terms that are also used in negative stereotypes for different groups. - -<!-- vale gitlab.InclusionAbleism = NO --> - -| Use | Avoid | -|------------------------|----------------------| -| Check for completeness | Sanity check | -| Uncertain outliers | Crazy outliers | -| Slows the service | Cripples the service | -| Placeholder variable | Dummy variable | -| Active/Inactive | Enabled/Disabled | -| On/Off | Enabled/Disabled | - -<!-- vale gitlab.InclusionAbleism = YES --> - -Credit: [Avoid ableist language](https://developers.google.com/style/inclusive-documentation#ableist-language) -in the Google Developer Style Guide. - -#### Culturally sensitive language - -Avoid terms that reflect negative cultural stereotypes and history. In most -cases, you can replace terms such as `master` and `slave` with terms that are -more precise and functional, such as `primary` and `secondary`. - -<!-- vale gitlab.InclusionCultural = NO --> - -| Use | Avoid | -|----------------------|-----------------------| -| Primary / secondary | Master / slave | -| Allowlist / denylist | Blacklist / whitelist | - -<!-- vale gitlab.InclusionCultural = YES --> - -For more information see the following [Internet Draft specification](https://tools.ietf.org/html/draft-knodel-terminology-02). - -### Fake user information - -You may need to include user information in entries such as a REST call or user profile. -**Do not** use real user information or email addresses in GitLab documentation. For email -addresses and names, do use: - -- **Email addresses**: Use an email address ending in `example.com`. -- **Names**: Use strings like `example_username`. Alternatively, use diverse or - non-gendered names with common surnames, such as `Sidney Jones`, `Zhang Wei`, - or `Alex Garcia`. - -### Fake URLs - -When including sample URLs in the documentation, use: - -- `example.com` when the domain name is generic. -- `gitlab.example.com` when referring to self-managed instances of GitLab. - -### Fake tokens - -There may be times where a token is needed to demonstrate an API call using -cURL or a variable used in CI. It is strongly advised not to use real tokens in -documentation even if the probability of a token being exploited is low. - -You can use the following fake tokens as examples: - -| Token type | Token value | -|:----------------------|:-------------------------------------------------------------------| -| Private user token | `<your_access_token>` | -| Personal access token | `n671WNGecHugsdEDPsyo` | -| Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | -| Application secret | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | -| CI/CD variable | `Li8j-mLUVA3eZYjPfd_H` | -| Specific runner token | `yrnZW46BrtBFqM7xDzE7dddd` | -| Shared runner token | `6Vk7ZsosqQyfreAxXTZr` | -| Trigger token | `be20d8dcc028677c931e04f3871a9b` | -| Webhook secret token | `6XhDroRcYPM5by_h-HLY` | -| Health check token | `Tu7BgjR9qeZTEyRzGG2P` | -| Request profile token | `7VgpS4Ax5utVD2esNstz` | - -### Language to avoid - -When creating documentation, limit or avoid the use of the following verb -tenses, words, and phrases: - -- Avoid jargon when possible, and when not possible, define the term or - [link to a definition](#links-to-external-documentation). -- Avoid uncommon words when a more-common alternative is possible, ensuring that - content is accessible to more readers. -- Don't write in the first person singular. - (Tested in [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).) - - Instead of "I" or "me," use "we," "you," "us," or "one." - - When possible, stay user focused by writing in the second person ("you" or - the imperative). -- Don't overuse "that". In many cases, you can remove "that" from a sentence - and improve readability. -- Avoid use of the future tense: - - Instead of "after you execute this command, GitLab will display the - result", use "after you execute this command, GitLab displays the result". - - Only use the future tense to convey when the action or result will actually - occur at a future time. -- Don't use slashes to clump different words together or as a replacement for - the word "or": - - Instead of "and/or," consider using "or," or use another sensible - construction. - - Other examples include "clone/fetch," author/assignee," and - "namespace/repository name." Break apart any such instances in an - appropriate way. - - Exceptions to this rule include commonly accepted technical terms, such as - CI/CD and TCP/IP. -- <!-- vale gitlab.LatinTerms = NO --> - We discourage use of Latin abbreviations, such as "e.g.," "i.e.," or "etc.," - as even native users of English might misunderstand them. - (Tested in [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml).) - - Instead of "i.e.," use "that is." - - Instead of "e.g.," use "for example," "such as," "for instance," or "like." - - Instead of "etc.," either use "and so on" or consider editing it out, since - it can be vague. - <!-- vale gitlab.LatinTerms = YES --> -- Avoid using the word *currently* when talking about the product or its - features. The documentation describes the product as it is, and not as it - will be at some indeterminate point in the future. -- Avoid the using the word *scalability* with increasing GitLab's performance - for additional users. Using the words *scale* or *scaling* in other cases is - acceptable, but references to increasing GitLab's performance for additional - users should direct readers to the GitLab - [reference architectures](../../administration/reference_architectures/index.md) - page. -- Avoid all forms of the phrases *high availability* and *HA*, and instead - direct readers to the GitLab [reference architectures](../../administration/reference_architectures/index.md) - for information about configuring GitLab to have the performance needed for - additional users over time. -- Don't use profanity or obscenities. Doing so may negatively affect other - users and contributors, which is contrary to GitLab's value of - [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). -- Avoid the use of [racially-insensitive terminology or phrases](https://www.marketplace.org/2020/06/17/tech-companies-update-language-to-avoid-offensive-terms/). For example: - - Use *primary* and *secondary* for database and server relationships. - - Use *allowlist* and *denylist* to describe access control lists. -- Avoid the word *please*. For details, see [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). - -### Word usage clarifications - -- Don't use "may" and "might" interchangeably: - - Use "might" to indicate the probability of something occurring. "If you - skip this step, the import process might fail." - - Use "may" to indicate giving permission for someone to do something, or - consider using "can" instead. "You may select either option on this - screen." Or, "You can select either option on this screen." - -### Contractions - -Contractions are encouraged, and can create a friendly and informal tone, -especially in tutorials, instructional documentation, and -[user interfaces](https://design.gitlab.com/content/punctuation/#contractions). - -Some contractions, however, should be avoided: - -- Do not use contractions with a proper noun and a verb. For example: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | GitLab is creating X. | GitLab's creating X. | - -- Do not use contractions when you need to emphasize a negative. For example: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Do *not* install X with Y. | *Don't* install X with Y. | - -- Do not use contractions in reference documentation. For example: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Do *not* set a limit greater than 1000. | *Don't* set a limit greater than 1000. | - | For `parameter1`, the default is 10. | For `parameter1`, the default's 10. | - -- Avoid contractions in error messages. Examples: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Requests to localhost are not allowed. | Requests to localhost aren't allowed. | - | Specified URL cannot be used. | Specified URL can't be used. | - -## 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: - - ```markdown - ## Header - - Paragraph. - - - List item 1 - - List item 2 - ``` - -### Emphasis - -- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`). -- Use underscore (`_`) for text in italics (`_italic_`). -- Use greater than (`>`) for blockquotes. - -### Punctuation - -Review the general punctuation rules for the GitLab documentation in the -following table. Check specific punctuation rules for [lists](#lists) below. -Additional examples are available in the [Pajamas guide for punctuation](https://design.gitlab.com/content/punctuation/). - -| Rule | Example | -|------------------------------------------------------------------|--------------------------------------------------------| -| Always end full sentences with a period. | _For a complete overview, read through this document._ | -| Always add a space after a period when beginning a new sentence. | _For a complete overview, check this doc. For other references, check out this guide._ | -| Do not use double spaces. (Tested in [`SentenceSpacing.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SentenceSpacing.yml).) | --- | -| Do not use tabs for indentation. Use spaces instead. You can configure your code editor to output spaces instead of tabs when pressing the tab key. | --- | -| Use serial commas ("Oxford commas") before the final 'and/or' in a list. (Tested in [`OxfordComma.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml).) | _You can create new issues, merge requests, and milestones._ | -| Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | _You should try this - or not._ | -| Always use lowercase after a colon. | _Related Issues: a way to create a relationship between issues._ | - -### Placeholder text - -Often in examples, a writer will provide a command or configuration that -uses values specific to the reader. - -In these cases, use [`<` and `>`](https://en.wikipedia.org/wiki/Usage_message#Pattern) -to call out where a reader must replace text with their own value. - -For example: - -```shell -cp <your_source_directory> <your_destination_directory> -``` - -### Keyboard commands - -Use the HTML `<kbd>` tag when referring to keystroke presses. For example: - -```plaintext -To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. -``` - -When the docs are generated, the output is: - -To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. - -## Lists - -- Always start list items with a capital letter, unless they are parameters or - commands that are in backticks, or similar. -- Always leave a blank line before and after a list. -- Begin a line with spaces (not tabs) to denote a [nested sub-item](#nesting-inside-a-list-item). - -### Ordered vs. unordered lists - -Only use ordered lists when their items describe a sequence of steps to follow. - -Do: - -```markdown -These are the steps to do something: - -1. First, do the first step. -1. Then, do the next step. -1. Finally, do the last step. -``` - -Don't: - -```markdown -This is a list of available features: - -1. Feature 1 -1. Feature 2 -1. Feature 3 -``` - -### Markup - -- Use dashes (`-`) for unordered lists instead of asterisks (`*`). -- Prefix `1.` to every item in an ordered list. When rendered, the list items - will appear with sequential numbering automatically. - -### Punctuation - -- Do not add commas (`,`) or semicolons (`;`) to the end of list items. -- Only add periods to the end of a list item if the item consists of a complete - sentence. The [definition of full sentence](https://www2.le.ac.uk/offices/ld/all-resources/writing/grammar/grammar-guides/sentence) - is: _"a complete sentence always contains a verb, expresses a complete idea, and makes sense standing alone"_. -- Be consistent throughout the list: if the majority of the items do not end in - a period, do not end any of the items in a period, even if they consist of a - complete sentence. The opposite is also valid: if the majority of the items - end with a period, end all with a period. -- Separate list items from explanatory text with a colon (`:`). For example: - - ```markdown - The list is as follows: - - - First item: this explains the first item. - - Second item: this explains the second item. - ``` - -**Examples:** - -Do: - -- First list item -- Second list item -- Third list item - -Don't: - -- First list item -- Second list item -- Third list item. - -Do: - -- Let's say this is a complete sentence. -- Let's say this is also a complete sentence. -- Not a complete sentence. - -Don't (vary use of periods; majority rules): - -- Let's say this is a complete sentence. -- Let's say this is also a complete sentence. -- Not a complete sentence - -### Nesting inside a list item - -It's possible to nest items under a list item, so that they render with the same -indentation as the list item. This can be done with: - -- [Code blocks](#code-blocks) -- [Blockquotes](#blockquotes) -- [Alert boxes](#alert-boxes) -- [Images](#images) - -Items nested in lists should always align with the first character of the list -item. In unordered lists (using `-`), this means two spaces for each level of -indentation: - -````markdown -- Unordered list item 1 - - A line nested using 2 spaces to align with the `U` above. - -- Unordered list item 2 - - > A quote block that will nest - > inside list item 2. - -- Unordered list item 3 - - ```plaintext - a codeblock that will next inside list item 3 - ``` - -- Unordered list item 4 - -  -```` - -For ordered lists, use three spaces for each level of indentation: - -````markdown -1. Ordered list item 1 - - A line nested using 3 spaces to align with the `O` above. - -1. Ordered list item 2 - - > A quote block that will nest - > inside list item 2. - -1. Ordered list item 3 - - ```plaintext - a codeblock that will next inside list item 3 - ``` - -1. Ordered list item 4 - -  -```` - -You can nest full lists inside other lists using the same rules as above. If you -want to mix types, that is also possible, as long as you don't mix items at the -same level: - -```markdown -1. Ordered list item one. -1. Ordered list item two. - - Nested unordered list item one. - - Nested unordered list item two. -1. Ordered list item three. - -- Unordered list item one. -- Unordered list item two. - 1. Nested ordered list item one. - 1. Nested ordered list item two. -- Unordered list item three. -``` - -## Tables - -Tables should be used to describe complex information in a straightforward -manner. Note that in many cases, an unordered list is sufficient to describe a -list of items with a single, simple description per item. But, if you have data -that is best described by a matrix, tables are the best choice for use. - -### Creation guidelines - -Due to accessibility and scannability requirements, tables should not have any -empty cells. If there is no otherwise meaningful value for a cell, consider entering -*N/A* (for 'not applicable') or *none*. - -To help tables be easier to maintain, consider adding additional spaces to the -column widths to make them consistent. For example: - -```markdown -| App name | Description | Requirements | -|:---------|:---------------------|:---------------| -| App 1 | Description text 1. | Requirements 1 | -| App 2 | Description text 2. | None | -``` - -Consider installing a plugin or extension in your editor for formatting tables: - -- [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 - -### Feature tables - -When creating tables of lists of features (such as whether or not features are -available to certain roles on the [Permissions](../../user/permissions.md#project-members-permissions) -page), use the following phrases (based on the SVG icons): - -| Option | Markdown | Displayed result | -|--------|--------------------------|------------------------| -| No | `**{dotted-circle}** No` | **{dotted-circle}** No | -| Yes | `**{check-circle}** Yes` | **{check-circle}** Yes | - -## Quotes - -Valid for Markdown content only, not for front matter entries: - -- Standard quotes: double quotes (`"`). Example: "This is wrapped in double - quotes". -- Quote within a quote: double quotes (`"`) wrap single quotes (`'`). Example: - "I am 'quoting' something within a quote". - -For other punctuation rules, please refer to the -[GitLab UX guide](https://design.gitlab.com/content/punctuation/). - -## Headings - -- Add **only one H1** in each document, by adding `#` at the beginning of - it (when using Markdown). The `h1` will be the document `<title>`. -- Start with an `h2` (`##`), and respect the order `h2` > `h3` > `h4` > `h5` > `h6`. - Never skip the hierarchy level, such as `h2` > `h4` -- Avoid putting numbers in headings. Numbers shift, hence documentation anchor - links shift too, which eventually leads to dead links. If you think it is - compelling to add numbers in headings, make sure to at least discuss it with - someone in the Merge Request. -- [Avoid using symbols and special characters](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/84) - in headers. Whenever possible, they should be plain and short text. -- When possible, avoid including words that might change in the future. Changing - a heading changes its anchor URL, which affects other linked pages. -- When introducing a new document, be careful for the headings to be - grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/product/product-categories/) - for review. - This is to ensure that no document with wrong heading is going live without an - audit, thus preventing dead links and redirection issues when corrected. -- Leave exactly one blank line before and after a heading. -- Do not use links in headings. -- Add the corresponding [product badge](#product-badges) according to the tier the - feature belongs. -- Our documentation site search engine prioritizes words used in headings and - subheadings. Make you subheading titles clear, descriptive, and complete to help - users find the right example, as shown in the section on [heading titles](#heading-titles). -- See [Capitalization](#capitalization) for guidelines on capitalizing headings. - -### Heading titles - -Keep heading titles clear and direct. Make every word count. To accommodate -search engine optimization (SEO), use the imperative, where possible. - -| Do | Don't | -|:--------------------------------------|:------------------------------------------------------------| -| Configure GDK | Configuring GDK | -| GitLab Release and Maintenance Policy | This section covers GitLab's Release and Maintenance Policy | -| Backport to older releases | Backporting to older releases | -| GitLab Pages examples | Examples | - -For guidelines on capitalizing headings, see the section on [capitalization](#capitalization). - -NOTE: **Note:** -If you change an existing title, be careful. These changes might affect not -only [links](#anchor-links) within the page, but might also affect links to the -GitLab documentation from both the GitLab application and external sites. - -### Anchor links - -Headings generate anchor links automatically when rendered. `## This is an example` -generates the anchor `#this-is-an-example`. - -NOTE: **Note:** -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39717) in GitLab 13.4, [product badges](#product-badges) used in headings aren't included in the -generated anchor links. For example, when you link to -`## This is an example **(CORE)**`, use the anchor `#this-is-an-example`. - -Keep in mind that the GitLab user interface links to many documentation pages -and anchor links to take the user to the right spot. Therefore, when you change -a heading, search `doc/*`, `app/views/*`, and `ee/app/views/*` for the old -anchor to make sure you're not breaking an anchor linked from other -documentation nor from the GitLab user interface. If you find the old anchor, be -sure to replace it with the new one. - -Important: - -- Avoid crosslinking documentation to headings unless you need to link to a - specific section of the document. This will avoid breaking anchors in the - future in case the heading is changed. -- If possible, avoid changing headings since they're not only linked internally. - There are various links to GitLab documentation on the internet, such as - tutorials, presentations, StackOverflow posts, and other sources. -- Do not link to `h1` headings. - -Note that, with Kramdown, it is possible to add a custom ID to an HTML element -with Markdown markup, but they **do not** work in GitLab's `/help`. Therefore, -do not use this option until further notice. - -## Links - -Links are important in GitLab documentation. They allow you to [link instead of -summarizing](#link-instead-of-summarize) to help preserve a [single source of truth](#why-a-single-source-of-truth) -within GitLab documentation. - -We include guidance for links in the following categories: - -- How to set up [anchor links](#anchor-links) for headings. -- How to set up [criteria](#basic-link-criteria) for configuring a link. -- What to set up when [linking to a `help`](../documentation/index.md#linking-to-help) - page. -- How to set up [links to internal documentation](#links-to-internal-documentation) - for cross-references. -- How to set up [links to external documentation](#links-to-external-documentation) - for authoritative sources. -- When to use [links requiring permissions](#links-requiring-permissions). -- How to set up a [link to a video](#link-to-video). -- How to [include links with version text](#text-for-documentation-requiring-version-text). -- How to [link to specific lines of code](#link-to-specific-lines-of-code) - -### Basic link criteria - -- Use inline link Markdown markup `[Text](https://example.com)`. - It's easier to read, review, and maintain. *Do not* use `[Text][identifier]`. - -- Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/). - For example, instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`, - write `Read more about [GitLab Issue Boards](LINK)`. - -### Links to internal documentation - -NOTE: **Note:** -_Internal_ refers to documentation in the same project. When linking to -documentation in separate projects (for example, linking to Omnibus documentation -from GitLab documentation), you must use absolute URLs. - -Do not use absolute URLs like `https://docs.gitlab.com/ee/index.html` to -crosslink to other documentation within the same project. Use relative links to -the file, like `../index.md`. (These are converted to HTML when the site is -rendered.) - -Relative linking enables crosslinks to work: - -- in Review Apps, local previews, and `/help`. -- when working on the documentation locally, so you can verify that they work as - early as possible in the process. -- within the GitLab user interface when browsing doc files in their respective - repositories. For example, the links displayed at - `https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md`. - -To link to internal documentation: - -- Use relative links to Markdown files in the same repository. -- Do not use absolute URLs or URLs from `docs.gitlab.com`. -- Use `../` to navigate to higher-level directories. -- Do not link relative to root. For example, `/ee/user/gitlab_com/index.md`. - - Don't: - - - `https://docs.gitlab.com/ee/administration/geo/replication/troubleshooting.html` - - `/ee/administration/geo/replication/troubleshooting.md` - - Do: `../../geo/replication/troubleshooting.md` - -- Always add the file name `file.md` at the end of the link with the `.md` - extension, not `.html`. - - Don't: - - - `../../merge_requests/` - - `../../issues/tags.html` - - `../../issues/tags.html#stages` - - Do: - - - `../../merge_requests/index.md` - - `../../issues/tags.md` - - `../../issues/tags.md#stages` - -NOTE: **Note:** -Using the Markdown extension is necessary for the [`/help`](index.md#gitlab-help) -section of GitLab. - -### Links to external documentation - -When describing interactions with external software, it's often helpful to -include links to external documentation. When possible, make sure that you're -linking to an [**authoritative** source](#authoritative-sources). For example, -if you're describing a feature in Microsoft's Active Directory, include a link -to official Microsoft documentation. - -### Authoritative sources - -When citing external information, use sources that are written by the people who -created the item or product in question. These sources are the most likely to be -accurate and remain up to date. - -Examples of authoritative sources include: - -- Specifications, such as a [Request for Comments](https://www.ietf.org/standards/rfcs/) - document from the Internet Engineering Task Force. -- Official documentation for a product. For example, if you're setting up an - interface with the Google OAuth 2 authorization server, include a link to - Google's documentation. -- Official documentation for a project. For example, if you're citing NodeJS - functionality, refer directly to [NodeJS documentation](https://nodejs.org/en/docs/). -- Books from an authoritative publisher. - -Examples of sources to avoid include: - -- Personal blog posts. -- Wikipedia. -- Non-trustworthy articles. -- Discussions on forums such as Stack Overflow. -- Documentation from a company that describes another company's product. - -While many of these sources to avoid can help you learn skills and or features, -they can become obsolete quickly. Nobody is obliged to maintain any of these -sites. Therefore, we should avoid using them as reference literature. - -NOTE: **Note:** -Non-authoritative sources are acceptable only if there is no equivalent -authoritative source. Even then, focus on non-authoritative sources that are -extensively cited or peer-reviewed. - -### Links requiring permissions - -Don't link directly to: - -- [Confidential issues](../../user/project/issues/confidential_issues.md). -- Project features that require [special permissions](../../user/permissions.md) - to view. - -These will fail for: - -- Those without sufficient permissions. -- Automated link checkers. - -Instead: - -- To reduce confusion, mention in the text that the information is either: - - Contained in a confidential issue. - - Requires special permission to a project to view. -- Provide a link in back ticks (`` ` ``) so that those with access to the issue - can easily navigate to it. - -Example: - -```markdown -For more information, see the [confidential issue](../../user/project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/<issue_number>`. -``` - -### Link to specific lines of code - -When linking to specific lines within a file, link to a commit instead of to the -branch. Lines of code change through time, therefore, linking to a line by using -the commit link ensures the user lands on the line you're referring to. The -**Permalink** button, which is available when viewing a file within a project, -makes it easy to generate a link to the most recent commit of the given file. - -- *Do:* `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)` -- *Don't:* `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).` - -If that linked expression is no longer in that line of the file due to additional -commits, you can still search the file for that query. In this case, update the -document to ensure it links to the most recent version of the file. - -## Navigation - -When documenting navigation through the user interface: - -- Use the exact wording as shown in the UI, including any capital letters as-is. -- Use bold text for navigation items and the char "greater than" (`>`) as a - separator. For example: `Navigate to your project's **Settings > CI/CD**`. -- If there are any expandable menus, make sure to mention that the user needs to - expand the tab to find the settings you're referring to. For example: - `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`. - -### Navigational elements - -Use the following terms when referring to the main GitLab user interface -elements: - -- **Top menu**: This is the top menu that spans the width of the user interface. - It includes the GitLab logo, search field, counters, and the user's avatar. -- **Left sidebar**: This is the navigation sidebar on the left of the user - interface, specific to the project or group. -- **Right sidebar**: This is the navigation sidebar on the right of the user - interface, specific to the open issue, merge request, or epic. - -## Images - -Images, including screenshots, can help a reader better understand a concept. -However, they can be hard to maintain, and should be used sparingly. - -Before including an image in the documentation, ensure it provides value to the -reader. - -### Capture the image - -Use images to help the reader understand where they are in a process, or how -they need to interact with the application. - -When you take screenshots: - -- *Capture the most relevant area of the page.* Don't include unnecessary white - space or areas of the page that don't help illustrate the point. The left - sidebar of the GitLab user interface can change, so don't include the sidebar - if it's not necessary. -- *Keep it small.* If you don't need to show the full width of the screen, don't. - A value of 1000 pixels is a good maximum width for your screenshot image. -- *Be consistent.* Coordinate screenshots with the other screenshots already on - a documentation page. For example, if other screenshots include the left - sidebar, include the sidebar in all screenshots. - -### Save the image - -- Save the image with a lowercase file name that is descriptive of the feature - or concept in the image. If the image is of the GitLab interface, append the - GitLab version to the file name, based on the following format: - `image_name_vX_Y.png`. For example, for a screenshot taken from the pipelines - page of GitLab 11.1, a valid name is `pipelines_v11_1.png`. If you're adding an - illustration that doesn't include parts of the user interface, add the release - number corresponding to the release the image was added to; for an MR added to - 11.1's milestone, a valid name for an illustration is `devops_diagram_v11_1.png`. -- Place images in a separate directory named `img/` in the same directory where - the `.md` document that you're working on is located. -- Consider using PNG images instead of JPEG. -- [Compress all PNG images](#compress-images). -- Compress gifs with <https://ezgif.com/optimize> or similar tool. -- Images should be used (only when necessary) to _illustrate_ the description - of a process, not to _replace_ it. -- Max image size: 100KB (gifs included). -- See also how to link and embed [videos](#videos) to illustrate the - documentation. - -### Add the image link to content - -The Markdown code for including an image in a document is: -`` - -The image description is the alt text for the rendered image on the -documentation site. For accessibility and SEO, use [descriptions](https://webaim.org/techniques/alttext/) -that: - -- Are accurate, succinct, and unique. -- Don't use *image of …* or *graphic of…* to describe the image. - -### Remove image shadow - -All images displayed on the [GitLab documentation site](https://docs.gitlab.com) -have a box shadow by default. To remove the box shadow, use the image class -`.image-noshadow` applied directly to an HTML `img` tag: - -```html -<img src="path/to/image.jpg" alt="Alt text (required)" class="image-noshadow"> -``` - -### Compress images - -You should always compress any new images you add to the documentation. One -known tool is [`pngquant`](https://pngquant.org/), which is cross-platform and -open source. Install it by visiting the official website and following the -instructions for your OS. - -GitLab has a [Rake task](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/tasks/pngquant.rake) -that you can use to automate the process. In the root directory of your local -copy of `https://gitlab.com/gitlab-org/gitlab`, run in a terminal: - -- Before compressing, if you want, check that all documentation PNG images have - been compressed: - - ```shell - bundle exec rake pngquant:lint - ``` - -- Compress all documentation PNG images using `pngquant`: - - ```shell - bundle exec rake pngquant:compress - ``` - -The only caveat is that the task runs on all images under `doc/`, not only the -ones you might have included in a merge request. In that case, you can run the -compress task and only commit the images that are relevant to your merge -request. - -## Videos - -Adding GitLab's existing YouTube video tutorials to the documentation is highly -encouraged, unless the video is outdated. Videos should not replace -documentation, but complement or illustrate it. If content in a video is -fundamental to a feature and its key use cases, but this is not adequately -covered in the documentation, add this detail to the documentation text or -create an issue to review the video and do so. - -Do not upload videos to the product repositories. [Link](#link-to-video) or -[embed](#embed-videos) them instead. - -### Link to video - -To link out to a video, include a YouTube icon so that readers can scan the page -for videos before reading: - -```markdown -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Video Title](link-to-video). -``` - -You can link any up-to-date video that is useful to the GitLab user. - -### Embed videos - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/472) in GitLab 12.1. - -The [GitLab documentation site](https://docs.gitlab.com) supports embedded -videos. - -You can only embed videos from [GitLab's official YouTube account](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg). -For videos from other sources, [link](#link-to-video) them instead. - -In most cases, it is better to [link to video](#link-to-video) instead, because -an embed takes up a lot of space on the page and can be distracting to readers. - -To embed a video, follow the instructions below and make sure you have your MR -reviewed and approved by a technical writer. - -1. Copy the code below and paste it into your Markdown file. Leave a blank line - above and below it. Do *not* edit the code (don't remove or add any spaces). -1. In YouTube, visit the video URL you want to display. Copy the regular URL - from your browser (`https://www.youtube.com/watch?v=VIDEO-ID`) and replace - the video title and link in the line under `<div class="video-fallback">`. -1. In YouTube, select **Share**, and then select **Embed**. -1. Copy the `<iframe>` source (`src`) **URL only** - (`https://www.youtube.com/embed/VIDEO-ID`), - and paste it, replacing the content of the `src` field in the - `iframe` tag. - -```html -leave a blank line here -<div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe> -</figure> -leave a blank line here -``` - -This is how it renders on the GitLab documentation site: - -<div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=enMumwvLAug">What is GitLab</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe> -</figure> - -> Notes: -> -> - The `figure` tag is required for semantic SEO and the `video_container` -class is necessary to make sure the video is responsive and displays on -different mobile devices. -> - The `<div class="video-fallback">` is a fallback necessary for GitLab's -`/help`, as GitLab's Markdown processor does not support iframes. It's hidden on -the documentation site, but will be displayed on GitLab's `/help`. - -## Code blocks - -- Always wrap code added to a sentence in inline code blocks (`` ` ``). - For example, `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, or `only: [master]`. - File names, commands, entries, and anything that refers to code should be - added to code blocks. To make things easier for the user, always add a full - code block for things that can be useful to copy and paste, as they can easily - do it with the button on code blocks. -- HTTP methods (`HTTP POST`) and HTTP status codes, both full (`404 File Not Found`) - and abbreviated (`404`), should be wrapped in inline code blocks when used in sentences. - For example: Send a `DELETE` request to delete the runner. Send a `POST` request to create one. -- Add a blank line above and below code blocks. -- When providing a shell command and its output, prefix the shell command with `$` - and leave a blank line between the command and the output. -- When providing a command without output, don't prefix the shell command with `$`. -- If you need to include triple backticks inside a code block, use four backticks - for the codeblock fences instead of three. -- For regular fenced code blocks, always use a highlighting class corresponding to - the language for better readability. Examples: - - ````markdown - ```ruby - Ruby code - ``` - - ```javascript - JavaScript code - ``` - - ```markdown - [Markdown code example](example.md) - ``` - - ```plaintext - Code or text for which no specific highlighting class is available. - ``` - ```` - -Syntax highlighting is required for fenced code blocks added to the GitLab -documentation. Refer to the following table for the most common language classes, -or check the [complete list](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) -of available language classes: - -| Preferred language tags | Language aliases and notes | -|-------------------------|------------------------------------------------------------------------------| -| `asciidoc` | | -| `dockerfile` | Alias: `docker`. | -| `elixir` | | -| `erb` | | -| `golang` | Alias: `go`. | -| `graphql` | | -| `haml` | | -| `html` | | -| `ini` | For some simple config files that are not in TOML format. | -| `javascript` | Alias `js`. | -| `json` | | -| `markdown` | Alias: `md`. | -| `mermaid` | | -| `nginx` | | -| `perl` | | -| `php` | | -| `plaintext` | Examples with no defined language, such as output from shell commands or API calls. If a codeblock has no language, it defaults to `plaintext`. Alias: `text`. | -| `prometheus` | Prometheus configuration examples. | -| `python` | | -| `ruby` | Alias: `rb`. | -| `shell` | Aliases: `bash` or `sh`. | -| `sql` | | -| `toml` | Runner configuration examples, and other TOML-formatted configuration files. | -| `typescript` | Alias: `ts`. | -| `xml` | | -| `yaml` | Alias: `yml`. | - -For a complete reference on code blocks, see the [Kramdown guide](https://about.gitlab.com/handbook/markdown-guide/#code-blocks). - -## GitLab SVG icons - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/384) in GitLab 12.7. - -You can use icons from the [GitLab SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/) -directly in the documentation. - -This way, you can achieve a consistent look when writing about interacting with -GitLab user interface elements. - -Usage examples: - -- Icon with default size (16px): `**{icon-name}**` - - Example: `**{tanuki}**` renders as: **{tanuki}**. -- Icon with custom size: `**{icon-name, size}**` - - Available sizes (in px): 8, 10, 12, 14, 16, 18, 24, 32, 48, and 72 - - Example: `**{tanuki, 24}**` renders as: **{tanuki, 24}**. -- Icon with custom size and class: `**{icon-name, size, class-name}**`. - - You can access any class available to this element in GitLab documentation CSS. - - Example with `float-right`, a - [Bootstrap utility class](https://getbootstrap.com/docs/4.4/utilities/float/): - `**{tanuki, 32, float-right}**` renders as: **{tanuki, 32, float-right}** - -### When to use icons - -Icons should be used sparingly, and only in ways that aid and do not hinder the -readability of the text. - -For example, the following adds little to the accompanying text: - -```markdown -1. Go to **{home}** **Project overview > Details** -``` - -1. Go to **{home}** **Project overview > Details** - -However, the following might help the reader connect the text to the user -interface: - -```markdown -| Section | Description | -|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| -| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | -| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit logs. | -| **{messages}** Messages | Send and manage broadcast messages for your users. | -``` - -| Section | Description | -|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| -| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | -| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit logs. | -| **{messages}** Messages | Send and manage broadcast messages for your users. | - -Use an icon when you find yourself having to describe an interface element. For -example: - -- Do: Select the Admin Area icon ( **{admin}** ). -- Don't: Select the Admin Area icon (the wrench icon). - -## Alert boxes - -When you need to call special attention to particular sentences, use the -following markup to create highlighted alert boxes. - -Alert boxes work for one paragraph only. Multiple paragraphs, lists, and headers -won't render correctly. For multiple lines, use [blockquotes](#blockquotes) -instead. - -Alert boxes render only on the GitLab documentation site (<https://docs.gitlab.com>). -Within GitLab itself, they will appear as plain Markdown text (like the examples -above the rendered versions, below). - -These alert boxes are used in the GitLab documentation. These aren't strict -guidelines, but for consistency you should try to use these values: - -| Color | Markup | Default keyword | Alternative keywords | -|--------|------------|-----------------|----------------------------------------------------------------------| -| Blue | `NOTE:` | `**Note:**` | | -| Yellow | `CAUTION:` | `**Caution:**` | `**Warning:**`, `**Important:**` | -| Red | `DANGER:` | `**Danger:**` | `**Warning:**`, `**Important:**`, `**Deprecated:**`, `**Required:**` | -| Green | `TIP:` | `**Tip:**` | | - -### Note - -Notes indicate additional information that is of special use to the reader. -Notes are most effective when used _sparingly_. - -Try to avoid them. Too many notes can impact the scannability of a topic and -create an overly busy page. - -Instead of adding a note, try one of these alternatives: - -- Re-write the sentence as part of the most-relevant paragraph. -- Put the information into its own standalone paragraph. -- Put the content under a new subheading that introduces the topic, which makes - it more visible. - -If you must use a note, use the following formatting: - -```markdown -NOTE: **Note:** -This is something to note. -``` - -How it renders on the GitLab documentation site: - -NOTE: **Note:** -This is something to note. - -### Tip - -```markdown -TIP: **Tip:** -This is a tip. -``` - -How it renders on the GitLab documentation site: - -TIP: **Tip:** -This is a tip. - -### Caution - -```markdown -CAUTION: **Caution:** -This is something to be cautious about. -``` - -How it renders on the GitLab documentation site: - -CAUTION: **Caution:** -This is something to be cautious about. - -### Danger - -```markdown -DANGER: **Danger:** -This is a breaking change, a bug, or something very important to note. -``` - -How it renders on the GitLab documentation site: - -DANGER: **Danger:** -This is a breaking change, a bug, or something very important to note. - -## Blockquotes - -For highlighting a text within a blue blockquote, use this format: - -```markdown -> This is a blockquote. -``` - -which renders on the [GitLab documentation site](https://docs.gitlab.com) as: - -> This is a blockquote. - -If the text spans across multiple lines it's OK to split the line. - -For multiple paragraphs, use the symbol `>` before every line: - -```markdown -> This is the first paragraph. -> -> This is the second paragraph. -> -> - This is a list item -> - Second item in the list -``` - -Which renders to: - -> This is the first paragraph. -> -> This is the second paragraph. -> -> - This is a list item -> - Second item in the list - -## Terms - -To maintain consistency through GitLab documentation, the following guides -documentation authors on agreed styles and usage of terms. - -### Merge requests (MRs) - -Merge requests allow you to exchange changes you made to source code and -collaborate with other people on the same project. You'll see this term used in -the following ways: - -- Use lowercase *merge requests* regardless of whether referring to the feature - or individual merge requests. - -As noted in the GitLab [Writing Style Guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines), -if you use the **MR** acronym, expand it at least once per document page. -Typically, the first use would be phrased as _merge request (MR)_ with subsequent -instances being _MR_. - -Examples: - -- "We prefer GitLab merge requests". -- "Open a merge request to fix a broken link". -- "After you open a merge request (MR), submit your MR for review and approval". - -### Describe UI elements - -The following are styles to follow when describing user interface elements in an -application: - -- For elements with a visible label, use that label in bold with matching case. - For example, `the **Cancel** button`. -- For elements with a tooltip or hover label, use that label in bold with - matching case. For example, `the **Add status emoji** button`. - -### Verbs for UI elements - -The following are recommended verbs for specific uses with user interface -elements: - -| Recommended | Used for | Replaces | -|:--------------------|:--------------------------------------|:---------------------------| -| *select* | buttons, links, menu items, dropdowns | "click, "press," "hit" | -| *select* or *clear* | checkboxes | "enable", "click", "press" | -| *expand* | expandable sections | "open" | - -### Other Verbs - -| Recommended | Used for | Replaces | -|:------------|:--------------------------------|:----------------------| -| *go to* | making a browser go to location | "navigate to", "open" | - -## GitLab versions and tiers - -Tagged and released versions of GitLab documentation are available: - -- In the [documentation archives](https://docs.gitlab.com/archives/). -- At the `/help` URL for any GitLab installation. - -The version introducing a new feature is added to the top of the topic in the -documentation to provide a link back to how the feature was developed. - -TIP: **Tip:** -Whenever you have documentation related to the `gitlab.rb` file, you're working -with a self-managed installation. The section or page is therefore likely to -apply only to self-managed instances. If so, the relevant "`TIER` ONLY" -[Product badge](#product-badges) should be included at the highest applicable -heading level. - -### Text for documentation requiring version text - -When a feature is new or updated, you can add version information as a bulleted -item in the **Version history**, or as an inline reference with related text. - -#### Version text in the **Version History** - -If all content in a section is related, add version text in a bulleted list -following the heading for the section. To render correctly, it must be on its -own line and surrounded by blank lines. - -- For features that need to declare the GitLab version that the feature was - introduced. Text similar to the following should be added immediately below - the heading as a blockquote: - - `> Introduced in GitLab 11.3.`. - -- Whenever possible, version text should have a link to the _completed_ issue, - merge request, or epic that introduced the feature. An issue is preferred over - a merge request, and a merge request is preferred over an epic. For example: - - `> [Introduced](<link-to-issue>) in GitLab 11.3.`. - -- If the feature is only available in GitLab Enterprise Edition, mention - the [paid tier](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers) - the feature is available in: - - `> [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.`. - -- If listing information for multiple version as a feature evolves, add the - information to a block-quoted bullet list. For example: - - ```markdown - > - [Introduced](<link-to-issue>) in GitLab 11.3. - > - Enabled by default in GitLab 11.4. - ``` - -- If a feature is moved to another tier: - - ```markdown - > - [Introduced](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. - > - [Moved](<link-to-issue>) to [GitLab Starter](https://about.gitlab.com/pricing/) in 11.8. - > - [Moved](<link-to-issue>) to GitLab Core in 12.0. - ``` - -- If a feature is deprecated, include a link to a replacement (when available): - - ```markdown - > - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>). - ``` - - It's also acceptable to describe the replacement in surrounding text, if - available. - - If the deprecation is not obvious in existing text, you may want to include a - warning such as: - - ```markdown - DANGER: **Deprecated:** - This feature was [deprecated](link-to-issue) in GitLab 12.3 - and replaced by [Feature name](link-to-feature-documentation). - ``` - -#### Inline version text - -If you're adding content to an existing topic, you can add version information -inline with the existing text. - -In this case, add `([introduced/deprecated](<link-to-issue>) in GitLab X.X)`. -If applicable, include the paid tier: `([introduced/deprecated](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4)` - -Including the issue link is encouraged, but isn't a requirement. For example: - -```markdown -The voting strategy (introduced in GitLab 13.4) requires -the primary and secondary voters to agree. -``` - -### Versions in the past or future - -When describing functionality available in past or future versions, use: - -- *Earlier*, and not *older* or *before*. -- *Later*, and not *newer* or *after*. - -For example: - -- Available in GitLab 12.3 and earlier. -- Available in GitLab 12.4 and later. -- If using GitLab 11.4 or earlier, ... -- If using GitLab 10.6 or later, ... - -### Importance of referencing GitLab versions and tiers - -Mentioning GitLab versions and tiers is important to all users and contributors -to quickly have access to the issue or merge request that introduced the change -for reference. Also, they can easily understand what features they have in their -GitLab instance and version, given that the note has some key information. - -`[Introduced](link-to-issue) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7` -links to the issue that introduced the feature, says which GitLab tier it -belongs to, says the GitLab version that it became available in, and links to -the pricing page in case the user wants to upgrade to a paid tier to use that -feature. - -For example, if you're a regular user and you're looking at the documentation -for a feature you haven't used before, you can immediately see if that feature -is available to you or not. Alternatively, if you've been using a certain -feature for a long time and it changed in some way, it's important to be able to -determine when it changed and what's new in that feature. - -This is even more important as we don't have a perfect process for shipping -documentation. Unfortunately, we still see features without documentation, and -documentation without features. So, for now, we cannot rely 100% on the -documentation site versions. - -Over time, version text will reference a progressively older version of GitLab. -In cases where version text refers to versions of GitLab four or more major -versions back, you can consider removing the text if it's irrelevant or confusing. - -For example, if the current major version is 12.x, version text referencing -versions of GitLab 8.x and older are candidates for removal if necessary for -clearer or cleaner documentation. - -## Products and features - -Refer to the information in this section when describing products and features -within the GitLab product documentation. - -### Avoid line breaks in names - -When entering a product or feature name that includes a space (such as -GitLab Community Edition) or even other companies' products (such as -Amazon Web Services), be sure to not split the product or feature name across -lines with an inserted line break. Splitting product or feature names across -lines makes searching for these items more difficult, and can cause problems if -names change. - -For example, the following Markdown content is *not* formatted correctly: - -```markdown -When entering a product or feature name that includes a space (such as GitLab -Community Edition), don't split the product or feature name across lines. -``` - -Instead, it should appear similar to the following: - -```markdown -When entering a product or feature name that includes a space (such as -GitLab Community Edition), don't split the product or feature name across lines. -``` - -### Product badges - -When a feature is available in paid tiers, add the corresponding tier to the -header or other page element according to the feature's availability: - -| Tier in which feature is available | Tier markup | -|:-----------------------------------------------------------------------|:----------------------| -| GitLab Core and GitLab.com Free, and their higher tiers | `**(CORE)**` | -| GitLab Starter and GitLab.com Bronze, and their higher tiers | `**(STARTER)**` | -| GitLab Premium and GitLab.com Silver, and their higher tiers | `**(PREMIUM)**` | -| GitLab Ultimate and GitLab.com Gold | `**(ULTIMATE)**` | -| *Only* GitLab Core and higher tiers (no GitLab.com-based tiers) | `**(CORE ONLY)**` | -| *Only* GitLab Starter and higher tiers (no GitLab.com-based tiers) | `**(STARTER ONLY)**` | -| *Only* GitLab Premium and higher tiers (no GitLab.com-based tiers) | `**(PREMIUM ONLY)**` | -| *Only* GitLab Ultimate (no GitLab.com-based tiers) | `**(ULTIMATE ONLY)**` | -| *Only* GitLab.com Free and higher tiers (no self-managed instances) | `**(FREE ONLY)**` | -| *Only* GitLab.com Bronze and higher tiers (no self-managed instances) | `**(BRONZE ONLY)**` | -| *Only* GitLab.com Silver and higher tiers (no self-managed instances) | `**(SILVER ONLY)**` | -| *Only* GitLab.com Gold (no self-managed instances) | `**(GOLD ONLY)**` | - -For clarity, all page title headers (H1s) must be have a tier markup for the -lowest tier that has information on the documentation page. - -If sections of a page apply to higher tier levels, they can be separately -labeled with their own tier markup. - -#### Product badge display behavior - -When using the tier markup with headers, the documentation page will display the -full tier badge with the header line. - -You can also use the tier markup with paragraphs, list items, and table cells. -For these cases, the tier mention will be represented by an orange info icon -**{information}** that will display the tiers when visitors point to the icon. -For example: - -- `**(STARTER)**` displays as **(STARTER)** -- `**(STARTER ONLY)**` displays as **(STARTER ONLY)** -- `**(SILVER ONLY)**` displays as **(SILVER ONLY)** - -#### How it works - -Introduced by [!244](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/244), -the special markup `**(STARTER)**` will generate a `span` element to trigger the -badges and tooltips (`<span class="badge-trigger starter">`). When the keyword -*only* is added, the corresponding GitLab.com badge will not be displayed. - -## Specific sections - -Certain styles should be applied to specific sections. Styles for specific -sections are outlined below. - -### GitLab restart - -There are many cases that a restart/reconfigure of GitLab is required. To avoid -duplication, link to the special document that can be found in -[`doc/administration/restart_gitlab.md`](../../administration/restart_gitlab.md). -Usually the text will read like: - -```markdown -Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md) -for the changes to take effect. -``` - -If the document you are editing resides in a place other than the GitLab CE/EE -`doc/` directory, instead of the relative link, use the full path: -`https://docs.gitlab.com/ee/administration/restart_gitlab.html`. Replace -`reconfigure` with `restart` where appropriate. - -### Installation guide - -**Ruby:** -In [step 2 of the installation guide](../../install/installation.md#2-ruby), -we install Ruby from source. Whenever there is a new version that needs to -be updated, remember to change it throughout the codeblock and also replace -the sha256sum (it can be found in the [downloads page](https://www.ruby-lang.org/en/downloads/) -of the Ruby website). - -### Configuration documentation for source and Omnibus installations - -GitLab currently officially supports two installation methods: installations -from source and Omnibus packages installations. - -Whenever there is a setting that is configurable for both installation methods, -prefer to document it in the CE documentation to avoid duplication. - -Configuration settings include: - -1. Settings that touch configuration files in `config/`. -1. NGINX settings and settings in `lib/support/` in general. - -When there is a list of steps to perform, usually that entails editing the -configuration file and reconfiguring/restarting GitLab. In such case, follow -the style below as a guide: - -````markdown -**For Omnibus installations** - -1. Edit `/etc/gitlab/gitlab.rb`: - - ```ruby - external_url "https://gitlab.example.com" - ``` - -1. Save the file and [reconfigure](path/to/administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - GitLab for the changes to take effect. - ---- - -**For installations from source** - -1. Edit `config/gitlab.yml`: - - ```yaml - gitlab: - host: "gitlab.example.com" - ``` - -1. Save the file and [restart](path/to/administration/restart_gitlab.md#installations-from-source) - GitLab for the changes to take effect. -```` - -In this case: - -- Before each step list the installation method is declared in bold. -- Three dashes (`---`) are used to create a horizontal line and separate the two - methods. -- The code blocks are indented one or more spaces under the list item to render - correctly. -- Different highlighting languages are used for each config in the code block. -- The [GitLab Restart](#gitlab-restart) section is used to explain a required - restart or reconfigure of GitLab. - -### Troubleshooting - -For troubleshooting sections, you should provide as much context as possible so -users can identify the problem they are facing and resolve it on their own. You -can facilitate this by making sure the troubleshooting content addresses: - -1. The problem the user needs to solve. -1. How the user can confirm they have the problem. -1. Steps the user can take towards resolution of the problem. - -If the contents of each category can be summarized in one line and a list of -steps aren't required, consider setting up a [table](#tables) with headers of -*Problem* \| *Cause* \| *Solution* (or *Workaround* if the fix is temporary), or -*Error message* \| *Solution*. - -## 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). - -## GraphQL API - -GraphQL APIs are different from [RESTful APIs](restful_api_styleguide.md). Reference -information is generated in our [GraphQL reference](../../api/graphql/reference/index.md). - -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 -[GraphiQL explorer](../api_graphql_styleguide.md#graphiql). - -This section describes the steps required to add your GraphQL examples to -GitLab documentation. - -### Add a dedicated GraphQL page - -To create a dedicated GraphQL page, create a new `.md` file in the -`doc/api/graphql/` directory. Give that file a functional name, such as -`import_from_specific_location.md`. - -### Start the page with an explanation - -Include a page title that describes the GraphQL functionality in a few words, -such as: - -```markdown -# Search for [substitute kind of data] -``` - -Describe the search. One sentence may be all you need. More information may -help readers learn how to use the example for their GitLab deployments. - -### Include a procedure using the GraphiQL explorer - -The GraphiQL explorer can help readers test queries with working deployments. -Set up the section with the following: - -- Use the following title: - - ```markdown - ## Set up the GraphiQL explorer - ``` - -- Include a code block with the query that anyone can include in their - instance of the GraphiQL explorer: - - ````markdown - ```graphql - query { - <insert queries here> - } - ``` - ```` - -- Tell the user what to do: - - ```markdown - 1. Open the GraphiQL explorer tool in the following URL: `https://gitlab.com/-/graphql-explorer`. - 1. Paste the `query` listed above into the left window of your GraphiQL explorer tool. - 1. Select Play to get the result shown here: - ``` - -- Include a screenshot of the result in the GraphiQL explorer. Follow the naming - convention described in the [Save the image](#save-the-image) section. -- Follow up with an example of what you can do with the output. Make sure the - example is something that readers can do on their own deployments. -- Include a link to the [GraphQL API resources](../../api/graphql/reference/index.md). - -### Add the GraphQL example to the Table of Contents - -You'll need to open a second MR, against the [GitLab documentation repository](https://gitlab.com/gitlab-org/gitlab-docs/). - -We store our Table of Contents in the `default-nav.yaml` file, in the -`content/_data` subdirectory. You can find the GraphQL section under the -following line: - -```yaml -- category_title: GraphQL -``` - -Be aware that CI tests for that second MR will fail with a bad link until the -main MR that adds the new GraphQL page is merged. - -And that's all you need! +This document was moved to [another location](styleguide/index.md). diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md new file mode 100644 index 00000000000..41e38266a58 --- /dev/null +++ b/doc/development/documentation/styleguide/index.md @@ -0,0 +1,1999 @@ +--- +stage: none +group: Style Guide +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' +--- + +# Documentation Style Guide + +This document defines the standards for GitLab's documentation content and +files. + +For broader information about the documentation, see the [Documentation guidelines](index.md). + +For guidelines specific to text in the GitLab interface, see the Pajamas [Content](https://design.gitlab.com/content/error-messages/) section. + +For information on how to validate styles locally or by using GitLab CI/CD, see [Testing](../testing.md). + +Use this guide for standards on grammar, formatting, word usage, and more. + +You can also view a list of [recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix). + +If you can't find what you need: + +- View the GitLab Handbook for [writing style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) that apply to all GitLab content. +- Refer to one of the following: + + - [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/). + - [Google Developer Documentation Style Guide](https://developers.google.com/style). + +If you have questions about style, mention `@tw-style` in an issue or merge request, or, if you have access to the GitLab Slack workspace, use `#docs-process`. + +## Documentation is the single source of truth (SSOT) + +### Why a single source of truth + +The documentation of GitLab products and features is the SSOT for all +information related to implementation, usage, and troubleshooting. It evolves +continuously, in keeping 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. + +### All information + +Include problem-solving actions that may address rare cases or be considered +_risky_, so long as proper context is provided in the form of 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. + +We will add all troubleshooting information to the documentation, no matter how +unlikely a user is to encounter a situation. For the [Troubleshooting sections](#troubleshooting), +people in GitLab Support can merge additions themselves. + +### All media types + +Include any media types/sources if the content is relevant to readers. You can +freely include or link presentations, diagrams, videos, and so on; no matter who +it was originally composed for, if it is helpful to any of our audiences, we can +include it. + +- 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 it may be reused or + updated by anyone. +- 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. + +### No special types + +In the software industry, it is a best practice to organize documentation in +different types. For example, [Divio recommends](https://www.divio.com/blog/documentation/): + +- Tutorials +- How-to guides +- Explanation +- Reference (for example, a glossary) + +At GitLab, we have so many product changes in our monthly releases that we can't +afford to continuously update multiple types of information. If we have multiple +types, the information will become outdated. Therefore, we have a +[single template](../structure.md) for documentation. + +We currently do not distinguish specific document types, although we are open to +reconsidering this policy after the documentation has reached a future stage of +maturity and quality. If you are reading this, then despite our continuous +improvement efforts, that point hasn't been reached. + +### Link instead of summarize + +There is a temptation to summarize the information on another page. This will +cause the information to live in two places. Instead, link to the single source +of truth and explain why it is important to consume the information. + +### Organize by topic, not by type + +Beyond top-level audience-type folders (for example, `administration`), we +organize content by topic, not by type, so it can be located in the +single-source-of-truth (SSOT) section for the subject matter. + +For example, do not create groupings of similar media types. For example: + +- Glossaries. +- FAQs. +- Sets of all articles or videos. + +Such grouping of content by type makes it difficult to browse for the information +you need and difficult to maintain up-to-date content. Instead, organize content +by its subject (for example, everything related to CI goes together) and +cross-link between any related content. + +### Docs-first methodology + +We employ a _documentation-first methodology_ to help ensure the documentation +remains a complete and trusted resource, and to make communicating about the use +of GitLab more efficient. + +- 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’s 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. Note +that among any other documentation changes, you can either: + +- Add a [Troubleshooting section](#troubleshooting) to a doc if none exists. +- Un-comment and use the placeholder Troubleshooting section included as part of + our [documentation template](../structure.md#template-for-new-docs), if present. + +The more we reflexively add useful information to the documentation, the more +(and more successfully) the documentation will be used to efficiently accomplish +tasks and solve problems. + +If you have questions when considering, authoring, or editing documentation, ask +the Technical Writing team on Slack in `#docs` or in GitLab by mentioning the +writer for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/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. + +Having a knowledge base in any form that's separate from the documentation would +be against the documentation-first methodology, because the content would overlap with +the documentation. + +## Markdown + +All GitLab documentation is written using [Markdown](https://en.wikipedia.org/wiki/Markdown). + +The [documentation website](https://docs.gitlab.com) uses GitLab Kramdown as its +Markdown rendering engine. For a complete Kramdown reference, see the +[GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/markdown-guide/). + +The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) Ruby gem +will support all [GFM markup](../../../user/markdown.md) in the future, which is +all markup supported for display in the GitLab application itself. For now, use +regular Markdown markup, following the rules in the linked style guide. + +Note that Kramdown-specific markup (for example, `{:.class}`) doesn't render +properly on GitLab instances under [`/help`](../index.md#gitlab-help). + +### HTML in Markdown + +Hard-coded HTML is valid, although it's discouraged from being used while we +have `/help`. HTML is permitted if: + +- There's no equivalent markup in Markdown. +- Advanced tables are necessary. +- Special styling is required. +- Reviewed and approved by a technical writer. + +### Markdown Rules + +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 within GitLab. It will also fail when a document is using +non-standard Markdown (which may render correctly, but is not the current +standard for GitLab documentation). + +#### Markdown rule `MD044/proper-names` (capitalization) + +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.json` +file in each project, to verify proper use of capitalization and backticks. +Words in backticks will be ignored by markdownlint. + +In general, product names should follow the exact capitalization of the official +names of the products, protocols, and so on. See [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json) +for the words tested for proper capitalization in GitLab documentation. + +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.yml`..." + - `needs` is a parameter, and `.gitlab.yml` is a file, so both need backticks. + Additionally, `.gitlab.yml` will fail markdownlint without backticks as 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. + +## Structure + +Because we want documentation to be a SSOT, we should [organize by topic, not by +type](#organize-by-topic-not-by-type). + +### Folder structure overview + +The documentation is separated by top-level audience folders [`user`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/user), +[`administration`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/administration), +and [`development`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/development) +(contributing) folders. + +Beyond that, we primarily follow the structure of the GitLab user interface or +API. + +Our goal is to have a clear hierarchical structure with meaningful URLs like +`docs.gitlab.com/user/project/merge_requests/`. With this pattern, you can +immediately tell that you are navigating to user-related documentation about +Project features; specifically about Merge Requests. Our site's paths match +those of our repository, so the clear structure also makes documentation easier +to update. + +Put files for a specific product area into the related folder: + +| Directory | What belongs here | +|:----------------------|:----------------------------------------------------------------------------------------------------------------------------------------| +| `doc/user/` | User related documentation. Anything that can be done within the GitLab user interface goes here, including usage of the `/admin` interface. | +| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed by using GitLab's interface exist under `doc/user/admin_area/`. | +| `doc/api/` | API related documentation. | +| `doc/development/` | Documentation related to the development of GitLab, whether contributing code or documentation. Related process and style guides should go here. | +| `doc/legal/` | Legal documents about contributing to GitLab. | +| `doc/install/` | Contains instructions for installing GitLab. | +| `doc/update/` | Contains instructions for updating GitLab. | +| `doc/topics/` | Indexes per topic (`doc/topics/topic_name/index.md`): all resources for that topic. | + +### Work with directories and files + +Refer to the following items when working with directories and files: + +1. When you create a new directory, always start with an `index.md` file. + Don't use another file name and _do not_ create `README.md` files. +1. _Do not_ use special characters and spaces, or capital letters in file + names, directory names, branch names, and anything that generates a path. +1. When creating or renaming a file or directory and it has more than one word + in its name, use underscores (`_`) instead of spaces or dashes. For example, + proper naming would be `import_project/import_from_github.md`. This applies + to both image files and Markdown files. +1. For image files, do not exceed 100KB. +1. Do not upload video files to the product repositories. + [Link or embed videos](#videos) instead. +1. There are four main directories: `user`, `administration`, `api`, and + `development`. +1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`, + `profile/`, `dashboard/` and `admin_area/`. + - `doc/user/project/` should contain all project related documentation. + - `doc/user/group/` should contain all group related documentation. + - `doc/user/profile/` should contain all profile related documentation. + Every page you would navigate under `/profile` should have its own document, + for example, `account.md`, `applications.md`, or `emails.md`. + - `doc/user/dashboard/` should contain all dashboard related documentation. + - `doc/user/admin_area/` should contain all admin related documentation + describing what can be achieved by accessing GitLab's admin interface + (_not to be confused with `doc/administration` where server access is + required_). + - Every category under `/admin/application_settings/` should have its + own document located at `doc/user/admin_area/settings/`. For example, + the **Visibility and Access Controls** category should have a document + located at `doc/user/admin_area/settings/visibility_and_access_controls.md`. +1. The `doc/topics/` directory holds topic-related technical content. Create + `doc/topics/topic_name/subtopic_name/index.md` when subtopics become necessary. + General user- and admin- related documentation, should be placed accordingly. +1. The `/university/` directory is *deprecated* and the majority of its documentation + has been moved. + +If you're unsure where to place a document or a content addition, this shouldn't +stop you from authoring and contributing. Use your best judgment, and then ask +the reviewer of your MR to confirm your decision, or ask a technical writer at +any stage in the process. The technical writing team will review all +documentation changes, regardless, and can move content if there is a better +place for it. + +### Avoid duplication + +Do not include the same information in multiple places. +[Link to a single source of truth instead.](#link-instead-of-summarize) + +### References across documents + +- Give each folder an `index.md` page that introduces the topic, introduces the + pages within, and links to the pages within (including to the index pages of + any next-level subpaths). +- To ensure discoverability, ensure each new or renamed doc is linked from its + higher-level index page and other related pages. +- When making reference to other GitLab products and features, link to their + respective documentation, at least on first mention. +- When making reference to third-party products or technologies, link out to + their external sites, documentation, and resources. + +### Structure within documents + +- Include any and all applicable subsections as described on the + [structure and template](../structure.md) page. +- Structure content in alphabetical order in tables, lists, and so on, unless + there's a logical reason not to (for example, when mirroring the user + interface or an otherwise ordered sequence). + +## Language + +GitLab documentation should be clear and easy to understand. + +- Be clear, concise, and stick to the goal of the documentation. +- Write in US English with US grammar. (Tested in [`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml).) +- Use [inclusive language](#inclusive-language). + +### Point of view + +In most cases, it’s appropriate to use the second-person (you, yours) point of +view, because it’s friendly and easy to understand. (Tested in +[`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).) + +### Capitalization + +#### Headings + +Use sentence case. For example: + +- `# Use variables to configure pipelines` +- `## Use the To-Do List` + +#### UI text + +When referring to specific user interface text, like a button label or menu +item, use the same capitalization that's displayed in the user interface. +Standards for this content are listed in the [Pajamas Design System Content section](https://design.gitlab.com/content/punctuation/) +and typically match what's called for in this Documentation Style Guide. + +If you think there's a mistake in the way the user interface text is styled, +create an issue or an MR to propose a change to the user interface text. + +#### Feature names + +- *Feature names are typically lowercase*, like those describing actions and + types of objects in GitLab. For example: + - epics + - issues + - issue weights + - merge requests + - milestones + - reorder issues + - runner, runners, shared runners + - a to-do item (tested in [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) +- *Some features are capitalized*, typically nouns naming GitLab-specific + capabilities or tools. For example: + - GitLab CI/CD + - Repository Mirroring + - Value Stream Analytics + - the To-Do List + - the Web IDE + - Geo + - GitLab Runner (see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529) for details) + +Document any exceptions in this style guide. If you're not sure, ask a GitLab +Technical Writer so that they can help decide and document the result. + +Do not match the capitalization of terms or phrases on the [Features page](https://about.gitlab.com/features/) +or [features.yml](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml) +by default. + +#### Other terms + +Capitalize names of: + +- GitLab [product tiers](https://about.gitlab.com/pricing/). For example, + GitLab Core and GitLab Ultimate. (Tested in [`BadgeCapitalization.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/BadgeCapitalization.yml).) +- Third-party organizations, software, and products. For example, Prometheus, + Kubernetes, Git, and The Linux Foundation. +- Methods or methodologies. For example, Continuous Integration, + Continuous Deployment, Scrum, and Agile. (Tested in [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json).) + +Follow the capitalization style listed at the [authoritative source](#links-to-external-documentation) +for the entity, which may use non-standard case styles. For example: GitLab and +npm. + +Use forms of *sign in*, instead of *log in* or *login*. For example: + +- Sign in to GitLab. +- Open the sign-in page. + +Exceptions to this rule include the concept of *single sign-on* and +references to user interface elements. For example: + +- To sign in to product X, enter your credentials, and then select **Log in**. + +### Inclusive language + +We strive to create documentation that's inclusive. This section includes +guidance and examples for the following categories: + +- [Gender-specific wording](#avoid-gender-specific-wording). + (Tested in [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml).) +- [Ableist language](#avoid-ableist-language). + (Tested in [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml).) +- [Cultural sensitivity](#culturally-sensitive-language). + (Tested in [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml).) + +We write our developer documentation with inclusivity and diversity in mind. This +page is not an exhaustive reference, but describes some general guidelines and +examples that illustrate some best practices to follow. + +#### Avoid gender-specific wording + +When possible, use gender-neutral pronouns. For example, you can use a singular +[they](https://developers.google.com/style/pronouns#gender-neutral-pronouns) as +a gender-neutral pronoun. + +Avoid the use of gender-specific pronouns, unless referring to a specific person. + +<!-- vale gitlab.InclusionGender = NO --> + +| Use | Avoid | +|-----------------------------------|---------------------------------| +| People, humanity | Mankind | +| GitLab Team Members | Manpower | +| You can install; They can install | He can install; She can install | + +<!-- vale gitlab.InclusionGender = YES --> + +If you need to set up [Fake user information](#fake-user-information), use +diverse or non-gendered names with common surnames. + +#### Avoid ableist language + +Avoid terms that are also used in negative stereotypes for different groups. + +<!-- vale gitlab.InclusionAbleism = NO --> + +| Use | Avoid | +|------------------------|----------------------| +| Check for completeness | Sanity check | +| Uncertain outliers | Crazy outliers | +| Slows the service | Cripples the service | +| Placeholder variable | Dummy variable | +| Active/Inactive | Enabled/Disabled | +| On/Off | Enabled/Disabled | + +<!-- vale gitlab.InclusionAbleism = YES --> + +Credit: [Avoid ableist language](https://developers.google.com/style/inclusive-documentation#ableist-language) +in the Google Developer Style Guide. + +#### Culturally sensitive language + +Avoid terms that reflect negative cultural stereotypes and history. In most +cases, you can replace terms such as `master` and `slave` with terms that are +more precise and functional, such as `primary` and `secondary`. + +<!-- vale gitlab.InclusionCultural = NO --> + +| Use | Avoid | +|----------------------|-----------------------| +| Primary / secondary | Master / slave | +| Allowlist / denylist | Blacklist / whitelist | + +<!-- vale gitlab.InclusionCultural = YES --> + +For more information see the following [Internet Draft specification](https://tools.ietf.org/html/draft-knodel-terminology-02). + +### Fake user information + +You may need to include user information in entries such as a REST call or user profile. +_Do not_ use real user information or email addresses in GitLab documentation. For email +addresses and names, do use: + +- _Email addresses_: Use an email address ending in `example.com`. +- _Names_: Use strings like `example_username`. Alternatively, use diverse or + non-gendered names with common surnames, such as `Sidney Jones`, `Zhang Wei`, + or `Alex Garcia`. + +### Fake URLs + +When including sample URLs in the documentation, use: + +- `example.com` when the domain name is generic. +- `gitlab.example.com` when referring to self-managed instances of GitLab. + +### Fake tokens + +There may be times where a token is needed to demonstrate an API call using +cURL or a variable used in CI. It is strongly advised not to use real tokens in +documentation even if the probability of a token being exploited is low. + +You can use the following fake tokens as examples: + +| Token type | Token value | +|:----------------------|:-------------------------------------------------------------------| +| Private user token | `<your_access_token>` | +| Personal access token | `n671WNGecHugsdEDPsyo` | +| Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | +| Application secret | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | +| CI/CD variable | `Li8j-mLUVA3eZYjPfd_H` | +| Specific runner token | `yrnZW46BrtBFqM7xDzE7dddd` | +| Shared runner token | `6Vk7ZsosqQyfreAxXTZr` | +| Trigger token | `be20d8dcc028677c931e04f3871a9b` | +| Webhook secret token | `6XhDroRcYPM5by_h-HLY` | +| Health check token | `Tu7BgjR9qeZTEyRzGG2P` | +| Request profile token | `7VgpS4Ax5utVD2esNstz` | + +### Language to avoid + +When creating documentation, limit or avoid the use of the following verb +tenses, words, and phrases: + +- Avoid jargon when possible, and when not possible, define the term or + [link to a definition](#links-to-external-documentation). +- Avoid uncommon words when a more-common alternative is possible, ensuring that + content is accessible to more readers. +- Don't write in the first person singular. + (Tested in [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).) + - Instead of _I_ or _me_, use _we_, _you_, _us_, or _one_. + - When possible, stay user focused by writing in the second person (_you_ or + the imperative). +- Don't overuse "that". In many cases, you can remove "that" from a sentence + and improve readability. +- Avoid use of the future tense: + - Instead of "after you execute this command, GitLab will display the + result", use "after you execute this command, GitLab displays the result". + - Only use the future tense to convey when the action or result will actually + occur at a future time. +- Don't use slashes to clump different words together or as a replacement for + the word "or": + - Instead of "and/or," consider using "or," or use another sensible + construction. + - Other examples include "clone/fetch," author/assignee," and + "namespace/repository name." Break apart any such instances in an + appropriate way. + - Exceptions to this rule include commonly accepted technical terms, such as + CI/CD and TCP/IP. +<!-- vale gitlab.LatinTerms = NO --> +- We discourage the use of Latin abbreviations and terms, such as _e.g._, + _i.e._, _etc._, or _via_, as even native users of English can misunderstand + those terms. (Tested in [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml).) + - Instead of _i.e._, use _that is_. + - Instead of _via_, use _through_. + - Instead of _e.g._, use _for example_, _such as_, _for instance_, or _like_. + - Instead of _etc._, either use _and so on_ or consider editing it out, since + it can be vague. +<!-- vale gitlab.LatinTerms = YES --> +- Avoid using the word *currently* when talking about the product or its + features. The documentation describes the product as it is, and not as it + will be at some indeterminate point in the future. +- Avoid the using the word *scalability* with increasing GitLab's performance + for additional users. Using the words *scale* or *scaling* in other cases is + acceptable, but references to increasing GitLab's performance for additional + users should direct readers to the GitLab + [reference architectures](../../../administration/reference_architectures/index.md) + page. +- Avoid all forms of the phrases *high availability* and *HA*, and instead + direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) + for information about configuring GitLab to have the performance needed for + additional users over time. +- Don't use profanity or obscenities. Doing so may negatively affect other + users and contributors, which is contrary to GitLab's value of + [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). +- Avoid the use of [racially-insensitive terminology or phrases](https://www.marketplace.org/2020/06/17/tech-companies-update-language-to-avoid-offensive-terms/). For example: + - Use *primary* and *secondary* for database and server relationships. + - Use *allowlist* and *denylist* to describe access control lists. +- Avoid the word _please_. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). +- Avoid words like _easily_, _simply_, _handy_, and _useful._ If the user + doesn't find the process to be these things, we lose their trust. + +### Word usage clarifications + +- Don't use "may" and "might" interchangeably: + - Use "might" to indicate the probability of something occurring. "If you + skip this step, the import process might fail." + - Use "may" to indicate giving permission for someone to do something, or + consider using "can" instead. "You may select either option on this + screen." Or, "You can select either option on this screen." + +### Contractions + +Contractions are encouraged, and can create a friendly and informal tone, +especially in tutorials, instructional documentation, and +[user interfaces](https://design.gitlab.com/content/punctuation/#contractions). + +Some contractions, however, should be avoided: + +- Do not use contractions with a proper noun and a verb. For example: + + | Do | Don't | + |------------------------------------------|-----------------------------------------| + | GitLab is creating X. | GitLab's creating X. | + +- Do not use contractions when you need to emphasize a negative. For example: + + | Do | Don't | + |------------------------------------------|-----------------------------------------| + | Do *not* install X with Y. | *Don't* install X with Y. | + +- Do not use contractions in reference documentation. For example: + + | Do | Don't | + |------------------------------------------|-----------------------------------------| + | Do *not* set a limit greater than 1000. | *Don't* set a limit greater than 1000. | + | For `parameter1`, the default is 10. | For `parameter1`, the default's 10. | + +- Avoid contractions in error messages. Examples: + + | Do | Don't | + |------------------------------------------|-----------------------------------------| + | Requests to localhost are not allowed. | Requests to localhost aren't allowed. | + | Specified URL cannot be used. | Specified URL can't be used. | + +## 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: + + ```markdown + ## Header + + Paragraph. + + - List item 1 + - List item 2 + ``` + +### Emphasis + +- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`). +- Use underscore (`_`) for text in italics (`_italic_`). +- Use greater than (`>`) for blockquotes. + +### Punctuation + +Follow these guidelines for punctuation: + +<!-- vale gitlab.Repetition = NO --> + +| Rule | Example | +|------------------------------------------------------------------|--------------------------------------------------------| +| Always end full sentences with a period. | _For a complete overview, read through this document._ | +| Always add a space after a period when beginning a new sentence. | _For a complete overview, check this doc. For other references, check out this guide._ | +| Do not use double spaces. (Tested in [`SentenceSpacing.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SentenceSpacing.yml).) | --- | +| Do not use tabs for indentation. Use spaces instead. You can configure your code editor to output spaces instead of tabs when pressing the tab key. | --- | +| Use serial commas (_Oxford commas_) before the final _and_ or _or_ in a list of three or more items. (Tested in [`OxfordComma.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml).) | _You can create new issues, merge requests, and milestones._ | +| Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | _You should try this - or not._ | +| Always use lowercase after a colon. | _Related Issues: a way to create a relationship between issues._ | + +<!-- vale gitlab.Repetition = YES --> + +### Placeholder text + +Often in examples, a writer will provide a command or configuration that +uses values specific to the reader. + +In these cases, use [`<` and `>`](https://en.wikipedia.org/wiki/Usage_message#Pattern) +to call out where a reader must replace text with their own value. + +For example: + +```shell +cp <your_source_directory> <your_destination_directory> +``` + +### Keyboard commands + +Use the HTML `<kbd>` tag when referring to keystroke presses. For example: + +```plaintext +To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. +``` + +When the docs are generated, the output is: + +To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. + +## Lists + +- Always start list items with a capital letter, unless they're parameters or + commands that are in backticks, or similar. +- Always leave a blank line before and after a list. +- Begin a line with spaces (not tabs) to denote a [nested sub-item](#nesting-inside-a-list-item). + +### Ordered vs. unordered lists + +Only use ordered lists when their items describe a sequence of steps to follow. + +Do: + +```markdown +These are the steps to do something: + +1. First, do the first step. +1. Then, do the next step. +1. Finally, do the last step. +``` + +Don't: + +```markdown +This is a list of available features: + +1. Feature 1 +1. Feature 2 +1. Feature 3 +``` + +### Markup + +- Use dashes (`-`) for unordered lists instead of asterisks (`*`). +- Prefix `1.` to every item in an ordered list. When rendered, the list items + will appear with sequential numbering. + +### Punctuation + +- Don't add commas (`,`) or semicolons (`;`) to the ends of list items. +- Only add periods to the end of a list item if the item consists of a complete + sentence (with a subject and a verb). +- Be consistent throughout the list: if the majority of the items do not end in + a period, do not end any of the items in a period, even if they consist of a + complete sentence. The opposite is also valid: if the majority of the items + end with a period, end all with a period. +- Separate list items from explanatory text with a colon (`:`). For example: + + ```markdown + The list is as follows: + + - First item: this explains the first item. + - Second item: this explains the second item. + ``` + +**Examples:** + +Do: + +- First list item +- Second list item +- Third list item + +Don't: + +- First list item +- Second list item +- Third list item. + +Do: + +- Let's say this is a complete sentence. +- Let's say this is also a complete sentence. +- Not a complete sentence. + +Don't (vary use of periods; majority rules): + +- Let's say this is a complete sentence. +- Let's say this is also a complete sentence. +- Not a complete sentence + +### Nesting inside a list item + +It's possible to nest items under a list item, so that they render with the same +indentation as the list item. This can be done with: + +- [Code blocks](#code-blocks) +- [Blockquotes](#blockquotes) +- [Alert boxes](#alert-boxes) +- [Images](#images) + +Items nested in lists should always align with the first character of the list +item. In unordered lists (using `-`), this means two spaces for each level of +indentation: + +````markdown +- Unordered list item 1 + + A line nested using 2 spaces to align with the `U` above. + +- Unordered list item 2 + + > A quote block that will nest + > inside list item 2. + +- Unordered list item 3 + + ```plaintext + a codeblock that will next inside list item 3 + ``` + +- Unordered list item 4 + +  +```` + +For ordered lists, use three spaces for each level of indentation: + +````markdown +1. Ordered list item 1 + + A line nested using 3 spaces to align with the `O` above. + +1. Ordered list item 2 + + > A quote block that will nest + > inside list item 2. + +1. Ordered list item 3 + + ```plaintext + a codeblock that will next inside list item 3 + ``` + +1. Ordered list item 4 + +  +```` + +You can nest full lists inside other lists using the same rules as above. If you +want to mix types, that's also possible, if you don't mix items at the same +level: + +```markdown +1. Ordered list item one. +1. Ordered list item two. + - Nested unordered list item one. + - Nested unordered list item two. +1. Ordered list item three. + +- Unordered list item one. +- Unordered list item two. + 1. Nested ordered list item one. + 1. Nested ordered list item two. +- Unordered list item three. +``` + +## Tables + +Tables should be used to describe complex information in a straightforward +manner. Note that in many cases, an unordered list is sufficient to describe a +list of items with a single, simple description per item. But, if you have data +that's best described by a matrix, tables are the best choice. + +### Creation guidelines + +Due to accessibility and scannability requirements, tables should not have any +empty cells. If there is no otherwise meaningful value for a cell, consider entering +*N/A* (for 'not applicable') or *none*. + +To help tables be easier to maintain, consider adding additional spaces to the +column widths to make them consistent. For example: + +```markdown +| App name | Description | Requirements | +|:---------|:---------------------|:---------------| +| App 1 | Description text 1. | Requirements 1 | +| App 2 | Description text 2. | None | +``` + +Consider installing a plugin or extension in your editor for formatting tables: + +- [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 + +### Feature tables + +When creating tables of lists of features (such as whether or not features are +available to certain roles on the [Permissions](../../../user/permissions.md#project-members-permissions) +page), use the following phrases (based on the SVG icons): + +| Option | Markdown | Displayed result | +|--------|--------------------------|------------------------| +| No | `**{dotted-circle}** No` | **{dotted-circle}** No | +| Yes | `**{check-circle}** Yes` | **{check-circle}** Yes | + +## Quotes + +Valid for Markdown content only, not for front matter entries: + +- Standard quotes: double quotes (`"`). Example: "This is wrapped in double + quotes". +- Quote within a quote: double quotes (`"`) wrap single quotes (`'`). Example: + "I am 'quoting' something within a quote". + +For other punctuation rules, refer to the +[GitLab UX guide](https://design.gitlab.com/content/punctuation/). + +## Headings + +- Add _only one H1_ in each document, by adding `#` at the beginning of + it (when using Markdown). The `h1` will be the document `<title>`. +- Start with an `h2` (`##`), and respect the order `h2` > `h3` > `h4` > `h5` > `h6`. + Never skip the hierarchy level, such as `h2` > `h4` +- Avoid putting numbers in headings. Numbers shift, hence documentation anchor + links shift too, which eventually leads to dead links. If you think it is + compelling to add numbers in headings, make sure to at least discuss it with + someone in the Merge Request. +- [Avoid using symbols and special characters](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/84) + in headers. Whenever possible, they should be plain and short text. +- When possible, avoid including words that might change in the future. Changing + a heading changes its anchor URL, which affects other linked pages. +- When introducing a new document, be careful for the headings to be + grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/product/product-categories/) + for review. + This is to ensure that no document with wrong heading is going live without an + audit, thus preventing dead links and redirection issues when corrected. +- Leave exactly one blank line before and after a heading. +- Do not use links in headings. +- Add the corresponding [product badge](#product-badges) according to the tier the + feature belongs. +- Our documentation site search engine prioritizes words used in headings and + subheadings. Make you subheading titles clear, descriptive, and complete to help + users find the right example, as shown in the section on [heading titles](#heading-titles). +- See [Capitalization](#capitalization) for guidelines on capitalizing headings. + +### Heading titles + +Keep heading titles clear and direct. Make every word count. To accommodate +search engine optimization (SEO), use the imperative, where possible. + +| Do | Don't | +|:--------------------------------------|:------------------------------------------------------------| +| Configure GDK | Configuring GDK | +| GitLab Release and Maintenance Policy | This section covers GitLab's Release and Maintenance Policy | +| Backport to older releases | Backporting to older releases | +| GitLab Pages examples | Examples | + +For guidelines on capitalizing headings, see the section on [capitalization](#capitalization). + +NOTE: **Note:** +If you change an existing title, be careful. These changes might affect not +only [links](#anchor-links) within the page, but might also affect links to the +GitLab documentation from both the GitLab application and external sites. + +### Anchor links + +Headings generate anchor links when rendered. `## This is an example` generates +the anchor `#this-is-an-example`. + +NOTE: **Note:** +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39717) in +GitLab 13.4, [product badges](#product-badges) used in headings aren't included +in the generated anchor links. For example, when you link to +`## This is an example **(CORE)**`, use the anchor `#this-is-an-example`. + +Keep in mind that the GitLab user interface links to many documentation pages +and anchor links to take the user to the right spot. Therefore, when you change +a heading, search `doc/*`, `app/views/*`, and `ee/app/views/*` for the old +anchor to make sure you're not breaking an anchor linked from other +documentation nor from the GitLab user interface. If you find the old anchor, be +sure to replace it with the new one. + +Important: + +- Avoid crosslinking documentation to headings unless you need to link to a + specific section of the document. This will avoid breaking anchors in the + future in case the heading is changed. +- If possible, avoid changing headings since they're not only linked internally. + There are various links to GitLab documentation on the internet, such as + tutorials, presentations, StackOverflow posts, and other sources. +- Do not link to `h1` headings. + +Note that, with Kramdown, it is possible to add a custom ID to an HTML element +with Markdown markup, but they _do not_ work in GitLab's `/help`. Therefore, +do not use this option until further notice. + +## Links + +Links are important in GitLab documentation. They allow you to [link instead of +summarizing](#link-instead-of-summarize) to help preserve a [single source of truth](#why-a-single-source-of-truth) +within GitLab documentation. + +We include guidance for links in the following categories: + +- How to set up [anchor links](#anchor-links) for headings. +- How to set up [criteria](#basic-link-criteria) for configuring a link. +- What to set up when [linking to a `help`](../../documentation/index.md#linking-to-help) + page. +- How to set up [links to internal documentation](#links-to-internal-documentation) + for cross-references. +- How to set up [links to external documentation](#links-to-external-documentation) + for authoritative sources. +- When to use [links requiring permissions](#links-requiring-permissions). +- How to set up a [link to a video](#link-to-video). +- How to [include links with version text](#text-for-documentation-requiring-version-text). +- How to [link to specific lines of code](#link-to-specific-lines-of-code) + +### Basic link criteria + +- Use inline link Markdown markup `[Text](https://example.com)`. + It's easier to read, review, and maintain. _Do not_ use `[Text][identifier]`. + +- Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/). + For example, instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`, + write `Read more about [GitLab Issue Boards](LINK)`. + +### Links to internal documentation + +NOTE: **Note:** +_Internal_ refers to documentation in the same project. When linking to +documentation in separate projects (for example, linking to Omnibus documentation +from GitLab documentation), you must use absolute URLs. + +Do not use absolute URLs like `https://docs.gitlab.com/ee/index.html` to +crosslink to other documentation within the same project. Use relative links to +the file, like `../index.md`. (These are converted to HTML when the site is +rendered.) + +Relative linking enables crosslinks to work: + +- in Review Apps, local previews, and `/help`. +- when working on the documentation locally, so you can verify that they work as + early as possible in the process. +- within the GitLab user interface when browsing doc files in their respective + repositories. For example, the links displayed at + `https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md`. + +To link to internal documentation: + +- Use relative links to Markdown files in the same repository. +- Do not use absolute URLs or URLs from `docs.gitlab.com`. +- Use `../` to navigate to higher-level directories. +- Don't prepend `./` to links to files or directories. +- Don't link relative to root. For example, `/ee/user/gitlab_com/index.md`. + + Don't: + + - `https://docs.gitlab.com/ee/administration/geo/replication/troubleshooting.html` + - `/ee/administration/geo/replication/troubleshooting.md` + - `./troubleshooting.md` + + Do: `../../geo/replication/troubleshooting.md` + +- Always add the file name `file.md` at the end of the link with the `.md` + extension, not `.html`. + + Don't: + + - `../../merge_requests/` + - `../../issues/tags.html` + - `../../issues/tags.html#stages` + + Do: + + - `../../merge_requests/index.md` + - `../../issues/tags.md` + - `../../issues/tags.md#stages` + +NOTE: **Note:** +Using the Markdown extension is necessary for the [`/help`](../index.md#gitlab-help) +section of GitLab. + +### Links to external documentation + +When describing interactions with external software, it's often helpful to +include links to external documentation. When possible, make sure that you're +linking to an [**authoritative** source](#authoritative-sources). For example, +if you're describing a feature in Microsoft's Active Directory, include a link +to official Microsoft documentation. + +### Authoritative sources + +When citing external information, use sources that are written by the people who +created the item or product in question. These sources are the most likely to be +accurate and remain up to date. + +Examples of authoritative sources include: + +- Specifications, such as a [Request for Comments](https://www.ietf.org/standards/rfcs/) + document from the Internet Engineering Task Force. +- Official documentation for a product. For example, if you're setting up an + interface with the Google OAuth 2 authorization server, include a link to + Google's documentation. +- Official documentation for a project. For example, if you're citing NodeJS + functionality, refer directly to [NodeJS documentation](https://nodejs.org/en/docs/). +- Books from an authoritative publisher. + +Examples of sources to avoid include: + +- Personal blog posts. +- Wikipedia. +- Non-trustworthy articles. +- Discussions on forums such as Stack Overflow. +- Documentation from a company that describes another company's product. + +While many of these sources to avoid can help you learn skills and or features, +they can become obsolete quickly. Nobody is obliged to maintain any of these +sites. Therefore, we should avoid using them as reference literature. + +NOTE: **Note:** +Non-authoritative sources are acceptable only if there is no equivalent +authoritative source. Even then, focus on non-authoritative sources that are +extensively cited or peer-reviewed. + +### Links requiring permissions + +Don't link directly to: + +- [Confidential issues](../../../user/project/issues/confidential_issues.md). +- Project features that require [special permissions](../../../user/permissions.md) + to view. + +These will fail for: + +- Those without sufficient permissions. +- Automated link checkers. + +Instead: + +- To reduce confusion, mention in the text that the information is either: + - Contained in a confidential issue. + - Requires special permission to a project to view. +- Provide a link in back ticks (`` ` ``) so that those with access to the issue + can navigate to it. + +Example: + +```markdown +For more information, see the [confidential issue](../../../user/project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/<issue_number>`. +``` + +### Link to specific lines of code + +When linking to specific lines within a file, link to a commit instead of to the +branch. Lines of code change through time, therefore, linking to a line by using +the commit link ensures the user lands on the line you're referring to. The +**Permalink** button, which is available when viewing a file within a project, +makes it easy to generate a link to the most recent commit of the given file. + +- _Do_: `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)` +- _Don't_: `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).` + +If that linked expression is no longer in that line of the file due to additional +commits, you can still search the file for that query. In this case, update the +document to ensure it links to the most recent version of the file. + +## Navigation + +When documenting navigation through the user interface: + +- Use the exact wording as shown in the UI, including any capital letters as-is. +- Use bold text for navigation items and the char "greater than" (`>`) as a + separator. For example: `Navigate to your project's **Settings > CI/CD**`. +- If there are any expandable menus, make sure to mention that the user needs to + expand the tab to find the settings you're referring to. For example: + `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`. + +### Navigational elements + +Use the following terms when referring to the main GitLab user interface +elements: + +- **Top menu**: This is the top menu that spans the width of the user interface. + It includes the GitLab logo, search field, counters, and the user's avatar. +- **Left sidebar**: This is the navigation sidebar on the left of the user + interface, specific to the project or group. +- **Right sidebar**: This is the navigation sidebar on the right of the user + interface, specific to the open issue, merge request, or epic. + +## Images + +Images, including screenshots, can help a reader better understand a concept. +However, they can be hard to maintain, and should be used sparingly. + +Before including an image in the documentation, ensure it provides value to the +reader. + +### Capture the image + +Use images to help the reader understand where they are in a process, or how +they need to interact with the application. + +When you take screenshots: + +- _Capture the most relevant area of the page._ Don't include unnecessary white + space or areas of the page that don't help illustrate the point. The left + sidebar of the GitLab user interface can change, so don't include the sidebar + if it's not necessary. +- _Keep it small._ If you don't need to show the full width of the screen, don't. + A value of 1000 pixels is a good maximum width for your screenshot image. +- _Be consistent._ Coordinate screenshots with the other screenshots already on + a documentation page. For example, if other screenshots include the left + sidebar, include the sidebar in all screenshots. + +### Save the image + +- Save the image with a lowercase file name that's descriptive of the feature + or concept in the image. If the image is of the GitLab interface, append the + GitLab version to the file name, based on the following format: + `image_name_vX_Y.png`. For example, for a screenshot taken from the pipelines + page of GitLab 11.1, a valid name is `pipelines_v11_1.png`. If you're adding an + illustration that doesn't include parts of the user interface, add the release + number corresponding to the release the image was added to; for an MR added to + 11.1's milestone, a valid name for an illustration is `devops_diagram_v11_1.png`. +- Place images in a separate directory named `img/` in the same directory where + the `.md` document that you're working on is located. +- Consider using PNG images instead of JPEG. +- [Compress all PNG images](#compress-images). +- Compress gifs with <https://ezgif.com/optimize> or similar tool. +- Images should be used (only when necessary) to _illustrate_ the description + of a process, not to _replace_ it. +- Max image size: 100KB (gifs included). +- See also how to link and embed [videos](#videos) to illustrate the + documentation. + +### Add the image link to content + +The Markdown code for including an image in a document is: +`` + +The image description is the alt text for the rendered image on the +documentation site. For accessibility and SEO, use [descriptions](https://webaim.org/techniques/alttext/) +that: + +- Are accurate, succinct, and unique. +- Don't use _image of…_ or _graphic of…_ to describe the image. + +### Compress images + +You should always compress any new images you add to the documentation. One +known tool is [`pngquant`](https://pngquant.org/), which is cross-platform and +open source. Install it by visiting the official website and following the +instructions for your OS. + +GitLab has a [Rake task](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/tasks/pngquant.rake) +that you can use to automate the process. In the root directory of your local +copy of `https://gitlab.com/gitlab-org/gitlab`, run in a terminal: + +- Before compressing, if you want, check that all documentation PNG images have + been compressed: + + ```shell + bundle exec rake pngquant:lint + ``` + +- Compress all documentation PNG images using `pngquant`: + + ```shell + bundle exec rake pngquant:compress + ``` + +The only caveat is that the task runs on all images under `doc/`, not only the +ones you might have included in a merge request. In that case, you can run the +compress task and only commit the images that are relevant to your merge +request. + +## Videos + +Adding GitLab's existing YouTube video tutorials to the documentation is highly +encouraged, unless the video is outdated. Videos should not replace +documentation, but complement or illustrate it. If content in a video is +fundamental to a feature and its key use cases, but this is not adequately +covered in the documentation, add this detail to the documentation text or +create an issue to review the video and do so. + +Do not upload videos to the product repositories. [Link](#link-to-video) or +[embed](#embed-videos) them instead. + +### Link to video + +To link out to a video, include a YouTube icon so that readers can scan the page +for videos before reading: + +```markdown +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Video Title](link-to-video). +``` + +You can link any up-to-date video that's useful to the GitLab user. + +### Embed videos + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/472) in GitLab 12.1. + +The [GitLab documentation site](https://docs.gitlab.com) supports embedded +videos. + +You can only embed videos from [GitLab's official YouTube account](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg). +For videos from other sources, [link](#link-to-video) them instead. + +In most cases, it is better to [link to video](#link-to-video) instead, because +an embed takes up a lot of space on the page and can be distracting to readers. + +To embed a video: + +1. Copy the code from this procedure and paste it into your Markdown file. Leave a + blank line above and below it. Do _not_ edit the code (don't remove or add any spaces). +1. In YouTube, visit the video URL you want to display. Copy the regular URL + from your browser (`https://www.youtube.com/watch?v=VIDEO-ID`) and replace + the video title and link in the line under `<div class="video-fallback">`. +1. In YouTube, select **Share**, and then select **Embed**. +1. Copy the `<iframe>` source (`src`) **URL only** + (`https://www.youtube.com/embed/VIDEO-ID`), + and paste it, replacing the content of the `src` field in the + `iframe` tag. + +```html +leave a blank line here +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe> +</figure> +leave a blank line here +``` + +This is how it renders on the GitLab documentation site: + +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=enMumwvLAug">What is GitLab</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe> +</figure> + +> Notes: +> +> - The `figure` tag is required for semantic SEO and the `video_container` +class is necessary to make sure the video is responsive and displays on +different mobile devices. +> - The `<div class="video-fallback">` is a fallback necessary for GitLab's +`/help`, as GitLab's Markdown processor does not support iframes. It's hidden on +the documentation site, but will be displayed on GitLab's `/help`. + +## Code blocks + +- Always wrap code added to a sentence in inline code blocks (`` ` ``). + For example, `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, or `only: [master]`. + File names, commands, entries, and anything that refers to code should be + added to code blocks. To make things easier for the user, always add a full + code block for things that can be useful to copy and paste, as they can do it + with the button on code blocks. +- HTTP methods (`HTTP POST`) and HTTP status codes, both full (`404 File Not Found`) + and abbreviated (`404`), should be wrapped in inline code blocks when used in sentences. + For example: Send a `DELETE` request to delete the runner. Send a `POST` request to create one. +- Add a blank line above and below code blocks. +- When providing a shell command and its output, prefix the shell command with `$` + and leave a blank line between the command and the output. +- When providing a command without output, don't prefix the shell command with `$`. +- If you need to include triple backticks inside a code block, use four backticks + for the codeblock fences instead of three. +- For regular fenced code blocks, always use a highlighting class corresponding to + the language for better readability. Examples: + + ````markdown + ```ruby + Ruby code + ``` + + ```javascript + JavaScript code + ``` + + ```markdown + [Markdown code example](example.md) + ``` + + ```plaintext + Code or text for which no specific highlighting class is available. + ``` + ```` + +Syntax highlighting is required for fenced code blocks added to the GitLab +documentation. Refer to the following table for the most common language classes, +or check the [complete list](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) +of available language classes: + +| Preferred language tags | Language aliases and notes | +|-------------------------|------------------------------------------------------------------------------| +| `asciidoc` | | +| `dockerfile` | Alias: `docker`. | +| `elixir` | | +| `erb` | | +| `golang` | Alias: `go`. | +| `graphql` | | +| `haml` | | +| `html` | | +| `ini` | For some simple config files that are not in TOML format. | +| `javascript` | Alias `js`. | +| `json` | | +| `markdown` | Alias: `md`. | +| `mermaid` | | +| `nginx` | | +| `perl` | | +| `php` | | +| `plaintext` | Examples with no defined language, such as output from shell commands or API calls. If a codeblock has no language, it defaults to `plaintext`. Alias: `text`. | +| `prometheus` | Prometheus configuration examples. | +| `python` | | +| `ruby` | Alias: `rb`. | +| `shell` | Aliases: `bash` or `sh`. | +| `sql` | | +| `toml` | Runner configuration examples, and other TOML-formatted configuration files. | +| `typescript` | Alias: `ts`. | +| `xml` | | +| `yaml` | Alias: `yml`. | + +For a complete reference on code blocks, see the [Kramdown guide](https://about.gitlab.com/handbook/markdown-guide/#code-blocks). + +## GitLab SVG icons + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/384) in GitLab 12.7. + +You can use icons from the [GitLab SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/) +directly in the documentation. + +This way, you can achieve a consistent look when writing about interacting with +GitLab user interface elements. + +Usage examples: + +- Icon with default size (16px): `**{icon-name}**` + + Example: `**{tanuki}**` renders as: **{tanuki}**. +- Icon with custom size: `**{icon-name, size}**` + + Available sizes (in px): 8, 10, 12, 14, 16, 18, 24, 32, 48, and 72 + + Example: `**{tanuki, 24}**` renders as: **{tanuki, 24}**. +- Icon with custom size and class: `**{icon-name, size, class-name}**`. + + You can access any class available to this element in GitLab documentation CSS. + + Example with `float-right`, a + [Bootstrap utility class](https://getbootstrap.com/docs/4.4/utilities/float/): + `**{tanuki, 32, float-right}**` renders as: **{tanuki, 32, float-right}** + +### When to use icons + +Icons should be used sparingly, and only in ways that aid and do not hinder the +readability of the text. + +For example, the following adds little to the accompanying text: + +```markdown +1. Go to **{home}** **Project overview > Details** +``` + +1. Go to **{home}** **Project overview > Details** + +However, the following might help the reader connect the text to the user +interface: + +```markdown +| Section | Description | +|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| +| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | +| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit logs. | +| **{messages}** Messages | Send and manage broadcast messages for your users. | +``` + +| Section | Description | +|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| +| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | +| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit logs. | +| **{messages}** Messages | Send and manage broadcast messages for your users. | + +Use an icon when you find yourself having to describe an interface element. For +example: + +- Do: Select the Admin Area icon ( **{admin}** ). +- Don't: Select the Admin Area icon (the wrench icon). + +## Alert boxes + +When you need to call special attention to particular sentences, use the +following markup to create highlighted alert boxes. + +Alert boxes work for one paragraph only. Multiple paragraphs, lists, and headers +won't render correctly. For multiple lines, use [blockquotes](#blockquotes) +instead. + +Alert boxes render only on the GitLab documentation site (<https://docs.gitlab.com>). +In the GitLab product help, alert boxes appear as plain Markdown text. + +These alert boxes are used in the GitLab documentation. These aren't strict +guidelines, but for consistency you should try to use these values: + +| Color | Markup | Default keyword | Alternative keywords | +|--------|------------|-----------------|----------------------------------------------------------------------| +| Blue | `NOTE:` | `**Note:**` | | +| Yellow | `CAUTION:` | `**Caution:**` | `**Warning:**`, `**Important:**` | +| Red | `DANGER:` | `**Danger:**` | `**Warning:**`, `**Important:**`, `**Deprecated:**`, `**Required:**` | +| Green | `TIP:` | `**Tip:**` | | + +### Note + +Notes indicate additional information that's of special use to the reader. +Notes are most effective when used _sparingly_. + +Try to avoid them. Too many notes can impact the scannability of a topic and +create an overly busy page. + +Instead of adding a note, try one of these alternatives: + +- Re-write the sentence as part of the most-relevant paragraph. +- Put the information into its own standalone paragraph. +- Put the content under a new subheading that introduces the topic, which makes + it more visible. + +If you must use a note, use the following formatting: + +```markdown +NOTE: **Note:** +This is something to note. +``` + +How it renders on the GitLab documentation site: + +NOTE: **Note:** +This is something to note. + +### Tip + +```markdown +TIP: **Tip:** +This is a tip. +``` + +How it renders on the GitLab documentation site: + +TIP: **Tip:** +This is a tip. + +### Caution + +```markdown +CAUTION: **Caution:** +This is something to be cautious about. +``` + +How it renders on the GitLab documentation site: + +CAUTION: **Caution:** +This is something to be cautious about. + +### Danger + +```markdown +DANGER: **Warning:** +This is a breaking change, a bug, or something very important to note. +``` + +How it renders on the GitLab documentation site: + +DANGER: **Warning:** +This is a breaking change, a bug, or something very important to note. + +## Blockquotes + +For highlighting a text within a blue blockquote, use this format: + +```markdown +> This is a blockquote. +``` + +which renders on the [GitLab documentation site](https://docs.gitlab.com) as: + +> This is a blockquote. + +If the text spans across multiple lines it's OK to split the line. + +For multiple paragraphs, use the symbol `>` before every line: + +```markdown +> This is the first paragraph. +> +> This is the second paragraph. +> +> - This is a list item +> - Second item in the list +``` + +Which renders to: + +> This is the first paragraph. +> +> This is the second paragraph. +> +> - This is a list item +> - Second item in the list + +## Terms + +To maintain consistency through GitLab documentation, the following guides +documentation authors on agreed styles and usage of terms. + +### Merge requests (MRs) + +Merge requests allow you to exchange changes you made to source code and +collaborate with other people on the same project. You'll see this term used in +the following ways: + +- Use lowercase _merge requests_ regardless of whether referring to the feature + or individual merge requests. + +As noted in the GitLab [Writing Style Guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines), +if you use the _MR_ acronym, expand it at least once per document page. +Typically, the first use would be phrased as _merge request (MR)_ with subsequent +instances being _MR_. + +Examples: + +- "We prefer GitLab merge requests". +- "Open a merge request to fix a broken link". +- "After you open a merge request (MR), submit your MR for review and approval". + +### Describe UI elements + +The following are styles to follow when describing user interface elements in an +application: + +- For elements with a visible label, use that label in bold with matching case. + For example, `the **Cancel** button`. +- For elements with a tooltip or hover label, use that label in bold with + matching case. For example, `the **Add status emoji** button`. + +### Verbs for UI elements + +The following are recommended verbs for specific uses with user interface +elements: + +| Recommended | Used for | Replaces | +|:--------------------|:--------------------------------------|:---------------------------| +| _select_ | buttons, links, menu items, dropdowns | "click, "press," "hit" | +| _select_ or _clear_ | checkboxes | "enable", "click", "press" | +| _expand_ | expandable sections | "open" | + +### Other Verbs + +| Recommended | Used for | Replaces | +|:------------|:--------------------------------|:----------------------| +| _go to_ | making a browser go to location | "navigate to", "open" | + +## GitLab versions and tiers + +Tagged and released versions of GitLab documentation are available: + +- In the [documentation archives](https://docs.gitlab.com/archives/). +- At the `/help` URL for any GitLab installation. + +The version introducing a new feature is added to the top of the topic in the +documentation to provide a link back to how the feature was developed. + +TIP: **Tip:** +Whenever you have documentation related to the `gitlab.rb` file, you're working +with a self-managed installation. The section or page is therefore likely to +apply only to self-managed instances. If so, the relevant "`TIER` ONLY" +[Product badge](#product-badges) should be included at the highest applicable +heading level. + +### Text for documentation requiring version text + +When a feature is new or updated, you can add version information as a bulleted +item in the **Version history**, or as an inline reference with related text. + +#### Version text in the **Version History** + +If all content in a section is related, add version text following the header for +the section. Each entry should be on a single line. To render correctly, it must be on its +own line and surrounded by blank lines. + +Features should declare the GitLab version that introduced a feature in a blockquote +following the header: + +```markdown +## Feature name + +> Introduced in GitLab 11.3. + +This feature does something. +``` + +Whenever possible, version text should have a link to the _completed_ issue, +merge request, or epic that introduced the feature. An issue is preferred over +a merge request, and a merge request is preferred over an epic. For example: + +```markdown +> [Introduced](<link-to-issue>) in GitLab 11.3. +``` + +If the feature is only available in GitLab Enterprise Edition, mention +the [paid tier](https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/) +the feature is available in: + +```markdown +> [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. +``` + +If listing information for multiple version as a feature evolves, add the +information to a block-quoted bullet list. For example: + +```markdown +> - [Introduced](<link-to-issue>) in GitLab 11.3. +> - Enabled by default in GitLab 11.4. +``` + +If a feature is moved to another tier: + +```markdown +> - [Introduced](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. +> - [Moved](<link-to-issue>) to [GitLab Starter](https://about.gitlab.com/pricing/) in 11.8. +> - [Moved](<link-to-issue>) to GitLab Core in 12.0. +``` + +If a feature is deprecated, include a link to a replacement (when available): + +```markdown +> - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>). +``` + +You can also describe the replacement in surrounding text, if available. + +If the deprecation is not obvious in existing text, you may want to include a +warning such as: + +```markdown +DANGER: **Deprecated:** +This feature was [deprecated](link-to-issue) in GitLab 12.3 +and replaced by [Feature name](link-to-feature-documentation). +``` + +#### Inline version text + +If you're adding content to an existing topic, you can add version information +inline with the existing text. + +In this case, add `([introduced/deprecated](<link-to-issue>) in GitLab X.X)`. +If applicable, include the paid tier: `([introduced/deprecated](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4)` + +Including the issue link is encouraged, but isn't a requirement. For example: + +```markdown +The voting strategy (in GitLab 13.4 and later) requires +the primary and secondary voters to agree. +``` + +#### End-of-life for features or products + +Whenever a feature or product enters the end-of-life process, indicate its +status by using the `Danger` [alert](#alert-boxes) with the `**Important**` +keyword directly below the feature or product's header (which can include H1 +page titles). Link to the deprecation and removal issues, if possible. + +For example: + +```markdown +DANGER: **Important:** +This feature is in its end-of-life process. It is [deprecated](link-to-issue) +for use in GitLab X.X, and is planned for [removal](link-to-issue) in GitLab X.X. +``` + +### Versions in the past or future + +When describing functionality available in past or future versions, use: + +- _Earlier_, and not _older_ or _before_. +- _Later_, and not _newer_ or _after_. + +For example: + +- Available in GitLab 12.3 and earlier. +- Available in GitLab 12.4 and later. +- In GitLab 11.4 and earlier, ... +- In GitLab 10.6 and later, ... + +### Importance of referencing GitLab versions and tiers + +Mentioning GitLab versions and tiers is important to all users and contributors +to quickly have access to the issue or merge request that introduced the change. +Also, they can know what features they have in their GitLab +instance and version, given that the note has some key information. + +`[Introduced](link-to-issue) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7` +links to the issue that introduced the feature, says which GitLab tier it +belongs to, says the GitLab version that it became available in, and links to +the pricing page in case the user wants to upgrade to a paid tier to use that +feature. + +For example, if you're a regular user and you're looking at the documentation +for a feature you haven't used before, you can immediately see if that feature +is available to you or not. Alternatively, if you've been using a certain +feature for a long time and it changed in some way, it's important to be able to +determine when it changed and what's new in that feature. + +This is even more important as we don't have a perfect process for shipping +documentation. Unfortunately, we still see features without documentation, and +documentation without features. So, for now, we cannot rely 100% on the +documentation site versions. + +Over time, version text will reference a progressively older version of GitLab. +In cases where version text refers to versions of GitLab four or more major +versions back, you can consider removing the text if it's irrelevant or confusing. + +For example, if the current major version is 12.x, version text referencing +versions of GitLab 8.x and older are candidates for removal if necessary for +clearer or cleaner documentation. + +## Products and features + +Refer to the information in this section when describing products and features +within the GitLab product documentation. + +### Avoid line breaks in names + +When entering a product or feature name that includes a space (such as +GitLab Community Edition) or even other companies' products (such as +Amazon Web Services), be sure to not split the product or feature name across +lines with an inserted line break. Splitting product or feature names across +lines makes searching for these items more difficult, and can cause problems if +names change. + +For example, the following Markdown content is _not_ formatted correctly: + +```markdown +When entering a product or feature name that includes a space (such as GitLab +Community Edition), don't split the product or feature name across lines. +``` + +Instead, it should appear similar to the following: + +```markdown +When entering a product or feature name that includes a space (such as +GitLab Community Edition), don't split the product or feature name across lines. +``` + +### Product badges + +When a feature is available in paid tiers, add the corresponding tier to the +header or other page element according to the feature's availability: + +| Tier in which feature is available | Tier markup | +|:-----------------------------------------------------------------------|:----------------------| +| GitLab Core and GitLab.com Free, and their higher tiers | `**(CORE)**` | +| GitLab Starter and GitLab.com Bronze, and their higher tiers | `**(STARTER)**` | +| GitLab Premium and GitLab.com Silver, and their higher tiers | `**(PREMIUM)**` | +| GitLab Ultimate and GitLab.com Gold | `**(ULTIMATE)**` | +| _Only_ GitLab Core and higher tiers (no GitLab.com-based tiers) | `**(CORE ONLY)**` | +| _Only_ GitLab Starter and higher tiers (no GitLab.com-based tiers) | `**(STARTER ONLY)**` | +| _Only_ GitLab Premium and higher tiers (no GitLab.com-based tiers) | `**(PREMIUM ONLY)**` | +| _Only_ GitLab Ultimate (no GitLab.com-based tiers) | `**(ULTIMATE ONLY)**` | +| _Only_ GitLab.com Free and higher tiers (no self-managed instances) | `**(FREE ONLY)**` | +| _Only_ GitLab.com Bronze and higher tiers (no self-managed instances) | `**(BRONZE ONLY)**` | +| _Only_ GitLab.com Silver and higher tiers (no self-managed instances) | `**(SILVER ONLY)**` | +| _Only_ GitLab.com Gold (no self-managed instances) | `**(GOLD ONLY)**` | + +For clarity, all page title headers (H1s) must be have a tier markup for the +lowest tier that has information on the documentation page. + +If sections of a page apply to higher tier levels, they can be separately +labeled with their own tier markup. + +#### Product badge display behavior + +When using the tier markup with headers, the documentation page will display the +full tier badge with the header line. + +You can also use the tier markup with paragraphs, list items, and table cells. +For these cases, the tier mention will be represented by an orange info icon +**{information}** that will display the tiers when visitors point to the icon. +For example: + +- `**(STARTER)**` displays as **(STARTER)** +- `**(STARTER ONLY)**` displays as **(STARTER ONLY)** +- `**(SILVER ONLY)**` displays as **(SILVER ONLY)** + +#### How it works + +Introduced by [!244](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/244), +the special markup `**(STARTER)**` will generate a `span` element to trigger the +badges and tooltips (`<span class="badge-trigger starter">`). When the keyword +_only_ is added, the corresponding GitLab.com badge will not be displayed. + +## Specific sections + +Certain styles should be applied to specific sections. Styles for specific +sections are outlined in this section. + +### GitLab restart + +There are many cases that a restart/reconfigure of GitLab is required. To avoid +duplication, link to the special document that can be found in +[`doc/administration/restart_gitlab.md`](../../../administration/restart_gitlab.md). +Usually the text will read like: + +```markdown +Save the file and [reconfigure GitLab](../../../administration/restart_gitlab.md) +for the changes to take effect. +``` + +If the document you are editing resides in a place other than the GitLab CE/EE +`doc/` directory, instead of the relative link, use the full path: +`https://docs.gitlab.com/ee/administration/restart_gitlab.html`. Replace +`reconfigure` with `restart` where appropriate. + +### Installation guide + +**Ruby:** +In [step 2 of the installation guide](../../../install/installation.md#2-ruby), +we install Ruby from source. Whenever there is a new version that needs to +be updated, remember to change it throughout the codeblock and also replace +the sha256sum (it can be found in the [downloads page](https://www.ruby-lang.org/en/downloads/) +of the Ruby website). + +### Configuration documentation for source and Omnibus installations + +GitLab currently officially supports two installation methods: installations +from source and Omnibus packages installations. + +Whenever there's a setting that's configurable for both installation methods, +the preference is to document it in the CE documentation to avoid duplication. + +Configuration settings include: + +- Settings that touch configuration files in `config/`. +- NGINX settings and settings in `lib/support/` in general. + +When you document a list of steps, it may entail editing the configuration file +and reconfiguring or restarting GitLab. In that case, use these styles: + +````markdown +**For Omnibus installations** + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + external_url "https://gitlab.example.com" + ``` + +1. Save the file and [reconfigure](path/to/administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab for the changes to take effect. + +--- + +**For installations from source** + +1. Edit `config/gitlab.yml`: + + ```yaml + gitlab: + host: "gitlab.example.com" + ``` + +1. Save the file and [restart](path/to/administration/restart_gitlab.md#installations-from-source) + GitLab for the changes to take effect. +```` + +In this case: + +- Before each step list the installation method is declared in bold. +- Three dashes (`---`) are used to create a horizontal line and separate the two + methods. +- The code blocks are indented one or more spaces under the list item to render + correctly. +- Different highlighting languages are used for each config in the code block. +- The [GitLab Restart](#gitlab-restart) section is used to explain a required + restart or reconfigure of GitLab. + +### Troubleshooting + +For troubleshooting sections, you should provide as much context as possible so +users can identify the problem they are facing and resolve it on their own. You +can facilitate this by making sure the troubleshooting content addresses: + +1. The problem the user needs to solve. +1. How the user can confirm they have the problem. +1. Steps the user can take towards resolution of the problem. + +If the contents of each category can be summarized in one line and a list of +steps aren't required, consider setting up a [table](#tables) with headers of +_Problem_ \| _Cause_ \| _Solution_ (or _Workaround_ if the fix is temporary), or +_Error message_ \| _Solution_. + +## 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/testing.md b/doc/development/documentation/testing.md new file mode 100644 index 00000000000..043da38d207 --- /dev/null +++ b/doc/development/documentation/testing.md @@ -0,0 +1,292 @@ +--- +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/engineering/ux/technical-writing/#designated-technical-writers +description: Learn how to contribute to GitLab Documentation. +--- + +# Documentation testing + +We treat documentation as code, and so use tests in our CI pipeline to maintain the +standards and quality of the docs. The current tests, which run in CI jobs when a +merge request with new or changed docs is submitted, are: + +- [`docs lint`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L41): + Runs several tests on the content of the docs themselves: + - [`lint-doc.sh` script](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) + runs the following checks and linters: + - All cURL examples use the long flags (ex: `--header`, not `-H`). + - The `CHANGELOG.md` does not contain duplicate versions. + - No files in `doc/` are executable. + - No new `README.md` was added. + - [markdownlint](#markdownlint). + - [Vale](#vale). + - Nanoc tests: + - [`internal_links`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L58) + checks that all internal links (ex: `[link](../index.md)`) are valid. + - [`internal_anchors`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L60) + checks that all internal anchors (ex: `[link](../index.md#internal_anchor)`) + are valid. + - [`ui-docs-links lint`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L62) + checks that all links to docs from UI elements (`app/views` files, for example) + are linking to valid docs and anchors. + +## Run tests locally + +Apart from [previewing your changes locally](index.md#previewing-the-changes-live), you can also run all lint checks +and Nanoc tests locally. + +### Lint checks + +Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) +script and can be executed as follows: + +1. Navigate to the `gitlab` directory. +1. Run: + + ```shell + MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh + ``` + +Where `MD_DOC_PATH` points to the file or directory you would like to run lint checks for. +If you omit it completely, it defaults to the `doc/` directory. +The output should be similar to: + +```plaintext +=> Linting documents at path /path/to/gitlab as <user>... +=> Checking for cURL short options... +=> Checking for CHANGELOG.md duplicate entries... +=> Checking /path/to/gitlab/doc for executable permissions... +=> Checking for new README.md files... +=> Linting markdown style... +=> Linting prose... +✔ 0 errors, 0 warnings and 0 suggestions in 1 file. +✔ Linting passed +``` + +This requires you to either: + +- Have the required lint tools installed on your machine. +- A working Docker installation, in which case an image with these tools pre-installed is used. + +### Nanoc tests + +To execute Nanoc tests locally: + +1. Navigate to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. +1. Run: + + ```shell + # Check for broken internal links + bundle exec nanoc check internal_links + + # Check for broken external links (might take a lot of time to complete). + # This test is set to be allowed to fail and is run only in the gitlab-docs project CI + bundle exec nanoc check internal_anchors + ``` + +### `ui-docs-links` test + +The `ui-docs-links lint` job uses `haml-lint` to test that all links to docs from +UI elements (`app/views` files, for example) are linking to valid docs and anchors. + +To run the `ui-docs-links` test locally: + +1. Open the `gitlab` directory in a terminal window. +1. Run: + + ```shell + bundle exec haml-lint -i DocumentationLinks + ``` + +If you receive an error the first time you run this test, run `bundle install`, which +installs GitLab's dependencies, and try again. + +If you don't want to install all of GitLab's dependencies to test the links, you can: + +1. Open the `gitlab` directory in a terminal window. +1. Install `haml-lint`: + + ```shell + gem install haml_lint + ``` + +1. Run: + + ```shell + haml-lint -i DocumentationLinks + ``` + +If you manually install `haml-lint` with this process, it does not update automatically +and you should make sure your version matches the version used by GitLab. + +## Local linters + +To help adhere to the [documentation style guidelines](styleguide/index.md), and improve the content +added to documentation, [install documentation linters](#install-linters) and +[integrate them with your code editor](#configure-editors). + +At GitLab, we mostly use: + +- [markdownlint](#markdownlint) +- [Vale](#vale) + +### markdownlint + +[markdownlint](https://github.com/DavidAnson/markdownlint) checks that Markdown syntax follows +[certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules), and is +used by the `docs-lint` test. + +Our [Documentation Style Guide](styleguide/index.md#markdown) and +[Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) elaborate on which choices must +be made when selecting Markdown syntax for GitLab documentation. This tool helps catch deviations +from those guidelines. + +markdownlint configuration is found in the following projects: + +- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.markdownlint.json) +- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/.markdownlint.json) +- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.markdownlint.json) +- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.markdownlint.json) +- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/.markdownlint.json) + +This configuration is also used within build pipelines. + +You can use markdownlint: + +- [On the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--). +- [Within a code editor](#configure-editors). +- [In a `pre-push` hook](#configure-pre-push-hooks). + +### Vale + +[Vale](https://errata-ai.gitbook.io/vale/) is a grammar, style, and word usage linter for the +English language. Vale's configuration is stored in the +[`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) file located in the root +directory of projects. + +Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/) that extend any of +several types of checks, which we store in the `.linting/vale/styles/gitlab` directory within the +documentation directory of projects. + +Vale configuration is found in the following projects: + +- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab) +- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/master/docs/.vale/gitlab) +- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/tree/master/doc/.vale/gitlab) +- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/master/doc/.vale/gitlab) +- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/master/doc/.vale/gitlab) + +This configuration is also used within build pipelines. + +You can use Vale: + +- [On the command line](https://errata-ai.gitbook.io/vale/getting-started/usage). +- [Within a code editor](#configure-editors). +- [In a Git hook](#configure-pre-push-hooks). Vale only reports errors in the Git hook (the same + configuration as the CI/CD pipelines), and does not report suggestions or warnings. + +### Install linters + +At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in +build pipelines: + +1. Install `markdownlint-cli`, using either: + + - `npm`: + + ```shell + npm install -g markdownlint-cli + ``` + + - `yarn`: + + ```shell + yarn global add markdownlint-cli + ``` + + We recommend installing the version of `markdownlint-cli` currently used in the documentation + linting [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L420). + +1. Install [`vale`](https://github.com/errata-ai/vale/releases). For example, to install using + `brew` for macOS, run: + + ```shell + brew install vale + ``` + + We recommend installing the version of Vale currently used in the documentation linting + [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L419). + +In addition to using markdownlint and Vale at the command line, these tools can be +[integrated with your code editor](#configure-editors). + +### Configure editors + +To configure markdownlint within your editor, install one of the following as appropriate: + +- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) +- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) +- [Atom](https://atom.io/packages/linter-node-markdownlint) +- [Vim](https://github.com/dense-analysis/ale) + +To configure Vale within your editor, install one of the following as appropriate: + +- The Sublime Text [`SublimeLinter-contrib-vale` plugin](https://packagecontrol.io/packages/SublimeLinter-contrib-vale). +- The Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). + You don't need Vale Server to use the plugin. You can configure the plugin to + [display only a subset of alerts](#show-subset-of-vale-alerts). +- [Vim](https://github.com/dense-analysis/ale). + +We don't use [Vale Server](https://errata-ai.github.io/vale/#using-vale-with-a-text-editor-or-another-third-party-application). + +### Configure pre-push hooks + +Git [pre-push hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) allow Git users to: + +- Run tests or other processes before pushing a branch. +- Avoid pushing a branch if failures occur with these tests. + +[`lefthook`](https://github.com/Arkweid/lefthook) is a Git hooks manager, making configuring, +installing, and removing Git hooks easy. + +Configuration for `lefthook` is available in the [`lefthook.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lefthook.yml) +file for the [`gitlab`](https://gitlab.com/gitlab-org/gitlab) project. + +To set up `lefthook` for documentation linting, see +[Pre-push static analysis](../contributing/style_guides.md#pre-push-static-analysis). + +### Show subset of Vale alerts + +You can set Visual Studio Code to display only a subset of Vale alerts when viewing files: + +1. Go to **Preferences > Settings > Extensions > Vale**. +1. In **Vale CLI: Min Alert Level**, select the minimum alert level you want displayed in files. + +To display only a subset of Vale alerts when running Vale from the command line, use +the `--minAlertLevel` flag, which accepts `error`, `warning`, or `suggestion`. Combine it with `--config` +to point to the configuration file within the project, if needed: + +```shell +vale --config .vale.ini --minAlertLevel error doc/**/*.md +``` + +Omit the flag to display all alerts, including `suggestion` level alerts. + +### Disable Vale tests + +You can disable a specific Vale linting rule or all Vale linting rules for any portion of a +document: + +- To disable a specific rule, add a `<!-- vale gitlab.rulename = NO -->` tag before the text, and a + `<!-- vale gitlab.rulename = YES -->` tag after the text, replacing `rulename` with the filename + of a test in the + [GitLab styles](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.linting/vale/styles/gitlab) + directory. +- To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text, and a + `<!-- vale on -->` tag after the text. + +Whenever possible, exclude only the problematic rule and line(s). + +For more information, see +[Vale's documentation](https://errata-ai.gitbook.io/vale/getting-started/markup#markup-based-configuration). diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 488c71a6328..9bc80116d25 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -1,10 +1,15 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Documentation process The process for creating and maintaining GitLab product documentation allows anyone to contribute a merge request or create an issue for GitLab's documentation. -NOTE: **Note:** Documentation updates relating to new features or feature enhancements must use the [feature workflow process](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#for-a-product-change) described in the GitLab Handbook. @@ -53,7 +58,7 @@ To update GitLab documentation: [GitLab Documentation guidelines](index.md) page. 1. Follow the described standards and processes listed on the page, including: - The [Structure and template](structure.md) page. - - The [Style Guide](styleguide.md). + - The [Style Guide](styleguide/index.md). - The [Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/). 1. Follow GitLab's [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines). @@ -82,7 +87,7 @@ Anyone with Maintainer access to the relevant GitLab project can merge documenta Maintainers must make a good-faith effort to ensure that the content: - Is clear and sufficiently easy for the intended audience to navigate and understand. -- Meets the [Documentation Guidelines](index.md) and [Style Guide](styleguide.md). +- Meets the [Documentation Guidelines](index.md) and [Style Guide](styleguide/index.md). If the author or reviewer has any questions, they can mention the writer who is assigned to the relevant [DevOps stage group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments). @@ -149,16 +154,15 @@ Remember: Ensure the following if skipping an initial Technical Writer review: -- That [product badges](styleguide.md#product-badges) are applied. -- That the GitLab [version](styleguide.md#text-for-documentation-requiring-version-text) that +- That [product badges](styleguide/index.md#product-badges) are applied. +- That the GitLab [version](styleguide/index.md#text-for-documentation-requiring-version-text) that introduced the feature has been included. - That changes to headings don't affect in-app hyperlinks. - Specific [user permissions](../../user/permissions.md) are documented. - That new documents are linked from higher-level indexes, for discoverability. - Style guide is followed: - - For [directories and files](styleguide.md#work-with-directories-and-files). - - For [images](styleguide.md#images). + - For [directories and files](styleguide/index.md#work-with-directories-and-files). + - For [images](styleguide/index.md#images). -NOTE: **Note:** Merge requests that change the location of documentation must always be reviewed by a Technical Writer prior to merging. diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 01f9d9b16fb..26a1e9ec3aa 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -1,9 +1,15 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Guidelines for implementing Enterprise Edition features - **Write the code and the tests.**: As with any code, EE features should have good test coverage to prevent regressions. - **Write documentation.**: Add documentation to the `doc/` directory. Describe - the feature and include screenshots, if applicable. Indicate [what editions](documentation/styleguide.md#product-badges) + the feature and include screenshots, if applicable. Indicate [what editions](documentation/styleguide/index.md#product-badges) the feature applies to. - **Submit a MR to the `www-gitlab-com` project.**: Add the new feature to the [EE features list](https://about.gitlab.com/features/). @@ -426,6 +432,38 @@ module EE end ``` +### Code in `app/graphql/` + +EE-specific mutations, resolvers, and types should be added to +`ee/app/graphql/{mutations,resolvers,types}`. + +To override a CE mutation, resolver, or type, create the file in +`ee/app/graphql/ee/{mutations,resolvers,types}` and add new code to a +`prepended` block. + +For example, if CE has a mutation called `Mutations::Tanukis::Create` and you +wanted to add a new argument, place the EE override in +`ee/app/graphql/ee/mutations/tanukis/create.rb`: + +```ruby +module EE + module Mutations + module Tanukis + module Create + extend ActiveSupport::Concern + + prepended do + argument :name, + GraphQL::STRING_TYPE, + required: false, + description: 'Tanuki name' + end + end + end + end +end +``` + #### Using `render_if_exists` Instead of using regular `render`, we should use `render_if_exists`, which @@ -535,7 +573,7 @@ constants. #### EE parameters -We can define `params` and utilize `use` in another `params` definition to +We can define `params` and use `use` in another `params` definition to include parameters defined in EE. However, we need to define the "interface" first in CE in order for EE to override it. We don't have to do this in other places due to `prepend_if_ee`, but Grape is complex internally and we couldn't easily diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index 639759e5014..cde221aaf16 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.md @@ -184,6 +184,38 @@ If the current version is `v12p1`, and we need to create a new version for `v12p 1. Change the namespace for files under `v12p1` folder from `Latest` to `V12p1` 1. Make changes to files under the `latest` folder as needed +## Creating a new Global Search migration + +> This functionality was introduced by [#234046](https://gitlab.com/gitlab-org/gitlab/-/issues/234046). + +NOTE: **Note:** +This only supported for indices created with GitLab 13.0 or greater. + +Migrations are stored in the [`ee/elastic/migrate/`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/elastic/migrate) folder with `YYYYMMDDHHMMSS_migration_name.rb` +file name format, which is similar to Rails database migrations: + +```ruby +# frozen_string_literal: true + +class MigrationName < Elastic::Migration + # Important: Any update to the Elastic index mappings should be replicated in Elastic::Latest::Config + + def migrate + end + + # Check if the migration has completed + # Return true if completed, otherwise return false + def completed? + end +end +``` + +Applied migrations are stored in `gitlab-#{RAILS_ENV}-migrations` index. All unexecuted migrations +are applied by the [`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/app/workers/elastic/migration_worker.rb) +cron worker sequentially. + +Any update to the Elastic index mappings should be replicated in [`Elastic::Latest::Config`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/elastic/latest/config.rb). + ## Performance Monitoring ### Prometheus @@ -234,7 +266,7 @@ which is useful to diagnose why a search might be slow. ### Correlation ID and `X-Opaque-Id` Our [correlation -ID](./distributed_tracing.md#developer-guidelines-for-working-with-correlation-ids) +ID](distributed_tracing.md#developer-guidelines-for-working-with-correlation-ids) is forwarded by all requests from Rails to Elasticsearch as the [`X-Opaque-Id`](https://www.elastic.co/guide/en/elasticsearch/reference/current/tasks.html#_identifying_running_tasks) header which allows us to track any diff --git a/doc/development/emails.md b/doc/development/emails.md index de9607fef64..4b43bff0e02 100644 --- a/doc/development/emails.md +++ b/doc/development/emails.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Dealing with email in development ## Ensuring compatibility with mailer Sidekiq jobs diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index 18b606450c2..3b2f1d21463 100644 --- a/doc/development/experiment_guide/index.md +++ b/doc/development/experiment_guide/index.md @@ -1,3 +1,9 @@ +--- +stage: Growth +group: Activation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Experiment Guide Experiments can be conducted by any GitLab team, most often the teams from the [Growth Sub-department](https://about.gitlab.com/handbook/engineering/development/growth/). Experiments are not tied to releases because they will primarily target GitLab.com. @@ -32,7 +38,7 @@ addressed. ## How to create an A/B test -### Implementation +### Implement the experiment 1. Add the experiment to the `Gitlab::Experimentation::EXPERIMENTS` hash in [`experimentation.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib%2Fgitlab%2Fexperimentation.rb): @@ -44,7 +50,7 @@ addressed. # Add your experiment here: signup_flow: { environment: ::Gitlab.dev_env_or_com?, # Target environment, defaults to enabled for development and GitLab.com - tracking_category: 'Growth::Acquisition::Experiment::SignUpFlow' # Used for providing the category when setting up tracking data + tracking_category: 'Growth::Activation::Experiment::SignUpFlow' # Used for providing the category when setting up tracking data } }.freeze ``` @@ -105,8 +111,131 @@ addressed. end ``` -1. Track necessary events. See the [product analytics guide](../product_analytics/index.md) for details. -1. After the merge request is merged, use [`chatops`](../../ci/chatops/README.md) in the +### Implement the tracking events + +To determine whether the experiment is a success or not, we must implement tracking events +to acquire data for analyzing. We can send events to Snowplow via either the backend or frontend. +Read the [product analytics guide](https://about.gitlab.com/handbook/product/product-analytics-guide/) for more details. + +#### Track backend events + +The framework provides the following helper method that is available in controllers: + +```ruby +before_action do + track_experiment_event(:signup_flow, 'action', 'value') +end +``` + +Which can be tested as follows: + +```ruby +context 'when the experiment is active and the user is in the experimental group' do + before do + stub_experiment(signup_flow: true) + stub_experiment_for_user(signup_flow: true) + end + + it 'tracks an event', :snowplow do + subject + + expect_snowplow_event( + category: 'Growth::Activation::Experiment::SignUpFlow', + action: 'action', + value: 'value', + label: 'experimentation_subject_id', + property: 'experimental_group' + ) + end +end +``` + +#### Track frontend events + +The framework provides the following helper method that is available in controllers: + +```ruby +before_action do + push_frontend_experiment(:signup_flow) + frontend_experimentation_tracking_data(:signup_flow, 'action', 'value') +end +``` + +This pushes tracking data to `gon.experiments` and `gon.tracking_data`. + +```ruby +expect(Gon.experiments['signupFlow']).to eq(true) + +expect(Gon.tracking_data).to eq( + { + category: 'Growth::Activation::Experiment::SignUpFlow', + action: 'action', + value: 'value', + label: 'experimentation_subject_id', + property: 'experimental_group' + } +) +``` + +Which can then be used for tracking as follows: + +```javascript +import { isExperimentEnabled } from '~/lib/utils/experimentation'; +import Tracking from '~/tracking'; + +document.addEventListener('DOMContentLoaded', () => { + const signupFlowExperimentEnabled = isExperimentEnabled('signupFlow'); + + if (signupFlowExperimentEnabled && gon.tracking_data) { + const { category, action, ...data } = gon.tracking_data; + + Tracking.event(category, action, data); + } +} +``` + +Which can be tested in Jest as follows: + +```javascript +import { withGonExperiment } from 'helpers/experimentation_helper'; +import Tracking from '~/tracking'; + +describe('event tracking', () => { + describe('with tracking data', () => { + withGonExperiment('signupFlow'); + + beforeEach(() => { + jest.spyOn(Tracking, 'event').mockImplementation(() => {}); + + gon.tracking_data = { + category: 'Growth::Activation::Experiment::SignUpFlow', + action: 'action', + value: 'value', + label: 'experimentation_subject_id', + property: 'experimental_group' + }; + }); + + it('should track data', () => { + performAction() + + expect(Tracking.event).toHaveBeenCalledWith( + 'Growth::Activation::Experiment::SignUpFlow', + 'action', + { + value: 'value', + label: 'experimentation_subject_id', + property: 'experimental_group' + }, + ); + }); + }); +}); +``` + +### Enable the experiment + +After all merge requests have been merged, use [`chatops`](../../ci/chatops/README.md) in the [appropriate channel](../feature_flags/controls.md#communicate-the-change) to start the experiment for 10% of the users. The feature flag should have the name of the experiment with the `_experiment_percentage` suffix appended. For visibility, please also share any commands run against production in the `#s_growth` channel: @@ -121,9 +250,39 @@ For visibility, please also share any commands run against production in the `#s /chatops run feature delete signup_flow_experiment_percentage ``` -### Tests and test helpers +### Testing and test helpers + +#### RSpec + +Use the following in RSpec to mock the experiment: + +```ruby +context 'when the experiment is active' do + before do + stub_experiment(signup_flow: true) + end + + context 'when the user is in the experimental group' do + before do + stub_experiment_for_user(signup_flow: true) + end + + it { is_expected.to do_experimental_thing } + end + + context 'when the user is in the control group' do + before do + stub_experiment_for_user(signup_flow: false) + end + + it { is_expected.to do_control_thing } + end +end +``` + +#### Jest -Use the following in Jest to test the experiment is enabled. +Use the following in Jest to mock the experiment: ```javascript import { withGonExperiment } from 'helpers/experimentation_helper'; diff --git a/doc/development/fe_guide/accessibility.md b/doc/development/fe_guide/accessibility.md index 669c93eb251..8cb61019556 100644 --- a/doc/development/fe_guide/accessibility.md +++ b/doc/development/fe_guide/accessibility.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Accessibility & Readability ## Resources diff --git a/doc/development/fe_guide/architecture.md b/doc/development/fe_guide/architecture.md index c7e1ba59f23..4b45fb97c76 100644 --- a/doc/development/fe_guide/architecture.md +++ b/doc/development/fe_guide/architecture.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Architecture When you are developing a new feature that requires architectural design, or if diff --git a/doc/development/fe_guide/axios.md b/doc/development/fe_guide/axios.md index 38a8c8f1086..856b03e4b47 100644 --- a/doc/development/fe_guide/axios.md +++ b/doc/development/fe_guide/axios.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Axios We use [Axios](https://github.com/axios/axios) to communicate with the server in Vue applications and most new code. diff --git a/doc/development/fe_guide/dependencies.md b/doc/development/fe_guide/dependencies.md index ba97e7e39be..bbe4cdc285d 100644 --- a/doc/development/fe_guide/dependencies.md +++ b/doc/development/fe_guide/dependencies.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Frontend dependencies ## Package manager diff --git a/doc/development/fe_guide/design_patterns.md b/doc/development/fe_guide/design_patterns.md index 5b7b16a9a8a..ed4d91f34bd 100644 --- a/doc/development/fe_guide/design_patterns.md +++ b/doc/development/fe_guide/design_patterns.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Design Patterns ## Singletons diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md index 2b64534e7c9..915dab06ac2 100644 --- a/doc/development/fe_guide/development_process.md +++ b/doc/development/fe_guide/development_process.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Frontend Development Process You can find more about the organization of the frontend team in the [handbook](https://about.gitlab.com/handbook/engineering/frontend/). diff --git a/doc/development/fe_guide/dropdowns.md b/doc/development/fe_guide/dropdowns.md index 019bd36573d..bd2dae13c5b 100644 --- a/doc/development/fe_guide/dropdowns.md +++ b/doc/development/fe_guide/dropdowns.md @@ -1,3 +1,3 @@ --- -redirect_to: 'https://design.gitlab.com/components/dropdowns/' +redirect_to: 'https://design.gitlab.com/components/dropdown/' --- diff --git a/doc/development/fe_guide/droplab/droplab.md b/doc/development/fe_guide/droplab/droplab.md index 83bc4216403..fe0f07b3019 100644 --- a/doc/development/fe_guide/droplab/droplab.md +++ b/doc/development/fe_guide/droplab/droplab.md @@ -1,22 +1,29 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # DropLab A generic dropdown for all of your custom dropdown needs. ## Usage -DropLab can be used by simply adding a `data-dropdown-trigger` HTML attribute. -This attribute allows us to find the "trigger" _(toggle)_ for the dropdown, -whether that is a button, link or input. +DropLab can be used by adding a `data-dropdown-trigger` HTML attribute. This +attribute allows us to find the "trigger" _(toggle)_ for the dropdown, whether +it's a button, link or input. -The value of the `data-dropdown-trigger` should be a CSS selector that -DropLab can use to find the trigger's dropdown list. +The value of the `data-dropdown-trigger` should be a CSS selector that DropLab +can use to find the trigger's dropdown list. You should also add the `data-dropdown` attribute to declare the dropdown list. The value is irrelevant. -The DropLab class has no side effects, so you must always call `.init` when -the DOM is ready. `DropLab.prototype.init` takes the same arguments as `DropLab.prototype.addHook`. -If you do not provide any arguments, it will globally query and instantiate all droplab compatible dropdowns. +The DropLab class has no side effects, so you must always call `.init` when the +DOM is ready. `DropLab.prototype.init` takes the same arguments as `DropLab.prototype.addHook`. +If you don't provide any arguments, it will globally query and instantiate all +DropLab-compatible dropdowns. ```html <a href="#" data-dropdown-trigger="#list">Toggle</a> @@ -31,8 +38,8 @@ const droplab = new DropLab(); droplab.init(); ``` -As you can see, we have a "Toggle" link, that is declared as a trigger. -It provides a selector to find the dropdown list it should control. +As noted, we have a "Toggle" link that's declared as a trigger. It provides a +selector to find the dropdown list it should control. ### Static data @@ -54,8 +61,8 @@ droplab.init(); ### Explicit instantiation -You can pass the trigger and list elements as constructor arguments to return -a non-global instance of DropLab using the `DropLab.prototype.init` method. +You can pass the trigger and list elements as constructor arguments to return a +non-global instance of DropLab using the `DropLab.prototype.init` method. ```html <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a> @@ -96,12 +103,13 @@ droplab.addHook(trigger, list); ### Dynamic data -Adding `data-dynamic` to your dropdown element will enable dynamic list rendering. +Adding `data-dynamic` to your dropdown element will enable dynamic list +rendering. -You can template a list item using the keys of the data object provided. -Use the handlebars syntax `{{ value }}` to HTML escape the value. -Use the `<%= value %>` syntax to simply interpolate the value. -Use the `<%= value %>` syntax to evaluate the value. +You can template a list item using the keys of the data object provided. Use the +handlebars syntax `{{ value }}` to HTML escape the value. Use the `<%= value %>` +syntax to interpolate the value. Use the `<%= value %>` syntax to evaluate the +value. Passing an array of objects to `DropLab.prototype.addData` will render that data for all `data-dynamic` dropdown lists tracked by that DropLab instance. @@ -126,8 +134,9 @@ droplab.init().addData([{ }]); ``` -Alternatively, you can specify a specific dropdown to add this data to but passing -the data as the second argument and the `id` of the trigger element as the first argument. +Alternatively, you can specify a specific dropdown to add this data to by +passing the data as the second argument and the `id` of the trigger element as +the first argument. ```html <a href="#" data-dropdown-trigger="#list" id="trigger">Toggle</a> @@ -149,7 +158,7 @@ droplab.init().addData('trigger', [{ }]); ``` -This allows you to mix static and dynamic content with ease, even with one trigger. +This allows you to mix static and dynamic content, even with one trigger. Note the use of scoping regarding the `data-dropdown` attribute to capture both dropdown lists, one of which is dynamic. @@ -185,12 +194,13 @@ DropLab adds some CSS classes to help lower the barrier to integration. For example: -- The `droplab-item-selected` CSS class is added to items that have been selected - either by a mouse click or by enter key selection. +- The `droplab-item-selected` CSS class is added to items that have been + selected either by a mouse click or by enter key selection. - The `droplab-item-active` CSS class is added to items that have been selected using arrow key navigation. -- You can add the `droplab-item-ignore` CSS class to any item that you do not want to be selectable. For example, - an `<li class="divider"></li>` list divider element that should not be interactive. +- You can add the `droplab-item-ignore` CSS class to any item that you don't + want to be selectable. For example, an `<li class="divider"></li>` list + divider element that shouldn't be interactive. ## Internal events @@ -198,26 +208,33 @@ DropLab uses some custom events to help lower the barrier to integration. For example: -- The `click.dl` event is fired when an `li` list item has been clicked. It is also - fired when a list item has been selected with the keyboard. It is also fired when a - `HookButton` button is clicked (a registered `button` tag or `a` tag trigger). -- The `input.dl` event is fired when a `HookInput` (a registered `input` tag trigger) triggers an `input` event. -- The `mousedown.dl` event is fired when a `HookInput` triggers a `mousedown` event. +- The `click.dl` event is fired when an `li` list item has been clicked. It's + also fired when a list item has been selected with the keyboard. It's also + fired when a `HookButton` button is clicked (a registered `button` tag or `a` + tag trigger). +- The `input.dl` event is fired when a `HookInput` (a registered `input` tag + trigger) triggers an `input` event. +- The `mousedown.dl` event is fired when a `HookInput` triggers a `mousedown` + event. - The `keyup.dl` event is fired when a `HookInput` triggers a `keyup` event. - The `keydown.dl` event is fired when a `HookInput` triggers a `keydown` event. -These custom events add a `detail` object to the vanilla `Event` object that provides some potentially useful data. +These custom events add a `detail` object to the vanilla `Event` object that +provides some potentially useful data. ## Plugins -Plugins are objects that are registered to be executed when a hook is added (when a droplab trigger and dropdown are instantiated). +Plugins are objects that are registered to be executed when a hook is added (when +a DropLab trigger and dropdown are instantiated). -If no modules API is detected, the library will fall back as it does with `window.DropLab` and will add `window.DropLab.plugins.PluginName`. +If no modules API is detected, the library will fall back as it does with +`window.DropLab` and will add `window.DropLab.plugins.PluginName`. ### Usage -To use plugins, you can pass them in an array as the third argument of `DropLab.prototype.init` or `DropLab.prototype.addHook`. -Some plugins require configuration values, the config object can be passed as the fourth argument. +To use plugins, you can pass them in an array as the third argument of +`DropLab.prototype.init` or `DropLab.prototype.addHook`. Some plugins require +configuration values; the config object can be passed as the fourth argument. ```html <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a> @@ -240,14 +257,13 @@ droplab.init(trigger, list, [droplabAjax], { ### Documentation -- [Ajax plugin](plugins/ajax.md) -- [Filter plugin](plugins/filter.md) -- [InputSetter plugin](plugins/input_setter.md) +Refer to the list of available [DropLab plugins](plugins/index.md) for +information about their use. ### Development -When plugins are initialised for a droplab trigger+dropdown, DropLab will -call the plugins `init` function, so this must be implemented in the plugin. +When plugins are initialised for a DropLab trigger+dropdown, DropLab calls the +plugins' `init` function, so this must be implemented in the plugin. ```javascript class MyPlugin { diff --git a/doc/development/fe_guide/droplab/plugins/ajax.md b/doc/development/fe_guide/droplab/plugins/ajax.md index f22d95064dd..3ac876ad062 100644 --- a/doc/development/fe_guide/droplab/plugins/ajax.md +++ b/doc/development/fe_guide/droplab/plugins/ajax.md @@ -1,17 +1,25 @@ -# Ajax +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- -`Ajax` is a droplab plugin that allows for retrieving and rendering list data from a server. +# Ajax plugin + +`Ajax` is a DropLab plugin that allows for retrieving and rendering list data +from a server. ## Usage -Add the `Ajax` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call. +Add the `Ajax` object to the plugins array of a `DropLab.prototype.init` or +`DropLab.prototype.addHook` call. -`Ajax` requires 2 configuration values, the `endpoint` and `method`. +`Ajax` requires 2 configuration values: the `endpoint` and `method`. -- `endpoint` should be a URL to the request endpoint. -- `method` should be `setData` or `addData`. -- `setData` completely replaces the dropdown with the response data. -- `addData` appends the response data to the current dropdown list. +- `endpoint`: Should be a URL to the request endpoint. +- `method`: Should be `setData` or `addData`. +- `setData`: Completely replaces the dropdown with the response data. +- `addData`: Appends the response data to the current dropdown list. ```html <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a> @@ -32,7 +40,7 @@ droplab.addHook(trigger, list, [Ajax], { }); ``` -Optionally you can set `loadingTemplate` to a HTML string. This HTML string will -replace the dropdown list while the request is pending. +Optionally, you can set `loadingTemplate` to a HTML string. This HTML string +replaces the dropdown list while the request is pending. Additionally, you can set `onError` to a function to catch any XHR errors. diff --git a/doc/development/fe_guide/droplab/plugins/filter.md b/doc/development/fe_guide/droplab/plugins/filter.md index e8194e45a41..9ab4946d21d 100644 --- a/doc/development/fe_guide/droplab/plugins/filter.md +++ b/doc/development/fe_guide/droplab/plugins/filter.md @@ -1,15 +1,22 @@ -# Filter +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- -`Filter` is a plugin that allows for filtering data that has been added +# Filter plugin + +`Filter` is a DropLab plugin that allows for filtering data that has been added to the dropdown using a simple fuzzy string search of an input value. ## Usage -Add the `Filter` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call. +Add the `Filter` object to the plugins array of a `DropLab.prototype.init` or +`DropLab.prototype.addHook` call. -- `Filter` requires a configuration value for `template`. -- `template` should be the key of the objects within your data array that you want to compare - to the user input string, for filtering. +- `Filter`: Requires a configuration value for `template`. +- `template`: Should be the key of the objects within your data array that you + want to compare to the user input string, for filtering. ```html <input href="#" id="trigger" data-dropdown-trigger="#list"> @@ -39,8 +46,10 @@ droplab.addData('trigger', [{ }]); ``` -Above, the input string will be compared against the `test` key of the passed data objects. +In the previous code, the input string is compared against the `test` key of the +passed data objects. -Optionally you can set `filterFunction` to a function. This function will be used instead -of `Filter`'s built in string search. `filterFunction` is passed 2 arguments, the first -is one of the data objects, the second is the current input value. +Optionally you can set `filterFunction` to a function. This function will be +used instead of `Filter`'s built-in string search. `filterFunction` is passed +two arguments: the first is one of the data objects, and the second is the +current input value. diff --git a/doc/development/fe_guide/droplab/plugins/index.md b/doc/development/fe_guide/droplab/plugins/index.md new file mode 100644 index 00000000000..d44670bfb3c --- /dev/null +++ b/doc/development/fe_guide/droplab/plugins/index.md @@ -0,0 +1,14 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +description: A list of DropLab plugins. +--- + +# DropLab plugins + +The following plugins are available for use with [DropLab](../droplab.md): + +- [Ajax plugin](ajax.md) +- [Filter plugin](filter.md) +- [InputSetter plugin](input_setter.md) diff --git a/doc/development/fe_guide/droplab/plugins/input_setter.md b/doc/development/fe_guide/droplab/plugins/input_setter.md index b873b7a14ee..ab8a5cebd08 100644 --- a/doc/development/fe_guide/droplab/plugins/input_setter.md +++ b/doc/development/fe_guide/droplab/plugins/input_setter.md @@ -1,17 +1,26 @@ -# InputSetter +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- -`InputSetter` is a plugin that allows for updating DOM out of the scope of droplab when a list item is clicked. +# InputSetter plugin + +`InputSetter` is a DropLab plugin that allows for updating DOM out of the scope +of DropLab when a list item is clicked. ## Usage -Add the `InputSetter` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call. +Add the `InputSetter` object to the plugins array of a `DropLab.prototype.init` +or `DropLab.prototype.addHook` call. -- `InputSetter` requires a configuration value for `input` and `valueAttribute`. -- `input` should be the DOM element that you want to manipulate. -- `valueAttribute` should be a string that is the name of an attribute on your list items that is used to get the value - to update the `input` element with. +- `InputSetter`: Requires a configuration value for `input` and `valueAttribute`. +- `input`: The DOM element that you want to manipulate. +- `valueAttribute`: A string that's the name of an attribute on your list items + that's used to get the value to update the `input` element with. -You can also set the `InputSetter` configuration to an array of objects, which will allow you to update multiple elements. +You can also set the `InputSetter` configuration to an array of objects, which +allows you to update multiple elements. ```html <input id="input" value=""> @@ -52,9 +61,12 @@ droplab.addData('trigger', [{ }]); ``` -Above, if the second list item was clicked, it would update the `#input` element -to have a `value` of `1`, it would also update the `#div` element's `data-selected-id` to `1`. +In the previous code, if the second list item was clicked, it would update the +`#input` element to have a `value` of `1`, it would also update the `#div` +element's `data-selected-id` to `1`. -Optionally you can set `inputAttribute` to a string that is the name of an attribute on your `input` element that you want to update. -If you do not provide an `inputAttribute`, `InputSetter` will update the `value` of the `input` element if it is an `INPUT` element, -or the `textContent` of the `input` element if it is not an `INPUT` element. +Optionally, you can set `inputAttribute` to a string that's the name of an +attribute on your `input` element that you want to update. If you don't provide +an `inputAttribute`, `InputSetter` will update the `value` of the `input` +element if it's an `INPUT` element, or the `textContent` of the `input` element +if it isn't an `INPUT` element. diff --git a/doc/development/fe_guide/editor_lite.md b/doc/development/fe_guide/editor_lite.md new file mode 100644 index 00000000000..eb5852d258d --- /dev/null +++ b/doc/development/fe_guide/editor_lite.md @@ -0,0 +1,224 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Editor Lite + +## Background + +**Editor Lite** is a technological product driving [Web Editor](../../user/project/repository/web_editor.md), [Snippets](../../user/snippets.md), [CI Linter](../../ci/lint.md), etc. Editor Lite is the driving technology for any single-file editing experience across the product. + +Editor Lite is a thin wrapper around [the Monaco editor](https://microsoft.github.io/monaco-editor/index.html) that provides the necessary helpers and abstractions and extends Monaco using extensions. + +## How to use Editor Lite + +Editor Lite is framework-agnostic and can be used in any application, whether it's Rails or Vue. For the convenience of integration, we have [the dedicated `<editor-lite>` Vue component](#vue-component), but in general, the integration of Editor Lite is pretty straightforward: + +1. Import Editor Lite: + +```javascript +import EditorLite from '~/editor/editor_lite'; +``` + +1. Initialize global editor for the view: + +```javascript +const editor = new EditorLite({ + // Editor Options. + // The list of all accepted options can be found at + // https://microsoft.github.io/monaco-editor/api/enums/monaco.editor.editoroption.html +}); +``` + +1. Create an editor's instance: + +```javascript +editor.createInstance({ + // Editor Lite configuration options. +}) +``` + +An instance of Editor Lite accepts the following configuration options: + +| Option | Required? | Description | +| ---- | ---- | ---- | +| `el` | `true` | `HTML Node`: element on which to render the editor | +| `blobPath` | `false` | `String`: the name of a file to render in the editor. It is used to identify the correct syntax highlighter to use with that or another file type. Can accept wildcard as in `*.js` when the actual filename isn't known or doesn't play any role | +| `blobContent` | `false` | `String`: the initial content to be rendered in the editor | +| `extensions` | `false` | `Array`: extensions to use in this instance | +| `blobGlobalId` | `false` | `String`: auto-generated property.<br>**Note:** this prop might go away in the future. Do not pass `blobGlobalId` unless you know what you're doing.| +| [Editor Options](https://microsoft.github.io/monaco-editor/api/enums/monaco.editor.editoroption.html) | `false` | `Object(s)`: any prop outside of the list above is treated as an Editor Option for this particular instance. This way, one can override global Editor Options on the instance level. | + +## API + +The editor follows the same public API as [provided by Monaco editor](https://microsoft.github.io/monaco-editor/api/interfaces/monaco.editor.istandalonecodeeditor.html) with just a few additional functions on the instance level: + +| Function | Arguments | Description +| ----- | ----- | ----- | +| `updateModelLanguage` | `path`: String | Updates the instance's syntax highlighting to follow the extension of the passed `path`. Available only on _instance_ level| +| `use` | Array of objects | Array of **extensions** to apply to the instance. Accepts only the array of _objects_, which means that the extensions' ES6 modules should be fetched and resolved in your views/components before being passed to `use`. This prop is available on _instance_ (applies extension to this particular instance) and _global edtor_ (applies the same extension to all instances) levels. | +| Monaco Editor options | See [documentation](https://microsoft.github.io/monaco-editor/api/interfaces/monaco.editor.istandalonecodeeditor.html) | Default Monaco editor options | + +## Tips + +1. Editor's loading state. + +Editor Lite comes with the loading state built-in, making spinners and loaders rarely needed in HTML. To benefit the built-in loading state, set the `data-editor-loading` property on the HTML element that is supposed to contain the editor. Editor Lite will show the loader automatically while it's bootstrapping. + + +1. Update syntax highlighting if the file name changes. + +```javascript +// fileNameEl here is the HTML input element that contains the file name +fileNameEl.addEventListener('change', () => { + this.editor.updateModelLanguage(fileNameEl.value); +}); +``` + +1. Get the editor's content. + +We might set up listeners on the editor for every change but it rapidly can become an expensive operation. Instead , we can get editor's content when it's needed. For example on a form's submission: + +```javascript +form.addEventListener('submit', () => { + my_content_variable = this.editor.getValue(); +}); +``` + +1. Performance + +Even though Editor Lite itself is extremely slim, it still depends on Monaco editor. Monaco is not an easily tree-shakeable module. Hence, every time you add Editor Lite to a view, the JavaScript bundle's size significantly increases, affecting your view's loading performance. To avoid that, it is recommended to import the editor on demand on those views where it is not 100% certain that the editor will be used. Or if the editor is a secondary element of the view. Loading Editor Lite on demand is no different from loading any other module: + +```javascript +someActionFunction() { + import(/* webpackChunkName: 'EditorLite' */ '~/editor/editor_lite'). + then(({ default: EditorLite }) => { + const editor = new EditorLite(); + ... + }); + ... +} +``` + +## Extensions + +Editor Lite has been built to provide a universal, extensible editing tool to the whole product, which would not depend on any particular group. Even though the Editor Lite's core is owned by [Create::Editor FE Team](https://about.gitlab.com/handbook/engineering/development/dev/create-editor-fe/), the main functional elements — extensions — can be owned by any group. Editor Lite extensions' main idea is that the core of the editor remains very slim and stable. At the same time, whatever new functionality is needed can be added as an extension to this core, without touching the core itself. It allows any group to build and own any new editing functionality without being afraid of it being broken or overridden with the Editor Lite changes. + +Structurally, the complete implementation of Editor Lite could be presented as the following diagram: + +```mermaid +graph TD; + B[Extension 1]---A[Editor Lite] + C[Extension 2]---A[Editor Lite] + D[Extension 3]---A[Editor Lite] + E[...]---A[Editor Lite] + F[Extension N]---A[Editor Lite] + A[Editor Lite]---Z[Monaco] +``` + +Technically, an extension is just an ES6 module that exports a JavaScript object: + +```javascript +import { Position } from 'monaco-editor'; + +export default { + navigateFileStart() { + this.setPosition(new Position(1, 1)); + }, +}; + +``` + +Important things to note here: + +- We can depend on other modules in our extensions. This organization helps keep the size of Editor Lite's core at bay by importing dependencies only when needed. +- `this` in extension's functions refers to the current Editor Lite instance. Using `this`, you get access to the complete instance's API, such as the `setPosition()` method in this particular case. + +### Using an existing extension + +Adding an extension to Editor Lite's instance is simple: + +```javascript +import EditorLite from '~/editor/editor_lite'; +import MyExtension from '~/my_extension'; + +const editor = new EditorLite().createInstance({ + ... +}); +editor.use(MyExtension); +``` + +### Creating an extension + +Let's create our first Editor Lite extension. As aforementioned, extensions are ES6 modules exporting the simple `Object` that is used to extend Editor Lite's functionality. As the most straightforward test, let's create an extension that extends Editor Lite with a new function that, when called, will output editor's content in `alert`. + +`~/my_folder/my_fancy_extension.js:` + +```javascript +export default { + throwContentAtMe() { + alert(this.getValue()); + }, +}; +``` + +And that's it with our extension! Note that we're using `this` as a reference to the instance. And through it, we get access to the complete underlying [Monaco editor API](https://microsoft.github.io/monaco-editor/api/interfaces/monaco.editor.istandalonecodeeditor.html) like `getValue()` in this case. + +Now let's use our extension: + +`~/my_folder/component_bundle.js`: + +```javascript +import EditorLite from '~/editor/editor_lite'; +import MyFancyExtension from './my_fancy_extension'; + +const editor = new EditorLite().createInstance({ + ... +}); +editor.use(MyFancyExtension); +... +someButton.addEventListener('click', () => { + editor.throwContentAtMe(); +}); +``` + +First of all, we import Editor Lite and our new extension. Then we create the editor and its instance. By default Editor Lite has no `throwContentAtMe` method. But the `editor.use(MyFancyExtension)` line brings that method to our instance. After that, we can use it any time we need it. In this case, we call it when some theoretical button has been clicked. + +This script would result in an alert containing the editor's content when `someButton` is clicked. + + + +### Tips + +1. Performance + +Just like Editor Lite itself, any extension can be loaded on demand to not harm loading performance of the views: + +```javascript +const EditorPromise = import( + /* webpackChunkName: 'EditorLite' */ '~/editor/editor_lite' +); +const MarkdownExtensionPromise = import('~/editor/editor_markdown_ext'); + +Promise.all([EditorPromise, MarkdownExtensionPromise]) + .then(([{ default: EditorLite }, { default: MarkdownExtension }]) => { + const editor = new EditorLite().createInstance({ + ... + }); + editor.use(MarkdownExtension); + }); +``` + +1. Using multiple extensions + +Just pass the array of extensions to your `use` method: + +```javascript +editor.use([FileTemplateExtension, MyFancyExtension]); +``` + +## <a id="vue-component"></a>`<editor-lite>` Vue component + +TBD diff --git a/doc/development/fe_guide/emojis.md b/doc/development/fe_guide/emojis.md index 3cd14c0dfd3..9b1abaa14ae 100644 --- a/doc/development/fe_guide/emojis.md +++ b/doc/development/fe_guide/emojis.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Emojis GitLab supports native Unicode emojis and falls back to image-based emojis selectively diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md index 0a26fdba934..22a48c8f9f9 100644 --- a/doc/development/fe_guide/frontend_faq.md +++ b/doc/development/fe_guide/frontend_faq.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Frontend FAQ ## Rules of Frontend FAQ @@ -63,7 +69,7 @@ banner on top of the component examples indicates that: > component. For example, at the time of writing, this type of warning can be observed for -[all form components](https://design.gitlab.com/components/forms/). It, however, +[all form components](https://design.gitlab.com/components/form/). It, however, doesn't imply that the component should not be used. GitLab always asks to use `<gl-*>` components whenever a suitable component exists. @@ -174,10 +180,9 @@ which adds the appropriate `core-js` polyfills once for each JavaScript feature we're using that our target browsers don't support. You don't need to add `core-js` polyfills manually. -NOTE: **Note:** -GitLab still manually adds non-`core-js` polyfills for extending browser features -(such as GitLab's SVG polyfill) that allow us reference SVGs by using `<use xlink:href>`. -These polyfills should be added to `app/assets/javascripts/commons/polyfills.js`. +GitLab adds non-`core-js` polyfills for extending browser features (such as +GitLab's SVG polyfill), which allow us to reference SVGs by using `<use xlink:href>`. +Be sure to add these polyfills to `app/assets/javascripts/commons/polyfills.js`. To see what polyfills are being used: diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index ad3958d4496..cae2435e4ff 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -664,7 +664,9 @@ it('calls mutation on submitting form ', () => { ### Testing with mocked Apollo Client -To test the logic of Apollo cache updates, we might want to mock an Apollo Client in our unit tests. To separate tests with mocked client from 'usual' unit tests, it's recommended to create an additional component factory. This way we only create Apollo Client instance when it's necessary: +To test the logic of Apollo cache updates, we might want to mock an Apollo Client in our unit tests. We use [`mock-apollo-client`](https://www.npmjs.com/package/mock-apollo-client) library to mock Apollo client and [`createMockApollo` helper](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/frontend/helpers/mock_apollo_helper.js) we created on top of it. + +To separate tests with mocked client from 'usual' unit tests, it's recommended to create an additional component factory. This way we only create Apollo Client instance when it's necessary: ```javascript function createComponent() {...} @@ -672,12 +674,6 @@ function createComponent() {...} function createComponentWithApollo() {...} ``` -We use [`mock-apollo-client`](https://www.npmjs.com/package/mock-apollo-client) library to mock Apollo client in tests. - -```javascript -import { createMockClient } from 'mock-apollo-client'; -``` - Then we need to inject `VueApollo` to Vue local instance (`localVue.use()` can also be called within `createComponentWithApollo()`) ```javascript @@ -741,8 +737,8 @@ describe('Some component with Apollo mock', () => { }) ``` -NOTE: **Note:** -When mocking resolved values, make sure the structure of the response is the same as actual API response: i.e. root property should be `data` for example +When mocking resolved values, ensure the structure of the response is the same +as the actual API response. For example, root property should be `data`. When testing queries, please keep in mind they are promises, so they need to be _resolved_ to render a result. Without resolving, we can check the `loading` state of the query: @@ -830,6 +826,53 @@ it('calls a mutation with correct parameters and reorders designs', async () => }); ``` +#### Testing `@client` queries + +If your application contains `@client` queries, most probably you will have an Apollo Client warning saying that you have a local query but no resolvers are defined. In order to fix it, you need to pass resolvers to the mocked client with a second parameter (bare minimum is an empty object): + +```javascript +import createMockApollo from 'jest/helpers/mock_apollo_helper'; +... +fakeApollo = createMockApollo(requestHandlers, {}); +``` + +Sometimes we want to test a `result` hook of the local query. In order to have it triggered, we need to populate a cache with correct data to be fetched with this query: + +```javascript +query fetchLocalUser { + fetchLocalUser @client { + name + } +} +``` + +```javascript +import fetchLocalUserQuery from '~/design_management/graphql/queries/fetch_local_user.query.graphql'; + +function createComponentWithApollo() { + const requestHandlers = [ + [getDesignListQuery, jest.fn().mockResolvedValue(designListQueryResponse)], + [permissionsQuery, jest.fn().mockResolvedValue(permissionsQueryResponse)], + ]; + + fakeApollo = createMockApollo(requestHandlers, {}); + fakeApollo.clients.defaultClient.cache.writeQuery({ + query: fetchLocalUserQuery, + data: { + fetchLocalUser: { + __typename: 'User', + name: 'Test', + }, + }, + }) + + wrapper = shallowMount(Index, { + localVue, + apolloProvider: fakeApollo, + }); +} +``` + ## Handling errors GitLab's GraphQL mutations currently have two distinct error modes: [Top-level](#top-level-errors) and [errors-as-data](#errors-as-data). @@ -910,3 +953,99 @@ const defaultClient = createDefaultClient( }, ); ``` + +## Making initial queries early with GraphQL startup calls + +To improve performance, sometimes we want to make initial GraphQL queries early. In order to do this, we can add them to **startup calls** with the following steps: + +- Move all the queries you need initially in your application to `app/graphql/queries`; +- Add `__typename` property to every nested query level: + + ```javascript + query getPermissions($projectPath: ID!) { + project(fullPath: $projectPath) { + __typename + userPermissions { + __typename + pushCode + forkProject + createMergeRequestIn + } + } + } + ``` + +- If queries contain fragments, you need to move fragments to the query file directly instead of importing them: + + ```javascript + fragment PageInfo on PageInfo { + __typename + hasNextPage + hasPreviousPage + startCursor + endCursor + } + + query getFiles( + $projectPath: ID! + $path: String + $ref: String! + ) { + project(fullPath: $projectPath) { + __typename + repository { + __typename + tree(path: $path, ref: $ref) { + __typename + pageInfo { + ...PageInfo + } + } + } + } + } + } + ``` + +- If the fragment is used only once, we can also remove the fragment altogether: + + ```javascript + query getFiles( + $projectPath: ID! + $path: String + $ref: String! + ) { + project(fullPath: $projectPath) { + __typename + repository { + __typename + tree(path: $path, ref: $ref) { + __typename + pageInfo { + __typename + hasNextPage + hasPreviousPage + startCursor + endCursor + } + } + } + } + } + } + ``` + +- Add startup call(s) with correct variables to the HAML file that serves as a view +for your application. To add GraphQL startup calls, we use +`add_page_startup_graphql_call` helper where the first parameter is a path to the +query, the second one is an object containing query variables. Path to the query is +relative to `app/graphql/queries` folder: for example, if we need a +`app/graphql/queries/repository/files.query.graphql` query, the path will be +`repository/files`. + + ```yaml + - current_route_path = request.fullpath.match(/-\/tree\/[^\/]+\/(.+$)/).to_a[1] + - add_page_startup_graphql_call('repository/path_last_commit', { projectPath: @project.full_path, ref: current_ref, path: current_route_path || "" }) + - add_page_startup_graphql_call('repository/permissions', { projectPath: @project.full_path }) + - add_page_startup_graphql_call('repository/files', { nextPageCursor: "", pageSize: 100, projectPath: @project.full_path, ref: current_ref, path: current_route_path || "/"}) + ``` diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md index 67add5709d9..994a3aa36fc 100644 --- a/doc/development/fe_guide/icons.md +++ b/doc/development/fe_guide/icons.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Icons and SVG Illustrations We manage our own icon and illustration library in the [`gitlab-svgs`](https://gitlab.com/gitlab-org/gitlab-svgs) @@ -84,7 +90,7 @@ Please use the following function inside JS to render an icon: ### Usage in HAML/Rails -DANGER: **Danger:** +DANGER: **Warning:** Do not use the `spinner` or `icon('spinner spin')` rails helpers to insert loading icons. These helpers rely on the Font Awesome icon library which is deprecated. diff --git a/doc/development/fe_guide/img/editor_lite_create_ext.png b/doc/development/fe_guide/img/editor_lite_create_ext.png Binary files differnew file mode 100644 index 00000000000..73941cf5d62 --- /dev/null +++ b/doc/development/fe_guide/img/editor_lite_create_ext.png diff --git a/doc/development/fe_guide/img/editor_lite_loading.png b/doc/development/fe_guide/img/editor_lite_loading.png Binary files differnew file mode 100644 index 00000000000..f2c242da155 --- /dev/null +++ b/doc/development/fe_guide/img/editor_lite_loading.png diff --git a/doc/development/fe_guide/img/gl-modal.png b/doc/development/fe_guide/img/gl-modal.png Binary files differdeleted file mode 100644 index b2d2d637e57..00000000000 --- a/doc/development/fe_guide/img/gl-modal.png +++ /dev/null diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index f909866d44e..9f98876bc8e 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Frontend Development Guidelines This document describes various guidelines to ensure consistency and quality diff --git a/doc/development/fe_guide/keyboard_shortcuts.md b/doc/development/fe_guide/keyboard_shortcuts.md index da9b3702a8d..227b5cfd22c 100644 --- a/doc/development/fe_guide/keyboard_shortcuts.md +++ b/doc/development/fe_guide/keyboard_shortcuts.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Implementing keyboard shortcuts We use [Mousetrap](https://craig.is/killing/mice) to implement keyboard diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index 5d2b699c40d..de9a9f5cb14 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Performance ## Best Practices @@ -71,9 +77,8 @@ controller with the `index` action. If a corresponding file exists at `pages/projects/issues/index/index.js`, it will be compiled into a webpack bundle and included on the page. -NOTE: **Note:** -Previously we had encouraged the use of -`content_for :page_specific_javascripts` within haml files, along with +Previously, GitLab encouraged the use of +`content_for :page_specific_javascripts` within HAML files, along with manually generated webpack bundles. However under this new system you should not ever need to manually add an entry point to the `webpack.config.js` file. @@ -91,17 +96,55 @@ browser's developer console while on any page within GitLab. modules outside of the entry point script. Just import, read the DOM, instantiate, and nothing else. -- **Entry Points May Be Asynchronous:** - _DO NOT ASSUME_ that the DOM has been fully loaded and available when an - entry point script is run. If you require that some code be run after the - DOM has loaded, you should attach an event handler to the `DOMContentLoaded` - event with: +- **`DOMContentLoaded` should not be used:** + All of GitLab's JavaScript files are added with the `defer` attribute. + According to the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-defer), + this implies that "the script is meant to be executed after the document has + been parsed, but before firing `DOMContentLoaded`". Since the document is already + parsed, `DOMContentLoaded` is not needed to bootstrap applications because all + the DOM nodes are already at our disposal. + +- **JavaScript that relies on CSS for calculations should use [`waitForCSSLoaded()`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/helpers/startup_css_helper.js#L34):** + GitLab uses [Startup.css](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38052) + to improve page performance. This can cause issues if JavaScript relies on CSS + for calculations. To fix this the JavaScript can be wrapped in the + [`waitForCSSLoaded()`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/helpers/startup_css_helper.js#L34) + helper function. ```javascript import initMyWidget from './my_widget'; + import { waitForCSSLoaded } from '~/helpers/startup_css_helper'; - document.addEventListener('DOMContentLoaded', () => { - initMyWidget(); + waitForCSSLoaded(initMyWidget); + ``` + + Note that `waitForCSSLoaded()` methods supports receiving the action in different ways: + + - With a callback: + + ```javascript + waitForCSSLoaded(action) + ``` + + - With `then()`: + + ```javascript + waitForCSSLoaded().then(action); + ``` + + - With `await` followed by `action`: + + ```javascript + await waitForCSSLoaded; + action(); + ``` + + For example, see how we use this in [app/assets/javascripts/pages/projects/graphs/charts/index.js](https://gitlab.com/gitlab-org/gitlab/-/commit/5e90885d6afd4497002df55bf015b338efcfc3c5#02e81de37f5b1716a3ef3222fa7f7edf22c40969_9_8): + + ```javascript + waitForCSSLoaded(() => { + const languagesContainer = document.getElementById('js-languages-chart'); + //... }); ``` diff --git a/doc/development/fe_guide/principles.md b/doc/development/fe_guide/principles.md index 2bef48fddcf..75954a5f988 100644 --- a/doc/development/fe_guide/principles.md +++ b/doc/development/fe_guide/principles.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Principles These principles will ensure that your frontend contribution starts off in the right direction. diff --git a/doc/development/fe_guide/security.md b/doc/development/fe_guide/security.md index a001dd83ab7..a82c315032f 100644 --- a/doc/development/fe_guide/security.md +++ b/doc/development/fe_guide/security.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Security ## Resources @@ -77,3 +83,25 @@ inject scripts into the web app. Inline styles should be avoided in almost all cases, they should only be used when no alternatives can be found. This allows reusability of styles as well as readability. + +### Sanitize HTML output + +If you need to output raw HTML, you should sanitize it. + +If you are using Vue, you can use the[`v-safe-html` directive](https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/directives-safe-html-directive--default) from GitLab UI. + +For other use cases, wrap a preconfigured version of [`dompurify`](https://www.npmjs.com/package/dompurify) +that also allows the icons to be rendered: + +```javascript +import { sanitize } from '~/lib/dompurify'; + +const unsafeHtml = '<some unsafe content ... >'; + +// ... + +element.appendChild(sanitize(unsafeHtml)); +``` + +This `sanitize` function takes the same configuration as the +original. diff --git a/doc/development/fe_guide/style/html.md b/doc/development/fe_guide/style/html.md index 1445da3f0e1..61a724cf3c7 100644 --- a/doc/development/fe_guide/style/html.md +++ b/doc/development/fe_guide/style/html.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # HTML style guide ## Buttons diff --git a/doc/development/fe_guide/style/index.md b/doc/development/fe_guide/style/index.md index 4ca409664de..0d73b16b5d3 100644 --- a/doc/development/fe_guide/style/index.md +++ b/doc/development/fe_guide/style/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab development style guides See below for the relevant style guides, guidelines, linting, and other information for developing GitLab. diff --git a/doc/development/fe_guide/style/javascript.md b/doc/development/fe_guide/style/javascript.md index 2a06a473878..b8e7429eb2c 100644 --- a/doc/development/fe_guide/style/javascript.md +++ b/doc/development/fe_guide/style/javascript.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers disqus_identifier: 'https://docs.gitlab.com/ee/development/fe_guide/style_guide_js.html' --- @@ -138,7 +141,7 @@ module.exports = SomeClass; export default SomeClass; ``` -_Note:_ We still use `require` in `scripts/` and `config/` files. +We still use `require` in `scripts/` and `config/` files. ## Absolute vs relative paths for modules diff --git a/doc/development/fe_guide/style/scss.md b/doc/development/fe_guide/style/scss.md index dba39eeb98c..c6ee1e64a80 100644 --- a/doc/development/fe_guide/style/scss.md +++ b/doc/development/fe_guide/style/scss.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers disqus_identifier: 'https://docs.gitlab.com/ee/development/fe_guide/style_guide_scss.html' --- @@ -46,11 +49,6 @@ We recommend a "utility-first" approach. This encourages an organic growth of component classes and prevents the creation of one-off unreusable classes. Also, the kind of classes that emerge from "utility-first" tend to be design-centered (e.g. `.button`, `.alert`, `.card`) rather than domain-centered (e.g. `.security-report-widget`, `.commit-header-icon`). -Examples of component classes that were created using "utility-first" include: - -- [`.circle-icon-container`](https://gitlab.com/gitlab-org/gitlab/blob/579fa8b8ec7eb38d40c96521f517c9dab8c3b97a/app/assets/stylesheets/framework/icons.scss#L85) -- [`.d-flex-center`](https://gitlab.com/gitlab-org/gitlab/blob/900083d89cd6af391d26ab7922b3f64fa2839bef/app/assets/stylesheets/framework/common.scss#L425) - Inspiration: - <https://tailwindcss.com/docs/utility-first> diff --git a/doc/development/fe_guide/style/vue.md b/doc/development/fe_guide/style/vue.md index 1a64db443bc..6b6ca9a6c71 100644 --- a/doc/development/fe_guide/style/vue.md +++ b/doc/development/fe_guide/style/vue.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Vue.js style guide ## Linting @@ -51,6 +57,66 @@ Please check this [rules](https://github.com/vuejs/eslint-plugin-vue#bulb-rules) 1. Use `.vue` for Vue templates. Do not use `%template` in HAML. +1. Explicitly define data being passed into the Vue app + + ```javascript + // bad + return new Vue({ + el: '#element', + components: { + componentName + }, + provide: { + ...someDataset + }, + props: { + ...anotherDataset + }, + render: createElement => createElement('component-name'), + })); + + // good + const { foobar, barfoo } = someDataset; + const { foo, bar } = anotherDataset; + + return new Vue({ + el: '#element', + components: { + componentName + }, + provide: { + foobar, + barfoo + }, + props: { + foo, + bar + }, + render: createElement => createElement('component-name'), + })); + ``` + + We discourage the use of the spread operator in this specific case in + order to keep our codebase explicit, discoverable, and searchable. + This applies in any place where we'll benefit from the above, such as + when [initializing Vuex state](../vuex.md#why-not-just-spread-the-initial-state). + The pattern above also enables us to easily parse non scalar values during + instantiation. + + ```javascript + return new Vue({ + el: '#element', + components: { + componentName + }, + props: { + foo, + bar: parseBoolean(bar) + }, + render: createElement => createElement('component-name'), + })); + ``` + ## Naming 1. **Extensions**: Use `.vue` extension for Vue components. Do not use `.js` as file extension ([#34371](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34371)). @@ -184,7 +250,7 @@ Please check this [rules](https://github.com/vuejs/eslint-plugin-vue#bulb-rules) ``` 1. Default key should be provided if the prop is not required. - _Note:_ There are some scenarios where we need to check for the existence of the property. + There are some scenarios where we need to check for the existence of the property. On those a default key should not be provided. ```javascript @@ -400,6 +466,199 @@ Useful links: $('span').tooltip('_fixTitle'); ``` +## Vue testing + +Over time, a number of programming patterns and style preferences have emerged in our efforts to effectively test Vue components. +The following guide describes some of these. **These are not strict guidelines**, but rather a collection of suggestions and +good practices that aim to provide insight into how we write Vue tests at GitLab. + +### Mounting a component + +Typically, when testing a Vue component, the component should be "re-mounted" in every test block. + +To achieve this: + +1. Create a mutable `wrapper` variable inside the top-level `describe` block. +1. Mount the component using [`mount`](https://vue-test-utils.vuejs.org/api/#mount)/[`shallowMount`](https://vue-test-utils.vuejs.org/api/#shallowMount). +1. Reassign the resulting [`Wrapper`](https://vue-test-utils.vuejs.org/api/wrapper/#wrapper) instance to our `wrapper` variable. + +Creating a global, mutable wrapper provides a number of advantages, including the ability to: + +- Define common functions for finding components/DOM elements: + + ```javascript + import MyComponent from '~/path/to/my_component.vue'; + describe('MyComponent', () => { + let wrapper; + + // this can now be reused across tests + const findMyComponent = wrapper.find(MyComponent); + // ... + }) + ``` + +- Use a `beforeEach` block to mount the component (see [the `createComponent` factory](#the-createcomponent-factory) for more information). +- Use an `afterEach` block to destroy the component, for example, `wrapper.destroy()`. + +#### The `createComponent` factory + +To avoid duplicating our mounting logic, it's useful to define a `createComponent` factory function +that we can reuse in each test block. This is a closure which should reassign our `wrapper` variable +to the result of [`mount`](https://vue-test-utils.vuejs.org/api/#mount) and [`shallowMount`](https://vue-test-utils.vuejs.org/api/#shallowMount): + +```javascript +import MyComponent from '~/path/to/my_component.vue'; +import { shallowMount } from '@vue/test-utils'; + +describe('MyComponent', () => { + // Initiate the "global" wrapper variable. This will be used throughout our test: + let wrapper; + + // Define our `createComponent` factory: + function createComponent() { + // Mount component and reassign `wrapper`: + wrapper = shallowMount(MyComponent); + } + + it('mounts', () => { + createComponent(); + + expect(wrapper.exists()).toBe(true); + }); + + it('`isLoading` prop defaults to `false`', () => { + createComponent(); + + expect(wrapper.props('isLoading')).toBe(false); + }); +}) +``` + +Similarly, we could further de-duplicate our test by calling `createComponent` in a `beforeEach` block: + +```javascript +import MyComponent from '~/path/to/my_component.vue'; +import { shallowMount } from '@vue/test-utils'; + +describe('MyComponent', () => { + // Initiate the "global" wrapper variable. This will be used throughout our test + let wrapper; + + // define our `createComponent` factory + function createComponent() { + // mount component and reassign `wrapper` + wrapper = shallowMount(MyComponent); + } + + beforeEach(() => { + createComponent(); + }); + + it('mounts', () => { + expect(wrapper.exists()).toBe(true); + }); + + it('`isLoading` prop defaults to `false`', () => { + expect(wrapper.props('isLoading')).toBe(false); + }); +}) +``` + +#### `createComponent` best practices + +1. Consider using a single (or a limited number of) object arguments over many arguments. + Defining single parameters for common data like `props` is okay, + but keep in mind our [JavaScript style guide](javascript.md#limit-number-of-parameters) and stay within the parameter number limit: + + ```javascript + // bad + function createComponent(data, props, methods, isLoading, mountFn) { } + + // good + function createComponent({ data, props, methods, stubs, isLoading } = {}) { } + + // good + function createComponent(props = {}, { data, methods, stubs, isLoading } = {}) { } + ``` + +1. If you require both `mount` _and_ `shallowMount` within the same set of tests, it +can be useful define a `mountFn` parameter for the `createComponent` factory that accepts +the mounting function (`mount` or `shallowMount`) to be used to mount the component: + + ```javascript + import { shallowMount } from '@vue/test-utils'; + + function createComponent({ mountFn = shallowMount } = {}) { } + ``` + +### Setting component state + +1. Avoid using [`setProps`](https://vue-test-utils.vuejs.org/api/wrapper/#setprops) to set +component state wherever possible. Instead, set the component's +[`propsData`](https://vue-test-utils.vuejs.org/api/options.html#propsdata) when mounting the component: + + ```javascript + // bad + wrapper = shallowMount(MyComponent); + wrapper.setProps({ + myProp: 'my cool prop' + }); + + // good + wrapper = shallowMount({ propsData: { myProp: 'my cool prop' } }); + ``` + + The exception here is when you wish to test component reactivity in some way. + For example, you may want to test the output of a component when after a particular watcher has executed. + Using `setProps` to test such behavior is okay. + +### Accessing component state + +1. When accessing props or attributes, prefer the `wrapper.props('myProp')` syntax over `wrapper.props().myProp`: + + ```javascript + // good + expect(wrapper.props().myProp).toBe(true); + expect(wrapper.attributes().myAttr).toBe(true); + + // better + expect(wrapper.props('myProp').toBe(true); + expect(wrapper.attributes('myAttr')).toBe(true); + ``` + +1. When asserting multiple props, check the deep equality of the `props()` object with [`toEqual`](https://jestjs.io/docs/en/expect#toequalvalue): + + ```javascript + // good + expect(wrapper.props('propA')).toBe('valueA'); + expect(wrapper.props('propB')).toBe('valueB'); + expect(wrapper.props('propC')).toBe('valueC'); + + // better + expect(wrapper.props()).toEqual({ + propA: 'valueA', + propB: 'valueB', + propC: 'valueC', + }); + ``` + +1. If you are only interested in some of the props, you can use [`toMatchObject`](https://jestjs.io/docs/en/expect#tomatchobjectobject). +Prefer `toMatchObject` over [`expect.objectContaining`](https://jestjs.io/docs/en/expect#expectobjectcontainingobject): + + ```javascript + // good + expect(wrapper.props()).toEqual(expect.objectContaining({ + propA: 'valueA', + propB: 'valueB', + })); + + // better + expect(wrapper.props()).toMatchObject({ + propA: 'valueA', + propB: 'valueB', + }); + ``` + ## The JavaScript/Vue Accord The goal of this accord is to make sure we are all on the same page. diff --git a/doc/development/fe_guide/tooling.md b/doc/development/fe_guide/tooling.md index b93c0a9736b..809e05ea61f 100644 --- a/doc/development/fe_guide/tooling.md +++ b/doc/development/fe_guide/tooling.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Tooling ## ESLint @@ -14,7 +20,7 @@ To check all currently staged files (based on `git diff`) with ESLint, run the f yarn eslint-staged ``` -_A list of problems found will be logged to the console._ +A list of problems found will be logged to the console. To apply automatic ESLint fixes to all currently staged files (based on `git diff`), run the following script: @@ -22,7 +28,7 @@ To apply automatic ESLint fixes to all currently staged files (based on `git dif yarn eslint-staged-fix ``` -_If manual changes are required, a list of changes will be sent to the console._ +If manual changes are required, a list of changes will be sent to the console. To check **all** files in the repository with ESLint, run the following script: @@ -30,7 +36,7 @@ To check **all** files in the repository with ESLint, run the following script: yarn eslint ``` -_A list of problems found will be logged to the console._ +A list of problems found will be logged to the console. To apply automatic ESLint fixes to **all** files in the repository, run the following script: @@ -38,7 +44,7 @@ To apply automatic ESLint fixes to **all** files in the repository, run the foll yarn eslint-fix ``` -_If manual changes are required, a list of changes will be sent to the console._ +If manual changes are required, a list of changes will be sent to the console. CAUTION: **Caution:** Limit use to global rule updates. Otherwise, the changes can lead to huge Merge Requests. @@ -54,9 +60,8 @@ rules only if you are invoking/instantiating existing code modules. - [`no-new`](https://eslint.org/docs/rules/no-new) - [`class-method-use-this`](https://eslint.org/docs/rules/class-methods-use-this) -NOTE: **Note:** -Disable these rules on a per-line basis. This makes it easier to refactor -in the future. E.g. use `eslint-disable-next-line` or `eslint-disable-line`. +Disable these rules on a per-line basis. This makes it easier to refactor in the +future. For example, use `eslint-disable-next-line` or `eslint-disable-line`. ### Disabling ESLint for a single violation diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 58a8332589d..77bdadfe8da 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Vue To get started with Vue, read through [their documentation](https://vuejs.org/v2/guide/). @@ -47,7 +53,7 @@ of the new feature should be. The Store and the Service should be imported and initialized in this file and provided as a prop to the main component. -Be sure to read about [page-specific JavaScript](./performance.md#page-specific-javascript). +Be sure to read about [page-specific JavaScript](performance.md#page-specific-javascript). ### Bootstrapping Gotchas @@ -56,33 +62,36 @@ Be sure to read about [page-specific JavaScript](./performance.md#page-specific- While mounting a Vue application, you might need to provide data from Rails to JavaScript. To do that, you can use the `data` attributes in the HTML element and query them while mounting the application. -_Note:_ You should only do this while initializing the application, because the mounted element will be replaced with Vue-generated DOM. +You should only do this while initializing the application, because the mounted element will be replaced with Vue-generated DOM. The advantage of providing data from the DOM to the Vue instance through `props` in the `render` function instead of querying the DOM inside the main Vue component is avoiding the need to create a fixture or an HTML element in the unit test, -which will make the tests easier. See the following example: +which will make the tests easier. + +See the following example, also, please refer to our [Vue style guide](style/vue.md#basic-rules) for additional +information on why we explicitly declare the data being passed into the Vue app; ```javascript // haml #js-vue-app{ data: { endpoint: 'foo' }} // index.js -document.addEventListener('DOMContentLoaded', () => new Vue({ - el: '#js-vue-app', - data() { - const dataset = this.$options.el.dataset; - return { - endpoint: dataset.endpoint, - }; - }, +const el = document.getElementById('js-vue-app'); + +if (!el) return false; + +const { endpoint } = el.dataset; + +return new Vue({ + el, render(createElement) { return createElement('my-component', { props: { - endpoint: this.endpoint, + endpoint }, }); }, -})); +} ``` > When adding an `id` attribute to mount a Vue application, please make sure this `id` is unique across the codebase @@ -94,7 +103,7 @@ By following this practice, we can avoid the need to mock the `gl` object, which It should be done while initializing our Vue instance, and the data should be provided as `props` to the main component: ```javascript -document.addEventListener('DOMContentLoaded', () => new Vue({ +return new Vue({ el: '.js-vue-app', render(createElement) { return createElement('my-component', { @@ -103,7 +112,7 @@ document.addEventListener('DOMContentLoaded', () => new Vue({ }, }); }, -})); +}); ``` #### Accessing feature flags @@ -111,7 +120,7 @@ document.addEventListener('DOMContentLoaded', () => new Vue({ Use Vue's [provide/inject](https://vuejs.org/v2/api/#provide-inject) mechanism to make feature flags available to any descendant components in a Vue application. The `glFeatures` object is already provided in `commons/vue.js`, so -only the mixin is required to utilize the flags: +only the mixin is required to use the flags: ```javascript // An arbitrary descendant component @@ -179,13 +188,40 @@ Check this [page](vuex.md) for more details. - It is acceptable for Vue to listen to existing jQuery events using jQuery event listeners. - It is not recommended to add new jQuery events for Vue to interact with jQuery. +### Mixing Vue and JavaScript classes (in the data function) + +In the [Vue documentation](https://vuejs.org/v2/api/#Options-Data) the Data function/object is defined as follows: + +> The data object for the Vue instance. Vue will recursively convert its properties into getter/setters to make it “reactive”. The object must be plain: native objects such as browser API objects and prototype properties are ignored. A rule of thumb is that data should just be data - it is not recommended to observe objects with their own stateful behavior. + +Based on the Vue guidance: + +- **Do not** use or create a JavaScript class in your [data function](https://vuejs.org/v2/api/#data), such as `user: new User()`. +- **Do not** add new JavaScript class implementations. +- **Do** use [GraphQL](../api_graphql_styleguide.md), [Vuex](vuex.md) or a set of components if cannot use simple primitives or objects. +- **Do** maintain existing implementations using such approaches. +- **Do** Migrate components to a pure object model when there are substantial changes to it. +- **Do** add business logic to helpers or utils, so you can test them separately from your component. + +#### Why + +There are additional reasons why having a JavaScript class presents maintainability issues on a huge codebase: + +- Once a class is created, it is easy to extend it in a way that can infringe Vue reactivity and best practices. +- A class adds a layer of abstraction, which makes the component API and its inner workings less clear. +- It makes it harder to test. Since the class is instantiated by the component data function, it is harder to 'manage' component and class separately. +- Adding OOP to a functional codebase adds yet another way of writing code, reducing consistency and clarity. + ## Style guide Please refer to the Vue section of our [style guide](style/vue.md) -for best practices while writing your Vue components and templates. +for best practices while writing and testing your Vue components and templates. ## Testing Vue Components +Please refer to the [Vue testing style guide](style/vue.md#vue-testing) +for guidelines and best practices for testing your Vue components. + Each Vue component has a unique output. This output is always present in the render function. Although we can test each method of a Vue component individually, our goal must be to test the output @@ -226,7 +262,7 @@ describe('~/todos/app.vue', () => { mock.restore(); }); - // NOTE: It is very helpful to separate setting up the component from + // It is very helpful to separate setting up the component from // its collaborators (i.e. Vuex, axios, etc.) const createWrapper = (props = {}) => { wrapper = shallowMount(App, { @@ -236,7 +272,7 @@ describe('~/todos/app.vue', () => { }, }); }; - // NOTE: Helper methods greatly help test maintainability and readability. + // Helper methods greatly help test maintainability and readability. const findLoader = () => wrapper.find(GlLoadingIcon); const findAddButton = () => wrapper.find('[data-testid="add-button"]'); const findTextInput = () => wrapper.find('[data-testid="text-input"]'); diff --git a/doc/development/fe_guide/vue3_migration.md b/doc/development/fe_guide/vue3_migration.md index afdb2690c02..46437f39dbe 100644 --- a/doc/development/fe_guide/vue3_migration.md +++ b/doc/development/fe_guide/vue3_migration.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Migration to Vue 3 In order to prepare for the eventual migration to Vue 3.x, we should be wary about adding the following features to the codebase: @@ -76,7 +82,6 @@ const FunctionalComp = (props, slots) => { } ``` -NOTE: **Note:** It is not recommended to replace stateful components with functional components unless you absolutely need a performance improvement right now. In Vue 3, performance gains for functional components will be negligible. ## Old slots syntax with `slot` attribute diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 528dcb3b7f4..7765ba04d40 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Vuex When there's a clear benefit to separating state management from components (e.g. due to state complexity) we recommend using [Vuex](https://vuex.vuejs.org) over any other Flux pattern. Otherwise, feel free to manage state within the components. @@ -9,14 +15,14 @@ Vuex should be strongly considered when: - There are complex interactions with Backend, e.g. multiple API calls - The app involves interacting with backend via both traditional REST API and GraphQL (especially when moving the REST API over to GraphQL is a pending backend task) -_Note:_ All of the below is explained in more detail in the official [Vuex documentation](https://vuex.vuejs.org). +The information included in this page is explained in more detail in the +official [Vuex documentation](https://vuex.vuejs.org). ## Separation of concerns Vuex is composed of State, Getters, Mutations, Actions, and Modules. -When a user clicks on an action, we need to `dispatch` it. This action will `commit` a mutation that will change the state. -_Note:_ The action itself will not update the state, only a mutation should update the state. +When a user clicks on an action, we need to `dispatch` it. This action will `commit` a mutation that will change the state. The action itself will not update the state; only a mutation should update the state. ## File structure @@ -60,7 +66,7 @@ export const createStore = () => The first thing you should do before writing any code is to design the state. -Often we need to provide data from haml to our Vue application. Let's store it in the state for better access. +Often we need to provide data from HAML to our Vue application. Let's store it in the state for better access. ```javascript export default () => ({ @@ -354,8 +360,8 @@ export default initialState => ({ ``` We've made the conscious decision to avoid this pattern to aid in the -discoverability and searchability of our frontend codebase. The reasoning for -this is described in [this +discoverability and searchability of our frontend codebase. The same applies +when [providing data to a Vue app](vue.md#providing-data-from-haml-to-javascript). The reasoning for this is described in [this discussion](https://gitlab.com/gitlab-org/frontend/rfcs/-/issues/56#note_302514865): > Consider a `someStateKey` is being used in the store state. You _may_ not be diff --git a/doc/development/feature_categorization/index.md b/doc/development/feature_categorization/index.md index 57e0ad8b772..66ed2952250 100644 --- a/doc/development/feature_categorization/index.md +++ b/doc/development/feature_categorization/index.md @@ -1,8 +1,14 @@ +--- +stage: Enablement +group: Infrastructure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Feature Categorization > [Introduced](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/269) in GitLab 13.2. -Each Sidekiq worker, controller action, or (eventually) API endpoint +Each Sidekiq worker, controller action, or API endpoint must declare a `feature_category` attribute. This attribute maps each of these to a [feature category](https://about.gitlab.com/handbook/product/product-categories/). This @@ -112,3 +118,42 @@ assigned to all actions. The spec also validates if the used feature categories are known. And if the actions used in configuration still exist as routes. + +## API endpoints + +Grape API endpoints can use the `feature_category` class method, like +[Rails controllers](#rails-controllers) do: + +```ruby +module API + class Issues < ::API::Base + feature_category :issue_tracking + end +end +``` + +The second argument can be used to specify feature categories for +specific routes: + +```ruby +module API + class Users < ::API::Base + feature_category :users, ['/users/:id/custom_attributes', '/users/:id/custom_attributes/:key'] + end +end +``` + +Or the feature category can be specified in the action itself: + +```ruby +module API + class Users < ::API::Base + get ':id', feature_category: :users do + end + end +end +``` + +As with Rails controllers, an API class must specify the category for +every single action unless the same category is used for every action +within that class. diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index ef38a85bec0..df737912c00 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -92,9 +92,7 @@ Guidelines: 1. If the feature meets the requirements for creating a [Change Management](https://about.gitlab.com/handbook/engineering/infrastructure/change-management/#feature-flags-and-the-change-management-process) issue, create a Change Management issue per [criticality guidelines](https://about.gitlab.com/handbook/engineering/infrastructure/change-management/#change-request-workflows). 1. For simple, low-risk, easily reverted features, proceed and [enable the feature in `#production`](#process). -1. For features that impact the user experience, consider notifying - `#support_gitlab-com` first. - `#support_gitlab-com` beforehand. +1. For features that impact the user experience, consider notifying `#support_gitlab-com` beforehand. #### Process @@ -215,7 +213,6 @@ actors. Feature.enabled?(:some_feature, group) ``` -NOTE: **Note:** **Percentage of time** rollout is not a good idea if what you want is to make sure a feature is always on or off to the users. In that case, **Percentage of actors** rollout is a better method. diff --git a/doc/development/feature_flags/development.md b/doc/development/feature_flags/development.md index 067e480f6f8..2855662e1db 100644 --- a/doc/development/feature_flags/development.md +++ b/doc/development/feature_flags/development.md @@ -35,7 +35,6 @@ used so that unfinished code can be deployed in production. A `development` feature flag should have a rollout issue, ideally created using the [Feature Flag Roll Out template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20Flag%20Roll%20Out.md). -NOTE: **Note:** This is the default type used when calling `Feature.enabled?`. ### `ops` type @@ -61,30 +60,6 @@ Feature.disabled?(:my_ops_flag, project, type: :ops) push_frontend_feature_flag(:my_ops_flag, project, type: :ops) ``` -### `licensed` type - -`licensed` feature flags are used to temporarily disable licensed features. There -should be a one-to-one mapping of `licensed` feature flags to licensed features. - -`licensed` feature flags must be `default_enabled: true`, because that's the only -supported option in the current implementation. This is under development as per -the [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/218667). - -The `licensed` type has a dedicated set of functions to check if a licensed -feature is available for a project or namespace. This check validates -if the license is assigned to the namespace and feature flag itself. -The `licensed` feature flag has the same name as a licensed feature name: - -```ruby -# Good: checks if feature flag is enabled -project.feature_available?(:my_licensed_feature) -namespace.feature_available?(:my_licensed_feature) - -# Bad: licensed flag must be accessed via `feature_available?` -Feature.enabled?(:my_licensed_feature, type: :licensed) -push_frontend_feature_flag(:my_licensed_feature, type: :licensed) -``` - ## Feature flag definition and validation > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229161) in GitLab 13.3. @@ -128,7 +103,7 @@ a YAML definition in `config/feature_flags` or `ee/config/feature_flags`. Only feature flags that have a YAML definition file can be used when running the development or testing environments. ```shell -$ bin/feature-flag my-feature-flag +$ bin/feature-flag my_feature_flag >> Specify the group introducing the feature flag, like `group::apm`: ?> group::memory @@ -140,9 +115,9 @@ https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue%5Btitle%5D=%5BFeature+fl >> URL of the rollout issue (enter to skip): ?> https://gitlab.com/gitlab-org/gitlab/-/issues/232533 -create config/feature_flags/development/test-flag.yml +create config/feature_flags/development/my_feature_flag.yml --- -name: test-flag +name: my_feature_flag introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38602 rollout_issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/232533 group: group::memory @@ -212,6 +187,30 @@ if Feature.disabled?(:my_feature_flag, project, type: :ops) end ``` +DANGER: **Warning:** +Don't use feature flags at application load time. For example, using the `Feature` class in +`config/initializers/*` or at the class level could cause an unexpected error. This error occurs +because a database that a feature flag adapter might depend on doesn't exist at load time +(especially for fresh installations). Checking for the database's existence at the caller isn't +recommended, as some adapters don't require a database at all (for example, the HTTP adapter). The +feature flag setup check must be abstracted in the `Feature` namespace. This approach also requires +application reload when the feature flag changes. You must therefore ask SREs to reload the +Web/API/Sidekiq fleet on production, which takes time to fully rollout/rollback the changes. For +these reasons, use environment variables (for example, `ENV['YOUR_FEATURE_NAME']`) or `gitlab.yml` +instead. + +Here's an example of a pattern that you should avoid: + +```ruby +class MyClass + if Feature.enabled?(:...) + new_process + else + legacy_process + end +end +``` + ### Frontend Use the `push_frontend_feature_flag` method for frontend code, which is @@ -309,57 +308,16 @@ used as an actor for `Feature.enabled?`. ### Feature flags for licensed features -If a feature is license-gated, there's no need to add an additional -explicit feature flag check since the flag is checked as part of the -`License.feature_available?` call. Similarly, there's no need to "clean up" a -feature flag once the feature has reached general availability. - -The [`Project#feature_available?`](https://gitlab.com/gitlab-org/gitlab/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/app/models/project_feature.rb#L63-68), -[`Namespace#feature_available?`](https://gitlab.com/gitlab-org/gitlab/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/ee/namespace.rb#L71-85) (EE), and -[`License.feature_available?`](https://gitlab.com/gitlab-org/gitlab/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/license.rb#L293-300) (EE) methods all implicitly check for -a by default enabled feature flag with the same name as the provided argument. - -**An important side-effect of the implicit feature flags mentioned above is that -unless the feature is explicitly disabled or limited to a percentage of users, -the feature flag check defaults to `true`.** - -NOTE: **Note:** -Due to limitations with `feature_available?`, the YAML definition for `licensed` feature -flags accepts only `default_enabled: true`. This is under development as per the -[related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/218667). - -#### Alpha/beta licensed feature flags - -This is relevant when developing the feature using -[several smaller merge requests](https://about.gitlab.com/handbook/values/#make-small-merge-requests), or when the feature is considered to be an -[alpha or beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga), and -should not be available by default. - -As an example, if you were to ship the frontend half of a feature without the -backend, you'd want to disable the feature entirely until the backend half is -also ready to be shipped. To make sure this feature is disabled for both -GitLab.com and self-managed instances, you should use the -[`Namespace#alpha_feature_available?`](https://gitlab.com/gitlab-org/gitlab/blob/458749872f4a8f27abe8add930dbb958044cb926/ee/app/models/ee/namespace.rb#L113) or -[`Namespace#beta_feature_available?`](https://gitlab.com/gitlab-org/gitlab/blob/458749872f4a8f27abe8add930dbb958044cb926/ee/app/models/ee/namespace.rb#L100-112) -method, according to our [definitions](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga). This ensures the feature is disabled unless the feature flag is -_explicitly_ enabled. - -CAUTION: **Caution:** -If `alpha_feature_available?` or `beta_feature_available?` is used, the YAML definition -for the feature flag must use `default_enabled: [false, true]`, because the usage -of the feature flag is undefined. These methods may change, as per the -[related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/218667). +You can't use a feature flag with the same name as a licensed feature name, because +it would cause a naming collision. This was [widely discussed and removed](https://gitlab.com/gitlab-org/gitlab/-/issues/259611) +because it is confusing. -The resulting YAML should be similar to: +To check for licensed features, add a dedicated feature flag under a different name +and check it explicitly, for example: -```yaml -name: scoped_labels -group: group::memory -type: licensed -# The `default_enabled:` is undefined -# as `feature_available?` uses `default_enabled: true` -# as `beta_feature_available?` uses `default_enabled: false` -default_enabled: [false, true] +```ruby +Feature.enabled?(:licensed_feature_feature_flag, project) && + project.feature_available?(:licensed_feature) ``` ### Feature groups @@ -397,7 +355,6 @@ Introducing a feature flag into the codebase creates an additional code path tha It is strongly advised to test all code affected by a feature flag, both when **enabled** and **disabled** to ensure the feature works properly. -NOTE: **Note:** When using the testing environment, all feature flags are enabled by default. To disable a feature flag in a test, use the `stub_feature_flags` diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index 2643571aec3..a867bcf792a 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -1,5 +1,4 @@ --- -type: index, dev stage: none group: Development info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" diff --git a/doc/development/feature_flags/process.md b/doc/development/feature_flags/process.md index b327eec58e8..b282424f59a 100644 --- a/doc/development/feature_flags/process.md +++ b/doc/development/feature_flags/process.md @@ -80,7 +80,7 @@ In order to build a final release and present the feature for self-managed users, the feature flag should be at least defaulted to **on**. If the feature is deemed stable and there is confidence that removing the feature flag is safe, consider removing the feature flag altogether. It's _strongly_ recommended that -the feature flag is [enabled **globally** on **production**](./controls.md#enabling-a-feature-for-gitlabcom) for **at least one day** +the feature flag is [enabled **globally** on **production**](controls.md#enabling-a-feature-for-gitlabcom) for **at least one day** before making this decision. Unexpected bugs are sometimes discovered during this period. The process for enabling features that are disabled by default can take 5-6 days diff --git a/doc/development/features_inside_dot_gitlab.md b/doc/development/features_inside_dot_gitlab.md index cb883471adf..e8918c76d04 100644 --- a/doc/development/features_inside_dot_gitlab.md +++ b/doc/development/features_inside_dot_gitlab.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Features inside the `.gitlab/` directory We have implemented standard features that depend on configuration files in the `.gitlab/` directory. You can find `.gitlab/` in various GitLab repositories. diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md index e8ae5a11d48..aa91e105513 100644 --- a/doc/development/file_storage.md +++ b/doc/development/file_storage.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # File Storage in GitLab We use the [CarrierWave](https://github.com/carrierwaveuploader/carrierwave) gem to handle file upload, store and retrieval. @@ -50,10 +56,10 @@ In the case of Issues/MR/Notes Markdown attachments, there is a different approa instead of basing the path into a mutable variable `:project_path_with_namespace`, it's possible to use the hash of the project ID instead, if project migrates to the new approach (introduced in 10.2). -> Note: We provide an [all-in-one Rake task](../administration/raketasks/uploads/migrate.md) to migrate all uploads to object -> storage in one go. If a new Uploader class or model type is introduced, make -> sure you add a Rake task invocation corresponding to it to the -> [category list](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/uploads/migrate.rake). +We provide an [all-in-one Rake task](../administration/raketasks/uploads/migrate.md) +to migrate all uploads to object storage in one go. If a new Uploader class or model +type is introduced, make sure you add a Rake task invocation corresponding to it to the +[category list](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/uploads/migrate.rake). ### Path segments @@ -101,7 +107,7 @@ The `CarrierWave::Uploader#store_dir` is overridden to ### Using `ObjectStorage::Extension::RecordsUploads` -> Note: this concern will automatically include `RecordsUploads::Concern` if not already included. +This concern will automatically include `RecordsUploads::Concern` if not already included. The `ObjectStorage::Concern` uploader will search for the matching `Upload` to select the correct object store. The `Upload` is mapped using `#store_dirs + identifier` for each store (LOCAL/REMOTE). diff --git a/doc/development/foreign_keys.md b/doc/development/foreign_keys.md index 8a81dc158a7..ff8c03ce76b 100644 --- a/doc/development/foreign_keys.md +++ b/doc/development/foreign_keys.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Foreign Keys & Associations When adding an association to a model you must also add a foreign key. For diff --git a/doc/development/gemfile.md b/doc/development/gemfile.md index 8d93c52e7bc..1daa3ad5cba 100644 --- a/doc/development/gemfile.md +++ b/doc/development/gemfile.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # `Gemfile` guidelines When adding a new entry to `Gemfile` or upgrading an existing dependency pay diff --git a/doc/development/geo/framework.md b/doc/development/geo/framework.md index 55f4be07bb4..e440e324c4a 100644 --- a/doc/development/geo/framework.md +++ b/doc/development/geo/framework.md @@ -4,17 +4,12 @@ group: Geo info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Geo self-service framework (alpha) +# Geo self-service framework NOTE: **Note:** -This document might be subjected to change. It's a -proposal we're working on and once the implementation is complete this -documentation will be updated. Follow progress in the -[epic](https://gitlab.com/groups/gitlab-org/-/epics/2161). - -NOTE: **Note:** -The Geo self-service framework is currently in -alpha. If you need to replicate a new data type, reach out to the Geo +This document is subject to change as we continue to implement and iterate on the framework. +Follow the progress in the [epic](https://gitlab.com/groups/gitlab-org/-/epics/2161). +If you need to replicate a new data type, reach out to the Geo team to discuss the options. You can contact them in `#g_geo` on Slack or mention `@geo-team` in the issue or merge request. @@ -26,38 +21,40 @@ minimal effort of the engineer who created a data type. ## Nomenclature Before digging into the API, developers need to know some Geo-specific -naming conventions. +naming conventions: -Model -: A model is an Active Model, which is how it is known in the entire +- **Model**: + A model is an Active Model, which is how it is known in the entire Rails codebase. It usually is tied to a database table. From Geo perspective, a model can have one or more resources. -Resource -: A resource is a piece of data that belongs to a model and is +- **Resource**: + A resource is a piece of data that belongs to a model and is produced by a GitLab feature. It is persisted using a storage - mechanism. By default, a resource is not a replicable. + mechanism. By default, a resource is not a Geo replicable. -Data type -: Data type is how a resource is stored. Each resource should +- **Data type**: + Data type is how a resource is stored. Each resource should fit in one of the data types Geo supports: -:- Git repository -:- Blob -:- Database -: For more detail, see [Data types](../../administration/geo/replication/datatypes.md). + - Git repository + - Blob + - Database + + For more detail, see [Data types](../../administration/geo/replication/datatypes.md). -Geo Replicable -: A Replicable is a resource Geo wants to sync across Geo nodes. There +- **Geo Replicable**: + A Replicable is a resource Geo wants to sync across Geo nodes. There is a limited set of supported data types of replicables. The effort required to implement replication of a resource that belongs to one of the known data types is minimal. -Geo Replicator -: A Geo Replicator is the object that knows how to replicate a +- **Geo Replicator**: + A Geo Replicator is the object that knows how to replicate a replicable. It's responsible for: -:- Firing events (producer) -:- Consuming events (consumer) -: It's tied to the Geo Replicable data type. All replicators have a + - Firing events (producer) + - Consuming events (consumer) + + It's tied to the Geo Replicable data type. All replicators have a common interface that can be used to process (that is, produce and consume) events. It takes care of the communication between the primary node (where events are produced) and the secondary node @@ -65,8 +62,8 @@ Geo Replicator Geo in their feature will use the API of replicators to make this happen. -Geo Domain-Specific Language -: The syntactic sugar that allows engineers to easily specify which +- **Geo Domain-Specific Language**: + The syntactic sugar that allows engineers to easily specify which resources should be replicated and how. ## Geo Domain-Specific Language @@ -144,7 +141,7 @@ replicator.model_record ``` The replicator can be used to generate events, for example in -ActiveRecord hooks: +`ActiveRecord` hooks: ```ruby after_create_commit -> { replicator.publish_created_event } @@ -207,9 +204,12 @@ For example, to add support for files referenced by a `Widget` model with a end ``` + If there is a common constraint for records to be available for replication, + make sure to also overwrite the `available_replicables` scope. + 1. Create `ee/app/replicators/geo/widget_replicator.rb`. Implement the - `#carrierwave_uploader` method which should return a `CarrierWave::Uploader`. - And implement the class method `.model` to return the `Widget` class. + `#carrierwave_uploader` method which should return a `CarrierWave::Uploader`, + and implement the class method `.model` to return the `Widget` class: ```ruby # frozen_string_literal: true @@ -236,7 +236,7 @@ For example, to add support for files referenced by a `Widget` model with a ``` 1. Add this replicator class to the method `replicator_classes` in -`ee/lib/gitlab/geo.rb`: + `ee/lib/gitlab/geo.rb`: ```ruby REPLICATOR_CLASSES = [ @@ -247,8 +247,8 @@ For example, to add support for files referenced by a `Widget` model with a ``` 1. Create `ee/spec/replicators/geo/widget_replicator_spec.rb` and perform - the setup necessary to define the `model_record` variable for the shared - examples. + the necessary setup to define the `model_record` variable for the shared + examples: ```ruby # frozen_string_literal: true @@ -319,9 +319,7 @@ For example, to add support for files referenced by a `Widget` model with a ``` 1. Update `REGISTRY_CLASSES` in `ee/app/workers/geo/secondary/registry_consistency_worker.rb`. - 1. Add `widget_registry` to `ActiveSupport::Inflector.inflections` in `config/initializers_before_autoloader/000_inflections.rb`. - 1. Create `ee/spec/factories/geo/widget_registry.rb`: ```ruby @@ -375,17 +373,17 @@ For example, to add support for files referenced by a `Widget` model with a end ``` -Widgets should now be replicated by Geo! +Widgets should now be replicated by Geo. #### Verification There are two ways to add verification related fields so that the Geo primary -can track verification state: +can track verification state. ##### Option 1: Add verification state fields to the existing `widgets` table itself 1. Add a migration to add columns ordered according to [our guidelines](../ordering_table_columns.md) -for verification state to the widgets table: + for verification state to the widgets table: ```ruby # frozen_string_literal: true @@ -462,7 +460,7 @@ for verification state to the widgets table: 1. Create a `widget_states` table and add a partial index on `verification_failure` and `verification_checksum` to ensure re-verification can be performed efficiently. Order - the columns according to [our guidelines](../ordering_table_columns.md): + the columns according to [the guidelines](../ordering_table_columns.md): ```ruby # frozen_string_literal: true @@ -520,12 +518,12 @@ for verification state to the widgets table: To do: Add verification on secondaries. This should be done as part of [Geo: Self Service Framework - First Implementation for Package File verification](https://gitlab.com/groups/gitlab-org/-/epics/1817) -Widgets should now be verified by Geo! +Widgets should now be verified by Geo. #### Metrics Metrics are gathered by `Geo::MetricsUpdateWorker`, persisted in -`GeoNodeStatus` for display in the UI, and sent to Prometheus. +`GeoNodeStatus` for display in the UI, and sent to Prometheus: 1. Add fields `widgets_count`, `widgets_checksummed_count`, `widgets_checksum_failed_count`, `widgets_synced_count`, @@ -560,8 +558,12 @@ Metrics are gathered by `Geo::MetricsUpdateWorker`, persisted in end ``` +1. Make sure the factory also allows setting a `project` attribute. If the model + does not have a direct relation to a project, you can use a `transient` + attribute. Check out `spec/factories/merge_request_diffs.rb` for an example. + Widget replication and verification metrics should now be available in the API, -the Admin Area UI, and Prometheus! +the Admin Area UI, and Prometheus. #### GraphQL API @@ -578,7 +580,6 @@ the Admin Area UI, and Prometheus! 1. Add the new `widget_registries` field name to the `expected_fields` array in `ee/spec/graphql/types/geo/geo_node_type_spec.rb`. - 1. Create `ee/app/graphql/resolvers/geo/widget_registries_resolver.rb`: ```ruby @@ -687,14 +688,14 @@ the Admin Area UI, and Prometheus! ``` Individual widget synchronization and verification data should now be available -via the GraphQL API! +via the GraphQL API. -1. Take care of replicating "update" events. Geo Framework does not currently support - replicating "update" events because all entities added to the framework, by this time, - are immutable. If this is the case - for the entity you're going to add, please follow <https://gitlab.com/gitlab-org/gitlab/-/issues/118743> - and <https://gitlab.com/gitlab-org/gitlab/-/issues/118745> as examples to add the new event type. - Please also remove this notice when you've added it. +Make sure to replicate the "update" events. Geo Framework does not currently support +replicating "update" events because all entities added to the framework, by this time, +are immutable. If this is the case +for the entity you're going to add, follow <https://gitlab.com/gitlab-org/gitlab/-/issues/118743> +and <https://gitlab.com/gitlab-org/gitlab/-/issues/118745> as examples to add the new event type. +Also, remove this notice when you've added it. #### Admin UI @@ -702,7 +703,7 @@ To do: This should be done as part of [Geo: Implement frontend for Self-Service Framework replicables](https://gitlab.com/groups/gitlab-org/-/epics/2525) Widget sync and verification data (aggregate and individual) should now be -available in the Admin UI! +available in the Admin UI. #### Releasing the feature diff --git a/doc/development/git_object_deduplication.md b/doc/development/git_object_deduplication.md index 06af34d9232..4f1afed24ba 100644 --- a/doc/development/git_object_deduplication.md +++ b/doc/development/git_object_deduplication.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # How Git object deduplication works in GitLab When a GitLab user [forks a project](../user/project/repository/forking_workflow.md), @@ -27,7 +33,7 @@ configuration. Objects in A that are not in B will remain in A. For this to work, it is of course critical that **no objects ever get deleted from B** because A might need them. -DANGER: **Danger:** +DANGER: **Warning:** Do not run `git prune` or `git gc` in pool repositories! This can cause data loss in "real" repositories that depend on the pool in question. @@ -156,7 +162,7 @@ repository and a pool. ### Pool existence -If GitLab thinks a pool repository exists (i.e. it exists according to +If GitLab thinks a pool repository exists (i.e. it exists according to SQL), but it does not on the Gitaly server, then it will be created on the fly by Gitaly. diff --git a/doc/development/github_importer.md b/doc/development/github_importer.md index 5a490737f37..9fa55d2662a 100644 --- a/doc/development/github_importer.md +++ b/doc/development/github_importer.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Working with the GitHub importer In GitLab 10.2 a new version of the GitHub importer was introduced. This new diff --git a/doc/development/go_guide/dependencies.md b/doc/development/go_guide/dependencies.md index b85344635c6..461ee394533 100644 --- a/doc/development/go_guide/dependencies.md +++ b/doc/development/go_guide/dependencies.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Dependency Management in Go Go takes an unusual approach to dependency management, in that it is diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index 15d25d2d1ed..4077cf2a2c2 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Go standards and style guidelines This document describes various guidelines and best practices for GitLab diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index cc3db267d53..691027f385f 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Gotchas The purpose of this guide is to document potential "gotchas" that contributors @@ -157,7 +163,7 @@ allow_next_found_instance_of(Project) do |project| end ``` -_**Note:** Since Active Record is not calling the `.new` method on model classes to instantiate the objects, +Since Active Record is not calling the `.new` method on model classes to instantiate the objects, you should use `expect_next_found_instance_of` or `allow_next_found_instance_of` mock helpers to setup mock on objects returned by Active Record query & finder methods._ If we also want to initialize the instance with some particular arguments, we @@ -182,7 +188,7 @@ refresh_service.execute(oldrev, newrev, ref) See ["Why is it bad style to `rescue Exception => e` in Ruby?"](https://stackoverflow.com/questions/10048173/why-is-it-bad-style-to-rescue-exception-e-in-ruby). -_**Note:** This rule is [enforced automatically by +This rule is [enforced automatically by RuboCop](https://gitlab.com/gitlab-org/gitlab-foss/blob/8-4-stable/.rubocop.yml#L911-914)._ ## Do not use inline JavaScript in views @@ -190,8 +196,8 @@ RuboCop](https://gitlab.com/gitlab-org/gitlab-foss/blob/8-4-stable/.rubocop.yml# Using the inline `:javascript` Haml filters comes with a performance overhead. Using inline JavaScript is not a good way to structure your code and should be avoided. -_**Note:** We've [removed these two filters](https://gitlab.com/gitlab-org/gitlab/blob/master/config/initializers/hamlit.rb) -in an initializer._ +We've [removed these two filters](https://gitlab.com/gitlab-org/gitlab/blob/master/config/initializers/hamlit.rb) +in an initializer. ### Further reading diff --git a/doc/development/graphql_guide/batchloader.md b/doc/development/graphql_guide/batchloader.md new file mode 100644 index 00000000000..6d529358499 --- /dev/null +++ b/doc/development/graphql_guide/batchloader.md @@ -0,0 +1,121 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# GraphQL BatchLoader + +GitLab uses the [batch-loader](https://github.com/exAspArk/batch-loader) Ruby gem to optimize and avoid N+1 SQL queries. + +It is the properties of the GraphQL query tree that create opportunities for batching like this - disconnected nodes might need the same data, but cannot know about themselves. + +## When should you use it? + +We should try to batch DB requests as much as possible during GraphQL **query** execution. There is no need to batch loading during **mutations** because they are executed serially. If you need to make a database query, and it is possible to combine two similar (but not identical) queries, then consider using the batch-loader. + +When implementing a new endpoint we should aim to minimise the number of SQL queries. For stability and scalability we must also ensure that our queries do not suffer from N+1 performance issues. + +## Implementation + +Batch loading is useful when a series of queries for inputs `Qα, Qβ, ... Qω` can be combined to a single query for `Q[α, β, ... ω]`. An example of this is lookups by ID, where we can find two users by usernames as cheaply as one, but real-world examples can be more complex. + +Batchloading is not suitable when the result sets have different sort-orders, grouping, aggregation or other non-composable features. + +There are two ways to use the batch-loader in your code. For simple ID lookups, use `::Gitlab::Graphql::Loaders::BatchModelLoader.new(model, id).find`. For more complex cases, you can use the batch API directly. + +For example, to load a `User` by `username`, we can add batching as follows: + +```ruby +class UserResolver < BaseResolver + type UserType, null: true + argument :username, ::GraphQL::STRING_TYPE, required: true + + def resolve(**args) + BatchLoader::GraphQL.for(username).batch do |usernames, loader| + User.by_username(usernames).each do |user| + loader.call(user.username, user) + end + end + end +end +``` + +- `project_id` is the `ID` of the current project being queried +- `loader.call` is used to map the result back to the input key (here a project ID) +- `BatchLoader::GraphQL` returns a lazy object (suspended promise to fetch the data) + +Here an [example MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46549) illustrating how to use our `BatchLoading` mechanism. + +## How does it work exactly? + +Each lazy object knows which data it needs to load and how to batch the query. When we need to use the lazy objects (which we announce by calling `#sync`), they will be loaded along with all other similar objects in the current batch. + +Inside the block we execute a batch query for our items (`User`). After that, all we have to do is to call loader by passing an item which was used in `BatchLoader::GraphQL.for` method (`usernames`) and the loaded object itself (`user`): + +```ruby +BatchLoader::GraphQL.for(username).batch do |usernames, loader| + User.by_username(usernames).each do |user| + loader.call(user.username, user) + end +end +``` + +### What does lazy mean? + +It is important to avoid syncing batches too early. In the example below we can see how calling sync too early can eliminate opportunities for batching: + +```ruby +x = find_lazy(1) +y = find_lazy(2) + +# calling .sync will flush the current batch and will inhibit maximum laziness +x.sync + +z = find_lazy(3) + +y.sync +z.sync + +# => will run 2 queries +``` + +```ruby +x = find_lazy(1) +y = find_lazy(2) +z = find_lazy(3) + +x.sync +y.sync +z.sync + +# => will run 1 query +``` + +## Testing + +Any GraphQL field that supports `BatchLoading` should be tested using the `batch_sync` method available in [GraphQLHelpers](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/support/helpers/graphql_helpers.rb). + +```ruby +it 'returns data as a batch' do + results = batch_sync(max_queries: 1) do + [{ id: 1 }, { id: 2 }].map { |args| resolve(args) } + end + + expect(results).to eq(expected_results) +end + +def resolve(args = {}, context = { current_user: current_user }) + resolve(described_class, obj: obj, args: args, ctx: context) +end +``` + +We can also use [QueryRecorder](../query_recorder.md) to make sure we are performing only **one SQL query** per call. + +```ruby +it 'executes only 1 SQL query' do + query_count = ActiveRecord::QueryRecorder.new { subject }.count + + expect(query_count).to eq(1) +end +``` diff --git a/doc/development/graphql_guide/index.md b/doc/development/graphql_guide/index.md index 9d7fb5ba0a8..12b4f9796c7 100644 --- a/doc/development/graphql_guide/index.md +++ b/doc/development/graphql_guide/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GraphQL development guidelines This guide contains all the information to successfully contribute to GitLab's diff --git a/doc/development/graphql_guide/pagination.md b/doc/development/graphql_guide/pagination.md index bf9eaa99158..d5140363396 100644 --- a/doc/development/graphql_guide/pagination.md +++ b/doc/development/graphql_guide/pagination.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GraphQL pagination ## Types of pagination @@ -59,13 +65,13 @@ Some of the benefits and tradeoffs of keyset pagination are - Performance is much better. -- Data stability is greater since you're not going to miss records due to +- More data stability for end-users since records are not missing from lists due to deletions or insertions. - It's the best way to do infinite scrolling. - It's more difficult to program and maintain. Easy for `updated_at` and - `sort_order`, complicated (or impossible) for complex sorting scenarios. + `sort_order`, complicated (or impossible) for [complex sorting scenarios](#limitations-of-query-complexity). ## Implementation @@ -80,12 +86,171 @@ However, there are some cases where we have to use the offset pagination connection, `OffsetActiveRecordRelationConnection`, such as when sorting by label priority in issues, due to the complexity of the sort. -<!-- ### Keyset pagination --> +### Keyset pagination + +The keyset pagination implementation is a subclass of `GraphQL::Pagination::ActiveRecordRelationConnection`, +which is a part of the `graphql` gem. This is installed as the default for all `ActiveRecord::Relation`. +However, instead of using a cursor based on an offset (which is the default), GitLab uses a more specialized cursor. + +The cursor is created by encoding a JSON object which contains the relevant ordering fields. For example: + +```ruby +ordering = {"id"=>"72410125", "created_at"=>"2020-10-08 18:05:21.953398000 UTC"} +json = ordering.to_json +cursor = Base64Bp.urlsafe_encode64(json, padding: false) + +"eyJpZCI6IjcyNDEwMTI1IiwiY3JlYXRlZF9hdCI6IjIwMjAtMTAtMDggMTg6MDU6MjEuOTUzMzk4MDAwIFVUQyJ9" + +json = Base64Bp.urlsafe_decode64(cursor) +Gitlab::Json.parse(json) + +{"id"=>"72410125", "created_at"=>"2020-10-08 18:05:21.953398000 UTC"} +``` + +The benefits of storing the order attribute values in the cursor: + +- If only the ID of the object were stored, the object and its attributes could be queried. + That would require an additional query, and if the object is no longer there, then the needed + attributes are not available. +- If an attribute is `NULL`, then one SQL query can be used. If it's not `NULL`, then a + different SQL query can be used. + +Based on whether the main attribute field being sorted on is `NULL` in the cursor, the proper query +condition is built. The last ordering field is considered to be unique (a primary key), meaning the +column never contains `NULL` values. + +#### Limitations of query complexity + +We only support two ordering fields, and one of those fields needs to be the primary key. + +Here are two examples of pseudocode for the query: + +- **Two-condition query.** `X` represents the values from the cursor. `C` represents + the columns in the database, sorted in ascending order, using an `:after` cursor, and with `NULL` + values sorted last. + + ```plaintext + X1 IS NOT NULL + AND + (C1 > X1) + OR + (C1 IS NULL) + OR + (C1 = X1 + AND + C2 > X2) + + X1 IS NULL + AND + (C1 IS NULL + AND + C2 > X2) + ``` + + Below is an example based on the relation `Issue.order(relative_position: :asc).order(id: :asc)` + with an after cursor of `relative_position: 1500, id: 500`: + + ```plaintext + when cursor[relative_position] is not NULL + + ("issues"."relative_position" > 1500) + OR ( + "issues"."relative_position" = 1500 + AND + "issues"."id" > 500 + ) + OR ("issues"."relative_position" IS NULL) + + when cursor[relative_position] is NULL + + "issues"."relative_position" IS NULL + AND + "issues"."id" > 500 + ``` + +- **Three-condition query.** The example below is not complete, but shows the + complexity of adding one more condition. `X` represents the values from the cursor. `C` represents + the columns in the database, sorted in ascending order, using an `:after` cursor, and with `NULL` + values sorted last. + + ```plaintext + X1 IS NOT NULL + AND + (C1 > X1) + OR + (C1 IS NULL) + OR + (C1 = X1 AND C2 > X2) + OR + (C1 = X1 + AND + X2 IS NOT NULL + AND + ((C2 > X2) + OR + (C2 IS NULL) + OR + (C2 = X2 AND C3 > X3) + OR + X2 IS NULL..... + ``` + +By using +[`Gitlab::Graphql::Pagination::Keyset::QueryBuilder`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/graphql/pagination/keyset/query_builder.rb), +we're able to build the necessary SQL conditions and apply them to the Active Record relation. + +Complex queries can be difficult or impossible to use. For example, +in [`issuable.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/concerns/issuable.rb), +the `order_due_date_and_labels_priority` method creates a very complex query. + +These types of queries are not supported. In these instances, you can use offset pagination. + +### Offset pagination + +There are times when the [complexity of sorting](#limitations-of-query-complexity) +is more than our keyset pagination can handle. + +For example, in [`IssuesResolver`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/resolvers/issues_resolver.rb), +when sorting by `priority_asc`, we can't use keyset pagination as the ordering is much +too complex. For more information, read [`issuable.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/concerns/issuable.rb). -<!-- ### Offset pagination --> +In cases like this, we can fall back to regular offset pagination by returning a +[`Gitlab::Graphql::Pagination::OffsetActiveRecordRelationConnection`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/graphql/pagination/offset_active_record_relation_connection.rb) +instead of an `ActiveRecord::Relation`: + +```ruby + def resolve(parent, finder, **args) + issues = apply_lookahead(Gitlab::Graphql::Loaders::IssuableLoader.new(parent, finder).batching_find_all) + + if non_stable_cursor_sort?(args[:sort]) + # Certain complex sorts are not supported by the stable cursor pagination yet. + # In these cases, we use offset pagination, so we return the correct connection. + Gitlab::Graphql::Pagination::OffsetActiveRecordRelationConnection.new(issues) + else + issues + end + end +``` <!-- ### External pagination --> +### External pagination + +There may be times where you need to return data through the GitLab API that is stored in +another system. In these cases you may have to paginate a third-party's API. + +An example of this is with our [Error Tracking](../../operations/error_tracking.md) implementation, +where we proxy [Sentry errors](../../operations/error_tracking.md#sentry-error-tracking) through +the GitLab API. We do this by calling the Sentry API which enforces its own pagination rules. +This means we cannot access the collection within GitLab to perform our own custom pagination. + +For consistency, we manually set the pagination cursors based on values returned by the external API, using `Gitlab::Graphql::ExternallyPaginatedArray.new(previous_cursor, next_cursor, *items)`. + +You can see an example implementation in the following files: + +- [`types/error__tracking/sentry_error_collection_type.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/error_tracking/sentry_error_collection_type.rb) which adds an extension to `field :errors`. +- [`resolvers/error_tracking/sentry_errors_resolver.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/graphql/resolvers/error_tracking/sentry_errors_resolver.rb) which returns the data from the resolver. + ## Testing Any GraphQL field that supports pagination and sorting should be tested diff --git a/doc/development/hash_indexes.md b/doc/development/hash_indexes.md index 1ed76e35f69..cc0b0b3a736 100644 --- a/doc/development/hash_indexes.md +++ b/doc/development/hash_indexes.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Hash Indexes PostgreSQL supports hash indexes besides the regular B-tree diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index 59399e54c3e..65a1d83a8fc 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -1,3 +1,9 @@ +--- +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Internationalization for GitLab > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10669) in GitLab 9.2. @@ -15,7 +21,7 @@ All `rake` commands described on this page must be run on a GitLab instance, usu In order to be able to work on the [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss) project you must download and configure it through [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/set-up-gdk.md). -Once you have the GitLab project ready, you can start working on the translation. +After you have the GitLab project ready, you can start working on the translation. ## Tools @@ -98,9 +104,8 @@ Active Record's `:message` option accepts a `Proc`, so we can do this instead: validates :group_id, uniqueness: { scope: [:project_id], message: -> (object, data) { _("already shared with this group") } } ``` -NOTE: **Note:** Messages in the API (`lib/api/` or `app/graphql`) do -not need to be externalised. +not need to be externalized. ### HAML files @@ -379,8 +384,8 @@ Namespaces should be PascalCase. s__('OpenedNDaysAgo|Opened') ``` -Note: The namespace should be removed from the translation. See the [translation -guidelines for more details](translation.md#namespaced-strings). +The namespace should be removed from the translation. See the +[translation guidelines for more details](translation.md#namespaced-strings). ### HTML @@ -475,6 +480,21 @@ This makes use of [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/do ## Best practices +### Minimize translation updates + +Updates can result in the loss of the translations for this string. To minimize risks, +avoid changes to strings, unless they: + +- Add value to the user. +- Include extra context for translators. + +For example, we should avoid changes like this: + +```diff +- _('Number of things: %{count}') % { count: 10 } ++ n_('Number of things: %d', 10) +``` + ### Keep translations dynamic There are cases when it makes sense to keep translations together within an array or a hash. diff --git a/doc/development/i18n/index.md b/doc/development/i18n/index.md index 2d84fe4536f..13f2b43b788 100644 --- a/doc/development/i18n/index.md +++ b/doc/development/i18n/index.md @@ -1,3 +1,9 @@ +--- +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Translate GitLab to your language The text in GitLab's user interface is in American English by default. diff --git a/doc/development/i18n/merging_translations.md b/doc/development/i18n/merging_translations.md index 8b3357c41d3..c4a709f84d3 100644 --- a/doc/development/i18n/merging_translations.md +++ b/doc/development/i18n/merging_translations.md @@ -1,3 +1,9 @@ +--- +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Merging translations from CrowdIn CrowdIn automatically syncs the `gitlab.pot` file with the CrowdIn service, presenting diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index 1916f96801d..56a4f835b3f 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -1,3 +1,9 @@ +--- +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Proofread Translations Most translations are contributed, reviewed, and accepted by the community. We @@ -115,10 +121,8 @@ are very appreciative of the work done by translators and proofreaders! ## Become a proofreader -NOTE: **Note:** -Before requesting Proofreader permissions in CrowdIn please make -sure that you have a history of contributing translations to the GitLab -project. +Before requesting Proofreader permissions in CrowdIn, be sure you have a history +of contributing translations to the GitLab project. 1. Contribute translations to GitLab. See instructions for [translating GitLab](translation.md). @@ -140,8 +144,8 @@ project. - link to your GitLab profile - link to your CrowdIn profile - In the merge request description, please include links to any projects you - have previously translated. + In the merge request description, include links to any projects you have + previously translated. 1. Your request to become a proofreader will be considered on the merits of your previous translations by [GitLab team members](https://about.gitlab.com/company/team/) diff --git a/doc/development/i18n/translation.md b/doc/development/i18n/translation.md index ed205c20c0d..128bacfda97 100644 --- a/doc/development/i18n/translation.md +++ b/doc/development/i18n/translation.md @@ -1,3 +1,9 @@ +--- +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Translating GitLab For managing the translation process we use [CrowdIn](https://crowdin.com). @@ -94,7 +100,7 @@ To propose additions to the glossary please ### Inclusive language in French <!-- vale gitlab.Spelling = NO --> -In French, the "écriture inclusive" is now over (see on [Legifrance](https://www.legifrance.gouv.fr/affichTexte.do?cidTexte=JORFTEXT000036068906&categorieLien=id)). +In French, the "écriture inclusive" is now over (see on [Legifrance](https://www.legifrance.gouv.fr/affichTexte.do?cidTexte=JORFTEXT000036068906&categorieLien=id)). So, to include both genders, write “Utilisateurs et utilisatrices” instead of “Utilisateur·rice·s”. When space is missing, the male gender should be used alone. <!-- vale gitlab.Spelling = YES --> diff --git a/doc/development/image_scaling.md b/doc/development/image_scaling.md new file mode 100644 index 00000000000..05f44209bc4 --- /dev/null +++ b/doc/development/image_scaling.md @@ -0,0 +1,96 @@ +--- +stage: Enablement +group: Memory +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Image scaling guide + +This section contains a brief overview of GitLab's image scaler and how to work with it. + +For a general introduction to the history of image scaling at GitLab, you might be interested in +[this Unfiltered blog post](https://about.gitlab.com/blog/2020/11/02/scaling-down-how-we-prototyped-an-image-scaler-at-gitlab/). + +## Why image scaling? + +Since version 13.6, GitLab scales down images on demand in order to reduce the page data footprint. +This both reduces the amount of data "on the wire", but also helps with rendering performance, +since the browser has less work to do. + +## When do we scale images? + +Generally, the image scaler is triggered whenever a client requests an image resource by adding +the `width` parameter to the query string. However, we only scale images of certain kinds and formats. +Whether we allow an image to be rescaled or not is decided by combination of hard-coded rules and configuration settings. + +The hard-coded rules only permit: + +- [Project, group and user avatars](https://gitlab.com/gitlab-org/gitlab/-/blob/fd08748862a5fe5c25b919079858146ea85843ae/app/controllers/concerns/send_file_upload.rb#L65-67) +- [PNGs or JPEGs](https://gitlab.com/gitlab-org/gitlab/-/blob/5dff8fa3814f2a683d8884f468cba1ec06a60972/lib/gitlab/file_type_detection.rb#L23) +- [Specific dimensions](https://gitlab.com/gitlab-org/gitlab/-/blob/5dff8fa3814f2a683d8884f468cba1ec06a60972/app/models/concerns/avatarable.rb#L6) + +Furthermore, configuration in Workhorse can lead to the image scaler rejecting a request if: + +- The image file is too large (controlled by [`max_filesize`](- we only rescale images that do not exceed a configured size in bytes (see [`max_filesize`](https://gitlab.com/gitlab-org/gitlab-workhorse/-/blob/67ab3a2985d2097392f93523ae1cffe0dbf01b31/config.toml.example#L17)))). +- Too many image scalers are already running (controlled by [`max_scaler_procs`](https://gitlab.com/gitlab-org/gitlab-workhorse/-/blob/67ab3a2985d2097392f93523ae1cffe0dbf01b31/config.toml.example#L16)). + +For instance, here are two different URLs that serve the GitLab project avatar both in its +original size and scaled down to 64 pixels. Only the second request will trigger the image scaler: + +- [`/uploads/-/system/project/avatar/278964/logo-extra-whitespace.png`](https://assets.gitlab-static.net/uploads/-/system/project/avatar/278964/logo-extra-whitespace.png) +- [`/uploads/-/system/project/avatar/278964/logo-extra-whitespace.png?width=64`](https://assets.gitlab-static.net/uploads/-/system/project/avatar/278964/logo-extra-whitespace.png?width=64) + +## Where do we scale images? + +Rails and Workhorse currently collaborate to rescale images. This is a common implementation and performance +pattern in GitLab: important business logic such as request authentication and validation +happens in Rails, whereas the "heavy lifting", scaling and serving the binary data, happens in Workhorse. + +The overall request flow is as follows: + +```mermaid +sequenceDiagram + Client->>+Workhorse: GET /uploads/-/system/project/avatar/278964/logo-extra-whitespace.png?width=64 + Workhorse->>+Rails: forward request + Rails->>+Rails: validate request + Rails->>+Rails: resolve image location + Rails-->>-Workhorse: Gitlab-Workhorse-Send-Data: send-scaled-image + Workhorse->>+Workhorse: invoke image scaler + Workhorse-->>-Client: 200 OK +``` + +### Rails + +Currently, image scaling is limited to `Upload` entities, specifically avatars as mentioned above. +Therefore, all image scaling related logic in Rails is currently found in the +[`send_file_upload`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/concerns/send_file_upload.rb) +controller mixin. Upon receiving a request coming from a client through Workhorse, we check whether +it should trigger the image scaler as per the criteria mentioned above, and if so, render a special response +header field (`Gitlab-Workhorse-Send-Data`) with the necessary parameters for Workhorse to carry +out the scaling request. If Rails decides the request does not constitute a valid image scaling request, +we simply follow the path we take to serve any ordinary upload. + +### Workhorse + +Assuming Rails decided the request to be valid, Workhorse will take over. Upon receiving the `send-scaled-image` +instruction through the Rails response, a [special response injecter](https://gitlab.com/gitlab-org/gitlab-workhorse/-/blob/master/internal/imageresizer/image_resizer.go) +will be invoked that knows how to rescale images. The only inputs it requires are the location of the image +(a path if the image resides in block storage, or a URL to remote storage otherwise) and the desired width. +Workhorse will handle the location transparently so Rails does not need to be concerned with where the image +actually resides. + +Additionally, to request validation in Rails, Workhorse will run several pre-condition checks to ensure that +we can actually rescale the image, such as making sure we wouldn't outgrow our scaler process budget but also +if the file meets the configured maximum allowed size constraint (to keep memory consumption in check). + +To actually scale the image, Workhorse will finally fork into a child process that performs the actual +scaling work, and stream the result back to the client. + +#### Caching rescaled images + +We currently do not store rescaled images anywhere; the scaler runs every time a smaller version is requested. +However, Workhorse implements standard conditional HTTP request strategies that allow us to skip the scaler +if the image in the client cache is up-to-date. +To that end we transmit a `Last-Modified` header field carrying the UTC +timestamp of the original image file and match it against the `If-Modified-Since` header field in client requests. +Only if the original image has changed and rescaling becomes necessary do we run the scaler again. diff --git a/doc/development/img/architecture_simplified.png b/doc/development/img/architecture_simplified.png Binary files differindex 72d00b91129..bd731758ddd 100644 --- a/doc/development/img/architecture_simplified.png +++ b/doc/development/img/architecture_simplified.png diff --git a/doc/development/img/bullet_v13_0.png b/doc/development/img/bullet_v13_0.png Binary files differindex e185bdef76d..2a3248e380c 100644 --- a/doc/development/img/bullet_v13_0.png +++ b/doc/development/img/bullet_v13_0.png diff --git a/doc/development/img/distributed_tracing_jaeger_ui.png b/doc/development/img/distributed_tracing_jaeger_ui.png Binary files differindex dcd18b1ec9f..5452294caa3 100644 --- a/doc/development/img/distributed_tracing_jaeger_ui.png +++ b/doc/development/img/distributed_tracing_jaeger_ui.png diff --git a/doc/development/img/memory_ruby_heap_fragmentation.png b/doc/development/img/memory_ruby_heap_fragmentation.png Binary files differindex 4703da7491d..204130f8d87 100644 --- a/doc/development/img/memory_ruby_heap_fragmentation.png +++ b/doc/development/img/memory_ruby_heap_fragmentation.png diff --git a/doc/development/img/merge_ref_head_options_v13_6.png b/doc/development/img/merge_ref_head_options_v13_6.png Binary files differnew file mode 100644 index 00000000000..3134092cc92 --- /dev/null +++ b/doc/development/img/merge_ref_head_options_v13_6.png diff --git a/doc/development/img/performance_bar_cached_queries.png b/doc/development/img/performance_bar_cached_queries.png Binary files differnew file mode 100644 index 00000000000..f5bdc6ffd84 --- /dev/null +++ b/doc/development/img/performance_bar_cached_queries.png diff --git a/doc/development/img/performance_bar_fixed_cached_queries.png b/doc/development/img/performance_bar_fixed_cached_queries.png Binary files differnew file mode 100644 index 00000000000..3f4232fb88f --- /dev/null +++ b/doc/development/img/performance_bar_fixed_cached_queries.png diff --git a/doc/development/img/performance_bar_members_page.png b/doc/development/img/performance_bar_members_page.png Binary files differnew file mode 100644 index 00000000000..bc81cd645e5 --- /dev/null +++ b/doc/development/img/performance_bar_members_page.png diff --git a/doc/development/img/telemetry_system_overview.png b/doc/development/img/telemetry_system_overview.png Binary files differdeleted file mode 100644 index f2e6b300e94..00000000000 --- a/doc/development/img/telemetry_system_overview.png +++ /dev/null diff --git a/doc/development/import_export.md b/doc/development/import_export.md index 8d2be1baf24..a73144abce6 100644 --- a/doc/development/import_export.md +++ b/doc/development/import_export.md @@ -1,3 +1,9 @@ +--- +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Import/Export development documentation Troubleshooting and general development guidelines and tips for the [Import/Export feature](../user/project/settings/import_export.md). @@ -354,28 +360,28 @@ The NDJSON tree will look like this: ```shell tree ├── project -│ ├── auto_devops.ndjson -│ ├── boards.ndjson -│ ├── ci_cd_settings.ndjson -│ ├── ci_pipelines.ndjson -│ ├── container_expiration_policy.ndjson -│ ├── custom_attributes.ndjson -│ ├── error_tracking_setting.ndjson -│ ├── external_pull_requests.ndjson -│ ├── issues.ndjson -│ ├── labels.ndjson -│ ├── merge_requests.ndjson -│ ├── milestones.ndjson -│ ├── pipeline_schedules.ndjson -│ ├── project_badges.ndjson -│ ├── project_feature.ndjson -│ ├── project_members.ndjson -│ ├── protected_branches.ndjson -│ ├── protected_tags.ndjson -│ ├── releases.ndjson -│ ├── services.ndjson -│ ├── snippets.ndjson -│ └── triggers.ndjson +│ ├── auto_devops.ndjson +│ ├── boards.ndjson +│ ├── ci_cd_settings.ndjson +│ ├── ci_pipelines.ndjson +│ ├── container_expiration_policy.ndjson +│ ├── custom_attributes.ndjson +│ ├── error_tracking_setting.ndjson +│ ├── external_pull_requests.ndjson +│ ├── issues.ndjson +│ ├── labels.ndjson +│ ├── merge_requests.ndjson +│ ├── milestones.ndjson +│ ├── pipeline_schedules.ndjson +│ ├── project_badges.ndjson +│ ├── project_feature.ndjson +│ ├── project_members.ndjson +│ ├── protected_branches.ndjson +│ ├── protected_tags.ndjson +│ ├── releases.ndjson +│ ├── services.ndjson +│ ├── snippets.ndjson +│ └── triggers.ndjson └── project.json ``` @@ -389,19 +395,19 @@ The NDJSON tree will look like this: tree └── groups ├── 4351 - │ ├── badges.ndjson - │ ├── boards.ndjson - │ ├── epics.ndjson - │ ├── labels.ndjson - │ ├── members.ndjson - │ └── milestones.ndjson + │ ├── badges.ndjson + │ ├── boards.ndjson + │ ├── epics.ndjson + │ ├── labels.ndjson + │ ├── members.ndjson + │ └── milestones.ndjson ├── 4352 - │ ├── badges.ndjson - │ ├── boards.ndjson - │ ├── epics.ndjson - │ ├── labels.ndjson - │ ├── members.ndjson - │ └── milestones.ndjson + │ ├── badges.ndjson + │ ├── boards.ndjson + │ ├── epics.ndjson + │ ├── labels.ndjson + │ ├── members.ndjson + │ └── milestones.ndjson ├── _all.ndjson ├── 4351.json └── 4352.json diff --git a/doc/development/import_project.md b/doc/development/import_project.md index 9e2f5af6738..8b27b7d28a5 100644 --- a/doc/development/import_project.md +++ b/doc/development/import_project.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Test Import Project For testing, we can import our own [GitLab CE](https://gitlab.com/gitlab-org/gitlab-foss/) project (named `gitlabhq` in this case) under a group named `qa-perf-testing`. Project tarballs that can be used for testing can be found over on the [performance-data](https://gitlab.com/gitlab-org/quality/performance-data) project. A different project could be used if required. @@ -17,7 +23,6 @@ The first option is to simply [import the Project tarball file via the GitLab UI It should take up to 15 minutes for the project to fully import. You can head to the project's main page for the current status. -NOTE: **Note:** This method ignores all the errors silently (including the ones related to `GITALY_DISABLE_REQUEST_LIMITS`) and is used by GitLab's users. For development and testing, check the other methods below. ### Importing via the `import-project` script diff --git a/doc/development/insert_into_tables_in_batches.md b/doc/development/insert_into_tables_in_batches.md index f65d2478d2e..5fe37a95b59 100644 --- a/doc/development/insert_into_tables_in_batches.md +++ b/doc/development/insert_into_tables_in_batches.md @@ -1,4 +1,7 @@ --- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers description: "Sometimes it is necessary to store large amounts of records at once, which can be inefficient when iterating collections and performing individual `save`s. With the arrival of `insert_all` in Rails 6, which operates at the row level (that is, using `Hash`es), GitLab has added a set diff --git a/doc/development/integrations/jenkins.md b/doc/development/integrations/jenkins.md index 5d3c869d922..d81dee94f17 100644 --- a/doc/development/integrations/jenkins.md +++ b/doc/development/integrations/jenkins.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # How to run Jenkins in development environment (on macOS) **(STARTER)** This is a step by step guide on how to set up [Jenkins](https://www.jenkins.io/) on your local machine and connect to it from your GitLab instance. GitLab triggers webhooks on Jenkins, and Jenkins connects to GitLab using the API. By running both applications on the same machine, we can make sure they are able to access each other. diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md index 1f9b03075f0..66a93f8c947 100644 --- a/doc/development/integrations/jira_connect.md +++ b/doc/development/integrations/jira_connect.md @@ -1,31 +1,37 @@ -# Setting up a development environment +--- +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- -The following are required to install and test the app: - -1. A Jira Cloud instance +# Set up a development environment - Atlassian provides free instances for development and testing. [Click here to sign up](https://developer.atlassian.com/platform/marketplace/getting-started/#free-developer-instances-to-build-and-test-your-app). +The following are required to install and test the app: -1. A GitLab instance available over the internet +- A Jira Cloud instance. Atlassian provides [free instances for development and testing](https://developer.atlassian.com/platform/marketplace/getting-started/#free-developer-instances-to-build-and-test-your-app). +- A GitLab instance available over the internet. For the app to work, Jira Cloud should + be able to connect to the GitLab instance through the internet. To easily expose your + local development environment, you can use tools like: + - [serveo](https://medium.com/automationmaster/how-to-forward-my-local-port-to-public-using-serveo-4979f352a3bf) + - [ngrok](https://ngrok.com). - For the app to work, Jira Cloud should be able to connect to the GitLab instance through the internet. + These also take care of SSL for you because Jira requires all connections to the app + host to be over SSL. - To easily expose your local development environment, you can use tools like - [serveo](https://medium.com/automationmaster/how-to-forward-my-local-port-to-public-using-serveo-4979f352a3bf) - or [ngrok](https://ngrok.com). These also take care of SSL for you because Jira - requires all connections to the app host to be over SSL. +## Install the app in Jira -## Installing the app in Jira +To install the app in Jira: -1. Enable Jira development mode to install apps that are not from the Atlassian Marketplace +1. Enable Jira development mode to install apps that are not from the Atlassian + Marketplace: - 1. Navigate to **Jira settings** (cog icon) > **Apps** > **Manage apps**. + 1. In Jira, navigate to **Jira settings > Apps > Manage apps**. 1. Scroll to the bottom of the **Manage apps** page and click **Settings**. 1. Select **Enable development mode** and click **Apply**. -1. Install the app +1. Install the app: - 1. Navigate to Jira, then choose **Jira settings** (cog icon) > **Apps** > **Manage apps**. + 1. In Jira, navigate to **Jira settings > Apps > Manage apps**. 1. Click **Upload app**. 1. In the **From this URL** field, provide a link to the app descriptor. The host and port must point to your GitLab instance. diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md index 1094074cab6..9bb92709d54 100644 --- a/doc/development/integrations/secure.md +++ b/doc/development/integrations/secure.md @@ -1,7 +1,13 @@ +--- +stage: Protect +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Security scanner integration Integrating a security scanner into GitLab consists of providing end users -with a [CI job definition](../../ci/yaml/README.md#introduction) +with a [CI job definition](../../ci/yaml/README.md) they can add to their CI configuration files to scan their GitLab projects. This CI job should then output its results in a GitLab-specified format. These results are then automatically presented in various places in GitLab, such as the Pipeline view, Merge Request @@ -40,12 +46,12 @@ Because the `script` entry can't be left empty, it must be set to the command th It is not possible to rely on the predefined `ENTRYPOINT` and `CMD` of the Docker image to perform the scan automatically, without passing any command. -The [`before_script`](../../ci/yaml/README.md#before_script-and-after_script) +The [`before_script`](../../ci/yaml/README.md#before_script) should not be used in the job definition because users may rely on this to prepare their projects before performing the scan. For instance, it is common practice to use `before_script` to install system libraries a particular project needs before performing SAST or Dependency Scanning. -Similarly, [`after_script`](../../ci/yaml/README.md#before_script-and-after_script) +Similarly, [`after_script`](../../ci/yaml/README.md#after_script) should not be used in the job definition, because it may be overridden by users. ### Stage @@ -175,7 +181,9 @@ SAST and Dependency Scanning scanners must scan the files in the project directo In order to be consistent with the official Container Scanning for GitLab, scanners must scan the Docker image whose name and tag are given by -`CI_APPLICATION_REPOSITORY` and `CI_APPLICATION_TAG`, respectively. +`CI_APPLICATION_REPOSITORY` and `CI_APPLICATION_TAG`, respectively. If the `DOCKER_IMAGE` +variable is provided, then the `CI_APPLICATION_REPOSITORY` and `CI_APPLICATION_TAG` variables +are ignored, and the image specified in the `DOCKER_IMAGE` variable is scanned instead. If not provided, `CI_APPLICATION_REPOSITORY` should default to `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG`, which is a combination of predefined CI variables. @@ -248,6 +256,11 @@ It is recommended to use the `debug` level for verbose logging that could be useful when debugging. The default value for `SECURE_LOG_LEVEL` should be set to `info`. +When executing command lines, scanners should use the `debug` level to log the command line and its output. +For instance, the [bundler-audit](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit) scanner +uses the `debug` level to log the command line `bundle audit check --quiet`, +and what `bundle audit` writes to the standard output. + #### common logutil package If you are using [go](https://golang.org/) and @@ -278,8 +291,7 @@ You can find the schemas for these scanners here: ### Version -This field specifies the version of the report schema you are using. Please reference individual scanner -pages for the specific versions to use. +This field specifies the version of the [Security Report Schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas) you are using. Please refer to the [releases](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) of the schemas for the specific versions to use. ### Vulnerabilities @@ -287,7 +299,7 @@ The `vulnerabilities` field of the report is an array of vulnerability objects. #### ID -The `id` field is the unique identifier of the vulnerability. +The `id` field is the unique identifier of the vulnerability. It is used to reference a fixed vulnerability from a [remediation objects](#remediations). We recommend that you generate a UUID and use it as the `id` field's value. @@ -532,7 +544,7 @@ of the available SAST Analyzers and what data is currently available. The `remediations` field of the report is an array of remediation objects. Each remediation describes a patch that can be applied to -[automatically fix](../../user/application_security/#solutions-for-vulnerabilities-auto-remediation) +[automatically fix](../../user/application_security/#automatic-remediation-for-vulnerabilities) a set of vulnerabilities. Here is an example of a report that contains remediations. diff --git a/doc/development/integrations/secure_partner_integration.md b/doc/development/integrations/secure_partner_integration.md index 19fd86f4bf6..52d10f0bd3c 100644 --- a/doc/development/integrations/secure_partner_integration.md +++ b/doc/development/integrations/secure_partner_integration.md @@ -1,3 +1,9 @@ +--- +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Secure Partner Integration - Onboarding Process If you want to integrate your product with the [Secure Stage](https://about.gitlab.com/direction/secure/), @@ -95,7 +101,7 @@ and complete an integration with the Secure stage. - Users can interact with the findings from your artifact within their workflow. They can dismiss the findings or accept them and create a backlog issue. - To automatically create issues without user interaction, use the [issue API](../../api/issues.md). This will be replaced by [Standalone Vulnerabilities](https://gitlab.com/groups/gitlab-org/-/epics/634) in the future. 1. Optional: Provide auto-remediation steps: - - If you specified `remediations` in your artifact, it is proposed through our [auto-remediation](../../user/application_security/index.md#solutions-for-vulnerabilities-auto-remediation) + - If you specified `remediations` in your artifact, it is proposed through our [auto-remediation](../../user/application_security/index.md#automatic-remediation-for-vulnerabilities) interface. 1. Demo the integration to GitLab: - After you have tested and are ready to demo your integration please diff --git a/doc/development/interacting_components.md b/doc/development/interacting_components.md index 697c64986b1..87bbe30d9fd 100644 --- a/doc/development/interacting_components.md +++ b/doc/development/interacting_components.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Developing against interacting components or features It's not uncommon that a single code change can reflect and interact with multiple parts of GitLab diff --git a/doc/development/internal_users.md b/doc/development/internal_users.md new file mode 100644 index 00000000000..9f1428dce80 --- /dev/null +++ b/doc/development/internal_users.md @@ -0,0 +1,44 @@ +--- +description: "Internal users documentation." +type: concepts, reference, dev +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +--- + +# Internal users + +GitLab uses internal users (sometimes referred to as "bots") to perform +actions or functions that cannot be attributed to a regular user. + +These users are created programatically throughout the codebase itself when +necessary, and do not count towards a license limit. + +They are used when a traditional user account would not be applicable, for +example when generating alerts or automatic review feedback. + +Technically, an internal user is a type of user, but they have reduced access +and a very specific purpose. They cannot be used for regular user actions, +such as authentication or API requests. + +They have email addresses and names which can be attributed to any actions +they perform. + +For example, when we [migrated](https://gitlab.com/gitlab-org/gitlab/-/issues/216120) +GitLab Snippets to [Versioned Snippets](../user/snippets.md#versioned-snippets) +in GitLab 13.0, we used an internal user to attribute the authorship of +snippets to itself when a snippet's author wasn't available for creating +repository commits, such as when the user has been disabled, so the Migration +Bot was used instead. + +For this bot: + +- The name was set to `GitLab Migration Bot`. +- The email was set to `noreply+gitlab-migration-bot@{instance host}`. + +Other examples of internal users: + +- [Alert Bot](../operations/metrics/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) +- Visual Review Bot diff --git a/doc/development/iterating_tables_in_batches.md b/doc/development/iterating_tables_in_batches.md index 56cbb3a0e9e..062b755de38 100644 --- a/doc/development/iterating_tables_in_batches.md +++ b/doc/development/iterating_tables_in_batches.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Iterating Tables In Batches Rails provides a method called `in_batches` that can be used to iterate over diff --git a/doc/development/lfs.md b/doc/development/lfs.md index 3ba81e6a140..64bc709ff9a 100644 --- a/doc/development/lfs.md +++ b/doc/development/lfs.md @@ -1,3 +1,9 @@ +--- +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/engineering/ux/technical-writing/#designated-technical-writers +--- + # Git LFS ## Deep Dive diff --git a/doc/development/licensed_feature_availability.md b/doc/development/licensed_feature_availability.md index 4350c7fb4d4..f83a57fe1ca 100644 --- a/doc/development/licensed_feature_availability.md +++ b/doc/development/licensed_feature_availability.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Licensed feature availability **(STARTER)** As of GitLab 9.4, we've been supporting a simplified version of licensed diff --git a/doc/development/licensing.md b/doc/development/licensing.md index 8cda3d5f361..d1808822ba6 100644 --- a/doc/development/licensing.md +++ b/doc/development/licensing.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab Licensing and Compatibility [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss/) (CE) is licensed [under the terms of the MIT License](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/LICENSE). [GitLab Enterprise Edition](https://gitlab.com/gitlab-org/gitlab/) (EE) is licensed under "[The GitLab Enterprise Edition (EE) license](https://gitlab.com/gitlab-org/gitlab/blob/master/LICENSE)" wherein there are more restrictions. @@ -12,7 +18,8 @@ Some gems may not include their license information in their `gemspec` file, and ### License Finder commands -> Note: License Finder currently uses GitLab misused terms of `whitelist` and `blacklist`. As a result, the commands below reference those terms. We've created an [issue on their project](https://github.com/pivotal/LicenseFinder/issues/745) to propose that they rename their commands. +NOTE: **Note:** +License Finder currently uses GitLab misused terms of `whitelist` and `blacklist`. As a result, the commands below reference those terms. We've created an [issue on their project](https://github.com/pivotal/LicenseFinder/issues/745) to propose that they rename their commands. There are a few basic commands License Finder provides that you'll need in order to manage license detection. diff --git a/doc/development/mass_insert.md b/doc/development/mass_insert.md index c19850ca67e..dfffab564bc 100644 --- a/doc/development/mass_insert.md +++ b/doc/development/mass_insert.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Mass inserting Rails models Setting the environment variable [`MASS_INSERT=1`](rake_tasks.md#environment-variables) diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index 2f084937cc9..a5d9a653472 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Merge Request Performance Guidelines Each new introduced merge request **should be performant by default**. @@ -119,10 +125,10 @@ read this section on [how to prepare the merge request for a database review](da ## Query Counts -**Summary:** a merge request **should not** increase the number of executed SQL +**Summary:** a merge request **should not** increase the total number of executed SQL queries unless absolutely necessary. -The number of queries executed by the code modified or added by a merge request +The total number of queries executed by the code modified or added by a merge request must not increase unless absolutely necessary. When building features it's entirely possible you will need some extra queries, but you should try to keep this at a minimum. @@ -141,7 +147,7 @@ end This will end up running one query for every object to update. This code can easily overload a database given enough rows to update or many instances of this code running in parallel. This particular problem is known as the -["N+1 query problem"](https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations). You can write a test with [QueryRecoder](query_recorder.md) to detect this and prevent regressions. +["N+1 query problem"](https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations). You can write a test with [QueryRecorder](query_recorder.md) to detect this and prevent regressions. In this particular case the workaround is fairly easy: @@ -152,6 +158,63 @@ objects_to_update.update_all(some_field: some_value) This uses ActiveRecord's `update_all` method to update all rows in a single query. This in turn makes it much harder for this code to overload a database. +## Cached Queries + +**Summary:** a merge request **should not** execute duplicated cached queries. + +Rails provides an [SQL Query Cache](cached_queries.md#cached-queries-guidelines), +used to cache the results of database queries for the duration of the request. + +See [why cached queries are considered bad](cached_queries.md#why-cached-queries-are-considered-bad) and +[how to detect them](cached_queries.md#how-to-detect). + +The code introduced by a merge request, should not execute multiple duplicated cached queries. + +The total number of the queries (including cached ones) executed by the code modified or added by a merge request +should not increase unless absolutely necessary. +The number of executed queries (including cached queries) should not depend on +collection size. +You can write a test by passing the `skip_cached` variable to [QueryRecorder](query_recorder.md) to detect this and prevent regressions. + +As an example, say you have a CI pipeline. All pipeline builds belong to the same pipeline, +thus they also belong to the same project (`pipeline.project`): + +```ruby +pipeline_project = pipeline.project +# Project Load (0.6ms) SELECT "projects".* FROM "projects" WHERE "projects"."id" = $1 LIMIT $2 +build = pipeline.builds.first + +build.project == pipeline_project +# CACHE Project Load (0.0ms) SELECT "projects".* FROM "projects" WHERE "projects"."id" = $1 LIMIT $2 +# => true +``` + +When we call `build.project`, it will not hit the database, it will use the cached result, but it will re-instantiate +same pipeline project object. It turns out that associated objects do not point to the same in-memory object. + +If we try to serialize each build: + +```ruby +pipeline.builds.each do |build| + build.to_json(only: [:name], include: [project: { only: [:name]}]) +end +``` + +It will re-instantiate project object for each build, instead of using the same in-memory object. + +In this particular case the workaround is fairly easy: + +```ruby +pipeline.builds.each do |build| + build.project = pipeline.project + build.to_json(only: [:name], include: [project: { only: [:name]}]) +end +``` + +We can assign `pipeline.project` to each `build.project`, since we know it should point to the same project. +This will allow us that each build point to the same in-memory project, +avoiding the cached SQL query and re-instantiation of the project object for each build. + ## Executing Queries in Loops **Summary:** SQL queries **must not** be executed in a loop unless absolutely @@ -464,7 +527,7 @@ end The usage of shared temporary storage is required if your intent is to persistent file for a disk-based storage, and not Object Storage. -[Workhorse direct_upload](./uploads.md#direct-upload) when accepting file +[Workhorse direct_upload](uploads.md#direct-upload) when accepting file can write it to shared storage, and later GitLab Rails can perform a move operation. The move operation on the same destination is instantaneous. The system instead of performing `copy` operation just re-attaches file into a new place. @@ -488,7 +551,7 @@ that implements a seamless support for Shared and Object Storage-based persisten #### Data access Each feature that accepts data uploads or allows to download them needs to use -[Workhorse direct_upload](./uploads.md#direct-upload). It means that uploads needs to be +[Workhorse direct_upload](uploads.md#direct-upload). It means that uploads needs to be saved directly to Object Storage by Workhorse, and all downloads needs to be served by Workhorse. @@ -500,5 +563,5 @@ can time out, which is especially problematic for slow clients. If clients take to upload/download the processing slot might be killed due to request processing timeout (usually between 30s-60s). -For the above reasons it is required that [Workhorse direct_upload](./uploads.md#direct-upload) is implemented +For the above reasons it is required that [Workhorse direct_upload](uploads.md#direct-upload) is implemented for all file uploads and downloads. diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 71191d1d871..84679a78545 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Migration Style Guide When writing migrations for GitLab, you have to take into account that @@ -376,8 +382,7 @@ Example changes: - `change_column_default` - `create_table` / `drop_table` -NOTE: **Note:** -`with_lock_retries` method **cannot** be used within the `change` method, you must manually define the `up` and `down` methods to make the migration reversible. +The `with_lock_retries` method **cannot** be used within the `change` method, you must manually define the `up` and `down` methods to make the migration reversible. ### How the helper method works @@ -437,7 +442,6 @@ the `with_multiple_threads` block, instead of re-using the global connection pool. This ensures each thread has its own connection object, and won't time out when trying to obtain one. -NOTE: **Note:** PostgreSQL has a maximum amount of connections that it allows. This limit can vary from installation to installation. As a result, it's recommended you do not use more than 32 threads in a single migration. Usually, 4-8 threads @@ -474,6 +478,12 @@ For a small table (such as an empty one or one with less than `1,000` records), it is recommended to use `remove_index` in a single-transaction migration, combining it with other operations that don't require `disable_ddl_transaction!`. +### Disabling an index + +There are certain situations in which you might want to disable an index before removing it. +See the [maintenance operations guide](database/maintenance_operations.md#disabling-an-index) +for more details. + ## Adding indexes Before adding an index, consider if this one is necessary. There are situations in which an index @@ -612,7 +622,6 @@ Before PostgreSQL 11, adding a column with a default was problematic as it would have caused a full table rewrite. The corresponding helper `add_column_with_default` has been deprecated and will be removed in a later release. -NOTE: **Note:** If a backport adding a column with a default value is needed for %12.9 or earlier versions, it should use `add_column_with_default` helper. If a [large table](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3) is involved, backporting to %12.9 is contraindicated. @@ -958,7 +967,6 @@ in a previous migration. ### Example: Add a column `my_column` to the users table -NOTE: **Note:** It is important not to leave out the `User.reset_column_information` command, in order to ensure that the old schema is dropped from the cache and ActiveRecord loads the updated schema information. ```ruby diff --git a/doc/development/module_with_instance_variables.md b/doc/development/module_with_instance_variables.md index 2229c99c99b..80e926f800c 100644 --- a/doc/development/module_with_instance_variables.md +++ b/doc/development/module_with_instance_variables.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Modules with instance variables could be considered harmful ## Background diff --git a/doc/development/multi_version_compatibility.md b/doc/development/multi_version_compatibility.md index 714be296b40..2501f8a169f 100644 --- a/doc/development/multi_version_compatibility.md +++ b/doc/development/multi_version_compatibility.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Compatibility with multiple versions of the application running at the same time When adding or changing features, we must be aware that there may be multiple versions of the application running diff --git a/doc/development/namespaces_storage_statistics.md b/doc/development/namespaces_storage_statistics.md index 5207276ba73..b4a7c8c3132 100644 --- a/doc/development/namespaces_storage_statistics.md +++ b/doc/development/namespaces_storage_statistics.md @@ -1,17 +1,23 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Database case study: Namespaces storage statistics -## Introduction +## Introduction On [Storage and limits management for groups](https://gitlab.com/groups/gitlab-org/-/epics/886), we want to facilitate a method for easily viewing the amount of storage consumed by a group, and allow easy management. -## Proposal +## Proposal 1. Create a new ActiveRecord model to hold the namespaces' statistics in an aggregated form (only for root namespaces). 1. Refresh the statistics in this model every time a project belonging to this namespace is changed. -## Problem +## Problem In GitLab, we update the project storage statistics through a [callback](https://gitlab.com/gitlab-org/gitlab/blob/4ab54c2233e91f60a80e5b6fa2181e6899fdcc3e/app/models/project.rb#L97) @@ -36,7 +42,7 @@ alternative method. ## Attempts -### Attempt A: PostgreSQL materialized view +### Attempt A: PostgreSQL materialized view Model can be updated through a refresh strategy based on a project routes SQL and a [materialized view](https://www.postgresql.org/docs/11/rules-materializedviews.html): @@ -65,7 +71,7 @@ While this implied a single query update (and probably a fast one), it has some - Materialized views syntax varies from PostgreSQL and MySQL. While this feature was worked on, MySQL was still supported by GitLab. - Rails does not have native support for materialized views. We'd need to use a specialized gem to take care of the management of the database views, which implies additional work. -### Attempt B: An update through a CTE +### Attempt B: An update through a CTE Similar to Attempt A: Model update done through a refresh strategy with a [Common Table Expression](https://www.postgresql.org/docs/9.1/queries-with.html) @@ -134,7 +140,7 @@ Even though this approach would make aggregating much easier, it has some major - We'd have to migrate **all namespaces** by adding and filling a new column. Because of the size of the table, dealing with time/cost will not be great. The background migration will take approximately `153h`, see <https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29772>. - Background migration has to be shipped one release before, delaying the functionality by another milestone. -### Attempt E (final): Update the namespace storage statistics in async way +### Attempt E (final): Update the namespace storage statistics in async way This approach consists of keep using the incremental statistics updates we currently already have, but we refresh them through Sidekiq jobs and in different transactions: @@ -164,7 +170,7 @@ The only downside of this approach is that namespaces' statistics are updated up which means there's a time window in which the statistics are inaccurate. Because we're still not [enforcing storage limits](https://gitlab.com/gitlab-org/gitlab/-/issues/17664), this is not a major problem. -## Conclusion +## Conclusion Updating the storage statistics asynchronously, was the less problematic and performant approach of aggregating the root namespaces. diff --git a/doc/development/new_fe_guide/dependencies.md b/doc/development/new_fe_guide/dependencies.md index afdf6e27b37..fad004f9df5 100644 --- a/doc/development/new_fe_guide/dependencies.md +++ b/doc/development/new_fe_guide/dependencies.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Dependencies ## Adding Dependencies diff --git a/doc/development/new_fe_guide/development/accessibility.md b/doc/development/new_fe_guide/development/accessibility.md index 9c63ccad6e1..1189dd1137b 100644 --- a/doc/development/new_fe_guide/development/accessibility.md +++ b/doc/development/new_fe_guide/development/accessibility.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Accessibility Using semantic HTML plays a key role when it comes to accessibility. @@ -6,7 +12,7 @@ Using semantic HTML plays a key role when it comes to accessibility. WAI-ARIA (the Accessible Rich Internet Applications specification) defines a way to make Web content and Web applications more accessible to people with disabilities. -> Note: It is [recommended](https://www.w3.org/TR/using-aria/#notes2) to use semantic elements as the primary method to achieve accessibility rather than adding aria attributes. Adding aria attributes should be seen as a secondary method for creating accessible elements. +The W3C recommends [using semantic elements](https://www.w3.org/TR/using-aria/#notes2) as the primary method to achieve accessibility rather than adding aria attributes. Adding aria attributes should be seen as a secondary method for creating accessible elements. ### Role diff --git a/doc/development/new_fe_guide/development/components.md b/doc/development/new_fe_guide/development/components.md index b7233f5d7c0..1597d4e62e7 100644 --- a/doc/development/new_fe_guide/development/components.md +++ b/doc/development/new_fe_guide/development/components.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Components ## Graphs diff --git a/doc/development/new_fe_guide/development/index.md b/doc/development/new_fe_guide/development/index.md index 119dbc58012..52435ca719d 100644 --- a/doc/development/new_fe_guide/development/index.md +++ b/doc/development/new_fe_guide/development/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Development ## [Components](components.md) diff --git a/doc/development/new_fe_guide/development/performance.md b/doc/development/new_fe_guide/development/performance.md index ad6fdc0b85c..44f5bccde95 100644 --- a/doc/development/new_fe_guide/development/performance.md +++ b/doc/development/new_fe_guide/development/performance.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Performance ## Monitoring diff --git a/doc/development/new_fe_guide/index.md b/doc/development/new_fe_guide/index.md index 9e9c367807f..c9b655c2274 100644 --- a/doc/development/new_fe_guide/index.md +++ b/doc/development/new_fe_guide/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Frontend Development Guidelines This guide contains all the information to successfully contribute to GitLab's frontend. diff --git a/doc/development/new_fe_guide/modules/dirty_submit.md b/doc/development/new_fe_guide/modules/dirty_submit.md index dd336ad3a90..17cdab3f240 100644 --- a/doc/development/new_fe_guide/modules/dirty_submit.md +++ b/doc/development/new_fe_guide/modules/dirty_submit.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Dirty Submit > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21115) in GitLab 11.3. diff --git a/doc/development/new_fe_guide/modules/index.md b/doc/development/new_fe_guide/modules/index.md index a7820442df0..18c5b05432c 100644 --- a/doc/development/new_fe_guide/modules/index.md +++ b/doc/development/new_fe_guide/modules/index.md @@ -1,5 +1,15 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Modules - [DirtySubmit](dirty_submit.md) Disable form submits until there are unsaved changes. + +- [Merge Request widget extensions](widget_extensions.md) + + Easily add extensions into the merge request widget diff --git a/doc/development/new_fe_guide/modules/widget_extensions.md b/doc/development/new_fe_guide/modules/widget_extensions.md new file mode 100644 index 00000000000..3844fedb126 --- /dev/null +++ b/doc/development/new_fe_guide/modules/widget_extensions.md @@ -0,0 +1,56 @@ +--- +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/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Merge request widget extensions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44616) in GitLab 13.6. + +## Summary + +Extensions in the merge request widget allow for others team to quickly and easily add new features +into the widget that will match the existing design and interaction as other extensions. + +## Usage + +To use extensions you need to first create a new extension object that will be used to fetch the +data that will be rendered in the extension. See the example file in +app/assets/javascripts/vue_merge_request_widget/extensions/issues.js for a working example. + +The basic object structure is as below: + +```javascript +export default { + name: '', + props: [], + computed: { + summary() {}, + statusIcon() {}, + }, + methods: { + fetchCollapsedData() {}, + fetchFullData() {}, + }, +}; +``` + +Following the same data structure allows each extension to follow the same registering structure +but allows for each extension to manage where it gets its own data from. + +After creating this structure you need to register it. Registering the extension can happen at any +point _after_ the widget has been created. + +To register a extension the following can be done: + +```javascript +// Import the register method +import { registerExtension } from '~/vue_merge_request_widget/components/extensions'; + +// Import the new extension +import issueExtension from '~/vue_merge_request_widget/extensions/issues'; + +// Register the imported extension +registerExtension(issueExtension); +``` diff --git a/doc/development/new_fe_guide/tips.md b/doc/development/new_fe_guide/tips.md index c65266a3f25..d7e9c440335 100644 --- a/doc/development/new_fe_guide/tips.md +++ b/doc/development/new_fe_guide/tips.md @@ -1,3 +1,9 @@ +--- +stage: none +group: Development +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Tips ## Clearing production compiled assets diff --git a/doc/development/newlines_styleguide.md b/doc/development/newlines_styleguide.md index e298ba1d935..f123482fa5a 100644 --- a/doc/development/newlines_styleguide.md +++ b/doc/development/newlines_styleguide.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Newlines style guide This style guide recommends best practices for newlines in Ruby code. diff --git a/doc/development/omnibus.md b/doc/development/omnibus.md index deaf72d2ecf..84c395e2e57 100644 --- a/doc/development/omnibus.md +++ b/doc/development/omnibus.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # What you should know about Omnibus packages Most users install GitLab using our Omnibus packages. As a developer it can be diff --git a/doc/development/ordering_table_columns.md b/doc/development/ordering_table_columns.md index 18788d0b86e..124f82ac2c8 100644 --- a/doc/development/ordering_table_columns.md +++ b/doc/development/ordering_table_columns.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Ordering Table Columns in PostgreSQL For GitLab we require that columns of new tables are ordered to use the @@ -45,7 +51,6 @@ In these examples, the `id` and `user_id` columns are packed together, which means we only need 8 bytes to store _both_ of them. This in turn means each row will require 8 bytes less space. -Note: **NOTE:** Since Ruby on Rails 5.1, the default data type for IDs is `bigint`, which uses 8 bytes. We are using `integer` in the examples to showcase a more realistic reordering scenario. diff --git a/doc/development/packages.md b/doc/development/packages.md index 9eae99ff890..de6cac2ce73 100644 --- a/doc/development/packages.md +++ b/doc/development/packages.md @@ -13,12 +13,13 @@ See already supported package types in [Packages documentation](../administratio Since GitLab packages' UI is pretty generic, it is possible to add basic new package system support with solely backend changes. This guide is superficial and does not cover the way the code should be written. However, you can find a good example -by looking at merge requests with Maven and NPM support: +by looking at the following merge requests: - [NPM registry support](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8673). -- [Conan repository](https://gitlab.com/gitlab-org/gitlab/-/issues/8248). - [Maven repository](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6607). -- [Instance level endpoint for Maven repository](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8757) +- [Composer repository for PHP dependencies](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22415). +- [Terraform modules registry](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834). +- [Instance-level endpoint for Maven repository](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8757). ## General information diff --git a/doc/development/performance.md b/doc/development/performance.md index 3b59393bae6..e20633a05f6 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Performance Guidelines This document describes various guidelines to follow to ensure good and @@ -334,15 +340,49 @@ These results can also be placed into a PostgreSQL database by setting the `RSPEC_PROFILING_POSTGRES_URL` variable. This is used to profile the test suite when running in the CI environment. -We store these results also when running CI jobs on the default branch on -`gitlab.com`. Statistics of these profiling data are [available -online](https://gitlab-org.gitlab.io/rspec_profiling_stats/). For example, -you can find which tests take longest to run or which execute the most +We store these results also when running nightly scheduled CI jobs on the +default branch on `gitlab.com`. Statistics of these profiling data are +[available online](https://gitlab-org.gitlab.io/rspec_profiling_stats/). For +example, you can find which tests take longest to run or which execute the most queries. This can be handy for optimizing our tests or identifying performance issues in our code. ## Memory profiling +We can use two approaches, often in combination, to track down memory issues: + +- Leaving the code intact and wrapping a profiler around it. +- Monitor memory usage of the process while disabling/enabling different parts of the code we suspect could be problematic. + +### Using Memory Profiler + +We can use `memory_profiler` for profiling. + +The [`memory_profiler`](https://github.com/SamSaffron/memory_profiler) gem is already present in GitLab's `Gemfile`, +you just need to require it: + +```ruby +require 'sidekiq/testing' + +report = MemoryProfiler.report do + # Code you want to profile +end + +output = File.open('/tmp/profile.txt','w') +report.pretty_print(output) +``` + +The report breaks down 2 key concepts: + +- Retained: long lived memory use and object count retained due to the execution of the code block. +- Allocated: all object allocation and memory allocation during code block. + +As a general rule, **retained** will always be smaller than or equal to allocated. + +The actual RSS cost will always be slightly higher as MRI heaps are not squashed to size and memory fragments. + +### Rbtrace + One of the reasons of the increased memory footprint could be Ruby memory fragmentation. To diagnose it, you can visualize Ruby heap as described in [this post by Aaron Patterson](https://tenderlovemaking.com/2017/09/27/visualizing-your-ruby-heap.html). diff --git a/doc/development/permissions.md b/doc/development/permissions.md index e930345caec..859c838280e 100644 --- a/doc/development/permissions.md +++ b/doc/development/permissions.md @@ -1,3 +1,9 @@ +--- +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab permissions guide There are multiple types of permissions across GitLab, and when implementing diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md index d12220d8c95..a8ef5701d50 100644 --- a/doc/development/pipelines.md +++ b/doc/development/pipelines.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Pipelines for the GitLab project Pipelines for <https://gitlab.com/gitlab-org/gitlab> and <https://gitlab.com/gitlab-org/gitlab-foss> (as well as the @@ -618,7 +624,7 @@ each pipeline includes default variables defined in Most of the jobs [extend from a few CI definitions](../ci/yaml/README.md#extends) defined in [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/global.gitlab-ci.yml) -that are scoped to a single [configuration parameter](../ci/yaml/README.md#configuration-parameters). +that are scoped to a single [configuration keyword](../ci/yaml/README.md#job-keywords). | Job definitions | Description | |------------------|-------------| diff --git a/doc/development/policies.md b/doc/development/policies.md index 8dfd4763551..b44367f7075 100644 --- a/doc/development/policies.md +++ b/doc/development/policies.md @@ -1,3 +1,9 @@ +--- +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # `DeclarativePolicy` framework The DeclarativePolicy framework is designed to assist in performance of policy checks, and to enable ease of extension for EE. The DSL code in `app/policies` is what `Ability.allowed?` uses to check whether a particular action is allowed on a subject. diff --git a/doc/development/polling.md b/doc/development/polling.md index 47cfc32d934..b06507787b0 100644 --- a/doc/development/polling.md +++ b/doc/development/polling.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Polling with ETag caching Polling for changes (repeatedly asking server if there are any new changes) diff --git a/doc/development/polymorphic_associations.md b/doc/development/polymorphic_associations.md index b6567704d8e..66ea974063a 100644 --- a/doc/development/polymorphic_associations.md +++ b/doc/development/polymorphic_associations.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Polymorphic Associations **Summary:** always use separate tables instead of polymorphic associations. diff --git a/doc/development/post_deployment_migrations.md b/doc/development/post_deployment_migrations.md index 4d523178a21..2550f9547df 100644 --- a/doc/development/post_deployment_migrations.md +++ b/doc/development/post_deployment_migrations.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Post Deployment Migrations Post deployment migrations are regular Rails migrations that can optionally be diff --git a/doc/development/product_analytics/event_dictionary.md b/doc/development/product_analytics/event_dictionary.md index b049db21c30..88cb75fdb83 100644 --- a/doc/development/product_analytics/event_dictionary.md +++ b/doc/development/product_analytics/event_dictionary.md @@ -1,32 +1,5 @@ --- -stage: Growth -group: Product Analytics -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +redirect_to: 'https://about.gitlab.com/handbook/product/product-analytics-guide/' --- -# Event Dictionary - -**Note: We've temporarily moved the Event Dictionary to a [Google Sheet](https://docs.google.com/spreadsheets/d/1VzE8R72Px_Y_LlE3Z05LxUlG_dumWe3vl-HeUo70TPw/edit?usp=sharing)**. The previous Markdown table exceeded 600 rows making it difficult to manage. In the future, our intention is to move this back into our docs using a [YAML file](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/823). - -The event dictionary is a single source of truth for the metrics and events we collect for product usage data. The Event Dictionary lists all the metrics and events we track, why we're tracking them, and where they are tracked. - -This is a living document that is updated any time a new event is planned or implemented. It includes the following information. - -- Section, stage, or group -- Description -- Implementation status -- Availability by plan type -- Code path - -We're currently focusing our Event Dictionary on [Usage Ping](usage_ping.md). In the future, we will also include [Snowplow](snowplow.md). We currently have an initiative across the entire product organization to complete the [Event Dictionary for Usage Ping](https://gitlab.com/groups/gitlab-org/-/epics/4174). - -## Instructions - -1. Open the Event Dictionary and fill in all the **PM to edit** columns highlighted in yellow. -1. Check that all the metrics and events are assigned to the correct section, stage, or group. If a metric is used across many groups, assign it to the stage. If a metric is used across many stages, assign it to the section. If a metric is incorrectly assigned to another section, stage, or group, let the PM know you have reassigned it. If your group has no assigned metrics and events, check that your metrics and events are not incorrectly assigned to another PM. -1. Add descriptions of what your metrics and events are tracking. Work with your Engineering team or the Product Analytics team if you need help understanding this. -1. Add what plans this metric is available on. Work with your Engineering team or the Product Analytics team if you need help understanding this. - -## Planned metrics and events - -For future metrics and events you plan to track, please add them to the Event Dictionary and note the status as `Planned`, `In Progress`, or `Implemented`. Once you have confirmed the metric has been implemented and have confirmed the metric data is in our data warehouse, change the status to **Data Available**. +This document was moved to [another location](https://about.gitlab.com/handbook/product/product-analytics-guide/). diff --git a/doc/development/product_analytics/index.md b/doc/development/product_analytics/index.md index ab76d6f0561..88cb75fdb83 100644 --- a/doc/development/product_analytics/index.md +++ b/doc/development/product_analytics/index.md @@ -1,182 +1,5 @@ --- -stage: Growth -group: Product Analytics -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +redirect_to: 'https://about.gitlab.com/handbook/product/product-analytics-guide/' --- -# Product Analytics Guide - -At GitLab, we collect product usage data for the purpose of helping us build a better product. Data helps GitLab understand which parts of the product need improvement and which features we should build next. Product usage data also helps our team better understand the reasons why people use GitLab. With this knowledge we are able to make better product decisions. - -We encourage users to enable tracking, and we embrace full transparency with our tracking approach so it can be easily understood and trusted. - -By enabling tracking, users can: - -- Contribute back to the wider community. -- Help GitLab improve on the product. - -## Our tracking tools - -We use three methods to gather product usage data: - -- [Snowplow](#snowplow) -- [Usage Ping](#usage-ping) -- [Database import](#database-import) - -### Snowplow - -Snowplow is an enterprise-grade marketing and product analytics platform which helps track the way -users engage with our website and application. - -Snowplow consists of two components: - -- [Snowplow JS](https://github.com/snowplow/snowplow/wiki/javascript-tracker) tracks client-side - events. -- [Snowplow Ruby](https://github.com/snowplow/snowplow/wiki/ruby-tracker) tracks server-side events. - -For more details, read the [Snowplow](snowplow.md) guide. - -### Usage Ping - -Usage Ping is a method for GitLab Inc to collect usage data on a GitLab instance. Usage Ping is primarily composed of row counts for different tables in the instance’s database. By comparing these counts month over month (or week over week), we can get a rough sense for how an instance is using the different features within the product. This high-level data is used to help our product, support, and sales teams. - -For more details, read the [Usage Ping](usage_ping.md) guide. - -### Database import - -Database imports are full imports of data into GitLab's data warehouse. For GitLab.com, the PostgreSQL database is loaded into Snowflake data warehouse every 6 hours. For more details, see the [data team handbook](https://about.gitlab.com/handbook/business-ops/data-team/platform/#extract-and-load). - -## What data can be tracked - -Our different tracking tools allows us to track different types of events. The event types and examples of what data can be tracked are outlined below. - -The availability of event types and their tracking tools varies by segment. For example, on Self-Managed Users, we only have reporting using Database records via Usage Ping. - -| Event Types | SaaS Instance | SaaS Plan | SaaS Group | SaaS Session | SaaS User | SM Instance | SM Plan | SM Group | SM Session | SM User | -|----------------------------------------|---------------|-----------|------------|--------------|-----------|-------------|---------|----------|------------|---------| -| Snowplow (JS Pageview events) | ✅ | 📅 | 📅 | ✅ | 📅 | 📅 | 📅 | 📅 | 📅 | 📅 | -| Snowplow (JS UI events) | ✅ | 📅 | 📅 | ✅ | 📅 | 📅 | 📅 | 📅 | 📅 | 📅 | -| Snowplow (Ruby Pageview events) | ✅ | 📅 | 📅 | ✅ | 📅 | 📅 | 📅 | 📅 | 📅 | 📅 | -| Snowplow (Ruby CRUD / API events) | ✅ | 📅 | 📅 | ✅ | 📅 | 📅 | 📅 | 📅 | 📅 | 📅 | -| Usage Ping (Redis UI counters) | 🔄 | 🔄 | 🔄 | ✖️ | 🔄 | 🔄 | 🔄 | 🔄 | ✖️ | 🔄 | -| Usage Ping (Redis Pageview counters) | 🔄 | 🔄 | 🔄 | ✖️ | 🔄 | 🔄 | 🔄 | 🔄 | ✖️ | 🔄 | -| Usage Ping (Redis CRUD / API counters) | 🔄 | 🔄 | 🔄 | ✖️ | 🔄 | 🔄 | 🔄 | 🔄 | ✖️ | 🔄 | -| Usage Ping (Database counters) | ✅ | 🔄 | 📅 | ✖️ | ✅ | ✅ | ✅ | ✅ | ✖️ | ✅ | -| Usage Ping (Instance settings) | ✅ | 🔄 | 📅 | ✖️ | ✅ | ✅ | ✅ | ✅ | ✖️ | ✅ | -| Usage Ping (Integration settings) | ✅ | 🔄 | 📅 | ✖️ | ✅ | ✅ | ✅ | ✅ | ✖️ | ✅ | -| Database import (Database records) | ✅ | ✅ | ✅ | ✖️ | ✅ | ✖️ | ✖️ | ✖️ | ✖️ | ✖️ | - -[Source file](https://docs.google.com/spreadsheets/d/1e8Afo41Ar8x3JxAXJF3nL83UxVZ3hPIyXdt243VnNuE/edit?usp=sharing) - -**Legend** - -✅ Available, 🔄 In Progress, 📅 Planned, ✖️ Not Possible - -SaaS = GitLab.com. SM = Self-Managed instance - -### Pageview events - -- Number of sessions that visited the /dashboard/groups page - -### UI events - -- Number of sessions that clicked on a button or link -- Number of sessions that closed a modal - -UI events are any interface-driven actions from the browser including click data. - -### CRUD or API events - -- Number of Git pushes -- Number of GraphQL queries -- Number of requests to a Rails action or controller - -These are backend events that include the creation, read, update, deletion of records, and other events that might be triggered from layers other than those available in the interface. - -### Database records - -These are raw database records which can be explored using business intelligence tools like Sisense. The full list of available tables can be found in [structure.sql](https://gitlab.com/gitlab-org/gitlab/-/blob/master/db/structure.sql). - -### Instance settings - -These are settings of your instance such as the instance's Git version and if certain features are enabled such as `container_registry_enabled`. - -### Integration settings - -These are integrations your GitLab instance interacts with such as an [external storage provider](../../administration/static_objects_external_storage.md) or an [external container registry](../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint). These services must be able to send data back into a GitLab instance for data to be tracked. - -## Reporting level - -Our reporting levels of aggregate or individual reporting varies by segment. For example, on Self-Managed Users, we can report at an aggregate user level using Usage Ping but not on an Individual user level. - -| Aggregated Reporting | SaaS Instance | SaaS Plan | SaaS Group | SaaS Session | SaaS User | SM Instance | SM Plan | SM Group | SM Session | SM User | -|----------------------|---------------|-----------|------------|--------------|-----------|-------------|---------|----------|------------|---------| -| Snowplow | ✅ | 📅 | 📅 | ✅ | 📅 | ✅ | 📅 | 📅 | ✅ | 📅 | -| Usage Ping | ✅ | 🔄 | 📅 | 📅 | ✅ | ✅ | ✅ | ✅ | 📅 | ✅ | -| Database import | ✅ | ✅ | ✅ | ✖️ | ✅ | ✖️ | ✖️ | ✖️ | ✖️ | ✖️ | - -| Identifiable Reporting | SaaS Instance | SaaS Plan | SaaS Group | SaaS Session | SaaS User | SM Instance | SM Plan | SM Group | SM Session | SM User | -|------------------------|---------------|-----------|------------|--------------|-----------|-------------|---------|----------|------------|---------| -| Snowplow | ✅ | 📅 | 📅 | ✅ | 📅 | ✖️ | ✖️ | ✖️ | ✖️ | ✖️ | -| Usage Ping | ✅ | 🔄 | 📅 | ✖️ | ✖️ | ✅ | ✅ | ✖️ | ✖️ | ✖️ | -| Database import | ✅ | ✅ | ✅ | ✖️ | ✅ | ✖️ | ✖️ | ✖️ | ✖️ | ✖️ | - -**Legend** - -✅ Available, 🔄 In Progress, 📅 Planned, ✖️ Not Possible - -SaaS = GitLab.com. SM = Self-Managed instance - -## Reporting time period - -Our reporting time periods varies by segment. For example, on Self-Managed Users, we can report all time counts and 28 day counts in Usage Ping. - -| Reporting Time Period | All Time | 28 Days | 7 Days | Daily | -|-----------------------|----------|---------|--------|-------| -| Snowplow | ✅ | ✅ | ✅ | ✅ | -| Usage Ping | ✅ | ✅ | 📅 | ✖️ | -| Database import | ✅ | ✅ | ✅ | ✅ | - -**Legend** - -✅ Available, 🔄 In Progress, 📅 Planned, ✖️ Not Possible - -## Systems overview - -The systems overview is a simplified diagram showing the interactions between GitLab Inc and self-managed instances. - - - -[Source file](https://app.diagrams.net/#G13DVpN-XnhWGz9tqReIj8pp1UE4ehk_EC) - -### GitLab Inc - -For Product Analytics purposes, GitLab Inc has three major components: - -1. [Data Infrastructure](https://about.gitlab.com/handbook/business-ops/data-team/platform/infrastructure/): This contains everything managed by our data team including Sisense Dashboards for visualization, Snowflake for Data Warehousing, incoming data sources such as PostgreSQL Pipeline and S3 Bucket, and lastly our data collectors [GitLab.com's Snowplow Collector](https://gitlab.com/gitlab-com/gl-infra/readiness/-/tree/master/library/snowplow/) and GitLab's Versions Application. -1. GitLab.com: This is the production GitLab application which is made up of a Client and Server. On the Client or browser side, a Snowplow JS Tracker (Frontend) is used to track client-side events. On the Server or application side, a Snowplow Ruby Tracker (Backend) is used to track server-side events. The server also contains Usage Ping which leverages a PostgreSQL database and a Redis in-memory data store to report on usage data. Lastly, the server also contains System Logs which are generated from running the GitLab application. -1. [Monitoring infrastructure](https://about.gitlab.com/handbook/engineering/monitoring/): This is the infrastructure used to ensure GitLab.com is operating smoothly. System Logs are sent from GitLab.com to our monitoring infrastructure and collected by a FluentD collector. From FluentD, logs are either sent to long term Google Cloud Services cold storage via Stackdriver, or, they are sent to our Elastic Cluster via Cloud Pub/Sub which can be explored in real-time using Kibana. - -### Self-managed - -For Product Analytics purposes, self-managed instances have two major components: - -1. Data infrastructure: Having a data infrastructure setup is optional on self-managed instances. If you'd like to collect Snowplow tracking events for your self-managed instance, you can setup your own self-managed Snowplow collector and configure your Snowplow events to point to your own collector. -1. GitLab: A self-managed GitLab instance contains all of the same components as GitLab.com mentioned above. - -### Differences between GitLab Inc and Self-managed - -As shown by the orange lines, on GitLab.com Snowplow JS, Snowplow Ruby, Usage Ping, and PostgreSQL database imports all flow into GitLab Inc's data infrastructure. However, on self-managed, only Usage Ping flows into GitLab Inc's data infrastructure. - -As shown by the green lines, on GitLab.com system logs flow into GitLab Inc's monitoring infrastructure. On self-managed, there are no logs sent to GitLab Inc's monitoring infrastructure. - -Note (1): Snowplow JS and Snowplow Ruby are available on self-managed, however, the Snowplow Collector endpoint is set to a self-managed Snowplow Collector which GitLab Inc does not have access to. - -## Additional information - -More useful links: - -- [Product Analytics Direction](https://about.gitlab.com/direction/product-analytics/) -- [Data Analysis Process](https://about.gitlab.com/handbook/business-ops/data-team/#data-analysis-process/) -- [Data for Product Managers](https://about.gitlab.com/handbook/business-ops/data-team/programs/data-for-product-managers/) -- [Data Infrastructure](https://about.gitlab.com/handbook/business-ops/data-team/platform/infrastructure/) +This document was moved to [another location](https://about.gitlab.com/handbook/product/product-analytics-guide/). diff --git a/doc/development/product_analytics/snowplow.md b/doc/development/product_analytics/snowplow.md index 21d92566ffd..c5f48994d5c 100644 --- a/doc/development/product_analytics/snowplow.md +++ b/doc/development/product_analytics/snowplow.md @@ -10,7 +10,7 @@ This guide provides an overview of how Snowplow works, and implementation detail For more information about Product Analytics, see: -- [Product Analytics Guide](index.md) +- [Product Analytics Guide](https://about.gitlab.com/handbook/product/product-analytics-guide/) - [Usage Ping Guide](usage_ping.md) More useful links: @@ -52,7 +52,7 @@ Tracking can be enabled at: - The instance level, which enables tracking on both the frontend and backend layers. - User level, though user tracking can be disabled on a per-user basis. GitLab tracking respects the [Do Not Track](https://www.eff.org/issues/do-not-track) standard, so any user who has enabled the Do Not Track option in their browser is not tracked at a user level. -We utilize Snowplow for the majority of our tracking strategy and it is enabled on GitLab.com. On a self-managed instance, Snowplow can be enabled by navigating to: +We use Snowplow for the majority of our tracking strategy and it is enabled on GitLab.com. On a self-managed instance, Snowplow can be enabled by navigating to: - **Admin Area > Settings > General** in the UI. - `admin/application_settings/integrations` in your browser. @@ -112,7 +112,7 @@ The current method provides several attributes that are sent on each click event ## Implementing Snowplow JS (Frontend) tracking -GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tracker](https://github.com/snowplow/snowplow/wiki/javascript-tracker) for tracking custom events. There are a few ways to utilize tracking, but each generally requires at minimum, a `category` and an `action`. Additional data can be provided that adheres to our [Structured event taxonomy](#structured-event-taxonomy). +GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tracker](https://github.com/snowplow/snowplow/wiki/javascript-tracker) for tracking custom events. There are a few ways to use tracking, but each generally requires at minimum, a `category` and an `action`. Additional data can be provided that adheres to our [Structured event taxonomy](#structured-event-taxonomy). | field | type | default value | description | |:-----------|:-------|:---------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -294,7 +294,7 @@ Custom event tracking and instrumentation can be added by directly calling the ` | `action` | string | 'generic' | The action being taken, which can be anything from a controller action like `create` to something like an Active Record callback. | | `data` | object | {} | Additional data such as `label`, `property`, `value`, and `context` as described in [Structured event taxonomy](#structured-event-taxonomy). These are set as empty strings if you don't provide them. | -Tracking can be viewed as either tracking user behavior, or can be utilized for instrumentation to monitor and visualize performance over time in an area or aspect of code. +Tracking can be viewed as either tracking user behavior, or can be used for instrumentation to monitor and visualize performance over time in an area or aspect of code. For example: diff --git a/doc/development/product_analytics/usage_ping.md b/doc/development/product_analytics/usage_ping.md index d482af77d8a..fa785d934cb 100644 --- a/doc/development/product_analytics/usage_ping.md +++ b/doc/development/product_analytics/usage_ping.md @@ -15,7 +15,7 @@ This guide describes Usage Ping's purpose and how it's implemented. For more information about Product Analytics, see: -- [Product Analytics Guide](index.md) +- [Product Analytics Guide](https://about.gitlab.com/handbook/product/product-analytics-guide/) - [Snowplow Guide](snowplow.md) More useful links: @@ -270,7 +270,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF ##### Adding new events -1. Define events in [`known_events.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events.yml). +1. Define events in [`known_events`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/). Example event: @@ -312,6 +312,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF - `aggregation`: aggregation `:daily` or `:weekly`. The argument defines how we build the Redis keys for data storage. For `daily` we keep a key for metric per day of the year, for `weekly` we keep a key for metric per week of the year. + - `feature_flag`: optional. For details, see our [GitLab internal Feature flags](../feature_flags/) documentation. 1. Track event in controller using `RedisTracking` module with `track_redis_hll_event(*controller_actions, name:, feature:, feature_default_enabled: false)`. @@ -402,7 +403,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF | `event` | string | yes | The event name it should be tracked | Response -w + Return 200 if tracking failed for any reason. - `200` if event was tracked or any errors @@ -412,7 +413,7 @@ w 1. Track events using JavaScript/Vue API helper which calls the API above - Example usage for an existing event already defined in [known events](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events.yml): + Example usage for an existing event already defined in [known events](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/): Note that `usage_data_api` and `usage_data_#{event_name}` should be enabled in order to be able to track events @@ -422,20 +423,46 @@ w api.trackRedisHllUserEvent('my_already_defined_event_name'), ``` -1. Track event using base module `Gitlab::UsageDataCounters::HLLRedisCounter.track_event(entity_id, event_name)`. +1. Track event using base module `Gitlab::UsageDataCounters::HLLRedisCounter.track_event(values, event_name)`. + + Arguments: + + - `values`: One value or array of values we count. For example: user_id, visitor_id, user_ids. + - `event_name`: event name. + +1. Track event on context level using base module `Gitlab::UsageDataCounters::HLLRedisCounter.track_event_in_context(entity_id, event_name, context)`. Arguments: - `entity_id`: value we count. For example: user_id, visitor_id. - `event_name`: event name. + - `context`: context value. Allowed values are `default`, `free`, `bronze`, `silver`, `gold`, `starter`, `premium`, `ultimate` -1. Get event data using `Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names:, start_date:, end_date)`. +1. Get event data using `Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names:, start_date:, end_date:, context: '')`. Arguments: - `event_names`: the list of event names. - `start_date`: start date of the period for which we want to get event data. - `end_date`: end date of the period for which we want to get event data. + - `context`: context of the event. Allowed values are `default`, `free`, `bronze`, `silver`, `gold`, `starter`, `premium`, `ultimate`. + +1. Testing tracking and getting unique events + +Trigger events in rails console by using `track_event` method + + ```ruby + Gitlab::UsageDataCounters::HLLRedisCounter.track_event(1, 'g_compliance_audit_events') + Gitlab::UsageDataCounters::HLLRedisCounter.track_event(2, 'g_compliance_audit_events') + ``` + +Next, get the unique events for the current week. + + ```ruby + # Get unique events for metric for current_week + Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names: 'g_compliance_audit_events', + start_date: Date.current.beginning_of_week, end_date: Date.current.end_of_week) + ``` Recommendations: @@ -445,9 +472,23 @@ Recommendations: - Use a [feature flag](../../operations/feature_flags.md) to have a control over the impact when adding new metrics. +##### Enable/Disable Redis HLL tracking + +Events are tracked behind [feature flags](../feature_flags/index.md) due to concerns for Redis performance and scalability. + +For a full list of events and coresponding feature flags see, [known_events](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/) files. + +To enable or disable tracking for specific event within <https://gitlab.com> or <https://staging.gitlab.com>, run commands such as the following to +[enable or disable the corresponding feature](../feature_flags/index.md). + +```shell +/chatops run feature set <feature_name> true +/chatops run feature set <feature_name> false +``` + ##### Known events in usage data payload -All events added in [`known_events.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events.yml) are automatically added to usage data generation under the `redis_hll_counters` key. This column is stored in [version-app as a JSON](https://gitlab.com/gitlab-services/version-gitlab-com/-/blob/master/db/schema.rb#L209). +All events added in [`known_events/common.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/common.yml) are automatically added to usage data generation under the `redis_hll_counters` key. This column is stored in [version-app as a JSON](https://gitlab.com/gitlab-services/version-gitlab-com/-/blob/master/db/schema.rb#L209). 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](#adding-new-events) events and data for the last complete week for weekly [aggregation](#adding-new-events) events. @@ -493,7 +534,7 @@ Example usage: redis_usage_data(Gitlab::UsageDataCounters::WikiPageCounter) redis_usage_data { ::Gitlab::UsageCounters::PodLogs.usage_totals[:total] } -# Define events in known_events.yml https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events.yml +# 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(visitor_id, 'expand_vulnerabilities') @@ -548,7 +589,17 @@ for how to use its API to query for data. ## Developing and testing Usage Ping -### 1. Use your Rails console to manually test counters +### 1. Naming and placing the metrics + +Add the metric in one of the top level keys + +- `license`: for license related metrics. +- `settings`: for settings related metrics. +- `counts_weekly`: for counters that have data for the most recent 7 days. +- `counts_monthly`: for counters that have data for the most recent 28 days. +- `counts`: for counters that have data for all time. + +### 2. Use your Rails console to manually test counters ```ruby # count @@ -560,7 +611,7 @@ Gitlab::UsageData.distinct_count(::Project, :creator_id) Gitlab::UsageData.distinct_count(::Note.with_suggestions.where(time_period), :author_id, start: ::User.minimum(:id), finish: ::User.maximum(:id)) ``` -### 2. Generate the SQL query +### 3. Generate the SQL query Your Rails console will return the generated SQL queries. @@ -574,7 +625,7 @@ pry(main)> Gitlab::UsageData.count(User.active) (1.9ms) SELECT COUNT("users"."id") FROM "users" WHERE ("users"."state" IN ('active')) AND ("users"."user_type" IS NULL OR "users"."user_type" IN (6, 4)) AND "users"."id" BETWEEN 1 AND 100000 ``` -### 3. Optimize queries with #database-lab +### 4. Optimize queries with #database-lab Paste the SQL query into `#database-lab` to see how the query performs at scale. @@ -601,27 +652,27 @@ We also use `#database-lab` and [explain.depesz.com](https://explain.depesz.com/ - Avoid joins and write the queries as simply as possible, [example](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36316). - Set a custom `batch_size` for `distinct_count`, [example](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38000). -### 4. Add the metric definition +### 5. Add the metric definition -When adding, changing, or updating metrics, please update the [Event Dictionary's **Usage Ping** table](event_dictionary.md). +When adding, changing, or updating metrics, please update the [Event Dictionary's **Usage Ping** table](https://about.gitlab.com/handbook/product/product-analytics-guide#event-dictionary). -### 5. Add new metric to Versions Application +### 6. Add new metric to Versions Application Check if new metrics need to be added to the Versions Application. See `usage_data` [schema](https://gitlab.com/gitlab-services/version-gitlab-com/-/blob/master/db/schema.rb#L147) and usage data [parameters accepted](https://gitlab.com/gitlab-services/version-gitlab-com/-/blob/master/app/services/usage_ping.rb). Any metrics added under the `counts` key are saved in the `stats` column. -### 6. Add the feature label +### 7. Add the feature label Add the `feature` label to the Merge Request for new Usage Ping metrics. These are user-facing changes and are part of expanding the Usage Ping feature. -### 7. Add a changelog file +### 8. Add a changelog file Ensure you comply with the [Changelog entries guide](../changelog.md). -### 8. Ask for a Product Analytics Review +### 9. Ask for a Product Analytics Review On GitLab.com, we have DangerBot setup to monitor Product Analytics related files and DangerBot will recommend a Product Analytics review. Mention `@gitlab-org/growth/product_analytics/engineers` in your MR for a review. -### 9. Verify your metric +### 10. Verify your metric On GitLab.com, the Product Analytics team regularly monitors Usage Ping. They may alert you that your metrics need further optimization to run quicker and with greater success. You may also use the [Usage Ping QA dashboard](https://app.periscopedata.com/app/gitlab/632033/Usage-Ping-QA) to check how well your metric performs. The dashboard allows filtering by GitLab version, by "Self-managed" & "Saas" and shows you how many failures have occurred for each metric. Whenever you notice a high failure rate, you may re-optimize your metric. @@ -671,6 +722,59 @@ with any of the other services that are running. That is not how node metrics ar always runs as a process alongside other GitLab components on any given node. From Usage Ping's perspective none of the node data would therefore appear to be associated to any of the services running, since they all appear to be running on different hosts. To alleviate this problem, the `node_exporter` in GCK was arbitrarily "assigned" to the `web` service, meaning only for this service `node_*` metrics will appear in Usage Ping. +## Aggregated metrics + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45979) in GitLab 13.6. +> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - It's enabled on GitLab.com. + +CAUTION: **Warning:** +This feature is intended solely for internal GitLab use. + +In order to add data for aggregated metrics into Usage Ping payload you should add corresponding definition into [`aggregated_metrics.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/aggregated_metrics.yml) file. Each aggregate definition includes following parts: + +- name: unique name under which aggregate metric will be added to Usage Ping payload +- operator: operator that defines how aggregated metric data will be counted. Available operators are: + - `OR`: removes duplicates and counts all entries that triggered any of listed events + - `AND`: removes duplicates and counts all elements that were observed triggering all of following events +- events: list of events names (from [`known_events.yml`](#known-events-in-usage-data-payload)) to aggregate into metric. All events in this list must have the same `redis_slot` and `aggregation` attributes. +- feature_flag: name of [development feature flag](../feature_flags/development.md#development-type) that will be checked before +metrics aggregation is performed. Corresponding feature flag should have `default_enabled` attribute set to `false`. +`feature_flag` attribute is **OPTIONAL** and can be omitted, when `feature_flag` is missing no feature flag will be checked. + +Example aggregated metric entries: + +```yaml +- name: product_analytics_test_metrics_union + operator: OR + events: ['i_search_total', 'i_search_advanced', 'i_search_paid'] +- name: product_analytics_test_metrics_intersection_with_feautre_flag + operator: AND + events: ['i_search_total', 'i_search_advanced', 'i_search_paid'] + feature_flag: example_aggregated_metric +``` + +Aggregated metrics will be added under `aggregated_metrics` key in both `counts_weekly` and `counts_monthly` top level keys in Usage Ping payload. + +```ruby +{ + :counts_monthly => { + :deployments => 1003, + :successful_deployments => 78, + :failed_deployments => 275, + :packages => 155, + :personal_snippets => 2106, + :project_snippets => 407, + :promoted_issues => 719, + :aggregated_metrics => { + :product_analytics_test_metrics_union => 7, + :product_analytics_test_metrics_intersection_with_feautre_flag => 2 + }, + :snippets => 2513 + } +} +``` + ## Example Usage Ping payload The following is example content of the Usage Ping payload. @@ -935,3 +1039,7 @@ bin/rake gitlab:usage_data:dump_sql_in_json # You may pipe the output into a file bin/rake gitlab:usage_data:dump_sql_in_yaml > ~/Desktop/usage-metrics-2020-09-02.yaml ``` + +## Generating and troubleshooting usage ping + +To get a usage ping, or to troubleshoot caching issues on your GitLab instance, please follow [instructions to generate usage ping](../../administration/troubleshooting/gitlab_rails_cheat_sheet.md#generate-usage-ping). diff --git a/doc/development/profiling.md b/doc/development/profiling.md index f5a4d1edb92..6e1b81e659d 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Profiling To make it easier to track down performance problems GitLab comes with a set of @@ -10,7 +16,6 @@ There is a `Gitlab::Profiler.profile` method, and corresponding `bin/profile-url` script, that enable profiling a GET or POST request to a specific URL, either as an anonymous user (the default) or as a specific user. -NOTE: **Note:** The first argument to the profiler is either a full URL (including the instance hostname) or an absolute path, including the leading slash. diff --git a/doc/development/projections.md b/doc/development/projections.md index 9d5702da530..b8f476c53e9 100644 --- a/doc/development/projections.md +++ b/doc/development/projections.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Projections Projections are a way to define relations between files. Every file can have a diff --git a/doc/development/prometheus.md b/doc/development/prometheus.md index 3e7acaf6d94..fc1f2303d0a 100644 --- a/doc/development/prometheus.md +++ b/doc/development/prometheus.md @@ -1,59 +1,5 @@ --- -stage: Monitor -group: Health -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +redirect_to: '../user/project/integrations/prometheus.md' --- -# Working with Prometheus - -For more information on working with [Prometheus metrics](prometheus_metrics.md), see -the documentation. - -## Access the UI of a Prometheus managed application in Kubernetes - -You can connect directly to Prometheus, and view the Prometheus user interface, when -using a Prometheus managed application in Kubernetes: - -1. Find the name of the Prometheus pod in the user interface of your Kubernetes - provider, such as GKE, or by running the following `kubectl` command in your - terminal: - - ```shell - kubectl get pods -n gitlab-managed-apps | grep 'prometheus-prometheus-server' - ``` - - The command should return a result like the following example, where - `prometheus-prometheus-server-55b4bd64c9-dpc6b` is the name of the Prometheus pod: - - ```plaintext - gitlab-managed-apps prometheus-prometheus-server-55b4bd64c9-dpc6b 2/2 Running 0 71d - ``` - -1. Run a `kubectl port-forward` command. In the following example, `9090` is the - Prometheus server's listening port: - - ```shell - kubectl port-forward prometheus-prometheus-server-55b4bd64c9-dpc6b 9090:9090 -n gitlab-managed-apps - ``` - - The `port-forward` command forwards all requests sent to your system's `9090` port - to the `9090` port of the Prometheus pod. If the `9090` port on your system is used - by another application, you can change the port number before the colon to your - desired port. For example, to forward port `8080` of your local system, change the - command to: - - ```shell - kubectl port-forward prometheus-prometheus-server-55b4bd64c9-dpc6b 8080:9090 -n gitlab-managed-apps - ``` - -1. Open `localhost:9090` in your browser to display the Prometheus user interface. - -## Script access to Prometheus - -You can script the access to Prometheus, extracting the name of the pod automatically like this: - -```shell -POD_INFORMATION=$(kubectl get pods -n gitlab-managed-apps | grep 'prometheus-prometheus-server') -POD_NAME=$(echo $POD_INFORMATION | awk '{print $1;}') -kubectl port-forward $POD_NAME 9090:9090 -n gitlab-managed-apps -``` +This document was moved to [another location](../user/project/integrations/prometheus.md). diff --git a/doc/development/pry_debugging.md b/doc/development/pry_debugging.md index 0558a0a515a..7f9a49d4d50 100644 --- a/doc/development/pry_debugging.md +++ b/doc/development/pry_debugging.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Pry debugging ## Invoking pry debugging diff --git a/doc/development/python_guide/index.md b/doc/development/python_guide/index.md index fae2e495417..22a01c3b877 100644 --- a/doc/development/python_guide/index.md +++ b/doc/development/python_guide/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Python Development Guidelines GitLab requires Python as a dependency for [reStructuredText](https://docutils.sourceforge.io/rst.html) diff --git a/doc/development/query_count_limits.md b/doc/development/query_count_limits.md index b3ecaf30d8a..07dcb6c7d90 100644 --- a/doc/development/query_count_limits.md +++ b/doc/development/query_count_limits.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Query Count Limits Each controller or API endpoint is allowed to execute up to 100 SQL queries and diff --git a/doc/development/query_recorder.md b/doc/development/query_recorder.md index ef9a3c657aa..4a02af3348c 100644 --- a/doc/development/query_recorder.md +++ b/doc/development/query_recorder.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # QueryRecorder QueryRecorder is a tool for detecting the [N+1 queries problem](https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations) from tests. @@ -20,17 +26,17 @@ 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. -NOTE: **Note:** 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. ## Cached queries -By default, QueryRecorder will ignore 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, -pass the `skip_cached` variable to `QueryRecorder` and use the `exceed_all_query_limit` matcher: +By default, QueryRecorder will ignore [cached queries](merge_request_performance_guidelines.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: ```ruby -it "avoids N+1 database queries" do +it "avoids N+1 database queries", :use_sql_query_cache do control_count = ActiveRecord::QueryRecorder.new(skip_cached: false) { visit_some_page }.count create_list(:issue, 5) expect { visit_some_page }.not_to exceed_all_query_limit(control_count) @@ -118,4 +124,5 @@ There are multiple ways to find the source of queries. - [Bullet](profiling.md#bullet) For finding `N+1` query problems - [Performance guidelines](performance.md) -- [Merge request performance guidelines](merge_request_performance_guidelines.md#query-counts) +- [Merge request performance guidelines - Query counts](merge_request_performance_guidelines.md#query-counts) +- [Merge request performance guidelines - Cached queries](merge_request_performance_guidelines.md#cached-queries) diff --git a/doc/development/rails_initializers.md b/doc/development/rails_initializers.md index 6473baf58d4..bc0ac963f3f 100644 --- a/doc/development/rails_initializers.md +++ b/doc/development/rails_initializers.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Rails initializers By default, Rails loads Zeitwerk after the initializers in `config/initializers` are loaded. diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index fd5dee69fc3..2dca747425c 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Rake tasks for developers Rake tasks are available for developers and others contributing to GitLab. @@ -12,7 +18,7 @@ bundle exec rake setup The `setup` task is an alias for `gitlab:setup`. This tasks calls `db:reset` to create the database, and calls `db:seed_fu` to seed the database. -Note: `db:setup` calls `db:seed` but this does nothing. +`db:setup` calls `db:seed` but this does nothing. ### Environment variables diff --git a/doc/development/reactive_caching.md b/doc/development/reactive_caching.md index cf125c46565..106a9b5de31 100644 --- a/doc/development/reactive_caching.md +++ b/doc/development/reactive_caching.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # `ReactiveCaching` > This doc refers to <https://gitlab.com/gitlab-org/gitlab/blob/master/app/models/concerns/reactive_caching.rb>. diff --git a/doc/development/redis.md b/doc/development/redis.md index a0ae84beb8d..7ee8afda36a 100644 --- a/doc/development/redis.md +++ b/doc/development/redis.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Redis guidelines GitLab uses [Redis](https://redis.io) for the following distinct purposes: diff --git a/doc/development/refactoring_guide/index.md b/doc/development/refactoring_guide/index.md index a9ff9556aed..17deffb4cb2 100644 --- a/doc/development/refactoring_guide/index.md +++ b/doc/development/refactoring_guide/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Refactoring guide This document is a collection of techniques and best practices to consider while performing a refactor. diff --git a/doc/development/reference_processing.md b/doc/development/reference_processing.md index cf587043cae..07833c0d302 100644 --- a/doc/development/reference_processing.md +++ b/doc/development/reference_processing.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers description: 'An introduction to reference parsers and reference filters, and a guide to their implementation.' --- @@ -10,7 +13,6 @@ abstractions in the `Banzai` pipeline: `ReferenceFilter` and `ReferenceParser`. This page explains what these are, how they are used, and how you would implement a new filter/parser pair. -NOTE: **Note:** Each `ReferenceFilter` must have a corresponding `ReferenceParser`. It is possible to share reference parsers between filters - if two filters find @@ -39,7 +41,7 @@ For example, the class is responsible for handling references to issues, such as `gitlab-org/gitlab#123` and `https://gitlab.com/gitlab-org/gitlab/-/issues/200048`. -All reference filters are instances of [`HTML::Pipeline::Filter`](https://www.rubydoc.info/github/jch/html-pipeline/v1.11.0/HTML/Pipeline/Filter), +All reference filters are instances of [`HTML::Pipeline::Filter`](https://www.rubydoc.info/github/jch/html-pipeline/HTML/Pipeline/Filter), and inherit (often indirectly) from [`Banzai::Filter::ReferenceFilter`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/banzai/filter/reference_filter.rb). `HTML::Pipeline::Filter` has a simple interface consisting of `#call`, a void @@ -196,6 +198,5 @@ In practice, all reference parsers inherit from [`BaseParser`](https://gitlab.co - `#references_relation` an active record relation for objects by ID. - `#nodes_user_can_reference(user, nodes)` to filter nodes directly. -NOTE: **Note:** A failure to implement this class for each reference type means that the application will raise exceptions during Markdown processing. diff --git a/doc/development/renaming_features.md b/doc/development/renaming_features.md index daf437027db..02d1851dbfe 100644 --- a/doc/development/renaming_features.md +++ b/doc/development/renaming_features.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Renaming features Sometimes the business asks to change the name of a feature. Broadly speaking, there are 2 approaches to that task. They basically trade between immediate effort and future complexity/bug risk: diff --git a/doc/development/repository_mirroring.md b/doc/development/repository_mirroring.md index fe6db987471..02d1499ca35 100644 --- a/doc/development/repository_mirroring.md +++ b/doc/development/repository_mirroring.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Repository mirroring ## Deep Dive diff --git a/doc/development/reusing_abstractions.md b/doc/development/reusing_abstractions.md index 8711bac69e0..77534eea076 100644 --- a/doc/development/reusing_abstractions.md +++ b/doc/development/reusing_abstractions.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Guidelines for reusing abstractions As GitLab has grown, different patterns emerged across the codebase. Service diff --git a/doc/development/rolling_out_changes_using_feature_flags.md b/doc/development/rolling_out_changes_using_feature_flags.md index 6bad91d6287..cff88388ba0 100644 --- a/doc/development/rolling_out_changes_using_feature_flags.md +++ b/doc/development/rolling_out_changes_using_feature_flags.md @@ -1 +1,5 @@ +--- +redirect_to: 'feature_flags/index.md' +--- + This document was moved to [another location](feature_flags/index.md). diff --git a/doc/development/routing.md b/doc/development/routing.md index e164431853f..cbae2b38427 100644 --- a/doc/development/routing.md +++ b/doc/development/routing.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Routing The GitLab backend is written primarily with Rails so it uses [Rails diff --git a/doc/development/scalability.md b/doc/development/scalability.md index 0fb54d89913..73f7c5e0915 100644 --- a/doc/development/scalability.md +++ b/doc/development/scalability.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab scalability This section describes the current architecture of GitLab as it relates to diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md index e35bda82aaa..ebab0e59cc3 100644 --- a/doc/development/secure_coding_guidelines.md +++ b/doc/development/secure_coding_guidelines.md @@ -219,11 +219,11 @@ the mitigations for a new feature. - [More details](https://dev.gitlab.org/gitlab/gitlabhq/-/merge_requests/2530/diffs) -#### Feature-specific Mitigations +#### Feature-specific mitigations For situations in which an allowlist or GitLab:HTTP cannot be used, it will be necessary to implement mitigations directly in the feature. It is best to validate the destination IP addresses themselves, not just domain names, as DNS can be controlled by the attacker. Below are a list of mitigations that should be implemented. -**Important Note:** There are many tricks to bypass common SSRF validations. If feature-specific mitigations are necessary, they should be reviewed by the AppSec team, or a developer who has worked on SSRF mitigations previously. +There are many tricks to bypass common SSRF validations. If feature-specific mitigations are necessary, they should be reviewed by the AppSec team, or a developer who has worked on SSRF mitigations previously. - Block connections to all localhost addresses - `127.0.0.1/8` (IPv4 - note the subnet mask) @@ -269,7 +269,7 @@ When user submitted data is included in responses to end users, which is just ab ### Mitigation -In most situations, a two-step solution can be utilized: input validation and output encoding in the appropriate context. +In most situations, a two-step solution can be used: input validation and output encoding in the appropriate context. #### Input validation @@ -311,6 +311,7 @@ Specifically, the following options are dangerous because they mark strings as t |----------------------|-------------------------------| | HAML templates | `html_safe`, `raw`, `!=` | | Embedded Ruby (ERB) | `html_safe`, `raw`, `<%== %>` | + In case you want to sanitize user-controlled values against XSS vulnerabilities, you can use [`ActionView::Helpers::SanitizeHelper`](https://api.rubyonrails.org/classes/ActionView/Helpers/SanitizeHelper.html). Calling `link_to` and `redirect_to` with user-controlled parameters can also lead to cross-site scripting. @@ -328,6 +329,7 @@ References: - When updating the content of an HTML element using JavaScript, mark user-controlled values as `textContent` or `nodeValue` instead of `innerHTML`. - Avoid using `v-html` with user-controlled data, use [`v-safe-html`](https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/directives-safe-html-directive--default) instead. +- Render unsafe or unsanitized content using [`dompurify`](fe_guide/security.md#sanitize-html-output). - Consider using [`gl-sprintf`](../../ee/development/i18n/externalization.md#interpolation) to interpolate translated strings securely. - Avoid `__()` with translations that contain user-controlled values. - When working with `postMessage`, ensure the `origin` of the message is allowlisted. @@ -428,6 +430,132 @@ The Path Traversal check can also be used to forbid any absolute path: requires :file_path, type: String, file_path: true ``` -NOTE: **Note:** Absolute paths are not allowed by default. If allowing an absolute path is required, you -need to provide an array of paths to the parameter `allowlist`. +need to provide an array of paths to the parameter `allowlist`. + +## OS command injection guidelines + +Command injection is an issue in which an attacker is able to execute arbitrary commands on the host +operating system through a vulnerable application. Such attacks don't always provide feedback to a +user, but the attacker can use simple commands like `curl` to obtain an answer. + +### Impact + +The impact of command injection greatly depends on the user context running the commands, as well as +how data is validated and sanitized. It can vary from low impact because the user running the +injected commands has limited rights, to critical impact if running as the root user. + +Potential impacts include: + +- Execution of arbitrary commands on the host machine. +- Unauthorized access to sensitive data, including passwords and tokens in secrets or configuration + files. +- Exposure of sensitive system files on the host machine, such as `/etc/passwd/` or `/etc/shadow`. +- Compromise of related systems and services gained through access to the host machine. + +You should be aware of and take steps to prevent command injection when working with user-controlled +data that are used to run OS commands. + +### Mitigation and prevention + +To prevent OS command injections, user-supplied data shouldn't be used within OS commands. In cases +where you can't avoid this: + +- Validate user-supplied data against an allowlist. +- Ensure that user-supplied data only contains alphanumeric characters (and no syntax or whitespace + characters, for example). +- Always use `--` to separate options from arguments. + +### Ruby + +Consider using `system("command", "arg0", "arg1", ...)` whenever you can. This prevents an attacker +from concatenating commands. + +For more examples on how to use shell commands securely, consult +[Guidelines for shell commands in the GitLab codebase](shell_commands.md). +It contains various examples on how to securely call OS commands. + +### Go + +Go has built-in protections that usually prevent an attacker from successfully injecting OS commands. + +Consider the following example: + +```golang +package main + +import ( + "fmt" + "os/exec" +) + +func main() { + cmd := exec.Command("echo", "1; cat /etc/passwd") + out, _ := cmd.Output() + fmt.Printf("%s", out) +} +``` + +This echoes `"1; cat /etc/passwd"`. + +**Do not** use `sh`, as it bypasses internal protections: + +```golang +out, _ = exec.Command("sh", "-c", "echo 1 | cat /etc/passwd").Output() +``` + +This outputs `1` followed by the content of `/etc/passwd`. + +## GitLab Internal Authorization + +### Introduction + +There are some cases where `users` passed in the code is actually referring to a `DeployToken`/`DeployKey` entity instead of a real `User`, because of the code below in **`/lib/api/api_guard.rb`** + +```ruby + def find_user_from_sources + strong_memoize(:find_user_from_sources) do + deploy_token_from_request || + find_user_from_bearer_token || + find_user_from_job_token || + user_from_warden + end + end +``` + +### Past Vulnerable Code + +In some scenarios such as [this one](https://gitlab.com/gitlab-org/gitlab/-/issues/237795), user impersonation is possible because a `DeployToken` ID can be used in place of a `User` ID. This happened because there was no check on the line with `Gitlab::Auth::CurrentUserMode.bypass_session!(user.id)`. In this case, the `id` is actually a `DeployToken` ID instead of a `User` ID. + +```ruby + def find_current_user! + user = find_user_from_sources + return unless user + + # Sessions are enforced to be unavailable for API calls, so ignore them for admin mode + Gitlab::Auth::CurrentUserMode.bypass_session!(user.id) if Feature.enabled?(:user_mode_in_session) + + unless api_access_allowed?(user) + forbidden!(api_access_denied_message(user)) + end +``` + +### Best Practices + +In order to prevent this from happening, it is recommended to use the method `user.is_a?(User)` to make sure it returns `true` when we are expecting to deal with a `User` object. This could prevent the ID confusion from the method `find_user_from_sources` mentioned above. Below code snippet shows the fixed code after applying the best practice to the vulnerable code above. + +```ruby + def find_current_user! + user = find_user_from_sources + return unless user + + if user.is_a?(User) && Feature.enabled?(:user_mode_in_session) + # Sessions are enforced to be unavailable for API calls, so ignore them for admin mode + Gitlab::Auth::CurrentUserMode.bypass_session!(user.id) + end + + unless api_access_allowed?(user) + forbidden!(api_access_denied_message(user)) + end +``` +
\ No newline at end of file diff --git a/doc/development/serializing_data.md b/doc/development/serializing_data.md index af791f5a4e0..83a75eef556 100644 --- a/doc/development/serializing_data.md +++ b/doc/development/serializing_data.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Serializing Data **Summary:** don't store serialized data in the database, use separate columns diff --git a/doc/development/service_measurement.md b/doc/development/service_measurement.md index 24b16aac95b..571bbddb494 100644 --- a/doc/development/service_measurement.md +++ b/doc/development/service_measurement.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab Developers Guide to service measurement You can enable service measurement in order to debug any slow service's execution time, number of SQL calls, garbage collection stats, memory usage, etc. @@ -16,7 +22,6 @@ The measuring module is a tool that allows to measure a service's execution, and The measuring module will log these measurements into a structured log called [`service_measurement.log`](../administration/logs.md#service_measurementlog), as a single entry for each service execution. -NOTE: **Note:** For GitLab.com, `service_measurement.log` is ingested in Elasticsearch and Kibana as part of our monitoring solution. ## How to use it @@ -64,9 +69,8 @@ def extra_attributes_for_measurement end ``` -NOTE: **Note:** -Once the measurement module is injected in the service, it will be behind generic feature flag. -In order to actually use it, you need to enable measuring for the desired service by enabling the feature flag. +After the measurement module is injected in the service, it will be behind a generic feature flag. +To actually use it, you need to enable measuring for the desired service by enabling the feature flag. ### Enabling measurement using feature flags diff --git a/doc/development/session.md b/doc/development/session.md index 971795d8816..a7f69f570c3 100644 --- a/doc/development/session.md +++ b/doc/development/session.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Accessing session data Session data in GitLab is stored in Redis and can be accessed in a variety of ways. diff --git a/doc/development/sha1_as_binary.md b/doc/development/sha1_as_binary.md index 6c4252ec634..e69ba149cde 100644 --- a/doc/development/sha1_as_binary.md +++ b/doc/development/sha1_as_binary.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Storing SHA1 Hashes As Binary Storing SHA1 hashes as strings is not very space efficient. A SHA1 as a string diff --git a/doc/development/shared_files.md b/doc/development/shared_files.md index fcd905b54a4..2c6b1222cfb 100644 --- a/doc/development/shared_files.md +++ b/doc/development/shared_files.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Shared files Historically, GitLab has been storing shared files in many different diff --git a/doc/development/shell_commands.md b/doc/development/shell_commands.md index b71fcbdc2ab..25113b4ac29 100644 --- a/doc/development/shell_commands.md +++ b/doc/development/shell_commands.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Guidelines for shell commands in the GitLab codebase This document contains guidelines for working with processes and files in the GitLab codebase. diff --git a/doc/development/shell_scripting_guide/index.md b/doc/development/shell_scripting_guide/index.md index 704b46c7efa..f447a0e0e72 100644 --- a/doc/development/shell_scripting_guide/index.md +++ b/doc/development/shell_scripting_guide/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Shell scripting standards and style guidelines GitLab consists of many various services and sub-projects. The majority of diff --git a/doc/development/sidekiq_debugging.md b/doc/development/sidekiq_debugging.md index b6a11dd813d..e0f74b39c9a 100644 --- a/doc/development/sidekiq_debugging.md +++ b/doc/development/sidekiq_debugging.md @@ -1,6 +1,5 @@ -# Sidekiq debugging +--- +redirect_to: '../administration/troubleshooting/sidekiq.md' +--- -## Log arguments to Sidekiq jobs - -This content has been moved to the -[Troubleshooting Sidekiq docs](../administration/troubleshooting/sidekiq.md). +This document was moved to [another location](../administration/troubleshooting/sidekiq.md). diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md index 24570cfc07b..13ae39997bc 100644 --- a/doc/development/sidekiq_style_guide.md +++ b/doc/development/sidekiq_style_guide.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Sidekiq Style Guide This document outlines various guidelines that should be followed when adding or @@ -21,7 +27,10 @@ After adding a new queue, run `bin/rake gitlab:sidekiq:all_queues_yml:generate` to regenerate `app/workers/all_queues.yml` or `ee/app/workers/all_queues.yml` so that it can be picked up by -[`sidekiq-cluster`](../administration/operations/extra_sidekiq_processes.md). +[`sidekiq-cluster`](../administration/operations/extra_sidekiq_processes.md). +Additionally, run +`bin/rake gitlab:sidekiq:sidekiq_queues_yml:generate` to regenerate +`config/sidekiq_queues.yml`. ## Queue Namespaces @@ -112,7 +121,6 @@ As a general rule, a worker can be considered idempotent if: A good example of that would be a cache expiration worker. -NOTE: **Note:** A job scheduled for an idempotent worker will automatically be [deduplicated](#deduplication) when an unstarted job with the same arguments is already in the queue. @@ -152,7 +160,6 @@ end It's encouraged to only have the `idempotent!` call in the top-most worker class, even if the `perform` method is defined in another class or module. -NOTE: **Note:** If the worker class is not marked as idempotent, a cop will fail. Consider skipping the cop if you're not confident your job can safely run multiple times. @@ -165,6 +172,22 @@ job. The work is skipped because the same work would be done by the job that was scheduled first; by the time the second job executed, the first job would do nothing. +#### Strategies + +GitLab supports two deduplication strategies: + +- `until_executing` +- `until_executed` + +More [deduplication strategies have been +suggested](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/195). If +you are implementing a worker that could benefit from a different +strategy, please comment in the issue. + +##### Until Executing + +This strategy takes a lock when a job is added to the queue, and removes that lock before the job starts. + For example, `AuthorizedProjectsWorker` takes a user ID. When the worker runs, it recalculates a user's authorizations. GitLab schedules this job each time an action potentially changes a user's @@ -173,10 +196,47 @@ same time, the second job can be skipped if the first job hasn't begun, because when the first job runs, it creates the authorizations for both projects. +```ruby +module AuthorizedProjectUpdate + class UserRefreshOverUserRangeWorker + include ApplicationWorker + + deduplicate :until_executing + idempotent! + + # ... + end +end +``` + +##### Until Executed + +This strategy takes a lock when a job is added to the queue, and removes that lock after the job finishes. +It can be used to prevent jobs from running simultaneously multiple times. + +```ruby +module Ci + class BuildTraceChunkFlushWorker + include ApplicationWorker + + deduplicate :until_executed + idempotent! + + # ... + end +end +``` + +#### Scheduling jobs in the future + GitLab doesn't skip jobs scheduled in the future, as we assume that the state will have changed by the time the job is scheduled to -execute. If you do want to deduplicate jobs scheduled in the future -this can be specified on the worker as follows: +execute. Deduplication of jobs scheduled in the feature is possible +for both `until_executed` and `until_executing` strategies. + +If you do want to deduplicate jobs scheduled in the future, +this can be specified on the worker by passing `including_scheduled: true` argument +when defining deduplication strategy: ```ruby module AuthorizedProjectUpdate @@ -191,11 +251,7 @@ module AuthorizedProjectUpdate end ``` -This strategy is called `until_executing`. More [deduplication -strategies have been -suggested](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/195). If -you are implementing a worker that could benefit from a different -strategy, please comment in the issue. +#### Troubleshooting If the automatic deduplication were to cause issues in certain queues. This can be temporarily disabled by enabling a feature flag @@ -429,9 +485,7 @@ class ExternalDependencyWorker end ``` -NOTE: **Note:** -Note that a job cannot be both high urgency and have -external dependencies. +A job cannot be both high urgency and have external dependencies. ## CPU-bound and Memory-bound Workers @@ -645,8 +699,8 @@ blocks: ## Arguments logging -When [`SIDEKIQ_LOG_ARGUMENTS`](../administration/troubleshooting/sidekiq.md#log-arguments-to-sidekiq-jobs) -is enabled, Sidekiq job arguments will be logged. +As of GitLab 13.6, Sidekiq job arguments will be logged by default, unless [`SIDEKIQ_LOG_ARGUMENTS`](../administration/troubleshooting/sidekiq.md#log-arguments-to-sidekiq-jobs) +is disabled. By default, the only arguments logged are numeric arguments, because arguments of other types could contain sensitive information. To @@ -767,7 +821,7 @@ This approach requires multiple releases. ##### Parameter hash This approach will not require multiple releases if an existing worker already -utilizes a parameter hash. +uses a parameter hash. 1. Use a parameter hash in the worker to allow future flexibility. diff --git a/doc/development/single_table_inheritance.md b/doc/development/single_table_inheritance.md index 27c3c4f3199..51268092225 100644 --- a/doc/development/single_table_inheritance.md +++ b/doc/development/single_table_inheritance.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Single Table Inheritance **Summary:** don't use Single Table Inheritance (STI), use separate tables diff --git a/doc/development/sql.md b/doc/development/sql.md index 55a8192578b..bf405eab688 100644 --- a/doc/development/sql.md +++ b/doc/development/sql.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # SQL Query Guidelines This document describes various guidelines to follow when writing SQL queries, diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index 2c1d70a005e..dabb18c1f75 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -361,7 +361,7 @@ Finished in 34.51 seconds (files took 0.76702 seconds to load) 1 example, 0 failures ``` -Note: `live_debug` only works on JavaScript enabled specs. +`live_debug` only works on JavaScript enabled specs. #### Run `:js` spec in a visible browser @@ -584,9 +584,9 @@ this trait should be either fixed to not rely on Sidekiq processing jobs, or the `:sidekiq_might_not_need_inline` trait should be updated to `:sidekiq_inline` if the processing of background jobs is needed/expected. -NOTE: **Note:** -The usage of `perform_enqueued_jobs` is only useful for testing delayed mail -deliveries since our Sidekiq workers aren't inheriting from `ApplicationJob` / `ActiveJob::Base`. +The usage of `perform_enqueued_jobs` is useful only for testing delayed mail +deliveries, because our Sidekiq workers aren't inheriting from `ApplicationJob` +/ `ActiveJob::Base`. #### DNS diff --git a/doc/development/testing_guide/ci.md b/doc/development/testing_guide/ci.md index 8091142410c..618f9010b4d 100644 --- a/doc/development/testing_guide/ci.md +++ b/doc/development/testing_guide/ci.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab tests in the Continuous Integration (CI) context ## Test suite parallelization on the CI diff --git a/doc/development/testing_guide/end_to_end/beginners_guide.md b/doc/development/testing_guide/end_to_end/beginners_guide.md index a1883f44170..ef0bd9902e1 100644 --- a/doc/development/testing_guide/end_to_end/beginners_guide.md +++ b/doc/development/testing_guide/end_to_end/beginners_guide.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Beginner's guide to writing end-to-end tests In this tutorial, you will learn about the creation of end-to-end (_e2e_) tests @@ -52,7 +58,6 @@ Check both [GitLab Community Edition](https://gitlab-org.gitlab.io/gitlab-foss/c for previously-written tests for this feature. For analyzing the code coverage, you must understand which application files implement specific features. -NOTE: **Note:** In this tutorial we're writing a login end-to-end test, even though it has been sufficiently covered by lower-level testing, because it's the first step for most end-to-end flows, and is easiest to understand. @@ -68,7 +73,6 @@ under the stage.  -NOTE: **Note:** If the test is Enterprise Edition only, the test will be created in the `features/ee` directory, but follow the same DevOps lifecycle format. @@ -204,7 +208,6 @@ end 1. Check if the user avatar appears in the top navigation. 1. Check if the user avatar *does not* appear in the top navigation. -NOTE: **Note:** Behind the scenes, `be_signed_in` is a [predicate matcher](https://relishapp.com/rspec/rspec-expectations/v/3-8/docs/built-in-matchers/predicate-matchers) that [implements checking the user avatar](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/qa/page/main/menu.rb#L74). diff --git a/doc/development/testing_guide/end_to_end/best_practices.md b/doc/development/testing_guide/end_to_end/best_practices.md index 58bae749dc5..4d12a0f79cb 100644 --- a/doc/development/testing_guide/end_to_end/best_practices.md +++ b/doc/development/testing_guide/end_to_end/best_practices.md @@ -1,6 +1,11 @@ +--- +stage: none +group: Development +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # End-to-end testing Best Practices -NOTE: **Note:** This is a tailored extension of the Best Practices [found in the testing guide](../best_practices.md). ## Link a test to its test-case issue @@ -263,7 +268,7 @@ We don't run tests that require Administrator access against our Production envi When you add a new test that requires Administrator access, apply the RSpec metadata `:requires_admin` so that the test will not be included in the test suites executed against Production and other environments on which we don't want to run those tests. -Note: When running tests locally or configuring a pipeline, the environment variable `QA_CAN_TEST_ADMIN_FEATURES` can be set to `false` to skip tests that have the `:requires_admin` tag. +When running tests locally or configuring a pipeline, the environment variable `QA_CAN_TEST_ADMIN_FEATURES` can be set to `false` to skip tests that have the `:requires_admin` tag. ## Prefer `Commit` resource over `ProjectPush` @@ -288,7 +293,6 @@ Resource::Repository::ProjectPush.fabricate! do |push| end ``` -NOTE: **Note:** A few exceptions for using a `ProjectPush` would be when your test calls for testing SSH integration or using the Git CLI. @@ -321,39 +325,69 @@ In general, we use an `expect` statement to check that something _is_ as we expe ```ruby Page::Project::Pipeline::Show.perform do |pipeline| - expect(pipeline).to have_job("a_job") + expect(pipeline).to have_job('a_job') end ``` -### Ensure `expect` checks for negation efficiently +### Create negatable matchers to speed `expect` checks However, sometimes we want to check that something is _not_ as we _don't_ want it to be. In other -words, we want to make sure something is absent. In such a case we should use an appropriate -predicate method that returns quickly, rather than waiting for a state that won't appear. +words, we want to make sure something is absent. For unit tests and feature specs, +we commonly use `not_to` +because RSpec's built-in matchers are negatable, as are Capybara's, which means the following two statements are +equivalent. + +```ruby +except(page).not_to have_text('hidden') +except(page).to have_no_text('hidden') +``` + +Unfortunately, that's not automatically the case for the predicate methods that we add to our +[page objects](page_objects.md). We need to [create our own negatable matchers](https://relishapp.com/rspec/rspec-expectations/v/3-9/docs/custom-matchers/define-a-custom-matcher#matcher-with-separate-logic-for-expect().to-and-expect().not-to). + +The initial example uses the `have_job` matcher which is derived from the [`has_job?` predicate +method of the `Page::Project::Pipeline::Show` page object](https://gitlab.com/gitlab-org/gitlab/-/blob/87864b3047c23b4308f59c27a3757045944af447/qa/qa/page/project/pipeline/show.rb#L53). +To create a negatable matcher, we use `has_no_job?` for the negative case: + +```ruby +RSpec::Matchers.define :have_job do |job_name| + match do |page_object| + page_object.has_job?(job_name) + end + + match_when_negated do |page_object| + page_object.has_no_job?(job_name) + end +end +``` -It's most efficient to use a predicate method that returns immediately when there is no job, or waits -until it disappears: +And then the two `expect` statements in the following example are equivalent: ```ruby -# Good Page::Project::Pipeline::Show.perform do |pipeline| - expect(pipeline).to have_no_job("a_job") + expect(pipeline).not_to have_job('a_job') + expect(pipeline).to have_no_job('a_job') end ``` -### Problematic alternatives +[See this merge request for a real example of adding a custom matcher](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46302). -Alternatively, if we want to check that a job doesn't exist it might be tempting to use `not_to`: +NOTE: **Note:** +We need to create custom negatable matchers only for the predicate methods we've added to the test framework, and only if we're using `not_to`. If we use `to have_no_*` a negatable matcher is not necessary. + +### Why we need negatable matchers + +Consider the following code, but assume that we _don't_ have a custom negatable matcher for `have_job`. ```ruby # Bad Page::Project::Pipeline::Show.perform do |pipeline| - expect(pipeline).not_to have_job("a_job") + expect(pipeline).not_to have_job('a_job') end ``` -For this statement to pass, `have_job("a_job")` has to return `false` so that `not_to` can negate it. -The problem is that `have_job("a_job")` waits up to ten seconds for `"a job"` to appear before +For this statement to pass, `have_job('a_job')` has to return `false` so that `not_to` can negate it. +The problem is that `have_job('a_job')` waits up to ten seconds for `'a job'` to appear before returning `false`. Under the expected condition this test will take ten seconds longer than it needs to. Instead, we could force no wait: @@ -361,9 +395,13 @@ Instead, we could force no wait: ```ruby # Not as bad but potentially flaky Page::Project::Pipeline::Show.perform do |pipeline| - expect(pipeline).not_to have_job("a_job", wait: 0) + expect(pipeline).not_to have_job('a_job', wait: 0) end ``` -The problem is that if `"a_job"` is present and we're waiting for it to disappear, this statement -will fail. +The problem is that if `'a_job'` is present and we're waiting for it to disappear, this statement will fail. + +Neither problem is present if we create a custom negatable matcher because the `has_no_job?` predicate method +would be used, which would wait only as long as necessary for the job to disappear. + +Lastly, negatable matchers are preferred over using matchers of the form `have_no_*` because it's a common and familiar practice to negate matchers using `not_to`. If we facilitate that practice by adding negatable matchers, we make it easier for subsequent test authors to write efficient tests. diff --git a/doc/development/testing_guide/end_to_end/dynamic_element_validation.md b/doc/development/testing_guide/end_to_end/dynamic_element_validation.md index 32b1c304a9a..871b3f80c18 100644 --- a/doc/development/testing_guide/end_to_end/dynamic_element_validation.md +++ b/doc/development/testing_guide/end_to_end/dynamic_element_validation.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Dynamic Element Validation We devised a solution to solve common test automation problems such as the dreaded `NoSuchElementException`. diff --git a/doc/development/testing_guide/end_to_end/environment_selection.md b/doc/development/testing_guide/end_to_end/environment_selection.md index 325f251b280..f5e3e99b79e 100644 --- a/doc/development/testing_guide/end_to_end/environment_selection.md +++ b/doc/development/testing_guide/end_to_end/environment_selection.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Environment selection Some tests are designed to be run against specific environments or [pipelines](https://about.gitlab.com/handbook/engineering/quality/guidelines/debugging-qa-test-failures/#scheduled-qa-test-pipelines). @@ -42,14 +48,13 @@ RSpec.describe 'Area' do it 'runs in dev environment', only: { tld: '.org', domain: 'gitlab', subdomain: 'dev' } do; end it 'runs in prod and staging environments', only: { subdomain: /(staging.)?/, domain: 'gitlab' } {} - + it 'runs only in nightly pipeline', only: { pipeline: :nightly } do; end - + it 'runs in nightly and canary pipelines', only: { pipeline: [:nightly, :canary] } do; end end ``` -NOTE: **Note:** If the test has a `before` or `after`, you must add the `only` metadata to the outer `RSpec.describe`. diff --git a/doc/development/testing_guide/end_to_end/feature_flags.md b/doc/development/testing_guide/end_to_end/feature_flags.md index e571774167d..2ff1c9f6dc3 100644 --- a/doc/development/testing_guide/end_to_end/feature_flags.md +++ b/doc/development/testing_guide/end_to_end/feature_flags.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Testing with feature flags To run a specific test with a feature flag enabled you can use the `QA::Runtime::Feature` class to diff --git a/doc/development/testing_guide/end_to_end/flows.md b/doc/development/testing_guide/end_to_end/flows.md index fb1d82914aa..291d8bd5319 100644 --- a/doc/development/testing_guide/end_to_end/flows.md +++ b/doc/development/testing_guide/end_to_end/flows.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Flows in GitLab QA Flows are frequently used sequences of actions. They are a higher level diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md index f61eab5c8f3..1d144359ed8 100644 --- a/doc/development/testing_guide/end_to_end/index.md +++ b/doc/development/testing_guide/end_to_end/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # End-to-end Testing ## What is end-to-end testing? diff --git a/doc/development/testing_guide/end_to_end/page_objects.md b/doc/development/testing_guide/end_to_end/page_objects.md index 6ce44b2d359..7eacaf4b08a 100644 --- a/doc/development/testing_guide/end_to_end/page_objects.md +++ b/doc/development/testing_guide/end_to_end/page_objects.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Page objects in GitLab QA In GitLab QA we are using a known pattern, called _Page Objects_. diff --git a/doc/development/testing_guide/end_to_end/resources.md b/doc/development/testing_guide/end_to_end/resources.md index b8a093c54c6..d73bae331d5 100644 --- a/doc/development/testing_guide/end_to_end/resources.md +++ b/doc/development/testing_guide/end_to_end/resources.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Resource class in GitLab QA Resources are primarily created using Browser UI steps, but can also 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 3a1303d9c0c..8e99cf18ea0 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 @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # RSpec metadata for end-to-end tests This is a partial list of the [RSpec metadata](https://relishapp.com/rspec/rspec-core/docs/metadata/user-defined-metadata) @@ -10,7 +16,7 @@ This is a partial list of the [RSpec metadata](https://relishapp.com/rspec/rspec | `: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. | | `:gitaly_cluster` | The test will run against a GitLab instance where repositories are stored on redundant Gitaly nodes behind a Praefect node. All nodes are [separate containers](../../../administration/gitaly/praefect.md#requirements-for-configuring-a-gitaly-cluster). Tests that use this tag have a longer setup time since there are three additional containers that need to be started. | | `:jira` | The test requires a Jira Server. [GitLab-QA](https://gitlab.com/gitlab-org/gitlab-qa) will provision the Jira Server in a Docker container when the `Test::Integration::Jira` test scenario is run. -| `:kubernetes` | The test includes a GitLab instance that is configured to be run behind an SSH tunnel, allowing a TLS-accessible GitLab. This test will also include provisioning of at least one Kubernetes cluster to test against. *This tag is often be paired with `:orchestrated`.* | +| `:kubernetes` | The test includes a GitLab instance that is configured to be run behind an SSH tunnel, allowing a TLS-accessible GitLab. This test will also include provisioning of at least one Kubernetes cluster to test against. _This tag is often be paired with `:orchestrated`._ | | `:only` | The test is only to be run against specific environments or pipelines. See [Environment selection](environment_selection.md) for more information. | | `:orchestrated` | The GitLab instance under test may be [configured by `gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md#orchestrated-tests) to be different to the default GitLab configuration, or `gitlab-qa` may launch additional services in separate Docker containers, or both. Tests tagged with `:orchestrated` are excluded when testing environments where we can't dynamically modify GitLab's configuration (for example, Staging). | | `:quarantine` | The test has been [quarantined](https://about.gitlab.com/handbook/engineering/quality/guidelines/debugging-qa-test-failures/#quarantining-tests), will run in a separate job that only includes quarantined tests, and is allowed to fail. The test will be skipped in its regular job so that if it fails it will not hold up the pipeline. Note that you can also [quarantine a test only when it runs against specific environment](environment_selection.md#quarantining-a-test-for-a-specific-environment). | @@ -19,3 +25,20 @@ This is a partial list of the [RSpec metadata](https://relishapp.com/rspec/rspec | `:runner` | The test depends on and will set up a GitLab Runner instance, typically to run a pipeline. | | `:skip_live_env` | The test will be excluded when run against live deployed environments such as Staging, Canary, and Production. | | `:testcase` | The link to the test case issue in the [Quality Testcases project](https://gitlab.com/gitlab-org/quality/testcases/). | +| `:mattermost` | The test requires a GitLab Mattermost service on the GitLab instance. | +| `:ldap_no_server` | The test requires a GitLab instance to be configured to use LDAP. To be used with the `:orchestrated` tag. It does not spin up an LDAP server at orchestration time. Instead, it creates the LDAP server at runtime. | +| `:ldap_no_tls` | The test requires a GitLab instance to be configured to use an external LDAP server with TLS not enabled. | +| `:ldap_tls` | The test requires a GitLab instance to be configured to use an external LDAP server with TLS enabled. | +| `:object_storage` | The test requires a GitLab instance to be configured to use multiple [object storage types](../../../administration/object_storage.md). Uses MinIO as the object storage server. | +| `:smtp` | The test requires a GitLab instance to be configured to use an SMTP server. Tests SMTP notification email delivery from GitLab by using MailHog. | +| `:group_saml` | The test requires a GitLab instance that has SAML SSO enabled at the group level. Interacts with an external SAML identity provider. Paired with the `:orchestrated` tag. | +| `:instance_saml` | The test requires a GitLab instance that has SAML SSO enabled at the instance level. Interacts with an external SAML identity provider. Paired with the `:orchestrated` tag. | +| `:skip_signup_disabled` | The test uses UI to sign up a new user and will be skipped in any environment that does not allow new user registration via the UI. | +| `:smoke` | The test belongs to the test suite which verifies basic functionality of a GitLab instance.| +| `:github` | The test requires a GitHub personal access token. | +| `:repository_storage` | The test requires a GitLab instance to be configured to use multiple [repository storage paths](../../../administration/repository_storage_paths.md). Paired with the `:orchestrated` tag. | +| `:geo` | The test requires two GitLab Geo instances - a primary and a secondary - to be spun up. | +| `:relative_url` | The test requires a GitLab instance to be installed under a [relative URL](../../../install/relative_url.md). | +| `:requires_git_protocol_v2` | The test requires that Git protocol version 2 is enabled on the server. It's assumed to be enabled by default but if not the test can be skipped by setting `QA_CAN_TEST_GIT_PROTOCOL_V2` to `false`. | +| `:requires_praefect` | The test requires that the GitLab instance uses [Gitaly Cluster](../../../administration/gitaly/praefect.md) (a.k.a. Praefect) as the repository storage . It's assumed to be used by default but if not the test can be skipped by setting `QA_CAN_TEST_PRAEFECT` to `false`. | +| `:packages` | The test requires a GitLab instance that has the [Package Registry](../../../administration/packages/#gitlab-package-registry-administration) enabled. | diff --git a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md index 658839fcf96..df4b833526c 100644 --- a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md +++ b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Running tests that require special setup ## Jenkins spec @@ -232,7 +238,11 @@ run: ./services/tunnel_gitlab: (pid 2650) 10875s, normally down; run: log: (pid run: ./services/tunnel_registry: (pid 2651) 10875s, normally down; run: log: (pid 65155) 177993s ``` -Also, restarting Docker and then, on the Terminal, issue the command `docker login https://[YOUR-REGISTRY-PORT].qa-tunnel.gitlab.info:443` and use the GDK credentials to login. Note that the Registry port and GDK port are not the same. When configuring Auto DevOps in GDK, the `gdk reconfigure` command outputs the port of the Registry: +Also, restarting Docker and then, on the Terminal, issue the command +`docker login https://[YOUR-REGISTRY-PORT].qa-tunnel.gitlab.info:443` and use +the GDK credentials to sign in. Note that the Registry port and GDK port aren't +the same. When configuring Auto DevOps in GDK, the `gdk reconfigure` command +outputs the port of the Registry: ```shell ********************************************* diff --git a/doc/development/testing_guide/end_to_end/style_guide.md b/doc/development/testing_guide/end_to_end/style_guide.md index 645c2633831..e6c96bca93e 100644 --- a/doc/development/testing_guide/end_to_end/style_guide.md +++ b/doc/development/testing_guide/end_to_end/style_guide.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Style guide for writing end-to-end tests This document describes the conventions used at GitLab for writing End-to-end (E2E) tests using the GitLab QA project. diff --git a/doc/development/testing_guide/flaky_tests.md b/doc/development/testing_guide/flaky_tests.md index 7aed908c4f6..47ed11d76a2 100644 --- a/doc/development/testing_guide/flaky_tests.md +++ b/doc/development/testing_guide/flaky_tests.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Flaky tests ## What's a flaky test? @@ -12,7 +18,13 @@ When a test frequently fails in `master`, should be created. If the test cannot be fixed in a timely fashion, there is an impact on the productivity of all the developers, so it should be placed in quarantine by -assigning the `:quarantine` metadata. +assigning the `:quarantine` metadata with the issue URL. + +```ruby +it 'should succeed', quarantine: 'https://gitlab.com/gitlab-org/gitlab/-/issues/12345' do + expect(response).to have_gitlab_http_status(:ok) +end +``` This means it will be skipped unless run with `--tag quarantine`: diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 730f8d5ad7d..28fe63f1fb4 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Frontend testing standards and style guidelines There are two types of test suites you'll encounter while developing frontend code @@ -24,7 +30,6 @@ We have started to migrate frontend tests to the [Jest](https://jestjs.io) testi Jest tests can be found in `/spec/frontend` and `/ee/spec/frontend` in EE. -NOTE: **Note:** Most examples have a Jest and Karma example. See the Karma examples only as explanation to what's going on in the code, should you stumble over some use cases during your discovery. The Jest examples are the one you should follow. ## Karma test suite @@ -110,6 +115,37 @@ describe('Component', () => { Remember that the performance of each test depends on the environment. +### Timout error due to async components + +If your component is fetching some other components asynchroneously based on some conditions, it might happen so that your Jest suite for this component will become flaky timing out from time to time. + +```javascript +// ide.vue +export default { + components: { + 'error-message': () => import('./error_message.vue'), + 'gl-button': () => import('@gitlab/ui/src/components/base/button/button.vue'), + ... +}; +``` + +To address this issue, you can "help" Jest by stubbing the async components so that Jest would not need to fetch those asynchroneously at the run-time. + +```javascript +// ide_spec.js +import { GlButton } from '@gitlab/ui'; +import ErrorMessage from '~/ide/components/error_message.vue'; +... +return shallowMount(ide, { + ... + stubs: { + ErrorMessage, + GlButton, + ... + }, +}) +``` + ## What and how to test Before jumping into more gritty details about Jest-specific workflows like mocks and spies, we should briefly cover what to test with Jest. @@ -198,47 +234,33 @@ Following you'll find some general common practices you will find as part of our When it comes to querying DOM elements in your tests, it is best to uniquely and semantically target the element. -Preferentially, this is done by targeting text the user actually sees using [DOM Testing Library](https://testing-library.com/docs/dom-testing-library/intro). +Preferentially, this is done by targeting what the user actually sees using [DOM Testing Library](https://testing-library.com/docs/dom-testing-library/intro). When selecting by text it is best to use [`getByRole` or `findByRole`](https://testing-library.com/docs/dom-testing-library/api-queries#byrole) as these enforce accessibility best practices as well. The examples below demonstrate the order of preference. -Sometimes this cannot be done feasibly. In these cases, adding test attributes to simplify the -selectors might be the best option. +When writing Vue component unit tests, it can be wise to query children by component, so that the unit test can focus on comprehensive value coverage +rather than dealing with the complexity of a child component's behavior. + +Sometimes, neither of the above are feasible. In these cases, adding test attributes to simplify the selectors might be the best option. A list of +possible selectors include: - A semantic attribute like `name` (also verifies that `name` was setup properly) - A `data-testid` attribute ([recommended by maintainers of `@vue/test-utils`](https://github.com/vuejs/vue-test-utils/issues/1498#issuecomment-610133465)) - a Vue `ref` (if using `@vue/test-utils`) ```javascript -import { mount, shallowMount } from '@vue/test-utils' import { getByRole, getByText } from '@testing-library/dom' -let wrapper -let el - -const createComponent = (mountFn = shallowMount) => { - wrapper = mountFn(Component) - el = wrapper.vm.$el // reference to the container element -} - -beforeEach(() => { - createComponent() -}) - - +// In this example, `wrapper` is a `@vue/test-utils` wrapper returned from `mount` or `shallowMount`. it('exists', () => { - // Best - - // NOTE: both mount and shallowMount work as long as a DOM element is available - // Finds a properly formatted link with an accessible name of "Click Me" - getByRole(el, 'link', { name: /Click Me/i }) - getByRole(el, 'link', { name: 'Click Me' }) - // Finds any element with the text "Click Me" - getByText(el, 'Click Me') - // Regex is also available - getByText(el, /Click Me/i) - - // Good + // Best (especially for integration tests) + getByRole(wrapper.element, 'link', { name: /Click Me/i }) + getByRole(wrapper.element, 'link', { name: 'Click Me' }) + getByText(wrapper.element, 'Click Me') + getByText(wrapper.element, /Click Me/i) + + // Good (especially for unit tests) + wrapper.find(FooComponent); wrapper.find('input[name=foo]'); wrapper.find('[data-testid="foo"]'); wrapper.find({ ref: 'foo'}); @@ -249,14 +271,6 @@ it('exists', () => { wrapper.find('.qa-foo-component'); wrapper.find('[data-qa-selector="foo"]'); }); - -// Good -it('exists', () => { - wrapper.find(FooComponent); - wrapper.find('input[name=foo]'); - wrapper.find('[data-testid="foo"]'); - wrapper.find({ ref: 'foo'}); -}); ``` It is not recommended that you add `.js-*` classes just for testing purposes. Only do this if there are no other feasible options available. @@ -327,7 +341,6 @@ it('tests a promise rejection', async () => { You can also simply return a promise from the test function. -NOTE: **Note:** Using the `done` and `done.fail` callbacks is discouraged when working with promises. They should only be used when testing callback-based code. @@ -777,7 +790,7 @@ While you work on a test suite, you may want to run these specs in watch mode, s # Watch and rerun all specs matching the name icon yarn jest --watch icon -# Watch and rerun one specifc file +# Watch and rerun one specific file yarn jest --watch path/to/spec/file.spec.js ``` @@ -917,6 +930,32 @@ it.each([ ); ``` +**Note**: only use template literal block if pretty print is **not** needed for spec output. For example, empty strings, nested objects etc. + +For example, when testing the difference between an empty search string and a non-empty search string, the use of the array block syntax with the pretty print option would be preferred. That way the differences between an empty string e.g. `''` and a non-empty string e.g. `'search string'` would be visible in the spec output. Whereas with a template literal block, the empty string would be shown as a space, which could lead to a confusing developer experience + +```javascript +// bad +it.each` + searchTerm | expected + ${''} | ${{ issue: { users: { nodes: [] } } }} + ${'search term'} | ${{ issue: { other: { nested: [] } } }} +`('when search term is $searchTerm, it returns $expected', ({ searchTerm, expected }) => { + expect(search(searchTerm)).toEqual(expected) +}); + +// good +it.each([ + ['', { issue: { users: { nodes: [] } } }], + ['search term', { issue: { other: { nested: [] } } }], +])('when search term is %p, expect to return %p', + (searchTerm, expected) => { + expect(search(searchTerm)).toEqual(expected) + } +); + +``` + ```javascript // test suite with tagged template literal block describe.each` diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md index a61a700594c..840c8c9206c 100644 --- a/doc/development/testing_guide/index.md +++ b/doc/development/testing_guide/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Testing standards and style guidelines This document describes various guidelines and best practices for automated diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index 61d3299cabf..5dcc7e7091e 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Review Apps Review Apps are automatically deployed by [the diff --git a/doc/development/testing_guide/smoke.md b/doc/development/testing_guide/smoke.md index 5a144b43478..76484dd193b 100644 --- a/doc/development/testing_guide/smoke.md +++ b/doc/development/testing_guide/smoke.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Smoke Tests It is imperative in any testing suite that we have Smoke Tests. In short, smoke diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index 88d7cf9ca08..d9e7edfa0c8 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Testing levels  diff --git a/doc/development/testing_guide/testing_migrations_guide.md b/doc/development/testing_guide/testing_migrations_guide.md index a5bcb651d71..b944c7ed406 100644 --- a/doc/development/testing_guide/testing_migrations_guide.md +++ b/doc/development/testing_guide/testing_migrations_guide.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- @@ -236,6 +239,5 @@ describe Gitlab::BackgroundMigration::ArchiveLegacyTraces, schema: 2018052915262 end ``` -NOTE: **Note:** These tests do not run within a database transaction, as we use a deletion database cleanup strategy. Do not depend on a transaction being present. diff --git a/doc/development/testing_guide/testing_rake_tasks.md b/doc/development/testing_guide/testing_rake_tasks.md index db8ca87e9f8..384739d1adb 100644 --- a/doc/development/testing_guide/testing_rake_tasks.md +++ b/doc/development/testing_guide/testing_rake_tasks.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Testing Rake tasks To make testing Rake tasks a little easier, there is a helper that can be included diff --git a/doc/development/understanding_explain_plans.md b/doc/development/understanding_explain_plans.md index 797dfc676eb..896b34a4ab4 100644 --- a/doc/development/understanding_explain_plans.md +++ b/doc/development/understanding_explain_plans.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Understanding EXPLAIN plans PostgreSQL allows you to obtain query plans using the `EXPLAIN` command. This @@ -428,6 +434,17 @@ If there aren't any, check if you can perhaps slightly change an existing one to fit both the existing and new queries. Only add a new index if none of the existing indexes can be used in any way. +When comparing execution plans, don't take timing as the only important metric. +Good timing is the main goal of any optimization, but it can be too volatile to +be used for comparison (for example, it depends a lot on the state of cache). +When optimizing a query, we usually need to reduce the amount of data we're +dealing with. Indexes are the way to work with fewer pages (buffers) to get the +result, so, during optimization, look at the number of buffers used (read and hit), +and work on reducing these numbers. Reduced timing will be the consequence of reduced +buffer numbers. [#database-lab](#database-lab) guarantees that the plan is structurally +identical to production (and overall number of buffers is the same as on production), +but difference in cache state and I/O speed may lead to different timings. + ## Queries that can't be optimised Now that we have seen how to optimise a query, let's look at another query that diff --git a/doc/development/uploads.md b/doc/development/uploads.md index ee94553c200..0307ab76cd1 100644 --- a/doc/development/uploads.md +++ b/doc/development/uploads.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Uploads development documentation [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) has special rules for handling uploads. @@ -214,7 +220,6 @@ In this setup, an extra Rails route must be implemented in order to handle autho and [its routes](https://gitlab.com/gitlab-org/gitlab/blob/cc723071ad337573e0360a879cbf99bc4fb7adb9/config/routes/git_http.rb#L31-32). - [API endpoints for uploading packages](packages.md#file-uploads). -Note: **Note:** This will fallback to _disk buffered upload_ when `direct_upload` is disabled inside the [object storage setting](../administration/uploads.md#object-storage-settings). The answer to the `/authorize` call will only contain a file system path. @@ -273,8 +278,10 @@ Uploads routes belong to one of these categories: 1. Rails controllers: uploads handled by Rails controllers. 1. Grape API: uploads handled by a Grape API endpoint. -1. GraphQL API: uploads handled by a GraphQL resolve function. In these cases, there is nothing else - to do apart from implementing the actual upload. +1. GraphQL API: uploads handled by a GraphQL resolve function. + +CAUTION: **Warning:** +GraphQL uploads do not support [direct upload](#direct-upload) yet. Depending on the use case, the feature may not work on installations without NFS (like GitLab.com or Kubernetes installations). Uploading to object storage inside the GraphQL resolve function may result in timeout errors. For more details please follow [issue #280819](https://gitlab.com/gitlab-org/gitlab/-/issues/280819). ### Update Workhorse for the new route diff --git a/doc/development/utilities.md b/doc/development/utilities.md index 52151d37038..aca14507fcd 100644 --- a/doc/development/utilities.md +++ b/doc/development/utilities.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab utilities We have developed a number of utilities to help ease development: diff --git a/doc/development/value_stream_analytics.md b/doc/development/value_stream_analytics.md index 70b16cc1739..4560a115562 100644 --- a/doc/development/value_stream_analytics.md +++ b/doc/development/value_stream_analytics.md @@ -1,3 +1,9 @@ +--- +stage: Manage +group: Optimize +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Value Stream Analytics development guide Value stream analytics calculates the time between two arbitrary events recorded on domain objects and provides aggregated statistics about the duration. @@ -53,8 +59,8 @@ def timestamp_projection end ``` -NOTE: **Note:** -More complex expressions are also possible (e.g. using `COALESCE`). Look at the existing event classes for examples. +More complex expressions are also possible (for example, using `COALESCE`). +Review the existing event classes for examples. In some cases, defining the `timestamp_projection` method is not enough. The calculation query should know which table contains the timestamp expression. Each `Event` class is responsible for making modifications to the calculation query to make the `timestamp_projection` work. This usually means joining an additional table. diff --git a/doc/development/verifying_database_capabilities.md b/doc/development/verifying_database_capabilities.md index f6c78e51299..fe60ec11bce 100644 --- a/doc/development/verifying_database_capabilities.md +++ b/doc/development/verifying_database_capabilities.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Verifying Database Capabilities Sometimes certain bits of code may only work on a certain database diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md index 9063fb867e2..18a2e17967a 100644 --- a/doc/development/what_requires_downtime.md +++ b/doc/development/what_requires_downtime.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # What requires downtime? When working with a database certain operations can be performed without taking @@ -88,6 +94,8 @@ renaming. For example class RenameUsersUpdatedAtToUpdatedAtTimestamp < ActiveRecord::Migration[4.2] include Gitlab::Database::MigrationHelpers + DOWNTIME = false + disable_ddl_transaction! def up @@ -100,13 +108,12 @@ class RenameUsersUpdatedAtToUpdatedAtTimestamp < ActiveRecord::Migration[4.2] end ``` -This will take care of renaming the column, ensuring data stays in sync, copying -over indexes and foreign keys, etc. +This will take care of renaming the column, ensuring data stays in sync, and +copying over indexes and foreign keys. -NOTE: **Note:** -If a column contains 1 or more indexes that do not contain the name of -the original column, the above procedure will fail. In this case you will first -need to rename these indexes. +If a column contains one or more indexes that don't contain the name of the +original column, the previously described procedure will fail. In that case, +you'll first need to rename these indexes. ### Step 2: Add A Post-Deployment Migration @@ -131,7 +138,6 @@ class CleanupUsersUpdatedAtRename < ActiveRecord::Migration[4.2] end ``` -NOTE: **Note:** If you're renaming a [large table](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3), please carefully consider the state when the first migration has run but the second cleanup migration hasn't been run yet. With [Canary](https://gitlab.com/gitlab-com/gl-infra/readiness/-/tree/master/library/canary/) it is possible that the system runs in this state for a significant amount of time. @@ -142,7 +148,7 @@ done without requiring downtime. However, this does require that any application changes are deployed _first_. Thus, changing the constraints of a column should happen in a post-deployment migration. -NOTE: Avoid using `change_column` as it produces an inefficient query because it re-defines +Avoid using `change_column` as it produces an inefficient query because it re-defines the whole column type. You can check the following guides for each specific use case: diff --git a/doc/development/wikis.md b/doc/development/wikis.md index 9a436762645..f8bcaac2ec0 100644 --- a/doc/development/wikis.md +++ b/doc/development/wikis.md @@ -1,8 +1,8 @@ --- type: reference, dev -stage: none -group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +stage: Create +group: Knowledge +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers description: "GitLab's development guidelines for Wikis" --- diff --git a/doc/development/windows.md b/doc/development/windows.md index 3301e4f7c8f..2ca99508746 100644 --- a/doc/development/windows.md +++ b/doc/development/windows.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- diff --git a/doc/downgrade_ee_to_ce/README.md b/doc/downgrade_ee_to_ce/README.md index cba21668816..2561ee875d2 100644 --- a/doc/downgrade_ee_to_ce/README.md +++ b/doc/downgrade_ee_to_ce/README.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Downgrading from EE to CE If you ever decide to downgrade your Enterprise Edition back to the Community diff --git a/doc/gitlab-basics/command-line-commands.md b/doc/gitlab-basics/command-line-commands.md index e259aeef37b..1933b432138 100644 --- a/doc/gitlab-basics/command-line-commands.md +++ b/doc/gitlab-basics/command-line-commands.md @@ -7,14 +7,14 @@ type: howto, reference # Edit files through the command line -When [working with Git from the command line](start-using-git.md), you will need to +When [working with Git from the command line](start-using-git.md), you need to use more than just the Git commands. There are several basic commands that you should learn, in order to make full use of the command line. ## Start working on your project To work on a Git project locally (from your own computer), with the command line, -first you will need to [clone (copy) it](start-using-git.md#clone-a-repository) to +first you need to [clone (copy) it](start-using-git.md#clone-a-repository) to your computer. ## Working with files on the command line @@ -57,16 +57,16 @@ nano README.md ### Remove a file or directory -It is easy to delete (remove) a file or directory, but be careful: +It's easy to delete (remove) a file or directory, but be careful: -DANGER: **Danger:** +DANGER: **Warning:** This will **permanently** delete a file. ```shell rm NAME-OF-FILE ``` -DANGER: **Danger:** +DANGER: **Warning:** This will **permanently** delete a directory and **all** of its contents. ```shell @@ -96,7 +96,7 @@ for example) . Execute the same full command with: Not all commands can be executed from a basic user account on a computer, you may need administrator's rights to execute commands that affect the system, or try to access protected data, for example. You can use `sudo` to execute these commands, but you -will likely be asked for an administrator password. +might be asked for an administrator password. ```shell sudo RESTRICTED-COMMAND @@ -108,8 +108,8 @@ damage to your data or system. ## Sample Git taskflow -If you are completely new to Git, looking through some [sample taskflows](https://rogerdudler.github.io/git-guide/) -will help you understand the best practices for using these commands as you work. +If you're completely new to Git, looking through some [sample taskflows](https://rogerdudler.github.io/git-guide/) +may help you understand the best practices for using these commands as you work. <!-- ## Troubleshooting diff --git a/doc/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md index 616bb752694..415edce0d7d 100644 --- a/doc/gitlab-basics/create-project.md +++ b/doc/gitlab-basics/create-project.md @@ -128,10 +128,10 @@ To use a custom project template on the **New project** page: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. -When you create a new repository locally, instead of manually creating a new project in GitLab +When you create a new repository locally, instead of manually creating a new project in GitLab and then [cloning the repository](start-using-git.md#clone-a-repository) locally, you can directly push it to GitLab to create the new project, all without leaving -your terminal. If you have access rights to the associated namespace, GitLab +your terminal. If you have access rights to the associated namespace, GitLab automatically creates a new project under that GitLab namespace with its visibility set to Private by default (you can later change it in the [project's settings](../public_access/public_access.md#how-to-change-project-visibility)). diff --git a/doc/gitlab-basics/img/fork_choose_namespace.png b/doc/gitlab-basics/img/fork_choose_namespace.png Binary files differdeleted file mode 100644 index 4c50276d5ad..00000000000 --- a/doc/gitlab-basics/img/fork_choose_namespace.png +++ /dev/null diff --git a/doc/gitlab-basics/img/fork_new.png b/doc/gitlab-basics/img/fork_new.png Binary files differdeleted file mode 100644 index 7bbc3d8fbae..00000000000 --- a/doc/gitlab-basics/img/fork_new.png +++ /dev/null diff --git a/doc/gitlab-basics/img/merge_request_page.png b/doc/gitlab-basics/img/merge_request_page.png Binary files differdeleted file mode 100644 index f6087294e22..00000000000 --- a/doc/gitlab-basics/img/merge_request_page.png +++ /dev/null diff --git a/doc/gitlab-basics/img/merge_request_select_branch.png b/doc/gitlab-basics/img/merge_request_select_branch.png Binary files differdeleted file mode 100644 index b1dec975f9b..00000000000 --- a/doc/gitlab-basics/img/merge_request_select_branch.png +++ /dev/null diff --git a/doc/gitlab-basics/img/project_clone_url.png b/doc/gitlab-basics/img/project_clone_url.png Binary files differdeleted file mode 100644 index bdd7d011db3..00000000000 --- a/doc/gitlab-basics/img/project_clone_url.png +++ /dev/null diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index 93ac17d823b..a1774ddb770 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -312,7 +312,7 @@ We need a security group for our database that will allow inbound traffic from t ### Create the database -DANGER: **Danger:** +DANGER: **Warning:** Avoid using burstable instances (t class instances) for the database as this could lead to performance issues due to CPU credits running out during sustained periods of high load. Now, it's time to create the database: @@ -349,6 +349,10 @@ Now that the database is created, let's move on to setting up Redis with ElastiC ElastiCache is an in-memory hosted caching solution. Redis maintains its own persistence and is used to store session data, temporary cache information, and background job queues for the GitLab application. +DANGER: **Warning:** +GitLab recommends you use ElastiCache Redis version 5.0.x, because version 6.x contains +a bug that [prevents Sidekiq from processing jobs](https://gitlab.com/gitlab-org/gitlab/-/issues/281683). + ### Create a Redis Security Group 1. Navigate to the EC2 dashboard. diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index b5e72a9b84a..9dc30ab2476 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -347,8 +347,8 @@ connect to it using SSH ([Secure Shell](https://en.wikipedia.org/wiki/Secure_She If you're running Windows, you'll need to connect using [PuTTY](https://www.putty.org) or an equivalent Windows SSH client. If you're running Linux or macOS, then you already have an SSH client installed. -Remember that you will need to login with the username and password you specified -[when you created](#basics) your Azure VM. +Remember to sign in with the username and password you specified when you +[created your Azure VM](#basics). If you need to reset your VM password, read [how to reset SSH credentials for a user on an Azure VM](https://docs.microsoft.com/en-us/azure/virtual-machines/troubleshooting/troubleshoot-ssh-connection). @@ -375,20 +375,20 @@ read on [using PuTTY in Windows](https://mediatemple.net/community/products/dv/2 ### Updating GitLab -Once you've logged in via SSH, enter the following command to update GitLab to the latest -version: +After signing in by using SSH, enter the following command to update GitLab to +the latest version: ```shell sudo apt-get update && sudo apt-get install gitlab-ce ``` -This command will update GitLab and its associated components to the latest versions, so it will -take a little time to complete. You'll see various update tasks being completed in your SSH -terminal window: +This command updates GitLab and its associated components to the latest versions, +so it will take a little time to complete. You'll see various update tasks being +completed in your SSH terminal window:  -Once the update process has completed, you'll see a message like this: +After the update process is complete, you'll see a message like this: ```plaintext Upgrade complete! If your GitLab server is misbehaving try running diff --git a/doc/install/digitaloceandocker.md b/doc/install/digitaloceandocker.md index fe32b37a9ed..deb8a8cc6ca 100644 --- a/doc/install/digitaloceandocker.md +++ b/doc/install/digitaloceandocker.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto --- diff --git a/doc/install/installation.md b/doc/install/installation.md index 0adf09595e4..87e3cd1ea06 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -90,6 +90,8 @@ The GitLab installation consists of setting up the following components: ## 1. Packages and dependencies +### sudo + `sudo` is not installed on Debian by default. Make sure your system is up-to-date and install it. @@ -110,6 +112,8 @@ sudo apt-get install -y vim sudo update-alternatives --set editor /usr/bin/vim.basic ``` +### Build dependencies + Install the required packages (needed to compile Ruby and native extensions to Ruby gems): ```shell @@ -129,69 +133,33 @@ If you want to use Kerberos for user authentication, install `libkrb5-dev` sudo apt-get install libkrb5-dev ``` -Make sure you have the right version of Git installed: - -```shell -# Install Git -sudo apt-get install -y git-core +### Git -# Make sure Git is version 2.24.0 or higher (recommended version is 2.28.0) -git --version -``` +From GitLab 13.6, we recommend you use the [Git version provided by +Gitaly](https://gitlab.com/gitlab-org/gitaly/-/issues/2729) +that: -Starting with GitLab 12.0, Git is required to be compiled with `libpcre2`. -Find out if that's the case: +- Is always at the version required by GitLab. +- May contain custom patches required for proper operation. ```shell -ldd $(command -v git) | grep pcre2 -``` - -The output should contain `libpcre2-8.so.0`. +# Install dependencies +sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev libpcre2-dev build-essential -If the system packaged Git is too old or not compiled with `pcre2`, remove it: +# Clone the Gitaly repository +git clone https://gitlab.com/gitlab-org/gitaly.git -b <X-Y-stable> /tmp/gitaly -```shell -sudo apt-get remove git-core +# Compile and install Git +cd /tmp/gitaly +sudo make git GIT_PREFIX=/usr/local ``` -On Ubuntu, install Git from [its official PPA](https://git-scm.com/download/linux): +Replace `<X-Y-stable>` with the stable branch that matches the GitLab version you want to +install. For example, if you want to install GitLab 13.6, use the branch name `13-6-stable`. -```shell -# run as root! -add-apt-repository ppa:git-core/ppa -apt update -apt install git -# repeat libpcre2 check as above -``` +When editing `config/gitlab.yml` later, change the `git -> bin_path` to `/usr/local/bin/git`. -On Debian, use the following compilation instructions: - -```shell -# Install dependencies -sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev build-essential - -# Download and compile pcre2 from source -curl --silent --show-error --location https://ftp.pcre.org/pub/pcre/pcre2-10.33.tar.gz --output pcre2.tar.gz -tar -xzf pcre2.tar.gz -cd pcre2-10.33 -chmod +x configure -./configure --prefix=/usr --enable-jit -make -sudo make install - -# Download and compile from source -cd /tmp -curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.28.0.tar.gz -echo 'f914c60a874d466c1e18467c864a910dd4ea22281ba6d4d58077cb0c3f115170 git-2.28.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.28.0.tar.gz -cd git-2.28.0/ -./configure --with-libpcre -make prefix=/usr/local all - -# Install into /usr/local/bin -sudo make prefix=/usr/local install - -# When editing config/gitlab.yml later, change the git -> bin_path to /usr/local/bin/git -``` +### GraphicsMagick For the [Custom Favicon](../user/admin_area/appearance.md#favicon) to work, GraphicsMagick needs to be installed. @@ -200,6 +168,8 @@ needs to be installed. sudo apt-get install -y graphicsmagick ``` +### Mail server + In order to receive mail notifications, make sure to install a mail server. By default, Debian is shipped with `exim4` but this [has problems](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/12754) while @@ -212,6 +182,8 @@ sudo apt-get install -y postfix Then select 'Internet Site' and press enter to confirm the hostname. +### Exiftool + [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse#dependencies) requires `exiftool` to remove EXIF data from uploaded images. @@ -243,9 +215,9 @@ Download Ruby and compile it: ```shell mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.6/ruby-2.6.6.tar.gz -echo '2d78048e293817f38d4ede4ebc7873013e97bb0b ruby-2.6.6.tar.gz' | shasum -c - && tar xzf ruby-2.6.6.tar.gz -cd ruby-2.6.6 +curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.2.tar.gz +echo 'cb9731a17487e0ad84037490a6baf8bfa31a09e8 ruby-2.7.2.tar.gz' | shasum -c - && tar xzf ruby-2.7.2.tar.gz +cd ruby-2.7.2 ./configure --disable-install-rdoc make @@ -463,22 +435,22 @@ Clone Community Edition: ```shell # Clone GitLab repository -sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-foss.git -b X-Y-stable gitlab +sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-foss.git -b <X-Y-stable> gitlab ``` Clone Enterprise Edition: ```shell # Clone GitLab repository -sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab.git -b X-Y-stable gitlab +sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab.git -b <X-Y-stable> gitlab ``` -Make sure to replace `X-Y-stable` with the stable branch that matches the +Make sure to replace `<X-Y-stable>` with the stable branch that matches the version you want to install. For example, if you want to install 11.8 you would use the branch name `11-8-stable`. CAUTION: **Caution:** -You can change `X-Y-stable` to `master` if you want the *bleeding edge* version, but never install `master` on a production server! +You can change `<X-Y-stable>` to `master` if you want the *bleeding edge* version, but never install `master` on a production server! ### Configure It diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md deleted file mode 100644 index d067c341be8..00000000000 --- a/doc/install/kubernetes/gitlab_chart.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com/charts/' ---- - -This document was moved to [another location](https://docs.gitlab.com/charts/). diff --git a/doc/install/kubernetes/gitlab_omnibus.md b/doc/install/kubernetes/gitlab_omnibus.md deleted file mode 100644 index d067c341be8..00000000000 --- a/doc/install/kubernetes/gitlab_omnibus.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com/charts/' ---- - -This document was moved to [another location](https://docs.gitlab.com/charts/). diff --git a/doc/install/kubernetes/gitlab_runner_chart.md b/doc/install/kubernetes/gitlab_runner_chart.md deleted file mode 100644 index be58c957166..00000000000 --- a/doc/install/kubernetes/gitlab_runner_chart.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com/runner/install/kubernetes.html' ---- - -This document was moved to [another location](https://docs.gitlab.com/runner/install/kubernetes.html). diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md deleted file mode 100644 index d067c341be8..00000000000 --- a/doc/install/kubernetes/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com/charts/' ---- - -This document was moved to [another location](https://docs.gitlab.com/charts/). diff --git a/doc/install/kubernetes/preparation/connect.md b/doc/install/kubernetes/preparation/connect.md deleted file mode 100644 index 839461c982c..00000000000 --- a/doc/install/kubernetes/preparation/connect.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com/charts/installation/cloud/' ---- - -This document was moved to [another location](https://docs.gitlab.com/charts/installation/cloud/). diff --git a/doc/install/kubernetes/preparation/eks.md b/doc/install/kubernetes/preparation/eks.md deleted file mode 100644 index c3f53c2f580..00000000000 --- a/doc/install/kubernetes/preparation/eks.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com/charts/installation/cloud/eks.html' ---- - -This document was moved to [another location](https://docs.gitlab.com/charts/installation/cloud/eks.html). diff --git a/doc/install/kubernetes/preparation/networking.md b/doc/install/kubernetes/preparation/networking.md deleted file mode 100644 index 7e88bbd3cd1..00000000000 --- a/doc/install/kubernetes/preparation/networking.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com/charts/installation/deployment.html#networking-and-dns' ---- - -This document was moved to [another location](https://docs.gitlab.com/charts/installation/deployment.html#networking-and-dns). diff --git a/doc/install/kubernetes/preparation/rbac.md b/doc/install/kubernetes/preparation/rbac.md deleted file mode 100644 index fc18b91641c..00000000000 --- a/doc/install/kubernetes/preparation/rbac.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com/charts/installation/deployment.html#rbac' ---- - -This document was moved to [another location](https://docs.gitlab.com/charts/installation/deployment.html#rbac). diff --git a/doc/install/kubernetes/preparation/tiller.md b/doc/install/kubernetes/preparation/tiller.md deleted file mode 100644 index c1c7910703e..00000000000 --- a/doc/install/kubernetes/preparation/tiller.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com/charts/installation/tools.html' ---- - -This document was moved to [another location](https://docs.gitlab.com/charts/installation/tools.html). diff --git a/doc/install/kubernetes/preparation/tools_installation.md b/doc/install/kubernetes/preparation/tools_installation.md deleted file mode 100644 index c1c7910703e..00000000000 --- a/doc/install/kubernetes/preparation/tools_installation.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com/charts/installation/tools.html' ---- - -This document was moved to [another location](https://docs.gitlab.com/charts/installation/tools.html). diff --git a/doc/install/openshift_and_gitlab/index.md b/doc/install/openshift_and_gitlab/index.md index 7ac5aa6667a..2d7389a48a0 100644 --- a/doc/install/openshift_and_gitlab/index.md +++ b/doc/install/openshift_and_gitlab/index.md @@ -183,9 +183,9 @@ Using the all-in-one VM gives you the ability to test OpenShift whenever you want. That means you get to play with it, shutdown the VM, and pick up where you left off. -Sometimes though, you may encounter some issues, like OpenShift not running -when booting up the VM. The web UI may not responding or you may see issues -when trying to login with `oc`, like: +Occasionally, you may encounter issues, like OpenShift not running when booting +up the VM. The web UI may not respond, or you may see issues when trying to sign +in with `oc`, like: ```plaintext The connection to the server 10.2.2.2:8443 was refused - did you specify the right host or port? @@ -213,8 +213,7 @@ In that case, the OpenShift service might not be running, so in order to fix it: systemctl status openshift -l ``` -Now you will be able to login using `oc` (like we did before) and visit the web -console. +You can now sign in by using `oc` (like we did before) and visit the web console. ## Deploy GitLab @@ -497,14 +496,13 @@ oc adm policy add-scc-to-user anyuid system:serviceaccount:gitlab:gitlab-ce-user ## Conclusion -By now, you should have an understanding of the basic OpenShift Origin concepts -and a sense of how things work using the web console or the CLI. +You should now have an understanding of the basic OpenShift Origin concepts, and +a sense of how things work using the web console or the CLI. -GitLab was hard to install in previous versions of OpenShift, -but now that belongs to the past. Upload a template, create a project, add an -application and you are done. You are ready to login to your new GitLab instance. +Upload a template, create a project, add an application, and you're done. You're +ready to sign in to your new GitLab instance. -And remember that in this tutorial we just scratched the surface of what Origin -is capable of. As always, you can refer to the detailed -[documentation](https://docs.okd.io) to learn more about deploying your own OpenShift -PaaS and managing your applications with the ease of containers. +Remember that this tutorial doesn't address all that Origin is capable of. As +always, refer to the detailed [documentation](https://docs.okd.io) to learn more +about deploying your own OpenShift PaaS and managing your applications with +containers. diff --git a/doc/install/pivotal/index.md b/doc/install/pivotal/index.md index 6a4b361c842..41a5ea82ea2 100644 --- a/doc/install/pivotal/index.md +++ b/doc/install/pivotal/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab Pivotal Tile **(PREMIUM ONLY)** CAUTION: **Discontinued:** diff --git a/doc/install/postgresql_extensions.md b/doc/install/postgresql_extensions.md index 9e5a1e3d627..6355806f067 100644 --- a/doc/install/postgresql_extensions.md +++ b/doc/install/postgresql_extensions.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Managing PostgreSQL extensions This guide documents how to manage PostgreSQL extensions for installations with an external diff --git a/doc/install/requirements.md b/doc/install/requirements.md index bc320bcd335..4a61831ff86 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -57,6 +57,10 @@ The minimum required Go version is 1.13. ### Git versions +From GitLab 13.6: + +- Git 2.29.x and later is required. + From GitLab 13.1: - Git 2.24.x and later is required. @@ -144,6 +148,7 @@ GitLab version | Minimum PostgreSQL version -|- 10.0 | 9.6 13.0 | 11 +13.6 | 12 You must also ensure the `pg_trgm` and `btree_gist` extensions are [loaded into every GitLab database](postgresql_extensions.html). diff --git a/doc/integration/README.md b/doc/integration/README.md index c8ce367e99f..25e8c1a51c1 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index 7cb8f8b70ce..d290ffa92b9 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -1,11 +1,17 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Akismet -GitLab leverages [Akismet](https://akismet.com/) to protect against spam. Currently +GitLab leverages [Akismet](https://akismet.com/) to protect against spam. GitLab uses Akismet to prevent the creation of spam issues on public projects. Issues -created via the web UI or the API can be submitted to Akismet for review. +created through the web UI or the API can be submitted to Akismet for review. -Detected spam will be rejected, and an entry in the "Spam Log" section in the -Admin page will be created. +Detected spam is rejected, and an entry is added in the **Spam Log** section of the +Admin page. Privacy note: GitLab submits the user's IP and user agent to Akismet. @@ -17,11 +23,11 @@ In earlier GitLab versions, this only applied to API and non-project members. To use Akismet: -1. Go to the URL: <https://akismet.com/account/> -1. Sign-in or create a new account. -1. Click on **Show** to reveal the API key. +1. Go to the [Akismet sign-in page](https://akismet.com/account/). +1. Sign in or create a new account. +1. Click **Show** to reveal the API key. 1. Go to **Admin Area > Settings > Reporting** (`/admin/application_settings/reporting`). -1. Check the **Enable Akismet** checkbox. +1. Select the **Enable Akismet** checkbox. 1. Fill in the API key from step 3. 1. Save the configuration. @@ -29,23 +35,20 @@ To use Akismet: ## Training -NOTE: **Note:** -Training the Akismet filter is only available in GitLab 8.11 and later. - -As a way to better recognize between spam and ham, you can train the Akismet +To better differentiate between spam and ham, you can train the Akismet filter whenever there is a false positive or false negative. When an entry is recognized as spam, it is rejected and added to the Spam Logs. -From here you can review if they are really spam. If one of them is not really +From here you can review if entries are really spam. If one of them is not really spam, you can use the **Submit as ham** button to tell Akismet that it falsely recognized an entry as spam.  -If an entry that is actually spam was not recognized as such, you will be able -to also submit this to Akismet. The **Submit as spam** button will only appear -to admin users. +If an entry that is actually spam was not recognized as such, you can also submit +this information to Akismet. The **Submit as spam** button is only displayed +to administrator users.  -Training Akismet will help it to recognize spam more accurately in the future. +Training Akismet helps it to recognize spam more accurately in the future. diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index d851b9f5dc7..339d97cb00f 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Auth0 OmniAuth Provider To enable the Auth0 OmniAuth provider, you must create an Auth0 account, and an @@ -6,31 +12,30 @@ application. 1. Sign in to the [Auth0 Console](https://auth0.com/auth/login). If you need to create an account, you can do so at the same link. -1. Select "New App/API". +1. Select **New App/API**. 1. Provide the Application Name ('GitLab' works fine). -1. Once created, you should see the Quick Start options. Disregard them and - select 'Settings' above the Quick Start options. +1. After creating, you should see the **Quick Start** options. Disregard them and + select **Settings** above the **Quick Start** options. -1. At the top of the Settings screen, you should see your Domain, Client ID and - Client Secret. Take note of these as you'll need to put them in the - configuration file. For example: +1. At the top of the Settings screen, you should see your **Domain**, **Client ID**, and + **Client Secret**. These values are needed in the configuration file. For example: - Domain: `test1234.auth0.com` - Client ID: `t6X8L2465bNePWLOvt9yi41i` - Client Secret: `KbveM3nqfjwCbrhaUy_gDu2dss8TIlHIdzlyf33pB7dEK5u_NyQdp65O_o02hXs2` -1. Fill in the Allowed Callback URLs: +1. Fill in the **Allowed Callback URLs**: - `http://YOUR_GITLAB_URL/users/auth/auth0/callback` (or) - `https://YOUR_GITLAB_URL/users/auth/auth0/callback` -1. Fill in the Allowed Origins (CORS): +1. Fill in the **Allowed Origins (CORS)**: - `http://YOUR_GITLAB_URL` (or) - `https://YOUR_GITLAB_URL` 1. On your GitLab server, open the configuration file. - For Omnibus package: + For Omnibus GitLab: ```shell sudo editor /etc/gitlab/gitlab.rb @@ -43,12 +48,12 @@ application. sudo -u git -H editor config/gitlab.yml ``` -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) +1. Read [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. 1. Add the provider configuration: - For Omnibus package: + For Omnibus GitLab: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -81,10 +86,14 @@ application. 1. Change `YOUR_AUTH0_CLIENT_SECRET` to the client secret from the Auth0 Console page from step 5. -1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you - installed GitLab via Omnibus or from source respectively. +1. Reconfigure or restart GitLab, depending on your installation method: + + - *If you installed from Omnibus GitLab,* + [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab. + - *If you installed from source,* + [restart GitLab](../administration/restart_gitlab.md#installations-from-source). -On the sign in page there should now be an Auth0 icon below the regular sign in -form. Click the icon to begin the authentication process. Auth0 will ask the -user to sign in and authorize the GitLab application. If everything goes well -the user will be returned to GitLab and will be signed in. +On the sign-in page there should now be an Auth0 icon below the regular sign-in +form. Click the icon to begin the authentication process. Auth0 asks the +user to sign in and authorize the GitLab application. If the user authenticates +successfully, the user is returned to GitLab and signed in. diff --git a/doc/integration/azure.md b/doc/integration/azure.md index 2059707e38c..a9660e1d716 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -1,6 +1,12 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Microsoft Azure OAuth2 OmniAuth Provider -To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your application with Azure. Azure will generate a client ID and secret key for you to use. +To enable the Microsoft Azure OAuth2 OmniAuth provider, you must register your application with Azure. Azure generates a client ID and secret key for you to use. Sign in to the [Azure Portal](https://portal.azure.com), and follow the instructions in the [Microsoft Quickstart documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app). @@ -9,15 +15,19 @@ As you go through the Microsoft procedure, keep the following in mind: - If you have multiple instances of Azure Active Directory, you can switch to the desired tenant. - You're setting up a Web application. -- For the redirect URI, you'll need the URL of the Azure OAuth callback of your GitLab installation (for example, `https://gitlab.mycompany.com/users/auth/azure_oauth2/callback`). The type dropdown should be set to "Web". +- The redirect URI requires the URL of the Azure OAuth callback of your GitLab + installation. For example, `https://gitlab.mycompany.com/users/auth/azure_oauth2/callback`. + The type dropdown should be set to **Web**. - The `client ID` and `client secret` are terms associated with OAuth 2. In some Microsoft documentation, the terms may be listed as `Application ID` and `Application Secret`. -- If you need to generate a new client secret, follow the Microsoft documentation on how to [Create a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#create-a-new-application-secret). -- Save the client ID and client secret for your new app. Once you leave the Azure portal, you won't be able to find the client secret again. +- If you need to generate a new client secret, follow the Microsoft documentation + for [creating a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#create-a-new-application-secret). +- Save the client ID and client secret for your new app, as the client secret is only + displayed one time. 1. On your GitLab server, open the configuration file. - For Omnibus package: + For Omnibus GitLab: ```shell sudo editor /etc/gitlab/gitlab.rb @@ -31,11 +41,12 @@ As you go through the Microsoft procedure, keep the following in mind: sudo -u git -H editor config/gitlab.yml ``` -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. +1. Refer to [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) + for initial settings. 1. Add the provider configuration: - For Omnibus package: + For Omnibus GitLab: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -60,16 +71,22 @@ As you go through the Microsoft procedure, keep the following in mind: ``` The `base_azure_url` is optional and can be added for different locales; - e.g. `base_azure_url: "https://login.microsoftonline.de"`. + such as `base_azure_url: "https://login.microsoftonline.de"`. -1. Replace 'CLIENT ID', 'CLIENT SECRET' and 'TENANT ID' with the values you got above. +1. Replace `CLIENT ID`, `CLIENT SECRET` and `TENANT ID` with the values you got above. 1. Save the configuration file. -1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you - installed GitLab via Omnibus or from source respectively. +1. Reconfigure or restart GitLab, depending on your installation method: + + - *If you installed from Omnibus GitLab,* + [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab. + - *If you installed from source,* + [restart GitLab](../administration/restart_gitlab.md#installations-from-source). + +On the sign-in page, you should now see a Microsoft icon below the regular sign-in form. +Click the icon to begin the authentication process. Microsoft then asks you to +sign in and authorize the GitLab application. If successful, you are returned to GitLab and signed in. -On the sign-in page, you should now see a Microsoft icon below the regular sign in form. Click the icon -to begin the authentication process. Microsoft then asks you to sign in and authorize the GitLab application. If everything goes well, you are returned to GitLab and signed in. -See [Enable OmniAuth for an Existing User](omniauth.md#enable-omniauth-for-an-existing-user) +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 newly-available Azure AD accounts. diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index a151fbf50e7..3dc6983355c 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -1,34 +1,29 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Integrate your GitLab server with Bitbucket Cloud NOTE: **Note:** Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an -earlier version, you'll need to explicitly enable it. - -Import projects from Bitbucket.org and login to your GitLab instance with your -Bitbucket.org account. - -## Overview +earlier version, you must explicitly enable it. You can set up Bitbucket.org as an OAuth2 provider so that you can use your -credentials to authenticate into GitLab or import your projects from +Bitbucket.org account credentials to sign into GitLab or import your projects from Bitbucket.org. -- To use Bitbucket.org as an OmniAuth provider, follow the [Bitbucket OmniAuth - provider](#bitbucket-omniauth-provider) section. +- To use Bitbucket.org as an OmniAuth provider, follow the + [Bitbucket OmniAuth provider](#bitbucket-omniauth-provider) section. - To import projects from Bitbucket, follow both the [Bitbucket OmniAuth provider](#bitbucket-omniauth-provider) and [Bitbucket project import](#bitbucket-project-import) sections. ## Bitbucket OmniAuth provider -NOTE: **Note:** -GitLab 8.15 significantly simplified the way to integrate Bitbucket.org with -GitLab. You are encouraged to upgrade your GitLab instance if you haven't done so -already. If you're using GitLab 8.14 or below, [use the previous integration -docs](https://gitlab.com/gitlab-org/gitlab/blob/8-14-stable-ee/doc/integration/bitbucket.md). - To enable the Bitbucket OmniAuth provider you must register your application -with Bitbucket.org. Bitbucket will generate an application ID and secret key for +with Bitbucket.org. Bitbucket generates an application ID and secret key for you to use. 1. Sign in to [Bitbucket.org](https://bitbucket.org). @@ -36,26 +31,23 @@ you to use. settings (**Manage team**), depending on how you want the application registered. It does not matter if the application is registered as an individual or a team, that is entirely up to you. -1. Select **OAuth** in the left menu under "Access Management". +1. In the left menu under **Access Management**, select **OAuth**. 1. Select **Add consumer**. 1. Provide the required details: - | Item | Description | - | :--- | :---------- | - | **Name** | This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. | - | **Application description** | Fill this in if you wish. | - | **Callback URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com/users/auth`. | - | **URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com`. | - - NOTE: Be sure to append `/users/auth` to the end of the callback URL - to prevent a [OAuth2 convert - redirect](http://tetraph.com/covert_redirect/) vulnerability. - - NOTE: Starting in GitLab 8.15, you MUST specify a callback URL, or you will - see an "Invalid redirect_uri" message. For more details, see [the - Bitbucket documentation](https://confluence.atlassian.com/bitbucket/oauth-faq-338365710.html). + - **Name:** This can be anything. Consider something like `<Organization>'s GitLab` + or `<Your Name>'s GitLab` or something else descriptive. + - **Application description:** *(Optional)* Fill this in if you wish. + - **Callback URL:** (Required in GitLab versions 8.15 and greater) + The URL to your GitLab installation, such as + `https://gitlab.example.com/users/auth`. Be sure to append `/users/auth` to + the end of the callback URL to prevent an + [OAuth2 convert redirect](http://tetraph.com/covert_redirect/) vulnerability. + Leaving this field empty + [results in an `Invalid redirect_uri` message](https://confluence.atlassian.com/bitbucket/oauth-faq-338365710.html). + - **URL:** The URL to your GitLab installation, such as `https://gitlab.example.com`. - And grant at least the following permissions: +1. Grant at least the following permissions: ```plaintext Account: Email, Read @@ -69,8 +61,8 @@ you to use.  1. Select **Save**. -1. Select your newly created OAuth consumer and you should now see a Key and - Secret in the list of OAuth consumers. Keep this page open as you continue +1. Select your newly created OAuth consumer, and you should now see a **Key** and + **Secret** in the list of OAuth consumers. Keep this page open as you continue the configuration.  @@ -119,16 +111,16 @@ you to use. 1. Save the configuration file. 1. For the changes to take effect, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) if you installed via - Omnibus, or [restart](../administration/restart_gitlab.md#installations-from-source) if installed from source. + Omnibus GitLab, or [restart](../administration/restart_gitlab.md#installations-from-source) if installed from source. -On the sign in page there should now be a Bitbucket icon below the regular sign -in form. Click the icon to begin the authentication process. Bitbucket will ask -the user to sign in and authorize the GitLab application. If everything goes -well, the user will be returned to GitLab and will be signed in. +On the sign-in page there should now be a Bitbucket icon below the regular +sign-in form. Click the icon to begin the authentication process. Bitbucket asks +the user to sign in and authorize the GitLab application. If successful, the user +is returned to GitLab and signed in. ## Bitbucket project import -Once the above configuration is set up, you can use Bitbucket to sign into +After the above configuration is set up, you can use Bitbucket to sign into GitLab and [start importing your projects](../user/project/import/bitbucket.md). If you want to import projects from Bitbucket, but don't want to enable signing in, diff --git a/doc/integration/cas.md b/doc/integration/cas.md index eee801350eb..e61988c3301 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # CAS OmniAuth Provider To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab will supply to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for backchannel logout. diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index a88f2db5c26..095c58f17fc 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -23,7 +23,9 @@ and the advantage of the following special searches: | GitLab version | Elasticsearch version | |---------------------------------------------|-------------------------------| -| GitLab Enterprise Edition 12.7 or greater | Elasticsearch 6.x through 7.x | +| GitLab Enterprise Edition 13.6 or greater | Elasticsearch 7.x (6.4 - 6.x deprecated to be removed in 13.8) | +| GitLab Enterprise Edition 13.2 through 13.5 | Elasticsearch 6.4 through 7.x | +| GitLab Enterprise Edition 12.7 through 13.2 | Elasticsearch 6.x through 7.x | | GitLab Enterprise Edition 11.5 through 12.6 | Elasticsearch 5.6 through 6.x | | GitLab Enterprise Edition 9.0 through 11.4 | Elasticsearch 5.1 through 5.5 | | GitLab Enterprise Edition 8.4 through 8.17 | Elasticsearch 2.4 with [Delete By Query Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/2.4/plugins-delete-by-query.html) installed | @@ -56,7 +58,7 @@ A few notes on CPU and storage: see boosts in both query and indexing performance. Keep in mind, these are **minimum requirements** for Elasticsearch. -Heavily-utilized Elasticsearch clusters will likely require considerably more +Heavily-used Elasticsearch clusters will likely require considerably more resources. ## Installing Elasticsearch @@ -244,6 +246,29 @@ for filtering to work correctly. To do this run the Rake tasks `gitlab:elastic:r `gitlab:elastic:clear_index_status`. Afterwards, removing a namespace or a project from the list will delete the data from the Elasticsearch index as expected. +## Enabling custom language analyzers + +You can improve the language support for Chinese and Japanese languages by utilizing [smartcn](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) and/or [kuromoji](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) analysis plugins from Elastic. + +To enable language(s) support: + +1. Install the desired plugin(s), please refer to [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/plugins/7.9/installation.html) for plugins installation instructions. The plugin(s) must be installed on every node in the cluster, and each node must be restarted after installation. For a list of plugins, see the table later in this section. +1. Navigate to the **Admin Area** (wrench icon), then **Settings > General**.. +1. Expand the **Advanced Search** section and locate **Custom analyzers: language support**. +1. Enable plugin(s) support for **Indexing**. +1. Click **Save changes** for the changes to take effect. +1. Trigger [Zero downtime reindexing](#zero-downtime-reindexing) or reindex everything from scratch to create a new index with updated mappings. +1. Enable plugin(s) support for **Searching** after the previous step is completed. + +For guidance on what to install, see the following Elasticsearch language plugin options: + +| Parameter | Description | +|-------------------------------------------------------|-------------| +| `Enable Chinese (smartcn) custom analyzer: Indexing` | Enables or disables Chinese language support using [smartcn](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) custom analyzer for newly created indices.| +| `Enable Chinese (smartcn) custom analyzer: Search` | Enables or disables using [smartcn](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) fields for Advanced Search. Please only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html), enabling custom analyzer indexing and recreating the index.| +| `Enable Japanese (kuromoji) custom analyzer: Indexing` | Enables or disables Japanese language support using [kuromoji](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) custom analyzer for newly created indices.| +| `Enable Japanese (kuromoji) custom analyzer: Search` | Enables or disables using [kuromoji](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) fields for Advanced Search. Please only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html), enabling custom analyzer indexing and recreating the index.| + ## Disabling Advanced Search To disable the Elasticsearch integration: diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index 96c9b9d7f62..a4fca36b154 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # External issue tracker GitLab has a great [issue tracker](../user/project/issues/index.md) but you can also use an external diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index dbefb560fe7..bb699fa90b7 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Facebook OAuth2 OmniAuth Provider To enable the Facebook OmniAuth provider you must register your application with Facebook. Facebook will generate an app ID and secret key for you to use. diff --git a/doc/integration/github.md b/doc/integration/github.md index ce2b50acc54..8407920c631 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -1,6 +1,14 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Integrate your GitLab instance with GitHub -You can integrate your GitLab instance with GitHub.com as well as GitHub Enterprise to enable users to import projects from GitHub and/or to login to your GitLab instance with your GitHub account. +You can integrate your GitLab instance with GitHub.com and GitHub Enterprise to +enable users to import projects from GitHub or sign in to your GitLab instance +with your GitHub account. ## Enabling GitHub OAuth @@ -18,11 +26,11 @@ See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) Once you have configured the GitHub provider, you'll need the following information, which you'll need to substitute in the GitLab configuration file, in the steps shown next. -| Setting from GitHub | Substitute in the GitLab configuration file | Description | -|:---------------------|:-----------------------------------------------|:------------| -| Client ID | `YOUR_APP_ID` | OAuth 2 Client ID | -| Client Secret | `YOUR_APP_SECRET` | OAuth 2 Client Secret | -| URL | `https://github.example.com/` | GitHub Deployment URL | +| Setting from GitHub | Substitute in the GitLab configuration file | Description | +|:---------------------|:---------------------------------------------|:------------| +| Client ID | `YOUR_APP_ID` | OAuth 2 Client ID | +| Client Secret | `YOUR_APP_SECRET` | OAuth 2 Client Secret | +| URL | `https://github.example.com/` | GitHub Deployment URL | Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server: diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index a200f6b6470..c618d226290 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Integrate your server with GitLab.com Import projects from GitLab.com and login to your GitLab instance with your GitLab.com account. diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 526db8a7338..72196fd0f52 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Gmail actions buttons for GitLab GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview). diff --git a/doc/integration/google.md b/doc/integration/google.md index 4cf589c1da8..cd40aaff30a 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Google OAuth2 OmniAuth Provider To enable the Google OAuth2 OmniAuth provider you must register your application diff --git a/doc/integration/img/jira_dev_panel_jira_setup_1.png b/doc/integration/img/jira_dev_panel_jira_setup_1.png Binary files differdeleted file mode 100644 index 5c0f594cc1d..00000000000 --- a/doc/integration/img/jira_dev_panel_jira_setup_1.png +++ /dev/null diff --git a/doc/integration/img/spam_log.png b/doc/integration/img/spam_log.png Binary files differindex 43e267daff4..693ea2a55cd 100644 --- a/doc/integration/img/spam_log.png +++ b/doc/integration/img/spam_log.png diff --git a/doc/integration/img/submit_issue.png b/doc/integration/img/submit_issue.png Binary files differindex e794eac189e..c1bb725cc03 100644 --- a/doc/integration/img/submit_issue.png +++ b/doc/integration/img/submit_issue.png diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 8fc638db95a..7eb147c1fe6 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Jenkins CI service **(STARTER)** NOTE: **Note:** diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index 5fc30bf3305..63d5ac48765 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Jenkins CI (deprecated) service NOTE: **Note:** diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md index b86eb1c38b6..1bd3095edce 100644 --- a/doc/integration/jira_development_panel.md +++ b/doc/integration/jira_development_panel.md @@ -9,9 +9,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2381) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/233149) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4. -The Jira Development Panel integration allows you to reference Jira issues within GitLab, displaying activity in the [Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) in the issue. It complements the [GitLab Jira integration](../user/project/integrations/jira.md). You may choose to configure both integrations to take advantage of both sets of features. (See a [feature comparison](../user/project/integrations/jira_integrations.md#feature-comparison)). +The Jira Development Panel integration allows you to reference Jira issues within GitLab, displaying +activity in the [Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) +in the issue. -Depending on your environment, you can enable this integration by configuring the Jira DVCS connector or by using the GitLab for Jira app in the Atlassian Marketplace. See the [Configuration](#configuration) section for details. +It complements the [GitLab Jira integration](../user/project/integrations/jira.md). You may choose +to configure both integrations to take advantage of both sets of features. See a +[feature comparison](../user/project/integrations/jira_integrations.md#feature-comparison). + +Depending on your environment, you can enable this integration by either: + +- Configuring the Jira DVCS connector. +- Using the GitLab for Jira app in the Atlassian Marketplace. + +See the [Configuration](#configuration) section for details. ## Features @@ -24,10 +35,12 @@ Depending on your environment, you can enable this integration by configuring th With this integration, you can access related GitLab merge requests, branches, and commits directly from a Jira issue, reflecting your work in GitLab. From the Development panel, you can open a detailed view and take actions including creating a new merge request from a branch. For more information, see [Usage](#usage). -This integration connects all GitLab projects within a top-level group or a personal namespace to projects in the Jira instance. -A top-level GitLab group is one that does not have any parent group itself. All the projects of that top-level group, -as well as projects of the top-level group's subgroups nesting down, are connected. Alternatively, you can specify -a GitLab personal namespace in the Jira configuration, which will then connect the projects in that personal namespace to Jira. +This integration connects all GitLab projects to projects in the Jira instance within either: + +- A top-level group. A top-level GitLab group is one that does not have any parent group itself. All + the projects of that top-level group, as well as projects of the top-level group's subgroups nesting + down, are connected. +- A personal namespace, which then connects the projects in that personal namespace to Jira. This differs from the [Jira integration](../user/project/integrations/jira.md), where the mapping is between one GitLab project and the entire Jira instance. @@ -36,17 +49,23 @@ This differs from the [Jira integration](../user/project/integrations/jira.md), <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Agile Management - GitLab-Jira Development Panel Integration](https://www.youtube.com/watch?v=VjVTOmMl85M&feature=youtu.be). -- If you're using GitLab.com and Jira Cloud, the recommended method to enable this integration is to install the [GitLab for Jira app](#gitlab-for-jira-app) from the Atlassian Marketplace, which offers a real-time sync between GitLab and Jira. -- If you're using self-managed GitLab, self-managed Jira, or both, configure the integration using [Jira's DVCS Connector](#jira-dvcs-configuration), which syncs data hourly. +If you're using: -We recommend that a GitLab group admin -or instance admin (in the case of self-managed GitLab) set up the integration, -in order to simplify administration. +- GitLab.com and Jira Cloud, we recommend you enable this integration by installing the + [GitLab for Jira app](#gitlab-for-jira-app) from the Atlassian Marketplace, which offers a real-time + sync between GitLab and Jira. +- Self-managed GitLab, self-managed Jira, or both, configure the integration using + [Jira's DVCS Connector](#jira-dvcs-configuration), which syncs data hourly. + +We recommend that a GitLab group administrator or instance administrator (in the case of +self-managed GitLab) set up the integration to simplify administration. ### Jira DVCS configuration -NOTE: **Note:** -If you're using GitLab.com and Jira Cloud, we recommend you use the [GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector. +If you're using GitLab.com and Jira Cloud, we recommend you use the +[GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector. + +When configuring Jira DVCS Connector: - If you are using self-managed GitLab, make sure your GitLab instance is accessible by Jira. - If you're connecting to Jira Cloud, ensure your instance is accessible through the internet. @@ -85,8 +104,8 @@ create and use a single-purpose `jira` user in GitLab. #### Jira DVCS Connector setup -NOTE: **Note:** -If you're using GitLab.com and Jira Cloud, we recommend you use the [GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector. +If you're using GitLab.com and Jira Cloud, we recommend you use the +[GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector. 1. Ensure you have completed the [GitLab configuration](#gitlab-account-configuration-for-dvcs). 1. If you're using Jira Server, go to **Settings (gear) > Applications > DVCS accounts**. @@ -288,14 +307,6 @@ For more information on using Jira Smart Commits to track time against an issue, ## Limitations -- This integration is currently not supported on GitLab instances under a [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab) (for example, `http://example.com/gitlab`). - -## Changelog - -### 11.10 - -- [Instance admins can now setup integration for all namespaces](https://gitlab.com/gitlab-org/gitlab/-/issues/8902) - -### 11.1 - -- [Support GitLab subgroups in Jira development panel](https://gitlab.com/gitlab-org/gitlab/-/issues/3561) +This integration is currently not supported on GitLab instances under a +[relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab). +For example, `http://example.com/gitlab`. diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 1a193deca18..50468443769 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Source Code +stage: Manage +group: Access info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: reference, how-to --- @@ -47,7 +47,7 @@ sudo chmod 0600 /etc/http.keytab ### Configure GitLab -**Installations from source** +#### Installations from source NOTE: **Note:** For source installations, make sure the `kerberos` gem group @@ -74,7 +74,7 @@ For source installations, make sure the `kerberos` gem group 1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect. -**Omnibus package installations** +#### Omnibus package installations 1. Edit `/etc/gitlab/gitlab.rb`: @@ -91,23 +91,75 @@ GitLab will now offer the `negotiate` authentication method for signing in and HTTP Git access, enabling Git clients that support this authentication protocol to authenticate with Kerberos tokens. -## Creating and linking Kerberos accounts +#### Enable single sign-on -The Administrative user can navigate to **Admin > Users > Example User > Identities** -and attach a Kerberos account. Existing GitLab users can go to **Profile > Account** -and attach a Kerberos account. If you want to allow users without a GitLab -account to login, you should enable the option `allow_single_sign_on` as -described in the [Configure GitLab](#configure-gitlab) section. Then, the first -time a user signs in with Kerberos credentials, GitLab will create a new GitLab -user associated with the email, which is built from the Kerberos username and -realm. User accounts will be created automatically when authentication was -successful. +See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) +for initial settings to enable single sign-on and add Kerberos servers +as an identity provider. -## Linking Kerberos and LDAP accounts together +## Create and link Kerberos accounts -If your users log in with Kerberos, but you also have [LDAP integration](../administration/auth/ldap/index.md) -enabled, then your users will be automatically linked to their LDAP accounts on -first login. For this to work, some prerequisites must be met: +You can either link a Kerberos account to an existing GitLab account, or +set up GitLab to create a new account when a Kerberos user tries to sign in. + +### Link a Kerberos account to an existing GitLab account + +If you're an administrator, you can link a Kerberos account to an +existing GitLab account. To do so: + +1. Navigate to **Admin Area > Overview > Users > Example User**. +1. Select the Identities tab. +1. Select 'Kerberos Spnego' in the 'Provider' dropdown box. +1. Make sure the **Identifier** corresponds to the Kerberos username. +1. Select **Save changes**. + +If you're not an administrator: + +1. Select your avatar in the upper-right corner, and select **Settings**. +1. Select Account. In the **Social sign-in** section, select + **Connect Kerberos Spnego**. + If you don't see a **Social sign-in** Kerberos option, follow the + requirements in [Enable single sign-on](#enable-single-sign-on). + +In either case, you should now be able to sign in to your GitLab account +with your Kerberos credentials. + +### Create accounts on first sign-in + +The first time users sign in to GitLab with their Kerberos accounts, +GitLab creates a matching account. +Before you continue, review the [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) options in Omnibus and GitLab source. You must also include `kerberos`. + +With that information at hand: + +1. Include `'kerberos'` with the `allow_single_sign_on` setting. +1. For now, accept the default `block_auto_created_users` option, true. +1. When a user tries to sign in with Kerberos credentials, GitLab + creates a new account. + 1. If `block_auto_created_users` is true, the Kerberos user may see + a message like: + + ```shell + Your account has been blocked. Please contact your GitLab + administrator if you think this is an error. + ``` + + 1. As an administrator, you can confirm the new, blocked account. + Select **Admin Area > Overview > Users** and review the Blocked tab. + 1. You can enable the user. + 1. If `block_auto_created_users` is false, the Kerberos user is + authenticated and is signed in to GitLab. + +CAUTION: **Warning** +We recommend that you retain the default for `block_auto_created_users`. +Kerberos users who create accounts on GitLab without administrator +knowledge can be a security risk. + +## Link Kerberos and LDAP accounts together + +If your users sign in with Kerberos, but you also have [LDAP integration](../administration/auth/ldap/index.md) +enabled, your users will be linked to their LDAP accounts on their first sign-in. +For this to work, some prerequisites must be met: The Kerberos username must match the LDAP user's UID. You can choose which LDAP attribute is used as the UID in GitLab's [LDAP configuration](../administration/auth/ldap/index.md#configuration) @@ -125,10 +177,10 @@ LDAP Distinguished Names look like `sAMAccountName=foo,dc=ad,dc=example,dc=com`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9962) in GitLab 13.5. -You can configure custom allowed realms when -the user's Kerberos realm doesn't 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 will be ignored and an LDAP identity will not be linked. +You can configure custom allowed realms when the user's Kerberos realm doesn't +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 will be +ignored and an LDAP identity won't be linked. **For Omnibus installations** @@ -164,7 +216,7 @@ GitLab users with a linked Kerberos account can also `git pull` and `git push` using Kerberos tokens, i.e., without having to send their password with each operation. -DANGER: **Danger:** +DANGER: **Warning:** There is a [known issue](https://github.com/curl/curl/issues/1261) with `libcurl` older than version 7.64.1 wherein it won't reuse connections when negotiating. This leads to authorization issues when push is larger than `http.postBuffer` diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index 8566134815a..5957af292ab 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Sign into GitLab with (almost) any OAuth2 provider The `omniauth-oauth2-generic` gem allows Single Sign On between GitLab and your own OAuth2 provider diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index fd1c21d725d..68d10a3135e 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab as OAuth2 authentication service provider This document is about using GitLab as an OAuth authentication service provider diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index cf09c2f2803..eebafab2693 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # OmniAuth GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and @@ -82,8 +88,8 @@ To change these settings: ```ruby # CAUTION! - # This allows users to login without having a user account first. Define the allowed providers - # using an array, e.g. ["saml", "twitter"], or as true/false to allow all providers or none. + # This allows users to sign in without having a user account first. Define the allowed providers + # using an array, for example, ["saml", "twitter"], or as true/false to allow all providers or none. # User accounts will be created automatically when authentication was successful. gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'twitter'] gitlab_rails['omniauth_auto_link_ldap_user'] = true @@ -105,13 +111,13 @@ To change these settings: ```yaml ## OmniAuth settings omniauth: - # Allow login via Twitter, Google, etc. using OmniAuth providers + # Allow sign-in by using Twitter, Google, etc. using OmniAuth providers # Versions prior to 11.4 require this to be set to true # enabled: true # CAUTION! - # This allows users to login without having a user account first. Define the allowed providers - # using an array, e.g. ["saml", "twitter"], or as true/false to allow all providers or none. + # This allows users to sign in without having a user account first. Define the allowed providers + # using an array, for example, ["saml", "twitter"], or as true/false to allow all providers or none. # User accounts will be created automatically when authentication was successful. allow_single_sign_on: ["saml", "twitter"] @@ -171,9 +177,9 @@ like `google_oauth2` for Google. Refer to the examples for the full names of the supported providers. NOTE: **Note:** -If you decide to remove an OmniAuth provider from the external providers list -you will need to manually update the users that use this method to login, if you -want their accounts to be upgraded to full internal accounts. +If you decide to remove an OmniAuth provider from the external providers list, +you must manually update the users that use this method to sign in if you want +their accounts to be upgraded to full internal accounts. **For Omnibus installations** @@ -296,13 +302,13 @@ omniauth: ## Bypassing two factor authentication -Starting with GitLab 12.3, this allows users to login with the specified -providers without two factor authentication. +In GitLab 12.3 or later, users can sign in with specified providers _without_ +using two factor authentication. -Define the allowed providers using an array, e.g. `["twitter", 'google_oauth2']`, or as -`true`/`false` to allow all providers or none. This option should only be configured -for providers which already have two factor authentication (default: false). -This configuration dose not apply to SAML. +Define the allowed providers using an array (for example, `["twitter", 'google_oauth2']`), +or as `true` or `false` to allow all providers (or none). This option should be +configured only for providers which already have two factor authentication +(default: false). This configuration doesn't apply to SAML. ```ruby gitlab_rails['omniauth_allow_bypass_two_factor'] = ['twitter', 'google_oauth2'] @@ -317,13 +323,12 @@ omniauth: ## Automatically sign in with provider -You can add the `auto_sign_in_with_provider` setting to your -GitLab configuration to automatically redirect login requests -to your OmniAuth provider for authentication, thus removing the need to click a button -before actually signing in. +You can add the `auto_sign_in_with_provider` setting to your GitLab +configuration to redirect login requests to your OmniAuth provider for +authentication, removing the need to click a button before actually signing in. -For example, when using the Azure integration, you would set the following -to enable auto sign in. +For example, when using the Azure integration, set the following to enable auto +sign-in: For Omnibus package: @@ -338,13 +343,15 @@ omniauth: auto_sign_in_with_provider: azure_oauth2 ``` -Please keep in mind that every sign in attempt will be redirected to the OmniAuth provider, -so you will not be able to sign in using local credentials. Make sure that at least one -of the OmniAuth users has admin permissions. +Keep in mind that every sign-in attempt will be redirected to the OmniAuth +provider; you won't be able to sign in using local credentials. Ensure at least +one of the OmniAuth users has admin permissions. -You may also bypass the auto signin feature by browsing to +You may also bypass the auto sign in feature by browsing to `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. ## Passwords for users created via OmniAuth -The [Generated passwords for users created through integrated authentication](../security/passwords_for_integrated_authentication_methods.md) guide provides an overview of how GitLab generates and sets passwords for users created via OmniAuth. +The [Generated passwords for users created through integrated authentication](../security/passwords_for_integrated_authentication_methods.md) +guide provides an overview about how GitLab generates and sets passwords for +users created with OmniAuth. diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index b66262772da..bf33483f949 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab as OpenID Connect identity provider This document is about using GitLab as an OpenID Connect identity provider diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 1868711ca9c..545f60cddbf 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # reCAPTCHA GitLab leverages [Google's reCAPTCHA](https://www.google.com/recaptcha/about/) diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index dbd0a03e3cf..3290f18e2cb 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Salesforce OmniAuth Provider You can integrate your GitLab instance with [Salesforce](https://www.salesforce.com/) to enable users to log in to your GitLab instance with their Salesforce account. diff --git a/doc/integration/saml.md b/doc/integration/saml.md index ee08a0026cd..16a33a86472 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -369,18 +369,18 @@ omniauth: auto_sign_in_with_provider: saml ``` -Please keep in mind that every sign in attempt will be redirected to the SAML server, -so you will not be able to sign in using local credentials. Make sure that at least one -of the SAML users has admin permissions. +Keep in mind that every sign in attempt will be redirected to the SAML server; +you won't be able to sign in using local credentials. Ensure at least one of the +SAML users has admin permissions. -You may also bypass the auto signin feature by browsing to +You may also bypass the auto sign-in feature by browsing to `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. ### `attribute_statements` NOTE: **Note:** -This setting should only be used to map attributes that are part of the -OmniAuth `info` hash schema. +This setting should be used only to map attributes that are part of the OmniAuth +`info` hash schema. `attribute_statements` is used to map Attribute Names in a SAMLResponse to entries in the OmniAuth [`info` hash](https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema#schema-10-and-later). @@ -541,9 +541,14 @@ This integration uses the `certificate` and `private_key` settings for both asse ## Request signing (optional) -Another optional configuration is to sign SAML authentication requests. GitLab SAML Requests uses the SAML redirect binding so this is not necessary, unlike the SAML POST binding where signing is required to prevent intermediaries tampering with the requests. +Another optional configuration is to sign SAML authentication requests. GitLab +SAML Requests use the SAML redirect binding, so this isn't necessary (unlike the +SAML POST binding, where signing is required to prevent intermediaries from +tampering with the requests). -In order to sign, you need to create a private key and public certificate pair for your GitLab instance to use for SAML. The settings related to signing can be set in the `security` section of the configuration. +To sign, you need to create a private key and public certificate pair for your +GitLab instance to use for SAML. The settings for signing can be set in the +`security` section of the configuration. For example: @@ -636,7 +641,9 @@ Group SAML on a self-managed instance is limited when compared to the recommende ## Troubleshooting -You can find the base64-encoded SAML Response in the [`production_json.log`](../administration/logs.md#production_jsonlog). +### SAML Response + +You can find the base64-encoded SAML Response in the [`production_json.log`](../administration/logs.md#production_jsonlog). This response is sent from the IdP, and contains user information that is consumed by GitLab. Many errors in the SAML integration can be solved by decoding this response and comparing it to the SAML settings in the GitLab configuration file. ### GitLab+SAML Testing Environments @@ -646,13 +653,14 @@ If you only need a SAML provider for testing, a [quick start guide to start a Do ### 500 error after login -If you see a "500 error" in GitLab when you are redirected back from the SAML sign in page, -this likely indicates that GitLab could not get the email address for the SAML user. +If you see a "500 error" in GitLab when you are redirected back from the SAML +sign-in page, this likely indicates that GitLab couldn't get the email address +for the SAML user. -Make sure the IdP provides a claim containing the user's email address, using claim name -`email` or `mail`. +Ensure the IdP provides a claim containing the user's email address, using the +claim name `email` or `mail`. -### Redirect back to login screen with no evident error +### Redirect back to the login screen with no evident error If after signing in into your SAML server you are redirected back to the sign in page and no error is displayed, check your `production.log` file. It will most likely contain the @@ -682,7 +690,7 @@ This error means that the IdP doesn't recognize GitLab as a valid sender and receiver of SAML requests. Make sure to add the GitLab callback URL to the approved audiences of the IdP server. -### Missing claims +### Missing claims, or `Email can't be blank` errors The IdP server needs to pass certain information in order for GitLab to either create an account, or match the login information to an existing account. `email` @@ -710,3 +718,10 @@ For this you need take the following into account: Make sure that one of the above described scenarios is valid, or the requests will fail with one of the mentioned errors. + +### User is blocked when signing in through SAML + +The following are the most likely reasons that a user is blocked when signing in through SAML: + +- In the configuration, `gitlab_rails['omniauth_block_auto_created_users'] = true` is set and this is the user's first time signing in. +- There are [`required_groups`](#required-groups) configured, but the user is not a member of one. diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index 1b645541cec..59374d8ad6f 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Shibboleth OmniAuth Provider NOTE: **Note:** diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index c73db32a42a..ea2c4b3e93f 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Slash Commands > The `run` command was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md index fc55dbb9654..22481e14236 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Trello Power-Up GitLab's Trello Power-Up enables you to seamlessly attach diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index e501eac0c5f..bfe18c43e9d 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Twitter OAuth2 OmniAuth Provider To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter will generate a client ID and secret key for you to use. diff --git a/doc/integration/vault.md b/doc/integration/vault.md index cead8f7592a..ea63f16c72b 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -106,13 +106,17 @@ The following assumes you already have Vault installed and running. vault login -method=oidc port=8250 role=demo ``` - Here is a short explanation of what this command does: + Here's a short explanation of what this command does: - 1. In the **Write the OIDC Role Config** (step 4), we created a role called `demo`. We set `role=demo` so Vault knows which configuration we'd like to login in with. + 1. In the **Write the OIDC Role Config** (step 4), we created a role called + `demo`. We set `role=demo` so Vault knows which configuration we'd like to + sign in with. 1. To set Vault to use the `OIDC` sign-in method, we set `-method=oidc`. - 1. To set the port that GitLab should redirect to, we set `port=8250` or another port number that matches the port given to GitLab when listing [Redirect URIs](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). + 1. To set the port that GitLab should redirect to, we set `port=8250` or + another port number that matches the port given to GitLab when listing + [Redirect URIs](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). - Once you run the command above, it will present a link in the terminal. + After running the command, it will present a link in the terminal. Click the link in the terminal and a tab will open in the browser confirming you're signed into Vault via OIDC:  diff --git a/doc/legal/README.md b/doc/legal/README.md index 497a477419a..4b3bcac190c 100644 --- a/doc/legal/README.md +++ b/doc/legal/README.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/legal/corporate_contributor_license_agreement.md b/doc/legal/corporate_contributor_license_agreement.md index 018c4b575b5..2496c866906 100644 --- a/doc/legal/corporate_contributor_license_agreement.md +++ b/doc/legal/corporate_contributor_license_agreement.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Corporate contributor license agreement You accept and agree to the following terms and conditions for Your present and future Contributions submitted to GitLab B.V.. Except for the license granted herein to GitLab B.V. and recipients of software distributed by GitLab B.V., You reserve all right, title, and interest in and to Your Contributions. diff --git a/doc/legal/individual_contributor_license_agreement.md b/doc/legal/individual_contributor_license_agreement.md index 7a071414629..8e6683d0dc6 100644 --- a/doc/legal/individual_contributor_license_agreement.md +++ b/doc/legal/individual_contributor_license_agreement.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Individual contributor license agreement You accept and agree to the following terms and conditions for Your present and future Contributions submitted to GitLab B.V.. Except for the license granted herein to GitLab B.V. and recipients of software distributed by GitLab B.V., You reserve all right, title, and interest in and to Your Contributions. diff --git a/doc/migrate_ci_to_ce/README.md b/doc/migrate_ci_to_ce/README.md index 3233cfdbaba..17f9db10767 100644 --- a/doc/migrate_ci_to_ce/README.md +++ b/doc/migrate_ci_to_ce/README.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto --- diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md index 150264eddcb..fad2c0e39be 100644 --- a/doc/operations/error_tracking.md +++ b/doc/operations/error_tracking.md @@ -16,7 +16,7 @@ Error Tracking allows developers to easily discover and view the errors that the ### Deploying Sentry -You can sign up to the cloud hosted <https://sentry.io>, deploy your own [on-premise instance](https://github.com/getsentry/onpremise/) or use GitLab to [install Sentry to a Kubernetes cluster](../user/clusters/applications.md#install-sentry-using-gitlab-cicd). +You can sign up to the cloud hosted [Sentry](https://sentry.io), deploy your own [on-premise instance](https://github.com/getsentry/onpremise/), or use GitLab to [install Sentry to a Kubernetes cluster](../user/clusters/applications.md#install-sentry-using-gitlab-cicd). To make this easier, we are [considering shipping Sentry with GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5343). ### Enabling Sentry diff --git a/doc/operations/feature_flags.md b/doc/operations/feature_flags.md index 00ebfe5ccf8..cac243edded 100644 --- a/doc/operations/feature_flags.md +++ b/doc/operations/feature_flags.md @@ -135,24 +135,21 @@ Selecting **Random** provides inconsistent application behavior for individual u ### Percent of Users -Enables the feature for a percentage of authenticated users. It uses the -[`gradualRolloutUserId`](https://unleash.github.io/docs/activation_strategy#gradualrolloutuserid) -Unleash activation strategy. - -NOTE: **Note:** -[Percent rollout](#percent-rollout) with a consistency based on **User IDs** has the same -behavior. It is recommended to use percent rollout instead of percent of users as -it is more flexible. +Enables the feature for a percentage of authenticated users. It uses the Unleash activation strategy +[`gradualRolloutUserId`](https://unleash.github.io/docs/activation_strategy#gradualrolloutuserid). For example, set a value of 15% to enable the feature for 15% of authenticated users. The rollout percentage can be from 0% to 100%. -NOTE: **Note:** -Stickiness (consistent application behavior for the same user) is guaranteed for logged-in users, but not anonymous users. +Stickiness (consistent application behavior for the same user) is guaranteed for logged-in users, +but not anonymous users. + +Note that [percent rollout](#percent-rollout) with a consistency based on **User IDs** has the same +behavior. We recommend using percent rollout because it's more flexible than percent of users CAUTION: **Caution:** -If this strategy is selected, then the Unleash client **must** be given a user +If the percent of users strategy is selected, then the Unleash client **must** be given a user ID for the feature to be enabled. See the [Ruby example](#ruby-application-example) below. ### User IDs @@ -164,11 +161,9 @@ Enables the feature for a list of target users. It is implemented using the Unleash [`userWithId`](https://unleash.github.io/docs/activation_strategy#userwithid) activation strategy. -Enter user IDs as a comma-separated list of values. For example, -`user@example.com, user2@example.com`, or `username1,username2,username3`, and so on. - -NOTE: **Note:** -User IDs are identifiers for your application users. They do not need to be GitLab users. +Enter user IDs as a comma-separated list of values (for example, +`user@example.com, user2@example.com`, or `username1,username2,username3`, and so on). Note that +user IDs are identifiers for your application users. They do not need to be GitLab users. CAUTION: **Caution:** The Unleash client **must** be given a user ID for the feature to be enabled for @@ -306,11 +301,9 @@ To get the access credentials that your application needs to communicate with Gi For example, if the application runs for a production server, the **Application name** could be `production` or similar. This value is used for the environment spec evaluation. -NOTE: **Note:** -The meaning of these fields might change over time. For example, we are not sure -if **Instance ID** will be single token or multiple tokens, assigned to the -**Environment**. Also, **Application name** could describe the version of -application instead of the running environment. +Note that the meaning of these fields might change over time. For example, we're not sure if +**Instance ID** will be single token or multiple tokens, assigned to the **Environment**. Also, +**Application name** could describe the application version instead of the running environment. ### Choose a client library diff --git a/doc/operations/incident_management/alert_integrations.md b/doc/operations/incident_management/alert_integrations.md index 58c1e1eae76..7850841d380 100644 --- a/doc/operations/incident_management/alert_integrations.md +++ b/doc/operations/incident_management/alert_integrations.md @@ -9,7 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.8. -GitLab can accept alerts from any source via a webhook receiver. This can be configured generically or, in GitLab versions 13.1 and greater, you can configure +GitLab can accept alerts from any source via a webhook receiver. This can be configured +generically or, in GitLab versions 13.1 and greater, you can configure [External Prometheus instances](../metrics/alerts.md#external-prometheus-instances) to use this endpoint. @@ -26,16 +27,14 @@ The list displays the integration name, type, and status (enabled or disabled): ## Configuration -You can either configure alerts to integrate with an [external Prometheus server](#external-prometheus-integration), -or provide a [generic HTTP endpoint](#generic-http-endpoint) to receive alerts -from other services. +GitLab can receive alerts via a [HTTP endpoint](#generic-http-endpoint) that you configure, +or the [Prometheus integration](#external-prometheus-integration). -### Generic HTTP Endpoint +### Generic HTTP Endpoint **CORE** -Enabling the Generic HTTP Endpoint creates a unique HTTP endpoint that can receive alert payloads in JSON format. You can always -[customize the payload](#customizing-the-payload) to your liking. - -You will need to activate the endpoint and obtain credentials to set up this integration: +Enabling the Generic HTTP Endpoint activates a unique HTTP endpoint that can +receive alert payloads in JSON format. You can always +[customize the payload](#customize-the-alert-payload-outside-of-gitlab) to your liking. 1. Sign in to GitLab as a user with maintainer [permissions](../../user/permissions.md) for a project. @@ -44,20 +43,49 @@ You will need to activate the endpoint and obtain credentials to set up this int 1. Toggle the **Active** alert setting to display the **URL** and **Authorization Key** for the webhook configuration. +### HTTP Endpoints **PREMIUM** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4442) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. + +In [GitLab Premium](https://about.gitlab.com/pricing/), you can create multiple +unique HTTP endpoints to receive alerts from any external source in JSON format, +and you can [customize the payload](#customize-the-alert-payload-outside-of-gitlab). + +1. Sign in to GitLab as a user with maintainer [permissions](../../user/permissions.md) + for a project. +1. Navigate to **Settings > Operations** in your project. +1. Expand the **Alerts** section. +1. For each endpoint you want to create: + + 1. In the **Integration** dropdown menu, select **HTTP Endpoint**. + 1. Name the integration. + 1. Toggle the **Active** alert setting to display the **URL** and **Authorization Key** + for the webhook configuration. You will input the URL and Authorization Key + in your external service. + 1. _(Optional)_ To generate a test alert to test the new integration, enter a + sample payload, then click **Save and test alert payload**.Valid JSON is required. + 1. Click **Save Integration**. + +The new HTTP Endpoint displays in the [integrations list](#integrations-list). +You can edit the integration by selecting the **{pencil}** pencil icon on the right +side of the integrations list. + ### External Prometheus integration -For GitLab versions 13.1 and greater, please see [External Prometheus Instances](../metrics/alerts.md#external-prometheus-instances) to configure alerts for this integration. +For GitLab versions 13.1 and greater, please read +[External Prometheus Instances](../metrics/alerts.md#external-prometheus-instances) +to configure alerts for this integration. -## Customizing the payload +## Customize the alert payload outside of GitLab -You can customize the payload by sending the following parameters. This applies to all types of integrations. All fields -other than `title` are optional: +For all integration types, you can customize the payload by sending the following +parameters. All fields other than `title` are optional: | Property | Type | Description | | ------------------------- | --------------- | ----------- | | `title` | String | The title of the incident. Required. | | `description` | String | A high-level summary of the problem. | -| `start_time` | DateTime | The time of the incident. If none is provided, a timestamp of the issue will be used. | +| `start_time` | DateTime | The time of the incident. If none is provided, a timestamp of the issue is used. | | `end_time` | DateTime | For existing alerts only. When provided, the alert is resolved and the associated incident is closed. | | `service` | String | The affected service. | | `monitoring_tool` | String | The name of the associated monitoring tool. | @@ -74,8 +102,9 @@ can be a nested JSON object. For example: { "foo": { "bar": { "baz": 42 } } } ``` -TIP: **Payload size:** -Ensure your requests are smaller than the [payload application limits](../../administration/instance_limits.md#generic-alert-json-payloads). +TIP: **Tip:** +Ensure your requests are smaller than the +[payload application limits](../../administration/instance_limits.md#generic-alert-json-payloads). Example request: @@ -132,15 +161,21 @@ GitLab displays an error or success message, depending on the outcome of your te In GitLab versions 13.2 and greater, GitLab groups alerts based on their payload. When an incoming alert contains the same payload as another alert (excluding the `start_time` and `hosts` attributes), GitLab groups these alerts -together and displays a counter on the [Alert Management List](./incidents.md) +together and displays a counter on the [Alert Management List](incidents.md) and details pages. If the existing alert is already `resolved`, GitLab creates a new alert instead. - + ## Link to your Opsgenie Alerts +DANGER: **Deprecated:** +We are building deeper integration with Opsgenie and other alerting tools through +[HTTP endpoint integrations](#generic-http-endpoint) so you can see alerts within +the GitLab interface. As a result, the previous direct link to Opsgenie Alerts from +the GitLab alerts list will be deprecated following the 13.7 release on December 22, 2020. + > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. You can monitor alerts using a GitLab integration with [Opsgenie](https://www.atlassian.com/software/opsgenie). diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index a6168386024..37836f4ab50 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -63,7 +63,7 @@ Alerts contain one of the following icons: ## Alert details page -Navigate to the Alert details view by visiting the [Alert list](./alerts.md) +Navigate to the Alert details view by visiting the [Alert list](alerts.md) and selecting an alert from the list. You need least Developer [permissions](../../user/permissions.md) to access alerts. @@ -142,7 +142,7 @@ There are different actions avilable in GitLab to help triage and respond to ale ### Update an alert's status The Alert detail view enables you to update the Alert Status. -See [Create and manage alerts in GitLab](./alerts.md) for more details. +See [Create and manage alerts in GitLab](alerts.md) for more details. ### Create an incident from an alert @@ -168,11 +168,11 @@ To assign an alert: 1. To display the list of current alerts, navigate to **Operations > Alerts**: -  +  1. Select your desired alert to display its **Alert Details View**: -  +  1. If the right sidebar is not expanded, select **{angle-double-right}** **Expand sidebar** to expand it. @@ -180,29 +180,29 @@ To assign an alert: From the dropdown menu, select each user you want to assign to the alert. GitLab creates a [to-do item](../../user/todos.md) for each user. -  +  After completing their portion of investigating or fixing the alert, users can unassign themselves from the alert. To remove an assignee, select **Edit** next to the **Assignee** dropdown menu and deselect the user from the list of assignees, or select **Unassigned**. -### Create a to do from an alert +### Create a to-do item from an alert > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1. You can manually create [To-Do list items](../../user/todos.md) for yourself from the Alert details screen, and view them later on your **To-Do List**. To -add a to do: +add a to-do item: 1. To display the list of current alerts, navigate to **Operations > Alerts**. 1. Select your desired alert to display its **Alert Management Details View**. 1. Select the **Add a To-Do** button in the right sidebar: -  +  Select the **To-Do List** **{todo-done}** in the navigation bar to view your current to-do list. - + ## Link runbooks to alerts @@ -219,46 +219,10 @@ the correct runbook: ## View the environment that generated the alert -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232492) in GitLab 13.5. -> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-environment-link-in-alert-details). **(CORE ONLY)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232492) in GitLab 13.5 behind a feature flag, disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/232492) in GitLab 13.6. CAUTION: **Warning:** This feature might not be available to you. Check the **version history** note above for details. The environment information and the link are displayed in the [Alert Details tab](#alert-details-tab). - -### Enable or disable Environment Link in Alert Details **(CORE ONLY)** - -Viewing the environment is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:expose_environment_path_in_alert_details) -``` - -To enable for just a particular project: - -```ruby -project = Project.find_by_full_path('your-group/your-project') -Feature.enable(:expose_environment_path_in_alert_details, project) -``` - -To disable it: - -```ruby -Feature.disable(:expose_environment_path_in_alert_details) -``` - -To disable for just a particular project: - -```ruby -project = Project.find_by_full_path('your-group/your-project') -Feature.disable(:expose_environment_path_in_alert_details, project) -``` diff --git a/doc/operations/incident_management/generic_alerts.md b/doc/operations/incident_management/generic_alerts.md index a8f2f9a58a6..29d609f1811 100644 --- a/doc/operations/incident_management/generic_alerts.md +++ b/doc/operations/incident_management/generic_alerts.md @@ -1,5 +1,5 @@ --- -redirect_to: alert_notifications.md +redirect_to: alert_integrations.md --- -This document was moved to [another location](alert_notifications.md). +This document was moved to [another location](alert_integrations.md). diff --git a/doc/operations/incident_management/img/alert_detail_full_v13_1.png b/doc/operations/incident_management/img/alert_detail_full_v13_1.png Binary files differdeleted file mode 100644 index 18a6f4fb67b..00000000000 --- a/doc/operations/incident_management/img/alert_detail_full_v13_1.png +++ /dev/null diff --git a/doc/operations/incident_management/img/alert_detail_overview_v13_1.png b/doc/operations/incident_management/img/alert_detail_overview_v13_1.png Binary files differdeleted file mode 100644 index 10c945d3810..00000000000 --- a/doc/operations/incident_management/img/alert_detail_overview_v13_1.png +++ /dev/null diff --git a/doc/operations/incident_management/img/alert_detail_system_notes_v13_1.png b/doc/operations/incident_management/img/alert_detail_system_notes_v13_1.png Binary files differdeleted file mode 100644 index 2a6d0320a54..00000000000 --- a/doc/operations/incident_management/img/alert_detail_system_notes_v13_1.png +++ /dev/null diff --git a/doc/operations/incident_management/img/alert_list_search_v13_1.png b/doc/operations/incident_management/img/alert_list_search_v13_1.png Binary files differdeleted file mode 100644 index ba993fe530b..00000000000 --- a/doc/operations/incident_management/img/alert_list_search_v13_1.png +++ /dev/null diff --git a/doc/operations/incident_management/img/alert_list_sort_v13_1.png b/doc/operations/incident_management/img/alert_list_sort_v13_1.png Binary files differdeleted file mode 100644 index 8e06c3478f7..00000000000 --- a/doc/operations/incident_management/img/alert_list_sort_v13_1.png +++ /dev/null diff --git a/doc/operations/incident_management/img/incident_highlight_bar_v13_5.png b/doc/operations/incident_management/img/incident_highlight_bar_v13_5.png Binary files differdeleted file mode 100644 index 6a40e97820c..00000000000 --- a/doc/operations/incident_management/img/incident_highlight_bar_v13_5.png +++ /dev/null diff --git a/doc/operations/incident_management/img/incident_list.png b/doc/operations/incident_management/img/incident_list.png Binary files differdeleted file mode 100644 index 0498fec6c9c..00000000000 --- a/doc/operations/incident_management/img/incident_list.png +++ /dev/null diff --git a/doc/operations/incident_management/img/incident_list_search_v13_3.png b/doc/operations/incident_management/img/incident_list_search_v13_3.png Binary files differdeleted file mode 100644 index 293268986cc..00000000000 --- a/doc/operations/incident_management/img/incident_list_search_v13_3.png +++ /dev/null diff --git a/doc/operations/incident_management/img/incident_sla_settings_v13_5.png b/doc/operations/incident_management/img/incident_sla_settings_v13_5.png Binary files differdeleted file mode 100644 index 94c8b840210..00000000000 --- a/doc/operations/incident_management/img/incident_sla_settings_v13_5.png +++ /dev/null diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md index 3d85fa0ebd8..13a755bbb6f 100644 --- a/doc/operations/incident_management/incidents.md +++ b/doc/operations/incident_management/incidents.md @@ -6,7 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Incidents -Incidents are critical entities in incident management workflows. They represent a service disruption or outage that needs to be restored urgently. GitLab provides tools for the triage, response, and remediation of incidents. +Incidents are critical entities in incident management workflows. They represent +a service disruption or outage that needs to be restored urgently. GitLab provides +tools for the triage, response, and remediation of incidents. ## Incident Creation @@ -14,7 +16,8 @@ You can create an incident manually or automatically. ### Create incidents manually -If you have at least Guest [permissions](../../user/permissions.md), to create an Incident, you have two options to do this manually. +If you have at least Guest [permissions](../../user/permissions.md), to create an +Incident, you have two options to do this manually. **From the Incidents List:** @@ -24,7 +27,7 @@ If you have at least Guest [permissions](../../user/permissions.md), to create a - Create a new issue using the `incident` template available when creating it. - Create a new issue and assign the `incident` label to it. - + **From the Issues List:** @@ -34,7 +37,7 @@ If you have at least Guest [permissions](../../user/permissions.md), to create a - Create a new issue using the `type` drop-down and select `Incident`. - The page refreshes and the page only displays fields relevant to Incidents. - + ### Create incidents automatically @@ -43,17 +46,17 @@ If you have at least Guest [permissions](../../user/permissions.md), to create a With Maintainer or higher [permissions](../../user/permissions.md), you can enable GitLab to create incident automatically whenever an alert is triggered: -1. Navigate to **Settings > Operations > Incidents** and expand - **Incidents**: +1. Navigate to **Settings > Operations > Incidents** and expand **Incidents**: -  +  -1. Check the **Create an incident** - checkbox. -1. To customize the incident, select an [issue templates](../../user/project/description_templates.md#creating-issue-templates). +1. Check the **Create an incident** checkbox. +1. To customize the incident, select an + [issue template](../../user/project/description_templates.md#creating-issue-templates). 1. To send [an email notification](alert_notifications.md#email-notifications) to users with [Developer permissions](../../user/permissions.md), select - **Send a separate email notification to Developers**. Email notifications will also be sent to users with **Maintainer** and **Owner** permissions. + **Send a separate email notification to Developers**. Email notifications are + also sent to users with **Maintainer** and **Owner** permissions. 1. Click **Save changes**. ### Create incidents via the PagerDuty webhook @@ -68,7 +71,7 @@ in both PagerDuty and GitLab: 1. Navigate to **Settings > Operations > Incidents** and expand **Incidents**. 1. Select the **PagerDuty integration** tab: -  +  1. Activate the integration, and save the changes in GitLab. 1. Copy the value of **Webhook URL** for use in a later step. @@ -167,7 +170,7 @@ tab, the incident must have been created with a linked alert. Incidents created automatically from alerts have this field populated. - + ### Timeline view @@ -177,32 +180,47 @@ To quickly see the latest updates on an incident, click **{comments}** **Turn timeline view on** in the comment bar to display comments un-threaded and ordered chronologically, newest to oldest: - + ### Service Level Agreement countdown timer > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241663) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. -After enabling **Incident SLA** in the Incident Management configuration, newly-created -incidents display a SLA (Service Level Agreement) timer showing the time remaining before -the SLA period expires. If the incident is not closed before the SLA period ends, GitLab -adds a `missed::SLA` label to the incident. +You can enable the Service Level Agreement Countdown timer on incidents to track +the Service Level Agreements (SLAs) you hold with your customers. The timer is +automatically started when the incident is created, and shows the time +remaining before the SLA period expires. To configure the timer: + +1. Navigate to **Settings > Operations**. +1. Scroll to **Incidents** and click **Expand**, then select the + **Incident settings** tab. +1. Select **Activate "time to SLA" countdown timer**. +1. Set a time limit in increments of 15 minutes. +1. Click **Save changes**. + +After you enable the SLA countdown timer, the **Time to SLA** attribute is displayed +as a column in the Incidents List, and as a field on newly created Incidents. If +the incident isn't closed before the SLA period ends, GitLab adds a `missed::SLA` +label to the incident. ## Incident Actions -There are different actions avilable to help triage and respond to incidents. +There are different actions available to help triage and respond to incidents. ### Assign incidents -Assign incidents to users that are actively responding. Select **Edit** in the right-hand side bar to select or deselect assignees. +Assign incidents to users that are actively responding. Select **Edit** in the +right-hand side bar to select or deselect assignees. ### Change severity -See [Incident List](#incident-list) for a full description of the severities available. Select **Edit** in the right-hand side bar to change the severity of an incident. +See [Incident List](#incident-list) for a full description of the severity levels available. +Select **Edit** in the right-hand side bar to change the severity of an incident. -### Add a to do +### Add a to-do item -Add a to-do for incidents that you want to track in your to-do list. Clicke the **Add a to do** button at the top of the right-hand side bar to add a to do. +Add a to-do for incidents that you want to track in your to-do list. Click the +**Add a to do** button at the top of the right-hand side bar to add a to-do item. ### Manage incidents from Slack diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md index e5d0ae1ddbb..4230091866e 100644 --- a/doc/operations/incident_management/status_page.md +++ b/doc/operations/incident_management/status_page.md @@ -12,11 +12,11 @@ With a GitLab Status Page, you can create and deploy a static website to communi efficiently to users during an incident. The Status Page landing page displays an overview of recent incidents: - + Clicking an incident displays a detail page with more information about a particular incident: - + - Status on the incident, including when the incident was last updated. - The incident title, including any emojis. @@ -138,7 +138,7 @@ you provided during setup. As part of publication, GitLab will: After publication, you can access the incident's details page by clicking the **Published on status page** button displayed under the Incident's title. - + ### Update an incident diff --git a/doc/operations/metrics/dashboards/img/metrics_settings_button_v13_3.png b/doc/operations/metrics/dashboards/img/metrics_settings_button_v13_3.png Binary files differdeleted file mode 100644 index 9c0eac12a3f..00000000000 --- a/doc/operations/metrics/dashboards/img/metrics_settings_button_v13_3.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/index.md b/doc/operations/metrics/dashboards/index.md index 4aa340a9e59..c11da2926bb 100644 --- a/doc/operations/metrics/dashboards/index.md +++ b/doc/operations/metrics/dashboards/index.md @@ -14,9 +14,6 @@ includes a few key metrics, but you can also define your own custom dashboards. You may create a [new dashboard from scratch](#add-a-new-dashboard-to-your-project) or [duplicate a GitLab-defined Prometheus dashboard](#duplicate-a-gitlab-defined-dashboard). -The metrics as defined below do not support alerts, unlike -[custom metrics](../index.md#adding-custom-metrics). - ## Add a new dashboard to your project > UI option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228856) in GitLab 13.3. @@ -116,14 +113,9 @@ Your custom dashboard is available at `https://example.com/project/-/metrics/cus > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223204) in GitLab 13.2. -To manage the settings for your metrics dashboard: - -1. Sign in as a user with project Maintainer or Administrator - [permissions](../../../user/permissions.md#project-members-permissions). -1. Navigate to your dashboard at **Operations > Metrics**. -1. In the top-right corner of your dashboard, click **Metrics Settings**: - -  +Users with project Maintainer or Administrator +[permissions](../../../user/permissions.md#project-members-permissions) +can manage [the settings](settings.md) for your metrics dashboard. ## Chart Context Menu @@ -226,7 +218,7 @@ links: ## Troubleshooting When troubleshooting issues with a managed Prometheus app, it is often useful to -[view the Prometheus UI](../../../development/prometheus.md#access-the-ui-of-a-prometheus-managed-application-in-kubernetes). +[view the Prometheus UI](../../../user/project/integrations/prometheus.md#access-the-ui-of-a-prometheus-managed-application-in-kubernetes). ### "No data found" error on Metrics dashboard page diff --git a/doc/operations/metrics/dashboards/settings.md b/doc/operations/metrics/dashboards/settings.md index aa0b9a81771..6052b0778da 100644 --- a/doc/operations/metrics/dashboards/settings.md +++ b/doc/operations/metrics/dashboards/settings.md @@ -21,8 +21,8 @@ time zone, but you can display dates and times in UTC format. To change the time zone: 1. Sign in as a user with Manage Project Operations [permissions](../../../user/permissions.md). -1. Navigate to **Settings > Operations**, and scroll to - **Metrics Dashboard**. +1. Navigate to **Settings > Operations**. +1. Scroll to **Metrics Dashboard** and click **Expand**. 1. In the **Dashboard timezone** select box, select *User's local timezone* or *UTC*: @@ -37,8 +37,8 @@ You can add a button on your monitoring dashboard that links directly to your existing external dashboards: 1. Sign in as a user with Manage Project Operations [permissions](../../../user/permissions.md). -1. Navigate to **Settings > Operations**, and scroll to - **Metrics Dashboard**. +1. Navigate to **Settings > Operations**. +1. Scroll to **Metrics Dashboard** and click **Expand**. 1. In **External dashboard URL**, provide the URL to your external dashboard:  diff --git a/doc/operations/metrics/dashboards/variables.md b/doc/operations/metrics/dashboards/variables.md index 2103f8e66db..e1f5f0ce6f4 100644 --- a/doc/operations/metrics/dashboards/variables.md +++ b/doc/operations/metrics/dashboards/variables.md @@ -50,6 +50,8 @@ For example, if the dashboard time range is set to 8 hours, the value of [Variables can be defined](../../../operations/metrics/dashboards/yaml.md#templating-templating-properties) in a custom dashboard YAML file. +Variable names are case-sensitive. + ## Query variables from URL > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214500) in GitLab 13.0. diff --git a/doc/operations/metrics/dashboards/yaml.md b/doc/operations/metrics/dashboards/yaml.md index c3523327c51..13397eb702a 100644 --- a/doc/operations/metrics/dashboards/yaml.md +++ b/doc/operations/metrics/dashboards/yaml.md @@ -87,8 +87,8 @@ is no longer used. | `id` | string | no | Used for associating dashboard metrics with database records. Must be unique across dashboard configuration files. Required for [alerting](../alerts.md) (support not yet enabled, see [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/27980)). | | `unit` | string | yes | Defines the unit of the query's return data. | | `label` | string | no, but highly encouraged | Defines the legend-label for the query. Should be unique within the panel's metrics. Can contain time series labels as interpolated variables. | -| `query` | string/number | yes if `query_range` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be utilized. | -| `query_range` | string/number | yes if `query` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query_range` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be utilized. | +| `query` | string/number | yes if `query_range` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be used. | +| `query_range` | string/number | yes if `query` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query_range` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be used. | | `step` | number | no, value is calculated if not defined | Defines query resolution step width in float number of seconds. Metrics on the same panel should use the same `step` value. | ## Dynamic labels diff --git a/doc/operations/metrics/index.md b/doc/operations/metrics/index.md index 39d03ded373..6ce0bd42d3c 100644 --- a/doc/operations/metrics/index.md +++ b/doc/operations/metrics/index.md @@ -4,7 +4,7 @@ group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Monitor your CI/CD environment's metrics **(CORE)** +# Monitor your environment's metrics **(CORE)** GitLab helps your team monitor the health and performance of your applications and infrastructure by turning statistics and log files into charts and graphs diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md index 77b4b22e6a8..9edec660d5f 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/maintenance.md @@ -1,4 +1,7 @@ --- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: concepts --- @@ -54,21 +57,11 @@ one major version. For example, it is safe to: - `12.7.5` -> `12.10.5` - `11.3.4` -> `11.11.1` - - `10.6.6` -> `10.8.3` - - `11.3.4` -> `11.11.8` - - `10.6.6` -> `10.8.7` - - `9.2.3` -> `9.5.5` - - `8.9.4` -> `8.12.3` - Upgrade the *patch* version. For example: - `12.0.4` -> `12.0.12` - `11.11.1` -> `11.11.8` - - `10.6.3` -> `10.6.6` - - `11.11.1` -> `11.11.8` - - `10.6.3` -> `10.6.6` - - `9.5.5` -> `9.5.9` - - `8.9.2` -> `8.9.6` NOTE: **Note:** Version specific changes in Omnibus GitLab Linux packages can be found in [the Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/update/README.html#version-specific-changes). @@ -79,74 +72,9 @@ Instructions are available for downloading an Omnibus GitLab Linux package local NOTE: **Note:** A step-by-step guide to [upgrading the Omnibus-bundled PostgreSQL is documented separately](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server). -### Upgrading major versions - -Upgrading the *major* version requires more attention. -Backward-incompatible changes and migrations are reserved for major versions. -We cannot guarantee that upgrading between major versions will be seamless. -We suggest upgrading to the latest available *minor* version within -your major version before proceeding to the next major version. -Doing this will address any backward-incompatible changes or deprecations -to help ensure a successful upgrade to the next major release. - -It's also important to ensure that any background migrations have been fully completed -before upgrading to a new major version. To see the current size of the `background_migration` queue, -[Check for background migrations before upgrading](../update/README.md#checking-for-background-migrations-before-upgrading). - -If your GitLab instance has any runners associated with it, it is very -important to upgrade GitLab Runner to match the GitLab minor version that was -upgraded to. This is to ensure [compatibility with GitLab versions](https://docs.gitlab.com/runner/#compatibility-with-gitlab-versions). - -### Version 12 onward: Extra step for major upgrades - -From version 12 onward, an additional step is required. More significant migrations -may occur during major release upgrades. - -To ensure these are successful: - -1. Increment to the first minor version (`x.0.x`) during the major version jump. -1. Proceed with upgrading to a newer release. - -**For example: `11.5.x` -> `11.11.x` -> `12.0.x` -> `12.10.x` -> `13.0.x`** - -### Example upgrade paths - -Please see the table below for some examples: +## Upgrading major versions -| Target version | Your version | Recommended upgrade path | Note | -| --------------------- | ------------ | ------------------------ | ---- | -| `13.4.3` | `12.9.2` | `12.9.2` -> `12.10.14` -> `13.0.14` -> `13.4.3` | Two intermediate versions are required: the final `12.10` release, plus `13.0`. | -| `13.2.10` | `11.5.0` | `11.5.0` -> `11.11.8` -> `12.0.12` -> `12.10.14` -> `13.0.14` -> `13.2.10` | Four intermediate versions are required: the final `11.11`, `12.0`, and `12.10` releases, plus `13.0`. | -| `12.10.14` | `11.3.4` | `11.3.4` -> `11.11.8` -> `12.0.12` -> `12.10.14` | Two intermediate versions are required: the final `11.11` release and `12.0.12` | -| `12.9.5` | `10.4.5` | `10.4.5` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.9.5` | Three intermediate versions are required: `10.8`, `11.11`, and `12.0`, then `12.9.5` | -| `12.2.5` | `9.2.6` | `9.2.6` -> `9.5.10` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.2.5` | Four intermediate versions are required: `9.5`, `10.8`, `11.11`, `12.0`, then `12.2`. | -| `11.3.4` | `8.13.4` | `8.13.4` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.3.4` | `8.17.7` is the last version in version 8, `9.5.10` is the last version in version 9, `10.8.7` is the last version in version 10. | - -### Upgrades from versions earlier than 8.12 - -- `8.11.x` and earlier: you might have to upgrade to `8.12.0` specifically before you can upgrade to `8.17.7`. This was [reported in an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/207259). -- [CI changes prior to version 8.0](https://docs.gitlab.com/omnibus/update/README.html#updating-gitlab-ci-from-prior-540-to-version-714-via-omnibus-gitlab) - when it was merged into GitLab. - -### Multi-step upgrade paths with GitLab all-in-one Linux package repository - -Linux package managers default to installing the latest available version of a package for installation and upgrades. -Upgrading directly to the latest major version can be problematic for older GitLab versions that require a multi-stage upgrade path. - -When following an upgrade path spanning multiple versions, for each upgrade, specify the intended GitLab version number in your package manager's install or upgrade command. - -Examples: - -```shell -# apt-get (Ubuntu/Debian) -sudo apt-get upgrade gitlab-ee=12.0.12-ee.0 -# yum (RHEL/CentOS 6 and 7) -yum install gitlab-ee-12.0.12-ee.0.el7 -# dnf (RHEL/CentOS 8) -dnf install gitlab-ee-12.0.12-ee.0.el8 -# zypper (SUSE) -zypper install gitlab-ee=12.0.12-ee.0 -``` +Backward-incompatible changes and migrations are reserved for major versions. See the [upgrade guide](../update/README.md#upgrading-to-a-new-major-version). ## Patch releases @@ -221,19 +149,6 @@ This decision is made on a case-by-case basis. ## More information -Check [our release posts](https://about.gitlab.com/releases/categories/releases/). - -Each month, we publish either a major or minor release of GitLab. At the end -of those release posts, there are three sections to look for: Deprecations, Removals, and Important notes on upgrading. These will include: - -- Steps you need to perform as part of an upgrade. - For example [8.12](https://about.gitlab.com/releases/2016/09/22/gitlab-8-12-released/#upgrade-barometer) - required the Elasticsearch index to be recreated. Any older version of GitLab upgrading to 8.12 or higher would require this. -- Changes to the versions of software we support such as - [ceasing support for IE11 in GitLab 13](https://about.gitlab.com/releases/2020/03/22/gitlab-12-9-released/#ending-support-for-internet-explorer-11). - -You should check all the major and minor versions you're passing over. - More information about the release procedures can be found in our [release documentation](https://gitlab.com/gitlab-org/release/docs). You may also want to read our [Responsible Disclosure Policy](https://about.gitlab.com/security/disclosure/). diff --git a/doc/public_access/public_access.md b/doc/public_access/public_access.md index 848065de001..1f9486dc324 100644 --- a/doc/public_access/public_access.md +++ b/doc/public_access/public_access.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- @@ -21,12 +24,12 @@ on the repository. ### Internal projects -Internal projects can be cloned by any logged in user. +Internal projects can be cloned by any logged in user except [external users](../user/permissions.md#external-users). They will also be listed in the public access directory (`/public`), but only for logged in users. -Any logged in user will have [Guest permissions](../user/permissions.md) +Any logged in user except [external users](../user/permissions.md#external-users) will have [Guest permissions](../user/permissions.md) on the repository. NOTE: **Note:** diff --git a/doc/raketasks/README.md b/doc/raketasks/README.md index 7aec74f1243..4d2185c62f2 100644 --- a/doc/raketasks/README.md +++ b/doc/raketasks/README.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 8a4cc0c8ff2..a06fe00ef0d 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Back up and restore GitLab **(CORE ONLY)** GitLab provides Rake tasks for backing up and restoring GitLab instances. @@ -329,7 +335,7 @@ sudo -u git -H GITLAB_ASSUME_YES=1 bundle exec rake gitlab:backup:restore RAILS_ > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37158) in GitLab 13.3. -Repositories can be backed up concurrently to help fully utilize CPU time. The +Repositories can be backed up concurrently to help fully use CPU time. The following variables are available to modify the default behavior of the Rake task: diff --git a/doc/raketasks/cleanup.md b/doc/raketasks/cleanup.md index 0b3da39d3d5..00a3e9196e2 100644 --- a/doc/raketasks/cleanup.md +++ b/doc/raketasks/cleanup.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Clean up **(CORE ONLY)** GitLab provides Rake tasks for cleaning up GitLab instances. @@ -6,7 +12,7 @@ GitLab provides Rake tasks for cleaning up GitLab instances. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36628) in GitLab 12.10. -DANGER: **Danger:** +DANGER: **Warning:** Do not run this within 12 hours of a GitLab upgrade. This is to ensure that all background migrations have finished, which otherwise may lead to data loss. @@ -201,6 +207,10 @@ sudo gitlab-rake gitlab:cleanup:sessions:active_sessions_lookup_keys bundle exec rake gitlab:cleanup:sessions:active_sessions_lookup_keys RAILS_ENV=production ``` +## Cleaning up stale Redis sessions + +[Clean up stale sessions](../administration/operations/cleaning_up_redis_sessions.md) to compact the Redis database after you upgrade to GitLab 7.3. + ## Container Registry garbage collection Container Registry can use considerable amounts of disk space. To clear up diff --git a/doc/raketasks/features.md b/doc/raketasks/features.md index 1d68671a545..ecdf6aee069 100644 --- a/doc/raketasks/features.md +++ b/doc/raketasks/features.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Namespaces **(CORE ONLY)** This Rake task enables [namespaces](../user/group/index.md#namespaces) for projects. diff --git a/doc/raketasks/generate_sample_prometheus_data.md b/doc/raketasks/generate_sample_prometheus_data.md index 902be6862c8..f37aa95c63b 100644 --- a/doc/raketasks/generate_sample_prometheus_data.md +++ b/doc/raketasks/generate_sample_prometheus_data.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: Health +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Generate sample Prometheus data **(CORE ONLY)** This command will run Prometheus queries for each of the metrics of a specific environment diff --git a/doc/raketasks/import.md b/doc/raketasks/import.md index b0603a76211..ecd777361a7 100644 --- a/doc/raketasks/import.md +++ b/doc/raketasks/import.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Import bare repositories **(CORE ONLY)** Rake tasks are available to import bare repositories into a GitLab instance. diff --git a/doc/raketasks/list_repos.md b/doc/raketasks/list_repos.md index 411de52e379..192a65f6a62 100644 --- a/doc/raketasks/list_repos.md +++ b/doc/raketasks/list_repos.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Listing repository directories **(CORE ONLY)** You can print a list of all Git repositories on disk managed by GitLab. @@ -13,7 +19,6 @@ cd /home/git/gitlab sudo -u git -H bundle exec rake gitlab:list_repos RAILS_ENV=production ``` -NOTE: **Note:** The results use the default ordering of the GitLab Rails application. ## Limit search results diff --git a/doc/raketasks/migrate_snippets.md b/doc/raketasks/migrate_snippets.md index 476615d3926..e36ad5184ad 100644 --- a/doc/raketasks/migrate_snippets.md +++ b/doc/raketasks/migrate_snippets.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Editor +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Migration to Versioned Snippets **(CORE ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215861) in GitLab 13.0. diff --git a/doc/raketasks/spdx.md b/doc/raketasks/spdx.md index 23eb27eb059..19ec0397179 100644 --- a/doc/raketasks/spdx.md +++ b/doc/raketasks/spdx.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # SPDX license list import **(PREMIUM ONLY)** GitLab provides a Rake task for uploading a fresh copy of the [SPDX license list](https://spdx.org/licenses/) diff --git a/doc/raketasks/user_management.md b/doc/raketasks/user_management.md index 61e30f9ddb1..a0a880eac51 100644 --- a/doc/raketasks/user_management.md +++ b/doc/raketasks/user_management.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # User management **(CORE ONLY)** GitLab provides Rake tasks for user management. @@ -26,7 +32,6 @@ sudo gitlab-rake gitlab:import:all_users_to_all_projects bundle exec rake gitlab:import:all_users_to_all_projects RAILS_ENV=production ``` -NOTE: **Note:** Admin users are added as maintainers. ## Add user as a developer to all groups @@ -53,7 +58,6 @@ sudo gitlab-rake gitlab:import:all_users_to_all_groups bundle exec rake gitlab:import:all_users_to_all_groups RAILS_ENV=production ``` -NOTE: **Note:** Admin users are added as owners so they can add additional users to the group. ## Control the number of active users diff --git a/doc/raketasks/web_hooks.md b/doc/raketasks/web_hooks.md index 7bd2ed311d2..769a5ebae3a 100644 --- a/doc/raketasks/web_hooks.md +++ b/doc/raketasks/web_hooks.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Webhooks administration **(CORE ONLY)** GitLab provides Rake tasks for webhooks management. diff --git a/doc/raketasks/x509_signatures.md b/doc/raketasks/x509_signatures.md index f7c47794690..79770a56808 100644 --- a/doc/raketasks/x509_signatures.md +++ b/doc/raketasks/x509_signatures.md @@ -1,3 +1,9 @@ +--- +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/engineering/ux/technical-writing/#designated-technical-writers +--- + # X.509 signatures **(CORE ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/122159) in GitLab 12.10. diff --git a/doc/security/README.md b/doc/security/README.md index f8b9e423c04..a8947ef3de9 100644 --- a/doc/security/README.md +++ b/doc/security/README.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false type: index --- diff --git a/doc/security/asset_proxy.md b/doc/security/asset_proxy.md index fdceecdf386..7eb6d5067e2 100644 --- a/doc/security/asset_proxy.md +++ b/doc/security/asset_proxy.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Proxying assets A possible security concern when managing a public facing GitLab instance is diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md index 2496029d93e..4571f0051d8 100644 --- a/doc/security/crime_vulnerability.md +++ b/doc/security/crime_vulnerability.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md index 7c3d7284f25..a8c4a4e878e 100644 --- a/doc/security/information_exclusivity.md +++ b/doc/security/information_exclusivity.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: concepts --- diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md index 5354fe30082..b8d329ab342 100644 --- a/doc/security/password_length_limits.md +++ b/doc/security/password_length_limits.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- @@ -11,11 +14,31 @@ By default, GitLab supports passwords with: GitLab administrators can modify password lengths: -- Using configuration file. -- [From](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20661) GitLab 12.6, using the GitLab UI. +- Using the GitLab UI. **[From](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20661) GitLab 12.6 this is the only available option.** +- Using configuration file. **Up to GitLab 12.5**. + +Changing the minimum or maximum length does not affect existing user passwords. Existing users are +not asked to reset their password to adhere to the new limits. The new limit restriction applies +only during new user sign-ups and when an existing user performs a password reset. + +## Modify minimum password length using GitLab UI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20661) in GitLab 12.6 + +The user password length is set to a minimum of 8 characters by default. + +To change the minimum password length using GitLab UI: + +1. Go to **Admin Area > Settings**, then select **Sign-up restrictions**. + +  + +1. Input a **Minimum password length** value greater than or equal to 8, then select **Save changes**. ## Modify maximum password length using configuration file +From GitLab 12.6, the minimum password length set in this configuration file is ignored. Minimum password lengths must instead be modified via the [GitLab UI](#modify-minimum-password-length-using-gitlab-ui). + The user password length is set to a maximum of 128 characters by default. To change that for installations from source: @@ -39,26 +62,6 @@ To change that for installations from source: 1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect. -NOTE: **Note:** -From GitLab 12.6, the minimum password length set in this configuration file will be ignored. Minimum password lengths will now have to be modified via the [GitLab UI](#modify-minimum-password-length-using-gitlab-ui) instead. - -## Modify minimum password length using GitLab UI - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20661) in GitLab 12.6 - -The user password length is set to a minimum of 8 characters by default. -To change that using GitLab UI: - -In **Admin Area > Settings** (`/admin/application_settings/general`), go to the section **Sign-up restrictions**. - -[Minimum password length settings](../user/admin_area/img/minimum_password_length_settings_v12_6.png) - -Set the **Minimum password length** to a value greater than or equal to 8 and hit **Save changes** to save the changes. - -CAUTION: **Caution:** -Changing minimum or maximum limit does not affect existing user passwords in any manner. Existing users will not be asked to reset their password to adhere to the new limits. -The new limit restriction will only apply during new user sign-ups and when an existing user performs a password reset. - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/security/password_storage.md b/doc/security/password_storage.md index 96487a75d8d..ca4d350dc06 100644 --- a/doc/security/password_storage.md +++ b/doc/security/password_storage.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/security/passwords_for_integrated_authentication_methods.md b/doc/security/passwords_for_integrated_authentication_methods.md index f2597ef1578..4872f26a0ad 100644 --- a/doc/security/passwords_for_integrated_authentication_methods.md +++ b/doc/security/passwords_for_integrated_authentication_methods.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/security/project_import_decompressed_archive_size_limits.md b/doc/security/project_import_decompressed_archive_size_limits.md index 16821e1f192..9e50290afcc 100644 --- a/doc/security/project_import_decompressed_archive_size_limits.md +++ b/doc/security/project_import_decompressed_archive_size_limits.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md index b386917f399..a84ecc8e47d 100644 --- a/doc/security/rack_attack.md +++ b/doc/security/rack_attack.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md index 9e754cf1917..94cc446c804 100644 --- a/doc/security/rate_limits.md +++ b/doc/security/rate_limits.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- diff --git a/doc/security/reset_user_password.md b/doc/security/reset_user_password.md index bc8de882afe..66e11587e96 100644 --- a/doc/security/reset_user_password.md +++ b/doc/security/reset_user_password.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto --- @@ -53,14 +56,15 @@ Don't forget to save the changes. user.save! ``` -Exit the console and try to login with your new password. +Exit the console, and then try to sign in with your new password. NOTE: **Note:** -Passwords can also be reset via the [Users API](../api/users.md#user-modification) +You can also reset passwords by using the [Users API](../api/users.md#user-modification). ### Reset your root password -The steps described above can also be used to reset the root password. But first, identify the root user, with an `id` of `1`. To do so, run the following command: +The previously described steps can also be used to reset the root password. First, +identify the root user, with an `id` of `1`. To do so, run the following command: ```shell user = User.where(id: 1).first diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index 995dea7809e..27cc2474b8a 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -8,22 +8,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Enforce Two-factor Authentication (2FA) Two-factor Authentication (2FA) provides an additional level of security to your -users' GitLab account. Once enabled, in addition to supplying their username and -password to login, they'll be prompted for a code generated by an application on -their phone. +users' GitLab account. After being enabled, in addition to supplying their +username and password to sign in, they'll be prompted for a code generated by an +application on their phone. You can read more about it here: [Two-factor Authentication (2FA)](../user/profile/account/two_factor_authentication.md) ## Enforcing 2FA for all users -Users on GitLab, can enable it without any admin's intervention. If you want to -enforce everyone to set up 2FA, you can choose from two different ways: +Users on GitLab can enable it without any administrator's intervention. If you +want to enforce everyone to set up 2FA, you can choose from two different ways: - Enforce on next login. - Suggest on next login, but allow a grace period before enforcing. -After the configured grace period has elapsed, users will be able to log in but +After the configured grace period has elapsed, users will be able to sign in but won't be able to leave the 2FA configuration area at `/profile/two_factor_auth`. To enable 2FA for all users: @@ -32,15 +32,17 @@ To enable 2FA for all users: (`/admin/application_settings/general`). 1. Expand the **Sign-in restrictions** section, where you can configure both. -If you want 2FA enforcement to take effect on next login, change the grace -period to `0`. +If you want 2FA enforcement to take effect during the next sign-in attempt, +change the grace period to `0`. ## Enforcing 2FA for all users in a group If you want to enforce 2FA only for certain groups, you can: -1. Enable it in the group's **Settings > General** page. Navigate to **Permissions, LFS, 2FA > Two-factor authentication**. -You can then check the **Require all users in this group to setup Two-factor authentication** option. +1. Enable it in the group's **Settings > General** page. Navigate to + **Permissions, LFS, 2FA > Two-factor authentication**. You can then select + the **Require all users in this group to setup Two-factor authentication** + option. 1. You can also specify a grace period in the **Time before enforced** option. To change this setting, you need to be administrator or owner of the group. diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md index bf3bbbb701e..4013bfb7cae 100644 --- a/doc/security/unlock_user.md +++ b/doc/security/unlock_user.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto --- diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md index 3d7aa3026ab..2e2fb093916 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: concepts, reference, howto --- diff --git a/doc/subscriptions/gitlab_com/index.md b/doc/subscriptions/gitlab_com/index.md index 128e9d07282..a03c8e758de 100644 --- a/doc/subscriptions/gitlab_com/index.md +++ b/doc/subscriptions/gitlab_com/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: index, reference --- @@ -54,7 +57,7 @@ To subscribe to GitLab.com: - **For individuals**: 1. Create a user account for yourself using our - [sign up page](https://gitlab.com/users/sign_in#register-pane). + [sign up page](https://gitlab.com/users/sign_up). 1. Visit the [billing page](https://gitlab.com/profile/billings) under your profile. 1. Select the **Bronze**, **Silver**, or **Gold** GitLab.com plan through the @@ -67,7 +70,7 @@ To subscribe to GitLab.com: 1. Proceed to checkout. - **For groups**: 1. Create a user account for yourself using our - [sign up page](https://gitlab.com/users/sign_in#register-pane). + [sign up page](https://gitlab.com/users/sign_up). 1. Create a [group](../../user/group/index.md). GitLab groups help assemble related projects together allowing you to grant members access to several projects at once. A group is not required if you plan on having projects inside a personal diff --git a/doc/subscriptions/img/additional_minutes.png b/doc/subscriptions/img/additional_minutes.png Binary files differdeleted file mode 100644 index b159b98c9ce..00000000000 --- a/doc/subscriptions/img/additional_minutes.png +++ /dev/null diff --git a/doc/subscriptions/img/buy_btn.png b/doc/subscriptions/img/buy_btn.png Binary files differdeleted file mode 100644 index 4fd05c0fba7..00000000000 --- a/doc/subscriptions/img/buy_btn.png +++ /dev/null diff --git a/doc/subscriptions/img/buy_minutes_card.png b/doc/subscriptions/img/buy_minutes_card.png Binary files differdeleted file mode 100644 index cab098300cd..00000000000 --- a/doc/subscriptions/img/buy_minutes_card.png +++ /dev/null diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md index bc58c9e899d..df71c6bcf31 100644 --- a/doc/subscriptions/index.md +++ b/doc/subscriptions/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: index, reference --- @@ -81,7 +84,7 @@ With the [Customers Portal](https://customers.gitlab.com/) you can: Your personal details are used on invoices. Your email address is used for the Customers Portal login and license-related email. -To change your personal details, including name and billing address: +To change your personal details, including name, billing address, and email address: 1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). 1. Select **My account > Account details**. diff --git a/doc/subscriptions/self_managed/index.md b/doc/subscriptions/self_managed/index.md index 5f232bd4ed2..a63c2830909 100644 --- a/doc/subscriptions/self_managed/index.md +++ b/doc/subscriptions/self_managed/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: index, reference --- @@ -6,16 +9,23 @@ type: index, reference You can install, administer, and maintain your own GitLab instance. -In this page we'll go through the details of your GitLab self-managed subscription. +This page covers the details of your GitLab self-managed subscription. -## Choose a GitLab tier +## Subscription + +The cost of a GitLab self-managed subscription is determined by the following: + +- GitLab tier +- Subscription seats + +## GitLab tier Pricing is [tier-based](https://about.gitlab.com/pricing/), allowing you to choose the features which fit your budget. For information on what features are available at each tier, see the [GitLab self-managed feature comparison](https://about.gitlab.com/pricing/self-managed/feature-comparison/). -## Choose the number of users +## Subscription seats A self-managed subscription uses a hybrid model. You pay for a subscription according to the maximum number of users enabled during the subscription period. @@ -23,14 +33,17 @@ For instances that aren't offline or on a closed network, the maximum number of simultaneous users in the self-managed installation is checked each quarter, using [Seat Link](#seat-link). -Every occupied seat is counted in the subscription, with the following exceptions: +### Billable users + +A _billable user_ counts against the number of subscription seats. Every user is considered a +billable user, with the following exceptions: -- [Deactivated](../../user/admin_area/activating_deactivating_users.md#deactivating-a-user), [pending approval](../../user/admin_area/approving_users.md) and - [blocked](../../user/admin_area/blocking_unblocking_users.md) users who are restricted prior to the - renewal of a subscription won't be counted as active users for the renewal subscription. They may - count as active users in the subscription period in which they were originally added. +- [Deactivated users](../../user/admin_area/activating_deactivating_users.md#deactivating-a-user) and + [blocked users](../../user/admin_area/blocking_unblocking_users.md) don't count as billable users in the current subscription. When they are either deactivated or blocked they release a _billable user_ seat. However, they may + count toward overages in the subscribed seat count. +- Users who are [pending approval](../../user/admin_area/approving_users.md). - Members with Guest permissions on an Ultimate subscription. -- GitLab-created service accounts: `Ghost User` and bots (`Support Bot`, [`Project bot users`](../../user/project/settings/project_access_tokens.md#project-bot-users), etc.). +- GitLab-created service accounts: `Ghost User` and bots (`Support Bot`, [`Project bot users`](../../user/project/settings/project_access_tokens.md#project-bot-users), and so on). ### Users statistics @@ -39,8 +52,23 @@ and blocked, go to **Admin Area > Overview > Dashboard** and select **Users stat in the **Users** section. For more details, see [Users statistics](../../user/admin_area/index.md#users-statistics). -NOTE: **Note:** -If you have LDAP integration enabled, anyone in the configured domain can sign up for a GitLab account. This can result in an unexpected bill at time of renewal. Consider [disabling new signups](../../user/admin_area/settings/sign_up_restrictions.md) and managing new users manually instead. +### Tips for managing users and subscription seats + +Managing the number of users against the number of subscription seats can be a challenge: + +- If LDAP integration is enabled, anyone in the configured domain can sign up for a GitLab account. + This can result in an unexpected bill at time of renewal. +- If sign-up is enabled on your instance, anyone who can access the instance can sign up for an + account. + +GitLab has several features which can help you manage the number of users: + +- Enable the [**Require administrator approval for new sign ups**](../../user/admin_area/settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) + option. +- Enable the [User cap](../../user/admin_area/settings/sign_up_restrictions.md#user-cap) + option. **Available in GitLab 13.6 and later**. +- [Disable new sign-ups](../../user/admin_area/settings/sign_up_restrictions.md), and instead manage new + users manually. ## Obtain a subscription @@ -96,10 +124,10 @@ It's important to regularly review your user accounts, because: #### Users over License A GitLab subscription is valid for a specific number of users. For details, see -[Choose the number of users](#choose-the-number-of-users). If the active user +[Billable users](#billable-users). If the billable user count exceeds the number included in the subscription, known as the number of _users over license_, you must pay for the excess number of users either before -renewal, or at the time of renewal. This is also known the _true up_ process. +renewal, or at the time of renewal. This is also known as the _true up_ process. Self-managed instances can add users to a subscription any time during the subscription period. The cost of additional users added during the subscription @@ -144,7 +172,7 @@ We recommend following these steps during renewal: | Field | Description | |:------|:------------| | Users in License | The number of users you've paid for in the current license loaded on the system. This does not include the amount you've paid for `Users over license` during renewal. | - | Active users | The number of current active users on your system. | + | Active users | The daily count of active users on your system. | | Maximum users | The highest number of active users on your system during the term of the loaded license. If this number exceeds your users in license count at any point, you incur users over license. | | Users over license | The number of users that exceed the `Users in License` for the current license term. Charges for this number of users will be incurred at the next renewal. | diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index d2bdf935aa1..9f42c96e31b 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- @@ -28,11 +31,18 @@ Your GitLab instance can perform HTTP POST requests on the following events: - `user_update_for_group` - `user_update_for_team` -The triggers for most of these are self-explanatory, but `project_update` and `project_rename` deserve some clarification: `project_update` is fired any time an attribute of a project is changed (name, description, tags, etc.) *unless* the `path` attribute is also changed. In that case, a `project_rename` is triggered instead (so that, for instance, if all you care about is the repository URL, you can just listen for `project_rename`). +The triggers for most of these are self-explanatory, but `project_update` and +`project_rename` deserve some clarification: `project_update` is fired any time +an attribute of a project is changed (including name, description, and tags) +_unless_ the `path` attribute is also changed. In that case, a `project_rename` +is triggered instead (so that, for instance, if all you care about is the +repository URL, you can just listen for `project_rename`). -`user_failed_login` is sent whenever a **blocked** user attempts to login and denied access. +`user_failed_login` is sent whenever a _blocked_ user attempts to sign in and is +denied access. -System hooks can be used, e.g. for logging or changing information in a LDAP server. +System hooks can be used, for example, for logging or changing information in an +LDAP server. NOTE: **Note:** We follow the same structure and deprecations as [Webhooks](../user/project/integrations/webhooks.md) diff --git a/doc/tools/email.md b/doc/tools/email.md index 69aca200311..41a78f3a68a 100644 --- a/doc/tools/email.md +++ b/doc/tools/email.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto, reference --- diff --git a/doc/topics/application_development_platform/index.md b/doc/topics/application_development_platform/index.md index 85741c4b631..c38b067f1f3 100644 --- a/doc/topics/application_development_platform/index.md +++ b/doc/topics/application_development_platform/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Application Development Platform The GitLab Application Development Platform refers to the set of GitLab features used to create, configure, and manage diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index 9e37ebb699b..8a876e07791 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Authentication This page gathers all the resources for the topic **Authentication** within GitLab. diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 0026cf4d18a..95b6241583f 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -1,3 +1,9 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Customizing Auto DevOps While [Auto DevOps](index.md) provides great defaults to get you started, you can customize @@ -68,7 +74,6 @@ Docker image based on based on the `ruby:alpine` instead of the default `ruby:la # ... put your stuff here ``` -NOTE: **Note:** Use Base64 encoding if you need to pass complex values, such as newlines and spaces. Left unencoded, complex values like these can cause escaping issues due to how Auto DevOps uses the arguments. @@ -117,7 +122,6 @@ to `CI_COMMIT_SHA,CI_ENVIRONMENT_NAME`. RUN --mount=type=secret,id=auto-devops-build-secrets . /run/secrets/auto-devops-build-secrets && $COMMAND ``` -NOTE: **Note:** When `AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` is set, Auto DevOps enables the experimental [Docker BuildKit](https://docs.docker.com/develop/develop-images/build_enhancements/) feature to use the `--secret` flag. @@ -447,7 +451,6 @@ the updated secrets. To update the secrets, either: - Manually delete running pods to cause Kubernetes to create new pods with updated secrets. -NOTE: **Note:** Variables with multi-line values are not currently supported due to limitations with the current Auto DevOps scripting environment. @@ -514,8 +517,7 @@ on the default branch. However, there are cases where you might want to use a staging environment, and deploy to production manually. For this scenario, the `STAGING_ENABLED` environment variable was introduced. -If you define `STAGING_ENABLED`, such as setting `STAGING_ENABLED` to -`1` as a CI/CD variable, then GitLab automatically deploys the application +If you define `STAGING_ENABLED` with a non-empty value, then GitLab automatically deploys the application to a `staging` environment, and creates a `production_manual` job for you when you're ready to manually deploy to production. @@ -526,8 +528,7 @@ you when you're ready to manually deploy to production. You can use a [canary environment](../../user/project/canary_deployments.md) before deploying any changes to production. -If you define `CANARY_ENABLED` in your project, such as setting `CANARY_ENABLED` to -`1` as a CI/CD variable, then two manual jobs are created: +If you define `CANARY_ENABLED` with a non-empty value, then two manual jobs are created: - `canary` - Deploys the application to the canary environment. - `production_manual` - Manually deploys the application to production. diff --git a/doc/topics/autodevops/img/autodevops_multiple_clusters.png b/doc/topics/autodevops/img/autodevops_multiple_clusters.png Binary files differdeleted file mode 100644 index f4d101ca921..00000000000 --- a/doc/topics/autodevops/img/autodevops_multiple_clusters.png +++ /dev/null diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 1952fadc076..014690c4cdf 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -1,3 +1,9 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Auto DevOps > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/37115) in GitLab 10.0. @@ -160,7 +166,7 @@ a base domain of `example.com`, you'd need a DNS entry like: ``` In this case, the deployed applications are served from `example.com`, and `1.2.3.4` -is the IP address of your load balancer; generally NGINX ([see requirements](#requirements)). +is the IP address of your load balancer; generally NGINX ([see requirements](requirements.md)). Setting up the DNS record is beyond the scope of this document; check with your DNS provider for information. @@ -177,7 +183,7 @@ See [Auto DevOps requirements for Amazon ECS](requirements.md#auto-devops-requir ## Enabling/Disabling Auto DevOps -When first using Auto DevOps, review the [requirements](#requirements) to ensure +When first using Auto DevOps, review the [requirements](requirements.md) to ensure all the necessary components to make full use of Auto DevOps are available. First-time users should follow the [quick start guide](quick_start_guide.md). @@ -401,7 +407,7 @@ If you receive this error, you can do one of the following actions: database by setting `AUTO_DEVOPS_POSTGRES_DELETE_V1` to a non-empty value and redeploying. - DANGER: **Danger:** + DANGER: **Warning:** Deleting the channel 1 PostgreSQL database permanently deletes the existing channel 1 database and all its data. See [Upgrading PostgreSQL](upgrading_postgresql.md) @@ -415,7 +421,7 @@ If you receive this error, you can do one of the following actions: and persisted by Helm, regardless of whether or not your chart uses the variable. -DANGER: **Danger:** +DANGER: **Warning:** Setting `POSTGRES_ENABLED` to `false` permanently deletes any existing channel 1 database for your environment. @@ -467,6 +473,104 @@ that works for this problem. Follow these steps to use the tool in Auto DevOps: 1. Continue the deployments as usual. +### Error: error initializing: Looks like "https://kubernetes-charts.storage.googleapis.com" is not a valid chart repository or cannot be reached + +As [announced in the official CNCF blogpost](https://www.cncf.io/blog/2020/10/07/important-reminder-for-all-helm-users-stable-incubator-repos-are-deprecated-and-all-images-are-changing-location/), +the stable Helm chart repository will be deprecated and removed on November 13th, 2020. +You may encounter this error after that date. + +Some GitLab features had dependencies on the stable chart. To mitigate the impact, we changed them +to use new official repositories or the [Helm Stable Archive repository maintained by GitLab](https://gitlab.com/gitlab-org/cluster-integration/helm-stable-archive). +Auto Deploy contains [an example fix](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/merge_requests/127). + +In Auto Deploy, `v1.0.6+` of `auto-deploy-image` no longer adds the deprecated stable repository to +the `helm` command. If you use a custom chart and it relies on the deprecated stable repository, +specify an older `auto-deploy-image` like this example: + +```yaml +include: + - template: Auto-DevOps.gitlab-ci.yml + +.auto-deploy: + image: "registry.gitlab.com/gitlab-org/cluster-integration/auto-deploy-image:v1.0.5" +``` + +Keep in mind that this approach will eventually stop working when the stable repository is removed, +so you must eventually fix your custom chart. + +To fix your custom chart: + +1. In your chart directory, update the `repository` value in your `requirements.yaml` file from : + + ```yaml + repository: "https://kubernetes-charts.storage.googleapis.com/" + ``` + + to: + + ```yaml + repository: "https://charts.helm.sh/stable" + ``` + +1. In your chart directory, run `helm dep update .` using the same Helm major version as Auto DevOps. +1. Commit the changes for the `requirements.yaml` file. +1. If you previously had a `requirements.lock` file, commit the changes to the file. + If you did not previously have a `requirements.lock` file in your chart, + you do not need to commit the new one. This file is optional, but when present, + it's used to verify the integrity of the downloaded dependencies. + +You can find more information in +[issue #263778, "Migrate PostgreSQL from stable Helm repo"](https://gitlab.com/gitlab-org/gitlab/-/issues/263778). + +### Error: release .... failed: timed out waiting for the condition + +When getting started with Auto DevOps, you may encounter this error when first +deploying your application: + +```plaintext +INSTALL FAILED +PURGING CHART +Error: release staging failed: timed out waiting for the condition +``` + +This is most likely caused by a failed liveness (or readiness) probe attempted +during the deployment process. By default, these probes are run against the root +page of the deployed application on port 5000. If your application isn't configured +to serve anything at the root page, or is configured to run on a specific port +*other* than 5000, this check fails. + +If it fails, you should see these failures within the events for the relevant +Kubernetes namespace. These events look like the following example: + +```plaintext +LAST SEEN TYPE REASON OBJECT MESSAGE +3m20s Warning Unhealthy pod/staging-85db88dcb6-rxd6g Readiness probe failed: Get http://10.192.0.6:5000/: dial tcp 10.192.0.6:5000: connect: connection refused +3m32s Warning Unhealthy pod/staging-85db88dcb6-rxd6g Liveness probe failed: Get http://10.192.0.6:5000/: dial tcp 10.192.0.6:5000: connect: connection refused +``` + +To change the port used for the liveness checks, pass +[custom values to the Helm chart](customize.md#customize-values-for-helm-chart) +used by Auto DevOps: + +1. Create a directory and file at the root of your repository named `.gitlab/auto-deploy-values.yaml`. + +1. Populate the file with the following content, replacing the port values with + the actual port number your application is configured to use: + + ```yaml + service: + internalPort: <port_value> + externalPort: <port_value> + ``` + +1. Commit your changes. + +After committing your changes, subsequent probes should use the newly-defined ports. +The page that's probed can also be changed by overriding the `livenessProbe.path` +and `readinessProbe.path` values (shown in the +[default `values.yaml`](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/blob/master/assets/auto-deploy-app/values.yaml) +file) in the same fashion. + ## Development guides [Development guide for Auto DevOps](../../development/auto_devops.md) diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 02d9669a9bc..3531035eb67 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -1,3 +1,9 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Getting started with Auto DevOps This step-by-step guide will help you use [Auto DevOps](index.md) to @@ -108,7 +114,6 @@ In this guide, we will install Ingress and Prometheus: - Prometheus - An open-source monitoring and alerting system used to supervise the deployed application. -NOTE: **Note:** We won't install GitLab Runner in this quick start guide, as this guide uses the shared runners provided by GitLab.com. @@ -155,7 +160,8 @@ The jobs are separated into stages: - **Build** - The application builds a Docker image and uploads it to your project's [Container Registry](../../user/packages/container_registry/index.md) ([Auto Build](stages.md#auto-build)). -- **Test** - GitLab runs various checks on the application: +- **Test** - GitLab runs various checks on the application, but all jobs except `test` + are allowed to fail in the test stage: - The `test` job runs unit and integration tests by detecting the language and framework ([Auto Test](stages.md#auto-test)) @@ -173,9 +179,6 @@ The jobs are separated into stages: licenses and is allowed to fail ([Auto License Compliance](stages.md#auto-license-compliance)) **(ULTIMATE)** - NOTE: **Note:** - All jobs except `test` are allowed to fail in the test stage. - - **Review** - Pipelines on `master` include this stage with a `dast_environment_deploy` job. To learn more, see [Dynamic Application Security Testing (DAST)](../../user/application_security/dast/index.md). diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index af98e0a438b..acec7b79d6b 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -1,3 +1,9 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Requirements for Auto DevOps You can set up Auto DevOps for [Kubernetes](#auto-devops-requirements-for-kubernetes) @@ -120,11 +126,9 @@ When you trigger a pipeline, if you have Auto DevOps enabled and if you have cor [entered AWS credentials as environment variables](../../ci/cloud_deployment/index.md#deploy-your-application-to-the-aws-elastic-container-service-ecs), your application will be deployed to AWS ECS. -NOTE: **Note:** [GitLab Managed Apps](../../user/clusters/applications.md) are not available when deploying to AWS ECS. You must manually configure your application (such as Ingress or Help) on AWS ECS. -NOTE: **Note:** If you have both a valid `AUTO_DEVOPS_PLATFORM_TARGET` variable and a Kubernetes cluster tied to your project, only the deployment to Kubernetes will run. diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index d3f02889a2e..f2d3b78e2b0 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -1,3 +1,9 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Stages of Auto DevOps The following sections describe the stages of [Auto DevOps](index.md). @@ -161,10 +167,7 @@ see the documentation. > - [Select functionality made available in all tiers](../../user/application_security/secret_detection/#making-secret-detection-available-to-all-gitlab-tiers) in 13.3 Secret Detection uses the -[Secret Detection Docker image](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) to run Secret Detection on the current code, and checks for leaked secrets. The -Auto Secret Detection stage runs only on the -[Ultimate](https://about.gitlab.com/pricing/) tier, and requires -[GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or above. +[Secret Detection Docker image](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) to run Secret Detection on the current code, and checks for leaked secrets. Auto Secret Detection requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or above. After creating the report, it's uploaded as an artifact which you can later download and evaluate. The merge request widget also displays any security @@ -285,7 +288,7 @@ see the documentation. To use a custom target instead of the auto-deployed review apps, set a `DAST_WEBSITE` environment variable to the URL for DAST to scan. -DANGER: **Danger:** +DANGER: **Warning:** If [DAST Full Scan](../../user/application_security/dast/index.md#full-scan) is enabled, GitLab strongly advises **not** to set `DAST_WEBSITE` to any staging or production environment. DAST Full Scan @@ -428,7 +431,7 @@ To use Auto Deploy on a Kubernetes 1.16+ cluster: 1. If you are deploying your application for the first time and are using GitLab 12.9 or 12.10, set `AUTO_DEVOPS_POSTGRES_CHANNEL` to `2`. -DANGER: **Danger:** +DANGER: **Warning:** On GitLab 12.9 and 12.10, opting into `AUTO_DEVOPS_POSTGRES_CHANNEL` version `2` deletes the version `1` PostgreSQL database. Follow the [guide to upgrading PostgreSQL](upgrading_postgresql.md) @@ -668,4 +671,16 @@ To use Auto Monitoring: ## Auto Code Intelligence -Code Intelligence is powered by [LSIF](https://lsif.dev/) and available for Go at this stage. We'll support more languages as they become available. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216438) in GitLab 13.5. + +[GitLab code intelligence](../../user/project/code_intelligence.md) adds +code navigation features common to interactive development environments (IDE), +including type signatures, symbol documentation, and go-to definition. It's powered by +[LSIF](https://lsif.dev/) and available for Auto DevOps projects using Go language only. +GitLab plans to add support for more languages as more LSIF indexers become available. +You can follow the [code intelligence epic](https://gitlab.com/groups/gitlab-org/-/epics/4212) +for updates. + +This stage is enabled by default. You can disable it by adding the +`CODE_INTELLIGENCE_DISABLED` environment variable. Read more about +[disabling Auto DevOps jobs](../../topics/autodevops/customize.md#disable-jobs). diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index 1aefb6b34df..16536e5b586 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -71,6 +71,10 @@ The v2 auto-deploy-image contains multiple dependency and architectural changes. If your Auto DevOps project has an active environment deployed with the v1 `auto-deploy-image`, please proceed with the following upgrade guide. Otherwise, you can skip this process. +#### Kubernetes 1.16+ + +The v2 auto-deploy-image also drops support for Kubernetes 1.15 and lower. + #### Helm 3 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228609) in GitLab 13.4. diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md index bcbc1d914be..a3c9f562f5e 100644 --- a/doc/topics/autodevops/upgrading_postgresql.md +++ b/doc/topics/autodevops/upgrading_postgresql.md @@ -1,3 +1,9 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Upgrading PostgreSQL for Auto DevOps Auto DevOps provides an [in-cluster PostgreSQL database](customize.md#postgresql-database-support) diff --git a/doc/topics/cron/index.md b/doc/topics/cron/index.md index 851dd6d3f77..2be579b4e98 100644 --- a/doc/topics/cron/index.md +++ b/doc/topics/cron/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Cron Cron syntax is used to schedule when jobs should run. diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md index 6f50dea26dd..c01080400ac 100644 --- a/doc/topics/git/git_rebase.md +++ b/doc/topics/git/git_rebase.md @@ -119,7 +119,7 @@ repository, you can run `git remote -v`. If there are [merge conflicts](#merge-conflicts), Git will prompt you to fix them before continuing the rebase. -To learn more, check Git's documentation on [rebasing](ttps://git-scm.com/book/en/v2/Git-Branching-Rebasing) +To learn more, check Git's documentation on [rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) and [rebasing strategies](https://git-scm.com/book/en/v2/Git-Branching-Rebasing). ### Interactive rebase diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 7235ba07d0a..80014358230 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/lfs/index.md @@ -114,8 +114,11 @@ See the documentation on [File Locking](../../../user/project/file_lock.md). ## LFS objects in project archives > - Support for including Git LFS blobs inside [project source downloads](../../../user/project/repository/index.md) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. -> - It's [deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-lfs-objects-in-project-archives). **(CORE ONLY)** +> - It was [deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/268409) on GitLab 13.6. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-lfs-objects-in-project-archives). CAUTION: **Warning:** This feature might not be available to you. Check the **version history** note above for details. @@ -139,10 +142,10 @@ Technical details about how this works can be found in the [development document ### Enable or disable LFS objects in project archives -_LFS objects in project archives_ is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. +_LFS objects in project archives_ is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. +can opt to disable it. To enable it: diff --git a/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md b/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md index c62b7e1cc12..d65d52841aa 100644 --- a/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_from_git_annex_to_git_lfs.md @@ -7,7 +7,7 @@ type: reference, howto # Migration guide from Git Annex to Git LFS -NOTE: **Note:** +DANGER: **Deprecated:** Git Annex support [has been removed](https://gitlab.com/gitlab-org/gitlab/-/issues/1648) in GitLab Enterprise Edition 9.0 (2017/03/22). @@ -37,7 +37,6 @@ ones that GitLab developed. ## Migration steps -NOTE: **Note:** Since Git Annex files are stored in a sub-directory of the normal repositories (`.git/annex/objects`) and LFS files are stored outside of the repositories, they are not compatible as they are using a different scheme. Therefore, the diff --git a/doc/topics/git/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md index f0ad7570d87..596b2cb400f 100644 --- a/doc/topics/git/lfs/migrate_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_to_git_lfs.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers description: "How to migrate an existing Git repository to Git LFS with BFG." --- diff --git a/doc/topics/git/partial_clone.md b/doc/topics/git/partial_clone.md index c976eda688a..58fa6d2f112 100644 --- a/doc/topics/git/partial_clone.md +++ b/doc/topics/git/partial_clone.md @@ -91,7 +91,7 @@ Updating files: 100% (28/28), done. $ cd www-gitlab-com -$ git sparse-checkout init --clone +$ git sparse-checkout init --cone $ git sparse-checkout add data remote: Enumerating objects: 301, done. diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index 8c5a2092a92..32676658bff 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -250,7 +250,7 @@ Atlassian has a more thorough explanation of the tradeoffs between merging and r A good way to prevent creating many merge commits is to not frequently merge `master` into the feature branch. There are three reasons to merge in `master`: utilizing new code, resolving merge conflicts, and updating long-running branches. -If you need to utilize some code that was introduced in `master` after you created the feature branch, you can often solve this by just cherry-picking a commit. +If you need to use some code that was introduced in `master` after you created the feature branch, you can often solve this by just cherry-picking a commit. If your feature branch has a merge conflict, creating a merge commit is a standard way of solving this. diff --git a/doc/topics/index.md b/doc/topics/index.md index 3b92bbb55cb..91b1905f1b6 100644 --- a/doc/topics/index.md +++ b/doc/topics/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Topics Welcome to Topics! We have organized our content resources into topics @@ -16,6 +22,3 @@ tutorials, technical overviews, blog posts) and videos. - [GitLab Installation](../install/README.md) - [GitLab Pages](../user/project/pages/index.md) - [Offline GitLab](offline/index.md) - -NOTE: **Note:** -More topics will be available soon. diff --git a/doc/topics/offline/index.md b/doc/topics/offline/index.md index a8366659c22..b40f5e92738 100644 --- a/doc/topics/offline/index.md +++ b/doc/topics/offline/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Offline GitLab Computers in an offline environment are isolated from the public internet as a security measure. This diff --git a/doc/topics/offline/quick_start_guide.md b/doc/topics/offline/quick_start_guide.md index 8b9996cb66f..92f8f9167b7 100644 --- a/doc/topics/offline/quick_start_guide.md +++ b/doc/topics/offline/quick_start_guide.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Getting started with an offline GitLab Installation This is a step-by-step guide that helps you install, configure, and use a self-managed GitLab @@ -7,9 +13,7 @@ instance entirely offline. NOTE: **Note:** This guide assumes the server is Ubuntu 18.04. Instructions for other servers may vary. - -NOTE: **Note:** -This guide assumes the server host resolves as `my-host`, which you should replace with your +This guide also assumes the server host resolves as `my-host`, which you should replace with your server's name. Follow the installation instructions [as outlined in the omnibus install diff --git a/doc/topics/web_application_firewall/index.md b/doc/topics/web_application_firewall/index.md index 5ce7c0779bb..83b3bfb1cef 100644 --- a/doc/topics/web_application_firewall/index.md +++ b/doc/topics/web_application_firewall/index.md @@ -1,5 +1,5 @@ --- -stage: Defend +stage: Protect group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -15,19 +15,14 @@ much more. ## Overview -GitLab provides a WAF out of the box after Ingress is deployed. -All you need to do is deploy your application along with a service -and Ingress resource. +GitLab provides a WAF out of the box after Ingress is deployed. All you need to do is deploy your +application along with a service and Ingress resource. In GitLab's [Ingress](../../user/clusters/applications.md#ingress) +deployment, the [ModSecurity](https://modsecurity.org/) +module is loaded into Ingress-NGINX by default and monitors the traffic going to the applications +which have an Ingress. The ModSecurity module runs with the [OWASP Core Rule Set (CRS)](https://coreruleset.org/) +by default. The OWASP CRS detects and logs a wide range of common attacks. -In GitLab's [Ingress](../../user/clusters/applications.md#ingress) deployment, the [ModSecurity](https://modsecurity.org/) module is loaded -into Ingress-NGINX by default and monitors the traffic going to the -applications which have an Ingress. - -The ModSecurity module runs with the [OWASP Core Rule Set (CRS)](https://coreruleset.org/) by default. The OWASP CRS will detect and log a wide range of common attacks. - -NOTE: **Note:** -The WAF is deployed in "Detection-only mode" by default and will only log attack -attempts. +By default, the WAF is deployed in Detection-only mode and only logs attack attempts. ## Requirements @@ -98,5 +93,5 @@ It is good to have a basic knowledge of the following: ## Roadmap -More information on the direction of the WAF can be -found in [Product Vision - Defend](https://about.gitlab.com/direction/defend/#waf) +You can find more information on the product direction of the WAF in +[Category Direction - Web Application Firewall](https://about.gitlab.com/direction/protect/web_application_firewall/). diff --git a/doc/topics/web_application_firewall/quick_start_guide.md b/doc/topics/web_application_firewall/quick_start_guide.md index 971250cd526..3df22854437 100644 --- a/doc/topics/web_application_firewall/quick_start_guide.md +++ b/doc/topics/web_application_firewall/quick_start_guide.md @@ -1,5 +1,5 @@ --- -stage: Defend +stage: Protect group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -17,7 +17,7 @@ These instructions will also work for a self-managed GitLab instance. However, y need to ensure your own [runners are configured](../../ci/runners/README.md) and [Google OAuth is enabled](../../integration/google.md). -**Note**: GitLab's Web Application Firewall is deployed with [Ingress](../../user/clusters/applications.md#ingress), +GitLab's Web Application Firewall is deployed with [Ingress](../../user/clusters/applications.md#ingress), so it will be available to your applications no matter how you deploy them to Kubernetes. ## Configuring your Google account @@ -107,7 +107,7 @@ the scenes. Make sure to switch the toggle to the enabled position before instal Both logging and blocking modes are available for WAF. While logging mode is useful for auditing anomalous traffic, blocking mode ensures the traffic doesn't reach past Ingress. - + After Ingress is installed, wait a few seconds and copy the IP address that is displayed in order to add in your base **Domain** at the top of the page. For @@ -252,7 +252,7 @@ You can now see the benefits of a using a Web Application Firewall. ModSecurity and the OWASP Core Rule Set, offer many more benefits. You can explore them in more detail: -- [GitLab Defend Vision](https://about.gitlab.com/direction/defend/#waf) +- [Category Direction - Web Application Firewall](https://about.gitlab.com/direction/protect/web_application_firewall/) - [ModSecurity](https://www.modsecurity.org/) - [OWASP Core Rule Set](https://github.com/coreruleset/coreruleset/) - [AutoDevOps](../autodevops/index.md) diff --git a/doc/university/README.md b/doc/university/README.md index 6f063e028b5..1448d150a2c 100644 --- a/doc/university/README.md +++ b/doc/university/README.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false type: index --- diff --git a/doc/university/training/gitlab_flow.md b/doc/university/training/gitlab_flow.md index b80eb031aee..ce6ee7e6561 100644 --- a/doc/university/training/gitlab_flow.md +++ b/doc/university/training/gitlab_flow.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false type: reference --- diff --git a/doc/university/training/index.md b/doc/university/training/index.md index 4c54108b4fa..c8613e834b8 100644 --- a/doc/university/training/index.md +++ b/doc/university/training/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false type: index --- diff --git a/doc/university/training/topics/agile_git.md b/doc/university/training/topics/agile_git.md index c5634bec27b..6cd5051261f 100644 --- a/doc/university/training/topics/agile_git.md +++ b/doc/university/training/topics/agile_git.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/university/training/topics/bisect.md b/doc/university/training/topics/bisect.md index cb6d6e683a8..09274c1ce11 100644 --- a/doc/university/training/topics/bisect.md +++ b/doc/university/training/topics/bisect.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/university/training/topics/cherry_picking.md b/doc/university/training/topics/cherry_picking.md index 47734834801..04b8f3b9a47 100644 --- a/doc/university/training/topics/cherry_picking.md +++ b/doc/university/training/topics/cherry_picking.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/university/training/topics/env_setup.md b/doc/university/training/topics/env_setup.md index be517032a1b..cbe2ce46be4 100644 --- a/doc/university/training/topics/env_setup.md +++ b/doc/university/training/topics/env_setup.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- @@ -6,22 +9,31 @@ comments: false ## Install -- **Windows** - - Install 'Git for Windows' from <https://gitforwindows.org> - +- **Windows** - Install 'Git for Windows' from [Git for Windows](https://gitforwindows.org). - **Mac** - Type '`git`' in the Terminal application. - If it's not installed, it will prompt you to install it. -- **Linux** - - ```shell - sudo yum install git-all - ``` - - ```shell - sudo apt-get install git-all - ``` +- **GNU/Linux** - Enter `which git` in the Terminal application and press <kbd>Enter</kbd> to + determine if Git is installed on your system. + + - If the output of that command gives you the path to the Git executable, similar to + `/usr/bin/git`, then Git is already installed on your system. + - If the output of the command displays "command not found" error, Git isn't installed on your system. + + GitLab recommends installing Git with the default package manager of your distribution. + The following commands install Git on various GNU/Linux distributions using their + default package managers. After you run the command corresponding to your distribution + and complete the installation process, Git should be available on your system: + + - **Arch Linux and its derivatives** - `sudo pacman -S git` + - **Fedora, RHEL, and CentOS** - For the `yum` package manager run `sudo yum install git-all`, + and for the `dnf` package manager run `sudo dnf install git`. + - **Debian/Ubuntu and their derivatives** - `sudo apt-get install git` + - **Gentoo** - `sudo emerge --ask --verbose dev-vcs/git` + - **openSUSE** - `sudo zypper install git` +- **FreeBSD** - `sudo pkg install git` +- **OpenBSD** - `doas pkg_add git` ## Configure Git diff --git a/doc/university/training/topics/feature_branching.md b/doc/university/training/topics/feature_branching.md index e7454dbba75..45fad8f1894 100644 --- a/doc/university/training/topics/feature_branching.md +++ b/doc/university/training/topics/feature_branching.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/university/training/topics/getting_started.md b/doc/university/training/topics/getting_started.md index fd50c5492f1..531d274249a 100644 --- a/doc/university/training/topics/getting_started.md +++ b/doc/university/training/topics/getting_started.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/university/training/topics/git_add.md b/doc/university/training/topics/git_add.md index a3389af526d..be66b1a14cc 100644 --- a/doc/university/training/topics/git_add.md +++ b/doc/university/training/topics/git_add.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/university/training/topics/git_intro.md b/doc/university/training/topics/git_intro.md index c9a1cbb7839..1ff436214b2 100644 --- a/doc/university/training/topics/git_intro.md +++ b/doc/university/training/topics/git_intro.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/university/training/topics/git_log.md b/doc/university/training/topics/git_log.md index 26b389beea9..c62b5ad5a3c 100644 --- a/doc/university/training/topics/git_log.md +++ b/doc/university/training/topics/git_log.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/university/training/topics/merge_conflicts.md b/doc/university/training/topics/merge_conflicts.md index e59f9e2bae8..87cb119768f 100644 --- a/doc/university/training/topics/merge_conflicts.md +++ b/doc/university/training/topics/merge_conflicts.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/university/training/topics/merge_requests.md b/doc/university/training/topics/merge_requests.md index ea679a7d66f..bda14dc342e 100644 --- a/doc/university/training/topics/merge_requests.md +++ b/doc/university/training/topics/merge_requests.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/university/training/topics/rollback_commits.md b/doc/university/training/topics/rollback_commits.md index 616ed972ab0..47f28f8ef89 100644 --- a/doc/university/training/topics/rollback_commits.md +++ b/doc/university/training/topics/rollback_commits.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/university/training/topics/stash.md b/doc/university/training/topics/stash.md index 28d28382d62..db4a21da6ba 100644 --- a/doc/university/training/topics/stash.md +++ b/doc/university/training/topics/stash.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/university/training/topics/subtree.md b/doc/university/training/topics/subtree.md index 5b08832084c..779ebab1441 100644 --- a/doc/university/training/topics/subtree.md +++ b/doc/university/training/topics/subtree.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/university/training/topics/tags.md b/doc/university/training/topics/tags.md index 01eb1dd9b4c..b2b8a085a77 100644 --- a/doc/university/training/topics/tags.md +++ b/doc/university/training/topics/tags.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false type: reference --- diff --git a/doc/university/training/topics/unstage.md b/doc/university/training/topics/unstage.md index b74cc9b2f0a..77aca3cdab8 100644 --- a/doc/university/training/topics/unstage.md +++ b/doc/university/training/topics/unstage.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/university/training/user_training.md b/doc/university/training/user_training.md index 43de90010b1..86f397eba41 100644 --- a/doc/university/training/user_training.md +++ b/doc/university/training/user_training.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false type: reference --- diff --git a/doc/update/README.md b/doc/update/README.md index b5e99671278..774d468cb76 100644 --- a/doc/update/README.md +++ b/doc/update/README.md @@ -1,28 +1,51 @@ -# Updating GitLab +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- -Depending on the installation method and your GitLab version, there are multiple -update guides. +# Upgrading GitLab -There are currently 3 official ways to install GitLab: +Upgrading GitLab is a relatively straightforward process, but the complexity +can increase based on the installation method you have used, how old your +GitLab version is, if you're upgrading to a major version, and so on. -- [Omnibus packages](#omnibus-packages) -- [Source installation](#installation-from-source) -- [Docker installation](#installation-using-docker) +Make sure to read the whole page as it contains information related to every upgrade method. -Based on your installation, choose a section below that fits your needs. +The [maintenance policy documentation](../policy/maintenance.md) +has additional information about upgrading, including: -## Omnibus Packages +- How to interpret GitLab product versioning. +- Recommendations on the what release to run. +- How we use patch and security patch releases. +- When we backport code changes. + +## Upgrade based on installation method + +Depending on the installation method and your GitLab version, there are multiple +official ways to update GitLab: -- The [Omnibus update guide](https://docs.gitlab.com/omnibus/update/README.html) - contains the steps needed to update an Omnibus GitLab package. +- [Linux packages (Omnibus GitLab)](#linux-packages-omnibus-gitlab) +- [Source installations](#installation-from-source) +- [Docker installations](#installation-using-docker) +- [Kubernetes (Helm) installations](#installation-using-helm) -## Installation from source +### Linux packages (Omnibus GitLab) + +The [Omnibus update guide](https://docs.gitlab.com/omnibus/update/) +contains the steps needed to update a package installed by GitLab's official +repositories. + +There are also instructions when you want to +[update to a specific version](https://docs.gitlab.com/omnibus/update/#multi-step-upgrade-using-the-official-repositories). + +### Installation from source - [Upgrading Community Edition and Enterprise Edition from source](upgrading_from_source.md) - The guidelines for upgrading Community Edition and Enterprise Edition from source. - [Patch versions](patch_versions.md) guide includes the steps needed for a - patch version, such as 6.2.0 to 6.2.1, and apply to both Community and Enterprise + patch version, such as 13.2.0 to 13.2.1, and apply to both Community and Enterprise Editions. In the past we used separate documents for the upgrading instructions, but we @@ -32,82 +55,20 @@ can still be found in the Git repository: - [Old upgrading guidelines for Community Edition](https://gitlab.com/gitlab-org/gitlab-foss/tree/11-8-stable/doc/update) - [Old upgrading guidelines for Enterprise Edition](https://gitlab.com/gitlab-org/gitlab/tree/11-8-stable-ee/doc/update) -## Installation using Docker +### Installation using Docker GitLab provides official Docker images for both Community and Enterprise editions. They are based on the Omnibus package and instructions on how to update them are in [a separate document](https://docs.gitlab.com/omnibus/docker/README.html). -## Upgrading without downtime - -Starting with GitLab 9.1.0 it's possible to upgrade to a newer major, minor, or -patch version of GitLab without having to take your GitLab instance offline. -However, for this to work there are the following requirements: - -- You can only upgrade 1 minor release at a time. So from 9.1 to 9.2, not to - 9.3. -- You have to use [post-deployment - migrations](../development/post_deployment_migrations.md) (included in - zero downtime update steps below). -- You are using PostgreSQL. Starting from GitLab 12.1, MySQL is not supported. -- Multi-node GitLab instance. Single-node instances may experience brief interruptions - [as services restart (Puma in particular)](https://docs.gitlab.com/omnibus/update/README.html#single-node-deployment). - -Most of the time you can safely upgrade from a patch release to the next minor -release if the patch release is not the latest. For example, upgrading from -9.1.1 to 9.2.0 should be safe even if 9.1.2 has been released. We do recommend -you check the release posts of any releases between your current and target -version just in case they include any migrations that may require you to upgrade -1 release at a time. - -Some releases may also include so called "background migrations". These -migrations are performed in the background by Sidekiq and are often used for -migrating data. Background migrations are only added in the monthly releases. - -Certain major/minor releases may require a set of background migrations to be -finished. To guarantee this such a release will process any remaining jobs -before continuing the upgrading procedure. While this won't require downtime -(if the above conditions are met) we recommend users to keep at least 1 week -between upgrading major/minor releases, allowing the background migrations to -finish. The time necessary to complete these migrations can be reduced by -increasing the number of Sidekiq workers that can process jobs in the -`background_migration` queue. To see the size of this queue, -[Check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading). - -As a rule of thumb, any database smaller than 10 GB won't take too much time to -upgrade; perhaps an hour at most per minor release. Larger databases however may -require more time, but this is highly dependent on the size of the database and -the migrations that are being performed. +### Installation using Helm -### Examples - -To help explain this, let's look at some examples. +GitLab can be deployed into a Kubernetes cluster using Helm. +Instructions on how to update a cloud-native deployment are in +[a separate document](https://docs.gitlab.com/charts/installation/upgrade.html). -**Example 1:** You are running a large GitLab installation using version 9.4.2, -which is the latest patch release of 9.4. When GitLab 9.5.0 is released this -installation can be safely upgraded to 9.5.0 without requiring downtime if the -requirements mentioned above are met. You can also skip 9.5.0 and upgrade to -9.5.1 once it's released, but you **can not** upgrade straight to 9.6.0; you -_have_ to first upgrade to a 9.5.x release. - -**Example 2:** You are running a large GitLab installation using version 9.4.2, -which is the latest patch release of 9.4. GitLab 9.5 includes some background -migrations, and 10.0 will require these to be completed (processing any -remaining jobs for you). Skipping 9.5 is not possible without downtime, and due -to the background migrations would require potentially hours of downtime -depending on how long it takes for the background migrations to complete. To -work around this you will have to upgrade to 9.5.x first, then wait at least a -week before upgrading to 10.0. - -**Example 3:** You use MySQL as the database for GitLab. Any upgrade to a new -major/minor release will require downtime. If a release includes any background -migrations this could potentially lead to hours of downtime, depending on the -size of your database. To work around this you will have to use PostgreSQL and -meet the other online upgrade requirements mentioned above. - -### Steps - -Steps to [upgrade without downtime](https://docs.gitlab.com/omnibus/update/README.html#zero-downtime-updates). +Use the [version mapping](https://docs.gitlab.com/charts/installation/version_mappings.html) +from the chart version to GitLab version to determine the [upgrade path](#upgrade-paths). ## Checking for background migrations before upgrading @@ -130,8 +91,6 @@ puts Sidekiq::Queue.new("background_migration").size Sidekiq::ScheduledSet.new.select { |r| r.klass == 'BackgroundMigrationWorker' }.size ``` ---- - **For installations from source** If using GitLab 12.9 and newer, run: @@ -153,7 +112,6 @@ Sidekiq::ScheduledSet.new.select { |r| r.klass == 'BackgroundMigrationWorker' }. CAUTION: **Warning:** The following operations can disrupt your GitLab performance. -NOTE: **Note:** It is safe to re-execute these commands, especially if you have 1000+ pending jobs which would likely overflow your runtime memory. **For Omnibus installations** @@ -180,16 +138,123 @@ pending_job_classes = scheduled_queue.select { |job| job["class"] == "Background pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) } ``` +## Upgrade paths + +Although you can generally upgrade through multiple GitLab versions in one go, +sometimes this can cause issues. + +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): + +`8.11.x` -> `8.12.0` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` -> `13.0.14` -> `13.1.11` - > `13.5.3` + +The following table, while not exhaustive, shows some examples of the supported +upgrade paths. + +| Target version | Your version | Supported upgrade path | Note | +| --------------------- | ------------ | ------------------------ | ---- | +| `13.4.3` | `12.9.2` | `12.9.2` -> `12.10.14` -> `13.0.14` -> `13.4.3` | Two intermediate versions are required: the final `12.10` release, plus `13.0`. | +| `13.2.10` | `11.5.0` | `11.5.0` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` -> `13.0.14` -> `13.2.10` | Five intermediate versions are required: the final `11.11`, `12.0`, `12.1` and `12.10` releases, plus `13.0`. | +| `12.10.14` | `11.3.4` | `11.3.4` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` | Three intermediate versions are required: the final `11.11` and `12.0` releases, plus `12.1` | +| `12.9.5` | `10.4.5` | `10.4.5` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.9.5` | Four intermediate versions are required: `10.8`, `11.11`, `12.0` and `12.1`, then `12.9.5` | +| `12.2.5` | `9.2.6` | `9.2.6` -> `9.5.10` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.2.5` | Five intermediate versions are required: `9.5`, `10.8`, `11.11`, `12.0`, `12.1`, then `12.2`. | +| `11.3.4` | `8.13.4` | `8.13.4` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.3.4` | `8.17.7` is the last version in version 8, `9.5.10` is the last version in version 9, `10.8.7` is the last version in version 10. | + ## Upgrading to a new major version -Major versions are reserved for backwards incompatible changes. We recommend that -you first upgrade to the latest available minor version within your major version. -Please follow the [Upgrade Recommendations](../policy/maintenance.md#upgrade-recommendations) -to identify a supported upgrade path. +Upgrading the *major* version requires more attention. +Backward-incompatible changes and migrations are reserved for major versions. +We cannot guarantee that upgrading between major versions will be seamless. +It is suggested to upgrade to the latest available *minor* version within +your major version before proceeding to the next major version. +Doing this will address any backward-incompatible changes or deprecations +to help ensure a successful upgrade to the next major release. +Identify a [supported upgrade path](#upgrade-paths). + +More significant migrations may occur during major release upgrades. To ensure these are successful: -Before upgrading to a new major version, you should ensure that any background -migration jobs from previous releases have been completed. To see the current size -of the `background_migration` queue, [check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading). +1. Increment to the first minor version (`x.0.x`) during the major version jump. +1. Proceed with upgrading to a newer release. + +It's also important to ensure that any background migrations have been fully completed +before upgrading to a new major version. To see the current size of the `background_migration` queue, +[Check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading). + +If your GitLab instance has any runners associated with it, it is very +important to upgrade GitLab Runner to match the GitLab minor version that was +upgraded to. This is to ensure [compatibility with GitLab versions](https://docs.gitlab.com/runner/#compatibility-with-gitlab-versions). + +## Upgrading without downtime + +Starting with GitLab 9.1.0 it's possible to upgrade to a newer major, minor, or +patch version of GitLab without having to take your GitLab instance offline. +However, for this to work there are the following requirements: + +- You can only upgrade 1 minor release at a time. So from 9.1 to 9.2, not to + 9.3. +- You have to use [post-deployment + migrations](../development/post_deployment_migrations.md) (included in + zero downtime update steps below). +- You are using PostgreSQL. Starting from GitLab 12.1, MySQL is not supported. +- Multi-node GitLab instance. Single-node instances may experience brief interruptions + [as services restart (Puma in particular)](https://docs.gitlab.com/omnibus/update/README.html#single-node-deployment). + +Most of the time you can safely upgrade from a patch release to the next minor +release if the patch release is not the latest. For example, upgrading from +9.1.1 to 9.2.0 should be safe even if 9.1.2 has been released. We do recommend +you check the release posts of any releases between your current and target +version just in case they include any migrations that may require you to upgrade +1 release at a time. + +Some releases may also include so called "background migrations". These +migrations are performed in the background by Sidekiq and are often used for +migrating data. Background migrations are only added in the monthly releases. + +Certain major/minor releases may require a set of background migrations to be +finished. To guarantee this such a release will process any remaining jobs +before continuing the upgrading procedure. While this won't require downtime +(if the above conditions are met) we recommend users to keep at least 1 week +between upgrading major/minor releases, allowing the background migrations to +finish. The time necessary to complete these migrations can be reduced by +increasing the number of Sidekiq workers that can process jobs in the +`background_migration` queue. To see the size of this queue, +[Check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading). + +As a rule of thumb, any database smaller than 10 GB won't take too much time to +upgrade; perhaps an hour at most per minor release. Larger databases however may +require more time, but this is highly dependent on the size of the database and +the migrations that are being performed. + +### Examples + +To help explain this, let's look at some examples. + +**Example 1:** You are running a large GitLab installation using version 9.4.2, +which is the latest patch release of 9.4. When GitLab 9.5.0 is released this +installation can be safely upgraded to 9.5.0 without requiring downtime if the +requirements mentioned above are met. You can also skip 9.5.0 and upgrade to +9.5.1 after it's released, but you **can not** upgrade straight to 9.6.0; you +_have_ to first upgrade to a 9.5.x release. + +**Example 2:** You are running a large GitLab installation using version 9.4.2, +which is the latest patch release of 9.4. GitLab 9.5 includes some background +migrations, and 10.0 will require these to be completed (processing any +remaining jobs for you). Skipping 9.5 is not possible without downtime, and due +to the background migrations would require potentially hours of downtime +depending on how long it takes for the background migrations to complete. To +work around this you will have to upgrade to 9.5.x first, then wait at least a +week before upgrading to 10.0. + +**Example 3:** You use MySQL as the database for GitLab. Any upgrade to a new +major/minor release will require downtime. If a release includes any background +migrations this could potentially lead to hours of downtime, depending on the +size of your database. To work around this you will have to use PostgreSQL and +meet the other online upgrade requirements mentioned above. + +### Steps + +Steps to [upgrade without downtime](https://docs.gitlab.com/omnibus/update/README.html#zero-downtime-updates). ## Upgrading between editions @@ -197,7 +262,7 @@ GitLab comes in two flavors: [Community Edition](https://about.gitlab.com/featur and [Enterprise Edition](https://about.gitlab.com/features/#enterprise) which builds on top of the Community Edition and includes extra features mainly aimed at organizations with more than 100 users. -Below you can find some guides to help you change editions easily. +Below you can find some guides to help you change GitLab editions. ### Community to Enterprise Edition @@ -220,7 +285,34 @@ If you need to downgrade your Enterprise Edition installation back to Community Edition, you can follow [this guide](../downgrade_ee_to_ce/README.md) to make the process as smooth as possible. -## Version specific upgrading instructions +## Version-specific upgrading instructions + +Each month, a major or minor release of GitLab is published along with a +[release post](https://about.gitlab.com/releases/categories/releases/). +You should check all the major and minor versions you're passing over. +At the end of those release posts, there are three sections to look for: + +- Deprecations +- Removals +- Important notes on upgrading + +These will include: + +- Steps you need to perform as part of an upgrade. + For example [8.12](https://about.gitlab.com/releases/2016/09/22/gitlab-8-12-released/#upgrade-barometer) + required the Elasticsearch index to be recreated. Any older version of GitLab upgrading to 8.12 or higher would require this. +- Changes to the versions of software we support such as + [ceasing support for IE11 in GitLab 13](https://about.gitlab.com/releases/2020/03/22/gitlab-12-9-released/#ending-support-for-internet-explorer-11). + +Apart from the instructions in this section, you should also check the +installation-specific upgrade instructions, based on how you installed GitLab: + +- [Linux packages (Omnibus GitLab)](https://docs.gitlab.com/omnibus/update/README.html#version-specific-changes) +- [Helm charts](https://docs.gitlab.com/charts/installation/upgrade.html) + +### 13.6.0 + +The required Git version is Git v2.29 or higher. ### 13.3.0 @@ -263,9 +355,9 @@ with the older Rails version - which could cause non-GET requests to fail for [multi-node GitLab installations](https://docs.gitlab.com/omnibus/update/#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.0 before upgrading to later versions: +all servers must first be upgraded to 13.1.X before upgrading to 13.2.0 or later: -1. Ensure all GitLab web nodes are on GitLab 13.1.0. +1. Ensure all GitLab web nodes are on GitLab 13.1.X. 1. Optionally, enable the `global_csrf_token` feature flag to enable new method of CSRF token generation: @@ -283,10 +375,16 @@ 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.x` to `12.10.x`, it is necessary to +perform an intermediary upgrade to `12.1.x` before upgrading to `12.10.x` to +avoid issues like [#215141](https://gitlab.com/gitlab-org/gitlab/-/issues/215141). + ### 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. Once upgraded to 11.11.x, +users first upgrade to the latest 11.11 patch release. After upgraded to 11.11.x, users can upgrade to 12.0.x. Failure to do so may result in database migrations not being applied, which could lead to application errors. @@ -298,11 +396,17 @@ release for 11.11.x. You can upgrade as usual to 12.0.x. Example 2: you are currently using a version of GitLab 10.x. To upgrade, first upgrade to the last 10.x release (10.8.7) then the last 11.x release (11.11.8). -Once upgraded to 11.11.8 you can safely upgrade to 12.0.x. +After upgraded to 11.11.8 you can safely upgrade to 12.0.x. See our [documentation on upgrade paths](../policy/maintenance.md#upgrade-recommendations) for more information. +### Upgrades from versions earlier than 8.12 + +- `8.11.x` and earlier: you might have to upgrade to `8.12.0` specifically before you can upgrade to `8.17.7`. This was [reported in an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/207259). +- [CI changes prior to version 8.0](https://docs.gitlab.com/omnibus/update/README.html#updating-gitlab-ci-from-prior-540-to-version-714-via-omnibus-gitlab) + when it was merged into GitLab. + ## Miscellaneous - [MySQL to PostgreSQL](mysql_to_postgresql.md) guides you through migrating diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md index 0759d45147a..10c1a5017b5 100644 --- a/doc/update/mysql_to_postgresql.md +++ b/doc/update/mysql_to_postgresql.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Migrating from MySQL to PostgreSQL This guide documents how to take a working GitLab instance that uses MySQL and diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md index 0092df7b89d..081df16be81 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/update/restore_after_failure.md b/doc/update/restore_after_failure.md index 2c70e38d041..e35d7bff562 100644 --- a/doc/update/restore_after_failure.md +++ b/doc/update/restore_after_failure.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Restoring from backup after a failed upgrade Upgrades are usually smooth and restoring from backup is a rare occurrence. diff --git a/doc/update/upgrading_from_ce_to_ee.md b/doc/update/upgrading_from_ce_to_ee.md index f82f5001c89..71d857ce18f 100644 --- a/doc/update/upgrading_from_ce_to_ee.md +++ b/doc/update/upgrading_from_ce_to_ee.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index a0f042acab2..d2a3466984e 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- @@ -132,7 +135,7 @@ To check you are running the minimum required Git version, see In Debian or Ubuntu: ```shell -# Make sure Git is version 2.24.0 or higher +# Make sure Git is version 2.29.0 or higher git --version # Remove packaged Git @@ -152,9 +155,9 @@ make install # Download and compile from source cd /tmp -curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.28.0.tar.gz -echo 'f914c60a874d466c1e18467c864a910dd4ea22281ba6d4d58077cb0c3f115170 git-2.28.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.28.0.tar.gz -cd git-2.28.0/ +curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.29.0.tar.gz +echo 'fa08dc8424ef80c0f9bf307877f9e2e49f1a6049e873530d6747c2be770742ff git-2.29.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.29.0.tar.gz +cd git-2.29.0/ ./configure --with-libpcre make prefix=/usr/local all diff --git a/doc/update/upgrading_postgresql_using_slony.md b/doc/update/upgrading_postgresql_using_slony.md index 5133e4cf4e5..4d8b58cc3af 100644 --- a/doc/update/upgrading_postgresql_using_slony.md +++ b/doc/update/upgrading_postgresql_using_slony.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Upgrading PostgreSQL Using Slony This guide describes the steps one can take to upgrade their PostgreSQL database diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md index e6c86cc8f2e..155f45f087f 100644 --- a/doc/user/abuse_reports.md +++ b/doc/user/abuse_reports.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Abuse reports You can report abuse from other GitLab users to GitLab administrators. diff --git a/doc/user/admin_area/activating_deactivating_users.md b/doc/user/admin_area/activating_deactivating_users.md index 8b3a7682841..96b39ae7116 100644 --- a/doc/user/admin_area/activating_deactivating_users.md +++ b/doc/user/admin_area/activating_deactivating_users.md @@ -44,7 +44,7 @@ Please note that for the deactivation option to be visible to an admin, the user Users can also be deactivated using the [GitLab API](../../api/users.md#deactivate-user). NOTE: **Note:** -A deactivated user does not consume a [seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). +A deactivated user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). ## Activating a user @@ -62,8 +62,8 @@ To do this: Users can also be activated using the [GitLab API](../../api/users.md#activate-user). NOTE: **Note:** -Activating a user will change the user's state to active and it consumes a -[seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). +Activating a user changes the user's state to active and consumes a +[seat](../../subscriptions/self_managed/index.md#billable-users). TIP: **Tip:** A deactivated user can also activate their account themselves by simply logging back in via the UI. diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index f04bd69b76b..d1f80e63c04 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -1,4 +1,10 @@ -# DevOps Report +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# DevOps Report **(CORE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30469) in GitLab 9.3. > - [Renamed from Conversational Development Index](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) in GitLab 12.6. @@ -10,6 +16,8 @@ The DevOps Report gives you an overview of your entire instance's adoption of [Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/) from planning to monitoring. +To see DevOps Report, go to **Admin Area > Analytics > DevOps Report**. + ## DevOps Score DevOps Score displays the usage of GitLab's major features on your instance over diff --git a/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6.png b/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6.png Binary files differnew file mode 100644 index 00000000000..da9e4c64e12 --- /dev/null +++ b/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6.png diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index f79245c7325..792d0245290 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Instance-level analytics > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41416) in GitLab 11.2. @@ -6,6 +12,6 @@ Administrators have access to instance-wide analytics, as shown in **Admin Area There are several kinds of statistics: -- [DevOps Report](dev_ops_report.md): Provides an overview of your entire instance's feature usage. -- [Instance Statistics](instance_statistics.md): Shows how much data your instance contains, and how that is changing. -- [User Cohorts](user_cohorts.md): Display the monthly cohorts of new users and their activities over time. +- [DevOps Report](dev_ops_report.md): Provides an overview of your entire instance's feature usage. **(CORE)** +- [Instance Statistics](instance_statistics.md): Shows how much data your instance contains, and how that is changing. **(CORE)** +- [User Cohorts](user_cohorts.md): Display the monthly cohorts of new users and their activities over time. **(CORE)** diff --git a/doc/user/admin_area/analytics/instance_statistics.md b/doc/user/admin_area/analytics/instance_statistics.md index bac0e845d2c..0d62d30435d 100644 --- a/doc/user/admin_area/analytics/instance_statistics.md +++ b/doc/user/admin_area/analytics/instance_statistics.md @@ -1,9 +1,23 @@ -# Instance Statistics +--- +stage: Manage +group: Value Stream Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235754) in GitLab 13.4. +# Instance Statistics **(CORE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235754) in GitLab 13.5 behind a feature flag, disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46962) in GitLab 13.6. +> - It's enabled on GitLab.com. +> - It's recommended for production use. + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. Instance Statistics gives you an overview of how much data your instance contains, and how quickly this volume is changing over time. +To see Instance Statistics, go to **Admin Area > Analytics > Instance Statistics**. + ## Total counts At the top of the page, Instance Statistics shows total counts for: @@ -16,3 +30,31 @@ At the top of the page, Instance Statistics shows total counts for: - Pipelines These figures can be useful for understanding how much data your instance contains in total. + +## Past year trend charts + +Instance Statistics also displays line charts that show total counts per month, over the past 12 months, +in the categories shown in [Total counts](#total-counts). + +These charts help you visualize how rapidly these records are being created on your instance. + + + +### Enable or disable Instance Statistics + +In GitLab version 13.5 only, Instance Statistics was under development and not ready for production use. +It was deployed behind a feature flag that was **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to enable it. + +To enable it: + +```ruby +Feature.enable(:instance_statistics) +``` + +To disable it: + +```ruby +Feature.disable(:instance_statistics) +``` diff --git a/doc/user/admin_area/analytics/user_cohorts.md b/doc/user/admin_area/analytics/user_cohorts.md index faf8caa7e00..c9b62e258ae 100644 --- a/doc/user/admin_area/analytics/user_cohorts.md +++ b/doc/user/admin_area/analytics/user_cohorts.md @@ -1,10 +1,18 @@ -# Cohorts +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Cohorts **(CORE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/23361) in GitLab 9.1. As a benefit of having the [usage ping active](../settings/usage_statistics.md), GitLab lets you analyze the users' activities over time of your GitLab installation. +To see User Cohorts, go to **Admin Area > Analytics > Cohorts**. + ## Overview How do we read the user cohorts table? Let's take an example with the following diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index 55dabce7342..23a6de38e17 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page.html' --- @@ -76,7 +79,7 @@ to activate it in the GitLab instance. You can also click on the **Sign-in page* to review the saved appearance settings: NOTE: **Note:** -You can add also add a [customized help message](settings/help_page.md) below the sign in message. +You can add also add a [customized help message](settings/help_page.md) below the sign in message or add [a Sign in text message](settings/sign_in_restrictions.md#sign-in-information). ## New project pages diff --git a/doc/user/admin_area/approving_users.md b/doc/user/admin_area/approving_users.md index 486d0b6a25d..430ad4f8899 100644 --- a/doc/user/admin_area/approving_users.md +++ b/doc/user/admin_area/approving_users.md @@ -9,7 +9,7 @@ type: howto > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5. -When [Require admin approval for new sign-ups](settings/sign_up_restrictions.md#require-admin-approval-for-new-sign-ups) is enabled, any user that signs up for an account using the registration form is placed under a **Pending approval** state. +When [Require admin approval for new sign-ups](settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) is enabled, any user that signs up for an account using the registration form is placed under a **Pending approval** state. A user pending approval is functionally identical to a [blocked](blocking_unblocking_users.md) user. @@ -18,7 +18,7 @@ A user pending approval: - Will not be able to sign in. - Cannot access Git repositories or the API. - Will not receive any notifications from GitLab. -- Does not consume a [seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). +- Does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). ## Approving a user @@ -33,4 +33,4 @@ Approving a user: 1. Activates their account. 1. Changes the user's state to active and it consumes a -[seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). +[seat](../../subscriptions/self_managed/index.md#billable-users). diff --git a/doc/user/admin_area/blocking_unblocking_users.md b/doc/user/admin_area/blocking_unblocking_users.md index d8dde317d38..989182db423 100644 --- a/doc/user/admin_area/blocking_unblocking_users.md +++ b/doc/user/admin_area/blocking_unblocking_users.md @@ -23,17 +23,17 @@ or directly from the Admin Area. To do this: A blocked user: -- Will not be able to login. +- Cannot log in. - Cannot access Git repositories or the API. -- Will not receive any notifications from GitLab. -- Will not be able to use [slash commands](../../integration/slash_commands.md). +- Does not receive any notifications from GitLab. +- Cannot use [slash commands](../../integration/slash_commands.md). -Personal projects, and group and user history of the blocked user will be left intact. +Personal projects, and group and user history of the blocked user are left intact. Users can also be blocked using the [GitLab API](../../api/users.md#block-user). NOTE: **Note:** -A blocked user does not consume a [seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). +A blocked user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). ## Unblocking a user @@ -47,5 +47,5 @@ A blocked user can be unblocked from the Admin Area. To do this: Users can also be unblocked using the [GitLab API](../../api/users.md#unblock-user). NOTE: **Note:** -Unblocking a user will change the user's state to active and it consumes a -[seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). +Unblocking a user changes the user's state to active and consumes a +[seat](../../subscriptions/self_managed/index.md#billable-users). diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 7e1a4faee75..0bbdf5bc5e7 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- @@ -62,12 +65,17 @@ To add a broadcast message: 1. Navigate to the **Admin Area > Messages** page. 1. Add the text for the message to the **Message** field. Markdown and emoji are supported. -1. If required, click the **Customize colors** link to edit the background color and font color of the message. +1. Select one of the suggested background colors, or add the hex code of a different color. The default color is orange. 1. If required, add a **Target Path** to only show the broadcast message on URLs matching that path. You can use the wildcard character `*` to match multiple URLs, for example `/users/*/issues`. 1. Select a date for the message to start and end. 1. Click the **Add broadcast message** button. NOTE: **Note:** +The **Background color** field expects the value to be a hexadecimal code because +the form uses the [color_field](https://api.rubyonrails.org/v6.0.3.4/classes/ActionView/Helpers/FormHelper.html#method-i-color_field) +helper method, which generates the proper HTML to render. + +NOTE: **Note:** Once a broadcast message has expired, it is no longer displayed in the UI but is still listed in the list of broadcast messages. User can also dismiss a broadcast message if the option **Dismissable** is set. diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index b17d0ab3dd5..fc04f9786b6 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -40,10 +40,13 @@ If you see a **Revoke** button, you can revoke that user's PAT. Whether you see | Revoked | Yes | No | Not applicable; token is already revoked | | Revoked | No | No | Not applicable; token is already revoked | +When a PAT is revoked from the credentials inventory, the instance notifies the user by email. + ## Delete a user's SSH key > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225248) in GitLab 13.5. You can **Delete** a user's SSH key by navigating to the credentials inventory's SSH Keys tab. +The instance then notifies the user.  diff --git a/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png b/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png Binary files differindex 59c190393d1..d05bda71545 100644 --- a/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png +++ b/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png diff --git a/doc/user/admin_area/img/appearance_sign_in_v12_3.png b/doc/user/admin_area/img/appearance_sign_in_v12_3.png Binary files differindex 7e2337bbae8..0caa29aae2c 100644 --- a/doc/user/admin_area/img/appearance_sign_in_v12_3.png +++ b/doc/user/admin_area/img/appearance_sign_in_v12_3.png diff --git a/doc/user/admin_area/img/mr_approval_settings_compliance_project_v13_1.png b/doc/user/admin_area/img/mr_approval_settings_compliance_project_v13_1.png Binary files differdeleted file mode 100644 index 04d01f2662f..00000000000 --- a/doc/user/admin_area/img/mr_approval_settings_compliance_project_v13_1.png +++ /dev/null diff --git a/doc/user/admin_area/img/scope_mr_approval_settings_v13_1.png b/doc/user/admin_area/img/scope_mr_approval_settings_v13_1.png Binary files differdeleted file mode 100644 index fe85d567a57..00000000000 --- a/doc/user/admin_area/img/scope_mr_approval_settings_v13_1.png +++ /dev/null diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 0ddbe17580a..fd8c72ad081 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- @@ -143,22 +146,16 @@ you must provide the complete email address. #### Users statistics -The **Users statistics** page provides an overview of user accounts by role, such as _Users with -highest role Maintainer_. +The **Users statistics** page provides an overview of user accounts by role. These statistics are +calculated daily, so user changes made since the last update are not reflected. The following totals are also included: -- Active users +- Billable users - Blocked users - Total users -GitLab billing is based on the number of **Active users**, calculated as **Total users** - -**Blocked users**. For details of active users, see -[Choosing the number of users](../../subscriptions/self_managed/index.md#choose-the-number-of-users). - -NOTE: **Note:** -Users statistics are calculated daily, so user changes made since the last update won't be -reflected in the statistics. +GitLab billing is based on the number of [**Billable users**](../../subscriptions/self_managed/index.md#billable-users). ### Administering Groups diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index c37a61d6748..2b0496b381a 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -8,14 +8,22 @@ type: howto # Activate GitLab EE with a license **(STARTER ONLY)** To activate all GitLab Enterprise Edition (EE) functionality, you need to upload -a license. After you've received your license from GitLab Inc., you can upload it -by **signing into your GitLab instance as an admin** or adding it at -installation time. +a license. It's only possible to activate GitLab Enterprise Edition, so first verify which edition +you are running. To verify, sign in to GitLab and browse to `/help`. The GitLab edition and version +are listed at the top of the **Help** page. + +If you are running GitLab Community Edition (CE), upgrade your installation to +GitLab Enterprise Edition (EE). For more details, see [Upgrading between editions](../../update/README.md#upgrading-between-editions). +If you have questions or need assistance upgrading from GitLab CE to EE please [contact GitLab Support](https://about.gitlab.com/support/#contact-support). The license is a base64-encoded ASCII text file with a `.gitlab-license` extension. You can obtain the file by [purchasing a license](https://about.gitlab.com/pricing/) or by signing up for a [free trial](https://about.gitlab.com/free-trial/). +After you've received your license from GitLab Inc., you can upload it +by **signing into your GitLab instance as an admin** or adding it at +installation time. + As of GitLab Enterprise Edition 9.4.0, a newly-installed instance without an uploaded license only has the Core features active. A trial license activates all Ultimate features, but after @@ -108,8 +116,9 @@ To remove a license from a self-managed instance: ## License history -You can upload and view more than one license, -but only the latest license is used as the active license. +You can upload and view more than one license, but only the latest license in the current date +range is used as the active license. When you upload a future-dated license, it +doesn't take effect until its applicable date. ## Troubleshooting diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 2a38ccb31f0..88c98248435 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: concepts, howto --- diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 957f84206e9..97c74483cc3 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -18,6 +18,12 @@ If you choose a size larger than what is currently configured for the web server you will likely get errors. See the [troubleshooting section](#troubleshooting) for more details. +## Max push size + +You can change the maximum push size for your repository. +Navigate to **Admin Area (wrench icon) > Settings > General**, then expand **Account and Limit**. +From here, you can increase or decrease by changing the value in `Maximum push size (MB)`. + ## Max import size You can change the maximum file size for imports in GitLab. @@ -76,12 +82,13 @@ and **will** be rejected if the sum of their sizes exceeds the maximum allowed repository size. NOTE: **Note:** -The repository size limit includes repository files and LFS, and does not include artifacts. +The repository size limit includes repository files and LFS, but does not include artifacts, uploads, +wiki, packages, or snippets. For details on manually purging files, see [reducing the repository size using Git](../../project/repository/reducing_the_repo_size_using_git.md). NOTE: **Note:** -GitLab.com repository size [is set by GitLab](../../gitlab_com/index.md#account-and-limit-settings). +For GitLab.com repository size limits, see [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). ## Troubleshooting diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 0b250e07412..80bca6f5b2c 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index ca983edd4fa..c0237c3da73 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto --- diff --git a/doc/user/admin_area/settings/img/custom_sign_in_page_v13_6.png b/doc/user/admin_area/settings/img/custom_sign_in_page_v13_6.png Binary files differnew file mode 100644 index 00000000000..5eb2134187a --- /dev/null +++ b/doc/user/admin_area/settings/img/custom_sign_in_page_v13_6.png diff --git a/doc/user/admin_area/settings/img/disable_signup_v12_7.png b/doc/user/admin_area/settings/img/disable_signup_v12_7.png Binary files differdeleted file mode 100644 index be1a070a804..00000000000 --- a/doc/user/admin_area/settings/img/disable_signup_v12_7.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/respond_to_terms.png b/doc/user/admin_area/settings/img/respond_to_terms.png Binary files differindex d0d086c3498..f91480d1ce7 100644 --- a/doc/user/admin_area/settings/img/respond_to_terms.png +++ b/doc/user/admin_area/settings/img/respond_to_terms.png diff --git a/doc/user/admin_area/settings/img/sign_up_restrictions_v13_5.png b/doc/user/admin_area/settings/img/sign_up_restrictions_v13_5.png Binary files differdeleted file mode 100644 index ebbfad77e69..00000000000 --- a/doc/user/admin_area/settings/img/sign_up_restrictions_v13_5.png +++ /dev/null diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index bc8df63e33f..21d495de5b7 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: index --- @@ -20,7 +23,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | [Account and limit](account_and_limit_settings.md) **(STARTER)** | 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](sign_up_restrictions.md) | Configure the way a user creates a new account. | -| [Sign in restrictions](sign_in_restrictions.md) | Set requirements for a user to sign-in. Enable mandatory two-factor authentication. | +| [Sign in restrictions](sign_in_restrictions.md) | Set requirements for a user to sign in. Enable mandatory two-factor authentication. | | [Terms of Service and Privacy Policy](terms.md) | Include a Terms of Service agreement and Privacy Policy that all users must accept. | | [External Authentication](external_authorization.md#configuration) | External Classification Policy Authorization | | [Web terminal](../../../administration/integration/terminal.md#limiting-websocket-connection-time) | Set max session time for web terminal. | diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index 748d608676d..c09bb6f3c67 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -8,51 +8,87 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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 -can inherit and use. This enables the integration for all projects that are not already using custom +can inherit and use, enabling the integration for all projects that are not already using custom settings. You can update these default settings at any time, changing the settings used for all projects that -are set to use instance-level defaults. Updating the default settings also enables the integration +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) as is -[group-level management](https://gitlab.com/groups/gitlab-org/-/epics/2543) of integration settings. +Only the complete settings for an integration can be inherited. Per-field inheritance is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). ## Manage instance-level default settings for a project integration **(CORE ONLY)** -> [Introduced in](https://gitlab.com/groups/gitlab-org/-/epics/2137) GitLab 13.3. +> - [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. 1. Navigate to **Admin Area > Settings > Integrations**. -1. Select a project integration. +1. Select an integration. 1. Enter configuration details and click **Save changes**. CAUTION: **Caution:** -This may affect all or most of the projects on your GitLab instance. Please review the details +This may affect all or most of the groups and projects on your GitLab instance. Please review the details below. If this is the first time you are setting up instance-level settings for an integration: -- The integration is enabled for all projects that don't already have this integration configured, +- The integration is enabled for all groups and projects that don't already have this integration configured, if you have the **Enable integration** toggle turned on in the instance-level settings. -- Projects that already have the integration configured are not affected, but can choose to use the +- Groups and projects that already have the integration configured are not affected, but can choose to use the inherited settings at any time. When you make further changes to the instance defaults: -- They are immediately applied to all projects that have the integration set to use default settings. -- They are immediately applied to newer projects, created since you last saved defaults for the +- They are immediately applied to all groups and projects that have the integration set to use default settings. +- They are immediately applied to newer groups and projects, created since you last saved defaults for the integration. If your instance-level default setting has the **Enable integration** toggle turned - on, the integration is automatically enabled for all such projects. -- Projects with custom settings selected for the integration are not immediately affected and may + on, the integration is automatically enabled for all such groups and projects. +- 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 projects without enabling the -integration on all non-configured projects by default. +administrators to update settings inherited by groups and projects without enabling the +integration on all non-configured groups and projects by default. -## Use instance-level default settings for a project integration +## Manage group-level default settings for a project integration + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6. + +1. Navigate to the group's **Settings > Integrations**. +1. Select an integration. +1. Enter configuration details and click **Save changes**. + +CAUTION: **Caution:** +This may affect all or most of the subgroups and projects belonging to the group. Please review the details below. + +If this is the first time you are setting up group-level settings for an integration: + +- The integration is enabled for all subgroups and projects belonging to the group that don't already have + this integration configured, if you have the **Enable integration** toggle turned on in the group-level + settings. +- Subgroups and projects that already have the integration configured are not affected, but can choose to use + the inherited settings at any time. + +When you make further changes to the group defaults: + +- They are immediately applied to all subgroups and projects belonging to the group that have the integration + set to use default settings. +- They are immediately applied to newer subgroups and projects, created since 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. + +## 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. 1. Navigate to **Project > Settings > Integrations**. 1. Choose the integration you want to enable or update. @@ -60,9 +96,9 @@ integration on all non-configured projects by default. 1. Ensure the toggle is set to **Enable integration**. 1. Click **Save changes**. -## Use custom settings for a project integration +## Use custom settings for a group or project integration -1. Navigate to project's **Settings > Integrations**. +1. Navigate to project or group's **Settings > Integrations**. 1. Choose the integration you want to enable or update. 1. From the drop-down, select **Use custom settings**. 1. Ensure the toggle is set to **Enable integration** and enter all required settings. diff --git a/doc/user/admin_area/settings/protected_paths.md b/doc/user/admin_area/settings/protected_paths.md index 0cfaf5843d0..bb6fff9650d 100644 --- a/doc/user/admin_area/settings/protected_paths.md +++ b/doc/user/admin_area/settings/protected_paths.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md index 45dcc9119ac..96cd71033d0 100644 --- a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md +++ b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 311b79af7e3..7ab1d396e8b 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- @@ -47,8 +50,21 @@ All users that are not logged-in will be redirected to the page represented by t All users will be redirect to the page represented by the configured "After sign out path" after sign out if value is not empty. -If a "Sign in text" in Markdown format is provided, then every user will be presented with -this message after logging-in. +In the Sign-in restrictions section, scroll to the "Sign-in text" text box. You can add a +custom message for your users in Markdown format. + +For example, if you include the following information in the noted text box: + +```markdown +# Custom sign-in text + +To access this text box, navigate to Admin Area > Settings > General, and expand the "Sign-in restrictions" section. +``` + +Your users will see the "Custom sign-in text" when they navigate to the sign-in screen for your +GitLab instance: + + <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index f57cf7c2045..5ea034ff4d2 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -1,52 +1,75 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- # Sign-up restrictions **(CORE ONLY)** -You can use sign-up restrictions to: +You can enforce the following restrictions on sign ups: -- Disable new sign-ups. -- Require admin approval for new sign-ups. +- Disable new sign ups. +- Require administrator approval for new sign ups. - Require user email confirmation. -- Denylist or allowlist email addresses belonging to specific domains. +- Allow or deny sign ups using specific email domains. -NOTE: **Note:** -These restrictions are only applied during sign-up from an external user. An admin can add a user through the admin panel with a disallowed domain. Also, note that the users can change their email addresses after sign-up to -disallowed domains. +## Disable new sign ups -## Disable new signups +By default, any user visiting your GitLab domain can sign up for an account. For customers running +public-facing GitLab instances, we **highly** recommend that you consider disabling new sign ups if +you do not expect public users to sign up for an account. -When this setting is enabled, any user visiting your GitLab domain will be able to sign up for an account. +To disable sign ups: - +1. Go to **Admin Area > Settings > General** and expand **Sign-up restrictions**. +1. Clear the **Sign-up enabled** checkbox, then select **Save changes**. -You can restrict new users from signing up by themselves for an account in your instance by disabling this setting. +## Require administrator approval for new sign ups -### Recommendations +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/267568) in GitLab 13.6. -For customers running public-facing GitLab instances, we highly recommend that you -consider disabling new sign-ups if you do not expect public users to sign up for an -account. +When this setting is enabled, any user visiting your GitLab domain and signing up for a new account must be explicitly [approved](../approving_users.md#approving-a-user) by an administrator before they can start using their account. This setting is enabled by default for newly created instances. This setting is only applicable if sign ups are enabled. -Alternatively, you could also consider setting up a -[allowlist](#allowlist-email-domains) or [denylist](#denylist-email-domains) on -email domains to prevent malicious users from creating accounts. +To require administrator approval for new sign ups: -## Require admin approval for new sign-ups +1. Go to **Admin Area > Settings > General** and expand **Sign-up restrictions**. +1. Select the **Require admin approval for new sign-ups** checkbox, then select **Save changes**. -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5. +## Require email confirmation -When this setting is enabled, any user visiting your GitLab domain and signing up for a new account will have to be explicitly [approved](../approving_users.md#approving-a-user) by an administrator before they can start using their account. +You can send confirmation emails during sign up and require that users confirm +their email address before they are allowed to sign in. - +To enforce confirmation of the email address used for new sign ups: -## Require email confirmation +1. Go to **Admin Area > Settings > General** and expand **Sign-up restrictions**. +1. Select the **Enable email restrictions for sign ups** checkbox, then select **Save changes**. -You can send confirmation emails during sign-up and require that users confirm -their email address before they are allowed to sign in. +## User cap **(CORE ONLY)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4315) in GitLab 13.6. - +When the number of users reaches the user cap, any user who is added or requests access must be +[approved](../approving_users.md#approving-a-user) by an administrator before they can start using +their account. + +## Soft email confirmation + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47003) in GitLab 12.2. +> - It's [deployed behind a feature flag](../../..//user/feature_flags.md), disabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-soft-email-confirmation). + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +The soft email confirmation improves the signup experience for new users by allowing +them to sign in without an immediate confirmation when an email confirmation is required. +GitLab shows the user a reminder to confirm their email address, and the user can't +create or update pipelines until their email address is confirmed. ## Minimum password length limit @@ -55,40 +78,61 @@ their email address before they are allowed to sign in. You can [change](../../../security/password_length_limits.md#modify-minimum-password-length-using-gitlab-ui) the minimum number of characters a user must have in their password using the GitLab UI. -## Allowlist email domains +## Allow or deny sign ups using specific email domains + +You can specify an inclusive or exclusive list of email domains which can be used for user sign up. + +These restrictions are only applied during sign up from an external user. An administrator can add a +user through the admin panel with a disallowed domain. Also, note that the users can change their +email addresses to disallowed domains after sign up. + +### Allowlist email domains > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/598) in GitLab 7.11.0 You can restrict users only to sign up using email addresses matching the given domains list. -## Denylist email domains +### Denylist email domains > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5259) in GitLab 8.10. -With this feature enabled, you can block email addresses of a specific domain -from creating an account on your GitLab server. This is particularly useful -to prevent malicious users from creating spam accounts with disposable email -addresses. - -## Settings +You can block users from signing up when using an email addresses of specific domains. This can +reduce the risk of malicious users creating spam accounts with disposable email addresses. -To access this feature: +### Create email domain allowlist or denylist -1. Navigate to the **Admin Area > Settings > General**. -1. Expand the **Sign-up restrictions** section. +To create an email domain allowlist or denylist: -For the denylist, you can enter the list manually or upload a `.txt` file that -contains list entries. +1. Go to **Admin Area > Settings > General** and expand **Sign-up restrictions**. +1. For the allowlist, you must enter the list manually. For the denylist, you can enter the list + manually or upload a `.txt` file that contains list entries. -For the allowlist, you must enter the list manually. - -Both the allowlist and denylist accept wildcards. For example, you can use + Both the allowlist and denylist accept wildcards. For example, you can use `*.company.com` to accept every `company.com` subdomain, or `*.io` to block all -domains ending in `.io`. Domains should be separated by a whitespace, +domains ending in `.io`. Domains must be separated by a whitespace, semicolon, comma, or a new line. - +  + +### Enable or disable soft email confirmation + +Soft email confirmation is under development but ready for production use. +It is deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:soft_email_confirmation) +``` + +To disable it: + +```ruby +Feature.disable(:soft_email_confirmation) +``` <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index 77c172aa927..95c32af5716 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index 29ca3bf5ab2..f0e53115cb1 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 140d149555a..d4080b3921a 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index 5d49d88d254..af3e0c5b63b 100644 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- @@ -19,6 +22,43 @@ These limits are disabled by default.  +## Use an HTTP header to bypass rate limiting + +> [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/622) in GitLab 13.6. + +Depending on the needs of your organization, you may want to enable rate limiting +but have some requests bypass the rate limiter. + +You can do this by marking requests that should bypass the rate limiter with a custom +header. You must do this somewhere in a load balancer or reverse proxy in front of +GitLab. For example: + +1. Pick a name for your bypass header. For example, `Gitlab-Bypass-Rate-Limiting`. +1. Configure your load balancer to set `Gitlab-Bypass-Rate-Limiting: 1` on requests + that should bypass GitLab rate limiting. +1. Configure your load balancer to either: + - Erase `Gitlab-Bypass-Rate-Limiting`. + - Set `Gitlab-Bypass-Rate-Limiting` to a value other than `1` on all requests that + should be affected by rate limiting. +1. Set the environment variable `GITLAB_THROTTLE_BYPASS_HEADER`. + - For [Omnibus](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` + in `/etc/default/gitlab`. + +It is important that your load balancer erases or overwrites the bypass +header on all incoming traffic, because otherwise you must trust your +users to not set that header and bypass the GitLab rate limiter. + +Note that the bypass only works if the header is set to `1`. + +Requests that bypassed the rate limiter because of the bypass header +will be marked with `"throttle_safelist":"throttle_bypass_header"` in +[`production_json.log`](../../../administration/logs.md#production_jsonlog). + +To disable the bypass mechanism, make sure the environment variable +`GITLAB_THROTTLE_BYPASS_HEADER` is unset or empty. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index 95a87378e18..3740dc95c12 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -78,7 +78,7 @@ CAUTION: **Warning:** The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to [Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. -Projects within a group can be deleted after a delayed period, by [configuring in Group Settings](../../group/index.md#enabling-delayed-project-removal). +Projects within a group (but not a personal namespace) can be deleted after a delayed period, by [configuring in Group Settings](../../group/index.md#enabling-delayed-project-removal). The default period is 7 days, and can be changed. Setting this period to 0 will enable immediate removal of projects or groups. diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 89acb430a9f..dc956765794 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -1,7 +1,7 @@ --- description: "Learn how long your open merge requests have spent in code review, and what distinguishes the longest-running." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. stage: Manage -group: Analytics +group: Value Stream Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 54b4c702c5c..29df25d76af 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Analytics +group: Value Stream Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -26,6 +26,7 @@ The following analytics features are available at the group level: - [Insights](../group/insights/index.md). **(ULTIMATE)** - [Issue](../group/issues_analytics/index.md). **(PREMIUM)** - [Productivity](productivity_analytics.md) **(PREMIUM)** +- [Repositories](../group/repositories_analytics/index.md) **(PREMIUM)** - [Value Stream](value_stream_analytics.md). **(PREMIUM)** ## Project-level analytics @@ -34,7 +35,7 @@ The following analytics features are available at the project level: - [CI/CD](../../ci/pipelines/index.md#pipeline-success-and-duration-charts). **(STARTER)** - [Code Review](code_review_analytics.md). **(STARTER)** -- [Insights](../group/insights/index.md). **(ULTIMATE)** +- [Insights](../project/insights/index.md). **(ULTIMATE)** - [Issue](../group/issues_analytics/index.md). **(PREMIUM)** - [Merge Request](merge_request_analytics.md), enabled with the `project_merge_request_analytics` [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-locally-in-development). **(STARTER)** diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 04a5fa71e19..5402d9a20a0 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -1,7 +1,7 @@ --- description: "Merge Request Analytics help you understand the efficiency of your code review process, and the productivity of your team." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. stage: Manage -group: Analytics +group: Value Stream Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -57,9 +57,11 @@ Data table displaying a maximum of the 100 most recent merge requests merged for You can filter the data that is presented on the page based on the following parameters: - Author -- Assignees -- Labels -- Milestones +- Assignee +- Label +- Milestone +- Source branch +- Target branch To filter results: diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index 951be1c550b..da3fe00a901 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Analytics +group: Value Stream Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 6d2de951a55..3fc5478d466 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Analytics +group: Value Stream Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 86525587b30..244e37ba3ab 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Analytics +group: Value Stream Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -105,7 +105,7 @@ Each stage of Value Stream Analytics is further described in the table below. | --------- | --------------- | | Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label will be tracked only if it already has an [Issue Board list](../project/issue_board.md) created for it. | | Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (e.g., `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. | -| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the issue closing pattern is not present in the merge request description, the MR is not considered to the measurement time of the stage. | +| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the closing pattern is not present, then the calculation takes the creation time of the first commit in the merge request as the start time. | | Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI/CD takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | | Review | Measures the median time taken to review the merge request that has a closing issue pattern, between its creation and until it's merged. | | Staging | Measures the median time between merging the merge request with a closing issue pattern until the very first deployment to a [production environment](#how-the-production-environment-is-identified). If there isn't a production environment, this is not tracked. | @@ -299,7 +299,7 @@ To recover a default stage that was previously hidden: A default value stream is readily available for each group. You can create additional value streams based on the different areas of work that you would like to measure. -Once created, a new value stream includes the [seven stages](#overview) that follow +Once created, a new value stream includes the [seven stages](#default-stages) that follow [GitLab workflow](../../topics/gitlab_flow.md) best practices. You can customize this flow by adding, hiding or re-ordering stages. @@ -339,12 +339,14 @@ Feature.disable(:value_stream_analytics_create_multiple_value_streams) > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21631) in GitLab 12.6. > - [Chart median line removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235455) in GitLab 13.4. -This chart visually depicts the total number of days it takes for cycles to be completed. +This chart visually depicts the total number of days it takes for cycles to be completed. (Totals are being replaced with averages in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/262070).) This chart uses the global page filters for displaying data based on the selected group, projects, and timeframe. In addition, specific stages can be selected from within the chart itself. +The chart data is limited to the last 500 items. + ### Disabling chart This chart is enabled by default. If you have a self-managed instance, an @@ -377,7 +379,7 @@ The current permissions on the Project Value Stream Analytics dashboard are: You can [read more about permissions](../../user/permissions.md) in general. -For Value Stream Analytics functionality introduced in GitLab 12.3 and later, +For Value Stream Analytics functionality introduced in GitLab 12.3 and later, users must have Reporter access or above. ## More resources diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 145422f8736..57c5f8bc1fa 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -8,9 +8,10 @@ type: reference, howto # Web API Fuzz Testing **(ULTIMATE)** You can add web API fuzzing to your [GitLab CI/CD](../../../ci/README.md) -pipelines. This helps you discover bugs and potential security issues that other QA processes may miss. -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 backend. +pipelines. This helps you discover bugs and potential security issues that other QA processes may +miss. 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 +backend. We recommend that you use fuzz testing in addition to [GitLab Secure](../index.md)'s other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/README.md), @@ -23,7 +24,10 @@ you can run fuzz tests as part your CI/CD workflow. - SOAP - GraphQL - Form bodies, JSON, or XML -- An OpenAPI definition, or HTTP Archive (HAR) of requests to test +- One of the following assets to provide APIs to test: + - OpenAPI v2 API definition + - HTTP Archive (HAR) of API requests to test + - Postman Collection v2.0 or v2.1 ## When fuzzing scans run @@ -48,15 +52,17 @@ changes, other pipelines, or other scanners) during a scan could cause inaccurat ## Configuration -There are two ways to perform scans. See the configuration section for the one you wish to use: +There are three ways to perform scans. See the configuration section for the one you wish to use: - [OpenAPI v2 specification](#openapi-specification) - [HTTP Archive (HAR)](#http-archive-har) +- [Postman Collection v2.0 or v2.1](#postman-collection) Examples of both configurations can be found here: - [Example OpenAPI v2 specification project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/openapi) - [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/har) +- [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/postman-api-fuzzing-example) ### OpenAPI Specification @@ -133,7 +139,7 @@ This is a minimal configuration for API Fuzzing. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -DANGER: **Danger:** +DANGER: **Warning:** **NEVER** run fuzz testing against a production server. Not only can it perform *any* function that the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run fuzzing against a test server. @@ -224,7 +230,98 @@ This is a minimal configuration for API Fuzzing. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -DANGER: **Danger:** +DANGER: **Warning:** +**NEVER** run fuzz testing against a production server. Not only can it perform *any* function that +the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting +data. Only run fuzzing against a test server. + +### Postman Collection + +The [Postman API Client](https://www.postman.com/product/api-client/) is a popular tool that +developers and testers use to call various types of APIs. The API definitions +[can be exported as a Postman Collection file](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-postman-data) +for use with API Fuzzing. When exporting, make sure to select a supported version of Postman +Collection: v2.0 or v2.1. + +When used with GitLab's API fuzzer, Postman Collections must contain definitions of the web API to +test with valid data. The API fuzzer extracts all the API definitions and uses them to perform +testing. + +DANGER: **Warning:** +Postman Collection files may contain sensitive information such as authentication tokens, API keys, +and session cookies. We recommend that you review the Postman Collection file contents before adding +them to a repository. + +Follow these steps to configure API fuzzing to use a Postman Collection file that provides +information about the target API to test: + +1. To use API fuzzing, you must [include](../../../ci/yaml/README.md#includetemplate) + the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) + that's provided as part of your GitLab installation. To do so, add the following to your + `.gitlab-ci.yml` file: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + ``` + +1. Add the configuration file [`gitlab-api-fuzzing-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing/-/blob/master/gitlab-api-fuzzing-config.yml) + to your repository's root as `.gitlab-api-fuzzing.yml`. + +1. The [configuration file](#configuration-files) has several testing profiles defined with varying + amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this + profile completes quickly, allowing for easier configuration validation. + + Provide the profile by adding the `FUZZAPI_PROFILE` variable to your `.gitlab-ci.yml` file, + substituting `Quick-10` for the profile you choose: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + ``` + +1. Add the `FUZZAPI_POSTMAN_COLLECTION` variable and set it to the Postman Collection's location: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json + ``` + +1. The target API instance's base URL is also required. Provide it by using the `FUZZAPI_TARGET_URL` + variable or an `environment_url.txt` file. + + Adding the URL in an `environment_url.txt` file at your project's root is great for testing in + dynamic environments. To run API fuzzing against an app dynamically created during a GitLab CI/CD + pipeline, have the app persist its domain in an `environment_url.txt` file. API fuzzing + automatically parses that file to find its scan target. You can see an + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + + Here's an example of using `FUZZAPI_TARGET_URL`: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json + FUZZAPI_TARGET_URL: http://test-deployment/ + ``` + +This is a minimal configuration for API Fuzzing. From here you can: + +- [Run your first scan](#running-your-first-scan). +- [Add authentication](#authentication). +- Learn how to [handle false positives](#handling-false-positives). + +DANGER: **Warning:** **NEVER** run fuzz testing against a production server. Not only can it perform *any* function that the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run fuzzing against a test server. @@ -398,6 +495,7 @@ increases as the numbers go up. To use a configuration file, add it to your repo | `FUZZAPI_REPORT` |Scan report filename. Defaults to `gl-api_fuzzing-report.xml`. | |[`FUZZAPI_OPENAPI`](#openapi-specification)|OpenAPI specification file or URL. | |[`FUZZAPI_HAR`](#http-archive-har)|HTTP Archive (HAR) file. | +|[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection)|Postman Collection file. | |[`FUZZAPI_OVERRIDES_FILE`](#overrides) |Path to a JSON file containing overrides. | |[`FUZZAPI_OVERRIDES_ENV`](#overrides) |JSON string containing headers to override. | |[`FUZZAPI_OVERRIDES_CMD`](#overrides) |Overrides command. | @@ -540,6 +638,86 @@ variables: FUZZAPI_OVERRIDES_INTERVAL: 300 ``` +### Header Fuzzing + +Header fuzzing is disabled by default due to the high number of false positives that occur with many +technology stacks. When header fuzzing is enabled, you must specify a list of headers to include in +fuzzing. + +Each profile in the default configuration file has an entry for `GeneralFuzzingCheck`. This check +performs header fuzzing. Under the `Configuration` section, you must change the `HeaderFuzzing` and +`Headers` settings to enable header fuzzing. + +This snippet shows the `Quick-10` profile's default configuration with header fuzzing disabled: + +```yaml +- Name: Quick-10 + DefaultProfile: Empty + Routes: + - Route: *Route0 + Checks: + - Name: FormBodyFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: false + Headers: + - Name: JsonFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: XmlFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true +``` + +`HeaderFuzzing` is a boolean that turns header fuzzing on and off. The default setting is `false` +for off. To turn header fuzzing on, change this setting to `true`: + +```yaml + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: true + Headers: +``` + +`Headers` is a list of headers to fuzz. Only headers listed are fuzzed. For example, to fuzz a +custom header `X-Custom` used by your APIs, add an entry for it using the syntax +`- Name: HeaderName`, substituting `HeaderName` with the header to fuzz: + +```yaml + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: true + Headers: + - Name: X-Custom +``` + +You now have a configuration to fuzz the header `X-Custom`. Use the same notation to list additional +headers: + +```yaml + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: true + Headers: + - Name: X-Custom + - Name: X-AnotherHeader +``` + +Repeat this configuration for each profile as needed. + ## Running your first scan When configured correctly, a CI/CD pipeline contains a `Fuzz` stage and a `apifuzzer_fuzz` job. The diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 9e7f98dd4fc..eef15a9c424 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Defend +stage: Protect group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -76,6 +76,7 @@ How you enable container scanning depends on your GitLab version: that comes with your GitLab installation. - GitLab versions earlier than 11.9: Copy and use the job from the [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). +- GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the `CS_MAJOR_VERSION` from `2` to `3`. To include the `Container-Scanning.gitlab-ci.yml` template (GitLab 11.9 and later), add the following to your `.gitlab-ci.yml` file: @@ -144,6 +145,26 @@ variables: CLAIR_OUTPUT: High ``` +Version `3` of the `container_scanning` Docker image uses [`centos:centos8`](https://hub.docker.com/_/centos) +as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77) +script and instead executes the analyzer by default. Any customizations made to the +`container_scanning` job's [`before_script`](../../../ci/yaml/README.md#before_script) +and [`after_script`](../../../ci/yaml/README.md#after_script) +blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based +Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-variables) +variable. + +This example [includes](../../../ci/yaml/README.md#include) the container scanning template and +enables version `2` of the analyzer: + +```yaml +include: + - template: Container-Scanning.gitlab-ci.yml + +variables: + CS_MAJOR_VERSION: '2' +``` + <!-- NOTE: The container scanning tool references the following heading in the code, so if you" make a change to this heading, make sure to update the documentation URLs used in the" container scanning tool (https://gitlab.com/gitlab-org/security-products/analyzers/klar)" --> @@ -164,6 +185,8 @@ scanning by using the following environment variables: | `CLAIR_VULNERABILITIES_DB_URL` | `clair-vulnerabilities-db` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) is running on and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool) section. | | `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | | `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | +| `CS_MAJOR_VERSION` | `3` | The major version of the Docker image tag. | +| `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | | `DOCKER_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | | `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | | `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | @@ -415,11 +438,11 @@ automatically generates. To enable remediation support, the scanning tool _must_ have access to the `Dockerfile` specified by the [`DOCKERFILE_PATH`](#available-variables) environment variable. To ensure that the scanning tool has access to this -file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/yaml/README.md#git-strategy) in +file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/runners/README.md#git-strategy) in your `.gitlab-ci.yml` file by following the instructions described in this document's [overriding the container scanning template](#overriding-the-container-scanning-template) section. -Read more about the [solutions for vulnerabilities](../index.md#solutions-for-vulnerabilities-auto-remediation). +Read more about the [solutions for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities). ## Troubleshooting diff --git a/doc/user/application_security/coverage_fuzzing/img/coverage_fuzzing_report_v13_6.png b/doc/user/application_security/coverage_fuzzing/img/coverage_fuzzing_report_v13_6.png Binary files differnew file mode 100644 index 00000000000..bed3ca4c9df --- /dev/null +++ b/doc/user/application_security/coverage_fuzzing/img/coverage_fuzzing_report_v13_6.png diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 9508407ccae..4c5afcee3d0 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -30,6 +30,7 @@ Docker image with the fuzz engine to run your app. | Swift | [libfuzzer](https://github.com/apple/swift/blob/master/docs/libFuzzerIntegration.md) | [swift-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/swift-fuzzing-example) | | Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | [rust-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/rust-fuzzing-example) | | Java | [JQF](https://github.com/rohanpadhye/JQF) | [java-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | +| Java | [javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | ## Configuration @@ -221,6 +222,34 @@ This essentially creates two steps: The `covfuzz-ci.yml` is the same as that in the [original synchronous example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example#running-go-fuzz-from-ci). +## Interacting with the vulnerabilities + +After a vulnerability is found, you can [interact with it](../index.md#interacting-with-the-vulnerabilities). +The merge request widget lists the vulnerability and contains a button for downloading the fuzzing +artifacts. By clicking one of the detected vulnerabilities, you can see its details. + + + +You can also view the vulnerability from the [Security Dashboard](../security_dashboard/index.md), +which shows an overview of all the security vulnerabilities in your groups, projects, and pipelines. + +Clicking the vulnerability opens a modal that provides additional information about the +vulnerability: + +- Status: The vulnerability's status. As with any type of vulnerability, a coverage fuzzing + vulnerability can be Detected, Confirmed, Dismissed, or Resolved. +- Project: The project in which the vulnerability exists. +- Crash type: The type of crash or weakness in the code. This typically maps to a [CWE](https://cwe.mitre.org/). +- Crash state: A normalized version of the stacktrace, containing the last three functions of the + crash (without random addresses). +- Stacktrace snippet: The last few lines of the stacktrace, which shows details about the crash. +- Identifier: The vulnerability's identifier. This maps to either a [CVE](https://cve.mitre.org/) + or [CWE](https://cwe.mitre.org/). +- Severity: The vulnerability's severity. This can be Critical, High, Medium, Low, Info, or Unknown. +- Scanner: The scanner that detected the vulnerability (for example, Coverage Fuzzing). +- Scanner Provider: The engine that did the scan. For Coverage Fuzzing, this can be any of the + engines listed in [Supported fuzzing engines and languages](#supported-fuzzing-engines-and-languages). + ### Glossary - Seed corpus: The set of test cases given as initial input to the fuzz target. This usually speeds diff --git a/doc/user/application_security/dast/img/dast_on_demand_v13_2.png b/doc/user/application_security/dast/img/dast_on_demand_v13_2.png Binary files differdeleted file mode 100644 index 045221d713c..00000000000 --- a/doc/user/application_security/dast/img/dast_on_demand_v13_2.png +++ /dev/null diff --git a/doc/user/application_security/dast/img/dast_single_v13_0.png b/doc/user/application_security/dast/img/dast_single_v13_0.png Binary files differindex 91ed4d916ab..1d528fa0ace 100644 --- a/doc/user/application_security/dast/img/dast_single_v13_0.png +++ b/doc/user/application_security/dast/img/dast_single_v13_0.png diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index fffaf4ad26b..2f1ed2faf90 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -161,6 +161,12 @@ headers whose values you want masked. For details on how to mask headers, see It's also possible to authenticate the user before performing the DAST checks. +**Important:** It is highly recommended that you configure the scanner to authenticate to the application, +or it will not be able to check most of the application for security risks, as most +of your application is likely not accessible without authentication. It is also recommended +that you periodically confirm the scanner's authentication is still working as this tends to break over +time due to authentication changes to the application. + Create masked variables to pass the credentials that DAST uses. To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). Note that the key of the username variable must be `DAST_USERNAME` @@ -185,7 +191,7 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. -DANGER: **Danger:** +DANGER: **Warning:** **NEVER** run an authenticated scan against a production server. When an authenticated scan is run, it may perform *any* function that the authenticated user can. This includes actions like modifying and deleting data, submitting forms, and following links. @@ -423,7 +429,51 @@ A URL scan allows you to specify which parts of a website are scanned by DAST. #### Define the URLs to scan -To specify the paths to scan, add a comma-separated list of the paths to the `DAST_PATHS` +URLs to scan can be specified by either of the following methods: + +- Use `DAST_PATHS_FILE` environment variable to specify the name of a file containing the paths. +- Use `DAST_PATHS` environment variable to list the paths. + +##### Use DAST_PATHS_FILE environment variable + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. + +To define the URLs to scan in a file, create a plain text file with one path per line. + +```txt +page1.html +/page2.html +category/shoes/page1.html +``` + +To scan the URLs in that file, set the environment variable `DAST_PATHS_FILE` to the path of that file. + +```yaml +include: + - template: DAST.gitlab-ci.yml + +variables: + DAST_PATHS_FILE: url_file.txt +``` + +By default, DAST scans do not clone the project repository. If the file is checked in to the project, instruct the DAST job to clone the project by setting GIT_STRATEGY to fetch. The file is expected to be in the `/zap/wrk` directory. + +```yaml +dast: + script: + - mkdir -p /zap/wrk + - cp url_file.txt /zap/wrk/url_file.txt + - /analyze -t $DAST_WEBSITE + variables: + GIT_STRATEGY: fetch + DAST_PATHS_FILE: url_file.txt +``` + +##### Use DAST_PATHS environment variable + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. + +To specify the paths to scan in an environment variable, add a comma-separated list of the paths to the `DAST_PATHS` environment variable. Note that you can only scan paths of a single host. ```yaml @@ -434,10 +484,13 @@ variables: DAST_PATHS=/page1.html,/category1/page1.html,/page3.html ``` -When using `DAST_PATHS`, note the following: +When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: +- `DAST_WEBSITE` must be defined when using either `DAST_PATHS_FILE` or `DAST_PATHS`. The paths listed in either will use `DAST_WEBSITE` to build the URLs to scan +- Spidering is disabed when `DAST_PATHS` or `DAST_PATHS_FILE` are defined +- `DAST_PATHS_FILE` and `DAST_PATHS` can not be used together - The `DAST_PATHS` environment variable has a limit of about 130kb. If you have a list or paths - greater than this, you should create multiple DAST jobs and split the paths over each job. + greater than this, use `DAST_PATHS_FILE`. #### Full Scan @@ -476,6 +529,7 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | | `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | | `DAST_API_SPECIFICATION` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` will be reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | | `DAST_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | | `DAST_USERNAME` | string | The username to authenticate to in the website. | | `DAST_PASSWORD` | string | The password to authenticate to in the website. | @@ -489,15 +543,16 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | | `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | | `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | -| `DAST_DEBUG` | boolean | Enable debug message output. Default: `false` | -| `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. | -| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. | -| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. | -| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. | -| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false` | -| `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false` | -| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html` | -| `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. | +| `DAST_DEBUG` | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1.| +| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | +| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line and be within `/zap/wrk`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | ### DAST command-line options @@ -548,7 +603,7 @@ variables: ### Cloning the project's repository The DAST job does not require the project's repository to be present when running, so by default -[`GIT_STRATEGY`](../../../ci/yaml/README.md#git-strategy) is set to `none`. +[`GIT_STRATEGY`](../../../ci/runners/README.md#git-strategy) is set to `none`. ### Debugging DAST jobs @@ -713,10 +768,6 @@ To delete a scanner profile: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.3. -> - It's deployed behind a feature flag, enabled by default. -> - It's enabled on GitLab.com. -> - It's able to be enabled or disabled per-project. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-on-demand-scans). An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger the scan. You must start it manually. @@ -747,35 +798,6 @@ To run an on-demand DAST scan, you need: The on-demand DAST scan runs and the project's dashboard shows the results. -### Enable or disable On-demand Scans - -The On-demand DAST Scans feature is enabled by default. You can disable on-demand scans -instance-wide, or disable it for specific projects if you prefer. - -To run on-demand DAST scans, an administrator must enable the -`security_on_demand_scans_feature_flag` feature flag. - -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable or enable the feature flags. - -To disable On-demand DAST Scans: - -```ruby -# Instance-wide -Feature.disable(:security_on_demand_scans_feature_flag) -# or by project -Feature.disable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) -``` - -To enable On-demand DAST Scans: - -```ruby -# Instance-wide -Feature.enable(:security_on_demand_scans_feature_flag) -# or by project -Feature.enable(:security_on_demand_scans_feature_flag, Project.find(<project ID>)) -``` - ## Reports The DAST tool outputs a report file in JSON format by default. However, this tool can also generate reports in diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v12_3.png b/doc/user/application_security/dependency_list/img/dependency_list_v12_3.png Binary files differdeleted file mode 100644 index 8eeadb34504..00000000000 --- a/doc/user/application_security/dependency_list/img/dependency_list_v12_3.png +++ /dev/null diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v12_4.png b/doc/user/application_security/dependency_list/img/dependency_list_v12_4.png Binary files differdeleted file mode 100644 index 4687987b763..00000000000 --- a/doc/user/application_security/dependency_list/img/dependency_list_v12_4.png +++ /dev/null diff --git a/doc/user/application_security/dependency_list/img/yarn_dependency_path_v13_6.png b/doc/user/application_security/dependency_list/img/yarn_dependency_path_v13_6.png Binary files differnew file mode 100644 index 00000000000..78e324f43c4 --- /dev/null +++ b/doc/user/application_security/dependency_list/img/yarn_dependency_path_v13_6.png diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 1f730e5f205..ddd059707d4 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -32,7 +32,7 @@ Dependencies are displayed with the following information: | --------- | ----------- | | Component | The dependency's name and version | | Packager | The packager used to install the dependency | -| Location | A link to the packager-specific lock file in your project that declared the dependency | +| Location | 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. | | License | Links to dependency's software licenses | Dependencies shown are initially sorted by the severity of their known vulnerabilities, if any. They @@ -44,6 +44,18 @@ If a dependency has known vulnerabilities, you can view them by clicking the arr dependency's name or the badge that indicates how many known vulnerabilities exist. For each vulnerability, its severity and description then appears below it. +### Dependency Paths + +The dependency list shows the path between a dependency and a top-level dependency it's connected +to, if any. There are many possible paths connecting a transient dependency to top-level +dependencies, but the UI only shows one of the shortest paths. + + + +Dependency Paths are supported for the following package managers: + +- [NuGet](https://www.nuget.org/) + ## Licenses > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab Ultimate 12.3. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index b90bb37c60f..1b164c9cecd 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -53,7 +53,7 @@ is **not** `19.03.0`. See [troubleshooting information](#error-response-from-dae ## Supported languages and package managers GitLab relies on [`rules`](../../../ci/yaml/README.md#rules) to start relevant analyzers depending on the languages detected in the repository. -The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile` or `api/Gemfile` file, but not if the only supported dependency file is `api/client/Gemfile`. +The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile` or `api/Gemfile` file, but not if the only supported dependency file is `api/client/Gemfile`. The following languages and dependency managers are supported: @@ -71,11 +71,11 @@ The following languages and dependency managers are supported: Plans are underway for supporting the following languages, dependency managers, and dependency files. For details, see the issue link for each. -| Package Managers | Languages | Supported files | Scan tools | -| ------------------- | --------- | --------------- | ------------ | +| Package Managers | Languages | Supported files | Scan tools | Issue | +| ------------------- | --------- | --------------- | ---------- | ----- | | [Pipenv](https://pipenv.pypa.io/en/latest/) | Python | `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#11756](https://gitlab.com/gitlab-org/gitlab/-/issues/11756) | | [Poetry](https://python-poetry.org/) | Python | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/-/issues/7006) | -| [sbt](https://www.scala-sbt.org/) 1.3+ ([Coursier](https://get-coursier.io/))| Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#249526](https://gitlab.com/gitlab-org/gitlab/-/issues/249526) | +| [sbt](https://www.scala-sbt.org/) 1.3+ ([Coursier](https://get-coursier.io/))| Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#271345](https://gitlab.com/gitlab-org/gitlab/-/issues/271345) | ## Contribute your scanner @@ -201,7 +201,7 @@ Once a vulnerability is found, you can interact with it. Read more on how to Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. Read more about the -[solutions for vulnerabilities](../index.md#solutions-for-vulnerabilities-auto-remediation). +[solutions for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities). ## Security Dashboard @@ -356,9 +356,11 @@ Here are the requirements for using dependency scanning in an offline environmen - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). - Docker Container Registry with locally available copies of dependency scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. -- Host an offline Git copy of the [gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/). - This is required because, in an offline environment, the Gemnasium analyzer can't fetch the latest - advisories from the online repository. +- If you have a limited access environment you will need to allow access, such as using a proxy, to the advisory database: `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git`. + If you are unable to permit access to `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` you must host an offline copy of this `git` repository and set the `GEMNASIUM_DB_REMOTE_URL` variable to the URL of this repository. For more information on configuration variables, see [Dependency Scanning](#configuring-dependency-scanning). + + This advisory database is constantly being updated, so you will need to periodically sync your local copy with GitLab's. + - _Only if scanning Ruby projects_: Host an offline Git copy of the [advisory database](https://github.com/rubysec/ruby-advisory-db). - _Only if scanning npm/yarn projects_: Host an offline copy of the [retire.js](https://github.com/RetireJS/retire.js/) [node](https://github.com/RetireJS/retire.js/blob/master/repository/npmrepository.json) and [js](https://github.com/RetireJS/retire.js/blob/master/repository/jsrepository.json) advisory databases. diff --git a/doc/user/application_security/img/security_configuration_page_v13_2.png b/doc/user/application_security/img/security_configuration_page_v13_2.png Binary files differdeleted file mode 100644 index 016328948cc..00000000000 --- a/doc/user/application_security/img/security_configuration_page_v13_2.png +++ /dev/null diff --git a/doc/user/application_security/img/security_widget_v13_6.png b/doc/user/application_security/img/security_widget_v13_6.png Binary files differnew file mode 100644 index 00000000000..2dd44909dfe --- /dev/null +++ b/doc/user/application_security/img/security_widget_v13_6.png diff --git a/doc/user/application_security/img/vulnerability_page_merge_request_button_dropdown_v13_1.png b/doc/user/application_security/img/vulnerability_page_merge_request_button_dropdown_v13_1.png Binary files differnew file mode 100644 index 00000000000..05ca74c3d5c --- /dev/null +++ b/doc/user/application_security/img/vulnerability_page_merge_request_button_dropdown_v13_1.png diff --git a/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png b/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png Binary files differnew file mode 100644 index 00000000000..a3034a7db04 --- /dev/null +++ b/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png diff --git a/doc/user/application_security/img/vulnerability_solution.png b/doc/user/application_security/img/vulnerability_solution.png Binary files differdeleted file mode 100644 index 63e9c1473b6..00000000000 --- a/doc/user/application_security/img/vulnerability_solution.png +++ /dev/null diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 413a9f894e2..30852d1bbcd 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- @@ -18,7 +21,7 @@ For an overview of application security with GitLab, see ## Quick start Get started quickly with Dependency Scanning, License Scanning, Static Application Security -Testing (SAST), and Secret Detection by adding the following to your `.gitlab-ci.yml`: +Testing (SAST), and Secret Detection by adding the following to your [`.gitlab-ci.yml`](../../ci/yaml/README.md): ```yaml include: @@ -67,12 +70,26 @@ GitLab uses the following tools to scan and report known vulnerabilities found i | [Dependency List](dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. | | [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | | [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | -| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | -| [Secret Detection](secret_detection/index.md) **(ULTIMATE)** | Analyze Git history for leaked secrets. | +| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | +| [Secret Detection](secret_detection/index.md) | Analyze Git history for leaked secrets. | | [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)** | View vulnerabilities in all your projects and groups. | | [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. | | [Coverage fuzzing](coverage_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. | +### Use security scanning tools with Pipelines for Merge Requests + +The security scanning tools can all be added to pipelines with [templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Security). +See each tool for details on how to use include each template in your CI/CD configuration. + +By default, the application security jobs are configured to run for branch pipelines only. +To use them with [pipelines for merge requests](../../ci/merge_request_pipelines/index.md), +you may need to override the default `rules:` configuration to add: + +```yaml +rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" +``` + ## Security Scanning with Auto DevOps When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools will be configured using default settings. @@ -93,7 +110,7 @@ The scanning tools and vulnerabilities database are updated regularly. | Secure scanning tool | Vulnerabilities database updates | |:-------------------------------------------------------------|-------------------------------------------| | [Container Scanning](container_scanning/index.md) | Uses `clair`. The latest `clair-db` version is used for each job by running the [`latest` Docker image tag](https://gitlab.com/gitlab-org/gitlab/blob/438a0a56dc0882f22bdd82e700554525f552d91b/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L37). The `clair-db` database [is updated daily according to the author](https://github.com/arminc/clair-local-scan#clair-server-or-local). | -| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for NPM packages), and `gemnasium` (GitLab's own tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | +| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for NPM packages), and `gemnasium` (GitLab's own tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | | [Dynamic Application Security Testing (DAST)](dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/master/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | | [Static Application Security Testing (SAST)](sast/index.md) | Relies exclusively on [the tools GitLab wraps](sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | @@ -106,6 +123,24 @@ latest versions of the scanning tools without having to do anything. There are s with this approach, however, and there is a [plan to resolve them](https://gitlab.com/gitlab-org/gitlab/-/issues/9725). +## Viewing security scan information in merge requests **(CORE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Core 13.5. +> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/273205) in 13.6. +> - It's [deployed behind a feature flag](../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It can be enabled or disabled for a single project. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-the-basic-security-widget). **(CORE ONLY)** + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +Merge requests which have run security scans let you know that the generated +reports are available to download. + + + ## Interacting with the vulnerabilities > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.8. @@ -119,7 +154,7 @@ information with several options: - [Create issue](#creating-an-issue-for-a-vulnerability): Create a new issue with the title and description pre-populated with information from the vulnerability report. By default, such issues are [confidential](../project/issues/confidential_issues.md). -- [Solution](#solutions-for-vulnerabilities-auto-remediation): For some vulnerabilities, +- [Automatic Remediation](#automatic-remediation-for-vulnerabilities): For some vulnerabilities, a solution is provided for how to fix the vulnerability.  @@ -141,21 +176,21 @@ To view details of DAST vulnerabilities: 1. Click on the vulnerability's description. The following details are provided: - | Field | Description | -|:-----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Description | Description of the vulnerability. | -| Project | Namespace and project in which the vulnerability was detected. | -| Method | HTTP method used to detect the vulnerability. | -| URL | URL at which the vulnerability was detected. | -| Request Headers | Headers of the request. | -| Response Status | Response status received from the application. | -| Response Headers | Headers of the response received from the application. | +| Field | Description | +|:-----------------|:------------------------------------------------------------------ | +| Description | Description of the vulnerability. | +| Project | Namespace and project in which the vulnerability was detected. | +| Method | HTTP method used to detect the vulnerability. | +| URL | URL at which the vulnerability was detected. | +| Request Headers | Headers of the request. | +| Response Status | Response status received from the application. | +| Response Headers | Headers of the response received from the application. | | Evidence | Evidence of the data found that verified the vulnerability. Often a snippet of the request or response, this can be used to help verify that the finding is a vulnerability. | -| Identifiers | Identifiers of the vulnerability. | -| Severity | Severity of the vulnerability. | -| Scanner Type | Type of vulnerability report. | -| Links | Links to further details of the detected vulnerability. | -| Solution | Details of a recommended solution to the vulnerability (optional). | +| Identifiers | Identifiers of the vulnerability. | +| Severity | Severity of the vulnerability. | +| Scanner Type | Type of vulnerability report. | +| Links | Links to further details of the detected vulnerability. | +| Solution | Details of a recommended solution to the vulnerability (optional). | #### Hide sensitive information in headers @@ -198,38 +233,60 @@ Pressing the "Dismiss Selected" button will dismiss all the selected vulnerabili  -### Solutions for vulnerabilities (auto-remediation) +### Creating an issue for a vulnerability + +You can create an issue for a vulnerability by visiting the vulnerability's page and clicking +**Create issue**, which you can find in the **Related issues** section. + + + +This creates a [confidential issue](../project/issues/confidential_issues.md) in the project the +vulnerability came from, and pre-populates it with some useful information taken from the vulnerability +report. Once the issue is created, you are redirected to it so you can edit, assign, or comment on +it. + +Upon returning to the group security dashboard, the vulnerability now has an associated issue next +to the name. + + + +### Automatic remediation for vulnerabilities > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. Some vulnerabilities can be fixed by applying the solution that GitLab -automatically generates. The following scanners are supported: +automatically generates. Although the feature name is Automatic Remediation, this feature is also commonly called Auto-Remediation, Auto Remediation, or Suggested Solutions. The following scanners are supported: - [Dependency Scanning](dependency_scanning/index.md): Automatic Patch creation is only available for Node.js projects managed with `yarn`. - [Container Scanning](container_scanning/index.md) +When an automatic solution is available, the button in the header shows **Resolve with merge request**: + + + +Selecting the button creates a merge request with the solution. + #### Manually applying the suggested patch -Some vulnerabilities can be fixed by applying a patch that is automatically -generated by GitLab. To apply the fix: +To manually apply the patch that GitLab generated for a vulnerability: + +1. Select the **Resolve with merge request** dropdown, then select **Download patch to resolve**: + +  -1. Click the vulnerability. -1. Download and review the patch file `remediation.patch`. 1. Ensure your local project has the same commit checked out that was used to generate the patch. 1. Run `git apply remediation.patch`. 1. Verify and commit the changes to your branch. - - #### Creating a merge request from a vulnerability > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9224) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. In certain cases, GitLab allows you to create a merge request that automatically remediates the vulnerability. Any vulnerability that has a -[solution](#solutions-for-vulnerabilities-auto-remediation) can have a merge +[solution](#automatic-remediation-for-vulnerabilities) can have a merge request created to automatically solve the issue. If this action is available, the vulnerability page or modal contains a **Create merge request** button. @@ -237,25 +294,6 @@ Click this button to create a merge request to apply the solution onto the sourc  -### Creating an issue for a vulnerability - -You can create an issue for a vulnerability by visiting the vulnerability's page and clicking -**Create issue**, which you can find in the **Related issues** section. - - - -This creates a [confidential issue](../project/issues/confidential_issues.md) in the project the -vulnerability came from, and pre-populates it with some useful information taken from the vulnerability -report. Once the issue is created, you are redirected to it so you can edit, assign, or comment on -it. CVE identifiers can be requested from GitLab by clicking the -[_CVE ID Request_ button](cve_id_request.md) that is enabled for maintainers of -public projects on GitLab.com - -Upon returning to the group security dashboard, the vulnerability now has an associated issue next -to the name. - - - ### Managing related issues for a vulnerability Issues can be linked to a vulnerability using the related issues block on the vulnerability page. @@ -320,7 +358,7 @@ appears:  -If at least one security scanner is enabled, you will be able to enable the `Vulnerability-Check` approval rule. If a license scanning job is enabled, you will be able to enable the `License-Check` rule. +If at least one security scanner is enabled, you can enable the `Vulnerability-Check` approval rule. If a license scanning job is enabled, you can enable the `License-Check` rule.  @@ -566,3 +604,36 @@ Additionally, we provide a dedicated project containing the versioned legacy tem This can be useful for offline setups or anyone wishing to use [Auto DevOps](../../topics/autodevops/index.md). Instructions are available in the [legacy template project](https://gitlab.com/gitlab-org/auto-devops-v12-10). + +#### Vulnerabilities are found, but the job succeeds. How can I have a pipeline fail instead? + +This is the current default behavior, because the job's status indicates success or failure of the analyzer itself. +Analyzer results are displayed in the [job logs](../../ci/jobs/index.md#expand-and-collapse-job-log-sections), +[Merge Request widget](sast/index.md) +or [Security Dashboard](security_dashboard/index.md). +There is [an open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/235772) in which changes to this behavior are being discussed. + +### Enable or disable the basic security widget **(CORE ONLY)** + +The basic security widget is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +# For the instance +Feature.enable(:core_security_mr_widget) +# For a single project +Feature.enable(:core_security_mr_widget, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:core_security_mr_widget) +# For a single project +Feature.disable(:core_security_mr_widget, Project.find(<project id>)) +``` diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 3a7c0148388..35582aa20ed 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -66,8 +66,7 @@ external links exposed in the UI. These links might not be accessible within an ### Automatic remediation for vulnerabilities -The [automatic remediation for vulnerabilities](../index.md#solutions-for-vulnerabilities-auto-remediation) feature -(auto-remediation) is available for offline Dependency Scanning and Container Scanning, but may not work +The [automatic remediation for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities) feature is available for offline Dependency Scanning and Container Scanning, but may not work depending on your instance's configuration. We can only suggest solutions, which are generally more current versions that have been patched, when we are able to access up-to-date registry services hosting the latest versions of that dependency or image. @@ -214,3 +213,28 @@ do ssh $GITLAB_HOST "sudo docker push ${registry}/analyzers/${i}:2" done ``` + +### Using GitLab Secure with AutoDevOps in an offline environment + +You can use GitLab AutoDevOps for Secure scans in an offline environment. However, you must first do +these steps: + +1. Load the container images into the local registry. GitLab Secure leverages analyzer container + images to do the various scans. These images must be available as part of running AutoDevOps. + Before running AutoDevOps, follow the [above steps](#using-the-official-gitlab-template) + to load those container images into the local container registry. + +1. Set the pipeline variable to ensure that AutoDevOps looks in the right place for those images. + The AutoDevOps templates leverage the `SECURE_ANALYZERS_PREFIX` variable to identify the location + of analyzer images. This variable is discussed above in [Using the secure bundle created](#using-the-secure-bundle-created). + Ensure that you set this variable to the correct value for where you loaded the analyzer images. + You could consider doing this with a pipeline variable or by [modifying](../../../topics/autodevops/customize.md#customizing-gitlab-ciyml) + the `.gitlab-ci.yml` file directly. + +Once these steps are complete, GitLab has local copies of the Secure analyzers and is set up to use +them instead of an Internet-hosted container image. This allows you to run Secure in AutoDevOps in +an offline environment. + +Note that these steps are specific to GitLab Secure with AutoDevOps. Using other stages with +AutoDevOps may require other steps covered in the +[Auto DevOps documentation](../../../topics/autodevops/). diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 6167c0445f9..4cbd4496dea 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -4,7 +4,10 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# SAST Analyzers **(ULTIMATE)** +# SAST Analyzers **(CORE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. +> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to GitLab Core in 13.3. SAST relies on underlying third party tools that are wrapped into what we call "Analyzers". An analyzer is a @@ -33,7 +36,7 @@ SAST supports the following official analyzers: - [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) (Sobelow (Elixir Phoenix)) - [`spotbugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) (SpotBugs with the Find Sec Bugs plugin (Ant, Gradle and wrapper, Grails, Maven and wrapper, SBT)) -The analyzers are published as Docker images that SAST will use to launch +The analyzers are published as Docker images that SAST uses to launch dedicated containers for each analysis. SAST is pre-configured with a set of **default images** that are maintained by @@ -77,12 +80,12 @@ variables: SAST_DEFAULT_ANALYZERS: "bandit,flawfinder" ``` -`bandit` runs first. When merging the reports, SAST will -remove the duplicates and will keep the `bandit` entries. +`bandit` runs first. When merging the reports, SAST +removes the duplicates and keeps the `bandit` entries. ### Disabling default analyzers -Setting `SAST_DEFAULT_ANALYZERS` to an empty string will disable all the official +Setting `SAST_DEFAULT_ANALYZERS` to an empty string disables all the official default analyzers. In `.gitlab-ci.yml` define: ```yaml @@ -121,7 +124,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) | Property / Tool | Apex | Bandit | Brakeman | ESLint security | SpotBugs | Flawfinder | Gosec | Kubesec Scanner | MobSF | NodeJsScan | PHP CS Security Audit | Security code Scan (.NET) | Sobelow | | --------------------------------------- | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :---------------------: | :-------------------------: | :----------------: | -| Severity | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | +| Severity | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | | Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Description | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | | File | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -129,11 +132,11 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) | End line | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Start column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | | End column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| External ID (e.g. CVE) | 𐄂 | 𐄂 | ⚠ | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| External ID (for example, CVE) | 𐄂 | 𐄂 | ⚠ | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | URLs | ✓ | 𐄂 | ✓ | 𐄂 | ⚠ | 𐄂 | ⚠ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Internal doc/explanation | ✓ | ⚠ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | | Solution | ✓ | 𐄂 | 𐄂 | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Affected item (e.g. class or package) | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| Affected item (for example, class or package) | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Confidence | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | x | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | | Source code extract | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | @@ -143,4 +146,4 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) - 𐄂 => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it. The values provided by these tools are heterogeneous so they are sometimes -normalized into common values (e.g., `severity`, `confidence`, etc). +normalized into common values (for example, `severity`, `confidence`, and so on). diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 9e4d4112ae8..49e194a9319 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -32,8 +32,8 @@ The results are sorted by the priority of the vulnerability: 1. Everything else A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish -for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST -job finishes but the DAST job fails, the security dashboard doesn't show SAST results. On failure, +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 @@ -71,9 +71,9 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | | Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.1 | | Go | [Gosec](https://github.com/securego/gosec) | 10.7 | -| Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | +| Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | | Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1 | -| Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | +| Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | | Java (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | | JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8 | | Kotlin (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | @@ -84,7 +84,7 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | | React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 | | Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | -| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | +| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | | Swift (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | | TypeScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | @@ -107,10 +107,11 @@ as shown in the following table: | [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | | View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | -| [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | +| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | | [Interaction with Vulnerabilities](#interacting-with-the-vulnerabilities) | **{dotted-circle}** | **{check-circle}** | | [Access to Security Dashboard](#security-dashboard) | **{dotted-circle}** | **{check-circle}** | | [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | +| [Customize SAST Rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -162,7 +163,7 @@ page: 1. Enter the custom SAST values. Custom values are stored in the `.gitlab-ci.yml` file. For variables not in the SAST Configuration page, their values are left unchanged. Default values are inherited from the GitLab SAST template. -1. Optionally, expand the **SAST analyzers** section, select individual [SAST analyzers](./analyzers.md) and enter custom analyzer values. +1. Optionally, expand the **SAST analyzers** section, select individual [SAST analyzers](analyzers.md) and enter custom analyzer values. 1. Click **Create Merge Request**. 1. Review and merge the merge request. @@ -205,15 +206,21 @@ spotbugs-sast: FAIL_NEVER: 1 ``` -### Custom rulesets +### Customize rulesets **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. -You can customize the default scanning rules provided with SAST's NodeJS-Scan and Gosec analyzers. -Customization allows you to exclude rules and modify the behavior of existing rules. +You can customize the default scanning rules provided by our SAST analyzers. + +Ruleset customization supports two capabilities: + +1. Disabling predefined rules +1. Modifying the default behavior of a given analyzer + +These capabilities can be used simultaneously. To customize the default scanning rules, create a file containing custom rules. These rules -are passed through to the analyzer's underlying scanner tool. +are passed through to the analyzer's underlying scanner tools. To create a custom ruleset: @@ -221,6 +228,25 @@ To create a custom ruleset: 1. Create a custom ruleset file named `sast-ruleset.toml` in the `.gitlab` directory. 1. In the `sast-ruleset.toml` file, do one of the following: + - Disable predefined rules belonging to SAST analyzers. In this example, the disabled rules + belong to `eslint` and `sobelow` and have the corresponding identifiers `type` and `value`: + + ```toml + [eslint] + [[eslint.ruleset]] + disable = true + [eslint.ruleset.identifier] + type = "eslint_rule_id" + value = "security/detect-object-injection" + + [sobelow] + [[sobelow.ruleset]] + disable = true + [sobelow.ruleset.identifier] + type = "sobelow_rule_id" + value = "sql_injection" + ``` + - Define a custom analyzer configuration. In this example, customized rules are defined for the `nodejs-scan` scanner: @@ -285,7 +311,7 @@ you can use the `MAVEN_CLI_OPTS` environment variable. Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos). -#### Enabling Kubesec analyzer +### Enabling Kubesec analyzer > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12752) in GitLab Ultimate 12.6. @@ -300,7 +326,7 @@ variables: SCAN_KUBERNETES_MANIFESTS: "true" ``` -#### Pre-compilation +### Pre-compilation If your project requires custom build configurations, it can be preferable to avoid compilation during your SAST execution and instead pass all job artifacts from an @@ -398,7 +424,7 @@ Some analyzers can be customized with environment variables. | Environment variable | Analyzer | Description | |---------------------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests. | -| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` will use to generate a Kubernetes manifest that `kubesec` will scan. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | +| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` uses to generate a Kubernetes manifest that `kubesec` will scan. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | | `KUBESEC_HELM_OPTIONS` | Kubesec | Additional arguments for the `helm` executable. | | `COMPILE` | SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) in GitLab 13.1. | | `ANT_HOME` | SpotBugs | The `ANT_HOME` environment variable. | @@ -426,7 +452,7 @@ to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. CAUTION: **Caution:** -Variables having names starting with these prefixes will **not** be propagated to the SAST Docker container and/or +Variables having names starting with these prefixes are **not** propagated to the SAST Docker container and/or analyzer containers: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, `OLDPWD`, `PATH`, `SHLVL`, `HOSTNAME`. ### Experimental features @@ -642,7 +668,7 @@ security reports without requiring internet access. ### Configure certificate checking of packages If a SAST job invokes a package manager, you must configure its certificate verification. In an -offline environment, certificate verification with an external source isn't possible. Either use a +offline environment, certificate verification with an external source is not possible. Either use a self-signed certificate or disable certificate verification. Refer to the package manager's documentation for instructions. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index bb10e9d7315..025a37f684d 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -5,9 +5,10 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Secret Detection **(ULTIMATE)** +# Secret Detection -> [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. +> - [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. +> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) in 13.3. A recurring problem when developing applications is that developers may unintentionally commit secrets and credentials to their remote repositories. If other people have access to the source, @@ -30,6 +31,29 @@ GitLab displays identified secrets visibly in a few places: - Detecting unintentional commit of secrets like keys, passwords, and API tokens. - Performing a single or recurring scan of the full history of your repository for secrets. +## Supported secrets + +Secret Detection detects a variety of common secrets by default. You can also customize the secret detection patterns using [custom rulesets](#custom-rulesets). + +The [default ruleset provided by Gitleaks](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks/gitleaks.toml) includes the following key types: + +- Cloud services: + - Amazon Web Services (AWS) + - Google Cloud Platform (GCP) +Encryption keys: + - PKCS8 + - RSA + - SSH + - PGP +- Social media platforms: + - Facebook API + - Twitter API +- Cloud SaaS vendors: + - GitHub API + - Slack Token + - Stripe API + - Generic API key strings starting with `api-` + ## Requirements To run Secret Detection jobs, by default, you need GitLab Runner with the @@ -59,7 +83,7 @@ as shown in the following table: | [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | | View [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | -| [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | +| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | | [Interaction with Vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | | [Access to Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | @@ -102,6 +126,18 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. +### Post-processing + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/46390) in GitLab 13.6. + +Upon detection of a secret, GitLab supports post processing hooks. These can be used to take actions like notifying the cloud service who issued the secret. The cloud provider can confirm the credentials and take remediation actions like revoking or reissuing a new secret and notifying the creator of the secret. Post-processing workflows vary by supported cloud providers. + +GitLab currently supports post-processing for following service providers: + +- Amazon Web Services (AWS) + +Third party cloud and SaaS providers can [express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). Learn more about the [technical details of post-processing secrets](https://gitlab.com/groups/gitlab-org/-/epics/4639). + ### Customizing settings The Secret Detection scan settings can be changed through [environment variables](#available-variables) @@ -142,7 +178,7 @@ Secret Detection can be customized by defining available variables: | `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | | `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | -### Custom rulesets +### Custom rulesets **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png Binary files differdeleted file mode 100644 index 8fab4e39175..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png Binary files differnew file mode 100644 index 00000000000..6ccae80e80e --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_export_csv_v12_10.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_export_csv_v12_10.png Binary files differdeleted file mode 100644 index 07b41b471d4..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_export_csv_v12_10.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 5fa8ebb80e0..1b038ef76a0 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -9,15 +9,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab provides a comprehensive set of features for viewing and managing vulnerabilities: -- Security dashboards: An overview of the security status in your instance, groups, and projects. -- Vulnerability reports: Detailed lists of all vulnerabilities for the instance, group, project, or +- Security dashboards: An overview of the security status in your instance, [groups](#group-security-dashboard), and + [projects](#project-security-dashboard). +- [Vulnerability reports](#vulnerability-report): Detailed lists of all vulnerabilities for the instance, group, project, or pipeline. This is where you triage and manage vulnerabilities. -- Security Center: A dedicated area for vulnerability management at the instance level. This +- [Security Center](#instance-security-center): A dedicated area for vulnerability management at the instance level. This includes a security dashboard, vulnerability report, and settings. -You can also drill down into a vulnerability and get extra information. This includes the project it -comes from, any related file(s), and metadata that helps you analyze the risk it poses. You can also -dismiss a vulnerability or create an issue for it. +You can also drill down into a vulnerability and get extra information on the +[Vulnerability Page](../vulnerabilities/index.md). This view includes the project it +comes from, any related file(s), and metadata that helps you analyze the risk it poses. +You can also confirm, dismiss, or resolve a vulnerability, create an issue for it, +and in some cases, generate a merge request to fix the vulnerability. To benefit from these features, you must first configure one of the [security scanners](../index.md). @@ -30,7 +33,7 @@ The vulnerability report displays vulnerabilities detected by scanners such as: - [Dynamic Application Security Testing](../dast/index.md) - [Dependency Scanning](../dependency_scanning/index.md) - [Static Application Security Testing](../sast/index.md) -- And others! +- And [others](../index.md#security-scanning-tools)! ## Requirements @@ -60,43 +63,67 @@ job finishes but the DAST job fails, the security dashboard doesn't show SAST re the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code). +You can filter the vulnerabilities list by selecting from the **Severity** and **Scanner** dropdowns. + ## Project Security Dashboard +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. + +At the project level, the Security Dashboard displays a chart with the number of vulnerabilities over time. +Access it by navigating to **Security & Compliance > Security Dashboard**. Currently, we display historical +data up to 365 days. + + + +Filter the historical data by clicking on the corresponding legend name. The image above, for example, shows +only the graph for vulnerabilities with **high** severity. + +### Vulnerability Report + > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. -At the project level, the Security Dashboard displays the vulnerabilities merged into your project's -[default branch](../../project/repository/branches/index.md#default-branch). Access it by navigating -to **Security & Compliance > Security Dashboard**. By default, the Security Dashboard displays all -detected and confirmed vulnerabilities. +The vulnerabilities that exist in your project's +[default branch](../../project/repository/branches/index.md#default-branch) are accessed by navigating to +**Security & Compliance > Vulnerability Report**. By default, the Vulnerability Report is filtered to +display all detected and confirmed vulnerabilities. -The Security Dashboard first displays the time at which the last pipeline completed on the project's -default branch. There's also a link to view this in more detail. +The Vulnerability Report first displays the time at which the last pipeline completed on the project's +default branch. There's also a link to view this in more detail. In the case of any pipeline failures, +you will see the number of failures clearly indicated. The failure notification takes you directly to +the **Failed jobs** tab of the pipeline page. -The Security Dashboard next displays the total number of vulnerabilities by severity (for example, +The Vulnerability Report next displays the total number of vulnerabilities by severity (for example, Critical, High, Medium, Low, Info, Unknown). Below this, a table shows each vulnerability's status, severity, and description. Clicking a vulnerability takes you to its [Vulnerability Details](../vulnerabilities) page to view more information about that vulnerability. - + You can filter the vulnerabilities by one or more of the following: -- Status -- Severity -- Scanner +| Filter | Available Options | +| --- | --- | +| Status | Detected, Confirmed, Dismissed, Resolved | +| Severity | Critical, High, Medium, Low, Info, Unknown | +| Scanner | [Available Scanners](../index.md#security-scanning-tools) | + +You can filter the vulnerabilities list by selecting from the **Status**, **Severity**, and +**Scanner** dropdowns. In the **Scanner** dropdown, select individual scanners or scanner groups to +toggle those scanners. The **Scanner** dropdown includes both GitLab scanners, and in GitLab 13.6 +and later, custom scanners. You can also dismiss vulnerabilities in the table: 1. Select the checkbox for each vulnerability you want to dismiss. 1. In the menu that appears, select the reason for dismissal and click **Dismiss Selected**. - + ## Group Security Dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. -The group Security Dashboard gives an overview of the vulnerabilities in the default branches of the +The group Security Dashboard gives an overview of the vulnerabilities found in the default branches of the projects in a group and its subgroups. Access it by navigating to **Security > Security Dashboard** after selecting your group. By default, the Security Dashboard displays all detected and confirmed vulnerabilities. If you don't see the vulnerabilities over time graph, the likely cause is that you @@ -111,20 +138,21 @@ enabled in a group. There is a timeline chart that shows how many open vulnerabilities your projects had at various points in time. You can display the vulnerability trends over a 30, 60, or 90-day time frame (the default is 90 days). Hover over the chart to get -more details about the open vulnerabilities at a specific time. +more details about the open vulnerabilities at a specific time. Aggregated data beyond 90 days can be accessed by querying our [VulnerabilitiesCountByDay GraphQL API](../../../api/graphql/reference/index.md#vulnerabilitiescountbyday). This data is retained for 365 days. Next to the timeline chart is a list of projects, grouped and sorted by the severity of the vulnerability found: -- F: One or more "critical" -- D: One or more "high" or "unknown" -- C: One or more "medium" -- B: One or more "low" -- A: Zero vulnerabilities +| Grade | Description | +| F | One or more "critical" | +| D | One or more "high" or "unknown" | +| C | One or more "medium" | +| B | One or more "low" | +| A | Zero vulnerabilities | Projects with no vulnerability tests configured will not appear in the list. Additionally, dismissed vulnerabilities are excluded. -Navigate to the group's [vulnerability report](#vulnerability-report) to view the vulnerabilities found. +Navigate to the group's [vulnerability report](#vulnerability-report-1) to view the vulnerabilities found. ## Instance Security Center @@ -232,10 +260,17 @@ into the default branch. You can filter which vulnerabilities the vulnerability report displays by: -- Status -- Severity -- Scanner -- Project +| Filter | Available Options | +| --- | --- | +| Status | Detected, Confirmed, Dismissed, Resolved | +| Severity | Critical, High, Medium, Low, Info, Unknown | +| Scanner | [Available Scanners](../index.md#security-scanning-tools) | +| Project | Projects configured in the Security Center settings | + +You can filter the vulnerabilities list by selecting from the **Status**, **Severity**, and +**Scanner**, and **Project** dropdowns. In the **Scanner** dropdown, select individual scanners or +scanner groups to toggle those scanners. The **Scanner** dropdown includes both GitLab scanners, and +in GitLab 13.6 and later, custom scanners. Clicking any vulnerability in the table takes you to its [Vulnerability Details](../vulnerabilities) page to see more information on that vulnerability. diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 391666a077e..f85d4f0140c 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Defend +stage: Protect group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_download_patch_button_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_download_patch_button_v13_1.png Binary files differdeleted file mode 100644 index b925c342a11..00000000000 --- a/doc/user/application_security/vulnerabilities/img/vulnerability_page_download_patch_button_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index ee3fd6c4dd4..95bb1ff1a67 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -11,10 +11,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w Each security vulnerability in a project's [Security Dashboard](../security_dashboard/index.md#project-security-dashboard) has an individual page which includes: -- Details of the vulnerability. +- Details for the vulnerability. - The status of the vulnerability within the project. - Available actions for the vulnerability. -- Issues related to the vulnerability. +- Any issues related to the vulnerability. On the vulnerability page, you can interact with the vulnerability in several different ways: @@ -25,22 +25,22 @@ several different ways: title and description pre-populated with information from the vulnerability report. By default, such issues are [confidential](../../project/issues/confidential_issues.md). - [Link issues](#link-issues-to-the-vulnerability) - Link existing issues to vulnerability. -- [Solution](#automatic-remediation-for-vulnerabilities) - For some vulnerabilities, - a solution is provided for how to fix the vulnerability. +- [Automatic remediation](#automatic-remediation-for-vulnerabilities) - For some vulnerabilities, + a solution is provided for how to fix the vulnerability automatically. ## Changing vulnerability status You can switch the status of a vulnerability using the **Status** dropdown to one of the following values: -| Status | Description | -|-----------|-------------------------------------------------------------------| -| Detected | The default state for a newly discovered vulnerability | -| Confirmed | A user has seen this vulnerability and confirmed it to be real | -| Dismissed | A user has seen this vulnerability and dismissed it | -| Resolved | The vulnerability has been fixed and is no longer in the codebase | +| Status | Description | +|-----------|------------------------------------------------------------------------------------------------------------------| +| Detected | The default state for a newly discovered vulnerability | +| Confirmed | A user has seen this vulnerability and confirmed it to be accurate | +| Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise will not be resolved | +| Resolved | The vulnerability has been fixed and is no longer valid | -A timeline shows you when the vulnerability status has changed, +A timeline shows you when the vulnerability status has changed and allows you to comment on a change. ## Creating an issue for a vulnerability @@ -48,7 +48,7 @@ and allows you to comment on a change. You can create an issue for a vulnerability by selecting the **Create issue** button. This creates a [confidential issue](../../project/issues/confidential_issues.md) in the -project the vulnerability came from, and pre-populates it with useful information from +project the vulnerability came from and pre-populates it with useful information from the vulnerability report. After the issue is created, GitLab redirects you to the issue page so you can edit, assign, or comment on the issue. @@ -61,4 +61,4 @@ that the resolution of one issue would resolve multiple vulnerabilities. ## Automatic remediation for vulnerabilities You can fix some vulnerabilities by applying the solution that GitLab automatically -generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#solutions-for-vulnerabilities-auto-remediation). +generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#automatic-remediation-for-vulnerabilities). diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 196c3e9fb43..74c679d9bb9 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -24,9 +24,11 @@ tasks in a secure and cloud-native way. It enables: Many more features are planned. Please [review our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329). -## Architecture +## GitLab Agent GitOps workflow -### GitLab Agent GitOps workflow +The GitLab Agent uses multiple GitLab projects to provide a flexible workflow +that can suit various needs. This diagram shows these repositories and the main +actors involved in a deployment: ```mermaid sequenceDiagram @@ -44,11 +46,6 @@ sequenceDiagram end ``` -Please refer to our [full architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture) -in the Agent project. - -## Get started with GitOps and the GitLab Agent - There are several components that work in concert for the Agent to accomplish GitOps deployments: - A properly-configured Kubernetes cluster. @@ -57,51 +54,93 @@ There are several components that work in concert for the Agent to accomplish Gi - A manifest repository that contains a `manifest.yaml`, which is tracked by the Agent and can be auto-generated. Any changes to `manifest.yaml` are applied to the cluster. +These repositories might be the same GitLab project or separate projects. + +For more details, please refer to our [full architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture) in the Agent project. + +## Get started with GitOps and the GitLab Agent + The setup process involves a few steps to enable GitOps deployments: -1. Installing the Agent server. -1. Defining a configuration directory. -1. Creating an Agent record in GitLab. -1. Generating and copying a Secret token used to connect to the Agent. -1. Installing the Agent into the cluster. -1. Creating a `manifest.yaml`. +1. [Install the Agent server](#install-the-kubernetes-agent-server). +1. [Define a configuration repository](#define-a-configuration-repository). +1. [Create an Agent record in GitLab](#create-an-agent-record-in-gitlab). +1. [Generate and copy a Secret token used to connect to the Agent](#create-the-kubernetes-secret). +1. [Install the Agent into the cluster](#install-the-agent-into-the-cluster). +1. [Create a `manifest.yaml`](#create-a-manifestyaml). + +### Upgrades and version compatibility + +As the GitLab Kubernetes Agent is a new product, we are constantly adding new features +to it. As a result, while shipped features are production ready, its internal API is +neither stable nor versioned yet. For this reason, GitLab only guarantees compatibility +between corresponding major.minor (X.Y) versions of GitLab and its cluster side +component, `agentk`. + +Upgrade your agent installations together with GitLab upgrades. To decide which version of `agentk`to install follow: + +1. Open the [GITLAB_KAS_VERSION](https://gitlab.com/gitlab-org/gitlab/-/blob/master/GITLAB_KAS_VERSION) file from the GitLab Repository, which contains the latest `agentk` version associated with the `master` branch. +1. Change the `master` branch and select the Git tag associated with your version. For instance, you could change it to GitLab [v13.5.3-ee release](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.5.3-ee/GITLAB_KAS_VERSION) -### Install the Agent server +The available `agentk` versions can be found in +[its container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/eyJuYW1lIjoiZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9hZ2VudGsiLCJ0YWdzX3BhdGgiOiIvZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9yZWdpc3RyeS9yZXBvc2l0b3J5LzEyMjMyMDUvdGFncz9mb3JtYXQ9anNvbiIsImlkIjoxMjIzMjA1LCJjbGVhbnVwX3BvbGljeV9zdGFydGVkX2F0IjpudWxsfQ==). -The GitLab Kubernetes Agent can be deployed using [Omnibus +### Install the Kubernetes Agent Server + +The GitLab Kubernetes Agent Server (KAS) can be deployed using [Omnibus GitLab](https://docs.gitlab.com/omnibus/) or the [GitLab chart](https://gitlab.com/gitlab-org/charts/gitlab). If you don't already have GitLab installed, please refer to our [installation documentation](https://docs.gitlab.com/ee/install/README.html). NOTE: **Note:** -GitLab plans to include the Agent on [GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/3834). +GitLab plans to include the KAS on [GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/3834). + +#### Install with Omnibus When using the [Omnibus GitLab](https://docs.gitlab.com/omnibus/) package: 1. Edit `/etc/gitlab/gitlab.rb`: -```plaintext -gitlab_kas['enable'] = true -``` + ```plaintext + gitlab_kas['enable'] = true + ``` 1. [Reconfigure GitLab](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). -When installing or upgrading the GitLab Helm chart, consider the following Helm 2 example. -(If you're using Helm 3, you must modify this example.) You must set `global.kas.enabled=true` -for the Agent to be properly installed and configured: +To configure any additional options related to GitLab Kubernetes Agent Server, +refer to 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). + +#### Install with the Helm chart + +When installing or upgrading the GitLab Helm chart, consider the following Helm v3 example. +If you're using Helm v2, you must modify this example. See our [notes regarding deploy with Helm](https://docs.gitlab.com/charts/installation/deployment.html#deploy-using-helm). + +You must set `global.kas.enabled=true` for the KAS to be properly installed and configured: ```shell +helm repo add gitlab https://charts.gitlab.io/ helm repo update -helm upgrade --force --install gitlab gitlab/gitlab \ - --timeout 600 \ +helm upgrade --install gitlab gitlab/gitlab \ + --timeout 600s \ --set global.hosts.domain=<YOUR_DOMAIN> \ --set global.hosts.externalIP=<YOUR_IP> \ --set certmanager-issuer.email=<YOUR_EMAIL> \ - --set name=gitlab-instance \ --set global.kas.enabled=true ``` +To specify other options related to the KAS sub-chart, create a `gitlab.kas` sub-section +of your `values.yaml` file: + +```shell +gitlab: + kas: + # put your KAS custom options here +``` + +For details, read [Using the GitLab-KAS chart](https://docs.gitlab.com/charts/charts/gitlab/kas/). + ### Define a configuration repository Next, you need a GitLab repository to contain your Agent configuration. The minimal @@ -111,12 +150,33 @@ repository layout looks like this: .gitlab/agents/<agent-name>/config.yaml ``` -The `config.yaml` file contents should look like this: +Your `config.yaml` file can specify multiple manifest projects in the +section `manifest_projects`: + +```yaml +gitops: + manifest_projects: + - id: "path-to/your-manifest-project-number1" + ... +``` + +GitLab [versions 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) also +supports manifest projects containing multiple directories (or subdirectories) +of YAML files. To use multiple YAML files, specify a `paths` attribute: ```yaml gitops: manifest_projects: - - id: "path-to/your-awesome-project" + - id: "path-to/your-manifest-project-number1" + paths: + # Read all .yaml files from team1/app1 directory. + # See https://github.com/bmatcuk/doublestar#about and + # https://pkg.go.dev/github.com/bmatcuk/doublestar/v2#Match for globbing rules. + - glob: '/team1/app1/*.yaml' + # Read all .yaml files from team2/apps and all subdirectories + - glob: '/team2/apps/**/*.yaml' + # If 'paths' is not specified or is an empty list, the configuration below is used + - glob: '/**/*.{yaml,yml,json}' ``` ### Create an Agent record in GitLab @@ -125,20 +185,24 @@ Next, create an GitLab Rails Agent record so the Agent can associate itself with the configuration repository project. Creating this record also creates a Secret needed to configure the Agent in subsequent steps. You can create an Agent record either: -- Through the Rails console, by running `rails c`: +- Through the Rails console: ```ruby - project = ::Project.find_by_full_path("path-to/your-awesome-project") + project = ::Project.find_by_full_path("path-to/your-configuration-project") + # agent-name should be the same as specified above in the config.yaml agent = ::Clusters::Agent.create(name: "<agent-name>", project: project) token = ::Clusters::AgentToken.create(agent: agent) token.token # this will print out the token you need to use on the next step ``` + For full details, read [Starting a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). + - Through GraphQL: **(PREMIUM ONLY)** ```graphql mutation createAgent { - createClusterAgent(input: { projectPath: "path-to/your-awesome-project", name: "<agent-name>" }) { + # agent-name should be the same as specified above in the config.yaml + createClusterAgent(input: { projectPath: "path-to/your-configuration-project", name: "<agent-name>" }) { clusterAgent { id name @@ -160,7 +224,7 @@ the Agent in subsequent steps. You can create an Agent record either: ``` NOTE: **Note:** - GraphQL only displays the token once, after creating it. + GraphQL only displays the token one time after creating it. If you are new to using the GitLab GraphQL API, refer to the [Getting started with the GraphQL API page](../../../api/graphql/getting_started.md), @@ -170,7 +234,7 @@ the Agent in subsequent steps. You can create an Agent record either: After generating the token, you must apply it to the Kubernetes cluster. -1. If you haven't previous defined or created a namespace, run the following command: +1. If you haven't previously defined or created a namespace, run the following command: ```shell kubectl create namespace <YOUR-DESIRED-NAMESPACE> @@ -188,43 +252,40 @@ Next, install the in-cluster component of the Agent. This example file contains Kubernetes resources required for the Agent to be installed. You can modify this example [`resources.yml` file](#example-resourcesyml-file) in the following ways: -- You can replace `gitlab-agent` with `<YOUR-DESIRED-NAMESPACE>`. -- For the `kas-address` (Kubernetes Agent Server), the agent can use the WebSockets - or gRPC protocols to connect to the Agent Server. Depending on your cluster - configuration and GitLab architecture, you may need to use one or the other. - For the `gitlab-kas` Helm chart, an Ingress is created for the Agent Server using - the `/-/kubernetes-agent` endpoint. This can be used for the WebSockets protocol connection. - - Specify the `grpc` scheme (such as `grpc://gitlab-kas:5005`) to use gRPC directly. - Encrypted gRPC is not supported yet. Follow the +- Replace `namespace: gitlab-agent` with `namespace: <YOUR-DESIRED-NAMESPACE>`. +- You can configure `kas-address` (Kubernetes Agent Server) in several ways. + The agent can use the WebSockets or gRPC protocols to connect to the Agent Server. + Select the option appropriate for your cluster configuration and GitLab architecture: + - The `wss` scheme (an encrypted WebSockets connection) is specified by default + after you install `gitlab-kas` sub-chart or enable `kas` for Omnibus GitLab. + In this case, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent` as + `kas-address`, where `GitLab.host.tld` is your GitLab hostname. + - Specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent`) + to use an unencrypted WebSockets connection. + - Specify the `grpc` scheme if both Agent and Server are installed in one cluster. + In this case, you may specify `kas-address` value as + `grpc://gitlab-kas.<your-namespace>:5005`) to use gRPC directly, where `gitlab-kas` + is the name of the service created by `gitlab-kas` chart, and `your-namespace` + is the namespace where the chart was installed. Encrypted gRPC is not supported yet. + Follow the [Support TLS for gRPC communication issue](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) for progress updates. - - Specify the `ws` scheme (such as `ws://gitlab-kas-ingress:80/-/kubernetes-agent`) - to use an unencrypted WebSockets connection. - - Specify the `wss` scheme (such as `wss://gitlab-kas-ingress:443/-/kubernetes-agent`) - to use an encrypted WebSockets connection. This is the recommended option if - installing the Agent into a separate cluster from your Agent Server. -- If you defined your own secret name, replace `gitlab-agent-token` with your secret name. +- If you defined your own secret name, replace `gitlab-agent-token` with your + secret name in the `secretName:` section. To apply this file, run the following command: ```shell -kubectl apply -n gitlab-agent -f ./resources.yml +kubectl apply -n <YOUR-DESIRED-NAMESPACE> -f ./resources.yml ``` To review your configuration, run the following command: ```shell -$ kubectl get pods --all-namespaces +$ kubectl get pods -n <YOUR-DESIRED-NAMESPACE> NAMESPACE NAME READY STATUS RESTARTS AGE gitlab-agent gitlab-agent-77689f7dcb-5skqk 1/1 Running 0 51s -kube-system coredns-f9fd979d6-n6wcw 1/1 Running 0 14m -kube-system etcd-minikube 1/1 Running 0 14m -kube-system kube-apiserver-minikube 1/1 Running 0 14m -kube-system kube-controller-manager-minikube 1/1 Running 0 14m -kube-system kube-proxy-j6zdh 1/1 Running 0 14m -kube-system kube-scheduler-minikube 1/1 Running 0 14m -kube-system storage-provisioner 1/1 Running 0 14m ``` #### Example `resources.yml` file @@ -256,7 +317,7 @@ spec: args: - --token-file=/config/token - --kas-address - - grpc://host.docker.internal:5005 # {"$openapi":"kas-address"} + - wss://gitlab.host.tld:443/-/kubernetes-agent volumeMounts: - name: token-volume mountPath: /config @@ -331,7 +392,9 @@ subjects: In a previous step, you configured a `config.yaml` to point to the GitLab projects the Agent should synchronize. In each of those projects, you must create a `manifest.yaml` file for the Agent to monitor. You can auto-generate this `manifest.yaml` with a -templating engine or other means. +templating engine or other means. Only public projects are supported as +manifest projects. Support for private projects is planned in the issue +[Agent authorization for private manifest projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). Each time you commit and push a change to this file, the Agent logs the change: @@ -341,7 +404,7 @@ Each time you commit and push a change to this file, the Agent logs the change: #### Example `manifest.yaml` file -This file creates a simple NGINX deployment. +This file creates an NGINX deployment. ```yaml apiVersion: apps/v1 @@ -368,7 +431,128 @@ spec: ## Example projects +The following example projects can help you get started with the Kubernetes Agent. + +### Simple NGINX deployment + This basic GitOps example deploys NGINX: - [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) - [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) + +### Deploying GitLab Runner with the Agent + +These instructions assume that the Agent is already set up as described in the +[Get started with GitOps](#get-started-with-gitops-and-the-gitlab-agent): + +1. Check the possible + [Runner chart YAML values](https://gitlab.com/gitlab-org/charts/gitlab-runner/blob/master/values.yaml) + on the Runner chart documentation, and create a `runner-chart-values.yaml` file + with the configuration that fits your needs, such as: + + ```yaml + ## The GitLab Server URL (with protocol) that want to register the runner against + ## ref: https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-register + ## + gitlabUrl: https://gitlab.my.domain.com/ + + ## The Registration Token for adding new Runners to the GitLab Server. This must + ## be retrieved from your GitLab Instance. + ## ref: https://docs.gitlab.com/ce/ci/runners/README.html + ## + runnerRegistrationToken: "XXXXXXYYYYYYZZZZZZ" + + ## For RBAC support: + rbac: + create: true + + ## Run all containers with the privileged flag enabled + ## This will allow the docker:dind image to run if you need to run Docker + ## commands. Please read the docs before turning this on: + ## ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-dockerdind + runners: + privileged: true + ``` + +1. Create a single manifest file to install the Runner chart with your cluster agent: + + ```shell + helm template --namespace gitlab gitlab-runner -f runner-chart-values.yaml gitlab/gitlab-runner > manifest.yaml + ``` + +1. Push your `manifest.yaml` to your manifest repository. + +## Troubleshooting + +If you face any issues while using GitLab Kubernetes Agent, you can read the +service logs with the following commands: + +- KAS pod logs - Tail these logs with the + `kubectl logs -f -l=app=kas -n <YOUR-GITLAB-NAMESPACE>` + command. In Omnibus GitLab, the logs reside in `/var/log/gitlab/gitlab-kas/`. +- Agent pod logs - Tail these logs with the + `kubectl logs -f -l=app=gitlab-agent -n <YOUR-DESIRED-NAMESPACE>` command. + +### KAS logs - GitOps: failed to get project info + +```plaintext +{"level":"warn","time":"2020-10-30T08:37:26.123Z","msg":"GitOps: failed to get project info","agent_id":4,"project_id":"root/kas-manifest001","error":"error kind: 0; status: 404"} +``` + +This error is shown if the specified manifest project `root/kas-manifest001` +doesn't exist, or if a project is private. To fix it, make sure the project exists +and its visibility is [set to public](../../../public_access/public_access.md). + +### KAS logs - Configuration file not found + +```plaintext +time="2020-10-29T04:44:14Z" level=warning msg="Config: failed to fetch" agent_id=2 error="configuration file not found: \".gitlab/agents/test-agent/config.yaml\ +``` + +This error is shown if the path to the configuration project was specified incorrectly, +or if the path to `config.yaml` inside the project is not valid. + +### Agent logs - Transport: Error while dialing failed to WebSocket dial + +```plaintext +{"level":"warn","time":"2020-11-04T10:14:39.368Z","msg":"GetConfiguration failed","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://gitlab-kas:443/-/kubernetes-agent\\\": dial tcp: lookup gitlab-kas on 10.60.0.10:53: no such host\""} +``` + +This error is shown if there are some connectivity issues between the address +specified as `kas-address`, and your Agent pod. To fix it, make sure that you +specified the `kas-address` correctly. + +### Agent logs - ValidationError(Deployment.metadata + +```plaintext +{"level":"info","time":"2020-10-30T08:56:54.329Z","msg":"Synced","project_id":"root/kas-manifest001","resource_key":"apps/Deployment/kas-test001/nginx-deployment","sync_result":"error validating data: [ValidationError(Deployment.metadata): unknown field \"replicas\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"selector\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"template\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta]"} +``` + +This error is shown if your `manifest.yaml` file is malformed, and Kubernetes can't +create specified objects. Make sure that your `manifest.yaml` file is valid. You +may try using it to create objects in Kubernetes directly for more troubleshooting. + +### Agent logs - Error while dialing failed to WebSocket dial: failed to send handshake request + +```plaintext +{"level":"warn","time":"2020-10-30T09:50:51.173Z","msg":"GetConfiguration failed","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent\\\": net/http: HTTP/1.x transport connection broken: malformed HTTP response \\\"\\\\x00\\\\x00\\\\x06\\\\x04\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x05\\\\x00\\\\x00@\\\\x00\\\"\""} +``` + +This error is shown if you configured `wss` as `kas-address` on the agent side, +but KAS on the server side is not available via `wss`. To fix it, make sure the +same schemes are configured on both sides. + +It's not possible to set the `grpc` scheme due to the issue +[It is not possible to configure KAS to work with `grpc` without directly editing GitLab KAS deployment](https://gitlab.com/gitlab-org/gitlab/-/issues/276888). To use `grpc` while the +issue is in progress, directly edit the deployment with the +`kubectl edit deployment gitlab-kas` command, and change `--listen-websocket=true` to `--listen-websocket=false`. After running that command, you should be able to use +`grpc://gitlab-kas.<YOUR-NAMESPACE>:5005`. + +#### Agent logs - Decompressor is not installed for grpc-encoding + +```plaintext +{"level":"warn","time":"2020-11-05T05:25:46.916Z","msg":"GetConfiguration.Recv failed","error":"rpc error: code = Unimplemented desc = grpc: Decompressor is not installed for grpc-encoding \"gzip\""} +``` + +This error is shown if the version of the agent is newer that the version of KAS. +To fix it, make sure that both `agentk` and KAS use the same versions. diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 4e0e2991acb..67a53fa773f 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -64,21 +64,35 @@ supported by GitLab before installing any of the applications. > - Introduced in GitLab 10.2 for project-level clusters. > - Introduced in GitLab 11.6 for group-level clusters. > - [Uses a local Tiller](https://gitlab.com/gitlab-org/gitlab/-/issues/209736) in GitLab 13.2 and later. +> - [Uses Helm 3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46267) for clusters created with GitLab 13.6 and later. [Helm](https://helm.sh/docs/) is a package manager for Kubernetes and is used to install the GitLab-managed apps. GitLab runs each `helm` command in a pod within the `gitlab-managed-apps` namespace inside the cluster. -GitLab's integration uses Helm 2 with a local -[Tiller](https://v2.helm.sh/docs/glossary/#tiller) server for managing -applications. Prior to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/209736), -GitLab used an in-cluster Tiller server in the `gitlab-managed-apps` -namespace. This server can now be safely removed. +- For clusters created on GitLab 13.6 and newer, GitLab uses Helm 3 to manage + applications. +- For clusters created on versions of GitLab prior to 13.6, GitLab uses + Helm 2 with a local [Tiller](https://v2.helm.sh/docs/glossary/#tiller) server. + Prior to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/209736), + GitLab used an in-cluster Tiller server in the `gitlab-managed-apps` + namespace. You can safely remove this server after upgrading to GitLab 13.2 + or newer. GitLab's Helm integration does not support installing applications behind a proxy, but a [workaround](../../topics/autodevops/index.md#install-applications-behind-a-proxy) is available. +#### Upgrade a cluster to Helm 3 + +GitLab does not currently offer a way to migrate existing application management +on existing clusters from Helm 2 to Helm 3. To migrate a cluster to Helm 3: + +1. Uninstall all applications on your cluster. +1. [Remove the cluster integration](../project/clusters/add_remove_clusters.md#removing-integration). +1. [Re-add the cluster](../project/clusters/add_remove_clusters.md#existing-kubernetes-cluster) as + an existing cluster. + ### cert-manager > Introduced in GitLab 11.6 for project- and group-level clusters. @@ -93,7 +107,7 @@ The chart used to install this application depends on the version of GitLab used - GitLab 12.3 and newer, the [`jetstack/cert-manager`](https://github.com/jetstack/cert-manager) chart is used with a [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/cert_manager/values.yaml) file. -- GitLab 12.2 and older, the [`stable/cert-manager`](https://gi2wthub.com/helm/charts/tree/master/stable/cert-manager) +- GitLab 12.2 and older, the [`stable/cert-manager`](https://github.com/helm/charts/tree/master/stable/cert-manager) chart was used. If you installed cert-manager prior to GitLab 12.3, Let's Encrypt @@ -625,10 +639,13 @@ To install applications using GitLab CI/CD: - template: Managed-Cluster-Applications.gitlab-ci.yml ``` - The job provided by this template connects to the cluster using tools provided + The job provided by this template connects to the `*` (default) cluster using tools provided in a custom Docker image. It requires that you have a runner registered with the Docker, Kubernetes, or Docker Machine executor. + To install to a specific cluster, read + [Use the template with a custom environment](#use-the-template-with-a-custom-environment). + 1. Add a `.gitlab/managed-apps/config.yaml` file to define which applications you would like to install. Define the `installed` key as `true` to install the application and `false` to uninstall the @@ -647,6 +664,47 @@ applications you have configured. In case of pipeline failure, the output of the [Helm Tiller](https://v2.helm.sh/docs/install/#running-tiller-locally) binary is saved as a [CI job artifact](../../ci/pipelines/job_artifacts.md). +For GitLab versions 13.5 and below, the Ingress, Fluentd, Prometheus, +and Sentry apps are fetched from the central Helm [stable +repository](https://kubernetes-charts.storage.googleapis.com/), which +will be [deleted](https://github.com/helm/charts#deprecation-timeline) +on November 13, 2020. This will cause the installation CI/CD pipeline to +fail. Upgrade to GitLab 13.6, or alternatively, you can +use the following `.gitlab-ci.yml`, which has been tested on GitLab +13.5: + +```yaml +include: + - template: Managed-Cluster-Applications.gitlab-ci.yml + +apply: + image: "registry.gitlab.com/gitlab-org/cluster-integration/cluster-applications:v0.34.1" +``` + +### Use the template with a custom environment + +If you only want apps to be installed on a specific cluster, or if your cluster's +scope does not match `production`, you can override the environment name in your `.gitlab-ci.yml` +file: + +```yaml +include: + - template: Managed-Cluster-Applications.gitlab-ci.yml + +apply: + except: + variables: + - '$CI_JOB_NAME == "apply"' + +.managed-apps: + extends: apply + +example-install: + extends: .managed-apps + environment: + name: example/production +``` + ### Important notes Note the following: @@ -717,7 +775,7 @@ certManager: You can customize the installation of cert-manager by defining a `.gitlab/managed-apps/cert-manager/values.yaml` file in your cluster management project. Refer to the -[chart](https://hub.helm.sh/charts/jetstack/cert-manager) for the +[chart](https://github.com/jetstack/cert-manager) for the available configuration options. Support for installing the Cert Manager managed application is provided by the @@ -797,7 +855,7 @@ least 2 people from the ### Install PostHog using GitLab CI/CD -[PostHog](https://www.posthog.com) 🦔 is a developer-friendly, open-source product analytics platform. +[PostHog](https://posthog.com) 🦔 is a developer-friendly, open-source product analytics platform. To install PostHog into the `gitlab-managed-apps` namespace of your cluster, define the `.gitlab/managed-apps/config.yaml` file with: @@ -954,15 +1012,15 @@ CAUTION: **Caution:** Installation and removal of the Cilium requires a **manual** [restart](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-gke/#restart-unmanaged-pods) of all affected pods in all namespaces to ensure that they are -[managed](https://docs.cilium.io/en/stable/troubleshooting/#ensure-pod-is-managed-by-cilium) +[managed](https://docs.cilium.io/en/v1.8/operations/troubleshooting/#ensure-managed-pod) by the correct networking plugin. NOTE: **Note:** Major upgrades might require additional setup steps. For more information, see -the official [upgrade guide](https://docs.cilium.io/en/stable/install/upgrade/). +the official [upgrade guide](https://docs.cilium.io/en/v1.8/operations/upgrade/). By default, Cilium's -[audit mode](https://docs.cilium.io/en/v1.8/gettingstarted/policy-creation/?highlight=policy-audit#enable-policy-audit-mode) +[audit mode](https://docs.cilium.io/en/v1.8/gettingstarted/policy-creation/#enable-policy-audit-mode) is enabled. In audit mode, Cilium doesn't drop disallowed packets. You can use `policy-verdict` log to observe policy-related decisions. You can disable audit mode by adding the following to diff --git a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_3_1.png b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_3_1.png Binary files differdeleted file mode 100644 index 89f4e917567..00000000000 --- a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_3_1.png +++ /dev/null diff --git a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_6.png b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_6.png Binary files differnew file mode 100644 index 00000000000..b2ac4f95e0d --- /dev/null +++ b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_6.png diff --git a/doc/user/compliance/compliance_dashboard/index.md b/doc/user/compliance/compliance_dashboard/index.md index 5c05725d95b..151c61b50d8 100644 --- a/doc/user/compliance/compliance_dashboard/index.md +++ b/doc/user/compliance/compliance_dashboard/index.md @@ -17,7 +17,7 @@ for merging into production. To access the Compliance Dashboard for a group, navigate to **{shield}** **Security & Compliance > Compliance** on the group's menu. - + NOTE: **Note:** The Compliance Dashboard shows only the latest MR on each project. @@ -63,14 +63,24 @@ This column has four states: If you do not see the success icon in your Compliance dashboard; please review the above criteria for the Merge Requests project to make sure it complies with the separation of duties described above. -## Chain of Custody report +## Chain of Custody report **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. The Chain of Custody report allows customers to export a list of merge commits within the group. The data provides a comprehensive view with respect to merge commits. It includes the merge commit SHA, merge request author, merge request ID, merge user, pipeline ID, group name, project name, and merge request approvers. +Depending on the merge strategy, the merge commit SHA can either be a merge commit, squash commit or a diff head commit. To download the Chain of Custody report, navigate to **{shield}** **Security & Compliance > Compliance** on the group's menu and click **List of all merge commits** +### Commit-specific Chain of Custody Report **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. + +You can generate a commit-specific Chain of Custody report for a given commit SHA. To do so, select +the dropdown next to the **List of all merge commits** button at the top of the Compliance Dashboard. + NOTE: **Note:** The Chain of Custody report download is a CSV file, with a maximum size of 15 MB. The remaining records are truncated when this limit is reached. diff --git a/doc/user/compliance/license_compliance/img/license_compliance_add_license_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_add_license_v13_0.png Binary files differdeleted file mode 100644 index 1366c569f17..00000000000 --- a/doc/user/compliance/license_compliance/img/license_compliance_add_license_v13_0.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/img/license_compliance_decision_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_decision_v13_0.png Binary files differdeleted file mode 100644 index 42bf8bd1ed5..00000000000 --- a/doc/user/compliance/license_compliance/img/license_compliance_decision_v13_0.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/img/license_compliance_pipeline_tab_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_pipeline_tab_v13_0.png Binary files differdeleted file mode 100644 index 49c66832f00..00000000000 --- a/doc/user/compliance/license_compliance/img/license_compliance_pipeline_tab_v13_0.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/img/license_compliance_search_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_search_v13_0.png Binary files differdeleted file mode 100644 index 5a4216dd645..00000000000 --- a/doc/user/compliance/license_compliance/img/license_compliance_search_v13_0.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/img/license_compliance_settings_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_settings_v13_0.png Binary files differdeleted file mode 100644 index 91f1eec2a23..00000000000 --- a/doc/user/compliance/license_compliance/img/license_compliance_settings_v13_0.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 894c0e14862..65c009f947f 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -37,10 +37,7 @@ compliance report will be shown properly.  -If you are a project or group Maintainer, you can click on a license to be given -the choice to allow it or deny it. - - +You can click on a license to see more information. When GitLab detects a **Denied** license, you can view it in the [license list](#license-list). @@ -62,7 +59,6 @@ The following languages and package managers are supported. | .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`. | [License Finder](https://github.com/pivotal/LicenseFinder) | | 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). | [License Finder](https://github.com/pivotal/LicenseFinder) | | Ruby | [gem](https://rubygems.org/) | | [License Finder](https://github.com/pivotal/LicenseFinder)| -| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage) | | [License Finder](https://github.com/pivotal/LicenseFinder) | NOTE: **Note:** Java 8 and Gradle 1.x projects are not supported. @@ -78,6 +74,7 @@ which means that the reported licenses might be incomplete or inaccurate. | JavaScript | [Yarn](https://yarnpkg.com/)|[License Finder](https://github.com/pivotal/LicenseFinder)| | Go | go get, gvt, glide, dep, trash, govendor |[License Finder](https://github.com/pivotal/LicenseFinder)| | Erlang | [Rebar](https://www.rebar3.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage) | | [License Finder](https://github.com/pivotal/LicenseFinder) | | Objective-C, Swift | [CocoaPods](https://cocoapods.org/) v0.39 and below |[License Finder](https://github.com/pivotal/LicenseFinder)| | Elixir | [Mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) |[License Finder](https://github.com/pivotal/LicenseFinder)| | C++/C | [Conan](https://conan.io/) |[License Finder](https://github.com/pivotal/LicenseFinder)| @@ -144,7 +141,7 @@ License Compliance can be configured using environment variables. | `ASDF_PYTHON_VERSION` | no | Version of Python to use for the scan. | | `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 your project has both Golang and Ruby code stored in different directories and you want to only scan the Ruby code, you can update your `.gitlab-ci-yml` template to specify which project directories to scan, like `LICENSE_FINDER_CLI_OPTS: '--debug --aggregate-paths=. ruby'`. | +| `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. | | `LM_PYTHON_VERSION` | no | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. | | `MAVEN_CLI_OPTS` | no | Additional arguments for the mvn executable. If not supplied, defaults to `-DskipTests`. | @@ -444,7 +441,7 @@ 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/README.md#before_script-and-after_script) +compile dependencies, use a [`before_script`](../../../ci/yaml/README.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). @@ -775,11 +772,11 @@ or using the appropriate [`ASDF_<tool>_VERSION`](https://asdf-vm.com/#/core-conf activate the appropriate version. For example, the following `.tool-versions` file will activate version `12.16.3` of [Node.js](https://nodejs.org/) -and version `2.6.6` of [Ruby](https://www.ruby-lang.org/). +and version `2.7.2` of [Ruby](https://www.ruby-lang.org/). ```plaintext nodejs 12.16.3 -ruby 2.6.6 +ruby 2.7.2 ``` The next example shows how to activate the same versions of the tools mentioned above by using environment variables defined in your @@ -792,7 +789,7 @@ include: license_scanning: variables: ASDF_NODEJS_VERSION: '12.16.3' - ASDF_RUBY_VERSION: '2.6.6' + ASDF_RUBY_VERSION: '2.7.2' ``` A full list of variables can be found in [environment variables](#available-variables). diff --git a/doc/user/discussions/img/discussions_resolved.png b/doc/user/discussions/img/discussions_resolved.png Binary files differdeleted file mode 100644 index 3fd496f6da5..00000000000 --- a/doc/user/discussions/img/discussions_resolved.png +++ /dev/null diff --git a/doc/user/discussions/img/mr_review_unresolve2.png b/doc/user/discussions/img/mr_review_unresolve2.png Binary files differdeleted file mode 100644 index 79da61bb556..00000000000 --- a/doc/user/discussions/img/mr_review_unresolve2.png +++ /dev/null diff --git a/doc/user/discussions/img/new_issue_for_discussion.png b/doc/user/discussions/img/new_issue_for_discussion.png Binary files differdeleted file mode 100644 index 819d872a9a2..00000000000 --- a/doc/user/discussions/img/new_issue_for_discussion.png +++ /dev/null diff --git a/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png b/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png Binary files differdeleted file mode 100644 index 928c7d33898..00000000000 --- a/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png +++ /dev/null diff --git a/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved_msg.png b/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved_msg.png Binary files differdeleted file mode 100644 index 9044926b0eb..00000000000 --- a/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved_msg.png +++ /dev/null diff --git a/doc/user/discussions/img/preview_issue_for_discussion.png b/doc/user/discussions/img/preview_issue_for_discussion.png Binary files differdeleted file mode 100644 index 30c273ca4c5..00000000000 --- a/doc/user/discussions/img/preview_issue_for_discussion.png +++ /dev/null diff --git a/doc/user/discussions/img/preview_issue_for_discussions.png b/doc/user/discussions/img/preview_issue_for_discussions.png Binary files differdeleted file mode 100644 index 3d906e1b0b0..00000000000 --- a/doc/user/discussions/img/preview_issue_for_discussions.png +++ /dev/null diff --git a/doc/user/discussions/img/resolve_discussion_button.png b/doc/user/discussions/img/resolve_discussion_button.png Binary files differdeleted file mode 100644 index ab454f661e0..00000000000 --- a/doc/user/discussions/img/resolve_discussion_button.png +++ /dev/null diff --git a/doc/user/discussions/img/resolve_discussion_issue_notice.png b/doc/user/discussions/img/resolve_discussion_issue_notice.png Binary files differdeleted file mode 100644 index ed50dc1de91..00000000000 --- a/doc/user/discussions/img/resolve_discussion_issue_notice.png +++ /dev/null diff --git a/doc/user/discussions/img/resolve_discussion_open_issue.png b/doc/user/discussions/img/resolve_discussion_open_issue.png Binary files differdeleted file mode 100644 index 9d0a14671d6..00000000000 --- a/doc/user/discussions/img/resolve_discussion_open_issue.png +++ /dev/null diff --git a/doc/user/feature_highlight.md b/doc/user/feature_highlight.md index 9b52c178493..31eb0e6375d 100644 --- a/doc/user/feature_highlight.md +++ b/doc/user/feature_highlight.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Feature highlight > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/16379) in GitLab 10.5 diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index ec0c207e190..54f14c71c93 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab.com settings In this page you will find information about the settings that are used on @@ -85,6 +91,7 @@ which is part of [GitLab CI/CD](#gitlab-cicd). ## GitLab CI/CD Below are the current settings regarding [GitLab CI/CD](../../ci/README.md). +Any settings or feature limits not listed here are using the defaults listed in the related documentation. | Setting | GitLab.com | Default | | ----------- | ----------------- | ------------- | @@ -94,7 +101,6 @@ Below are the current settings regarding [GitLab CI/CD](../../ci/README.md). | [Max jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | `500` for Free tier, unlimited otherwise | Unlimited | [Max CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) | `2` | Unlimited | | [Max pipeline schedules in projects](../../administration/instance_limits.md#number-of-pipeline-schedules) | `10` for Free tier, `50` for all paid tiers | Unlimited | -| [Max number of instance level variables](../../administration/instance_limits.md#number-of-instance-level-variables) | `25` | `25` | | [Scheduled Job Archival](../../user/admin_area/settings/continuous_integration.md#archive-jobs) | 3 months | Never | | Max test cases per [unit test report](../../ci/unit_test_reports.md) | `500_000` | Unlimited | @@ -107,7 +113,7 @@ or over the repository size limit, you can [reduce your repository size with Git | Setting | GitLab.com | Default | | ----------- | ----------- | ------------- | -| Repository size including LFS | 10 GB | Unlimited | +| [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md) | 10 GB | Unlimited | | Maximum import size | 5 GB | 50 MB | NOTE: **Note:** @@ -146,7 +152,7 @@ Shared runners provided by GitLab are **not** configurable. Consider [installing Linux shared runners on GitLab.com run in [autoscale mode](https://docs.gitlab.com/runner/configuration/autoscale.html) and are powered by Google Cloud Platform. Autoscaling means reduced waiting times to spin up CI/CD jobs, and isolated VMs for each project, thus maximizing security. They're free to use for public open source projects and limited -to 2000 CI minutes per month per group for private projects. More minutes +to 400 CI minutes per month per group for private projects. More minutes [can be purchased](../../subscriptions/gitlab_com/index.md#purchase-additional-ci-minutes), if needed. Read about all [GitLab.com plans](https://about.gitlab.com/pricing/). @@ -264,26 +270,23 @@ sentry_dsn = "X" ### Windows shared runners (beta) -The Windows shared runners are currently in -[beta](https://about.gitlab.com/handbook/product/#beta) and should not be used -for production workloads. +The Windows shared runners are in [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) +and shouldn't be used for production workloads. -During the beta period, the -[shared runner pipeline quota](../admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota) -will apply for groups and projects in the same way as Linux runners. -This may change when the beta period ends, as discussed in this -[related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30834). +During this beta period, the [shared runner pipeline quota](../admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota) +applies for groups and projects in the same manner as Linux runners. This may +change when the beta period ends, as discussed in this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30834). -Windows shared runners on GitLab.com automatically autoscale by -launching virtual machines on the Google Cloud Platform. This solution uses -a new [autoscaling driver](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/tree/master/docs/readme.md) +Windows shared runners on GitLab.com autoscale by launching virtual machines on +the Google Cloud Platform. This solution uses an +[autoscaling driver](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/tree/master/docs/readme.md) developed by GitLab for the [custom executor](https://docs.gitlab.com/runner/executors/custom.html). -Windows shared runners execute your CI/CD jobs on `n1-standard-2` instances with 2 -vCPUs and 7.5GB RAM. You can find a full list of available Windows packages in the -[package documentation](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/gcp/windows-containers/blob/master/cookbooks/preinstalled-software/README.md). +Windows shared runners execute your CI/CD jobs on `n1-standard-2` instances with +2 vCPUs and 7.5 GB RAM. You can find a full list of available Windows packages in +the [package documentation](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/gcp/windows-containers/blob/master/cookbooks/preinstalled-software/README.md). We want to keep iterating to get Windows shared runners in a stable state and -[generally available](https://about.gitlab.com/handbook/product/#generally-available-ga). +[generally available](https://about.gitlab.com/handbook/product/gitlab-the-product/#generally-available-ga). You can follow our work towards this goal in the [related epic](https://gitlab.com/groups/gitlab-org/-/epics/2162). @@ -292,7 +295,7 @@ You can follow our work towards this goal in the The full contents of our `config.toml` are: NOTE: **Note:** -Settings that are not public are shown as `X`. +Settings that aren't public are shown as `X`. ```toml concurrent = X @@ -406,7 +409,7 @@ test: - For the beta release, we have included a set of software packages in the base VM image. If your CI job requires additional software that's not included in this list, then you will need to add installation - commands to [`before_script`](../../ci/yaml/README.md#before_script-and-after_script) or [`script`](../../ci/yaml/README.md#script) to install the required + commands to [`before_script`](../../ci/yaml/README.md#before_script) or [`script`](../../ci/yaml/README.md#script) to install the required software. Note that each job runs on a new VM instance, so the installation of additional software packages needs to be repeated for each job in your pipeline. @@ -429,7 +432,7 @@ and the following environment variables: | `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL` | - | `3` | | `SIDEKIQ_MEMORY_KILLER_GRACE_TIME` | - | `900` | | `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_WAIT` | - | `30` | -| `SIDEKIQ_LOG_ARGUMENTS` | `1` | - | +| `SIDEKIQ_LOG_ARGUMENTS` | `1` | `1` | NOTE: **Note:** The `SIDEKIQ_MEMORY_KILLER_MAX_RSS` setting is `16000000` on Sidekiq import @@ -627,6 +630,13 @@ You can view more information in our runbooks such as: - Our [current log retention policies](https://gitlab.com/gitlab-com/runbooks/-/tree/master/docs/logging#retention) - A [diagram of our logging infrastructure](https://gitlab.com/gitlab-com/runbooks/-/tree/master/docs/logging#logging-infrastructure-overview) +### Job Logs + +By default, GitLab does not expire job logs. Job logs are retained indefinitely, +and can't be configured on GitLab.com to expire. You can erase job logs +[manually with the Jobs API](../../api/jobs.md#erase-a-job) or by +[deleting a pipeline](../../ci/pipelines/index.md#delete-a-pipeline). + ## GitLab.com at scale In addition to the GitLab Enterprise Edition Omnibus install, GitLab.com uses diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index a689b7c380b..cf55a1f688b 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Analytics +group: Value Stream Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Contribution Analytics **(STARTER)** diff --git a/doc/user/group/dependency_proxy/img/group_dependency_proxy.png b/doc/user/group/dependency_proxy/img/group_dependency_proxy.png Binary files differdeleted file mode 100644 index 035aff0b6c4..00000000000 --- a/doc/user/group/dependency_proxy/img/group_dependency_proxy.png +++ /dev/null diff --git a/doc/user/group/epics/img/containing_epic.png b/doc/user/group/epics/img/containing_epic.png Binary files differindex dc13d55e2bc..1ba5a30708f 100644 --- a/doc/user/group/epics/img/containing_epic.png +++ b/doc/user/group/epics/img/containing_epic.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index f380b36cc00..e98c4b416fe 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Plan -group: Portfolio Management +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/#designated-technical-writers --- diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index c09032bffb2..5895b611bb3 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -1,7 +1,7 @@ --- type: howto stage: Plan -group: Portfolio Management +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/#designated-technical-writers --- @@ -23,9 +23,9 @@ selected group. From your group page: To create an epic from the epic list, in a group: 1. Go to **{epic}** **Epics**. -1. Click **New epic**. +1. Select **New epic**. 1. Enter a descriptive title. -1. Click **Create epic**. +1. Select **Create epic**. ### Access the New Epic form @@ -33,8 +33,8 @@ To create an epic from the epic list, in a group: There are two ways to get to the New Epic form and create an epic in the group you're in: -- From an epic in your group, click **New Epic**. -- From anywhere, in the top menu, click **plus** (**{plus-square}**) **> New epic**. +- From an epic in your group, select **New Epic**. +- From anywhere, in the top menu, select **plus** (**{plus-square}**) **> New epic**.  @@ -63,13 +63,13 @@ After you create an epic, you can edit change the following details: To edit an epic's title or description: -1. Click the **Edit title and description** **{pencil}** button. +1. Select the **Edit title and description** **{pencil}** button. 1. Make your changes. -1. Click **Save changes**. +1. Select **Save changes**. To edit an epics' start date, due date, or labels: -1. Click **Edit** next to each section in the epic sidebar. +1. Select **Edit** next to each section in the epic sidebar. 1. Select the dates or labels for your epic. ## Bulk-edit epics @@ -82,7 +82,7 @@ You can edit multiple epics at once. To learn how to do it, visit NOTE: **Note:** To delete an epic, you need to be an [Owner](../../permissions.md#group-members-permissions) of a group/subgroup. -When editing the description of an epic, click the **Delete** button to delete the epic. +When editing the description of an epic, select the **Delete** button to delete the epic. A modal appears to confirm your action. Deleting an epic releases all existing issues from their associated epic in the system. @@ -92,7 +92,7 @@ Deleting an epic releases all existing issues from their associated epic in the Whenever you decide that there is no longer need for that epic, close the epic by: -- Clicking the **Close epic** button. +- Selecting the **Close epic** button.  @@ -129,7 +129,7 @@ that of Issues and Merge Requests) based on following parameters:  -To search, go to the list of epics and click the field **Search or filter results**. +To search, go to the list of epics and select the field **Search or filter results**. It will display a dropdown menu, from which you can add an author. You can also enter plain text to search by epic title or description. When done, press <kbd>Enter</kbd> on your keyboard to filter the list. @@ -168,7 +168,7 @@ To make an epic confidential: ### Add a new issue to an epic -You can add an existing issue to an epic, or, create a new issue that's +You can add an existing issue to an epic, or create a new issue that's automatically added to the epic. #### Add an existing issue to an epic @@ -183,15 +183,15 @@ current parent. To add a new issue to an epic: -1. Click the **Add** dropdown button. -1. Click **Add a new issue**. +1. On the epic's page, under **Epics and Issues**, select the **Add** dropdown button. +1. Select **Add an existing issue**. 1. Identify the issue to be added, using either of the following methods: - Paste the link of the issue. - Search for the desired issue by entering part of the issue's title, then selecting the desired match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/9126)). If there are multiple issues to be added, press <kbd>Spacebar</kbd> and repeat this step. -1. Click **Add**. +1. Select **Add**. #### Create an issue from an epic @@ -202,11 +202,11 @@ while dividing work into smaller parts. To create an issue from an epic: -1. On the epic's page, under **Epics and Issues**, click the **Add** dropdown button and select - **Create new issue**. +1. On the epic's page, under **Epics and Issues**, select the **Add** dropdown button. +1. Select **Add a new issue**. 1. Under **Title**, enter the title for the new issue. 1. From the **Project** dropdown, select the project in which the issue should be created. -1. Click **Create issue**. +1. Select **Create issue**. ### Remove an issue from an epic @@ -215,9 +215,9 @@ After you remove an issue from an epic, the issue will no longer be associated w To remove an issue from an epic: -1. Click the **Remove** (**{close}**) button next to the issue you want to remove. +1. Select the **Remove** (**{close}**) button next to the issue you want to remove. The **Remove issue** warning appears. -1. Click **Remove**. +1. Select **Remove**.  @@ -285,15 +285,15 @@ For more on epic templates, see [Epic Templates - Repeatable sets of issues](htt To add a child epic to an epic: -1. Click the **Add** dropdown button. -1. Click **Add a new epic**. +1. Select the **Add** dropdown button. +1. Select **Add a new epic**. 1. Identify the epic to be added, using either of the following methods: - Paste the link of the epic. - Search for the desired issue by entering part of the epic's title, then selecting the desired match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/9126)). If there are multiple epics to be added, press <kbd>Spacebar</kbd> and repeat this step. -1. Click **Add**. +1. Select **Add**. ### Move child epics between epics @@ -325,5 +325,5 @@ To reorder child epics assigned to an epic: To remove a child epic from a parent epic: -1. Click on the <kbd>x</kbd> button in the parent epic's list of epics. -1. Click **Remove** in the **Remove epic** warning message. +1. Select the <kbd>x</kbd> button in the parent epic's list of epics. +1. Select **Remove** in the **Remove epic** warning message. diff --git a/doc/user/group/img/add_new_members.png b/doc/user/group/img/add_new_members.png Binary files differdeleted file mode 100644 index 8bd9e2374bc..00000000000 --- a/doc/user/group/img/add_new_members.png +++ /dev/null diff --git a/doc/user/group/img/add_new_members_v13_6.png b/doc/user/group/img/add_new_members_v13_6.png Binary files differnew file mode 100644 index 00000000000..4255eeb72c7 --- /dev/null +++ b/doc/user/group/img/add_new_members_v13_6.png diff --git a/doc/user/group/img/create_new_project_from_group.png b/doc/user/group/img/create_new_project_from_group.png Binary files differdeleted file mode 100644 index df98091334c..00000000000 --- a/doc/user/group/img/create_new_project_from_group.png +++ /dev/null diff --git a/doc/user/group/img/create_new_project_from_group_v13_6.png b/doc/user/group/img/create_new_project_from_group_v13_6.png Binary files differnew file mode 100644 index 00000000000..72d19817686 --- /dev/null +++ b/doc/user/group/img/create_new_project_from_group_v13_6.png diff --git a/doc/user/group/img/manual_permissions_v13_1.png b/doc/user/group/img/manual_permissions_v13_1.png Binary files differdeleted file mode 100644 index 0ada9a4839c..00000000000 --- a/doc/user/group/img/manual_permissions_v13_1.png +++ /dev/null diff --git a/doc/user/group/img/manual_permissions_v13_6.png b/doc/user/group/img/manual_permissions_v13_6.png Binary files differnew file mode 100644 index 00000000000..6d26061b049 --- /dev/null +++ b/doc/user/group/img/manual_permissions_v13_6.png diff --git a/doc/user/group/img/restrict-by-email.gif b/doc/user/group/img/restrict-by-email.gif Binary files differnew file mode 100644 index 00000000000..d1ebeb07a0a --- /dev/null +++ b/doc/user/group/img/restrict-by-email.gif diff --git a/doc/user/group/img/restrict-by-ip.gif b/doc/user/group/img/restrict-by-ip.gif Binary files differnew file mode 100644 index 00000000000..6292a58e748 --- /dev/null +++ b/doc/user/group/img/restrict-by-ip.gif diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 2c838724cb3..e09c685147a 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -130,7 +130,7 @@ give a user access to all projects in the group with one action. Add members to a group by navigating to the group's dashboard and clicking **Members**. - + Select the [permission level](../permissions.md#permissions), and add the new member. You can also set the expiring date for that user; this is the date on which they will no longer have access to your group. @@ -235,7 +235,7 @@ There are two different ways to add a new project to a group: - Select a group, and then click **New project**. You can then continue [creating your project](../../gitlab-basics/create-project.md). -  +  - While you are creating a project, select a group namespace you've already created from the dropdown menu. @@ -375,9 +375,9 @@ In GitLab [8.15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/822) and 1. Go to your group's **Members** page. 1. Select the pencil icon in the row for the user you are editing. -1. Select the orange `Change permissions` button. +1. Select the brown `Edit permissions` button in the modal. - + Now you will be able to edit the user's permissions from the **Members** page. @@ -394,13 +394,6 @@ milestones. ## Group wikis **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. -> - It's [deployed behind a feature flag](../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-group-wikis). - -CAUTION: **Warning:** -This feature might not be available to you. Check the **version history** note above for details. Group wikis work the same way as [project wikis](../project/wiki/index.md), please refer to those docs for details on usage. @@ -414,27 +407,13 @@ There are a few limitations compared to project wikis: - Local Git access is not supported yet. - Group wikis are not included in global search, group exports, backups, and Geo replication. - Changes to group wikis don't show up in the group's activity feed. +- Group wikis [can't be moved](../../api/project_repository_storage_moves.md#limitations) using the project + repository moves API. -You can follow [this epic](https://gitlab.com/groups/gitlab-org/-/epics/2782) for updates. - -### Enable or disable group wikis **(CORE ONLY)** - -Group wikis are under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable it for your instance. - -To enable it: +For updates, you can follow: -```ruby -Feature.enable(:group_wikis) -``` - -To disable it: - -```ruby -Feature.disable(:group_wikis) -``` +- [The epic tracking feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). +- [The issue for adding the ability to move group wikis using the API](https://gitlab.com/gitlab-org/gitlab/-/issues/219003). ## Group Security Dashboard **(ULTIMATE)** @@ -513,6 +492,23 @@ If you want to retain ownership over the original namespace and protect the URL redirects, then instead of changing a group's path or renaming a username, you can create a new group and transfer projects to it. +### Group repository settings + +You can change settings that are specific to repositories in your group. + +#### Custom initial branch name **(CORE ONLY)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43290) in GitLab 13.6. + +By default, when you create a new project in GitLab, the initial branch is called `master`. +For groups, a group administrator can customize the initial branch name to something +else. This way, every new project created under that group from then on will start from the custom branch name rather than `master`. To do so: + +1. Go to the **Group page > Settings > Repository** and expand **Default initial + branch name**. +1. Change the default initial branch to a custom name of your choice. +1. **Save Changes**. + ### Remove a group To remove a group and its contents: @@ -525,7 +521,10 @@ To remove a group and its contents: This action either: - Removes the group, and also queues a background job to delete all projects in that group. -- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/premium/) or higher tiers, marks a group for deletion. The deletion will happen 7 days later by default, but this can be changed in the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/premium/) or higher tiers, this action adds a background job to mark a group for deletion. By default, the job schedules the deletion 7 days in the future. You can modify this waiting period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). + +Since [GitLab 13.6](https://gitlab.com/gitlab-org/gitlab/-/issues/39504), if the user who sets up the deletion leaves or is otherwise removed from the group before the +actual deletion happens, the job is cancelled, and the group is no longer scheduled for deletion. ### Restore a group **(PREMIUM)** @@ -608,6 +607,8 @@ To enable this feature: 1. Expand the **Permissions, LFS, 2FA** section, and enter IP address ranges into **Allow access to the following IP addresses** field. 1. Click **Save changes**. + + #### Allowed domain restriction **(PREMIUM)** >- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7297) in [GitLab Premium and Silver](https://about.gitlab.com/pricing/) 12.2. @@ -636,6 +637,8 @@ To enable this feature: 1. Expand the **Permissions, LFS, 2FA** section, and enter the domain names into **Restrict membership by email** field. 1. Click **Save changes**. + + This will enable the domain-checking for all new users added to the group from this moment on. #### Group file templates **(PREMIUM)** @@ -742,6 +745,7 @@ To enable prevent project forking: - **Audit Events**: View [Audit Events](../../administration/audit_events.md) for the group. **(STARTER ONLY)** - **Pipelines quota**: Keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group. +- **Integrations**: Configure [integrations](../admin_area/settings/project_integration_management.md) for your group. #### Storage usage quota **(STARTER)** @@ -794,7 +798,7 @@ With [GitLab Issue Analytics](issues_analytics/index.md), you can see a bar char With [GitLab Repositories Analytics](repositories_analytics/index.md), you can download a CSV of the latest coverage data for all the projects in your group. -## Dependency Proxy **(PREMIUM)** +## Dependency Proxy Use GitLab as a [dependency proxy](../packages/dependency_proxy/index.md) for upstream Docker images. diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index dd1f8914392..50dfb0e5ccd 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Analytics +group: Value Stream Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 69512f90fca..dea1eaba819 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Analytics +group: Value Stream Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 2eb50f07de3..90050e217ee 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - It's enabled on GitLab.com. > - It's able to be enabled or disabled per-group. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iterations). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iterations). **(STARTER ONLY)** Iterations are a way to track issues over a period of time. This allows teams to track velocity and volatility metrics. Iterations can be used with [milestones](../../project/milestones/index.md) @@ -50,7 +50,7 @@ To create an iteration: ## Edit an iteration -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. NOTE: **Note:** You need Developer [permissions](../../permissions.md) or higher to edit an iteration. @@ -73,7 +73,23 @@ An iteration report displays a list of all the issues assigned to an iteration a To view an iteration report, go to the iterations list page and click an iteration's title. -## Disable Iterations **(CORE ONLY)** +### Iteration burndown and burnup charts + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222750) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. +> - It was deployed behind a feature flag, disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45492) on GitLab 13.6. +> - It's enabled on GitLab.com. +> - It's able to be enabled or disabled per-group. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iteration-charts). **(STARTER ONLY)** + +The iteration report includes [burndown and burnup charts](../../project/milestones/burndown_and_burnup_charts.md), +similar to how they appear when viewing a [milestone](../../project/milestones/index.md). + +Burndown charts help track completion progress of total scope, and burnup charts track the daily +total count and weight of issues added to and completed in a given timebox. + +## Disable iterations **(STARTER ONLY)** GitLab Iterations feature is deployed with a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) @@ -97,6 +113,30 @@ Feature.disable(:group_iterations) Feature.disable(:group_iterations, Group.find(<group ID>)) ``` +## Disable iteration charts **(STARTER ONLY)** + +GitLab iteration charts feature is deployed with a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can disable it for your instance. `:iteration_charts` can be enabled or disabled per-group. + +To enable it: + +```ruby +# Instance-wide +Feature.enable(:iteration_charts) +# or by group +Feature.enable(:iteration_charts, Group.find(<group ID>)) +``` + +To disable it: + +```ruby +# Instance-wide +Feature.disable(:iteration_charts) +# or by group +Feature.disable(:iteration_charts, Group.find(<group ID>)) +``` + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index c9a10146440..fe5e7979592 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -12,6 +12,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w CAUTION: **Warning:** This feature might not be available to you. Check the **version history** note above for details. +## Latest project test coverage list + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267624) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. + +To see the latest code coverage for each project in your group: + +1. Go to **Analytics > Repositories** in the group (not from a project). +1. In the **Latest test coverage results** section, use the **Select projects** dropdown to choose the projects you want to check. + +## Download historic test coverage data + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. + You can get a CSV of the code coverage data for all of the projects in your group. This report has a maximum of 1000 records. To get the report: 1. Go to your group's **Analytics > Repositories** page diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index c185055f6b2..f9d49c1236e 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -1,7 +1,7 @@ --- type: reference stage: Plan -group: Portfolio Management +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/#designated-technical-writers --- diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index 7497d036d31..50f062bafa9 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w CAUTION: **Caution:** This [Closed Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#sts=Closed%20Beta) feature is being re-evaluated in favor of a different -[identity model](https://gitlab.com/gitlab-org/gitlab/-/issues/218631) that does not require separate accounts. +[identity model](https://gitlab.com/groups/gitlab-org/-/epics/4345) that does not require separate accounts. We recommend that group administrators who haven't yet implemented this feature wait for the new solution. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 3cb566c7f77..94d2c9afb24 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -88,8 +88,6 @@ We intend to add a similar SSO requirement for [Git and API activity](https://gi When SSO enforcement is enabled for a group, users cannot share a project in the group outside the top-level group, even if the project is forked. -To disallow users to contribute outside of the top-level group, please see [Group Managed Accounts](group_managed_accounts.md). - ## Providers NOTE: **Note:** @@ -107,7 +105,7 @@ When [configuring your identify provider](#configuring-your-identity-provider), ### Azure setup notes <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). +For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). Please note that the video is outdated in regards to objectID mapping and the [SCIM documentation should be followed](scim_setup.md#azure-configuration-steps). | GitLab Setting | Azure Field | |--------------|----------------| @@ -136,7 +134,7 @@ For a demo of the Okta SAML setup including SCIM, see [Demo: Okta Group SAML & S Under Okta's **Single sign-on URL** field, check the option **Use this for Recipient URL and Destination URL**. -We recommend: +For NameID, the following settings are recommended; for SCIM, the following settings are required: - **Application username** (NameID) set to **Custom** `user.getInternalProperty("id")`. - **Name ID Format** set to **Persistent**. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index c6444ada165..7c089a289c6 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -121,8 +121,12 @@ Once synchronized, changing the field mapped to `id` and `externalId` may cause ### Okta configuration steps -The SAML application that was created during [Single sign-on](index.md#okta-setup-notes) setup for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/) now needs to be set up for SCIM. -Before proceeding, be sure to complete the [GitLab configuration](#gitlab-configuration) process. +Before you start this section, complete the [GitLab configuration](#gitlab-configuration) process. +Make sure that you've also set up a SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/), +as described in the [Okta setup notes](index.md#okta-setup-notes) + +Make sure that the Okta setup matches our documentation exactly, especially the NameID +configuration. Otherwise, the Okta SCIM app may not work properly. 1. Sign in to Okta. 1. If you see an **Admin** button in the top right, click the button. This will @@ -212,39 +216,7 @@ When the user is added back to the SCIM app, GitLab cannot create a new user bec Solution: Have a user sign in directly to GitLab, then [manually link](#user-access-and-linking-setup) their account. -### Azure - -#### How do I verify my SCIM configuration is correct? - -Review the following: - -- Ensure that the SCIM value for `id` matches the SAML value for `NameId`. -- Ensure that the SCIM value for `externalId` matches the SAML value for `NameId`. - -Review the following SCIM parameters for sensible values: - -- `userName` -- `displayName` -- `emails[type eq "work"].value` - -#### Testing Azure connection: invalid credentials - -When testing the connection, you may encounter an error: **You appear to have entered invalid credentials. Please confirm you are using the correct information for an administrative account**. If `Tenant URL` and `secret token` are correct, check whether your group path contains characters that may be considered invalid JSON primitives (such as `.`). Removing such characters from the group path typically resolves the error. - -#### Azure: (Field) can't be blank sync error - -When checking the Audit Logs for the Provisioning, you can sometimes see the -error `Namespace can't be blank, Name can't be blank, and User can't be blank.` - -This is likely caused because not all required fields (such as first name and last name) are present for all users being mapped. - -As a workaround, try an alternate mapping: - -1. Follow the Azure mapping instructions from above. -1. Delete the `name.formatted` target attribute entry. -1. Change the `displayName` source attribute to have `name.formatted` target attribute. - -#### How do I diagnose why a user is unable to sign in +### How do I diagnose why a user is unable to sign in Ensure that the user has been added to the SCIM app. @@ -254,9 +226,9 @@ The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenev This value is also used by SCIM to match users on the `id`, and is updated by SCIM whenever the `id` or `externalId` values change. -It is important that this SCIM `id` and SCIM `externalId` are configured to the same value as the SAML `NameId`. SAML responses can be traced using [debugging tools](./index.md#saml-debugging-tools), and any errors can be checked against our [SAML troubleshooting docs](./index.md#troubleshooting). +It is important that this SCIM `id` and SCIM `externalId` are configured to the same value as the SAML `NameId`. SAML responses can be traced using [debugging tools](index.md#saml-debugging-tools), and any errors can be checked against our [SAML troubleshooting docs](index.md#troubleshooting). -#### How do I verify user's SAML NameId matches the SCIM externalId +### How do I verify user's SAML NameId matches the SCIM externalId Group owners can see the list of users and the `externalId` stored for each user in the group SAML SSO Settings page. @@ -264,7 +236,7 @@ A possible alternative is to use the [SCIM API](../../../api/scim.md#get-a-list- To see how the `external_uid` compares to the value returned as the SAML NameId, you can have the user use a [SAML Tracer](index.md#saml-debugging-tools). -#### Update or fix mismatched SCIM externalId and SAML NameId +### Update or fix mismatched SCIM externalId and SAML NameId Whether the value was changed or you need to map to a different field, ensure `id`, `externalId`, and `NameId` all map to the same field. @@ -277,15 +249,47 @@ that provider may create duplicate users. If the `externalId` for a user is not correct, and also doesn't match the SAML NameID, you can address the problem in the following ways: -- You can have users unlink and relink themselves, based on the ["SAML authentication failed: User has already been taken"](./index.md#message-saml-authentication-failed-user-has-already-been-taken) section. +- You can have users unlink and relink themselves, based on the ["SAML authentication failed: User has already been taken"](index.md#message-saml-authentication-failed-user-has-already-been-taken) section. - You can unlink all users simultaneously, by removing all users from the SAML app while provisioning is turned on. - It may be possible to use the [SCIM API](../../../api/scim.md#update-a-single-saml-user) to manually correct the `externalId` stored for users to match the SAML `NameId`. To look up a user, you'll need to know the desired value that matches the `NameId` as well as the current `externalId`. It is important not to update these to incorrect values, since this will cause users to be unable to sign in. It is also important not to assign a value to the wrong user, as this would cause users to get signed into the wrong account. -#### I need to change my SCIM app +### I need to change my SCIM app -Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](./index.md#i-need-to-change-my-saml-app) section. +Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](index.md#i-need-to-change-my-saml-app) section. Alternatively, users can be removed from the SCIM app which will delink all removed users. Sync can then be turned on for the new SCIM app to [link existing users](#user-access-and-linking-setup). + +### Azure + +#### How do I verify my SCIM configuration is correct? + +Review the following: + +- Ensure that the SCIM value for `id` matches the SAML value for `NameId`. +- Ensure that the SCIM value for `externalId` matches the SAML value for `NameId`. + +Review the following SCIM parameters for sensible values: + +- `userName` +- `displayName` +- `emails[type eq "work"].value` + +#### Testing Azure connection: invalid credentials + +When testing the connection, you may encounter an error: **You appear to have entered invalid credentials. Please confirm you are using the correct information for an administrative account**. If `Tenant URL` and `secret token` are correct, check whether your group path contains characters that may be considered invalid JSON primitives (such as `.`). Removing such characters from the group path typically resolves the error. + +#### (Field) can't be blank sync error + +When checking the Audit Logs for the Provisioning, you can sometimes see the +error `Namespace can't be blank, Name can't be blank, and User can't be blank.` + +This is likely caused because not all required fields (such as first name and last name) are present for all users being mapped. + +As a workaround, try an alternate mapping: + +1. Follow the Azure mapping instructions from above. +1. Delete the `name.formatted` target attribute entry. +1. Change the `displayName` source attribute to have `name.formatted` target attribute. diff --git a/doc/user/group/settings/img/new_group_navigation_v13_1.png b/doc/user/group/settings/img/new_group_navigation_v13_1.png Binary files differindex 98d45a694b6..307175727c7 100644 --- a/doc/user/group/settings/img/new_group_navigation_v13_1.png +++ b/doc/user/group/settings/img/new_group_navigation_v13_1.png diff --git a/doc/user/group/subgroups/img/create_subgroup_button.png b/doc/user/group/subgroups/img/create_subgroup_button.png Binary files differdeleted file mode 100644 index d1355d4b2c3..00000000000 --- a/doc/user/group/subgroups/img/create_subgroup_button.png +++ /dev/null diff --git a/doc/user/group/subgroups/img/create_subgroup_button_v13_6.png b/doc/user/group/subgroups/img/create_subgroup_button_v13_6.png Binary files differnew file mode 100644 index 00000000000..013aee6b0b4 --- /dev/null +++ b/doc/user/group/subgroups/img/create_subgroup_button_v13_6.png diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 6de38354c5e..268014a3cd2 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto, concepts --- @@ -80,7 +83,10 @@ By default, groups created in: - GitLab 12.2 or later allow both Owners and Maintainers to create subgroups. - GitLab 12.1 or earlier only allow Owners to create subgroups. -This setting can be for any group by an Owner or Administrator. +The setting can be changed for any group by: + +- A group owner. Select the group, and navigate to **Settings > General > Permissions, LFS, 2FA**. +- An administrator. Navigate to **Admin Area > Overview > Groups**, select the group, and choose **Edit**. For more information check the [permissions table](../../permissions.md#group-members-permissions). For a list @@ -93,10 +99,9 @@ creation is disabled by an administrator in their settings. To create a subgroup: -1. In the group's dashboard expand the **New project** split button, select - **New subgroup** and click the **New subgroup** button. +1. In the group's dashboard click the **New subgroup** button. -  +  1. Create a new group like you would normally do. Notice that the immediate parent group namespace is fixed under **Group path**. The visibility level can differ from diff --git a/doc/user/img/unordered_check_list_render_gfm.png b/doc/user/img/unordered_check_list_render_gfm.png Binary files differdeleted file mode 100644 index 2ce0fb95645..00000000000 --- a/doc/user/img/unordered_check_list_render_gfm.png +++ /dev/null diff --git a/doc/user/index.md b/doc/user/index.md index 32a1c235882..8701b5e038b 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, index description: 'Read through the GitLab User documentation to learn how to use, configure, and customize GitLab and GitLab.com to your own needs.' --- @@ -69,6 +72,17 @@ With GitLab Enterprise Edition, you can also: You can also [integrate](project/integrations/overview.md) GitLab with numerous third-party applications, such as Mattermost, Microsoft Teams, HipChat, Trello, Slack, Bamboo CI, Jira, and a lot more. +## User types + +There are several types of users in GitLab: + +- Regular users and GitLab.com users. <!-- Note: further description TBA --> +- [Groups](group/index.md) of users. +- GitLab [admin area](admin_area/index.md) user. +- [GitLab Administrator](../administration/index.md) with full access to + self-managed instances' features and settings. +- [Internal users](../development/internal_users.md). + ## Projects In GitLab, you can create [projects](project/index.md) to host @@ -84,18 +98,6 @@ it all at once, from one single project. - [Milestones](project/milestones/index.md): Work on multiple issues and merge requests towards the same target date with Milestones. -## GitLab CI/CD - -Use built-in [GitLab CI/CD](../ci/README.md) to test, build, and deploy your applications -directly from GitLab. No third-party integrations needed. - -- [GitLab Auto Deploy](../topics/autodevops/stages.md#auto-deploy): Deploy your application out-of-the-box with GitLab Auto Deploy. -- [Review Apps](../ci/review_apps/index.md): Live-preview the changes introduced by a merge request with Review Apps. -- [GitLab Pages](project/pages/index.md): Publish your static site directly from - GitLab with GitLab Pages. You can build, test, and deploy any Static Site Generator with Pages. -- [GitLab Container Registry](packages/container_registry/index.md): Build and deploy Docker - images with Container Registry. - ## Account There is a lot you can customize and configure @@ -151,6 +153,11 @@ requests you're assigned to. you have quick access to. You can also gather feedback on them through [Discussions](#discussions). +## GitLab CI/CD + +Use built-in [GitLab CI/CD](../ci/README.md) to test, build, and deploy your applications +directly from GitLab. No third-party integrations needed. + ## Features behind feature flags Understand what [features behind feature flags](feature_flags.md) mean. diff --git a/doc/user/infrastructure/img/terraform_list_view_v13_5.png b/doc/user/infrastructure/img/terraform_list_view_v13_5.png Binary files differnew file mode 100644 index 00000000000..b23dfa6289e --- /dev/null +++ b/doc/user/infrastructure/img/terraform_list_view_v13_5.png diff --git a/doc/user/infrastructure/img/terraform_plan_widget_v13_0.png b/doc/user/infrastructure/img/terraform_plan_widget_v13_0.png Binary files differdeleted file mode 100644 index 62bf4b279b2..00000000000 --- a/doc/user/infrastructure/img/terraform_plan_widget_v13_0.png +++ /dev/null diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index cee6e21a5c5..4af18873798 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -13,35 +13,7 @@ workflows to tie into GitLab's authentication and authorization. These features lowering the barrier to entry for teams to adopt Terraform, collaborate effectively within GitLab, and support Terraform best practices. -## Quick Start - -Use the following `.gitlab-ci.yml` to set up a simple Terraform project integration -for GitLab versions 13.5 and greater: - -```yaml -include: - - template: Terraform.latest.gitlab-ci.yml - -variables: - # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables - TF_STATE_NAME: default - TF_CACHE_KEY: default -``` - -This template uses `.latest.`, instead of stable, and may include breaking changes. -This template also includes some opinionated decisions, which you can override: - -- Including the latest [GitLab Terraform Image](https://gitlab.com/gitlab-org/terraform-images). -- Using the [GitLab managed Terraform State](#gitlab-managed-terraform-state) as - the Terraform state storage backend. -- Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml): - `init`, `validate`, `build`, and `deploy`. These stages - [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml) - `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on `master`. - -## GitLab managed Terraform State - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. +## GitLab Managed Terraform state [Terraform remote backends](https://www.terraform.io/docs/backends/index.html) enable you to store the state file in a remote, shared store. GitLab uses the @@ -57,507 +29,36 @@ Amazon S3 or Google Cloud Storage. Its features include: - Locking and unlocking state. - Remote Terraform plan and apply execution. -To get started with a GitLab-managed Terraform State, there are two different options: - -- [Use a local machine](#get-started-using-local-development). -- [Use GitLab CI](#get-started-using-gitlab-ci). - -## Permissions for using Terraform - -In GitLab version 13.1, [Maintainer access](../permissions.md) was required to use a -GitLab managed Terraform state backend. In GitLab versions 13.2 and greater, -[Maintainer access](../permissions.md) is required to lock, unlock and write to the state -(using `terraform apply`), while [Developer access](../permissions.md) is required to read -the state (using `terraform plan -lock=false`). - -## Get started using local development - -If you plan to only run `terraform plan` and `terraform apply` commands from your -local machine, this is a simple way to get started: - -1. Create your project on your GitLab instance. -1. Navigate to **Settings > General** and note your **Project name** - and **Project ID**. -1. Define the Terraform backend in your Terraform project to be: - - ```hcl - terraform { - backend "http" { - } - } - ``` - -1. Create a [Personal Access Token](../profile/personal_access_tokens.md) with - the `api` scope. - -1. On your local machine, run `terraform init`, passing in the following options, - replacing `<YOUR-STATE-NAME>`, `<YOUR-PROJECT-ID>`, `<YOUR-USERNAME>` and - `<YOUR-ACCESS-TOKEN>` with the relevant values. This command initializes your - Terraform state, and stores that state within your GitLab project. The name of - your state can contain only uppercase and lowercase letters, decimal digits, - hyphens, and underscores. This example uses `gitlab.com`: - - ```shell - terraform init \ - -backend-config="address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>" \ - -backend-config="lock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ - -backend-config="unlock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ - -backend-config="username=<YOUR-USERNAME>" \ - -backend-config="password=<YOUR-ACCESS-TOKEN>" \ - -backend-config="lock_method=POST" \ - -backend-config="unlock_method=DELETE" \ - -backend-config="retry_wait_min=5" - ``` - -You can now run `terraform plan` and `terraform apply` as you normally would. - -## Get started using GitLab CI - -If you don't want to start with local development, you can also use GitLab CI to -run your `terraform plan` and `terraform apply` commands. - -Next, [configure the backend](#configure-the-backend). - -## Configure the backend - -After executing the `terraform init` command, you must configure the Terraform backend -and the CI YAML file: - -1. In your Terraform project, define the [HTTP backend](https://www.terraform.io/docs/backends/types/http.html) - by adding the following code block in a `.tf` file (such as `backend.tf`) to - define the remote backend: - - ```hcl - terraform { - backend "http" { - } - } - ``` - -1. In the root directory of your project repository, configure a - `.gitlab-ci.yaml` file. This example uses a pre-built image which includes a - `gitlab-terraform` helper. For supported Terraform versions, see the [GitLab - Terraform Images project](https://gitlab.com/gitlab-org/terraform-images). - - ```yaml - image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest - ``` - -1. In the `.gitlab-ci.yaml` file, define some environment variables to ease - development. In this example, `TF_ROOT` is the directory where the Terraform - commands must be executed, `TF_ADDRESS` is the URL to the state on the GitLab - instance where this pipeline runs, and the final path segment in `TF_ADDRESS` - is the name of the Terraform state. Projects may have multiple states, and - this name is arbitrary, so in this example we set it to `example-production` - which corresponds with the directory we're using as our `TF_ROOT`, and we - ensure that the `.terraform` directory is cached between jobs in the pipeline - using a cache key based on the state name (`example-production`): - - ```yaml - variables: - TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production - TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production - - cache: - key: example-production - paths: - - ${TF_ROOT}/.terraform - ``` - -1. In a `before_script`, change to your `TF_ROOT`: - - ```yaml - before_script: - - cd ${TF_ROOT} - - stages: - - prepare - - validate - - build - - deploy - - init: - stage: prepare - script: - - gitlab-terraform init - - validate: - stage: validate - script: - - gitlab-terraform validate - - plan: - stage: build - script: - - gitlab-terraform plan - - gitlab-terraform plan-json - artifacts: - name: plan - paths: - - ${TF_ROOT}/plan.cache - reports: - terraform: ${TF_ROOT}/plan.json - - apply: - stage: deploy - environment: - name: production - script: - - gitlab-terraform apply - dependencies: - - plan - when: manual - only: - - master - ``` - -1. Push your project to GitLab, which triggers a CI job pipeline. This pipeline - runs the `gitlab-terraform init`, `gitlab-terraform validate`, and - `gitlab-terraform plan` commands. - -The output from the above `terraform` commands should be viewable in the job logs. - -CAUTION: **Caution:** -Like any other job artifact, Terraform plan data is [viewable by anyone with Guest access](../permissions.md) to the repository. -Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan -includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly -recommends encrypting plan output or modifying the project visibility settings. - -## Example project - -See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 within a custom VPC. - -## Copy Terraform state between backends - -Terraform supports copying the state when the backend is changed or -reconfigured. This can be useful if you need to migrate from another backend to -GitLab managed Terraform state. It's also useful if you need to change the state -name as in the following example: - -```shell -PROJECT_ID="<gitlab-project-id>" -TF_USERNAME="<gitlab-username>" -TF_PASSWORD="<gitlab-personal-access-token>" -TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/old-state-name" - -terraform init \ - -backend-config=address=${TF_ADDRESS} \ - -backend-config=lock_address=${TF_ADDRESS}/lock \ - -backend-config=unlock_address=${TF_ADDRESS}/lock \ - -backend-config=username=${TF_USERNAME} \ - -backend-config=password=${TF_PASSWORD} \ - -backend-config=lock_method=POST \ - -backend-config=unlock_method=DELETE \ - -backend-config=retry_wait_min=5 -``` - -```plaintext -Initializing the backend... - -Successfully configured the backend "http"! Terraform will automatically -use this backend unless the backend configuration changes. - -Initializing provider plugins... - -Terraform has been successfully initialized! - -You may now begin working with Terraform. Try running "terraform plan" to see -any changes that are required for your infrastructure. All Terraform commands -should now work. - -If you ever set or change modules or backend configuration for Terraform, -rerun this command to reinitialize your working directory. If you forget, other -commands will detect it and remind you to do so if necessary. -``` - -Now that `terraform init` has created a `.terraform/` directory that knows where -the old state is, you can tell it about the new location: - -```shell -TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/new-state-name" - -terraform init \ - -backend-config=address=${TF_ADDRESS} \ - -backend-config=lock_address=${TF_ADDRESS}/lock \ - -backend-config=unlock_address=${TF_ADDRESS}/lock \ - -backend-config=username=${TF_USERNAME} \ - -backend-config=password=${TF_PASSWORD} \ - -backend-config=lock_method=POST \ - -backend-config=unlock_method=DELETE \ - -backend-config=retry_wait_min=5 -``` - -```plaintext -Initializing the backend... -Backend configuration changed! - -Terraform has detected that the configuration specified for the backend -has changed. Terraform will now check for existing state in the backends. - - -Acquiring state lock. This may take a few moments... -Do you want to copy existing state to the new backend? - Pre-existing state was found while migrating the previous "http" backend to the - newly configured "http" backend. No existing state was found in the newly - configured "http" backend. Do you want to copy this state to the new "http" - backend? Enter "yes" to copy and "no" to start with an empty state. - - Enter a value: yes - - -Successfully configured the backend "http"! Terraform will automatically -use this backend unless the backend configuration changes. - -Initializing provider plugins... - -Terraform has been successfully initialized! - -You may now begin working with Terraform. Try running "terraform plan" to see -any changes that are required for your infrastructure. All Terraform commands -should now work. - -If you ever set or change modules or backend configuration for Terraform, -rerun this command to reinitialize your working directory. If you forget, other -commands will detect it and remind you to do so if necessary. -``` - -If you type `yes`, it copies your state from the old location to the new -location. You can then go back to running it from within GitLab CI. - -## Output Terraform Plan information into a merge request - -Using the [GitLab Terraform Report artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform), -you can expose details from `terraform plan` runs directly into a merge request widget, -enabling you to see statistics about the resources that Terraform creates, -modifies, or destroys. +Read more on setting up and [using GitLab Managed Terraform states](terraform_state.md) -Let's explore how to configure a GitLab Terraform Report artifact. You can -either use a pre-built image which includes a `gitlab-terraform` helper as -above, where `gitlab-terraform plan-json` outputs the required artifact, or you -can configure this manually as follows: +## Terraform integration in Merge Requests -1. For simplicity, let's define a few reusable variables to allow us to - refer to these files multiple times: +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. - ```yaml - variables: - PLAN: plan.cache - PLAN_JSON: plan.json - ``` +Read more on setting up and [using the merge request integrations](mr_integration.md). -1. Install `jq`, a - [lightweight and flexible command-line JSON processor](https://stedolan.github.io/jq/). -1. Create an alias for a specific `jq` command that parses out the information we - want to extract from the `terraform plan` output: - - ```yaml - before_script: - - apk --no-cache add jq - - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" - ``` - - NOTE: **Note:** - In distributions that use Bash (for example, Ubuntu), `alias` statements are not - expanded in non-interactive mode. If your pipelines fail with the error - `convert_report: command not found`, alias expansion can be activated explicitly - by adding a `shopt` command to your script: - - ```yaml - before_script: - - shopt -s expand_aliases - - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" - ``` - -1. Define a `script` that runs `terraform plan` and `terraform show`. These commands - pipe the output and convert the relevant bits into a store variable `PLAN_JSON`. - This JSON is used to create a - [GitLab Terraform Report artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform). - The Terraform report obtains a Terraform `tfplan.json` file. The collected - Terraform plan report is uploaded to GitLab as an artifact, and is shown in merge requests. - - ```yaml - plan: - stage: build - script: - - terraform plan -out=$PLAN - - terraform show --json $PLAN | convert_report > $PLAN_JSON - artifacts: - reports: - terraform: $PLAN_JSON - ``` - - For a full example using the pre-built image, see [Example `.gitlab-ci.yaml` - file](#example-gitlab-ciyaml-file). - - For an example displaying multiple reports, see [`.gitlab-ci.yaml` multiple reports file](#multiple-terraform-plan-reports). - -1. Running the pipeline displays the widget in the merge request, like this: - -  - -1. Clicking the **View Full Log** button in the widget takes you directly to the - plan output present in the pipeline logs: - -  +## Quick Start -### Example `.gitlab-ci.yaml` file +Use the following `.gitlab-ci.yml` to set up a simple Terraform project integration +for GitLab versions 13.5 and greater: ```yaml -default: - image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest - - cache: - key: example-production - paths: - - ${TF_ROOT}/.terraform +include: + - template: Terraform.latest.gitlab-ci.yml variables: - TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production - TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production - -before_script: - - cd ${TF_ROOT} - -stages: - - prepare - - validate - - build - - deploy - -init: - stage: prepare - script: - - gitlab-terraform init - -validate: - stage: validate - script: - - gitlab-terraform validate - -plan: - stage: build - script: - - gitlab-terraform plan - - gitlab-terraform plan-json - artifacts: - name: plan - paths: - - ${TF_ROOT}/plan.cache - reports: - terraform: ${TF_ROOT}/plan.json - -apply: - stage: deploy - environment: - name: production - script: - - gitlab-terraform apply - dependencies: - - plan - when: manual - only: - - master -``` - -### Multiple Terraform Plan reports - -Starting with GitLab version 13.2, you can display multiple reports on the Merge Request -page. The reports also display the `artifacts: name:`. See example below for a suggested setup. - -```yaml -default: - image: - name: registry.gitlab.com/gitlab-org/gitlab-build-images:terraform - entrypoint: - - '/usr/bin/env' - - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' - - cache: - paths: - - .terraform - -stages: - - build - -.terraform-plan-generation: - stage: build - variables: - PLAN: plan.tfplan - JSON_PLAN_FILE: tfplan.json - before_script: - - cd ${TERRAFORM_DIRECTORY} - - terraform --version - - terraform init - - apk --no-cache add jq - script: - - terraform validate - - terraform plan -out=${PLAN} - - terraform show --json ${PLAN} | jq -r '([.resource_changes[]?.change.actions?]|flatten)|{"create":(map(select(.=="create"))|length),"update":(map(select(.=="update"))|length),"delete":(map(select(.=="delete"))|length)}' > ${JSON_PLAN_FILE} - artifacts: - reports: - terraform: ${TERRAFORM_DIRECTORY}/${JSON_PLAN_FILE} - -review_plan: - extends: .terraform-plan-generation - variables: - TERRAFORM_DIRECTORY: "review/" - # Review will not include an artifact name - -staging_plan: - extends: .terraform-plan-generation - variables: - TERRAFORM_DIRECTORY: "staging/" - artifacts: - name: Staging - -production_plan: - extends: .terraform-plan-generation - variables: - TERRAFORM_DIRECTORY: "production/" - artifacts: - name: Production + # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables + TF_STATE_NAME: default + TF_CACHE_KEY: default ``` -## Using a GitLab managed Terraform state backend as a remote data source - -You can use a GitLab-managed Terraform state as a -[Terraform data source](https://www.terraform.io/docs/providers/terraform/d/remote_state.html). -To use your existing Terraform state backend as a data source, provide the following details -as [Terraform input variables](https://www.terraform.io/docs/configuration/variables.html): - -- **address**: The URL of the remote state backend you want to use as a data source. - For example, `https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>`. -- **username**: The username to authenticate with the data source. If you are using a [Personal Access Token](../profile/personal_access_tokens.md) for - authentication, this is your GitLab username. If you are using GitLab CI, this is `'gitlab-ci-token'`. -- **password**: The password to authenticate with the data source. If you are using a Personal Access Token for - authentication, this is the token value. If you are using GitLab CI, it is the contents of the `${CI_JOB_TOKEN}` CI variable. - -An example setup is shown below: - -1. Create a file named `example.auto.tfvars` with the following contents: - - ```plaintext - example_remote_state_address=https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME> - example_username=<GitLab username> - example_access_token=<GitLab Personal Acceess Token> - ``` - -1. Define the data source by adding the following code block in a `.tf` file (such as `data.tf`): - - ```hcl - data "terraform_remote_state" "example" { - backend = "http" - - config = { - address = var.example_remote_state_address - username = var.example_username - password = var.example_access_token - } - } - ``` - -Outputs from the data source can now be referenced within your Terraform resources -using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. +This template uses `.latest.`, instead of stable, and may include breaking changes. +This template also includes some opinionated decisions, which you can override: -You need at least [developer access](../permissions.md) to the target project -to read the Terraform state. +- Including the latest [GitLab Terraform Image](https://gitlab.com/gitlab-org/terraform-images). +- Using the [GitLab managed Terraform State](#gitlab-managed-terraform-state) as + the Terraform state storage backend. +- Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml): + `init`, `validate`, `build`, and `deploy`. These stages + [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml) + `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on `master`. diff --git a/doc/user/infrastructure/mr_integration.md b/doc/user/infrastructure/mr_integration.md new file mode 100644 index 00000000000..7d9a036cac8 --- /dev/null +++ b/doc/user/infrastructure/mr_integration.md @@ -0,0 +1,205 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Terraform integration in Merge Requests + +Collaborating around Infrastructure as Code (IaC) changes requires both code changes and expected infrastructure changes to be checked and approved. GitLab provides a solution to help collaboration around Terraform code changes and their expected effects using the Merge Request pages. This way users don't have to build custom tools or rely on 3rd party solutions to streamline their IaC workflows. + +## Output Terraform Plan information into a merge request + +Using the [GitLab Terraform Report artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform), +you can expose details from `terraform plan` runs directly into a merge request widget, +enabling you to see statistics about the resources that Terraform creates, +modifies, or destroys. + +## Setup + +NOTE: **Note:** +GitLab ships with a [pre-built CI template](index.md#quick-start) that uses GitLab Managed Terraform state and integrates Terraform changes into merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup. + +To manually configure a GitLab Terraform Report artifact requires the following steps: + +1. For simplicity, let's define a few reusable variables to allow us to + refer to these files multiple times: + + ```yaml + variables: + PLAN: plan.cache + PLAN_JSON: plan.json + ``` + +1. Install `jq`, a + [lightweight and flexible command-line JSON processor](https://stedolan.github.io/jq/). +1. Create an alias for a specific `jq` command that parses out the information we + want to extract from the `terraform plan` output: + + ```yaml + before_script: + - apk --no-cache add jq + - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" + ``` + + NOTE: **Note:** + In distributions that use Bash (for example, Ubuntu), `alias` statements are not + expanded in non-interactive mode. If your pipelines fail with the error + `convert_report: command not found`, alias expansion can be activated explicitly + by adding a `shopt` command to your script: + + ```yaml + before_script: + - shopt -s expand_aliases + - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" + ``` + +1. Define a `script` that runs `terraform plan` and `terraform show`. These commands + pipe the output and convert the relevant bits into a store variable `PLAN_JSON`. + This JSON is used to create a + [GitLab Terraform Report artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform). + The Terraform report obtains a Terraform `tfplan.json` file. The collected + Terraform plan report is uploaded to GitLab as an artifact, and is shown in merge requests. + + ```yaml + plan: + stage: build + script: + - terraform plan -out=$PLAN + - terraform show --json $PLAN | convert_report > $PLAN_JSON + artifacts: + reports: + terraform: $PLAN_JSON + ``` + + For a full example using the pre-built image, see [Example `.gitlab-ci.yaml` + file](#example-gitlab-ciyaml-file). + + For an example displaying multiple reports, see [`.gitlab-ci.yaml` multiple reports file](#multiple-terraform-plan-reports). + +1. Running the pipeline displays the widget in the merge request, like this: + +  + +1. Clicking the **View Full Log** button in the widget takes you directly to the + plan output present in the pipeline logs: + +  + +### Example `.gitlab-ci.yaml` file + +```yaml +default: + image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest + + cache: + key: example-production + paths: + - ${TF_ROOT}/.terraform + +variables: + TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production + TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production + +before_script: + - cd ${TF_ROOT} + +stages: + - prepare + - validate + - build + - deploy + +init: + stage: prepare + script: + - gitlab-terraform init + +validate: + stage: validate + script: + - gitlab-terraform validate + +plan: + stage: build + script: + - gitlab-terraform plan + - gitlab-terraform plan-json + artifacts: + name: plan + paths: + - ${TF_ROOT}/plan.cache + reports: + terraform: ${TF_ROOT}/plan.json + +apply: + stage: deploy + environment: + name: production + script: + - gitlab-terraform apply + dependencies: + - plan + when: manual + only: + - master +``` + +### Multiple Terraform Plan reports + +Starting with GitLab version 13.2, you can display multiple reports on the Merge Request +page. The reports also display the `artifacts: name:`. See example below for a suggested setup. + +```yaml +default: + image: + name: registry.gitlab.com/gitlab-org/gitlab-build-images:terraform + entrypoint: + - '/usr/bin/env' + - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' + + cache: + paths: + - .terraform + +stages: + - build + +.terraform-plan-generation: + stage: build + variables: + PLAN: plan.tfplan + JSON_PLAN_FILE: tfplan.json + before_script: + - cd ${TERRAFORM_DIRECTORY} + - terraform --version + - terraform init + - apk --no-cache add jq + script: + - terraform validate + - terraform plan -out=${PLAN} + - terraform show --json ${PLAN} | jq -r '([.resource_changes[]?.change.actions?]|flatten)|{"create":(map(select(.=="create"))|length),"update":(map(select(.=="update"))|length),"delete":(map(select(.=="delete"))|length)}' > ${JSON_PLAN_FILE} + artifacts: + reports: + terraform: ${TERRAFORM_DIRECTORY}/${JSON_PLAN_FILE} + +review_plan: + extends: .terraform-plan-generation + variables: + TERRAFORM_DIRECTORY: "review/" + # Review will not include an artifact name + +staging_plan: + extends: .terraform-plan-generation + variables: + TERRAFORM_DIRECTORY: "staging/" + artifacts: + name: Staging + +production_plan: + extends: .terraform-plan-generation + variables: + TERRAFORM_DIRECTORY: "production/" + artifacts: + name: Production +``` diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md new file mode 100644 index 00000000000..ef36f0217be --- /dev/null +++ b/doc/user/infrastructure/terraform_state.md @@ -0,0 +1,360 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# GitLab managed Terraform State + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. + +[Terraform remote backends](https://www.terraform.io/docs/backends/index.html) +enable you to store the state file in a remote, shared store. GitLab uses the +[Terraform HTTP backend](https://www.terraform.io/docs/backends/types/http.html) +to securely store the state files in local storage (the default) or +[the remote store of your choice](../../administration/terraform_state.md). + +The GitLab managed Terraform state backend can store your Terraform state easily and +securely, and spares you from setting up additional remote resources like +Amazon S3 or Google Cloud Storage. Its features include: + +- Supporting encryption of the state file both in transit and at rest. +- Locking and unlocking state. +- Remote Terraform plan and apply execution. + +## Permissions for using Terraform + +In GitLab version 13.1, [Maintainer access](../permissions.md) was required to use a +GitLab managed Terraform state backend. In GitLab versions 13.2 and greater, +[Maintainer access](../permissions.md) is required to lock, unlock and write to the state +(using `terraform apply`), while [Developer access](../permissions.md) is required to read +the state (using `terraform plan -lock=false`). + +## Set up GitLab-managed Terraform state + +To get started with a GitLab-managed Terraform state, there are two different options: + +- [Use a local machine](#get-started-using-local-development). +- [Use GitLab CI](#get-started-using-gitlab-ci). + +Terraform States can be found by navigating to a Project's **{cloud-gear}** **Operations > Terraform** page. + +### Get started using local development + +If you plan to only run `terraform plan` and `terraform apply` commands from your +local machine, this is a simple way to get started: + +1. Create your project on your GitLab instance. +1. Navigate to **Settings > General** and note your **Project name** + and **Project ID**. +1. Define the Terraform backend in your Terraform project to be: + + ```hcl + terraform { + backend "http" { + } + } + ``` + +1. Create a [Personal Access Token](../profile/personal_access_tokens.md) with + the `api` scope. + +1. On your local machine, run `terraform init`, passing in the following options, + replacing `<YOUR-STATE-NAME>`, `<YOUR-PROJECT-ID>`, `<YOUR-USERNAME>` and + `<YOUR-ACCESS-TOKEN>` with the relevant values. This command initializes your + Terraform state, and stores that state within your GitLab project. The name of + your state can contain only uppercase and lowercase letters, decimal digits, + hyphens, and underscores. This example uses `gitlab.com`: + + ```shell + terraform init \ + -backend-config="address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>" \ + -backend-config="lock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ + -backend-config="unlock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ + -backend-config="username=<YOUR-USERNAME>" \ + -backend-config="password=<YOUR-ACCESS-TOKEN>" \ + -backend-config="lock_method=POST" \ + -backend-config="unlock_method=DELETE" \ + -backend-config="retry_wait_min=5" + ``` + +You can now run `terraform plan` and `terraform apply` as you normally would. + +### Get started using GitLab CI + +If you don't want to start with local development, you can also use GitLab CI to +run your `terraform plan` and `terraform apply` commands. + +Next, [configure the backend](#configure-the-backend). + +#### Configure the backend + +After executing the `terraform init` command, you must configure the Terraform backend +and the CI YAML file: + +1. In your Terraform project, define the [HTTP backend](https://www.terraform.io/docs/backends/types/http.html) + by adding the following code block in a `.tf` file (such as `backend.tf`) to + define the remote backend: + + ```hcl + terraform { + backend "http" { + } + } + ``` + +1. In the root directory of your project repository, configure a + `.gitlab-ci.yaml` file. This example uses a pre-built image which includes a + `gitlab-terraform` helper. For supported Terraform versions, see the [GitLab + Terraform Images project](https://gitlab.com/gitlab-org/terraform-images). + + ```yaml + image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest + ``` + +1. In the `.gitlab-ci.yaml` file, define some environment variables to ease + development. In this example, `TF_ROOT` is the directory where the Terraform + commands must be executed, `TF_ADDRESS` is the URL to the state on the GitLab + instance where this pipeline runs, and the final path segment in `TF_ADDRESS` + is the name of the Terraform state. Projects may have multiple states, and + this name is arbitrary, so in this example we set it to `example-production` + which corresponds with the directory we're using as our `TF_ROOT`, and we + ensure that the `.terraform` directory is cached between jobs in the pipeline + using a cache key based on the state name (`example-production`): + + ```yaml + variables: + TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production + TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production + + cache: + key: example-production + paths: + - ${TF_ROOT}/.terraform + ``` + +1. In a `before_script`, change to your `TF_ROOT`: + + ```yaml + before_script: + - cd ${TF_ROOT} + + stages: + - prepare + - validate + - build + - deploy + + init: + stage: prepare + script: + - gitlab-terraform init + + validate: + stage: validate + script: + - gitlab-terraform validate + + plan: + stage: build + script: + - gitlab-terraform plan + - gitlab-terraform plan-json + artifacts: + name: plan + paths: + - ${TF_ROOT}/plan.cache + reports: + terraform: ${TF_ROOT}/plan.json + + apply: + stage: deploy + environment: + name: production + script: + - gitlab-terraform apply + dependencies: + - plan + when: manual + only: + - master + ``` + +1. Push your project to GitLab, which triggers a CI job pipeline. This pipeline + runs the `gitlab-terraform init`, `gitlab-terraform validate`, and + `gitlab-terraform plan` commands. + +The output from the above `terraform` commands should be viewable in the job logs. + +CAUTION: **Caution:** +Like any other job artifact, Terraform plan data is [viewable by anyone with Guest access](../permissions.md) to the repository. +Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan +includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly +recommends encrypting plan output or modifying the project visibility settings. + +### Example project + +See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 within a custom VPC. + +## Using a GitLab managed Terraform state backend as a remote data source + +You can use a GitLab-managed Terraform state as a +[Terraform data source](https://www.terraform.io/docs/providers/terraform/d/remote_state.html). +To use your existing Terraform state backend as a data source, provide the following details +as [Terraform input variables](https://www.terraform.io/docs/configuration/variables.html): + +- **address**: The URL of the remote state backend you want to use as a data source. + For example, `https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>`. +- **username**: The username to authenticate with the data source. If you are using a [Personal Access Token](../profile/personal_access_tokens.md) for + authentication, this is your GitLab username. If you are using GitLab CI, this is `'gitlab-ci-token'`. +- **password**: The password to authenticate with the data source. If you are using a Personal Access Token for + authentication, this is the token value. If you are using GitLab CI, it is the contents of the `${CI_JOB_TOKEN}` CI variable. + +An example setup is shown below: + +1. Create a file named `example.auto.tfvars` with the following contents: + + ```plaintext + example_remote_state_address=https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME> + example_username=<GitLab username> + example_access_token=<GitLab Personal Acceess Token> + ``` + +1. Define the data source by adding the following code block in a `.tf` file (such as `data.tf`): + + ```hcl + data "terraform_remote_state" "example" { + backend = "http" + + config = { + address = var.example_remote_state_address + username = var.example_username + password = var.example_access_token + } + } + ``` + +Outputs from the data source can now be referenced within your Terraform resources +using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. + +You need at least [developer access](../permissions.md) to the target project +to read the Terraform state. + +## Migrating to GitLab Managed Terraform state + +Terraform supports copying the state when the backend is changed or +reconfigured. This can be useful if you need to migrate from another backend to +GitLab managed Terraform state. Using a local terminal is recommended to run the commands needed for migrating to GitLab Managed Terraform state. + +The following example demonstrates how to change the state name, the same workflow is needed to migrate to GitLab Managed Terraform state from a different state storage backend. + +### Setting up the initial backend + +```shell +PROJECT_ID="<gitlab-project-id>" +TF_USERNAME="<gitlab-username>" +TF_PASSWORD="<gitlab-personal-access-token>" +TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/old-state-name" + +terraform init \ + -backend-config=address=${TF_ADDRESS} \ + -backend-config=lock_address=${TF_ADDRESS}/lock \ + -backend-config=unlock_address=${TF_ADDRESS}/lock \ + -backend-config=username=${TF_USERNAME} \ + -backend-config=password=${TF_PASSWORD} \ + -backend-config=lock_method=POST \ + -backend-config=unlock_method=DELETE \ + -backend-config=retry_wait_min=5 +``` + +```plaintext +Initializing the backend... + +Successfully configured the backend "http"! Terraform will automatically +use this backend unless the backend configuration changes. + +Initializing provider plugins... + +Terraform has been successfully initialized! + +You may now begin working with Terraform. Try running "terraform plan" to see +any changes that are required for your infrastructure. All Terraform commands +should now work. + +If you ever set or change modules or backend configuration for Terraform, +rerun this command to reinitialize your working directory. If you forget, other +commands will detect it and remind you to do so if necessary. +``` + +### Changing the backend + +Now that `terraform init` has created a `.terraform/` directory that knows where +the old state is, you can tell it about the new location: + +```shell +TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/new-state-name" + +terraform init \ + -backend-config=address=${TF_ADDRESS} \ + -backend-config=lock_address=${TF_ADDRESS}/lock \ + -backend-config=unlock_address=${TF_ADDRESS}/lock \ + -backend-config=username=${TF_USERNAME} \ + -backend-config=password=${TF_PASSWORD} \ + -backend-config=lock_method=POST \ + -backend-config=unlock_method=DELETE \ + -backend-config=retry_wait_min=5 +``` + +```plaintext +Initializing the backend... +Backend configuration changed! + +Terraform has detected that the configuration specified for the backend +has changed. Terraform will now check for existing state in the backends. + + +Acquiring state lock. This may take a few moments... +Do you want to copy existing state to the new backend? + Pre-existing state was found while migrating the previous "http" backend to the + newly configured "http" backend. No existing state was found in the newly + configured "http" backend. Do you want to copy this state to the new "http" + backend? Enter "yes" to copy and "no" to start with an empty state. + + Enter a value: yes + + +Successfully configured the backend "http"! Terraform will automatically +use this backend unless the backend configuration changes. + +Initializing provider plugins... + +Terraform has been successfully initialized! + +You may now begin working with Terraform. Try running "terraform plan" to see +any changes that are required for your infrastructure. All Terraform commands +should now work. + +If you ever set or change modules or backend configuration for Terraform, +rerun this command to reinitialize your working directory. If you forget, other +commands will detect it and remind you to do so if necessary. +``` + +If you type `yes`, it copies your state from the old location to the new +location. You can then go back to running it from within GitLab CI. + +## Managing state files + +NOTE: **Note:** +We are currently working on [providing a graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563). + + + +The state files attached to a project can be found under Operations / Terraform. + +## Removing a State file + +You can only remove a state file by making a request to the API, like the following example: + +```shell +curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id/terraform/state/<your_state_name>" +``` diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index c370f9d8725..68af74b69fe 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Instance-level Kubernetes clusters > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in GitLab 11.11. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 8b65da4ab94..4bdf72673a1 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -425,6 +425,7 @@ GFM recognizes the following: | merge request | `!123` | `namespace/project!123` | `project!123` | | snippet | `$123` | `namespace/project$123` | `project$123` | | epic **(ULTIMATE)** | `&123` | `group1/subgroup&123` | | +| vulnerability **(ULTIMATE)** *(1)* | `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | | label by ID | `~123` | `namespace/project~123` | `project~123` | | one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | | multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | @@ -438,6 +439,26 @@ GFM recognizes the following: | repository file line references | `[README](doc/README#L13)` | | | | [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | +1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/281035) in GitLab 13.6. + + The Vulnerability special references feature is under development but ready for production use. + It is deployed behind a feature flag that is **disabled by default**. + [GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) + can opt to enable it for your instance. + It's disabled on GitLab.com. + + To disable it: + + ```ruby + Feature.disable(:vulnerability_special_references) + ``` + + To enable it: + + ```ruby + Feature.enable(:vulnerability_special_references) + ``` + For example, referencing an issue by using `#123` will format the output as a link to issue number 123 with text `#123`. Likewise, a link to issue number 123 will be recognized and formatted with text `#123`. @@ -532,7 +553,7 @@ If this snippet was placed on a page at `<your_wiki>/documentation/main`, it would link to `<your_wiki>/documentation/related`: ```markdown -[Link to Related Page](./related) +[Link to Related Page](related) ``` If this snippet was placed on a page at `<your_wiki>/documentation/related/content`, @@ -546,7 +567,7 @@ If this snippet was placed on a page at `<your_wiki>/documentation/main`, it would link to `<your_wiki>/documentation/related.md`: ```markdown -[Link to Related Page](./related.md) +[Link to Related Page](related.md) ``` If this snippet was placed on a page at `<your_wiki>/documentation/related/content`, diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 5a2ff410253..9e2dfd9ad96 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Operations Dashboard **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5781) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/9218) to [GitLab Premium](https://about.gitlab.com/pricing/) in 11.10. diff --git a/doc/user/packages/composer_repository/img/project_id_v13_5.png b/doc/user/packages/composer_repository/img/project_id_v13_5.png Binary files differdeleted file mode 100644 index 45861b6ff1b..00000000000 --- a/doc/user/packages/composer_repository/img/project_id_v13_5.png +++ /dev/null diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index d4fb662c3a6..6e5563d0d4e 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -77,7 +77,7 @@ Prerequisites: - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`. NOTE: **Note:** - [Deploy tokens](./../../project/deploy_tokens/index.md) are + [Deploy tokens](../../project/deploy_tokens/index.md) are [not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) for use with Composer. To publish the package: @@ -140,7 +140,7 @@ Prerequisites: - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to, at minimum, `read_api`. NOTE: **Note:** - [Deploy tokens](./../../project/deploy_tokens/index.md) are + [Deploy tokens](../../project/deploy_tokens/index.md) are [not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) for use with Composer. To install a package: diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 10c820a86be..f6f8d6d61b6 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -12,23 +12,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w Publish Conan packages in your project’s Package Registry. Then install the packages whenever you need to use them as a dependency. -To publish Conan packages to the Package Registry, add the -Package Registry as a remote and authenticate with it. +To publish Conan packages to the Package Registry, add the Package Registry as a +remote and authenticate with it. -Then you can run `conan` commands and publish your package to the Package Registry. +Then you can run `conan` commands and publish your package to the +Package Registry. ## Build a Conan package -This section explains how to install Conan and build a package for your C/C++ project. +This section explains how to install Conan and build a package for your C/C++ +project. -If you already use Conan and know how to build your own packages, go to the [next section](#add-the-package-registry-as-a-conan-remote). +If you already use Conan and know how to build your own packages, go to the +[next section](#add-the-package-registry-as-a-conan-remote). ### Install Conan -Download the Conan package manager to your local development environment by following -the instructions at [conan.io](https://conan.io/downloads.html). +Download the Conan package manager to your local development environment by +following the instructions at [conan.io](https://conan.io/downloads.html). -When installation is complete, verify you can use Conan in your terminal by running: +When installation is complete, verify you can use Conan in your terminal by +running: ```shell conan --version @@ -42,15 +46,16 @@ Conan version 1.20.5 ### Install CMake -When you develop with C++ and Conan, you have a range of compilers to choose from. -This example uses the CMake compiler. +When you develop with C++ and Conan, you can select from many available +compilers. This example uses the CMake compiler. To install CMake: - For Mac, use [homebrew](https://brew.sh/) and run `brew install cmake`. - For other operating systems, follow the instructions at [cmake.org](https://cmake.org/install/). -When installation is complete, verify you can use CMake in your terminal by running: +When installation is complete, verify you can use CMake in your terminal by +running: ```shell cmake --version @@ -60,8 +65,8 @@ The CMake version is printed in the output. ### Create a project -To test the Package Registry, you need a C++ project. If you don't already have one, you can clone the -Conan [hello world starter project](https://github.com/conan-io/hello). +To test the Package Registry, you need a C++ project. If you don't already have +one, you can clone the Conan [hello world starter project](https://github.com/conan-io/hello). ### Build a package @@ -74,22 +79,26 @@ To build a package: conan new Hello/0.1 -t ``` -1. Create a package for the recipe by running `conan create` with the Conan user and channel: +1. Create a package for the recipe by running `conan create` with the Conan user + and channel: ```shell conan create . mycompany/beta ``` NOTE: **Note:** - If you use an [instance remote](#add-a-remote-for-your-instance), you must follow a specific [naming convention](#package-recipe-naming-convention-for-instance-remotes). + If you use an [instance remote](#add-a-remote-for-your-instance), you must + follow a specific [naming convention](#package-recipe-naming-convention-for-instance-remotes). A package with the recipe `Hello/0.1@mycompany/beta` is created. -For more details on creating and managing Conan packages, see the [Conan docs](https://docs.conan.io/en/latest/creating_packages.html). +For more details about creating and managing Conan packages, see the +[Conan documentation](https://docs.conan.io/en/latest/creating_packages.html). ## Add the Package Registry as a Conan remote -To run `conan` commands, you must add the Package Registry as a Conan remote for your project or instance. +To run `conan` commands, you must add the Package Registry as a Conan remote for +your project or instance. ### Add a remote for your project @@ -143,9 +152,9 @@ To add the remote: #### Package recipe naming convention for instance remotes -The standard Conan recipe convention is `package_name/version@user/channel`, -but if you're using an [instance remote](#add-a-remote-for-your-instance), the recipe -`user` must be the plus sign (`+`) separated project path. +The standard Conan recipe convention is `package_name/version@user/channel`, but +if you're using an [instance remote](#add-a-remote-for-your-instance), the +recipe `user` must be the plus sign (`+`) separated project path. Example recipe names: @@ -156,58 +165,68 @@ Example recipe names: | `gitlab-org/gitlab-ce` | `my-package/1.0.0@gitlab-org+gitlab-ce/stable` | Yes | | `gitlab-org/gitlab-ce` | `my-package/1.0.0@foo/stable` | No | -[Project remotes](#add-a-remote-for-your-project) have a more flexible naming convention. +[Project remotes](#add-a-remote-for-your-project) have a more flexible naming +convention. ## Authenticate to the Package Registry -To authenticate to the Package Registry, you need either a personal access token or deploy token. +To authenticate to the Package Registry, you need either a personal access token +or deploy token. -- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), set the scope to `api`. -- If you use a [deploy token](./../../project/deploy_tokens/index.md), set the scope to `read_package_registry`, `write_package_registry`, or both. +- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), + set the scope to `api`. +- If you use a [deploy token](../../project/deploy_tokens/index.md), set the + scope to `read_package_registry`, `write_package_registry`, or both. ### Add your credentials to the GitLab remote -Associate your token with the GitLab remote, so that you don't have to explicitly -add a token to every Conan command. +Associate your token with the GitLab remote, so that you don't have to +explicitly add a token to every Conan command. Prerequisites: - You must have an authentication token. -- The Conan remote [must be set](#add-the-package-registry-as-a-conan-remote). +- The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote). -In a terminal, run this command. In this example, the remote name is `gitlab`. Use the name of your remote. +In a terminal, run this command. In this example, the remote name is `gitlab`. +Use the name of your remote. ```shell conan user <gitlab_username or deploy_token_username> -r gitlab -p <personal_access_token or deploy_token> ``` -Now when you run commands with `--remote=gitlab`, your username and password are automatically included in the requests. +Now when you run commands with `--remote=gitlab`, your username and password are +included in the requests. -Alternately, you can explicitly include your credentials in any given command. For example: +Alternatively, you can explicitly include your credentials in any given command. +For example: ```shell CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=<personal_access_token or deploy_token> conan upload Hello/0.1@mycompany/beta --all --remote=gitlab ``` NOTE: **Note:** -Your authentication with GitLab expires on a regular basis, -so occasionally you may need to re-enter your personal access token. +Because your authentication with GitLab expires on a regular basis, you may +occasionally need to re-enter your personal access token. ### Set a default remote for your project (optional) -If you want to interact with the GitLab Package Registry without having to specify a remote, -you can tell Conan to always use the Package Registry for your packages. +If you want to interact with the GitLab Package Registry without having to +specify a remote, you can tell Conan to always use the Package Registry for your +packages. -In a terminal, run this command. +In a terminal, run this command: ```shell conan remote add_ref Hello/0.1@mycompany/beta gitlab ``` NOTE: **Note:** -The package recipe includes the version, so the default remote for `Hello/0.1@user/channel` does not work for `Hello/0.2@user/channel`. +The package recipe includes the version, so the default remote for +`Hello/0.1@user/channel` doesn't work for `Hello/0.2@user/channel`. -If you do not set a default user or remote, you can still include the user and remote in your commands: +If you don't set a default user or remote, you can still include the user and +remote in your commands: ```shell `CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=<personal_access_token or deploy_token> <conan command> --remote=gitlab @@ -215,17 +234,18 @@ If you do not set a default user or remote, you can still include the user and r ## Publish a Conan package -Publish a Conan package to the Package Registry, so that anyone who can access the project can use the package as a dependency. +Publish a Conan package to the Package Registry, so that anyone who can access +the project can use the package as a dependency. Prerequisites: -To publish a Conan package, you need: - -- The Package Registry [set as a remote](#add-the-package-registry-as-a-conan-remote). -- [Authentication](#authenticate-to-the-package-registry) set up with the Package Registry. -- A local [Conan package](https://docs.conan.io/en/latest/creating_packages/getting_started.html). +- The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote). +- [Authentication](#authenticate-to-the-package-registry) with the + Package Registry must be configured. +- A local [Conan package](https://docs.conan.io/en/latest/creating_packages/getting_started.html) + must exist. - For an instance remote, the package must meet the [naming convention](#package-recipe-naming-convention-for-instance-remotes). -- A project ID, which is on the project's homepage. +- You must have the project ID, which is on the project's homepage. To publish the package, use the `conan upload` command: @@ -237,11 +257,11 @@ conan upload Hello/0.1@mycompany/beta --all > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11678) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. -To work with Conan commands in [GitLab CI/CD](./../../../ci/README.md), you can use -`CI_JOB_TOKEN` in place of the personal access token in your commands. +To work with Conan commands in [GitLab CI/CD](../../../ci/README.md), you can +use `CI_JOB_TOKEN` in place of the personal access token in your commands. -You can provide the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` with each -Conan command in your `.gitlab-ci.yml` file. For example: +You can provide the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` with each Conan +command in your `.gitlab-ci.yml` file. For example: ```yaml image: conanio/gcc7 @@ -255,24 +275,26 @@ create_package: - CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload <package-name>/0.1@<group-name>+<project-name>/stable --all --remote=gitlab ``` -Additional Conan images to use as the basis of your CI file are available -in the [Conan docs](https://docs.conan.io/en/latest/howtos/run_conan_in_docker.html#available-docker-images). +Additional Conan images to use as the basis of your CI file are available in the +[Conan docs](https://docs.conan.io/en/latest/howtos/run_conan_in_docker.html#available-docker-images). ## Install a Conan package -Install a Conan package from the Package Registry so you can use it as a dependency. +Install a Conan package from the Package Registry so you can use it as a +dependency. -Conan packages are often installed as dependencies by using the `conanfile.txt` file. +Conan packages are often installed as dependencies by using the `conanfile.txt` +file. Prerequisites: -To install a Conan package, you need: - -- The Package Registry [set as a remote](#add-the-package-registry-as-a-conan-remote). -- [Authentication](#authenticate-to-the-package-registry) set up with the Package Registry. +- The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote). +- [Authentication](#authenticate-to-the-package-registry) with the + Package Registry must be configured. -1. In the project where you want to install the package as a dependency, open `conanfile.txt`. - Or, in the root of your project, create a file called `conanfile.txt`. +1. In the project where you want to install the package as a dependency, open + `conanfile.txt`. Or, in the root of your project, create a file called + `conanfile.txt`. 1. Add the Conan recipe to the `[requires]` section of the file: @@ -284,7 +306,8 @@ To install a Conan package, you need: cmake ``` -1. At the root of your project, create a `build` directory and change to that directory: +1. At the root of your project, create a `build` directory and change to that + directory: ```shell mkdir build && cd build @@ -298,7 +321,7 @@ To install a Conan package, you need: NOTE: **Note:** If you try to install the package you just created in this tutorial, the package -already exists on your local machine, so this command has no effect. +already exists on your local computer, so this command has no effect. ## Remove a Conan package @@ -310,19 +333,22 @@ There are two ways to remove a Conan package from the GitLab Package Registry. conan remove Hello/0.2@user/channel --remote=gitlab ``` - You must explicitly include the remote in this command, otherwise the package is only removed from your - local system cache. + You must explicitly include the remote in this command, otherwise the package + is removed only from your local system cache. NOTE: **Note:** - This command removes all recipe and binary package files from the Package Registry. + This command removes all recipe and binary package files from the + Package Registry. - From the GitLab user interface: - Go to your project's **Packages & Registries > Package Registry**. Remove the package by clicking the red trash icon. + Go to your project's **Packages & Registries > Package Registry**. Remove the + package by clicking the red trash icon. ## Search for Conan packages in the Package Registry -To search by full or partial package name, or by exact recipe, run the `conan search` command. +To search by full or partial package name, or by exact recipe, run the +`conan search` command. - To search for all packages with a specific package name: @@ -336,7 +362,8 @@ To search by full or partial package name, or by exact recipe, run the `conan se conan search He* --remote=gitlab ``` -The scope of your search includes all projects you have permission to access. This includes your private projects as well as all public projects. +The scope of your search includes all projects you have permission to access. +This includes your private projects as well as all public projects. ## Fetch Conan package information from the Package Registry @@ -351,7 +378,9 @@ conan info Hello/0.1@mycompany/beta The GitLab Conan repository supports the following Conan CLI commands: - `conan upload`: Upload your recipe and package files to the Package Registry. -- `conan install`: Install a Conan package from the Package Registry, this includes using the `conanfile.txt` file. -- `conan search`: Search the Package Registry for public packages, and private packages you have permission to view. +- `conan install`: Install a Conan package from the Package Registry, which + includes using the `conanfile.txt` file. +- `conan search`: Search the Package Registry for public packages, and private + packages you have permission to view. - `conan info`: View the information on a given package from the Package Registry. - `conan remove`: Delete the package from the Package Registry. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index baadd3c91a7..1cb6c951bd9 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -447,7 +447,7 @@ For the project where it's defined, tags matching the regex pattern are removed. The underlying layers and images remain. To delete the underlying layers and images that aren't associated with any tags, administrators can use -[garbage collection](../../../administration/packages/container_registry.md#removing-unused-layers-not-referenced-by-manifests) with the `-m` switch. +[garbage collection](../../../administration/packages/container_registry.md#removing-untagged-manifests-and-unreferenced-layers) with the `-m` switch. ### Enable the cleanup policy @@ -468,7 +468,7 @@ Cleanup policies can be run on all projects, with these exceptions: ``` There are performance risks with enabling it for all projects, especially if you - are using an [external registry](./index.md#use-with-external-container-registries). + are using an [external registry](index.md#use-with-external-container-registries). - For self-managed GitLab instances, you can enable or disable the cleanup policy for a specific project. @@ -522,7 +522,7 @@ To create a cleanup policy in the UI: | **Expiration interval** | How long tags are exempt from being deleted. | | **Expiration schedule** | How often the policy should run. | | **Number of tags to retain** | How many tags to _always_ keep for each image. | - | **Tags with names matching this regex pattern expire:** | The regex pattern that determines which tags to remove. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | + | **Tags with names matching this regex pattern expire:** | The regex pattern that determines which tags to remove. This value cannot be blank. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | | **Tags with names matching this regex pattern are preserved:** | The regex pattern that determines which tags to preserve. The `latest` tag is always preserved. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | 1. Click **Set cleanup policy**. @@ -544,6 +544,8 @@ Here are examples of regex patterns you may want to use: .* ``` + This is the default value for the expiration regex. + - Match tags that start with `v`: ```plaintext @@ -578,7 +580,7 @@ See the API documentation for further details: [Edit project](../../../api/proje ### Use with external container registries -When using an [external container registry](./../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint), +When using an [external container registry](../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint), running a cleanup policy on a project may have some performance risks. If a project runs a policy to remove thousands of tags the GitLab background jobs may get backed up or fail completely. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 3fa21ef486b..e1fae770a5d 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -4,9 +4,10 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Dependency Proxy **(PREMIUM)** +# Dependency Proxy -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 13.6. The GitLab Dependency Proxy is a local proxy you can use for your frequently-accessed upstream images. @@ -41,6 +42,9 @@ The Dependency Proxy is not available for projects. ## Use the Dependency Proxy for Docker images +CAUTION: **Important:** +In some specific storage configurations, an issue occurs and container images are not pulled correctly from the cache. The problem occurs when an image is located in object storage. The proxy looks for it locally and fails to find it. View [issue #208080](https://gitlab.com/gitlab-org/gitlab/-/issues/208080) for details. + You can use GitLab as a source for your Docker images. Prerequisites: diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 0c961b5c86f..f489c7c800f 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -49,7 +49,7 @@ Example request: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ --upload-file path/to/file.txt \ - https://gitlab.example.com/api/v4/projects/24/generic/my_package/0.0.1/file.txt + https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt ``` Example response: @@ -85,12 +85,12 @@ Example request that uses a personal access token: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ - https://gitlab.example.com/api/v4/projects/24/generic/my_package/0.0.1/file.txt + https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt ``` ## Publish a generic package by using CI/CD -To work with generic packages in [GitLab CI/CD](./../../../ci/README.md), you can use +To work with generic packages in [GitLab CI/CD](../../../ci/README.md), you can use `CI_JOB_TOKEN` in place of the personal access token in your commands. For example: @@ -137,3 +137,9 @@ Feature.disable(:generic_packages) # For a single project Feature.disable(:generic_packages, Project.find(<project id>)) ``` + +### Generic package sample project + +The [Write CI-CD Variables in Pipeline](https://gitlab.com/guided-explorations/cfg-data/write-ci-cd-variables-in-pipeline) project contains a working example you can use to create, upload, and download generic packages in GitLab CI/CD. + +It also demonstrates how to manage a semantic version for the generic package: storing it in a CI/CD variable, retrieving it, incrementing it, and writing it back to the CI/CD variable when tests for the download work correctly. diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index bd3b5b49ebd..81edc3afcfd 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -4,11 +4,11 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# GitLab Go Proxy +# Go proxy for GitLab > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1. > - It's deployed behind a feature flag, disabled by default. -> - It's disabled on GitLab.com. +> - It's disabled for GitLab.com. > - It's not recommended for production use. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-the-go-proxy). > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. @@ -16,14 +16,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w With the Go proxy for GitLab, every project in GitLab can be fetched with the [Go proxy protocol](https://proxy.golang.org/). -## Prerequisites +## Enable the Go proxy -### Enable the Go proxy +The Go proxy for GitLab is under development, and isn't ready for production use +due to [potential performance issues with large repositories](https://gitlab.com/gitlab-org/gitlab/-/issues/218083). -The Go proxy for GitLab is under development and not ready for production use, due to -[potential performance issues with large repositories](https://gitlab.com/gitlab-org/gitlab/-/issues/218083). - -It is deployed behind a feature flag that is **disabled by default**. +It's deployed behind a feature flag that is _disabled by default_. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can enable it for your instance. @@ -47,57 +45,46 @@ Feature.enable(:go_proxy, Project.find(1)) Feature.disable(:go_proxy, Project.find(2)) ``` -### Enable the Package Registry - -The Package Registry is enabled for new projects by default. If you cannot find -the **Packages > List** entry under your project's sidebar, verify -the following: - -1. Your GitLab administrator has - [enabled support for the Package Registry](../../../administration/packages/index.md). -1. The Package Registry is [enabled for your project](../index.md). - NOTE: **Note:** -GitLab does not currently display Go modules in the **Packages Registry** of a project. -Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213770) for details. +Even if it's enabled, GitLab doesn't display Go modules in the **Package Registry**. +Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213770) for +details. ## Add GitLab as a Go proxy -NOTE: **Note:** -To use a Go proxy, you must be using Go 1.13 or later. - -The available proxy endpoints are: +To use GitLab as a Go proxy, you must be using Go 1.13 or later. -- Project - can fetch modules defined by a project - `/api/v4/projects/:id/packages/go` +The available proxy endpoint is for fetching modules by project: `/api/v4/projects/:id/packages/go` -To use the Go proxy for GitLab to fetch Go modules from GitLab, add the -appropriate proxy endpoint to `GOPROXY`. For details on setting Go environment -variables, see [Set environment variables](#set-environment-variables). For -details on configuring `GOPROXY`, see [Dependency Management in Go > -Proxies](../../../development/go_guide/dependencies.md#proxies). +To fetch Go modules from GitLab, add the project-specific endpoint to `GOPROXY`. -For example, adding the project-specific endpoint to `GOPROXY` will tell Go -to initially query that endpoint and fall back to the default behavior: +Go queries the endpoint and falls back to the default behavior: ```shell -go env -w GOPROXY='https://gitlab.com/api/v4/projects/1234/packages/go,https://proxy.golang.org,direct' +go env -w GOPROXY='https://gitlab.example.com/api/v4/projects/1234/packages/go,https://proxy.golang.org,direct' ``` -With this configuration, Go fetches dependencies as follows: +With this configuration, Go fetches dependencies in this order: -1. Attempt to fetch from the project-specific Go proxy. -1. Attempt to fetch from [proxy.golang.org](https://proxy.golang.org). -1. Fetch directly with version control system operations (such as `git clone`, +1. Go attempts to fetch from the project-specific Go proxy. +1. Go attempts to fetch from [proxy.golang.org](https://proxy.golang.org). +1. Go fetches directly with version control system operations (like `git clone`, `svn checkout`, and so on). -If `GOPROXY` is not specified, Go follows steps 2 and 3, which corresponds to -setting `GOPROXY` to `https://proxy.golang.org,direct`. If `GOPROXY` only -contains the project-specific endpoint, Go will only query that endpoint. +If `GOPROXY` isn't specified, Go follows steps 2 and 3, which corresponds to +setting `GOPROXY` to `https://proxy.golang.org,direct`. If `GOPROXY` +contains only the project-specific endpoint, Go queries only that endpoint. + +For details about how to set Go environment variables, see +[Set environment variables](#set-environment-variables). + +For details about configuring `GOPROXY`, see +[Dependency Management in Go > Proxies](../../../development/go_guide/dependencies.md#proxies). ## Fetch modules from private projects -`go` does not support transmitting credentials over insecure connections. The -steps below work only if GitLab is configured for HTTPS. +`go` doesn't support transmitting credentials over insecure connections. The +following steps work only if GitLab is configured for HTTPS: 1. Configure Go to include HTTP basic authentication credentials when fetching from the Go proxy for GitLab. @@ -107,31 +94,38 @@ steps below work only if GitLab is configured for HTTPS. ### Enable request authentication Create a [personal access token](../../profile/personal_access_tokens.md) with -the `api` or `read_api` scope and add it to -[`~/.netrc`](https://ec.haxx.se/usingcurl/usingcurl-netrc): +the scope set to `api` or `read_api`. -```netrc +Open your [`~/.netrc`](https://ec.haxx.se/usingcurl/usingcurl-netrc) file +and add the following text. Replace the variables in `< >` with your values. + +```plaintext machine <url> login <username> password <token> ``` -`<url>` should be the URL of the GitLab instance, for example `gitlab.com`. -`<username>` and `<token>` should be your username and the personal access -token, respectively. +- `<url>`: The GitLab URL, for example `gitlab.com`. +- `<username>`: Your username. +- `<token>`: Your personal access token. ### Disable checksum database queries -When downloading dependencies, by default Go 1.13 and later validate fetched -sources against the checksum database `sum.golang.org`. If the checksum of the -fetched sources does not match the checksum from the database, Go will not build -the dependency. This causes private modules to fail to build, as -`sum.golang.org` cannot fetch the source of private modules and thus cannot -provide a checksum. To resolve this issue, `GONOSUMDB` should be set to a -comma-separated list of private projects. For details on setting Go environment -variables, see [Set environment variables](#set-environment-variables). For more -details on disabling this feature of Go, see [Dependency Management in Go > -Checksums](../../../development/go_guide/dependencies.md#checksums). +When downloading dependencies with Go 1.13 and later, fetched sources are +validated against the checksum database `sum.golang.org`. + +If the checksum of the fetched sources doesn't match the checksum from the +database, Go doesn't build the dependency. + +Private modules fail to build because `sum.golang.org` can't fetch the source +of private modules, and so it cannot provide a checksum. + +To resolve this issue, set `GONOSUMDB` to a comma-separated list of private +projects. For details about setting Go environment variables, see +[Set environment variables](#set-environment-variables). For more details about +disabling this feature of Go, see +[Dependency Management in Go > Checksums](../../../development/go_guide/dependencies.md#checksums). -For example, to disable checksum queries for `gitlab.com/my/project`, set `GONOSUMDB`: +For example, to disable checksum queries for `gitlab.com/my/project`, set +`GONOSUMDB`: ```shell go env -w GONOSUMDB='gitlab.com/my/project,<previous value>' @@ -139,32 +133,36 @@ go env -w GONOSUMDB='gitlab.com/my/project,<previous value>' ## Working with Go -If you are unfamiliar with managing dependencies in Go, or Go in general, -consider reviewing the following documentation: +If you're unfamiliar with managing dependencies in Go, or Go in general, review +the following documentation: - [Dependency Management in Go](../../../development/go_guide/dependencies.md) - [Go Modules Reference](https://golang.org/ref/mod) -- [Documentation (golang.org)](https://golang.org/doc/) -- [Learn (learn.go.dev)](https://learn.go.dev/) +- [Documentation (`golang.org`)](https://golang.org/doc/) +- [Learn (`learn.go.dev`)](https://learn.go.dev/) ### Set environment variables -Go uses environment variables to control various features. These can be managed -in all the usual ways, but Go 1.14 will read and write Go environment variables -from and to a special Go environment file, `~/.go/env` by default. If `GOENV` is -set to a file, Go will read and write that file instead. If `GOENV` is not set -but `GOPATH` is set, Go will read and write `$GOPATH/env`. +Go uses environment variables to control various features. You can manage these +variables in all the usual ways. However, Go 1.14 reads and writes Go +environment variables to and from a special Go environment file, `~/.go/env` by +default. + +- If `GOENV` is set to a file, Go reads and writes to and from that file instead. +- If `GOENV` is not set but `GOPATH` is set, Go reads and writes `$GOPATH/env`. Go environment variables can be read with `go env <var>` and, in Go 1.14 and -later, can be written with `go env -w <var>=<value>`. For example, `go env -GOPATH` or `go env -w GOPATH=/go`. +later, can be written with `go env -w <var>=<value>`. For example, +`go env GOPATH` or `go env -w GOPATH=/go`. ### Release a module Go modules and module versions are defined by source repositories, such as Git, -SVN, Mercurial, and so on. A module is a repository containing `go.mod` and Go -files. Module versions are defined by VCS tags. To publish a module, push -`go.mod` and source files to a VCS repository. To publish a module version, push -a VCS tag. See [Dependency Management in Go > -Versioning](../../../development/go_guide/dependencies.md#versioning) for more -details on what constitutes a valid module or module version. +SVN, and Mercurial. A module is a repository that contains `go.mod` and Go +files. Module versions are defined by VCS tags. + +To publish a module, push `go.mod` and source files to a VCS repository. To +publish a module version, push a VCS tag. + +See [Dependency Management in Go > Versioning](../../../development/go_guide/dependencies.md#versioning) +for more details about what constitutes a valid module or module version. diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 53ba3d01b3e..83d179cbc9c 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -30,31 +30,31 @@ The Package Registry supports the following formats: You can also use the [API](../../api/packages.md) to administer the Package Registry. -The GitLab [Container Registry](container_registry/index.md) is a secure and private registry for container images. -It's built on open source software and completely integrated within GitLab. -Use GitLab CI/CD to create and publish images. Use the GitLab [API](../../api/container_registry.md) to -manage the registry across groups and projects. +## Accepting contributions -The [Dependency Proxy](dependency_proxy/index.md) is a local proxy for frequently-used upstream images and packages. - -## Suggested contributions - -Consider contributing to GitLab. This [development documentation](../../development/packages.md) will -guide you through the process. Or check out how other members of the community -are adding support for [PHP](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17417) or [Terraform](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834). +The below table lists formats that are not supported, but are accepting Community contributions for. Consider contributing to GitLab. This [development documentation](../../development/packages.md) will +guide you through the process. -| Format | Use case | +| Format | Status | | ------ | ------ | -| [Cargo](https://gitlab.com/gitlab-org/gitlab/-/issues/33060) | Cargo is the Rust package manager. Build, publish and share Rust packages | -| [Chef](https://gitlab.com/gitlab-org/gitlab/-/issues/36889) | Configuration management with Chef using all the benefits of a repository manager. | -| [CocoaPods](https://gitlab.com/gitlab-org/gitlab/-/issues/36890) | Speed up development with Xcode and CocoaPods. | -| [Conda](https://gitlab.com/gitlab-org/gitlab/-/issues/36891) | Secure and private local Conda repositories. | -| [CRAN](https://gitlab.com/gitlab-org/gitlab/-/issues/36892) | Deploy and resolve CRAN packages for the R language. | -| [Debian](https://gitlab.com/gitlab-org/gitlab/-/issues/5835) | Host and provision Debian packages. | -| [Opkg](https://gitlab.com/gitlab-org/gitlab/-/issues/36894) | Optimize your work with OpenWrt using Opkg repositories. | -| [P2](https://gitlab.com/gitlab-org/gitlab/-/issues/36895) | Host all your Eclipse plugins in your own GitLab P2 repository. | -| [Puppet](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | Configuration management meets repository management with Puppet repositories. | -| [RPM](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) | Distribute RPMs directly from GitLab. | -| [RubyGems](https://gitlab.com/gitlab-org/gitlab/-/issues/803) | Use GitLab to host your own gems. | -| [SBT](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | Resolve dependencies from and deploy build output to SBT repositories when running SBT builds. | -| [Vagrant](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | Securely host your Vagrant boxes in local repositories. | +| Chef | [#36889](https://gitlab.com/gitlab-org/gitlab/-/issues/36889) | +| CocoaPods | [#36890](https://gitlab.com/gitlab-org/gitlab/-/issues/36890) | +| Conda | [#36891](https://gitlab.com/gitlab-org/gitlab/-/issues/36891) | +| CRAN | [#36892](https://gitlab.com/gitlab-org/gitlab/-/issues/36892) | +| Debian | [WIP: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44746) | +| Opkg | [#36894](https://gitlab.com/gitlab-org/gitlab/-/issues/36894) | +| P2 | [#36895](https://gitlab.com/gitlab-org/gitlab/-/issues/36895) | +| Puppet | [#36897](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | +| RPM | [#5932](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) | +| RubyGems | [#803](https://gitlab.com/gitlab-org/gitlab/-/issues/803) | +| SBT | [#36898](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | +| Terraform | [WIP: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) | +| Vagrant | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | + +## Container Registry + +The GitLab [Container Registry](container_registry/index.md) is a secure and private registry for container images. It's built on open source software and completely integrated within GitLab. Use GitLab CI/CD to create and publish images. Use the GitLab [API](../../api/container_registry.md) to manage the registry across groups and projects. + +## Dependency Proxy + +The [Dependency Proxy](dependency_proxy/index.md) is a local proxy for frequently-used upstream images and packages. diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index d4a8ff0cdb4..5d0d64b310d 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -17,9 +17,9 @@ Then, install the packages whenever you need to use them as a dependency. This section explains how to install Maven and build a package. If you already use Maven and know how to build your own packages, go to the -[next section](#add-the-package-registry-as-a-maven-remote). +[next section](#authenticate-to-the-package-registry-with-maven). -Maven repositories work well with Gradle, too. To set up a Gradle project, see [get started with Gradle](#use-gradle-to-create-a-java-project). +Maven repositories work well with Gradle, too. To set up a Gradle project, see [get started with Gradle](#build-a-java-project-with-gradle). ### Install Maven @@ -29,14 +29,14 @@ The required minimum versions are: - Maven 3.6+ Follow the instructions at [maven.apache.org](https://maven.apache.org/install.html) -to download and install Maven for your local development environment. Once +to download and install Maven for your local development environment. After installation is complete, verify you can use Maven in your terminal by running: ```shell mvn --version ``` -You should see something similar to the below printed in the output: +The output should be similar to: ```shell Apache Maven 3.6.1 (d66c9c0b3152b2e69ee9bac180bb8fcc8e6af555; 2019-04-04T20:00:29+01:00) @@ -48,29 +48,26 @@ OS name: "mac os x", version: "10.15.2", arch: "x86_64", family: "mac" ### Create a project -Understanding how to create a full Java project is outside the scope of this -guide but you can follow the steps below to create a new project that can be +Follow these steps to create a Maven project that can be published to the GitLab Package Registry. -Start by opening your terminal and creating a directory where you would like to -store the project in your environment. From inside the directory, you can run -the following Maven command to initialize a new package: +1. Open your terminal and create a directory to store the project. +1. From the new directory, run this Maven command to initialize a new package: -```shell -mvn archetype:generate -DgroupId=com.mycompany.mydepartment -DartifactId=my-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false -``` + ```shell + mvn archetype:generate -DgroupId=com.mycompany.mydepartment -DartifactId=my-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false + ``` -The arguments are as follows: + The arguments are: -- `DgroupId`: A unique string that identifies your package. You should follow -the [Maven naming conventions](https://maven.apache.org/guides/mini/guide-naming-conventions.html). -- `DartifactId`: The name of the JAR, appended to the end of the `DgroupId`. -- `DarchetypeArtifactId`: The archetype used to create the initial structure of -the project. -- `DinteractiveMode`: Create the project using batch mode (optional). + - `DgroupId`: A unique string that identifies your package. Follow + the [Maven naming conventions](https://maven.apache.org/guides/mini/guide-naming-conventions.html). + - `DartifactId`: The name of the `JAR`, appended to the end of the `DgroupId`. + - `DarchetypeArtifactId`: The archetype used to create the initial structure of + the project. + - `DinteractiveMode`: Create the project using batch mode (optional). -After running the command, you should see the following message, indicating that -your project has been set up successfully: +This message indicates that the project was set up successfully: ```shell ... @@ -82,33 +79,33 @@ your project has been set up successfully: [INFO] ------------------------------------------------------------------------ ``` -You should see a new directory where you ran this command matching your -`DartifactId` parameter (in this case it should be `my-project`). +In the folder where you ran the command, a new directory should be displayed. +The directory name should match the `DartifactId` parameter, which in this case, +is `my-project`. -## Use Gradle to create a Java project +## Build a Java project with Gradle This section explains how to install Gradle and initialize a Java project. If you already use Gradle and know how to build your own packages, go to the -[next section](#add-the-package-registry-as-a-maven-remote). +[next section](#authenticate-to-the-package-registry-with-maven). ### Install Gradle -Installation is needed only if you want to create a new Gradle project. Follow +If you want to create a new Gradle project, you must install Gradle. Follow instructions at [gradle.org](https://gradle.org/install/) to download and install Gradle for your local development environment. -Verify you can use Gradle in your terminal by running: +In your terminal, verify you can use Gradle by running: ```shell gradle -version ``` -If you want to use an existing Gradle project, installation is not necessary. -Simply execute `gradlew` (on Linux) or `gradlew.bat` (on Windows) in the project -directory instead. +To use an existing Gradle project, in the project directory, +on Linux execute `gradlew`, or on Windows execute `gradlew.bat`. -You should see something similar to the below printed in the output: +The output should be similar to: ```plaintext ------------------------------------------------------------ @@ -127,88 +124,79 @@ OS: Windows 10 10.0 amd64 ### Create a Java project -Understanding how to create a full Java project in Gradle is outside the scope of this -guide, but you can follow the steps below to create a new project that can be +Follow these steps to create a Maven project that can be published to the GitLab Package Registry. -Start by opening your terminal and creating a directory where you would like to -store the project in your environment. From inside the directory, you can run -the following Maven command to initialize a new package: +1. Open your terminal and create a directory to store the project. +1. From this new directory, run this Maven command to initialize a new package: -```shell -gradle init -``` + ```shell + gradle init + ``` -The output should be + The output should be: -```plaintext -Select type of project to generate: - 1: basic - 2: application - 3: library - 4: Gradle plugin -Enter selection (default: basic) [1..4] -``` + ```plaintext + Select type of project to generate: + 1: basic + 2: application + 3: library + 4: Gradle plugin + Enter selection (default: basic) [1..4] + ``` -Enter `3` to create a new Library project. The output should be: +1. Enter `3` to create a new Library project. The output should be: -```plaintext -Select implementation language: - 1: C++ - 2: Groovy - 3: Java - 4: Kotlin - 5: Scala - 6: Swift -``` + ```plaintext + Select implementation language: + 1: C++ + 2: Groovy + 3: Java + 4: Kotlin + 5: Scala + 6: Swift + ``` -Enter `3` to create a new Java Library project. The output should be: +1. Enter `3` to create a new Java Library project. The output should be: -```plaintext -Select build script DSL: - 1: Groovy - 2: Kotlin -Enter selection (default: Groovy) [1..2] -``` + ```plaintext + Select build script DSL: + 1: Groovy + 2: Kotlin + Enter selection (default: Groovy) [1..2] + ``` -Choose `1` to create a new Java Library project which is described in Groovy DSL. The output should be: +1. Enter `1` to create a new Java Library project that is described in Groovy DSL. The output should be: -```plaintext -Select test framework: - 1: JUnit 4 - 2: TestNG - 3: Spock - 4: JUnit Jupiter -``` + ```plaintext + Select test framework: + 1: JUnit 4 + 2: TestNG + 3: Spock + 4: JUnit Jupiter + ``` -Choose `1` to initialize the project with JUnit 4 testing libraries. The output should be: +1. Enter `1` to initialize the project with JUnit 4 testing libraries. The output should be: -```plaintext -Project name (default: test): -``` + ```plaintext + Project name (default: test): + ``` -Enter a project name or hit enter to use the directory name as project name. +1. Enter a project name or press Enter to use the directory name as project name. -## Add the Package Registry as a Maven remote +## Authenticate to the Package Registry with Maven -The next step is to add the GitLab Package Registry as a Maven remote. If a -project is private or you want to upload Maven artifacts to GitLab, -credentials must be provided for authorization too. Support is available -for [personal access tokens](#authenticate-with-a-personal-access-token), -[CI job tokens](#authenticate-with-a-ci-job-token), and -[deploy tokens](../../project/deploy_tokens/index.md) only. Regular username/password -credentials do not work. +To authenticate to the Package Registry, you need either a personal access token or deploy token. -### Authenticate with a personal access token +- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), set the scope to `api`. +- If you use a [deploy token](../../project/deploy_tokens/index.md), set the scope to `read_package_registry`, `write_package_registry`, or both. -To authenticate with a [personal access token](../../profile/personal_access_tokens.md), -set the scope to `api` when creating one, and add it to your Maven or Gradle configuration -files. +### Authenticate with a personal access token in Maven -#### Authenticate with a personal access token in Maven +To use a personal access token, add this section to your +[`settings.xml`](https://maven.apache.org/settings.html) file. -Add a corresponding section to your -[`settings.xml`](https://maven.apache.org/settings.html) file: +The `name` must be `Private-Token`. ```xml <settings> @@ -228,45 +216,40 @@ Add a corresponding section to your </settings> ``` -#### Authenticate with a personal access token in Gradle +### Authenticate with a deploy token in Maven -Create a file `~/.gradle/gradle.properties` with the following content: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) deploy token authentication in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -```groovy -gitLabPrivateToken=REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN -``` +To use a deploy token, add this section to your +[`settings.xml`](https://maven.apache.org/settings.html) file. -Add a repositories section to your -[`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html) -file: +The `name` must be `Deploy-Token`. -```groovy -repositories { - maven { - url "https://<gitlab-url>/api/v4/groups/<group>/-/packages/maven" - name "GitLab" - credentials(HttpHeaderCredentials) { - name = 'Private-Token' - value = gitLabPrivateToken - } - authentication { - header(HttpHeaderAuthentication) - } - } -} +```xml +<settings> + <servers> + <server> + <id>gitlab-maven</id> + <configuration> + <httpHeaders> + <property> + <name>Deploy-Token</name> + <value>REPLACE_WITH_YOUR_DEPLOY_TOKEN</value> + </property> + </httpHeaders> + </configuration> + </server> + </servers> +</settings> ``` -You should now be able to upload Maven artifacts to your project. - -### Authenticate with a CI job token +### Authenticate with a CI job token in Maven -If you're using GitLab CI/CD, a CI job token can be used instead -of a personal access token. +To authenticate with a CI job token, add this section to your +[`settings.xml`](https://maven.apache.org/settings.html) file. -#### Authenticate with a CI job token in Maven - -To authenticate with a CI job token, add a corresponding section to your -[`settings.xml`](https://maven.apache.org/settings.html) file: +The `name` must be `Job-Token`. ```xml <settings> @@ -286,23 +269,35 @@ To authenticate with a CI job token, add a corresponding section to your </settings> ``` -You can read more on -[how to create Maven packages using GitLab CI/CD](#creating-maven-packages-with-gitlab-cicd). +Read more about [how to create Maven packages using GitLab CI/CD](#create-maven-packages-with-gitlab-cicd). + +## Authenticate to the Package Registry with Gradle -#### Authenticate with a CI job token in Gradle +To authenticate to the Package Registry, you need either a personal access token or deploy token. -To authenticate with a CI job token, add a repositories section to your +- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), set the scope to `api`. +- If you use a [deploy token](../../project/deploy_tokens/index.md), set the scope to `read_package_registry`, `write_package_registry`, or both. + +### Authenticate with a personal access token in Gradle + +Create a file `~/.gradle/gradle.properties` with the following content: + +```groovy +gitLabPrivateToken=REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN +``` + +Add a `repositories` section to your [`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html) file: ```groovy repositories { maven { - url "https://<gitlab-url>/api/v4/groups/<group>/-/packages/maven" + url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven" name "GitLab" credentials(HttpHeaderCredentials) { - name = 'Job-Token' - value = System.getenv("CI_JOB_TOKEN") + name = 'Private-Token' + value = gitLabPrivateToken } authentication { header(HttpHeaderAuthentication) @@ -311,51 +306,42 @@ repositories { } ``` -### Authenticate with a deploy token - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. - -To authenticate with a [deploy token](./../../project/deploy_tokens/index.md), -set the scope to `api` when creating one, and add it to your Maven or Gradle configuration -files. - -#### Authenticate with a deploy token in Maven +### Authenticate with a deploy token in Gradle -Add a corresponding section to your -[`settings.xml`](https://maven.apache.org/settings.html) file: +To authenticate with a deploy token, add a `repositories` section to your +[`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html) +file: -```xml -<settings> - <servers> - <server> - <id>gitlab-maven</id> - <configuration> - <httpHeaders> - <property> - <name>Deploy-Token</name> - <value>REPLACE_WITH_YOUR_DEPLOY_TOKEN</value> - </property> - </httpHeaders> - </configuration> - </server> - </servers> -</settings> +```groovy +repositories { + maven { + url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven" + name "GitLab" + credentials(HttpHeaderCredentials) { + name = 'Deploy-Token' + value = '<deploy-token>' + } + authentication { + header(HttpHeaderAuthentication) + } + } +} ``` -#### Authenticate with a deploy token in Gradle +### Authenticate with a CI job token in Gradle -To authenticate with a deploy token, add a repositories section to your +To authenticate with a CI job token, add a `repositories` section to your [`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html) file: ```groovy repositories { maven { - url "https://<gitlab-url>/api/v4/groups/<group>/-/packages/maven" + url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven" name "GitLab" credentials(HttpHeaderCredentials) { - name = 'Deploy-Token' - value = '<deploy-token>' + name = 'Job-Token' + value = System.getenv("CI_JOB_TOKEN") } authentication { header(HttpHeaderAuthentication) @@ -364,177 +350,162 @@ repositories { } ``` -## Configuring your project to use the GitLab Maven repository URL - -To download and upload packages from GitLab, you need a `repository` and -`distributionManagement` section in your `pom.xml` file. If you're following the -steps from above, then you must add the following information to your -`my-project/pom.xml` file. +## Use the GitLab endpoint for Maven packages -Depending on your workflow and the amount of Maven packages you have, there are -3 ways you can configure your project to use the GitLab endpoint for Maven packages: +To use the GitLab endpoint for Maven packages, choose an option: -- **Project level**: Useful when you have few Maven packages which are not under +- **Project-level**: Use when you have few Maven packages and they are not in the same GitLab group. -- **Group level**: Useful when you have many Maven packages under the same GitLab +- **Group-level**: Use when you have many Maven packages in the same GitLab group. -- **Instance level**: Useful when you have many Maven packages under different - GitLab groups or on their own namespace. +- **Instance-level**: Use when you have many Maven packages in different + GitLab groups or in their own namespace. + +The option you choose determines the settings you'll add to your `pom.xml` file. -NOTE: **Note:** -In all cases, you need a project specific URL for uploading a package in -the `distributionManagement` section. +In all cases, to publish a package, you need: -### Project level Maven endpoint +- A project-specific URL in the `distributionManagement` section. +- A `repository` and `distributionManagement` section. -The example below shows how the relevant `repository` section of your `pom.xml` -would look like in Maven: +### Project-level Maven endpoint + +The relevant `repository` section of your `pom.xml` +in Maven should look like this: ```xml <repositories> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> </repository> </repositories> <distributionManagement> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> </repository> <snapshotRepository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> </snapshotRepository> </distributionManagement> ``` -The corresponding section in Gradle would look like this: +The corresponding section in Gradle would be: ```groovy repositories { maven { - url "https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven" + url "https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven" name "GitLab" } } ``` -The `id` must be the same with what you -[defined in `settings.xml`](#add-the-package-registry-as-a-maven-remote). - -Replace `PROJECT_ID` with your project ID which can be found on the home page -of your project. +- The `id` is what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven). +- The `PROJECT_ID` is your project ID, which you can view on your project's home page. +- Replace `gitlab.example.com` with your domain name. +- For retrieving artifacts, use either the + [URL-encoded](../../../api/README.md#namespaced-path-encoding) path of the project + (like `group%2Fproject`) or the project's ID (like `42`). However, only the + project's ID can be used for publishing. -If you have a self-managed GitLab installation, replace `gitlab.com` with your -domain name. +### Group-level Maven endpoint -NOTE: **Note:** -For retrieving artifacts, you can use either the -[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project -(such as `group%2Fproject`) or the project's ID (such as `42`). However, only the -project's ID can be used for uploading. - -### Group level Maven endpoint - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8798) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8798) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. If you rely on many packages, it might be inefficient to include the `repository` section -with a unique URL for each package. Instead, you can use the group level endpoint for -all your Maven packages stored within one GitLab group. Only packages you have access to +with a unique URL for each package. Instead, you can use the group-level endpoint for +all the Maven packages stored within one GitLab group. Only packages you have access to are available for download. -The group level endpoint works with any package names, which means the you -have the flexibility of naming compared to [instance level endpoint](#instance-level-maven-endpoint). -However, GitLab does not guarantee the uniqueness of the package names within +The group-level endpoint works with any package names, so you +have more flexibility in naming, compared to the [instance-level endpoint](#instance-level-maven-endpoint). +However, GitLab does not guarantee the uniqueness of package names within the group. You can have two projects with the same package name and package version. As a result, GitLab serves whichever one is more recent. -The example below shows how the relevant `repository` section of your `pom.xml` -would look like. You still need a project specific URL for uploading a package in +This example shows the relevant `repository` section of your `pom.xml` file. +You still need a project-specific URL for publishing a package in the `distributionManagement` section: ```xml <repositories> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/groups/GROUP_ID/-/packages/maven</url> + <url>https://gitlab.example.com/api/v4/groups/GROUP_ID/-/packages/maven</url> </repository> </repositories> <distributionManagement> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> </repository> <snapshotRepository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> </snapshotRepository> </distributionManagement> ``` -For Gradle, the corresponding repositories section would look like: +For Gradle, the corresponding `repositories` section would look like: ```groovy repositories { maven { - url "https://gitlab.com/api/v4/groups/GROUP_ID/-/packages/maven" + url "https://gitlab.example.com/api/v4/groups/GROUP_ID/-/packages/maven" name "GitLab" } } ``` -The `id` must be the same with what you -[defined in `settings.xml`](#add-the-package-registry-as-a-maven-remote). - -Replace `my-group` with your group name and `PROJECT_ID` with your project ID -which can be found on the home page of your project. - -If you have a self-managed GitLab installation, replace `gitlab.com` with your -domain name. +- For the `id`, use what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven). +- For `my-group`, use your group name. +- For `PROJECT_ID`, use your project ID, which you can view on your project's home page. +- Replace `gitlab.example.com` with your domain name. +- For retrieving artifacts, use either the + [URL-encoded](../../../api/README.md#namespaced-path-encoding) path of the group + (like `group%2Fsubgroup`) or the group's ID (like `12`). -NOTE: **Note:** -For retrieving artifacts, you can use either the -[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the group -(such as `group%2Fsubgroup`) or the group's ID (such as `12`). +### Instance-level Maven endpoint -### Instance level Maven endpoint - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8274) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8274) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. If you rely on many packages, it might be inefficient to include the `repository` section -with a unique URL for each package. Instead, you can use the instance level endpoint for -all maven packages stored in GitLab and the packages you have access to are available +with a unique URL for each package. Instead, you can use the instance-level endpoint for +all Maven packages stored in GitLab. All packages you have access to are available for download. -Note that **only packages that have the same path as the project** are exposed via -the instance level endpoint. +**Only packages that have the same path as the project** are exposed by +the instance-level endpoint. -| Project | Package | Instance level endpoint available | +| Project | Package | Instance-level endpoint available | | ------- | ------- | --------------------------------- | | `foo/bar` | `foo/bar/1.0-SNAPSHOT` | Yes | | `gitlab-org/gitlab` | `foo/bar/1.0-SNAPSHOT` | No | | `gitlab-org/gitlab` | `gitlab-org/gitlab/1.0-SNAPSHOT` | Yes | -The example below shows how the relevant `repository` section of your `pom.xml` -would look like. You still need a project specific URL for uploading a package in -the `distributionManagement` section: +This example shows how relevant `repository` section of your `pom.xml`. +You still need a project-specific URL in the `distributionManagement` section. ```xml <repositories> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/packages/maven</url> + <url>https://gitlab.example.com/api/v4/packages/maven</url> </repository> </repositories> <distributionManagement> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> </repository> <snapshotRepository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> </snapshotRepository> </distributionManagement> ``` @@ -544,40 +515,35 @@ The corresponding repositories section in Gradle would look like: ```groovy repositories { maven { - url "https://gitlab.com/api/v4/packages/maven" + url "https://gitlab.example.com/api/v4/packages/maven" name "GitLab" } } ``` -The `id` must be the same with what you -[defined in `settings.xml`](#add-the-package-registry-as-a-maven-remote). - -Replace `PROJECT_ID` with your project ID which can be found on the home page -of your project. - -If you have a self-managed GitLab installation, replace `gitlab.com` with your -domain name. +- The `id` is what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven). +- The `PROJECT_ID` is your project ID, which you can view on your project's home page. +- Replace `gitlab.example.com` with your domain name. +- For retrieving artifacts, use either the + [URL-encoded](../../../api/README.md#namespaced-path-encoding) path of the project + (like `group%2Fproject`) or the project's ID (like `42`). However, only the + project's ID can be used for publishing. -NOTE: **Note:** -For retrieving artifacts, you can use either the -[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project -(such as `group%2Fproject`) or the project's ID (such as `42`). However, only the -project's ID can be used for uploading. +## Publish a package -## Uploading packages +After you have set up the [remote and authentication](#authenticate-to-the-package-registry-with-maven) +and [configured your project](#use-the-gitlab-endpoint-for-maven-packages), +publish a Maven artifact from your project. -Once you have set up the [remote and authentication](#add-the-package-registry-as-a-maven-remote) -and [configured your project](#configuring-your-project-to-use-the-gitlab-maven-repository-url), -test to upload a Maven artifact from a project of yours. +### Publish by using Maven -### Upload using Maven +To publish a package by using Maven: ```shell mvn deploy ``` -If the deploy is successful, you should see the build success message again: +If the deploy is successful, the build success message should be displayed: ```shell ... @@ -585,108 +551,112 @@ If the deploy is successful, you should see the build success message again: ... ``` -You should also see that the upload was uploaded to the correct registry: +The message should also show that the package was published to the correct location: ```shell -Uploading to gitlab-maven: https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.jar +Uploading to gitlab-maven: https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.jar ``` -### Upload using Gradle +### Publish by using Gradle -Add the Gradle plugin [`maven-publish`](https://docs.gradle.org/current/userguide/publishing_maven.html) to the plugins section: +To publish a package by using Gradle: -```groovy -plugins { - id 'java' - id 'maven-publish' -} -``` +1. Add the Gradle plugin [`maven-publish`](https://docs.gradle.org/current/userguide/publishing_maven.html) to the plugins section: -Add a `publishing` section: + ```groovy + plugins { + id 'java' + id 'maven-publish' + } + ``` -```groovy -publishing { - publications { - library(MavenPublication) { - from components.java - } - } - repositories { - maven { - url "https://gitlab.com/api/v4/projects/<PROJECT_ID>/packages/maven" - credentials(HttpHeaderCredentials) { - name = "Private-Token" - value = gitLabPrivateToken // the variable resides in ~/.gradle/gradle.properties - } - authentication { - header(HttpHeaderAuthentication) - } - } - } -} -``` +1. Add a `publishing` section: + + ```groovy + publishing { + publications { + library(MavenPublication) { + from components.java + } + } + repositories { + maven { + url "https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven" + credentials(HttpHeaderCredentials) { + name = "Private-Token" + value = gitLabPrivateToken // the variable resides in ~/.gradle/gradle.properties + } + authentication { + header(HttpHeaderAuthentication) + } + } + } + } + ``` -Replace `PROJECT_ID` with your project ID which can be found on the home page -of your project. +1. Replace `PROJECT_ID` with your project ID, which can be found on your project's home page. -Run the publish task: +1. Run the publish task: -```shell -gradle publish -``` + ```shell + gradle publish + ``` -You can then navigate to your project's **Packages & Registries** page and see the uploaded -artifacts or even delete them. +Now navigate to your project's **Packages & Registries** page and view the published artifacts. -## Installing a package +## Install a package -Installing a package from the GitLab Package Registry requires that you set up -the [remote and authentication](#add-the-package-registry-as-a-maven-remote) -as above. Once this is completed, there are two ways to install a package. +To install a package from the GitLab Package Registry, you must configure +the [remote and authenticate](#authenticate-to-the-package-registry-with-maven). +When this is completed, there are two ways to install a package. -### Install using Maven with `mvn install` +### Use Maven with `mvn install` -Add the dependency manually to your project `pom.xml` file. To add the example -created above, the XML would look like: +To install a package by using `mvn install`: -```xml -<dependency> - <groupId>com.mycompany.mydepartment</groupId> - <artifactId>my-project</artifactId> - <version>1.0-SNAPSHOT</version> -</dependency> -``` +1. Add the dependency manually to your project `pom.xml` file. + To add the example created earlier, the XML would be: -Then, inside your project, run the following: + ```xml + <dependency> + <groupId>com.mycompany.mydepartment</groupId> + <artifactId>my-project</artifactId> + <version>1.0-SNAPSHOT</version> + </dependency> + ``` -```shell -mvn install -``` +1. In your project, run the following: + + ```shell + mvn install + ``` -Provided everything is set up correctly, you should see the dependency -downloaded from the GitLab Package Registry: +The message should show that the package is downloading from the Package Registry: ```shell -Downloading from gitlab-maven: http://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom +Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom ``` -### Install using Maven with `mvn dependency:get` +### Use Maven with `mvn dependency:get` -The second way to install packages is to use the Maven commands directly. -Inside your project directory, run: +You can install packages by using the Maven commands directly. + +1. In your project directory, run: + + ```shell + mvn dependency:get -Dartifact=com.nickkipling.app:nick-test-app:1.1-SNAPSHOT + ``` + +The message should show that the package is downloading from the Package Registry: ```shell -mvn dependency:get -Dartifact=com.nickkipling.app:nick-test-app:1.1-SNAPSHOT +Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom ``` -You should see the same downloading message confirming that the project was -retrieved from the GitLab Package Registry. - TIP: **Tip:** -Both the XML block and Maven command are readily copy and pastable from the -Package details page, allowing for quick and easy installation. +In the GitLab UI, on the Package Registry page for Maven, you can view and copy these commands. -### Install using Gradle +### Use Gradle Add a [dependency](https://docs.gradle.org/current/userguide/declaring_dependencies.html) to `build.gradle` in the dependencies section: @@ -696,25 +666,25 @@ dependencies { } ``` -## Removing a package +## Remove a package -In the packages view of your project page, you can delete packages by clicking -the red trash icons or by clicking the **Delete** button on the package details -page. +For your project, go to **Packages & Registries > Package Registry**. -## Creating Maven packages with GitLab CI/CD +To remove a package, click the red trash icon or, from the package details, the **Delete** button. -Once you have your repository configured to use the GitLab Maven Repository, +## Create Maven packages with GitLab CI/CD + +After you have configured your repository to use the Package Repository for Maven, you can configure GitLab CI/CD to build new packages automatically. -### Creating Maven packages with GitLab CI/CD using Maven +### Create Maven packages with GitLab CI/CD by using Maven -The example below shows how to create a new package each time the `master` branch -is updated: +You can create a new package each time the `master` branch is updated. 1. Create a `ci_settings.xml` file that serves as Maven's `settings.xml` file. - Add the server section with the same ID you defined in your `pom.xml` file. - For example, in our case it's `gitlab-maven`: + +1. Add the `server` section with the same ID you defined in your `pom.xml` file. + For example, use `gitlab-maven` as the ID: ```xml <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" @@ -735,30 +705,29 @@ is updated: </settings> ``` -1. Make sure your `pom.xml` file includes the following: +1. Make sure your `pom.xml` file includes the following. + You can either let Maven use the CI environment variables, as shown in this example, + or you can hard code your project's ID. ```xml <repositories> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </repository> </repositories> <distributionManagement> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </repository> <snapshotRepository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </snapshotRepository> </distributionManagement> ``` - TIP: **Tip:** - You can either let Maven utilize the CI environment variables or hardcode your project's ID. - 1. Add a `deploy` job to your `.gitlab-ci.yml` file: ```yaml @@ -773,16 +742,17 @@ is updated: 1. Push those files to your repository. The next time the `deploy` job runs, it copies `ci_settings.xml` to the -user's home location (in this case the user is `root` since it runs in a -Docker container), and Maven uses the configured CI -[environment variables](../../../ci/variables/README.md#predefined-environment-variables). +user's home location. In this example: + +- The user is `root`, because the job runs in a Docker container. +- Maven uses the configured CI [environment variables](../../../ci/variables/README.md#predefined-environment-variables). -### Creating Maven packages with GitLab CI/CD using Gradle +### Create Maven packages with GitLab CI/CD by using Gradle -The example below shows how to create a new package each time the `master` branch -is updated: +You can create a package each time the `master` branch +is updated. -1. Make sure you use the Job-Token authentication as described in ["Authenticating with a CI job token in Gradle"](#authenticate-with-a-ci-job-token-in-gradle). +1. Authenticate with [a CI job token in Gradle](#authenticate-with-a-ci-job-token-in-gradle). 1. Add a `deploy` job to your `.gitlab-ci.yml` file: @@ -795,11 +765,13 @@ is updated: - master ``` -1. Push those files to your repository. +1. Commit files to your repository. + +When the pipeline is successful, the package is created. ### Version validation -The version string is validated using the following regex. +The version string is validated by using the following regex. ```ruby \A(\.?[\w\+-]+\.?)+\z @@ -827,7 +799,7 @@ When you set these options, all network requests are logged and a large amount o ### Useful Maven command-line options There are some [Maven command-line options](https://maven.apache.org/ref/current/maven-embedder/cli.html) -that may be useful when performing tasks with GitLab CI/CD. +that you can use when performing tasks with GitLab CI/CD. - File transfer progress can make the CI logs hard to read. Option `-ntp,--no-transfer-progress` was added in @@ -835,7 +807,7 @@ that may be useful when performing tasks with GitLab CI/CD. Alternatively, look at `-B,--batch-mode` [or lower level logging changes.](https://stackoverflow.com/questions/21638697/disable-maven-download-progress-indication) -- Specify where to find the POM file (`-f,--file`): +- Specify where to find the `pom.xml` file (`-f,--file`): ```yaml package: @@ -852,11 +824,10 @@ that may be useful when performing tasks with GitLab CI/CD. - 'mvn -s settings/ci.xml package' ``` -### Verifying your Maven settings +### Verify your Maven settings -If you encounter issues within CI that relate to the `settings.xml` file, it might be useful -to add an additional script task or job to -[verify the effective settings](https://maven.apache.org/plugins/maven-help-plugin/effective-settings-mojo.html). +If you encounter issues within CI/CD that relate to the `settings.xml` file, try adding +an additional script task or job to [verify the effective settings](https://maven.apache.org/plugins/maven-help-plugin/effective-settings-mojo.html). The help plugin can also provide [system properties](https://maven.apache.org/plugins/maven-help-plugin/system-mojo.html), including environment variables: diff --git a/doc/user/packages/npm_registry/img/npm_package_view_v12_5.png b/doc/user/packages/npm_registry/img/npm_package_view_v12_5.png Binary files differdeleted file mode 100644 index a6f823011eb..00000000000 --- a/doc/user/packages/npm_registry/img/npm_package_view_v12_5.png +++ /dev/null diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index f15b31d8b67..feb797240f4 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -4,331 +4,378 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# GitLab NPM Registry +# NPM packages in the Package Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -With the GitLab NPM Registry, every -project can have its own space to store NPM packages. +Publish NPM packages in your project's Package Registry. Then install the +packages whenever you need to use them as a dependency. - - -NOTE: **Note:** Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported. -## Enabling the NPM Registry - -NOTE: **Note:** -This option is available only if your GitLab administrator has -[enabled support for the NPM registry](../../../administration/packages/index.md). - -Enabling the NPM registry makes it available for all new projects -by default. To enable it for existing projects, or if you want to disable it: - -1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. -1. Find the Packages feature and enable or disable it. -1. Click on **Save changes** for the changes to take effect. - -You should then be able to see the **Packages & Registries** section on the left sidebar. +## Build an NPM package -Before proceeding to authenticating with the GitLab NPM Registry, you should -get familiar with the package naming convention. +This section covers how to install NPM or Yarn and build a package for your +JavaScript project. -## Getting started +If you already use NPM and know how to build your own packages, go to +the [next section](#authenticate-to-the-package-registry). -This section covers how to install NPM (or Yarn) and build a package for your -JavaScript project. This is a quickstart if you are new to NPM packages. If you -are already using NPM and understand how to build your own packages, move on to -the [next section](#authenticating-to-the-gitlab-npm-registry). +### Install NPM -### Installing NPM +Install Node.js and NPM in your local development environment by following +the instructions at [npmjs.com](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). -Follow the instructions at [npmjs.com](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) to download and install Node.js and -NPM to your local development environment. - -Once installation is complete, verify you can use NPM in your terminal by +When installation is complete, verify you can use NPM in your terminal by running: ```shell npm --version ``` -You should see the NPM version printed in the output: +The NPM version is shown in the output: ```plaintext 6.10.3 ``` -### Installing Yarn +### Install Yarn -You may want to install and use Yarn as an alternative to NPM. Follow the -instructions at [yarnpkg.com](https://classic.yarnpkg.com/en/docs/install) to install on -your development environment. +As an alternative to NPM, you can install Yarn in your local environment by following the +instructions at [yarnpkg.com](https://classic.yarnpkg.com/en/docs/install). -Once installed, you can verify that Yarn is available with the following command: +When installation is complete, verify you can use Yarn in your terminal by +running: ```shell yarn --version ``` -You should see the version printed like so: +The Yarn version is shown in the output: ```plaintext 1.19.1 ``` -### Creating a project +### Create a project -Understanding how to create a full JavaScript project is outside the scope of -this guide but you can initialize a new empty package by creating and navigating -to an empty directory and using the following command: +To create a project: -```shell -npm init -``` +1. Create an empty directory. +1. Go to the directory and initialize an empty package by running: -Or if you're using Yarn: + ```shell + npm init + ``` -```shell -yarn init -``` + Or if you're using Yarn: + + ```shell + yarn init + ``` + +1. Enter responses to the questions. Ensure the **package name** follows + the [naming convention](#package-naming-convention) and is scoped to the + project or group where the registry exists. + +A `package.json` file is created. + +## Use the GitLab endpoint for NPM packages + +To use the GitLab endpoint for NPM packages, choose an option: + +- **Project-level**: Use when you have few NPM packages and they are not in + the same GitLab group. +- **Instance-level**: Use when you have many NPM packages in different + GitLab groups or in their own namespace. Be sure to comply with the [package naming convention](#package-naming-convention). -This takes you through a series of questions to produce a `package.json` -file, which is required for all NPM packages. The most important question is the -package name. NPM packages must [follow the naming convention](#package-naming-convention) -and be scoped to the project or group where the registry exists. +Some features such as [publishing](#publish-an-npm-package) a package is only available on the project-level endpoint. -Once you have completed the setup, you are now ready to upload your package to -the GitLab registry. To get started, you need to set up authentication and then -configure GitLab as a remote registry. +## Authenticate to the Package Registry -## Authenticating to the GitLab NPM Registry +To authenticate to the Package Registry, you must use one of the following: -If a project is private or you want to upload an NPM package to GitLab, -you need to provide credentials for authentication. [Personal access tokens](../../profile/personal_access_tokens.md) -and [deploy tokens](../../project/deploy_tokens/index.md) -are preferred, but support is available for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). +- A [personal access token](../../../user/profile/personal_access_tokens.md) + (required for two-factor authentication (2FA)), with the scope set to `api`. +- A [deploy token](../../project/deploy_tokens/index.md), with the scope set to `read_package_registry`, `write_package_registry`, or both. +- It's not recommended, but you can use [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). + Standard OAuth tokens cannot authenticate to the GitLab NPM Registry. You must use a personal access token with OAuth headers. +- A [CI job token](#authenticate-with-a-ci-job-token). -CAUTION: **Two-factor authentication (2FA) is only supported with personal access tokens:** -If you have 2FA enabled, you need to use a [personal access token](../../profile/personal_access_tokens.md) with OAuth headers with the scope set to `api` or a [deploy token](../../project/deploy_tokens/index.md) with `read_package_registry` or `write_package_registry` scopes. Standard OAuth tokens cannot authenticate to the GitLab NPM Registry. +### Authenticate with a personal access token or deploy token -### Authenticating with a personal access token or deploy token +To authenticate with the Package Registry, you will need a [personal access token](../../profile/personal_access_tokens.md) or [deploy token](../../project/deploy_tokens/index.md). -To authenticate with a [personal access token](../../profile/personal_access_tokens.md) or [deploy token](../../project/deploy_tokens/index.md), -set your NPM configuration: +#### Project-level NPM endpoint + +To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, set your NPM configuration: ```shell # Set URL for your scoped packages. # For example package with name `@foo/bar` will use this URL for download -npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/ +npm config set @foo:registry https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/ -# Add the token for the scoped packages URL. This will allow you to download -# `@foo/` packages from private projects. -npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "<your_token>" - -# Add token for uploading to the registry. Replace <your_project_id> -# with the project you want your package to be uploaded to. -npm config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" +# Add the token for the scoped packages URL. Replace <your_project_id> +# with the project where your package is located. +npm config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" ``` -Replace `<your_project_id>` with your project ID which can be found on the home page -of your project and `<your_token>` with your personal access token or deploy token. - -If you have a self-managed GitLab installation, replace `gitlab.com` with your -domain name. +- `<your_project_id>` is your project ID, found on the project's home page. +- `<your_token>` is your personal access token or deploy token. +- Replace `gitlab.example.com` with your domain name. -You should now be able to download and upload NPM packages to your project. +You should now be able to publish and install NPM packages in your project. -NOTE: **Note:** -If you encounter an error message with [Yarn](https://classic.yarnpkg.com/en/), see the -[troubleshooting section](#troubleshooting). +If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view +[troubleshooting steps](#troubleshooting). -### Using variables to avoid hard-coding auth token values +#### Instance-level NPM endpoint -To avoid hard-coding the `authToken` value, you may use a variables in its place: +To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, set your NPM configuration: ```shell -npm config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "${NPM_TOKEN}" -npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}" -``` +# Set URL for your scoped packages. +# For example package with name `@foo/bar` will use this URL for download +npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/ -Then, you could run `npm publish` either locally or via GitLab CI/CD: +# Add the token for the scoped packages URL. This will allow you to download +# `@foo/` packages from private projects. +npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>" +``` -- **Locally:** Export `NPM_TOKEN` before publishing: +- `<your_token>` is your personal access token or deploy token. +- Replace `gitlab.example.com` with your domain name. - ```shell - NPM_TOKEN=<your_token> npm publish - ``` +You should now be able to publish and install NPM packages in your project. -- **GitLab CI/CD:** Set an `NPM_TOKEN` [variable](../../../ci/variables/README.md) - under your project's **Settings > CI/CD > Variables**. +If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view +[troubleshooting steps](#troubleshooting). -### Authenticating with a CI job token +### Authenticate with a CI job token -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab Premium 12.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab Premium 12.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -If you’re using NPM with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. +If you're using NPM with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. The token inherits the permissions of the user that generates the pipeline. -Add a corresponding section to your `.npmrc` file: +#### Project-level NPM endpoint + +To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, add a corresponding section to your `.npmrc` file: ```ini -@foo:registry=https://gitlab.com/api/v4/packages/npm/ -//gitlab.com/api/v4/packages/npm/:_authToken=${CI_JOB_TOKEN} -//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN} +@foo:registry=https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/ +//gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN} ``` -## Uploading packages +#### Instance-level NPM endpoint -Before you can upload a package, you need to specify the registry -for NPM. To do this, add the following section to the bottom of `package.json`: +To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, add a corresponding section to your `.npmrc` file: -```json -"publishConfig": { - "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/" -} +```ini +@foo:registry=https://gitlab.example.com/api/v4/packages/npm/ +//gitlab.example.com/api/v4/packages/npm/:_authToken=${CI_JOB_TOKEN} ``` -Replace `<your_project_id>` with your project ID, which can be found on the home -page of your project, and replace `@foo` with your own scope. - -If you have a self-managed GitLab installation, replace `gitlab.com` with your -domain name. +#### Use variables to avoid hard-coding auth token values -Once you have enabled it and set up [authentication](#authenticating-to-the-gitlab-npm-registry), -you can upload an NPM package to your project: +To avoid hard-coding the `authToken` value, you may use a variable in its place: ```shell -npm publish +npm config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "${NPM_TOKEN}" +npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}" ``` -You can then navigate to your project's **Packages & Registries** page and see the uploaded -packages or even delete them. +Then, you can run `npm publish` either locally or by using GitLab CI/CD. -Attempting to publish a package with a name that already exists within -a given scope causes a `403 Forbidden!` error. +- **Locally:** Export `NPM_TOKEN` before publishing: -## Uploading a package with the same version twice + ```shell + NPM_TOKEN=<your_token> npm publish + ``` -You cannot upload a package with the same name and version twice, unless you -delete the existing package first. This aligns with npmjs.org's behavior, with -the exception that npmjs.org does not allow users to ever publish the same version -more than once, even if it has been deleted. +- **GitLab CI/CD:** Set an `NPM_TOKEN` [variable](../../../ci/variables/README.md) + under your project's **Settings > CI/CD > Variables**. ## Package naming convention -**Packages must be scoped in the root namespace of the project**. The package -name may be anything but it is preferred that the project name be used unless -it is not possible due to a naming collision. For example: +Your NPM package name must be in the format of `@scope:package-name`. + +- The `@scope` is the root namespace of the GitLab project. It must match exactly, including the case. +- The `package-name` can be whatever you want. + +For example, if your project is `https://gitlab.example.com/my-org/engineering-group/team-amazing/analytics`, +the root namespace is `my-org`. When you publish a package, it must have `my-org` as the scope. | Project | Package | Supported | | ---------------------- | ----------------------- | --------- | -| `foo/bar` | `@foo/bar` | Yes | -| `foo/bar/baz` | `@foo/baz` | Yes | -| `foo/bar/buz` | `@foo/anything` | Yes | +| `my-org/bar` | `@my-org/bar` | Yes | +| `my-org/bar/baz` | `@my-org/baz` | Yes | +| `My-org/Bar/baz` | `@My-org/Baz` | Yes | +| `my-org/bar/buz` | `@my-org/anything` | Yes | | `gitlab-org/gitlab` | `@gitlab-org/gitlab` | Yes | | `gitlab-org/gitlab` | `@foo/bar` | No | -The regex that is used for naming is validating all package names from all package managers: +In GitLab, this regex validates all package names from all package managers: ```plaintext /\A\@?(([\w\-\.\+]*)\/)*([\w\-\.]+)@?(([\w\-\.\+]*)\/)*([\w\-\.]*)\z/ ``` -It allows for capital letters, while NPM does not, and allows for almost all of the -characters NPM allows with a few exceptions (`~` is not allowed). +This regex allows almost all of the characters that NPM allows, with a few exceptions (for example, `~` is not allowed). + +The regex also allows for capital letters, while NPM does not. Capital letters are needed because the scope must be +identical to the root namespace of the project. -NOTE: **Note:** -Capital letters are needed because the scope is required to be -identical to the top level namespace of the project. So, for example, if your -project path is `My-Group/project-foo`, your package must be named `@My-Group/any-package-name`. -`@my-group/any-package-name` will not work. +CAUTION: **Caution:** +When you update the path of a user or group, or transfer a subgroup or project, +you must remove any NPM packages first. You cannot update the root namespace +of a project with NPM packages. Make sure you update your `.npmrc` files to follow +the naming convention and run `npm publish` if necessary. -CAUTION: **When updating the path of a user/group or transferring a (sub)group/project:** -Make sure to remove any NPM packages first. You cannot update the root namespace of a project with NPM packages. Don't forget to update your `.npmrc` files to follow the above naming convention and run `npm publish` if necessary. +## Publish an NPM package -Now, you can configure your project to authenticate with the GitLab NPM -Registry. +Prerequisites: -## Installing a package +- [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. +- Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages). -NPM packages are commonly installed using the `npm` or `yarn` commands -inside a JavaScript project. If you haven't already, set the -URL for scoped packages. You can do this with the following command: +To upload an NPM package to your project, run this command: ```shell -npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/ +npm publish ``` -Replace `@foo` with your scope. +To view the package, go to your project's **Packages & Registries**. -Next, you need to ensure [authentication](#authenticating-to-the-gitlab-npm-registry) -is setup so you can successfully install the package. Once this has been -completed, you can run the following command inside your project to install a -package: +If you try to publish a package [with a name that already exists](#publishing-packages-with-the-same-name-or-version) within +a given scope, you get a `403 Forbidden!` error. -```shell -npm install @my-project-scope/my-package -``` +## Publish an NPM package by using CI/CD -Or if you're using Yarn: +Prerequisites: -```shell -yarn add @my-project-scope/my-package +- [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. +- Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages). + +To work with NPM commands within [GitLab CI/CD](../../../ci/README.md), you can use +`CI_JOB_TOKEN` in place of the personal access token or deploy token in your commands. + +An example `.gitlab-ci.yml` file for publishing NPM packages: + +```yaml +image: node:latest + +stages: + - deploy + +deploy: + stage: deploy + script: + - echo "//gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc + - npm publish ``` -### Forwarding requests to npmjs.org +## Publishing packages with the same name or version + +You cannot publish a package if a package of the same name and version already exists. +You must delete the existing package first. + +This aligns with npmjs.org's behavior. However, npmjs.org does not ever let you publish +the same version more than once, even if it has been deleted. + +## Install a package + +NPM packages are commonly-installed by using the `npm` or `yarn` commands +in a JavaScript project. + +1. Set the URL for scoped packages by running: + + ```shell + npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/ + ``` + + Replace `@foo` with your scope. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/55344) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. +1. Ensure [authentication](#authenticate-to-the-package-registry) is configured. -By default, when an NPM package is not found in the GitLab NPM Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/). +1. In your project, to install a package, run: + + ```shell + npm install @my-project-scope/my-package + ``` + + Or if you're using Yarn: + + ```shell + yarn add @my-project-scope/my-package + ``` + +In [GitLab 12.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/55344), +when an NPM package is not found in the Package Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/). Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). -### Installing packages from other organizations +### Install NPM packages from other organizations You can route package requests to organizations and users outside of GitLab. -To do this, add lines to your `.npmrc` file, replacing `my-org` with the namespace or group that owns your project's repository. The name is case-sensitive and must match the name of your group or namespace exactly. +To do this, add lines to your `.npmrc` file. Replace `my-org` with the namespace or group that owns your project's repository, +and use your organization's URL. The name is case-sensitive and must match the name of your group or namespace exactly. ```shell @foo:registry=https://gitlab.example.com/api/v4/packages/npm/ -//gitlab.com/api/v4/packages/npm/:_authToken= "<your_token>" -//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" +//gitlab.example.com/api/v4/packages/npm/:_authToken= "<your_token>" +//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" @my-other-org:registry=https://gitlab.example.com/api/v4/packages/npm/ -//gitlab.com/api/v4/packages/npm/:_authToken= "<your_token>" -//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" +//gitlab.example.com/api/v4/packages/npm/:_authToken= "<your_token>" +//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" ``` -## Removing a package +### NPM dependencies metadata -In the packages view of your project page, you can delete packages by clicking -the red trash icons or by clicking the **Delete** button on the package details -page. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) in GitLab Premium 12.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -## Publishing a package with CI/CD +In GitLab 12.6 and later, packages published to the Package Registry expose the following attributes to the NPM client: -To work with NPM commands within [GitLab CI/CD](./../../../ci/README.md), you can use -`CI_JOB_TOKEN` in place of the personal access token or deploy token in your commands. +- name +- version +- dist-tags +- dependencies + - dependencies + - devDependencies + - bundleDependencies + - peerDependencies + - deprecated -A simple example `.gitlab-ci.yml` file for publishing NPM packages: +## Add NPM distribution tags -```yaml -image: node:latest +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9425) in GitLab Premium 12.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -stages: - - deploy +You can add [distribution tags](https://docs.npmjs.com/cli/dist-tag) to newly-published packages. +Tags are optional and can be assigned to only one package at a time. -deploy: - stage: deploy - script: - - echo "//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc - - npm publish +When you publish a package without a tag, the `latest` tag is added by default. +When you install a package without specifying the tag or version, the `latest` tag is used. + +Examples of the supported `dist-tag` commands: + +```shell +npm publish @scope/package --tag # Publish a package with new tag +npm dist-tag add @scope/package@version my-tag # Add a tag to an existing package +npm dist-tag ls @scope/package # List all tags under the package +npm dist-tag rm @scope/package@version my-tag # Delete a tag from the package +npm install @scope/package@my-tag # Install a specific tag ``` -Learn more about [using `CI_JOB_TOKEN` to authenticate to the GitLab NPM registry](#authenticating-with-a-ci-job-token). +You cannot use your `CI_JOB_TOKEN` or deploy token with the `npm dist-tag` commands. +View [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/258835) for details. + +Due to a bug in NPM 6.9.0, deleting distribution tags fails. Make sure your NPM version is 6.9.1 or later. ## Troubleshooting @@ -344,7 +391,7 @@ info No lockfile found. warning XXX: No license field [1/4] 🔍 Resolving packages... [2/4] 🚚 Fetching packages... -error An unexpected error occurred: "https://gitlab.com/api/v4/projects/XXX/packages/npm/XXX/XXX/-/XXX/XXX-X.X.X.tgz: Request failed \"404 Not Found\"". +error An unexpected error occurred: "https://gitlab.example.com/api/v4/projects/XXX/packages/npm/XXX/XXX/-/XXX/XXX-X.X.X.tgz: Request failed \"404 Not Found\"". info If you think this is a bug, please open a bug report with the information provided in "/Users/XXX/gitlab-migration/module-util/yarn-error.log". info Visit https://classic.yarnpkg.com/en/docs/cli/install for documentation about this command ``` @@ -353,14 +400,14 @@ In this case, try adding this to your `.npmrc` file (and replace `<your_token>` with your personal access token or deploy token): ```plaintext -//gitlab.com/api/v4/projects/:_authToken=<your_token> +//gitlab.example.com/api/v4/projects/:_authToken=<your_token> ``` You can also use `yarn config` instead of `npm config` when setting your auth-token dynamically: ```shell -yarn config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" -yarn config set '//gitlab.com/api/v4/packages/npm/:_authToken' "<your_token>" +yarn config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" +yarn config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>" ``` ### `npm publish` targets default NPM registry (`registry.npmjs.org`) @@ -375,23 +422,20 @@ should look like: "name": "@foo/my-package", "version": "1.0.0", "description": "Example package for GitLab NPM registry", - "publishConfig": { - "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/" - } } ``` And the `.npmrc` file should look like: ```ini -//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_token> -//gitlab.com/api/v4/packages/npm/:_authToken=<your_token> -@foo:registry=https://gitlab.com/api/v4/packages/npm/ +//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_token> +//gitlab.example.com/api/v4/packages/npm/:_authToken=<your_token> +@foo:registry=https://gitlab.example.com/api/v4/packages/npm/ ``` ### `npm install` returns `Error: Failed to replace env in config: ${NPM_TOKEN}` -You do not need a token to run `npm install` unless your project is private (the token is only required to publish). If the `.npmrc` file was checked in with a reference to `$NPM_TOKEN`, you can remove it. If you prefer to leave the reference in, you need to set a value prior to running `npm install` or set the value using [GitLab environment variables](./../../../ci/variables/README.md): +You do not need a token to run `npm install` unless your project is private. The token is only required to publish. If the `.npmrc` file was checked in with a reference to `$NPM_TOKEN`, you can remove it. If you prefer to leave the reference in, you must set a value prior to running `npm install` or set the value by using [GitLab environment variables](../../../ci/variables/README.md): ```shell NPM_TOKEN=<your_token> npm install @@ -399,50 +443,11 @@ NPM_TOKEN=<your_token> npm install ### `npm install` returns `npm ERR! 403 Forbidden` -- Check that your token is not expired and has appropriate permissions. -- Check that [your token does not begin with `-`](https://gitlab.com/gitlab-org/gitlab/-/issues/235473). -- Check if you have attempted to publish a package with a name that already exists within a given scope. -- Ensure the scoped packages URL includes a trailing slash: - - Correct: `//gitlab.com/api/v4/packages/npm/` - - Incorrect: `//gitlab.com/api/v4/packages/npm` - -## NPM dependencies metadata - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) in GitLab Premium 12.6. - -Starting from GitLab 12.6, new packages published to the GitLab NPM Registry expose the following attributes to the NPM client: - -- name -- version -- dist-tags -- dependencies - - dependencies - - devDependencies - - bundleDependencies - - peerDependencies - - deprecated - -## NPM distribution tags - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9425) in GitLab Premium 12.8. - -You can add [distribution tags](https://docs.npmjs.com/cli/dist-tag) for newly published packages. -They follow NPM's convention where they are optional, and each tag can only be assigned to one -package at a time. The `latest` tag is added by default when a package is published without a tag. -The same applies to installing a package without specifying the tag or version. - -Examples of the supported `dist-tag` commands and using tags in general: - -```shell -npm publish @scope/package --tag # Publish new package with new tag -npm dist-tag add @scope/package@version my-tag # Add a tag to an existing package -npm dist-tag ls @scope/package # List all tags under the package -npm dist-tag rm @scope/package@version my-tag # Delete a tag from the package -npm install @scope/package@my-tag # Install a specific tag -``` - -NOTE: **Note:** -You cannot use your `CI_JOB_TOKEN` or deploy token with the `npm dist-tag` commands. View [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/258835) for details. +If you get this error, ensure that: -CAUTION: **Warning:** -Due to a bug in NPM 6.9.0, deleting dist tags fails. Make sure your NPM version is greater than 6.9.1. +- Your token is not expired and has appropriate permissions. +- [Your token does not begin with `-`](https://gitlab.com/gitlab-org/gitlab/-/issues/235473). +- A package with the same name doesn't already exist within the given scope. +- The scoped packages URL includes a trailing slash: + - Correct: `//gitlab.example.com/api/v4/packages/npm/` + - Incorrect: `//gitlab.example.com/api/v4/packages/npm` diff --git a/doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png b/doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png Binary files differindex e4f6068f28c..8c14a14e304 100644 --- a/doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png +++ b/doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 22e1a95649d..2b61c4a6c28 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -4,34 +4,38 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# GitLab NuGet Repository +# NuGet packages in the Package Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -With the GitLab NuGet Repository, every project can have its own space to store NuGet packages. +Publish NuGet packages in your project’s Package Registry. Then, install the +packages whenever you need to use them as a dependency. -The GitLab NuGet Repository works with: +The Package Registry works with: - [NuGet CLI](https://docs.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference) - [.NET Core CLI](https://docs.microsoft.com/en-us/dotnet/core/tools/) - [Visual Studio](https://visualstudio.microsoft.com/vs/) -## Setting up your development environment +## Install NuGet -[NuGet CLI 5.1 or later](https://www.nuget.org/downloads) is required. Earlier versions have not been tested -against the GitLab NuGet Repository and might not work. If you have [Visual Studio](https://visualstudio.microsoft.com/vs/), -NuGet CLI is probably already installed. +The required minimum versions are: -Alternatively, you can use [.NET SDK 3.0 or later](https://dotnet.microsoft.com/download/dotnet-core/3.0), which installs NuGet CLI. +- [NuGet CLI 5.1 or later](https://www.nuget.org/downloads). If you have + [Visual Studio](https://visualstudio.microsoft.com/vs/), the NuGet CLI is + probably already installed. +- Alternatively, you can use [.NET SDK 3.0 or later](https://dotnet.microsoft.com/download/dotnet-core/3.0), + which installs the NuGet CLI. +- NuGet protocol version 3 or later. -You can confirm that [NuGet CLI](https://www.nuget.org/) is properly installed with: +Verify that the [NuGet CLI](https://www.nuget.org/) is installed by running: ```shell nuget help ``` -You should see something similar to: +The output should be similar to: ```plaintext NuGet Version: 5.1.0.6013 @@ -43,103 +47,98 @@ Available commands: [output truncated] ``` -NOTE: **Note:** -GitLab currently only supports NuGet's protocol version 3. Earlier versions are not supported. +### Install NuGet on macOS -### macOS support +For macOS, you can use [Mono](https://www.mono-project.com/) to run the +NuGet CLI. -For macOS, you can also use [Mono](https://www.mono-project.com/) to run -the NuGet CLI. For Homebrew users, run `brew install mono` to install -Mono. Then you should be able to download the Windows C# binary -`nuget.exe` from the [NuGet CLI page](https://www.nuget.org/downloads) -and run: +1. If you use Homebrew, to install Mono, run `brew install mono`. +1. Download the Windows C# binary `nuget.exe` from the [NuGet CLI page](https://www.nuget.org/downloads). +1. Run this command: -```shell -mono nuget.exe -``` - -## Enabling the NuGet Repository - -NOTE: **Note:** -This option is available only if your GitLab administrator has -[enabled support for the Package Registry](../../../administration/packages/index.md). - -When the NuGet Repository is enabled, it is available for all new projects -by default. To enable it for existing projects, or if you want to disable it: - -1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. -1. Find the Packages feature and enable or disable it. -1. Click on **Save changes** for the changes to take effect. + ```shell + mono nuget.exe + ``` -You should then be able to see the **Packages & Registries** section on the left sidebar. +## Add the Package Registry as a source for NuGet packages -## Adding the GitLab NuGet Repository as a source to NuGet +To publish and install packages to the Package Registry, you must add the +Package Registry as a source for your packages. -You need the following: +Prerequisites: - Your GitLab username. - A personal access token or deploy token. For repository authentication: - - You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`. - - You can generate a [deploy token](./../../project/deploy_tokens/index.md) with the scope set to `read_package_registry`, `write_package_registry`, or both. -- A suitable name for your source. -- Your project ID which can be found on the home page of your project. + - You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) + with the scope set to `api`. + - You can generate a [deploy token](../../project/deploy_tokens/index.md) + with the scope set to `read_package_registry`, `write_package_registry`, or + both. +- A name for your source. +- Your project ID, which is found on your project's home page. You can now add a new source to NuGet with: -- [NuGet CLI](#add-nuget-repository-source-with-nuget-cli) -- [Visual Studio](#add-nuget-repository-source-with-visual-studio). -- [.NET CLI](#add-nuget-repository-source-with-net-cli) +- [NuGet CLI](#add-a-source-with-the-nuget-cli) +- [Visual Studio](#add-a-source-with-visual-studio) +- [.NET CLI](#add-a-source-with-the-net-cli) -### Add NuGet Repository source with NuGet CLI +### Add a source with the NuGet CLI -To add the GitLab NuGet Repository as a source with `nuget`: +To add the Package Registry as a source with `nuget`: ```shell -nuget source Add -Name <source_name> -Source "https://gitlab-instance.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token> +nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token> ``` -Where: - -- `<source_name>` is your desired source name. +- `<source_name>` is the desired source name. For example: ```shell -nuget source Add -Name "GitLab" -Source "https://gitlab.example/api/v4/projects/10/packages/nuget/index.json" -UserName carol -Password 12345678asdf +nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName carol -Password 12345678asdf ``` -### Add NuGet Repository source with Visual Studio +### Add a source with Visual Studio + +To add the Package Registry as a source with Visual Studio: 1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). -1. Open the **FILE > OPTIONS** (Windows) or **Visual Studio > Preferences** (Mac OS). -1. In the **NuGet** section, open **Sources** to see a list of all your NuGet sources. -1. Click **Add**. -1. Fill the fields with: - - **Name**: Desired name for the source - - **Location**: `https://gitlab.com/api/v4/projects/<your_project_id>/packages/nuget/index.json` - - Replace `<your_project_id>` with your project ID. - - If you have a self-managed GitLab installation, replace `gitlab.com` with your domain name. - - **Username**: Your GitLab username or deploy token username - - **Password**: Your personal access token or deploy token +1. In Windows, select **File > Options**. On macOS, select **Visual Studio > Preferences**. +1. In the **NuGet** section, select **Sources** to view a list of all your NuGet sources. +1. Select **Add**. +1. Complete the following fields: + - **Name**: Name for the source. + - **Location**: `https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json`, + where `<your_project_id>` is your project ID, and `gitlab.example.com` is + your domain name. + - **Username**: Your GitLab username or deploy token username. + - **Password**: Your personal access token or deploy token.  1. Click **Save**. -  +The source is displayed in your list. -In case of any warning, please make sure that the **Location**, **Username**, and **Password** are correct. + -### Add NuGet Repository source with .NET CLI +If you get a warning, ensure that the **Location**, **Username**, and +**Password** are correct. -To add the GitLab NuGet Repository as a source for .NET, create a file named `nuget.config` in the root of your project with the following content: +### Add a source with the .NET CLI -```xml -<?xml version="1.0" encoding="utf-8"?> -<configuration> +To add the Package Registry as a source for .NET: + +1. In the root of your project, create a file named `nuget.config`. +1. Add this content: + + ```xml + <?xml version="1.0" encoding="utf-8"?> + <configuration> <packageSources> <clear /> - <add key="gitlab" value="https://gitlab-instance.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" /> + <add key="gitlab" value="https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" /> </packageSources> <packageSourceCredentials> <gitlab> @@ -147,46 +146,51 @@ To add the GitLab NuGet Repository as a source for .NET, create a file named `nu <add key="ClearTextPassword" value="<gitlab_personal_access_token or deploy_token>" /> </gitlab> </packageSourceCredentials> -</configuration> -``` + </configuration> + ``` + +## Publish a NuGet package -## Uploading packages +When publishing packages: -When uploading packages, note that: +- The Package Registry on GitLab.com can store up to 500 MB of content. + This limit is [configurable for self-managed GitLab instances](../../../administration/instance_limits.md#package-registry-limits). +- If you publish the same package with the same version multiple times, each + consecutive upload is saved as a separate file. When installing a package, + GitLab serves the most recent file. +- When publishing packages to GitLab, they aren't displayed in the packages user + interface of your project immediately. It can take up to 10 minutes to process + a package. -- The Package Registry on GitLab.com can store up to 500 MB of content. This limit is [configurable for self-managed GitLab instances](../../../administration/instance_limits.md#package-registry-limits). -- If you upload the same package with the same version multiple times, each consecutive upload - is saved as a separate file. When installing a package, GitLab serves the most recent file. -- When uploading packages to GitLab, they are not displayed in the packages UI of your project - immediately. It can take up to 10 minutes to process a package. +### Publish a package with the NuGet CLI -### Upload packages with NuGet CLI +Prerequisite: -This section assumes that your project is properly built and you already [created a NuGet package with NuGet CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package). -Upload your package using the following command: +- [A NuGet package created with NuGet CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package). + +Publish a package by running this command: ```shell nuget push <package_file> -Source <source_name> ``` -Where: - - `<package_file>` is your package filename, ending in `.nupkg`. -- `<source_name>` is the [source name used during setup](#adding-the-gitlab-nuget-repository-as-a-source-to-nuget). +- `<source_name>` is the [source name used during setup](#add-a-source-with-the-nuget-cli). + +### Publish a package with the .NET CLI + +Prerequisite: -### Upload packages with .NET CLI +[A NuGet package created with .NET CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli). -This section assumes that your project is properly built and you already [created a NuGet package with .NET CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli). -Upload your package using the following command: +Publish a package by running this command: ```shell dotnet nuget push <package_file> --source <source_name> ``` -Where: - - `<package_file>` is your package filename, ending in `.nupkg`. -- `<source_name>` is the [source name used during setup](#adding-the-gitlab-nuget-repository-as-a-source-to-nuget). +- `<source_name>` is the [source name used during setup](#add-a-source-with-the-net-cli). For example: @@ -194,16 +198,47 @@ For example: dotnet nuget push MyPackage.1.0.0.nupkg --source gitlab ``` +### Publish a NuGet package by using CI/CD + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36424) in GitLab 13.3. + +If you’re using NuGet with GitLab CI/CD, a CI job token can be used instead of a +personal access token or deploy token. The token inherits the permissions of the +user that generates the pipeline. + +This example shows how to create a new package each time the `master` branch is +updated: + +1. Add a `deploy` job to your `.gitlab-ci.yml` file: + + ```yaml + image: mcr.microsoft.com/dotnet/core/sdk:3.1 + + stages: + - deploy + + deploy: + stage: deploy + script: + - dotnet pack -c Release + - dotnet nuget add source "$CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text + - dotnet nuget push "bin/Release/*.nupkg" --source gitlab + only: + - master + ``` + +1. Commit the changes and push it to your GitLab repository to trigger a new CI/CD build. + ## Install packages -### Install a package with NuGet CLI +### Install a package with the NuGet CLI CAUTION: **Warning:** -By default, `nuget` checks the official source at `nuget.org` first. If you have a package in the -GitLab NuGet Repository with the same name as a package at `nuget.org`, you must specify the source -name to install the correct package. +By default, `nuget` checks the official source at `nuget.org` first. If you have +a NuGet package in the Package Registry with the same name as a package at +`nuget.org`, you must specify the source name to install the correct package. -Install the latest version of a package using the following command: +Install the latest version of a package by running this command: ```shell nuget install <package_id> -OutputDirectory <output_directory> \ @@ -211,60 +246,24 @@ nuget install <package_id> -OutputDirectory <output_directory> \ -Source <source_name> ``` -Where: - - `<package_id>` is the package ID. - `<output_directory>` is the output directory, where the package is installed. -- `<package_version>` (Optional) is the package version. -- `<source_name>` (Optional) is the source name. +- `<package_version>` The package version. Optional. +- `<source_name>` The source name. Optional. -### Install a package with .NET CLI +### Install a package with the .NET CLI CAUTION: **Warning:** -If you have a package in the GitLab NuGet Repository with the same name as a package at a different source, -you should verify the order in which `dotnet` checks sources during install. This is defined in the -`nuget.config` file. +If you have a package in the Package Registry with the same name as a package at +a different source, verify the order in which `dotnet` checks sources during +install. This is defined in the `nuget.config` file. -Install the latest version of a package using the following command: +Install the latest version of a package by running this command: ```shell dotnet add package <package_id> \ -v <package_version> ``` -Where: - - `<package_id>` is the package ID. -- `<package_version>` (Optional) is the package version. - -## Publishing a NuGet package with CI/CD - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36424) in GitLab 13.3. - -If you’re using NuGet with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. -The token inherits the permissions of the user that generates the pipeline. - -This example shows how to create a new package each time the `master` branch -is updated: - -1. Add a `deploy` job to your `.gitlab-ci.yml` file: - - ```yaml - image: mcr.microsoft.com/dotnet/core/sdk:3.1 - - stages: - - deploy - - deploy: - stage: deploy - script: - - dotnet restore -p:Configuration=Release - - dotnet build -c Release - - dotnet pack -c Release - - dotnet nuget add source "$CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text - - dotnet nuget push "bin/Release/*.nupkg" --source gitlab - only: - - master - ``` - -1. Commit the changes and push it to your GitLab repository to trigger a new CI build. +- `<package_version>` is the package version. Optional. diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index ae9ca5b2333..56fd4a02ba0 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -31,23 +31,30 @@ authenticate with GitLab by using the `CI_JOB_TOKEN`. CI/CD templates, which you can use to get started, are in [this repo](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). -Learn more about [using CI/CD to build Maven packages](../maven_repository/index.md#creating-maven-packages-with-gitlab-cicd), [NPM packages](../npm_registry/index.md#publishing-a-package-with-cicd), [Composer packages](../composer_repository/index.md#publish-a-composer-package-by-using-cicd), [NuGet Packages](../nuget_repository/index.md#publishing-a-nuget-package-with-cicd), [Conan Packages](../conan_repository/index.md#publish-a-conan-package-by-using-cicd), [PyPI packages](../pypi_repository/index.md#using-gitlab-ci-with-pypi-packages), and [generic packages](../generic_packages/index.md#publish-a-generic-package-by-using-cicd). +Learn more about using CI/CD to build: -If you use CI/CD to build a package, extended activity -information is displayed when you view the package details: +- [Maven packages](../maven_repository/index.md#create-maven-packages-with-gitlab-cicd) +- [NPM packages](../npm_registry/index.md#publish-an-npm-package-by-using-cicd) +- [Composer packages](../composer_repository/index.md#publish-a-composer-package-by-using-cicd) +- [NuGet packages](../nuget_repository/index.md#publish-a-nuget-package-by-using-cicd) +- [Conan packages](../conan_repository/index.md#publish-a-conan-package-by-using-cicd) +- [Generic packages](../generic_packages/index.md#publish-a-generic-package-by-using-cicd) + +If you use CI/CD to build a package, extended activity information is displayed +when you view the package details:  -When using Maven and NPM, you can view which pipeline published the package, as well as the commit and -user who triggered it. +When using Maven and NPM, you can view which pipeline published the package, and +the commit and user who triggered it. ## Download a package To download a package: 1. Go to **Packages & Registries > Package Registry**. -1. Click the name of the package you want to download. -1. In the **Activity** section, click the name of the package you want to download. +1. Select the name of the package you want to download. +1. In the **Activity** section, select the name of the package you want to download. ## Delete a package diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 33c37ee6a6c..83b29d5f53a 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -4,89 +4,83 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# GitLab PyPI Repository +# PyPI packages in the Package Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -With the GitLab PyPI Repository, every project can have its own space to store PyPI packages. +Publish PyPI packages in your project’s Package Registry. Then install the +packages whenever you need to use them as a dependency. -The GitLab PyPI Repository works with: +The Package Registry works with: - [pip](https://pypi.org/project/pip/) - [twine](https://pypi.org/project/twine/) -## Setting up your development environment +## Build a PyPI package -You need a recent version of [pip](https://pypi.org/project/pip/) and [twine](https://pypi.org/project/twine/). +This section explains how to create a PyPI package. -## Enabling the PyPI Repository +If you already use PyPI and know how to build your own packages, go to the +[next section](#authenticate-with-the-package-registry). -NOTE: **Note:** -This option is available only if your GitLab administrator has -[enabled support for the Package Registry](../../../administration/packages/index.md). +### Install pip and twine -After the PyPI Repository is enabled, it is available for all new projects -by default. To enable it for existing projects, or if you want to disable it: +Install a recent version of [pip](https://pypi.org/project/pip/) and +[twine](https://pypi.org/project/twine/). -1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. -1. Find the Packages feature and enable or disable it. -1. Click on **Save changes** for the changes to take effect. +### Create a project -You should then be able to see the **Packages & Registries** section on the left sidebar. +Create a test project. -## Getting started +1. Open your terminal. +1. Create a directory called `MyPyPiPackage`, and then go to that directory: -This section covers creating a new example PyPI package to upload. This is a -quickstart to test out the **GitLab PyPI Registry**. If you already understand how -to build and publish your own packages, move on to the [next section](#adding-the-gitlab-pypi-repository-as-a-source). + ```shell + mkdir MyPyPiPackage && cd MyPyPiPackage + ``` -### Create a project +1. Create another directory and go to it: -Understanding how to create a full Python project is outside the scope of this -guide, but you can create a small package to test out the registry. Start by -creating a new directory called `MyPyPiPackage`: + ```shell + mkdir mypypipackage && cd mypypipackage + ``` -```shell -mkdir MyPyPiPackage && cd MyPyPiPackage -``` +1. Create the required files in this directory: -After creating this, create another directory inside: + ```shell + touch __init__.py + touch greet.py + ``` -```shell -mkdir mypypipackage && cd mypypipackage -``` +1. Open the `greet.py` file, and then add: -Create two new files inside this directory to set up the basic project: + ```python + def SayHello(): + print("Hello from MyPyPiPackage") + return + ``` -```shell -touch __init__.py -touch greet.py -``` +1. Open the `__init__.py` file, and then add: -Inside `greet.py`, add the following code: + ```python + from .greet import SayHello + ``` -```python -def SayHello(): - print("Hello from MyPyPiPackage") - return -``` +1. To test the code, in your `MyPyPiPackage` directory, start the Python prompt. -Inside the `__init__.py` file, add the following: + ```shell + python + ``` -```python -from .greet import SayHello -``` +1. Run this command: -Now that the basics of our project is completed, we can test that the code runs. -Start the Python prompt inside your top `MyPyPiPackage` directory. Then run: + ```python + >>> from mypypipackage import SayHello + >>> SayHello() + ``` -```python ->>> from mypypipackage import SayHello ->>> SayHello() -``` - -You should see an output similar to the following: +A message indicates that the project was set up successfully: ```plaintext Python 3.8.2 (v3.8.2:7b3ab5921f, Feb 24 2020, 17:52:18) @@ -97,80 +91,81 @@ Type "help", "copyright", "credits" or "license" for more information. Hello from MyPyPiPackage ``` -Once we've verified that the sample project is working as above, we can next -work on creating a package. - ### Create a package -Inside your `MyPyPiPackage` directory, we need to create a `setup.py` file. Run -the following: +After you create a project, you can create a package. -```shell -touch setup.py -``` +1. In your terminal, go to the `MyPyPiPackage` directory. +1. Create a `setup.py` file: -This file contains all the information about our package. For more information -about this file, see [creating setup.py](https://packaging.python.org/tutorials/packaging-projects/#creating-setup-py). -GitLab identifies packages based on -[Python normalized names (PEP-503)](https://www.python.org/dev/peps/pep-0503/#normalized-names), -so ensure your package name meets these requirements. -See the [installation section](#install-packages) for more details. - -For this guide, we don't need to extensively fill out this file, simply add the -below to your `setup.py`: - -```python -import setuptools - -setuptools.setup( - name="mypypipackage", - version="0.0.1", - author="Example Author", - author_email="author@example.com", - description="A small example package", - packages=setuptools.find_packages(), - classifiers=[ - "Programming Language :: Python :: 3", - "License :: OSI Approved :: MIT License", - "Operating System :: OS Independent", - ], - python_requires='>=3.6', -) -``` + ```shell + touch setup.py + ``` -Save the file, then execute the setup like so: + This file contains all the information about the package. For more information + about this file, see [creating setup.py](https://packaging.python.org/tutorials/packaging-projects/#creating-setup-py). + Because GitLab identifies packages based on + [Python normalized names (PEP-503)](https://www.python.org/dev/peps/pep-0503/#normalized-names), + ensure your package name meets these requirements. See the [installation section](#authenticate-with-a-ci-job-token) + for details. -```shell -python3 setup.py sdist bdist_wheel -``` +1. Open the `setup.py` file, and then add basic information: + + ```python + import setuptools -If successful, you should be able to see the output in a newly created `dist` -folder. Run: + setuptools.setup( + name="mypypipackage", + version="0.0.1", + author="Example Author", + author_email="author@example.com", + description="A small example package", + packages=setuptools.find_packages(), + classifiers=[ + "Programming Language :: Python :: 3", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", + ], + python_requires='>=3.6', + ) + ``` + +1. Save the file. +1. Execute the setup: + + ```shell + python3 setup.py sdist bdist_wheel + ``` + +The output should be visible in a newly-created `dist` folder: ```shell ls dist ``` -And confirm your output matches the below: +The output should appear similar to the following: ```plaintext mypypipackage-0.0.1-py3-none-any.whl mypypipackage-0.0.1.tar.gz ``` -Our package is now all set up and ready to be uploaded to the **GitLab PyPI -Package Registry**. Before we do so, we next need to set up authentication. +The package is now ready to be published to the Package Registry. -## Adding the GitLab PyPI Repository as a source +## Authenticate with the Package Registry -### Authenticating with a personal access token +Before you can publish to the Package Registry, you must authenticate. -You need the following: +To do this, you can use: -- A personal access token. You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. -- A suitable name for your source. -- Your project ID which can be found on the home page of your project. +- A [personal access token](../../../user/profile/personal_access_tokens.md) + with the scope set to `api`. +- A [deploy token](../../project/deploy_tokens/index.md) with the scope set to + `read_package_registry`, `write_package_registry`, or both. +- A [CI job token](#authenticate-with-a-ci-job-token). -Edit your `~/.pypirc` file and add the following: +### Authenticate with a personal access token + +To authenticate with a personal access token, edit the `~/.pypirc` file and add: ```ini [distutils] @@ -178,20 +173,17 @@ index-servers = gitlab [gitlab] -repository = https://gitlab.com/api/v4/projects/<project_id>/packages/pypi +repository = https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi username = __token__ password = <your personal access token> ``` -### Authenticating with a deploy token - -You need the following: +- `username` must be `__token__` exactly. +- Your project ID is on your project's home page. -- A deploy token. You can generate a [deploy token](./../../project/deploy_tokens/index.md) with the `read_package_registry` and/or `write_package_registry` scopes for repository authentication. -- A suitable name for your source. -- Your project ID which can be found on the home page of your project. +### Authenticate with a deploy token -Edit your `~/.pypirc` file and add the following: +To authenticate with a deploy token, edit your `~/.pypirc` file and add: ```ini [distutils] @@ -199,21 +191,58 @@ index-servers = gitlab [gitlab] -repository = https://gitlab.com/api/v4/projects/<project_id>/packages/pypi +repository = https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi username = <deploy token username> password = <deploy token> ``` -## Uploading packages +Your project ID is on your project's home page. -When uploading packages, note that: +### Authenticate with a CI job token -- The maximum allowed size is 50 Megabytes. -- You cannot upload the same version of a package multiple times. If you try, you receive the error `Validation failed: File name has already been taken`. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202012) in GitLab 13.4. + +To work with PyPI commands within [GitLab CI/CD](../../../ci/README.md), you +can use `CI_JOB_TOKEN` instead of a personal access token or deploy token. + +For example: + +```yaml +image: python:latest + +run: + script: + - pip install twine + - python setup.py sdist bdist_wheel + - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/pypi dist/* +``` + +You can also use `CI_JOB_TOKEN` in a `~/.pypirc` file that you check in to +GitLab: + +```ini +[distutils] +index-servers = + gitlab + +[gitlab] +repository = https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/pypi +username = gitlab-ci-token +password = ${env.CI_JOB_TOKEN} +``` + +## Publish a PyPI package + +When publishing packages, note that: + +- The maximum allowed size is 50 MB. +- You can't upload the same version of a package multiple times. If you try, + you'll receive the error `Validation failed: File name has already been taken`. ### Ensure your version string is valid -If your version string (for example, `0.0.1`) is invalid, it will be rejected. GitLab uses the following regex to validate the version string. +If your version string (for example, `0.0.1`) isn't valid, it will be rejected. +GitLab uses the following regex to validate the version string. ```ruby \A(?: @@ -227,118 +256,86 @@ If your version string (for example, `0.0.1`) is invalid, it will be rejected. G )\z}xi ``` -You can play around with the regex and try your version strings on [this regular expression editor](https://rubular.com/r/FKM6d07ouoDaFV). +You can experiment with the regex and try your version strings by using this +[regular expression editor](https://rubular.com/r/FKM6d07ouoDaFV). -For more details about the regex used, please check the [documentation here](https://www.python.org/dev/peps/pep-0440/#appendix-b-parsing-version-strings-with-regular-expressions)) +For more details about the regex, review this [documentation](https://www.python.org/dev/peps/pep-0440/#appendix-b-parsing-version-strings-with-regular-expressions). -### Upload packages with Twine +### Publish a PyPI package by using twine -If you were following the guide above, then the `MyPyPiPackage` package should -be ready to be uploaded. Run the following command: +To publish a PyPI package, run a command like: ```shell python3 -m twine upload --repository gitlab dist/* ``` -If successful, you should see the following: +This message indicates that the package was published successfully: ```plaintext -Uploading distributions to https://gitlab.com/api/v4/projects/<your_project_id>/packages/pypi +Uploading distributions to https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi Uploading mypypipackage-0.0.1-py3-none-any.whl 100%|███████████████████████████████████████████████████████████████████████████████████████████| 4.58k/4.58k [00:00<00:00, 10.9kB/s] Uploading mypypipackage-0.0.1.tar.gz 100%|███████████████████████████████████████████████████████████████████████████████████████████| 4.24k/4.24k [00:00<00:00, 11.0kB/s] ``` -This indicates that the package was uploaded successfully. You can then navigate -to your project's **Packages & Registries** page and see the uploaded packages. +To view the published package, go to your project's **Packages & Registries** +page. -If you would rather not use a `.pypirc` file to define your repository source, -you can upload to the repository with the authentication inline: +If you didn't use a `.pypirc` file to define your repository source, you can +publish to the repository with the authentication inline: ```shell -TWINE_PASSWORD=<personal_access_token or deploy_token> TWINE_USERNAME=<username or deploy_token_username> python3 -m twine upload --repository-url https://gitlab.com/api/v4/projects/<project_id>/packages/pypi dist/* +TWINE_PASSWORD=<personal_access_token or deploy_token> TWINE_USERNAME=<username or deploy_token_username> python3 -m twine upload --repository-url https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi dist/* ``` -If you did not follow the guide above, then you need to ensure your package -has been properly built and you [created a PyPI package with `setuptools`](https://packaging.python.org/tutorials/packaging-projects/). +If you didn't follow the steps on this page, ensure your package was properly +built, and that you [created a PyPI package with `setuptools`](https://packaging.python.org/tutorials/packaging-projects/). -You can then upload your package using the following command: +You can then upload your package by using the following command: ```shell python -m twine upload --repository <source_name> dist/<package_file> ``` -Where: - - `<package_file>` is your package filename, ending in `.tar.gz` or `.whl`. -- `<source_name>` is the [source name used during setup](#adding-the-gitlab-pypi-repository-as-a-source). +- `<source_name>` is the [source name used during setup](#authenticate-with-the-package-registry). -## Install packages +## Install a PyPI package -Install the latest version of a package using the following command: +To install the latest version of a package, use the following command: ```shell -pip install --extra-index-url https://__token__:<personal_access_token>@gitlab.com/api/v4/projects/<project_id>/packages/pypi/simple --no-deps <package_name> +pip install --extra-index-url https://__token__:<personal_access_token>@gitlab.example.com/api/v4/projects/<project_id>/packages/pypi/simple --no-deps <package_name> ``` -Where: - - `<package_name>` is the package name. - `<personal_access_token>` is a personal access token with the `read_api` scope. - `<project_id>` is the project ID. -If you were following the guide above and want to test installing the -`MyPyPiPackage` package, you can run the following: +If you were following the guide and want to install the +`MyPyPiPackage` package, you can run: ```shell -pip install mypypipackage --no-deps --extra-index-url https://__token__:<personal_access_token>@gitlab.com/api/v4/projects/<your_project_id>/packages/pypi/simple +pip install mypypipackage --no-deps --extra-index-url https://__token__:<personal_access_token>@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple ``` -This should result in the following: +This message indicates that the package was installed successfully: ```plaintext -Looking in indexes: https://__token__:****@gitlab.com/api/v4/projects/<your_project_id>/packages/pypi/simple +Looking in indexes: https://__token__:****@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple Collecting mypypipackage - Downloading https://gitlab.com/api/v4/projects/<your_project_id>/packages/pypi/files/d53334205552a355fee8ca35a164512ef7334f33d309e60240d57073ee4386e6/mypypipackage-0.0.1-py3-none-any.whl (1.6 kB) + Downloading https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/files/d53334205552a355fee8ca35a164512ef7334f33d309e60240d57073ee4386e6/mypypipackage-0.0.1-py3-none-any.whl (1.6 kB) Installing collected packages: mypypipackage Successfully installed mypypipackage-0.0.1 ``` -GitLab looks for packages using -[Python normalized names (PEP-503)](https://www.python.org/dev/peps/pep-0503/#normalized-names), -so the characters `-`, `_`, and `.` are all treated the same and repeated characters are removed. -A `pip install` request for `my.package` looks for packages that match any of -the three characters, such as `my-package`, `my_package`, and `my....package`. - -## Using GitLab CI with PyPI packages +### Package names -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202012) in GitLab 13.4. - -To work with PyPI commands within [GitLab CI/CD](./../../../ci/README.md), you can use -`CI_JOB_TOKEN` in place of the personal access token or deploy token in your commands. +GitLab looks for packages that use +[Python normalized names (PEP-503)](https://www.python.org/dev/peps/pep-0503/#normalized-names). +The characters `-`, `_`, and `.` are all treated the same, and repeated +characters are removed. -For example: - -```yaml -image: python:latest - -run: - script: - - pip install twine - - python setup.py sdist bdist_wheel - - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/pypi dist/* -``` - -You can also use `CI_JOB_TOKEN` in a `~/.pypirc` file that you check into GitLab: - -```ini -[distutils] -index-servers = - gitlab - -[gitlab] -repository = https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/pypi -username = gitlab-ci-token -password = ${env.CI_JOB_TOKEN} -``` +A `pip install` request for `my.package` looks for packages that match any of +the three characters, such as `my-package`, `my_package`, and `my....package`. diff --git a/doc/user/packages/workflows/monorepo.md b/doc/user/packages/workflows/monorepo.md index f20f3427ac5..1e375dffe7e 100644 --- a/doc/user/packages/workflows/monorepo.md +++ b/doc/user/packages/workflows/monorepo.md @@ -68,7 +68,7 @@ package is to be uploaded to. If you set this to any project that you have access to and update any other configuration similarly depending on the package type, your packages are published to that project. This means you can publish multiple packages to one project, even if their code does not exist in the same -place. See the [project registry workflow documentation](./project_registry.md) +place. See the [project registry workflow documentation](project_registry.md) for more details. ## CI workflows for automating packaging diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 24437e6dfac..a8972f05acd 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -67,16 +67,16 @@ If you are using NPM, this involves creating an `.npmrc` file and adding the app to your project using your project ID, then adding a section to your `package.json` file with a similar URL. Follow -the instructions in the [GitLab NPM Registry documentation](../npm_registry/index.md#authenticating-to-the-gitlab-npm-registry). After +the instructions in the [GitLab NPM Registry documentation](../npm_registry/index.md#authenticate-to-the-package-registry). After you do this, you can push your NPM package to your project using `npm publish`, as described in the -[uploading packages](../npm_registry/index.md#uploading-packages) section of the docs. +[publishing packages](../npm_registry/index.md#publish-an-npm-package) section of the docs. #### Maven If you are using Maven, this involves updating your `pom.xml` file with distribution sections, including the appropriate URL for your project, as described in the [GitLab Maven Repository documentation](../maven_repository/index.md#project-level-maven-endpoint). -Then, you need to add a `settings.xml` file and [include your access token](../maven_repository/index.md#authenticate-with-a-personal-access-token). -Now you can [deploy Maven packages](../maven_repository/index.md#uploading-packages) to your project. +Then, you need to add a `settings.xml` file and [include your access token](../maven_repository/index.md#authenticate-with-a-personal-access-token-in-maven). +Now you can [deploy Maven packages](../maven_repository/index.md#publish-a-package) to your project. #### Conan diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 2e9f36360c6..f1365ee1cab 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -163,7 +163,7 @@ The following table depicts the various user permission levels in a project. | Delete wiki pages | | | | ✓ | ✓ | | View project Audit Events | | | | ✓ | ✓ | | Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | -| Manage [project access tokens](./project/settings/project_access_tokens.md) **(CORE ONLY)** | | | | ✓ | ✓ | +| Manage [project access tokens](project/settings/project_access_tokens.md) **(CORE ONLY)** | | | | ✓ | ✓ | | Switch visibility level | | | | | ✓ | | Transfer project to another namespace | | | | | ✓ | | Rename project | | | | | ✓ | @@ -180,11 +180,11 @@ The following table depicts the various user permission levels in a project. 1. Guest users are able to perform this action on public and internal projects, but not private projects. This doesn't apply to [external users](#external-users) where explicit access must be given even if the project is internal. 1. Guest users can only view the confidential issues they created themselves. 1. If **Public pipelines** is enabled in **Project Settings > CI/CD**. -1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [Protected Branches](./project/protected_branches.md). -1. If the [branch is protected](./project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings), this depends on the access Developers and Maintainers are given. +1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [Protected Branches](project/protected_branches.md). +1. If the [branch is protected](project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings), this depends on the access Developers and Maintainers are given. 1. Guest users can access GitLab [**Releases**](project/releases/index.md) for downloading assets but are not allowed to download the source code nor see repository information like tags and commits. 1. Actions are limited only to records owned (referenced) by user. -1. When [Share Group Lock](./group/index.md#share-with-group-lock) is enabled the project can't be shared with other groups. It does not affect group with group sharing. +1. When [Share Group Lock](group/index.md#share-with-group-lock) is enabled the project can't be shared with other groups. It does not affect group with group sharing. 1. For information on eligible approvers for merge requests, see [Eligible approvers](project/merge_requests/merge_request_approvals.md#eligible-approvers). 1. Owner permission is only available at the group or personal namespace level (and for instance admins) and is inherited by its projects. @@ -256,7 +256,7 @@ group. | Share (invite) groups with groups | | | | | ✓ | | Create/edit/delete group milestones | | | ✓ | ✓ | ✓ | | Create/edit/delete iterations | | | ✓ | ✓ | ✓ | -| Enable/disable a dependency proxy **(PREMIUM)** | | | ✓ | ✓ | ✓ | +| Enable/disable a dependency proxy | | | ✓ | ✓ | ✓ | | Create and edit group wiki pages **(PREMIUM)** | | | ✓ | ✓ | ✓ | | Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | @@ -314,6 +314,10 @@ External users: - Can only access public projects and projects to which they are explicitly granted access, thus hiding all other internal or private ones from them (like being logged out). +- Can only access public groups and groups to which they are explicitly granted access, + thus hiding all other internal or private ones from them (like being + logged out). +- Can only access public snippets. Access can be granted by adding the user as member to the project or group. Like usual users, they receive a role in the project or group with all @@ -391,7 +395,7 @@ with the permissions described on the documentation on [auditor users permission [Read more about Auditor users.](../administration/auditor_users.md) -## Users with minimal access **(PREMIUM ONLY)** +## Users with minimal access **(PREMIUM)** >[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40942) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. @@ -432,7 +436,7 @@ instance and project. In addition, all admins can use the admin interface under |---------------------------------------|-----------------|-------------|----------|--------| | See commits and jobs | ✓ | ✓ | ✓ | ✓ | | Retry or cancel job | | ✓ | ✓ | ✓ | -| Erase job artifacts and trace | | ✓ (*1*) | ✓ | ✓ | +| Erase job artifacts and job logs | | ✓ (*1*) | ✓ | ✓ | | Delete project | | | ✓ | ✓ | | Create project | | | ✓ | ✓ | | Change project configuration | | | ✓ | ✓ | diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index 09bfa7afc9e..cf5e4591a50 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -14,9 +14,9 @@ You can create users: ## Create users on sign in page -If you have [sign-up enabled](../../admin_area/settings/sign_up_restrictions.md), users can create their own accounts using the **Register** tab on the sign in page. +If you have [sign-up enabled](../../admin_area/settings/sign_up_restrictions.md), users can create their own accounts by selecting "Register now" on the sign-in page, or navigate to `https://gitlab.example.com/users/sign_up`. - + ## Create users in Admin Area diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index a70d11438f4..637d740ab0f 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -35,7 +35,7 @@ As an administrator, you can delete a user account by: - **Delete user and contributions** to delete the user and their associated records. -DANGER: **Danger:** +DANGER: **Warning:** Using the **Delete user and contributions** option may result in removing more data than intended. Please see [associated records](#associated-records) below for additional details. diff --git a/doc/user/profile/account/img/register_tab.png b/doc/user/profile/account/img/register_tab.png Binary files differdeleted file mode 100644 index 4bbb4e62687..00000000000 --- a/doc/user/profile/account/img/register_tab.png +++ /dev/null diff --git a/doc/user/profile/account/img/register_v13_6.png b/doc/user/profile/account/img/register_v13_6.png Binary files differnew file mode 100644 index 00000000000..ce4adc0f55b --- /dev/null +++ b/doc/user/profile/account/img/register_v13_6.png diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 0e645e1b4a3..dacb6c3a5a7 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -8,12 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Two-factor authentication Two-factor authentication (2FA) provides an additional level of security to your -GitLab account. Once enabled, in addition to supplying your username and -password to login, you'll be prompted for a code generated by your one time password -authenticator. For example, a password manager on one of your devices. +GitLab account. After being enabled, in addition to supplying your username and +password to sign in, you'll be prompted for a code generated by your one-time +password authenticator (for example, a password manager on one of your devices). -By enabling 2FA, the only way someone other than you can log into your account -is to know your username and password *and* have access to your one time password secret. +By enabling 2FA, the only way someone other than you can sign in to your account +is to know your username and password _and_ have access to your one-time +password secret. ## Overview @@ -21,30 +22,30 @@ TIP: **Tip:** When you enable 2FA, don't forget to back up your [recovery codes](#recovery-codes)! In addition to time-based one time passwords (TOTP), GitLab supports U2F -(universal 2nd factor) devices as the second factor of authentication. Once +(universal 2nd factor) and WebAuthn (experimental) devices as the second factor of authentication. Once enabled, in addition to supplying your username and password to log in, you'll -be prompted to activate your U2F device (usually by pressing a button on it), +be prompted to activate your U2F / WebAuthn device (usually by pressing a button on it), and it will perform secure authentication on your behalf. It is highly recommended that you set up 2FA with both a -[one-time password authenticator](#enable-2fa-via-one-time-password-authenticator) -and a [U2F device](#enable-2fa-via-u2f-device), so you can still access your account -if you lose your U2F device. +[one-time password authenticator](#one-time-password) or use [FortiAuthenticator](#one-time-password-via-fortiauthenticator) +and a [U2F device](#u2f-device) or a [WebAuthn device](#webauthn-device), so you can still access your account +if you lose your U2F / WebAuthn device. ## Enabling 2FA -There are two ways to enable two-factor authentication: via a one time password authenticator -or a U2F device. +There are multiple ways to enable two-factor authentication: via a one time password authenticator +or a U2F / WebAuthn device. -### Enable 2FA via one time password authenticator +### One-time password To enable 2FA: 1. **In GitLab:** - 1. Log in to your GitLab account. + 1. Sign in to your GitLab account. 1. Go to your [**Profile settings**](../index.md#profile-settings). 1. Go to **Account**. - 1. Click **Enable Two-factor Authentication**. + 1. Select **Enable Two-factor Authentication**. 1. **On your device (usually your phone):** 1. Install a compatible application, like: - [Authenticator](https://mattrubin.me/authenticator/): open source app for iOS devices. @@ -59,14 +60,88 @@ To enable 2FA: 1. **In GitLab:** 1. Enter the six-digit pin number from the entry on your device into the **Pin code** field. - 1. Click **Submit**. + 1. Select **Submit**. If the pin you entered was correct, you'll see a message indicating that two-factor authentication has been enabled, and you'll be presented with a list -of [recovery codes](#recovery-codes). Make sure you download them and keep them +of [recovery codes](#recovery-codes). Be sure to download them and keep them in a safe place. -### Enable 2FA via U2F device +### One-time password via FortiAuthenticator + +> - Introduced in [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/212312) +> - It's deployed behind a feature flag, disabled by default. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-fortiauthenticator-integration). + +You can use FortiAuthenticator as an OTP provider in GitLab. Users must exist in +both FortiAuthenticator and GitLab with the exact same username, and users must +have FortiToken configured in FortiAuthenticator. + +You'll also need a username and access token for FortiAuthenticator. The +`access_token` in the code samples shown below is the FortAuthenticator access +key. To get the token, see the `REST API Solution Guide` at +[`Fortinet Document Library`](https://docs.fortinet.com/document/fortiauthenticator/6.2.0/rest-api-solution-guide/158294/the-fortiauthenticator-api). +GitLab 13.5 has been tested with FortAuthenticator version 6.2.0. + +First configure FortiAuthenticator in GitLab. On your GitLab server: + +1. Open the configuration file. + + For Omnibus GitLab: + + ```shell + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```shell + cd /home/git/gitlab + sudo -u git -H editor config/gitlab.yml + ``` + +1. Add the provider configuration: + + For Omnibus package: + + ```ruby + gitlab_rails['forti_authenticator_enabled'] = true + gitlab_rails['forti_authenticator_host'] = 'forti_authenticator.example.com' + gitlab_rails['forti_authenticator_port'] = 443 + gitlab_rails['forti_authenticator_username'] = '<some_username>' + gitlab_rails['forti_authenticator_access_token'] = 's3cr3t' + ``` + + For installations from source: + + ```yaml + forti_authenticator: + enabled: true + host: forti_authenticator.example.com + port: 443 + username: <some_username> + access_token: s3cr3t + ``` + +1. Save the configuration file. +1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + or [restart GitLab](../../../administration/restart_gitlab.md#installations-from-source) + for the changes to take effect if you installed GitLab via Omnibus or from + source respectively. + +#### Enable FortiAuthenticator integration + +This feature comes with the `:forti_authenticator` feature flag disabled by +default. + +To enable this feature, ask a GitLab administrator with [Rails console access](../../../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) +to run the following command: + +```ruby +Feature.enable(:forti_authenticator, User.find(<user ID>)) +``` + +### U2F device > Introduced in [GitLab 8.9](https://about.gitlab.com/blog/2016/06/22/gitlab-adds-support-for-u2f/). @@ -100,10 +175,46 @@ To set up 2FA with a U2F device: You will see a message indicating that your device was successfully set up. Click on **Register U2F Device** to complete the process. +### WebAuthn device + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22506) in GitLab 13.4. +> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-webauthn). **(CORE ONLY)** + +The WebAuthn workflow is [supported by](https://caniuse.com/#search=webauthn) the +following desktop browsers: + +- Chrome +- Edge +- Firefox +- Opera +- Safari + +and the following mobile browsers: + +- Chrome for Android +- Firefox for Android +- iOS Safari (since iOS 13.3) + +To set up 2FA with a WebAuthn compatible device: + +1. Sign in to your GitLab account. +1. Go to your [**Profile settings**](../index.md#profile-settings). +1. Go to **Account**. +1. Select **Enable Two-Factor Authentication**. +1. Plug in your WebAuthn device. +1. Select **Set up New WebAuthn Device**. +1. Depending on your device, you might need to press a button or touch a sensor. + +You will see a message indicating that your device was successfully set up. +Recovery codes are not generated for WebAuthn devices. + ## Recovery codes NOTE: **Note:** -Recovery codes are not generated for U2F devices. +Recovery codes are not generated for U2F / WebAuthn devices. CAUTION: **Caution:** Each code can be used only once to log in to your account. @@ -141,6 +252,14 @@ To log in via a U2F device: You will see a message indicating that your device responded to the authentication request and you will be automatically logged in. +### Log in via WebAuthn device + +In supported browsers you should be automatically prompted to activate your WebAuthn device +(e.g. by touching/pressing its button) after entering your credentials. + +You will see a message indicating that your device responded to the authentication +request and you will be automatically logged in. + ## Disabling 2FA If you ever need to disable 2FA: @@ -151,7 +270,7 @@ If you ever need to disable 2FA: 1. Click **Disable**, under **Two-Factor Authentication**. This will clear all your two-factor authentication registrations, including mobile -applications and U2F devices. +applications and U2F / WebAuthn devices. ## Personal access tokens @@ -257,7 +376,8 @@ Sign in and re-enable two-factor authentication as soon as possible. you may have cases where authorization always fails because of time differences. - The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from multiple hostnames, or FQDNs. Each U2F registration is linked to the _current hostname_ at - the time of registration, and cannot be used for other hostnames/FQDNs. + the time of registration, and cannot be used for other hostnames/FQDNs. The same applies to + WebAuthn registrations. For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`: @@ -268,6 +388,25 @@ Sign in and re-enable two-factor authentication as soon as possible. - To enforce 2FA at the system or group levels see [Enforce Two-factor Authentication](../../../security/two_factor_authentication.md). +## Enable or disable WebAuthn **(CORE ONLY)** + +Support for WebAuthn is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:webauthn) +``` + +To disable it: + +```ruby +Feature.disable(:webauthn) +``` + ## Troubleshooting If you are receiving an `invalid pin code` error, this may indicate that there is a time sync issue between the authentication application and the GitLab instance itself. diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index a5b15a7880c..4630215eca6 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto --- diff --git a/doc/user/profile/img/busy_status_indicator_v13_6.png b/doc/user/profile/img/busy_status_indicator_v13_6.png Binary files differnew file mode 100644 index 00000000000..291e0fab971 --- /dev/null +++ b/doc/user/profile/img/busy_status_indicator_v13_6.png diff --git a/doc/user/profile/img/unknown_sign_in_email_v13_0.png b/doc/user/profile/img/unknown_sign_in_email_v13_0.png Binary files differdeleted file mode 100644 index 51a7c29cdfa..00000000000 --- a/doc/user/profile/img/unknown_sign_in_email_v13_0.png +++ /dev/null diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 0400d9ca2e5..8ae92a42581 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -86,7 +86,7 @@ From there, you can: If you don't know your current password, select the 'I forgot my password' link. - + ## Changing your username @@ -188,17 +188,22 @@ To set your current status: 1. Set the desired emoji and/or status message. 1. Click **Set status**. Alternatively, you can click **Remove status** to remove your user status entirely. + + or 1. Click your avatar. 1. Select **Profile**. 1. Click **Edit profile** (pencil icon). 1. Enter your status message in the **Your status** text field. + 1. Alternatively, select the **Busy** checkbox ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259649) in GitLab 13.6}. 1. Click **Add status emoji** (smiley face), and select the desired emoji. 1. Click **Update profile settings**. You can also set your current status [using the API](../../api/users.md#user-status). +If you previously selected the "Busy" checkbox, remember to deselect it when you become available again. + ## Commit email > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21598) in GitLab 11.4. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 73a83b08a23..f3d27147557 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -7,13 +7,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Notification Emails -GitLab Notifications allow you to stay informed about what's happening in GitLab. With notifications enabled, you can receive updates about activity in issues, merge requests, and epics. Notifications are sent via email. +GitLab Notifications allow you to stay informed about what's happening in GitLab. With notifications +enabled, you can receive updates about activity in issues, merge requests, epics, and designs. +Notifications are sent via email. ## Receiving notifications You will receive notifications for one of the following reasons: -- You participate in an issue, merge request, or epic. In this context, _participate_ means comment, or edit. +- You participate in an issue, merge request, epic or design. In this context, _participate_ means comment, or edit. - You enable notifications in an issue, merge request, or epic. To enable notifications, click the **Notifications** toggle in the sidebar to _on_. While notifications are enabled, you will receive notification of actions occurring in that issue, merge request, or epic. @@ -209,6 +211,18 @@ If an open merge request becomes unmergeable due to conflict, its author will be If a user has also set the merge request to automatically merge once pipeline succeeds, then that user will also be notified. +## Design email notifications + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217095) in GitLab 13.6. + +Email notifications are sent to the participants when comments are made on a design. + +The participants are: + +- Authors of the design (can be multiple people if different authors have uploaded different versions of the design). +- Authors of comments on the design. +- Anyone that is `@mentioned` in a comment on the design. + ## Filtering email Notification email messages include GitLab-specific headers. You can filter the notification emails based on the content of these headers to better manage your notifications. For example, you could filter all emails for a specific project where you are being assigned either a merge request or issue. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 61944bb9d0b..168bcb5a42e 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: concepts, howto --- diff --git a/doc/user/profile/unknown_sign_in_notification.md b/doc/user/profile/unknown_sign_in_notification.md index 6a6820bb2d4..a97af3d6965 100644 --- a/doc/user/profile/unknown_sign_in_notification.md +++ b/doc/user/profile/unknown_sign_in_notification.md @@ -30,4 +30,4 @@ for a notification email to be sent. ## Example email - + diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index afce3869cbf..e9bb6d0e3ff 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Canary Deployments **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. @@ -61,3 +67,74 @@ Canary deployments are marked with a yellow dot in the Deploy Board so that you can easily notice them.  + +### Advanced traffic control with Canary Ingress **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. + +Canary deployments can be more strategic with [Canary Ingress](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#canary), +which is an advanced traffic routing service that controls incoming HTTP +requests between stable and canary deployments based on factors such as weight, sessions, cookies, +and others. GitLab uses this service in its [Auto Deploy architecture](../../topics/autodevops/upgrading_auto_deploy_dependencies.md#v2-chart-resource-architecture) +to let users easily and safely roll out their new deployments. + +#### How to set up a Canary Ingress in a canary deployment + +A Canary Ingress is installed by default if your Auto DevOps pipeline uses +[`v2.0.0+` of `auto-deploy-image`](../../topics/autodevops/upgrading_auto_deploy_dependencies.md#verify-dependency-versions). +A Canary Ingress becomes available when you create a new canary deployment and is destroyed when the +canary deployment is promoted to production. + +Here's an example setup flow from scratch: + +1. Prepare an [Auto DevOps-enabled](../../topics/autodevops/index.md) project. +1. Set up a [Kubernetes Cluster](../../user/project/clusters/index.md) in your project. +1. Install [Ingress](../../user/clusters/applications.md#ingress) as a GitLab Managed App. +1. Set up [the base domain](../../user/project/clusters/index.md#base-domain) based on the Ingress + Endpoint assigned above. +1. Check if [`v2.0.0+` of `auto-deploy-image` is used in your Auto DevOps pipelines](../../topics/autodevops/upgrading_auto_deploy_dependencies.md#verify-dependency-versions). + If it isn't, follow the documentation to specify the image version. +1. [Run a new Auto DevOps pipeline](../../ci/pipelines/index.md#run-a-pipeline-manually) + and make sure that the `production` job succeeds and creates a production environment. +1. Configure a [`canary` deployment job for Auto DevOps pipelines](../../topics/autodevops/customize.md#deploy-policy-for-canary-environments). +1. [Run a new Auto DevOps pipeline](../../ci/pipelines/index.md#run-a-pipeline-manually) + and make sure that the `canary` job succeeds and creates a canary deployment with Canary Ingress. + +#### How to check the current traffic weight on a Canary Ingress + +1. Visit [Deploy Board](../../user/project/deploy_boards.md). +1. Open your browser's inspection tool and examine a response from the `environments.json` endpoint. + You can find the current weight under `rollout_status`. + +  + + Note that we have [a plan](https://gitlab.com/gitlab-org/gitlab/-/issues/218139) + to visualize this information in a [Deploy Board](../../user/project/deploy_boards.md) + without needing a browser's inspection tool. + +#### How to change the traffic weight on a Canary Ingress + +You can change the traffic weight by using [GraphiQL](../../api/graphql/getting_started.md#graphiql) +or by sending requests to the [GraphQL API](../../api/graphql/getting_started.md#command-line). + +Here's an example using [GraphiQL](../../api/graphql/getting_started.md#graphiql): + +1. Visit [GraphiQL Explorer](https://gitlab.com/-/graphql-explorer). +1. Execute the `environmentsCanaryIngressUpdate` GraphQL mutation: + + ```shell + mutation { + environmentsCanaryIngressUpdate(input:{ + id: "gid://gitlab/Environment/29", # Your Environment ID. You can get the ID from the URL of the environment page. + weight: 45 # The new traffic weight. e.g. If you set `45`, 45% of traffic goes to a canary deployment and 55% of traffic goes to a stable deployment. + }) { + errors + } + } + ``` + +1. If the request succeeds, the `errors` response contains an empty array. GitLab sends a `PATCH` + request to your Kubernetes cluster for updating the weight parameter on a Canary Ingress. + +Note that there's [a plan](https://gitlab.com/gitlab-org/gitlab/-/issues/218139) +to control the weight from a [Deploy Board](../../user/project/deploy_boards.md). diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 65416d73f06..c3f2b96ce9f 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -139,6 +139,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 1. Enter a role name and optional description into the fields provided. 1. Click **Create role**, the new role name will appear at the top. Click on its name and copy the `Role ARN` from the newly created role. 1. In GitLab, enter the copied role ARN into the `Role ARN` field. +1. In the **Cluster Region** field, enter the [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) you plan to use for your new cluster. GitLab will authenticate you have access to this region when authenticating your role. 1. Click **Authenticate with AWS**. 1. Choose your cluster's settings: - **Kubernetes cluster name** - The name you wish to give the cluster. @@ -152,9 +153,6 @@ To create and add a new Kubernetes cluster to your project, group, or instance: the one you created much earlier by following the [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) guide. - - - **Region** - The [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) - in which the cluster will be created. - **Key pair name** - Select the [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) that you can use to connect to your worker nodes if required. - **VPC** - Select a [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) @@ -184,9 +182,10 @@ The following errors are commonly encountered when creating a new cluster. #### Error: Request failed with status code 422 When submitting the initial authentication form, GitLab returns a status code 422 -error when it can't determine the role you've provided. Make sure you've +error when it can't determine the role or region you've provided. Make sure you've correctly configured your role with the **Account ID** and **External ID** provided by GitLab. In GitLab, make sure to enter the correct **Role ARN**. +Make sure you also have access to the chosen region. #### Could not load Security Groups for this VPC diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 094f4bcf6ba..c96e38b1dfc 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -94,7 +94,11 @@ GitLab creates the following resources for RBAC clusters. | Environment namespace | `Namespace` | Contains all environment-specific resources | Deploying to a cluster | | Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | | Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | -| Environment namespace | `RoleBinding` | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Deploying to a cluster | +| Environment namespace | `RoleBinding` | [`admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Deploying to a cluster | + +The environment namespace `RoleBinding` was +[updated](https://gitlab.com/gitlab-org/gitlab/-/issues/31113) in GitLab 13.6 +to `admin` roleRef. Previously, the `edit` roleRef was used. ### ABAC cluster resources @@ -149,6 +153,9 @@ Amazon Elastic Kubernetes Service (EKS) at the project, group, or instance level - [Amazon EKS](add_eks_clusters.md#new-eks-cluster). - [Google GKE](add_gke_clusters.md#creating-the-cluster-on-gke). +After creating a cluster, you can install runners for it as described in +[GitLab Managed Apps](../../clusters/applications.md). + ## Add existing cluster If you have an existing Kubernetes cluster, you can add it to a project, group, @@ -158,6 +165,9 @@ Kubernetes integration isn't supported for arm64 clusters. See the issue [Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab/-/issues/29838) for details. +After adding an existing cluster, you can install runners for it as described in +[GitLab Managed Apps](../../clusters/applications.md). + ### Existing Kubernetes cluster To add a Kubernetes cluster to your project, group, or instance: diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 459ba144186..9273fb7b361 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -22,6 +22,8 @@ Using the GitLab project Kubernetes integration, you can: - Use [Web terminals](#web-terminals). - Use [Deploy Boards](#deploy-boards). **(PREMIUM)** - Use [Canary Deployments](#canary-deployments). **(PREMIUM)** +- Use [deployment variables](#deployment-variables). +- Use [role-based or attribute-based access controls](add_remove_clusters.md#access-controls). - View [Logs](#viewing-pod-logs). - Run serverless workloads on [Kubernetes with Knative](serverless/index.md). @@ -40,14 +42,15 @@ of memory and CPU usage. GitLab is committed to support at least two production-ready Kubernetes minor versions at any given time. We regularly review the versions we support, and -provide a four-month deprecation period before we remove support of a specific +provide a three-month deprecation period before we remove support of a specific version. The range of supported versions is based on the evaluation of: - Our own needs. - The versions supported by major managed Kubernetes providers. - The versions [supported by the Kubernetes community](https://kubernetes.io/docs/setup/release/version-skew-policy/#supported-versions). -Currently, GitLab supports the following Kubernetes versions: +GitLab supports the following Kubernetes versions, and you can upgrade your +Kubernetes version to any supported version at any time: - 1.17 - 1.16 @@ -241,9 +244,18 @@ A Kubernetes cluster can be the destination for a deployment job. If ### Deployment variables +Deployment variables require a valid [Deploy Token](../deploy_tokens/index.md) named +[`gitlab-deploy-token`](../deploy_tokens/index.md#gitlab-deploy-token), and the +following command in your deployment job script, for Kubernetes to access the registry: + +```plaintext +kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run | kubectl apply -f - +``` + The Kubernetes cluster integration exposes the following [deployment variables](../../../ci/variables/README.md#deployment-environment-variables) in the -GitLab CI/CD build environment. +GitLab CI/CD build environment to deployment jobs, which are jobs that have +[defined a target environment](../../../ci/environments/index.md#defining-environments). | Variable | Description | | -------- | ----------- | diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md index bed01ff4d58..2d74f67ba35 100644 --- a/doc/user/project/clusters/securing.md +++ b/doc/user/project/clusters/securing.md @@ -1,5 +1,5 @@ --- -stage: Defend +stage: Protect group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -42,7 +42,7 @@ Minimum requirements (depending on the GitLab Manage Application you want to ins NOTE: **Note:** These diagrams use the term _Kubernetes_ for simplicity. In practice, Sidekiq connects to a Helm -Tiller daemon running in a pod in the cluster. +command runner pod in the cluster. You install GitLab Managed Apps from the GitLab web interface with a one-click setup process. GitLab uses Sidekiq (a background processing service) to facilitate this. diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index db91f78fc20..0de0fd38336 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -335,7 +335,7 @@ Some steps in this documentation use SAM CLI. Follow the instructions for [installing SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) to install and configure SAM CLI. -If you use [AWS Cloud9](https://aws.amazon.com/cloud9/) as your integrated development +If you use [AWS Cloud9](https://aws.amazon.com/cloud9/) as your integrated development environment (IDE), the following are installed for you: - [AWS Command Line Interface](https://docs.aws.amazon.com/en_pv/cli/latest/userguide/cli-chap-install.html) @@ -357,7 +357,7 @@ To create a new AWS SAM application: 1. `git push` the application back to the GitLab project. This creates a SAM app named `gitlabpoc` using the default configuration, a single -Python 3.8 function invoked by an [Amazon API Gateway](https://aws.amazon.com/api-gateway/) +Python 3.8 function invoked by an [Amazon API Gateway](https://aws.amazon.com/api-gateway/) endpoint. To see additional runtimes supported by SAM and options for `sam init`, run: ```shell @@ -367,13 +367,13 @@ sam init -h ### Setting up your AWS credentials with your GitLab account In order to interact with your AWS account, the GitLab CI/CD pipelines require both -`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be set in the project's CI/CD +`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be set in the project's CI/CD variables. To set these: -1. Navigate to the project's **Settings > CI / CD**. -1. Expand the **Variables** section and create entries for `AWS_ACCESS_KEY_ID` and +1. Navigate to the project's **Settings > CI / CD**. +1. Expand the **Variables** section and create entries for `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. 1. Mask the credentials so they do not show in logs using the **Masked** toggle. @@ -460,7 +460,7 @@ CLI installed locally for you to test locally. First, test the function. -SAM provides a default event in `events/event.json` that includes a message body of: +SAM provides a default event in `events/event.json` that includes a message body of: ```plaintext {\"message\": \"hello world\"} @@ -491,7 +491,7 @@ sam local start-api ``` SAM again launches a Docker container, this time with a mocked Amazon API Gateway -listening on `localhost:3000`. +listening on `localhost:3000`. Call the `hello` API by running: diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index d0c5a24826a..5f96f65ea06 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -35,7 +35,9 @@ code_navigation: lsif: dump.lsif ``` -The generated LSIF file must be less than 170MiB. +The generated LSIF file size may be limited by +the [artifact application limits (`ci_max_artifact_size_lsif`)](../../administration/instance_limits.md#maximum-file-size-per-type-of-artifact), +default to 100MB (configurable by an instance administrator). After the job succeeds, code intelligence data can be viewed while browsing the code: diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 4ae3d5ec032..37ebef3a26e 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -27,7 +27,7 @@ who is responsible for each file or path. Code Owners allows for a version controlled, single source of truth file outlining the exact GitLab users or groups that own certain files or paths in a repository. Code Owners can be -utilized in the merge request approval process which can streamline +used in the merge request approval process which can streamline the process of finding the right reviewers and approvers for a given merge request. @@ -48,10 +48,14 @@ You can choose to add the `CODEOWNERS` file in three places: - Inside the `.gitlab/` directory - Inside the `docs/` directory -The `CODEOWNERS` file is scoped to a branch, which means that as -new files are introduced, the user adding the new content can -specify themselves as a code owner, all before the new changes -get merged to the target branch. +The `CODEOWNERS` file is valid for the branch where it lives. For example, if you change the code owners +in a feature branch, they won't be valid in the main branch until the feature branch is merged. + +If you introduce new files to your repository and you want to identify the code owners for that file, +you have to update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same +branch), GitLab will count the owners as soon as the branch is merged. If +you don't, you can do that later, but your new files will not belong to anyone until you update your +`CODEOWNERS` file in the TARGET branch. When a file matches multiple entries in the `CODEOWNERS` file, the users from last pattern matching the file are displayed on the diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 3c6494d5f1a..2bf35b48547 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -41,9 +41,9 @@ knowledge. In particular, you should be familiar with: - [Kubernetes namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) - [Kubernetes canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) -NOTE: **Note:** -Apps that consist of multiple deployments are shown as duplicates on the deploy board. -Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/8463) for details. +In GitLab 13.5 and earlier, apps that consist of multiple deployments are shown as +duplicates on the deploy board. This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/8463) +in GitLab 13.6. ## Use cases diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 5ca421dda5b..1ac528ca4ae 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -13,57 +13,61 @@ type: howto > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI / CD** in GitLab 12.10.1. > - [Added package registry scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. -Deploy tokens allow you to download (`git clone`) or push and pull packages and container registry images of a project without having a user and a password. +Deploy tokens allow you to download (`git clone`) or push and pull packages and +container registry images of a project without having a user and a password. Deploy tokens can be managed by [maintainers only](../../permissions.md). -If you have a key pair, you might want to use [deploy keys](../../../ssh/README.md#deploy-keys) instead. +If you have a key pair, you might want to use [deploy keys](../../../ssh/README.md#deploy-keys) +instead. ## Creating a Deploy Token -You can create as many deploy tokens as you like from the settings of your project. Alternatively, you can also create [group-scoped deploy tokens](#group-deploy-token). +You can create as many deploy tokens as you need from the settings of your +project. Alternatively, you can also create [group-scoped deploy tokens](#group-deploy-token). -1. Log in to your GitLab account. +1. Sign in to your GitLab account. 1. Go to the project (or group) you want to create Deploy Tokens for. 1. Go to **Settings > Repository**. 1. Click on "Expand" on **Deploy Tokens** section. 1. Choose a name, expiry date (optional), and username (optional) for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). -1. Click on **Create deploy token**. -1. Save the deploy token somewhere safe. Once you leave or refresh +1. Select **Create deploy token**. +1. Save the deploy token somewhere safe. After you leave or refresh the page, **you won't be able to access it again**.  ## Deploy token expiration -Deploy tokens expire on the date you define, at midnight UTC. +Deploy tokens expire at midnight UTC on the date you define. ## Revoking a deploy token -At any time, you can revoke any deploy token by just clicking the -respective **Revoke** button under the 'Active deploy tokens' area. +At any time, you can revoke any deploy token by just clicking the respective +**Revoke** button under the 'Active deploy tokens' area. ## Limiting scopes of a deploy token -Deploy tokens can be created with different scopes that allow various -actions that a given token can perform. The available scopes are depicted in -the following table along with GitLab version it was introduced in. +Deploy tokens can be created with different scopes that allow various actions +that a given token can perform. The available scopes are depicted in the +following table along with GitLab version it was introduced in: -| Scope | Description | Introduced in GitLab Version | -| ----- | ----------- | ------ | -| `read_repository` | Allows read-access to the repository through `git clone` | 10.7 | -| `read_registry` | Allows read-access to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | 10.7 | -| `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | 12.10 | -| `read_package_registry` | Allows read access to the package registry. | 13.0 | +| Scope | Description | Introduced in GitLab Version | +|--------------------------|-------------|------------------------------| +| `read_repository` | Allows read-access to the repository through `git clone` | 10.7 | +| `read_registry` | Allows read-access to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | 10.7 | +| `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | 12.10 | +| `read_package_registry` | Allows read access to the package registry. | 13.0 | | `write_package_registry` | Allows write access to the package registry. | 13.0 | ## Deploy token custom username > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29639) in GitLab 12.1. -The default username format is `gitlab+deploy-token-#{n}`. Some tools or platforms may not support this format, -in such case you can specify custom username to be used when creating the deploy token. +The default username format is `gitlab+deploy-token-#{n}`. Some tools or +platforms may not support this format; in this case you can specify a custom +username to be used when creating the deploy token. ## Usage @@ -87,13 +91,13 @@ To read the container registry images, you'll need to: 1. Create a Deploy Token with `read_registry` as a scope. 1. Take note of your `username` and `token`. -1. Log in to GitLab’s Container Registry using the deploy token: +1. Sign in to GitLab’s Container Registry using the deploy token: ```shell docker login -u <username> -p <deploy_token> registry.example.com ``` -Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply +Replace `<username>` and `<deploy_token>` with the proper values. You can now pull images from your Container Registry. ### Push Container Registry images @@ -104,13 +108,13 @@ To push the container registry images, you'll need to: 1. Create a Deploy Token with `write_registry` as a scope. 1. Take note of your `username` and `token`. -1. Log in to GitLab’s Container Registry using the deploy token: +1. Sign in to GitLab’s Container Registry using the deploy token: ```shell docker login -u <username> -p <deploy_token> registry.example.com ``` -Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply +Replace `<username>` and `<deploy_token>` with the proper values. You can now push images to your Container Registry. ### Read or pull packages @@ -121,7 +125,8 @@ To pull packages in the GitLab package registry, you'll need to: 1. Create a Deploy Token with `read_package_registry` as a scope. 1. Take note of your `username` and `token`. -1. For the [package type of your choice](./../../packages/index.md), follow the authentication instructions for deploy tokens. +1. For the [package type of your choice](../../packages/index.md), follow the + authentication instructions for deploy tokens. ### Push or upload packages @@ -131,7 +136,8 @@ To upload packages in the GitLab package registry, you'll need to: 1. Create a Deploy Token with `write_package_registry` as a scope. 1. Take note of your `username` and `token`. -1. For the [package type of your choice](./../../packages/index.md), follow the authentication instructions for deploy tokens. +1. For the [package type of your choice](../../packages/index.md), follow the + authentication instructions for deploy tokens. ### Group Deploy Token @@ -158,10 +164,10 @@ apply consistently when cloning the repository of related projects. There's a special case when it comes to Deploy Tokens. If a user creates one named `gitlab-deploy-token`, the username and token of the Deploy Token will be -automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` and -`CI_DEPLOY_PASSWORD`, respectively. +automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` +and `CI_DEPLOY_PASSWORD`, respectively. -After you create the token, you can login to the Container Registry using +After you create the token, you can sign in to the Container Registry by using those variables: ```shell @@ -169,4 +175,7 @@ docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY ``` NOTE: **Note:** -The special handling for the `gitlab-deploy-token` deploy token is not currently implemented for group deploy tokens. For the deploy token to be available for CI/CD jobs, it must be created at the project level. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214014) for details. +The special handling for the `gitlab-deploy-token` deploy token is not currently +implemented for group deploy tokens. For the deploy token to be available for +CI/CD jobs, it must be created at the project level. For details, see +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214014). diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index e0c4097d1c5..4c14251cfa5 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -62,7 +62,7 @@ To create the `.gitlab/issue_templates` directory: 1. Click the `+` button next to `master` again and select **New directory**.This time, n 1. Name your directory `issue_templates` and commit to your default branch. -To check if this has worked correctly, [create a new issue](./issues/managing_issues.md#create-a-new-issue) +To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-a-new-issue) and see if you can choose a description template. ## Creating merge request templates diff --git a/doc/user/project/img/epics_swimlanes_drag_and_drop.png b/doc/user/project/img/epics_swimlanes_drag_and_drop.png Binary files differnew file mode 100644 index 00000000000..b2cc4105898 --- /dev/null +++ b/doc/user/project/img/epics_swimlanes_drag_and_drop.png diff --git a/doc/user/project/img/epics_swimlanes_v13.6.png b/doc/user/project/img/epics_swimlanes_v13.6.png Binary files differnew file mode 100644 index 00000000000..6f787ba8b10 --- /dev/null +++ b/doc/user/project/img/epics_swimlanes_v13.6.png diff --git a/doc/user/project/img/group_issue_board.png b/doc/user/project/img/group_issue_board.png Binary files differdeleted file mode 100644 index be360d18540..00000000000 --- a/doc/user/project/img/group_issue_board.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_add_list.png b/doc/user/project/img/issue_board_add_list.png Binary files differdeleted file mode 100644 index 91098daa1d1..00000000000 --- a/doc/user/project/img/issue_board_add_list.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_add_list_v13_6.png b/doc/user/project/img/issue_board_add_list_v13_6.png Binary files differnew file mode 100644 index 00000000000..4239ab6e7e4 --- /dev/null +++ b/doc/user/project/img/issue_board_add_list_v13_6.png diff --git a/doc/user/project/img/issue_board_assignee_lists.png b/doc/user/project/img/issue_board_assignee_lists.png Binary files differdeleted file mode 100644 index f2660cd8f80..00000000000 --- a/doc/user/project/img/issue_board_assignee_lists.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_assignee_lists_v13_6.png b/doc/user/project/img/issue_board_assignee_lists_v13_6.png Binary files differnew file mode 100644 index 00000000000..d0fbb0a2ef0 --- /dev/null +++ b/doc/user/project/img/issue_board_assignee_lists_v13_6.png diff --git a/doc/user/project/img/issue_board_creation.png b/doc/user/project/img/issue_board_creation.png Binary files differdeleted file mode 100644 index 099fe6eee21..00000000000 --- a/doc/user/project/img/issue_board_creation.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_creation_v13_6.png b/doc/user/project/img/issue_board_creation_v13_6.png Binary files differnew file mode 100644 index 00000000000..e36b53418fd --- /dev/null +++ b/doc/user/project/img/issue_board_creation_v13_6.png diff --git a/doc/user/project/img/issue_board_edit_button.png b/doc/user/project/img/issue_board_edit_button.png Binary files differdeleted file mode 100644 index a0dc6f41592..00000000000 --- a/doc/user/project/img/issue_board_edit_button.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_focus_mode.gif b/doc/user/project/img/issue_board_focus_mode.gif Binary files differdeleted file mode 100644 index 9565bdb0865..00000000000 --- a/doc/user/project/img/issue_board_focus_mode.gif +++ /dev/null diff --git a/doc/user/project/img/issue_board_milestone_lists.png b/doc/user/project/img/issue_board_milestone_lists.png Binary files differdeleted file mode 100644 index 91926f58f87..00000000000 --- a/doc/user/project/img/issue_board_milestone_lists.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_milestone_lists_v13_6.png b/doc/user/project/img/issue_board_milestone_lists_v13_6.png Binary files differnew file mode 100644 index 00000000000..a7718ffd66c --- /dev/null +++ b/doc/user/project/img/issue_board_milestone_lists_v13_6.png diff --git a/doc/user/project/img/issue_board_move_issue_card_list.png b/doc/user/project/img/issue_board_move_issue_card_list.png Binary files differdeleted file mode 100644 index 13750a63766..00000000000 --- a/doc/user/project/img/issue_board_move_issue_card_list.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_move_issue_card_list_v13_6.png b/doc/user/project/img/issue_board_move_issue_card_list_v13_6.png Binary files differnew file mode 100644 index 00000000000..2b661a63d7d --- /dev/null +++ b/doc/user/project/img/issue_board_move_issue_card_list_v13_6.png diff --git a/doc/user/project/img/issue_board_summed_weights.png b/doc/user/project/img/issue_board_summed_weights.png Binary files differdeleted file mode 100644 index 6035d7ca330..00000000000 --- a/doc/user/project/img/issue_board_summed_weights.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_summed_weights_v13_6.png b/doc/user/project/img/issue_board_summed_weights_v13_6.png Binary files differnew file mode 100644 index 00000000000..a6482e73c0a --- /dev/null +++ b/doc/user/project/img/issue_board_summed_weights_v13_6.png diff --git a/doc/user/project/img/issue_board_system_notes.png b/doc/user/project/img/issue_board_system_notes.png Binary files differdeleted file mode 100644 index c6ecb498198..00000000000 --- a/doc/user/project/img/issue_board_system_notes.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_system_notes_v13_6.png b/doc/user/project/img/issue_board_system_notes_v13_6.png Binary files differnew file mode 100644 index 00000000000..4958f63541e --- /dev/null +++ b/doc/user/project/img/issue_board_system_notes_v13_6.png diff --git a/doc/user/project/img/issue_board_view_scope.png b/doc/user/project/img/issue_board_view_scope.png Binary files differdeleted file mode 100644 index d173679a0e7..00000000000 --- a/doc/user/project/img/issue_board_view_scope.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_add_issues_modal.png b/doc/user/project/img/issue_boards_add_issues_modal.png Binary files differdeleted file mode 100644 index ecddf6709d0..00000000000 --- a/doc/user/project/img/issue_boards_add_issues_modal.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_add_issues_modal_v13_6.png b/doc/user/project/img/issue_boards_add_issues_modal_v13_6.png Binary files differnew file mode 100644 index 00000000000..a138efc9c1c --- /dev/null +++ b/doc/user/project/img/issue_boards_add_issues_modal_v13_6.png diff --git a/doc/user/project/img/issue_boards_blocked_icon_v12_8.png b/doc/user/project/img/issue_boards_blocked_icon_v12_8.png Binary files differdeleted file mode 100644 index 1055fb48322..00000000000 --- a/doc/user/project/img/issue_boards_blocked_icon_v12_8.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_blocked_icon_v13_6.png b/doc/user/project/img/issue_boards_blocked_icon_v13_6.png Binary files differnew file mode 100644 index 00000000000..2dac6bb2ee3 --- /dev/null +++ b/doc/user/project/img/issue_boards_blocked_icon_v13_6.png diff --git a/doc/user/project/img/issue_boards_core.png b/doc/user/project/img/issue_boards_core.png Binary files differdeleted file mode 100644 index 41ddbb24b14..00000000000 --- a/doc/user/project/img/issue_boards_core.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_core_v13_6.png b/doc/user/project/img/issue_boards_core_v13_6.png Binary files differnew file mode 100644 index 00000000000..8695b523c12 --- /dev/null +++ b/doc/user/project/img/issue_boards_core_v13_6.png diff --git a/doc/user/project/img/issue_boards_multiple.png b/doc/user/project/img/issue_boards_multiple.png Binary files differdeleted file mode 100644 index e6183360610..00000000000 --- a/doc/user/project/img/issue_boards_multiple.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_multiple_v13_6.png b/doc/user/project/img/issue_boards_multiple_v13_6.png Binary files differnew file mode 100644 index 00000000000..18ff5e2bc66 --- /dev/null +++ b/doc/user/project/img/issue_boards_multiple_v13_6.png diff --git a/doc/user/project/img/issue_boards_premium.png b/doc/user/project/img/issue_boards_premium.png Binary files differdeleted file mode 100644 index ef9f5bbea32..00000000000 --- a/doc/user/project/img/issue_boards_premium.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_premium_v13_6.png b/doc/user/project/img/issue_boards_premium_v13_6.png Binary files differnew file mode 100644 index 00000000000..8d1c1299d5c --- /dev/null +++ b/doc/user/project/img/issue_boards_premium_v13_6.png diff --git a/doc/user/project/img/issue_boards_remove_issue.png b/doc/user/project/img/issue_boards_remove_issue.png Binary files differdeleted file mode 100644 index 7050e6c3ede..00000000000 --- a/doc/user/project/img/issue_boards_remove_issue.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_remove_issue_v13_6.png b/doc/user/project/img/issue_boards_remove_issue_v13_6.png Binary files differnew file mode 100644 index 00000000000..c980759ad0c --- /dev/null +++ b/doc/user/project/img/issue_boards_remove_issue_v13_6.png diff --git a/doc/user/project/img/rollout_status_canary_ingress.png b/doc/user/project/img/rollout_status_canary_ingress.png Binary files differnew file mode 100644 index 00000000000..fb59ba31615 --- /dev/null +++ b/doc/user/project/img/rollout_status_canary_ingress.png diff --git a/doc/user/project/import/img/gemnasium/connect_github.png b/doc/user/project/import/img/gemnasium/connect_github.png Binary files differindex 5933f4d5d0a..fae62e8d840 100644 --- a/doc/user/project/import/img/gemnasium/connect_github.png +++ b/doc/user/project/import/img/gemnasium/connect_github.png diff --git a/doc/user/project/import/img/gemnasium/create_project.png b/doc/user/project/import/img/gemnasium/create_project.png Binary files differindex 6e00bf63405..8edbf711629 100644 --- a/doc/user/project/import/img/gemnasium/create_project.png +++ b/doc/user/project/import/img/gemnasium/create_project.png diff --git a/doc/user/project/import/img/gemnasium/project_connected.png b/doc/user/project/import/img/gemnasium/project_connected.png Binary files differindex 8e7216c015b..332d2230ef8 100644 --- a/doc/user/project/import/img/gemnasium/project_connected.png +++ b/doc/user/project/import/img/gemnasium/project_connected.png diff --git a/doc/user/project/import/img/jira/import_issues_from_jira_form_v12_10.png b/doc/user/project/import/img/jira/import_issues_from_jira_form_v12_10.png Binary files differdeleted file mode 100644 index 317a426394c..00000000000 --- a/doc/user/project/import/img/jira/import_issues_from_jira_form_v12_10.png +++ /dev/null diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index a1c28cfa2b7..a113758495a 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -30,6 +30,11 @@ repository is too large the import can timeout. There is also the option of [connecting your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** +## LFS authentication + +When importing a project that contains LFS objects, if the project has an [`.lfsconfig`](https://github.com/git-lfs/git-lfs/blob/master/docs/man/git-lfs-config.5.ronn) +file with a URL host (`lfs.url`) different from the repository URL host, LFS files are not downloaded. + ## Migrating from self-managed GitLab to GitLab.com If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). Issues and merge requests can't be imported. diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index faa2a9b4927..cbc25552873 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: concepts --- diff --git a/doc/user/project/index.md b/doc/user/project/index.md index a00f93bac9c..333c72a65b1 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -192,17 +192,7 @@ To delete a project, first navigate to the home page for that project. 1. Click **Delete project** 1. Confirm this action by typing in the expected text. -### Delayed deletion **(PREMIUM)** - -By default, projects in a personal namespace are deleted after a seven day delay. - -Admins can restore the project during this period of time. -This delay [may be changed by an admin](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). - -Admins can view all projects pending deletion. If you're an administrator, go to the top navigation bar, click **Projects > Your projects**, and then select the **Deleted projects** tab. -From this tab an admin can restore any project. - -For information on delay deletion of projects within a group, please see [Enabling delayed Project removal](../group/index.md#enabling-delayed-project-removal) +Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects within a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal). ## CI/CD for external repositories **(PREMIUM)** @@ -250,6 +240,14 @@ For users without permissions to view the project's code: - The wiki homepage is displayed, if any. - The list of issues within the project is displayed. +## GitLab Workflow - VS Code extension + +To avoid switching from the GitLab UI and VS Code while working in GitLab repositories, you can integrate +the [VS Code](https://code.visualstudio.com/) editor with GitLab through the +[GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). + +To review or contribute to the extension's code, visit [its codebase in GitLab](https://gitlab.com/gitlab-org/gitlab-vscode-extension/). + ## Redirects when changing repository paths When a repository path changes, it is essential to smoothly transition from the diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 4d646ee2f79..eaef0b8d69f 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Insights **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index be89323a246..822483a1d5b 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # IBM Engineering Workflow Management (EWM) Integration **(CORE)** This service allows you to navigate from GitLab to EWM work items mentioned in merge request descriptions and commit messages. Each work item reference is automatically converted to a link back to the work item. diff --git a/doc/user/project/integrations/img/jira_create_new_group_name.png b/doc/user/project/integrations/img/jira_create_new_group_name.png Binary files differdeleted file mode 100644 index bfc0dc6b2e9..00000000000 --- a/doc/user/project/integrations/img/jira_create_new_group_name.png +++ /dev/null diff --git a/doc/user/project/integrations/img/toggle_metrics_user_starred_dashboard_v13_0.png b/doc/user/project/integrations/img/toggle_metrics_user_starred_dashboard_v13_0.png Binary files differdeleted file mode 100644 index 59dc9ccfd30..00000000000 --- a/doc/user/project/integrations/img/toggle_metrics_user_starred_dashboard_v13_0.png +++ /dev/null diff --git a/doc/user/project/integrations/img/webex_teams_configuration.png b/doc/user/project/integrations/img/webex_teams_configuration.png Binary files differdeleted file mode 100644 index 493b3ea50a0..00000000000 --- a/doc/user/project/integrations/img/webex_teams_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index 2c681db1692..90f91fbaa0d 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -1 +1,5 @@ +--- +redirect_to: 'overview.md' +--- + This document was moved to [Integrations](overview.md). diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 28a9afa5bb0..97be16f8dd3 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -95,6 +95,55 @@ spec: targetPort: ${CONTAINER_PORT} ``` +#### Access the UI of a Prometheus managed application in Kubernetes + +You can connect directly to Prometheus, and view the Prometheus user interface, when +using a Prometheus managed application in Kubernetes: + +1. Find the name of the Prometheus pod in the user interface of your Kubernetes + provider, such as GKE, or by running the following `kubectl` command in your + terminal: + + ```shell + kubectl get pods -n gitlab-managed-apps | grep 'prometheus-prometheus-server' + ``` + + The command should return a result like the following example, where + `prometheus-prometheus-server-55b4bd64c9-dpc6b` is the name of the Prometheus pod: + + ```plaintext + gitlab-managed-apps prometheus-prometheus-server-55b4bd64c9-dpc6b 2/2 Running 0 71d + ``` + +1. Run a `kubectl port-forward` command. In the following example, `9090` is the + Prometheus server's listening port: + + ```shell + kubectl port-forward prometheus-prometheus-server-55b4bd64c9-dpc6b 9090:9090 -n gitlab-managed-apps + ``` + + The `port-forward` command forwards all requests sent to your system's `9090` port + to the `9090` port of the Prometheus pod. If the `9090` port on your system is used + by another application, you can change the port number before the colon to your + desired port. For example, to forward port `8080` of your local system, change the + command to: + + ```shell + kubectl port-forward prometheus-prometheus-server-55b4bd64c9-dpc6b 8080:9090 -n gitlab-managed-apps + ``` + +1. Open `localhost:9090` in your browser to display the Prometheus user interface. + +#### Script access to Prometheus + +You can script the access to Prometheus, extracting the name of the pod automatically like this: + +```shell +POD_INFORMATION=$(kubectl get pods -n gitlab-managed-apps | grep 'prometheus-prometheus-server') +POD_NAME=$(echo $POD_INFORMATION | awk '{print $1;}') +kubectl port-forward $POD_NAME 9090:9090 -n gitlab-managed-apps +``` + ### Manual configuration of Prometheus #### Requirements diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 39daa14407f..7654909b735 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -10,9 +10,9 @@ You can configure GitLab to send notifications to a Webex Teams space. ## Create a webhook for the space -1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/teams/applications/incoming-webhooks-cisco-systems). +1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/teams/applications/incoming-webhooks-cisco-systems-38054). 1. Click **Connect** and log in to Webex Teams, if required. -1. Enter a name for the webhook and select the space that will receive the notifications. +1. Enter a name for the webhook and select the space to receive the notifications. 1. Click **ADD**. 1. Copy the **Webhook URL**. @@ -27,4 +27,4 @@ Once you have a webhook URL for your Webex Teams space, you can configure GitLab 1. Paste the **Webhook** URL for the Webex Teams space. 1. Configure the remaining options and then click **Test settings and save changes**. -The Webex Teams space will begin to receive all applicable GitLab events. +The Webex Teams space now begins to receive all applicable GitLab events. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 7adea5ebcd6..6a436c5093e 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1358,6 +1358,140 @@ X-Gitlab-Event: Deployment Hook Note that `deployable_id` is the ID of the CI job. +### Feature Flag events + +Triggered when a feature flag is turned on or off. + +**Request Header**: + +```plaintext +X-Gitlab-Event: Feature Flag Hook +``` + +**Request Body**: + +```json +{ + "object_kind": "feature_flag", + "project": { + "id": 1, + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlabhq/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "git_http_url":"http://example.com/gitlabhq/gitlab-test.git", + "namespace":"GitlabHQ", + "visibility_level":20, + "path_with_namespace":"gitlabhq/gitlab-test", + "default_branch":"master", + "ci_config_path": null, + "homepage":"http://example.com/gitlabhq/gitlab-test", + "url":"http://example.com/gitlabhq/gitlab-test.git", + "ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "http_url":"http://example.com/gitlabhq/gitlab-test.git" + }, + "user": { + "name": "Administrator", + "username": "root", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "email": "admin@example.com" + }, + "user_url": "http://example.com/root", + "object_attributes": { + "id": 6, + "name": "test-feature-flag", + "description": "test-feature-flag-description", + "active": true + } +} +``` + +### Release events + +Triggered when a release is created or updated. + +**Request Header**: + +```plaintext +X-Gitlab-Event: Release Hook +``` + +**Request Body**: + +```json +{ + "id": 1, + "created_at": "2020-11-02 12:55:12 UTC", + "description": "v1.0 has been released", + "name": "v1.1", + "released_at": "2020-11-02 12:55:12 UTC", + "tag": "v1.1", + "object_kind": "release", + "project": { + "id": 2, + "name": "release-webhook-example", + "description": "", + "web_url": "https://example.com/gitlab-org/release-webhook-example", + "avatar_url": null, + "git_ssh_url": "ssh://git@example.com/gitlab-org/release-webhook-example.git", + "git_http_url": "https://example.com/gitlab-org/release-webhook-example.git", + "namespace": "Gitlab", + "visibility_level": 0, + "path_with_namespace": "gitlab-org/release-webhook-example", + "default_branch": "master", + "ci_config_path": null, + "homepage": "https://example.com/gitlab-org/release-webhook-example", + "url": "ssh://git@example.com/gitlab-org/release-webhook-example.git", + "ssh_url": "ssh://git@example.com/gitlab-org/release-webhook-example.git", + "http_url": "https://example.com/gitlab-org/release-webhook-example.git" + }, + "url": "https://example.com/gitlab-org/release-webhook-example/-/releases/v1.1", + "action": "create", + "assets": { + "count": 5, + "links": [ + { + "id": 1, + "external": true, + "link_type": "other", + "name": "Changelog", + "url": "https://example.net/changelog" + } + ], + "sources": [ + { + "format": "zip", + "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.zip" + }, + { + "format": "tar.gz", + "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.tar.gz" + }, + { + "format": "tar.bz2", + "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.tar.bz2" + }, + { + "format": "tar", + "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.tar" + } + ] + }, + "commit": { + "id": "ee0a3fb31ac16e11b9dbb596ad16d4af654d08f8", + "message": "Release v1.1", + "title": "Release v1.1", + "timestamp": "2020-10-31T14:58:32+11:00", + "url": "https://example.com/gitlab-org/release-webhook-example/-/commit/ee0a3fb31ac16e11b9dbb596ad16d4af654d08f8", + "author": { + "name": "Example User", + "email": "user@example.com" + } + } +} +``` + ## Image URL rewriting From GitLab 11.2, simple image references are rewritten to use an absolute URL diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index bce40e9a838..dfe608df18d 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -31,7 +31,7 @@ To let your team members organize their own workflows, use [multiple issue boards](#use-cases-for-multiple-issue-boards). This allows creating multiple issue boards in the same project. - + Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: @@ -45,7 +45,7 @@ as shown in the following table: To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards) below. - + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of @@ -69,8 +69,8 @@ For example, let's consider this simplified development workflow: 1. When frontend is complete, the new feature is deployed to a **staging** environment to be tested. 1. When successful, it's deployed to **production**. -If you have the labels "**backend**", "**frontend**", "**staging**", and -"**production**", and an issue board with a list for each, you can: +If you have the labels **Backend**, **Frontend**, **Staging**, and +**Production**, and an issue board with a list for each, you can: - Visualize the entire flow of implementations since the beginning of the development life cycle until deployed to production. @@ -78,7 +78,7 @@ If you have the labels "**backend**", "**frontend**", "**staging**", and - Move issues between lists to organize them according to the labels you've set. - Add multiple issues to lists in the board by selecting one or more existing issues. - + ### Use cases for multiple issue boards @@ -199,7 +199,7 @@ Using the search box at the top of the menu, you can filter the listed boards. When you have ten or more boards available, a **Recent** section is also shown in the menu, with shortcuts to your last four visited boards. - + When you're revisiting an issue board in a project or group with multiple boards, GitLab automatically loads the last board you visited. @@ -229,20 +229,16 @@ An issue board can be associated with a GitLab [Milestone](milestones/index.md#m which automatically filter the board issues accordingly. This allows you to create unique boards according to your team's need. - + -You can define the scope of your board when creating it or by clicking the "Edit board" button. -Once a milestone, assignee or weight is assigned to an issue board, you can no longer +You can define the scope of your board when creating it or by clicking the **Edit board** button. +After a milestone, assignee or weight is assigned to an issue board, you can no longer filter through these in the search bar. In order to do that, you need to remove the desired scope (for example, milestone, assignee, or weight) from the issue board. - - If you don't have editing permission in a board, you're still able to see the configuration by clicking **View scope**. - - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video presentation](https://youtu.be/m5UTNCSqaDk) of the Configurable Issue Board feature. @@ -253,12 +249,8 @@ the Configurable Issue Board feature. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28597) to the Free tier of GitLab.com in 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212331) to GitLab Core in 13.0. -Click the button at the top right to toggle focus mode on and off. In focus mode, the navigation UI -is hidden, allowing you to focus on issues in the board. - - - ---- +To enable or disable focus mode, select the **Toggle focus mode** button (**{maximize}**) at the top +right. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. ### Sum of issue weights **(STARTER)** @@ -266,7 +258,7 @@ The top of each list indicates the sum of issue weights for the issues that belong to that list. This is useful when using boards for capacity allocation, especially in combination with [assignee lists](#assignee-lists). - + ### Group issue boards **(PREMIUM)** @@ -279,8 +271,6 @@ group and its descendant subgroups. Similarly, you can only filter by group labe boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only group-level objects are available. - - ### Assignee lists **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5784) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.0. @@ -290,15 +280,15 @@ an assignee list that shows all issues assigned to a user. You can have a board with both label lists and assignee lists. To add an assignee list: -1. Click **Add list**. +1. Select the **Add list** dropdown button. 1. Select the **Assignee list** tab. -1. Search and click the user you want to add as an assignee. +1. Search and select the user you want to add as an assignee. Now that the assignee list is added, you can assign or unassign issues to that user by [dragging issues](#drag-issues-between-lists) to and from an assignee list. To remove an assignee list, just as with a label list, click the trash icon. - + ### Milestone lists **(PREMIUM)** @@ -307,7 +297,7 @@ To remove an assignee list, just as with a label list, click the trash icon. 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. To add a milestone list: -1. Click **Add list**. +1. Select the **Add list** dropdown button. 1. Select the **Milestone** tab. 1. Search and click the milestone. @@ -315,7 +305,31 @@ Like the assignee lists, you're able to [drag issues](#drag-issues-between-lists to and from a milestone list to manipulate the milestone of the dragged issues. As in other list types, click the trash icon to remove a list. - + + +### Group issues in swimlanes **(PREMIUM)** + +> Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. + +With swimlanes you can visualize issues grouped by epic. +Your issue board keeps all the other features, but with a different visual organization of issues. +This feature is available both at the project and group level. + +To group issues by epic in an issue board: + +1. Select the **Group by** dropdown button. +1. Select **Epic**. + + + +You can also [drag issues](#drag-issues-between-lists) to change their position and epic assignment: + +- To reorder an issue, drag it to the new position within a list. +- To assign an issue to another epic, drag it to the epic's horizontal lane. +- To unassign an issue from an epic, drag it to the **Issues with no epic assigned** lane. +- To move an issue to another epic _and_ another list, at the same time, drag the issue diagonally. + + ## Work In Progress limits **(STARTER)** @@ -347,7 +361,7 @@ To set a WIP limit for a list: If an issue is blocked by another issue, an icon appears next to its title to indicate its blocked status. - + ## Actions you can take on an issue board @@ -381,16 +395,16 @@ have that label. ### Create a new list -Create a new list by clicking the **Add list** button in the upper right corner of the issue board. +Create a new list by clicking the **Add list** dropdown button in the upper right corner of the issue board. - + -Then, choose the label or user to create the list from. The new list is inserted -at the end of the lists, before **Done**. Moving and reordering lists is as -easy as dragging them around. +Then, choose the label or user to base the new list on. The new list is inserted +at the end of the lists, before **Done**. To move and reorder lists, drag them around. To create a list for a label that doesn't yet exist, create the label by -choosing **Create new label**. This creates the label immediately and adds it to the dropdown. +choosing **Create project label** or **Create group label**. +This creates the label immediately and adds it to the dropdown. You can now choose it to create a list. ### Delete a list @@ -404,14 +418,14 @@ list view that's removed. You can always restore it later if you need. ### Add issues to a list You can add issues to a list by clicking the **Add issues** button -present in the upper right corner of the issue board. This opens up a modal +in the top right corner of the issue board. This opens up a modal window where you can see all the issues that do not belong to any list. Select one or more issues by clicking the cards and then click **Add issues** to add them to the selected list. You can limit the issues you want to add to the list by filtering by author, assignee, milestone, and label. - + ### Remove an issue from a list @@ -419,13 +433,13 @@ Removing an issue from a list can be done by clicking the issue card and then clicking the **Remove from board** button in the sidebar. The respective label is removed. - + ### Filter issues You should be able to use the filters on top of your issue board to show only -the results you want. It's similar to the filtering used in the issue tracker -since the metadata from the issues and labels are re-used in the issue board. +the results you want. It's similar to the filtering used in the issue tracker, +as the metadata from the issues and labels is re-used in the issue board. You can filter by author, assignee, milestone, and label. @@ -435,13 +449,13 @@ By reordering your lists, you can create workflows. As lists in issue boards are based on labels, it works out of the box with your existing issues. So if you've already labeled things with **Backend** and **Frontend**, the issue appears in -the lists as you create them. In addition, this means you can easily move -something between lists by changing a label. +the lists as you create them. In addition, this means you can move something between lists by +changing a label. A typical workflow of using an issue board would be: 1. You have [created](labels.md#label-management) and [prioritized](labels.md#label-priority) - labels so that you can easily categorize your issues. + labels to categorize your issues. 1. You have a bunch of issues (ideally labeled). 1. You visit the issue board and start [creating lists](#create-a-new-list) to create a workflow. @@ -457,15 +471,15 @@ For example, you can create a list based on the label of **Frontend** and one fo **Frontend** list. That way, everyone knows that this issue is now being worked on by the designers. -Then, once they're done, all they have to do is +Then, when they're done, all they have to do is drag it to the next list, **Backend**. Then, a backend developer can -eventually pick it up. Once they’re done, they move it to **Done**, to close the +eventually pick it up. When they’re done, they move it to **Done**, to close the issue. This process can be seen clearly when visiting an issue. With every move to another list, the label changes and a system note is recorded. - + ### Drag issues between lists @@ -473,16 +487,17 @@ When dragging issues between lists, different behavior occurs depending on the s | | To Open | To Closed | To label `B` list | To assignee `Bob` list | |----------------------------|--------------------|--------------|------------------------------|---------------------------------------| -| From Open | - | Issue closed | `B` added | `Bob` assigned | -| From Closed | Issue reopened | - | Issue reopened<br/>`B` added | Issue reopened<br/>`Bob` assigned | -| From label `A` list | `A` removed | Issue closed | `A` removed<br/>`B` added | `Bob` assigned | -| From assignee `Alice` list | `Alice` unassigned | Issue closed | `B` added | `Alice` unassigned<br/>`Bob` assigned | +| **From Open** | - | Issue closed | `B` added | `Bob` assigned | +| **From Closed** | Issue reopened | - | Issue reopened<br/>`B` added | Issue reopened<br/>`Bob` assigned | +| **From label `A` list** | `A` removed | Issue closed | `A` removed<br/>`B` added | `Bob` assigned | +| **From assignee `Alice` list** | `Alice` unassigned | Issue closed | `B` added | `Alice` unassigned<br/>`Bob` assigned | ### Multi-select issue cards > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. -You can select multiple issue cards, then drag the group to another position within the list, or to another list. This makes it faster to reorder many issues at once. +You can select multiple issue cards, then drag the group to another position within the list, or to +another list. This makes it faster to reorder many issues at once. To select and move multiple cards: diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index af01534a67f..af9a6401474 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Export Issues to CSV > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1126) in [GitLab Starter 9.0](https://about.gitlab.com/releases/2017/03/22/gitlab-9-0-released/#export-issues-ees-eep). diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 807f4fcffdf..2cac88b1b29 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Importing issues from CSV > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23532) in GitLab 11.7. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 6f57487fccd..c19c9ca0615 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -228,7 +228,7 @@ available in the **Resolved Comment** area at the bottom of the right sidebar. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245074) in GitLab 13.5. -Add a to do for a design by clicking **Add a To Do** on the design sidebar: +Add a to-do item for a design by clicking **Add a to do** on the design sidebar:  diff --git a/doc/user/project/issues/img/adding_note_to_design_1.png b/doc/user/project/issues/img/adding_note_to_design_1.png Binary files differindex aa50bbb69ce..3c25fcb1241 100644 --- a/doc/user/project/issues/img/adding_note_to_design_1.png +++ b/doc/user/project/issues/img/adding_note_to_design_1.png diff --git a/doc/user/project/issues/img/adding_note_to_design_2.png b/doc/user/project/issues/img/adding_note_to_design_2.png Binary files differindex 37cefeb1a15..c418a0364c0 100644 --- a/doc/user/project/issues/img/adding_note_to_design_2.png +++ b/doc/user/project/issues/img/adding_note_to_design_2.png diff --git a/doc/user/project/issues/img/button_close_issue.png b/doc/user/project/issues/img/button_close_issue.png Binary files differdeleted file mode 100644 index 05d257ce9bf..00000000000 --- a/doc/user/project/issues/img/button_close_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/button_close_issue_v13_6.png b/doc/user/project/issues/img/button_close_issue_v13_6.png Binary files differnew file mode 100644 index 00000000000..6c7f8da496b --- /dev/null +++ b/doc/user/project/issues/img/button_close_issue_v13_6.png diff --git a/doc/user/project/issues/img/closing_and_related_issues.png b/doc/user/project/issues/img/closing_and_related_issues.png Binary files differdeleted file mode 100644 index c6543e85fdb..00000000000 --- a/doc/user/project/issues/img/closing_and_related_issues.png +++ /dev/null diff --git a/doc/user/project/issues/img/confirm_design_deletion_v12_4.png b/doc/user/project/issues/img/confirm_design_deletion_v12_4.png Binary files differindex 447d3907122..5631b6ec98e 100644 --- a/doc/user/project/issues/img/confirm_design_deletion_v12_4.png +++ b/doc/user/project/issues/img/confirm_design_deletion_v12_4.png diff --git a/doc/user/project/issues/img/delete_multiple_designs_v12_4.png b/doc/user/project/issues/img/delete_multiple_designs_v12_4.png Binary files differindex 75cbdf77c24..40d449d5b39 100644 --- a/doc/user/project/issues/img/delete_multiple_designs_v12_4.png +++ b/doc/user/project/issues/img/delete_multiple_designs_v12_4.png diff --git a/doc/user/project/issues/img/delete_single_design_v12_4.png b/doc/user/project/issues/img/delete_single_design_v12_4.png Binary files differdeleted file mode 100644 index 158b4949ce4..00000000000 --- a/doc/user/project/issues/img/delete_single_design_v12_4.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_drag_and_drop_uploads_v12_9.png b/doc/user/project/issues/img/design_drag_and_drop_uploads_v12_9.png Binary files differdeleted file mode 100644 index 6680c792063..00000000000 --- a/doc/user/project/issues/img/design_drag_and_drop_uploads_v12_9.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png b/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png Binary files differindex 25a02eef406..4ab5e184905 100644 --- a/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png +++ b/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png diff --git a/doc/user/project/issues/img/design_management_v12_3.png b/doc/user/project/issues/img/design_management_v12_3.png Binary files differdeleted file mode 100644 index b3647aa97c1..00000000000 --- a/doc/user/project/issues/img/design_management_v12_3.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_management_v13_2.png b/doc/user/project/issues/img/design_management_v13_2.png Binary files differindex 6d7e03d6f20..3da11c92514 100644 --- a/doc/user/project/issues/img/design_management_v13_2.png +++ b/doc/user/project/issues/img/design_management_v13_2.png diff --git a/doc/user/project/issues/img/design_zooming_v12_7.png b/doc/user/project/issues/img/design_zooming_v12_7.png Binary files differindex 4acb4e10913..4966af06e41 100644 --- a/doc/user/project/issues/img/design_zooming_v12_7.png +++ b/doc/user/project/issues/img/design_zooming_v12_7.png diff --git a/doc/user/project/issues/img/epic_tree_health_status_v12_10.png b/doc/user/project/issues/img/epic_tree_health_status_v12_10.png Binary files differdeleted file mode 100644 index 1a603656fd8..00000000000 --- a/doc/user/project/issues/img/epic_tree_health_status_v12_10.png +++ /dev/null diff --git a/doc/user/project/issues/img/issue_health_status_v12_10.png b/doc/user/project/issues/img/issue_health_status_v12_10.png Binary files differdeleted file mode 100644 index dd6becbb970..00000000000 --- a/doc/user/project/issues/img/issue_health_status_v12_10.png +++ /dev/null diff --git a/doc/user/project/issues/img/issue_health_status_v12_9.png b/doc/user/project/issues/img/issue_health_status_v12_9.png Binary files differdeleted file mode 100644 index f8922a74fc1..00000000000 --- a/doc/user/project/issues/img/issue_health_status_v12_9.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_from_open_issue.png b/doc/user/project/issues/img/new_issue_from_open_issue.png Binary files differdeleted file mode 100644 index c6f3f0617ab..00000000000 --- a/doc/user/project/issues/img/new_issue_from_open_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png b/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png Binary files differnew file mode 100644 index 00000000000..902aa40614a --- /dev/null +++ b/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png diff --git a/doc/user/project/issues/img/reopen-issue.png b/doc/user/project/issues/img/reopen-issue.png Binary files differdeleted file mode 100644 index fc48742afe0..00000000000 --- a/doc/user/project/issues/img/reopen-issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/report-abuse.png b/doc/user/project/issues/img/report-abuse.png Binary files differdeleted file mode 100644 index f8cef22da03..00000000000 --- a/doc/user/project/issues/img/report-abuse.png +++ /dev/null diff --git a/doc/user/project/issues/img/select_designs_v12_4.png b/doc/user/project/issues/img/select_designs_v12_4.png Binary files differindex 532a79fce65..fe1c55a4ae2 100644 --- a/doc/user/project/issues/img/select_designs_v12_4.png +++ b/doc/user/project/issues/img/select_designs_v12_4.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 434af3a4a49..716377f2e45 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -95,12 +95,13 @@ While you can view and manage the full details of an issue on the [issue page](# you can also work with multiple issues at a time using the [Issues List](#issues-list), [Issue Boards](#issue-boards), Issue references, and [Epics](#epics)**(PREMIUM)**. -Key actions for Issues include: +Key actions for issues include: - [Creating issues](managing_issues.md#create-a-new-issue) - [Moving issues](managing_issues.md#moving-issues) - [Closing issues](managing_issues.md#closing-issues) - [Deleting issues](managing_issues.md#deleting-issues) +- [Promoting issues](managing_issues.md#promote-an-issue-to-an-epic) **(PREMIUM)** ### Issue page @@ -189,6 +190,8 @@ requires [GraphQL](../../../api/graphql/index.md) to be enabled. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. > - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4 and later. +> - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. + To help you track the status of your issues, you can assign a status to each issue to flag work that's progressing as planned or needs attention to keep on schedule: @@ -201,7 +204,7 @@ that's progressing as planned or needs attention to keep on schedule: After an issue is closed, its health status can't be edited and the "Edit" button becomes disabled until the issue is reopened. -You can then see issue statuses on the +You can then see issue statuses in the [issue list](#issues-list) and the [Epic tree](../../group/epics/index.md#issue-health-status-in-epic-tree). #### Disable issue health status diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 003444e0ed8..a5f60fbd515 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -18,7 +18,7 @@ You can find all the information for that issue on one screen.  -- **1.** [New Issue, close issue (reopen issue, report issue)](#new-issue-close-issue-reopen-issue-report-issue) +- **1.** [Issue actions](#issue-actions) - **2.** [To Do](#to-do) - **3.** [Assignee](#assignee) - **3.1.** [Multiple Assignees **(STARTER)**](#multiple-assignees) @@ -55,22 +55,21 @@ Many of the elements of the issue screen refresh automatically, such as the titl description, when they are changed by another user. Comments and system notes also update automatically in response to various actions and content updates. -### New Issue, close issue (reopen issue, report issue) +### Issue actions -Clicking on **New issue** will open a new window to create a new issue in the same project. -Clicking on **Close issue** will close this issue, but it will not be deleted. If the -issue is already closed, you can still access it and the button will show **Reopen issue**, as shown below, -which you can click to reopen the issue. A reopened issue is no different from any -other issue. +In an open issue, you can close it by selecting the **Close issue** button. +The issue is marked as closed but is not deleted. - +To reopen a closed issue, select the **Reopen issue** button. +A reopened issue is no different from any other open issue. -If you do not have rights to modify the issue, the **close issue** button will be -replaced with **report issue**, which you can click to [submit an abuse report](../../abuse_reports.md) -about the issue. It will also appear if you have rights to modify the issue, but only -after it is closed. +To access additional actions, select the vertical ellipsis +(**{ellipsis_v}**) button: - +- To create a new issue in the same project, select **New issue** in the dropdown menu. + +- If you are not the issue author, you can [submit an abuse report](../../abuse_reports.md). + Select **Report abuse** in the dropdown menu. ### To Do diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index b033dc79dcc..62b388ec137 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -7,9 +7,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Managing issues [GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and -planning work in GitLab. [Creating](#create-a-new-issue), [moving](#moving-issues), -[closing](#closing-issues), and [deleting](#deleting-issues) are key actions that -you can do with issues. +planning work in GitLab. + +Key actions for issues include: + +- [Creating issues](#create-a-new-issue) +- [Moving issues](#moving-issues) +- [Closing issues](#closing-issues) +- [Deleting issues](#deleting-issues) +- [Promoting issues](#promote-an-issue-to-an-epic) **(PREMIUM)** ## Create a new issue @@ -28,10 +34,10 @@ There are many ways to get to the New Issue form from within a project:  -- From an **opened issue** in your project, click **New Issue** to create a new - issue in the same project: +- From an **open issue** in your project, click the vertical ellipsis (**{ellipsis_v}**) button + to open a dropdown menu, and then click **New Issue** to create a new issue in the same project: -  +  - From your **Project's Dashboard**, click the plus sign (**+**) to open a dropdown menu with a few options. Select **New Issue** to create an issue in that project: @@ -178,7 +184,7 @@ end; nil When you decide that an issue is resolved, or no longer needed, you can close the issue using the close button: - + You can also close an issue from the [Issue Boards](../issue_board.md) by dragging an issue card from its list and dropping it into the **Closed** list. @@ -280,6 +286,23 @@ editing it and clicking on the delete button.  +## Promote an issue to an epic **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. +> - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. + +You can promote an issue to an epic in the immediate parent group. + +To promote an issue to an epic: + +1. In an issue, select the vertical ellipsis (**{ellipsis_v}**) button. +1. Select **Promote to epic**. + +Alternatively, you can use the `/promote` [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). + +Read more about promoting an issue to an epic on the [Manage epics page](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic). + ## Add an issue to an iteration **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 4f0354f86af..c237f46b23a 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -95,6 +95,8 @@ If you delete a label, it is permanently deleted. All references to the label ar #### Promote a project label to a group label +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231472) in GitLab 13.6: promoting a project label keeps that label's ID and changes it into a group label. Previously, promoting a project label created a new group label with a new ID and deleted the old label. + If you previously created a project label and now want to make it available for other projects within the same group, you can promote it to a group label. @@ -105,6 +107,8 @@ also merged. All issues, merge requests, issue board lists, issue board filters, and label subscriptions with the old labels are assigned to the new group label. +The new group label has the same ID as the previous project label. + CAUTION: **Caution:** Promoting a label is a permanent action, and cannot be reversed. diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index d8579c4cd8e..c66103604ed 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Members of a project You can manage the groups and users and their access levels in all of your diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 033d69cbbfa..395f4353f47 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Share Projects with other Groups You can share projects with other [groups](../../group/index.md). This makes it diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index e03d4e99b86..d50056c9450 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -265,6 +265,40 @@ Once the Code Quality job has completed: [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts) for the `code_quality` job. +### Generating an HTML report + +In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/ci-cd/codequality/-/issues/10), +it is possible to generate an HTML report file by setting the `REPORT_FORMAT` +variable to `html`. This is useful if you just want to view the report in a more +human-readable format or to publish this artifact on GitLab Pages for even +easier reviewing. + +```yaml +include: + - template: Code-Quality.gitlab-ci.yml + +code_quality: + variables: + REPORT_FORMAT: html + artifacts: + paths: [gl-code-quality-report.html] +``` + +It's also possible to generate both JSON and HTML report files by defining +another job and using `extends: code_quality`: + +```yaml +include: + - template: Code-Quality.gitlab-ci.yml + +code_quality_html: + extends: code_quality + variables: + REPORT_FORMAT: html + artifacts: + paths: [gl-code-quality-report.html] +``` + ## Extending functionality ### Using Analysis Plugins @@ -314,7 +348,7 @@ This can be due to multiple reasons: nothing will be displayed. - The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD setting can cause the Code Quality artifact(s) to expire faster than desired. -- Large `codeclimate.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). +- Large `codeclimate.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). As a work-around, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) that are [ignored by GitLab](#implementing-a-custom-tool). You can: - Configure the Code Quality tool to not output those types. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md new file mode 100644 index 00000000000..52c6f8a8d41 --- /dev/null +++ b/doc/user/project/merge_requests/csv_export.md @@ -0,0 +1,45 @@ +--- +stage: Manage +group: Compliance +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Export Merge Requests to CSV **(CORE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3619) in GitLab 13.6. + +Exporting Merge Requests CSV enables you and your team to export all the data collected from merge requests into a comma-separated values (CSV) file, which stores tabular data in plain text. + +To export Merge Requests to CSV, navigate to your **Merge Requests** from the sidebar of a project and click **Export to CSV**. + +## CSV Output + +The following table shows what attributes will be present in the CSV. + +| Column | Description | +|--------------------|--------------------------------------------------------------| +| MR ID | MR iid | +| URL | A link to the merge request on GitLab | +| Title | Merge request title | +| State | Opened, Closed, Locked, or Merged | +| Description | Merge request description | +| Source Branch | Source branch | +| Target Branch | Target branch | +| Source Project ID | ID of the source project | +| Target Project ID | ID of the target project | +| Author | Full name of the merge request author | +| Author Username | Username of the author, with the @ symbol omitted | +| Assignees | Full names of the merge request assignees, joined with a `,` | +| Assignee Usernames | Username of the assignees, with the @ symbol omitted | +| Approvers | Full names of the approvers, joined with a `,` | +| Approver Usernames | Username of the approvers, with the @ symbol omitted | +| Merged User | Full name of the merged user | +| Merged Username | Username of the merge user, with the @ symbol omitted | +| Milestone ID | ID of the merge request milestone | +| Created At (UTC) | Formatted as YYYY-MM-DD HH:MM:SS | +| Updated At (UTC) | Formatted as YYYY-MM-DD HH:MM:SS | + +## Limitations + +- Export merge requests to CSV is not available at the Group’s merge request list. +- As the merge request CSV file is sent as an email attachment, the size is limited to 15MB to ensure successful delivery across a range of email providers. If you need to minimize the size of the file, you can narrow the search before export. For example, you can set up exports of open and closed merge requests in separate files. diff --git a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png b/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png Binary files differdeleted file mode 100644 index ed374b11fbd..00000000000 --- a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/project_merge_requests_list_view.png b/doc/user/project/merge_requests/img/project_merge_requests_list_view.png Binary files differindex 457716d811c..2c86a1ad839 100644 --- a/doc/user/project/merge_requests/img/project_merge_requests_list_view.png +++ b/doc/user/project/merge_requests/img/project_merge_requests_list_view.png diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 2675f509eed..3ee88275aac 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -156,7 +156,7 @@ The best approach is to capture the dynamic URL in a [`.env` file](https://docs. as a job artifact to be shared, then use a custom environment variable we've provided named `K6_DOCKER_OPTIONS` to configure the k6 Docker container to use the file. With this, k6 can then use any environment variables from the `.env` file in scripts using standard JavaScript, -such as: ``http.get(`${__ENV.ENVIRONMENT_URL`})``. +such as: ``http.get(`${__ENV.ENVIRONMENT_URL}`)``. For example: diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index bded1839f97..039f0f7d5e1 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -73,11 +73,11 @@ test: cobertura: coverage/cobertura-coverage.xml ``` -### Java examples +### Java and Kotlin examples #### Maven example -The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java uses [Maven](https://maven.apache.org/) +The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/) to build the project and [Jacoco](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -101,7 +101,7 @@ coverage-jdk11: # The `visualize` stage does not exist by default. # Please define it first, or chose an existing stage like `deploy`. stage: visualize - image: haynes/jacoco2cobertura:1.0.3 + image: haynes/jacoco2cobertura:1.0.4 script: # convert report from jacoco to cobertura - 'python /opt/cover2cover.py target/site/jacoco/jacoco.xml src/main/java > target/site/cobertura.xml' @@ -117,7 +117,7 @@ coverage-jdk11: #### Gradle example -The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java uses [Gradle](https://gradle.org/) +The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java or Kotlin uses [Gradle](https://gradle.org/) to build the project and [Jacoco](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -141,7 +141,7 @@ coverage-jdk11: # The `visualize` stage does not exist by default. # Please define it first, or chose an existing stage like `deploy`. stage: visualize - image: haynes/jacoco2cobertura:1.0.3 + image: haynes/jacoco2cobertura:1.0.4 script: # convert report from jacoco to cobertura - 'python /opt/cover2cover.py build/jacoco/jacoco.xml src/main/java > build/cobertura.xml' diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 9581c974414..0922ffb2943 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, concepts --- diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index e7abf6e5fb6..2218d38fdad 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -27,7 +27,7 @@ There are several ways to flag a merge request as a Draft: description will have the same effect. - **Deprecated** Add `[WIP]` or `WIP:` to the start of the merge request's title. **WIP** still works but was deprecated in favor of **Draft**. It will be removed in the next major version (GitLab 14.0). -- Add the `/wip` [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) +- Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) in a comment in the merge request. This is a toggle, and can be repeated to change the status back. Note that any other text in the comment will be discarded. - Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the beginning of a commit message targeting the @@ -43,7 +43,7 @@ Similar to above, when a Merge Request is ready to be merged, you can remove the - Remove `[Draft]`, `Draft:` or `(Draft)` from the start of the merge request's title. Clicking on **Remove the Draft: prefix from the title**, under the title box, when editing the merge request's description, will have the same effect. -- Add the `/wip` [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) +- Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) in a comment in the merge request. This is a toggle, and can be repeated to change the status back. Note that any other text in the comment will be discarded. - Click on the **Resolve Draft status** button near the bottom of the merge request description, diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 327a52a05ab..ae03be5fa0f 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -9,18 +9,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w [Burndown](#burndown-charts) and [burnup](#burnup-charts) charts show the progress of completing a milestone. - + ## Burndown charts > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1540) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1 for project milestones. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5354) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.8 for group milestones. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to [GitLab Starter](https://about.gitlab.com/pricing/) 11.2 for group milestones. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. Burndown charts show the number of issues over the course of a milestone. - + At a glance, you see the current state for the completion a given milestone. Without them, you would have to organize the data from the milestone and plot it @@ -81,12 +81,12 @@ cumulative value. ### Fixed burndown charts -For milestones created before GitLab 13.5, burndown charts have an additional toggle to +For milestones created before GitLab 13.6, burndown charts have an additional toggle to switch between Legacy and Fixed views. | Legacy | Fixed | | ----- | ----- | -|  |  | +|  |  | **Fixed burndown** charts track the full history of milestone activity, from its creation until the milestone expires. After the milestone due date passes, issues removed from the milestone no longer @@ -103,11 +103,18 @@ Reopened issues are considered as having been opened on the day after they were ## Burnup charts -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. +> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-burnup-charts). **(STARTER ONLY)** + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. Burnup charts show the assigned and completed work for a milestone. - + To view a project's burnup chart: @@ -129,6 +136,25 @@ Burnup charts can show either the total number of issues or total weight for eac day of the milestone. Use the toggle above the charts to switch between total and weight. +### Enable or disable burnup charts **(STARTER ONLY)** + +Burnup charts is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:burnup_charts) +``` + +To disable it: + +```ruby +Feature.disable(:burnup_charts) +``` + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md index 5aa5534dd37..5d9e6b67bb8 100644 --- a/doc/user/project/milestones/burndown_charts.md +++ b/doc/user/project/milestones/burndown_charts.md @@ -2,4 +2,4 @@ redirect_to: './burndown_and_burnup_charts.md' --- -This document was moved to [another location](./burndown_and_burnup_charts.md). +This document was moved to [another location](burndown_and_burnup_charts.md). diff --git a/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_5.png b/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_6.png Binary files differindex 8d6ba1d4fa7..8d6ba1d4fa7 100644 --- a/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_5.png +++ b/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_6.png diff --git a/doc/user/project/milestones/img/burndown_chart_fixed_v13_5.png b/doc/user/project/milestones/img/burndown_chart_fixed_v13_6.png Binary files differindex a532bfeeca0..a532bfeeca0 100644 --- a/doc/user/project/milestones/img/burndown_chart_fixed_v13_5.png +++ b/doc/user/project/milestones/img/burndown_chart_fixed_v13_6.png diff --git a/doc/user/project/milestones/img/burndown_chart_legacy_v13_5.png b/doc/user/project/milestones/img/burndown_chart_legacy_v13_6.png Binary files differindex 5824fc59ce5..5824fc59ce5 100644 --- a/doc/user/project/milestones/img/burndown_chart_legacy_v13_5.png +++ b/doc/user/project/milestones/img/burndown_chart_legacy_v13_6.png diff --git a/doc/user/project/milestones/img/burndown_chart_v13_5.png b/doc/user/project/milestones/img/burndown_chart_v13_6.png Binary files differindex e06b24f9907..e06b24f9907 100644 --- a/doc/user/project/milestones/img/burndown_chart_v13_5.png +++ b/doc/user/project/milestones/img/burndown_chart_v13_6.png diff --git a/doc/user/project/milestones/img/burnup_chart_v13_5.png b/doc/user/project/milestones/img/burnup_chart_v13_6.png Binary files differindex a850caba348..a850caba348 100644 --- a/doc/user/project/milestones/img/burnup_chart_v13_5.png +++ b/doc/user/project/milestones/img/burnup_chart_v13_6.png diff --git a/doc/user/project/milestones/img/milestones_new_group_milestone.png b/doc/user/project/milestones/img/milestones_new_group_milestone.png Binary files differindex a517f0f7537..5bbe8e51f23 100644 --- a/doc/user/project/milestones/img/milestones_new_group_milestone.png +++ b/doc/user/project/milestones/img/milestones_new_group_milestone.png diff --git a/doc/user/project/milestones/img/milestones_new_project_milestone.png b/doc/user/project/milestones/img/milestones_new_project_milestone.png Binary files differindex 482c73f6568..2d0bdce542d 100644 --- a/doc/user/project/milestones/img/milestones_new_project_milestone.png +++ b/doc/user/project/milestones/img/milestones_new_project_milestone.png diff --git a/doc/user/project/milestones/img/milestones_project_milestone_page.png b/doc/user/project/milestones/img/milestones_project_milestone_page.png Binary files differindex c17bf350aeb..1faaf0b3979 100644 --- a/doc/user/project/milestones/img/milestones_project_milestone_page.png +++ b/doc/user/project/milestones/img/milestones_project_milestone_page.png diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 8cbed3de1c6..9c47f15cb8f 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -150,7 +150,7 @@ There are also tabs below these that show the following: For project milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. - + ### Group Burndown Charts **(STARTER)** diff --git a/doc/user/project/operations/img/alert_issue_v13_1.png b/doc/user/project/operations/img/alert_issue_v13_1.png Binary files differdeleted file mode 100644 index da79074aa2f..00000000000 --- a/doc/user/project/operations/img/alert_issue_v13_1.png +++ /dev/null diff --git a/doc/user/project/operations/img/error_details_v12_5.png b/doc/user/project/operations/img/error_details_v12_5.png Binary files differdeleted file mode 100644 index f4866141948..00000000000 --- a/doc/user/project/operations/img/error_details_v12_5.png +++ /dev/null diff --git a/doc/user/project/operations/img/error_details_v12_6.png b/doc/user/project/operations/img/error_details_v12_6.png Binary files differdeleted file mode 100644 index 3194d8284d7..00000000000 --- a/doc/user/project/operations/img/error_details_v12_6.png +++ /dev/null diff --git a/doc/user/project/operations/img/error_details_with_issue_v12_6.png b/doc/user/project/operations/img/error_details_with_issue_v12_6.png Binary files differdeleted file mode 100644 index 963b70bd1e4..00000000000 --- a/doc/user/project/operations/img/error_details_with_issue_v12_6.png +++ /dev/null diff --git a/doc/user/project/operations/img/error_details_with_issue_v12_7.png b/doc/user/project/operations/img/error_details_with_issue_v12_7.png Binary files differdeleted file mode 100644 index aa846ee7220..00000000000 --- a/doc/user/project/operations/img/error_details_with_issue_v12_7.png +++ /dev/null diff --git a/doc/user/project/operations/img/feature_flags_list_v12_7.png b/doc/user/project/operations/img/feature_flags_list_v12_7.png Binary files differdeleted file mode 100644 index a28a844b46d..00000000000 --- a/doc/user/project/operations/img/feature_flags_list_v12_7.png +++ /dev/null diff --git a/doc/user/project/operations/img/specs_list_v12_6.png b/doc/user/project/operations/img/specs_list_v12_6.png Binary files differdeleted file mode 100644 index ea429802a40..00000000000 --- a/doc/user/project/operations/img/specs_list_v12_6.png +++ /dev/null diff --git a/doc/user/project/packages/img/maven_package_view.png b/doc/user/project/packages/img/maven_package_view.png Binary files differdeleted file mode 100644 index 2eb4b6f76b4..00000000000 --- a/doc/user/project/packages/img/maven_package_view.png +++ /dev/null diff --git a/doc/user/project/packages/img/npm_package_view.png b/doc/user/project/packages/img/npm_package_view.png Binary files differdeleted file mode 100644 index e0634718c02..00000000000 --- a/doc/user/project/packages/img/npm_package_view.png +++ /dev/null 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 a7eb4c4019f..e030326ac5f 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -158,9 +158,12 @@ When it succeeds, go to **Settings > Pages** to view the URL where your site is now available. If you want to do more advanced tasks, you can update your `.gitlab-ci.yml` file -with [any of the available settings](../../../../ci/yaml/README.md). See -[Validate the `.gitlab-ci.yml`](../../../../ci/yaml/README.md#validate-the-gitlab-ciyml) -for instructions on validating your YAML file with the Lint tool included with GitLab. +with [any of the available settings](../../../../ci/yaml/README.md). You can validate +your `.gitlab-ci.yml` file with the [CI Lint](../../../../ci/lint.md) tool that's included with GitLab. + +After successful execution of this `pages` job, a special `pages:deploy` job appears in the +pipeline view. It prepares the content of the website for GitLab Pages daemon. GitLab executes it in +the background and doesn't use runner. The following topics show other examples of other options you can add to your CI/CD file. diff --git a/doc/user/project/pages/img/icons/click.png b/doc/user/project/pages/img/icons/click.png Binary files differdeleted file mode 100644 index 62a997a7591..00000000000 --- a/doc/user/project/pages/img/icons/click.png +++ /dev/null diff --git a/doc/user/project/pages/img/icons/cogs.png b/doc/user/project/pages/img/icons/cogs.png Binary files differdeleted file mode 100644 index f37f8f361d1..00000000000 --- a/doc/user/project/pages/img/icons/cogs.png +++ /dev/null diff --git a/doc/user/project/pages/img/icons/fork.png b/doc/user/project/pages/img/icons/fork.png Binary files differdeleted file mode 100644 index 1ae8fa722b7..00000000000 --- a/doc/user/project/pages/img/icons/fork.png +++ /dev/null diff --git a/doc/user/project/pages/img/icons/free.png b/doc/user/project/pages/img/icons/free.png Binary files differdeleted file mode 100644 index c74cd90fa1a..00000000000 --- a/doc/user/project/pages/img/icons/free.png +++ /dev/null diff --git a/doc/user/project/pages/img/icons/monitor.png b/doc/user/project/pages/img/icons/monitor.png Binary files differdeleted file mode 100644 index ce27b7e177e..00000000000 --- a/doc/user/project/pages/img/icons/monitor.png +++ /dev/null diff --git a/doc/user/project/pages/img/pages_workflow_v12_5.png b/doc/user/project/pages/img/pages_workflow_v12_5.png Binary files differdeleted file mode 100644 index ca5190fca79..00000000000 --- a/doc/user/project/pages/img/pages_workflow_v12_5.png +++ /dev/null diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 4f389716f08..f5cd6991869 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -29,7 +29,7 @@ directly from a repository in GitLab. </ul> </p> </div> -<div class="col-md-3"><img src="img/ssgs_pages.png" alt="Examples of SSGs supported by Pages" class="image-noshadow middle display-block"></div> +<div class="col-md-3"><img src="img/ssgs_pages.png" alt="Examples of SSGs supported by Pages" class="middle display-block"></div> </div> To publish a website with Pages, you can use any SSG, @@ -89,7 +89,7 @@ need admin access to your domain's registrar (or control panel) to set it up wit The following diagrams show the workflows you might follow to get started with Pages. -<img src="img/new_project_for_pages_v12_5.png" alt="New projects for GitLab Pages" class="image-noshadow"> +<img src="img/new_project_for_pages_v12_5.png" alt="New projects for GitLab Pages"> ## Access to your Pages site diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index b97d5328c07..6dbc12cc2ec 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -11,7 +11,7 @@ GitLab Pages offers. To familiarize yourself with GitLab Pages first: -- Read an [introduction to GitLab Pages](index.md#overview). +- Read an [introduction to GitLab Pages](index.md). - Learn [how to get started with Pages](index.md#getting-started). - Learn how to enable GitLab Pages across your GitLab instance on the [administrator documentation](../../../administration/pages/index.md). diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index 02d1dd7898a..13ea57939f8 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -1,4 +1,7 @@ --- +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)." --- diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 2f1b05f481e..46db7293711 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -40,6 +40,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/copy_metadata <#issue>` | ✓ | ✓ | | Copy labels and milestone from another issue in the project. | | `/create_merge_request <branch name>` | ✓ | | | Create a new merge request starting from the current issue. | | `/done` | ✓ | ✓ | ✓ | Mark to do as done. | +| `/draft` | | ✓ | | Toggle the draft status. | | `/due <date>` | ✓ | | | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | | `/duplicate <#issue>` | ✓ | | | Close this issue and mark as a duplicate of another issue. **(CORE)** Also, mark both as related. **(STARTER)** | | `/epic <epic>` | ✓ | | | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. **(PREMIUM)** | @@ -74,7 +75,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/tableflip <comment>` | ✓ | ✓ | ✓ | Append the comment with `(╯°□°)╯︵ ┻━┻`. | | `/target_branch <local branch name>` | | ✓ | | Set target branch. | | `/title <new title>` | ✓ | ✓ | ✓ | Change title. | -| `/todo` | ✓ | ✓ | ✓ | Add a to do. | +| `/todo` | ✓ | ✓ | ✓ | Add a to-do item. | | `/unassign @user1 @user2` | ✓ | ✓ | | Remove specific assignees. **(STARTER)** | | `/unassign` | ✓ | ✓ | | Remove all assignees. | | `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓ | ✓ | ✓ | Remove specified labels. | @@ -82,7 +83,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/unlock` | ✓ | ✓ | | Unlock the discussions. | | `/unsubscribe` | ✓ | ✓ | ✓ | Unsubscribe from notifications. | | `/weight <value>` | ✓ | | | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. **(STARTER)** | -| `/wip` | | ✓ | | Toggle the Work In Progress status. | +| `/wip` | | ✓ | | Toggle the draft status. | | `/zoom <Zoom URL>` | ✓ | | | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | ## Autocomplete characters diff --git a/doc/user/project/releases/img/edit_release_page_v12_10.png b/doc/user/project/releases/img/edit_release_page_v12_10.png Binary files differdeleted file mode 100644 index ebb12a549b7..00000000000 --- a/doc/user/project/releases/img/edit_release_page_v12_10.png +++ /dev/null diff --git a/doc/user/project/releases/img/edit_release_page_v12_6.png b/doc/user/project/releases/img/edit_release_page_v12_6.png Binary files differdeleted file mode 100644 index ae7641ac8a5..00000000000 --- a/doc/user/project/releases/img/edit_release_page_v12_6.png +++ /dev/null diff --git a/doc/user/project/releases/img/release_with_milestone_v12_5.png b/doc/user/project/releases/img/release_with_milestone_v12_5.png Binary files differdeleted file mode 100644 index 2a7a2ee9754..00000000000 --- a/doc/user/project/releases/img/release_with_milestone_v12_5.png +++ /dev/null diff --git a/doc/user/project/releases/img/releases.png b/doc/user/project/releases/img/releases.png Binary files differdeleted file mode 100644 index da5bcd9d913..00000000000 --- a/doc/user/project/releases/img/releases.png +++ /dev/null diff --git a/doc/user/project/releases/img/releases_count_v12_8.png b/doc/user/project/releases/img/releases_count_v12_8.png Binary files differdeleted file mode 100644 index e70f623d508..00000000000 --- a/doc/user/project/releases/img/releases_count_v12_8.png +++ /dev/null diff --git a/doc/user/project/releases/img/releases_sort_v13_6.png b/doc/user/project/releases/img/releases_sort_v13_6.png Binary files differnew file mode 100644 index 00000000000..e663e3cc7f3 --- /dev/null +++ b/doc/user/project/releases/img/releases_sort_v13_6.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 962d612cac1..674fe8b22b8 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -43,6 +43,13 @@ To view a list of releases: - On private projects, this number is visible to users with Reporter [permissions](../../permissions.md#project-members-permissions) or higher. +### Sort Releases + +On the top right of the **Releases** page, you can use the sorting button to order releases by +**Released date** or **Created date**. You can sort releases in ascending or descending order. + + + ## Create a release > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32812) in GitLab 12.9. Releases can be created directly in the GitLab UI. @@ -130,6 +137,8 @@ In the interface, to add release notes to an existing Git tag: You can associate a release with one or more [project milestones](../milestones/index.md#project-milestones-and-group-milestones). +[GitLab Premium](https://about.gitlab.com/pricing/) customers can specify [group milestones](../milestones/index.md#project-milestones-and-group-milestones) to associate with a release. + You can do this in the user interface, or by including a `milestones` array in your request to the [Releases API](../../../api/releases/index.md#create-a-release). @@ -446,17 +455,17 @@ In the API: - If you do not specify a `released_at` date, release evidence is collected on the date the release is created. -## GitLab Releaser +## Release Command Line -> [Introduced](https://gitlab.com/gitlab-org/gitlab-releaser/-/merge_requests/6) in GitLab 12.10. +> [Introduced](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/6) in GitLab 12.10. -GitLab Releaser is a CLI tool for managing GitLab Releases from the command line or from +The Release CLI is a command-line tool for managing GitLab Releases from the command line or from GitLab's CI/CD configuration file, `.gitlab-ci.yml`. With it, you can create, update, modify, and delete releases right through the terminal. -Read the [GitLab Releaser documentation](https://gitlab.com/gitlab-org/gitlab-releaser/-/tree/master/docs/index.md) +Read the [Release CLI documentation](https://gitlab.com/gitlab-org/release-cli/-/blob/master/docs/index.md) for details. <!-- ## Troubleshooting diff --git a/doc/user/project/repository/branches/img/compare_branches.png b/doc/user/project/repository/branches/img/compare_branches.png Binary files differindex 52d5c518c45..e6f88da4989 100644 --- a/doc/user/project/repository/branches/img/compare_branches.png +++ b/doc/user/project/repository/branches/img/compare_branches.png diff --git a/doc/user/project/repository/img/file_ext_icons_repo_v12_10.png b/doc/user/project/repository/img/file_ext_icons_repo_v12_10.png Binary files differindex 346f0e58325..04a8f38871b 100644 --- a/doc/user/project/repository/img/file_ext_icons_repo_v12_10.png +++ b/doc/user/project/repository/img/file_ext_icons_repo_v12_10.png diff --git a/doc/user/project/repository/img/repository_mirroring_push_settings.png b/doc/user/project/repository/img/repository_mirroring_push_settings.png Binary files differindex 9fc25dd3b25..8916d21d515 100644 --- a/doc/user/project/repository/img/repository_mirroring_push_settings.png +++ b/doc/user/project/repository/img/repository_mirroring_push_settings.png diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index fe432e0d553..69a32841981 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -22,8 +22,8 @@ GitLab. ## Jupyter Hub as a GitLab Managed App -You can deploy [Jupyter Hub as a GitLab managed app](./../../../clusters/applications.md#jupyterhub). +You can deploy [Jupyter Hub as a GitLab managed app](../../../clusters/applications.md#jupyterhub). ## Jupyter Git integration -Find out how to [leverage JupyterLab’s Git extension on your Kubernetes cluster](./../../../clusters/applications.md#jupyter-git-integration). +Find out how to [leverage JupyterLab’s Git extension on your Kubernetes cluster](../../../clusters/applications.md#jupyter-git-integration). 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 ad79fd8a8f9..9f4dfe54c47 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 @@ -18,7 +18,7 @@ We **recommend [`git filter-repo`](https://github.com/newren/git-filter-repo/blo over [`git filter-branch`](https://git-scm.com/docs/git-filter-branch) and [BFG](https://rtyley.github.io/bfg-repo-cleaner/). -DANGER: **Danger:** +DANGER: **Warning:** Rewriting repository history is a destructive operation. Make sure to back up your repository before you begin. The best way back up a repository is to [export the project](../settings/import_export.md#exporting-a-project-and-its-data). @@ -202,6 +202,12 @@ To purge files from GitLab storage: ## Repository cleanup +NOTE: **Note:** +Safely cleaning the repository requires it to be made read-only for the duration +of the operation. This happens automatically, but submitting the cleanup request +will fail if any writes are ongoing, so cancel any outstanding `git push` +operations before continuing. + > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19376) in GitLab 11.6. Repository cleanup allows you to upload a text file of objects and GitLab will remove internal Git diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 188699e0c77..1f9835f4f59 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -577,3 +577,7 @@ Should an error occur during a push, GitLab will display an "Error" highlight fo ### 13:Received RST_STREAM with error code 2 with GitHub If you receive an "13:Received RST_STREAM with error code 2" while mirroring to a GitHub repository, your GitHub settings might be set to block pushes that expose your email address used in commits. Either set your email address on GitHub to be public, or disable the [Block command line pushes that expose my email](https://github.com/settings/emails) setting. + +### 4:Deadline Exceeded + +When upgrading to GitLab 11.11.8 or newer, a change in how usernames are represented means that you may need to update your mirroring username and password to ensure that `%40` characters are replaced with `@`. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index af0daaaeca2..5b82cdbd9e9 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -29,6 +29,11 @@ When you are satisfied with your new file, click **Commit Changes** at the botto  +### Shortcuts + +You can use handy shortcuts when editing a file through the Web Editor, which are the same as +the WEB IDE's. For details, see the documentation for [Command Palette](../web_ide/index.md#command-palette). + ### Template dropdowns When starting a new project, there are some common files that the new project @@ -107,7 +112,7 @@ name or a referenced merge request or your project has an active fork relationship. If you would like to make this button appear, a possible workaround is to [remove your project's fork relationship](../settings/index.md#removing-a-fork-relationship). Once removed, the fork -relationship cannot be restored, and you will no longer be able to send merge requests to the source. +relationship cannot be restored. This project will no longer be able to receive or send merge requests to the source project or other forks.  diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 0a1b81a6359..34a075df990 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -76,7 +76,7 @@ Follow these steps to do so: address's format. The older format is still supported, however, allowing existing aliases or contacts to continue working. - DANGER: **Danger:** + DANGER: **Warning:** This email address can be used by anyone to create an issue on this project, whether or not they have access to your GitLab instance. We recommend **putting this behind an alias** so it can be changed if needed, and **[enabling Akismet](../../integration/akismet.md)** on your GitLab @@ -99,7 +99,7 @@ navigation's **Issues** menu. When a user submits a new issue using Service Desk, or when a new note is created on a Service Desk issue, an email is sent to the author. -The body of these email messages can customized by using templates. To create a new customized template, +The body of these email messages can be customized by using templates. To create a new customized template, create a new Markdown (`.md`) file inside the `.gitlab/service_desk_templates/` directory in your repository. Commit and push to your default branch. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 478d9b3b948..3e493f02392 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Source Code +stage: Manage +group: Import info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: reference, howto --- @@ -32,6 +32,9 @@ To set up a project import/export: Note the following: +- Before you can import a project, you need to export the data first. + See [Exporting a project and its data](#exporting-a-project-and-its-data) + for how you can export a project through the UI. - Imports from a newer version of GitLab are not supported. The Importing GitLab version must be greater than or equal to the Exporting GitLab version. - Imports will fail unless the import and export GitLab instances are @@ -41,7 +44,7 @@ Note the following: - Group members are exported as project members, as long as the user has maintainer or admin access to the group where the exported project lives. - Project members with owner access will be imported as maintainers. -- Using an admin account to import will map users by primary email address (self-managed only). +- Imported users can be mapped by their primary email on self-managed instances, if an administrative user (not an owner) does the import. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues will be owned by the importer. - If an imported project contains merge requests originating from forks, @@ -129,6 +132,11 @@ For more details on the specific data persisted in a project export, see the ## Exporting a project and its data +Full project export functionality is limited to project maintainers and owners. +You can configure such functionality through [project settings](index.md): + +To export a project and its data, follow these steps: + 1. Go to your project's homepage. 1. Click **Settings** in the sidebar. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 8fdcf58b5aa..4b368fc20d6 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -72,6 +72,7 @@ Use the switches to enable or disable the following features: | **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md) | | **Pages** | ✓ | Allows you to [publish static websites](../pages/) | | **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md) +| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md) Some features depend on others: diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index b6ce21ebea6..9f8cf2ff41a 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -54,7 +54,7 @@ Furthermore, the bot user can not be added to any other project. When the project access token is [revoked](#revoking-a-project-access-token) the bot user is then deleted and all records are moved to a system-wide user with the username "Ghost User". For more information, see [Associated Records](../../profile/account/delete_account.md#associated-records). -Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#choose-the-number-of-users) and do not count as licensed seats. +Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users) and do not count as licensed seats. ## Revoking a project access token diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 8a2f62ec7a2..e58667c275c 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -80,6 +80,7 @@ codebase. ## Edit content > - Support for modifying the default merge request title and description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216861) in GitLab 13.5. +> - Support for selecting a merge request template [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263252) in GitLab 13.6. After setting up your project, you can start editing content directly from the Static Site Editor. @@ -91,7 +92,9 @@ To edit a file: wish to edit the raw Markdown instead, you can toggle the **Markdown** mode in the bottom-right corner. 1. When you're done, click **Submit changes...**. -1. (Optional) Adjust the default title and description of the merge request that will be submitted with your changes. +1. (Optional) Adjust the default title and description of the merge request that will be submitted + with your changes. Alternatively, select a [merge request template](../../../user/project/description_templates.md#creating-merge-request-templates) + from the dropdown menu and edit it accordingly. 1. Click **Submit changes**. 1. A new merge request is automatically created and you can assign a colleague for review. @@ -104,13 +107,36 @@ The Static Site Editors supports Markdown files (`.md`, `.md.erb`) for editing t ### Images > - Support for adding images through the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216640) in GitLab 13.1. +> - Support for uploading images via the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218529) in GitLab 13.6. -You can add image files on the WYSIWYG mode by clicking the image icon (**{doc-image}**). -From there, link to a URL, add optional [ALT text](https://moz.com/learn/seo/alt-text), -and you're done. The link can reference images already hosted in your project, an asset hosted +#### Upload an image + +You can upload image files via the WYSIWYG editor directly to the repository to default upload directory +`source/images`. To do so: + +1. Click the image icon (**{doc-image}**). +1. Choose the **Upload file** tab. +1. Click **Choose file** to select a file from your computer. +1. Optional: add a description to the image for SEO and accessibility ([ALT text](https://moz.com/learn/seo/alt-text)). +1. Click **Insert image**. + +The selected file can be any supported image file (`.png`, `.jpg`, `.jpeg`, `.gif`). The editor renders +thumbnail previews so you can verify the correct image is included and there aren't any references to +missing images. + +#### Link to an image + +You can also link to an image if you'd like: + +1. Click the image icon (**{doc-image}**). +1. Choose the **Link to an image** tab. +1. Add the link to the image into the **Image URL** field (use the full path; relative paths are not supported yet). +1. Optional: add a description to the image for SEO and accessibility ([ALT text](https://moz.com/learn/seo/alt-text)). +1. Click **Insert image**. + +The link can reference images already hosted in your project, an asset hosted externally on a content delivery network, or any other external URL. The editor renders thumbnail previews so you can verify the correct image is included and there aren't any references to missing images. -default directory (`source/images/`). ### Videos diff --git a/doc/user/project/web_ide/img/command_palette_v13_6.png b/doc/user/project/web_ide/img/command_palette_v13_6.png Binary files differnew file mode 100644 index 00000000000..54580a79ebd --- /dev/null +++ b/doc/user/project/web_ide/img/command_palette_v13_6.png diff --git a/doc/user/project/web_ide/img/commit_changes_v12_9.png b/doc/user/project/web_ide/img/commit_changes_v12_9.png Binary files differindex d26c9cc82e1..9a8bb214b3d 100644 --- a/doc/user/project/web_ide/img/commit_changes_v12_9.png +++ b/doc/user/project/web_ide/img/commit_changes_v12_9.png diff --git a/doc/user/project/web_ide/img/dark_theme_v13_0.png b/doc/user/project/web_ide/img/dark_theme_v13_0.png Binary files differindex f1999363904..020578a9444 100644 --- a/doc/user/project/web_ide/img/dark_theme_v13_0.png +++ b/doc/user/project/web_ide/img/dark_theme_v13_0.png diff --git a/doc/user/project/web_ide/img/solarized_light_theme_v13_0.png b/doc/user/project/web_ide/img/solarized_light_theme_v13_0.png Binary files differindex adf6d3c6b02..b4b14f1fc7f 100644 --- a/doc/user/project/web_ide/img/solarized_light_theme_v13_0.png +++ b/doc/user/project/web_ide/img/solarized_light_theme_v13_0.png diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 4da9b5f88ff..2b9db1c952d 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, how-to --- -# Web IDE +# Web IDE **(CORE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Core in 10.7. @@ -25,9 +25,25 @@ and from merge requests. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18323) in [GitLab Core](https://about.gitlab.com/pricing/) 10.8. The file finder allows you to quickly open files in the current branch by -searching. The file finder is launched using the keyboard shortcut `Command-p`, -`Control-p`, or `t` (when editor is not in focus). Type the filename or -file path fragments to start seeing results. +searching for fragments of the file path. The file finder is launched using the keyboard shortcut +<kbd>Cmd</kbd>+<kbd>p</kbd>, <kbd>Ctrl</kbd>+<kbd>p</kbd>, or <kbd>t</kbd> +(when editor is not in focus). Type the filename or file path fragments to +start seeing results. + +## Command palette + +You can see all available commands for manipulating editor content by pressing +the <kbd>F1</kbd> key when the editor is in focus. After that, +you'll see a complete list of available commands for +manipulating editor content. The editor supports commands for multi-cursor +editing, code block folding, commenting, searching and replacing, navigating +editor warnings and suggestions, and more. + +Some commands have a keyboard shortcut assigned to them. The command palette +displays this shortcut next to each command. You can use this shortcut to invoke +the command without having to select it in the command palette. + + ## Syntax highlighting @@ -244,6 +260,8 @@ quickly share your project with others. ### Enabling Live Preview +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268288) in GitLab 12.9, third-party assets and libraries required for Live Preview are hosted at `https://sandbox-prod.gitlab-static.net` when it is enabled. However, some libraries are still served from other third-party services which may or may not be desirable in your environment. + The Live Preview feature needs to be enabled in the GitLab instances admin settings. Live Preview is enabled for all projects on GitLab.com diff --git a/doc/user/project/wiki/img/wiki_move_page_1.png b/doc/user/project/wiki/img/wiki_move_page_1.png Binary files differdeleted file mode 100644 index 189fcc9a845..00000000000 --- a/doc/user/project/wiki/img/wiki_move_page_1.png +++ /dev/null diff --git a/doc/user/project/wiki/img/wiki_move_page_2.png b/doc/user/project/wiki/img/wiki_move_page_2.png Binary files differdeleted file mode 100644 index 63e6ddb29c1..00000000000 --- a/doc/user/project/wiki/img/wiki_move_page_2.png +++ /dev/null diff --git a/doc/user/project/wiki/img/wiki_sidebar_v13_5.png b/doc/user/project/wiki/img/wiki_sidebar_v13_5.png Binary files differindex 0f445d61d71..f22424749a5 100644 --- a/doc/user/project/wiki/img/wiki_sidebar_v13_5.png +++ b/doc/user/project/wiki/img/wiki_sidebar_v13_5.png diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 64608b9a915..e082e091dec 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -96,12 +96,12 @@ Please note that: ## Editing a wiki page -NOTE: **Note:** -Requires Developer [permissions](../../permissions.md). +You need Developer [permissions](../../permissions.md) or higher to edit a wiki page. +To do so: -To edit a page, simply click on the **Edit** button. From there on, you can -change its content. When done, click **Save changes** for the changes to take -effect. +1. Click the edit icon (**{pencil}**). +1. Edit the content. +1. Click **Save changes**. ### Adding a table of contents @@ -110,23 +110,34 @@ For an example, see [Table of contents](../../markdown.md#table-of-contents). ## Deleting a wiki page -NOTE: **Note:** -Requires Maintainer [permissions](../../permissions.md). +You need Maintainer [permissions](../../permissions.md) or higher to delete a wiki page. +To do so: -You can find the **Delete** button only when editing a page. Click on it and -confirm you want the page to be deleted. +1. Open the page you want to delete. +1. Click the **Delete page** button. +1. Confirm the deletion. ## Moving a wiki page -You can move a wiki page from one directory to another by specifying the full -path in the wiki page title in the [edit](#editing-a-wiki-page) form. +You need Developer [permissions](../../permissions.md) or higher to move a wiki page. +To do so: + +1. Click the edit icon (**{pencil}**). +1. Add the new path to the **Title** field. +1. Click **Save changes**. + +For example, if you have a wiki page called `about` under `company` and you want to +move it to the wiki's root: - +1. Click the edit icon (**{pencil}**). +1. Change the **Title** from `about` to `/about`. +1. Click **Save changes**. - +If you want to do the opposite: -In order to move a wiki page to the root directory, the wiki page title must -be preceded by the slash (`/`) character. +1. Click the edit icon (**{pencil}**). +1. Change the **Title** from `about` to `company/about`. +1. Click **Save changes**. ## Viewing a list of all created wiki pages diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index 28dd4c142f7..ea3ca7a28d7 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Reserved project and group names Not all project & group names are allowed because they would conflict with @@ -76,6 +82,9 @@ Currently the following names are reserved as top level groups: - `s` - `search` - `sent_notifications` +- `sitemap` +- `sitemap.xml` +- `sitemap.xml.gz` - `slash-command-logo.png` - `snippets` - `unsubscribes` diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md index ed5ecc17a8b..c1414fb9ebe 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search_syntax.md @@ -64,8 +64,8 @@ The Advanced Search Syntax also supports the use of filters. The available filte - extension: Filters by extension in the filename. Please write the extension without a leading dot. Exact match only. - blob: Filters by Git `object ID`. Exact match only. -To use them, simply add them to your query in the format `<filter_name>:<value>` without - any spaces between the colon (`:`) and the value. +To use them, add them to your keyword in the format `<filter_name>:<value>` without +any spaces between the colon (`:`) and the value. A keyword or an asterisk (`*`) is required for filter searches and has to be added in front of the filter separated by a space. Examples: diff --git a/doc/user/search/img/filtering_merge_requests_by_date_v13_6.png b/doc/user/search/img/filtering_merge_requests_by_date_v13_6.png Binary files differnew file mode 100644 index 00000000000..8f59534ef1c --- /dev/null +++ b/doc/user/search/img/filtering_merge_requests_by_date_v13_6.png diff --git a/doc/user/search/img/filtering_merge_requests_by_environment_v13_6.png b/doc/user/search/img/filtering_merge_requests_by_environment_v13_6.png Binary files differnew file mode 100644 index 00000000000..e73a0995d73 --- /dev/null +++ b/doc/user/search/img/filtering_merge_requests_by_environment_v13_6.png diff --git a/doc/user/search/img/issue_search_filter.png b/doc/user/search/img/issue_search_filter.png Binary files differdeleted file mode 100644 index d4de3ff7656..00000000000 --- a/doc/user/search/img/issue_search_filter.png +++ /dev/null diff --git a/doc/user/search/img/project_search_sha_redirect.png b/doc/user/search/img/project_search_sha_redirect.png Binary files differnew file mode 100644 index 00000000000..718a859d4af --- /dev/null +++ b/doc/user/search/img/project_search_sha_redirect.png diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 412951f8a3b..79c6cf3b07d 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -44,6 +44,7 @@ groups: - Author - Assignee - [Milestone](../project/milestones/index.md) + - [Iteration](../group/iterations/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6) - Release - [Label](../project/labels.md) - My-reaction @@ -117,6 +118,28 @@ the dropdown) **Approved-By** and select the user.  +### Filtering merge requests by environment or deployment date **(CORE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44041) in GitLab 13.6. + +To filter merge requests by deployment data, such as the environment or a date, +you can type (or select from the dropdown) the following: + +- Environment +- Deployed-before +- Deployed-after + +When filtering by an environment, a dropdown presents all environments that +you can choose from: + + + +When filtering by a deploy date, you must enter the date manually. Deploy dates +use the format `YYYY-MM-DD`, and must be quoted if you wish to specify +both a date and time (`"YYYY-MM-DD HH:MM"`): + + + ## Filters autocomplete GitLab provides many filters across many pages (issues, merge requests, epics, @@ -211,6 +234,7 @@ You can also type in this search bar to see autocomplete suggestions for: - Recently viewed issues (try and type some word from the title of a recently viewed issue) - Recently viewed merge requests (try and type some word from the title of a recently viewed merge request) - Recently viewed epics (try and type some word from the title of a recently viewed epic) +- [GitLab Flavored Markdown](../markdown.md#special-gitlab-references) (GFM) for issues within a project (try and type a GFM reference for an issue) ## Basic search @@ -248,6 +272,14 @@ the search field on the top-right of your screen while the project page is open.   +### SHA search + +You can quickly access a commit from within the project dashboard by entering the SHA +into the search field on the top right of the screen. If a single result is found, you will be +redirected to the commit result and given the option to return to the search results page. + + + ## Advanced Search **(STARTER)** Leverage Elasticsearch for faster, more advanced code search across your entire diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index c34d5be5899..6361aa856fe 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference disqus_identifier: 'https://docs.gitlab.com/ee/workflow/shortcuts.html' --- diff --git a/doc/user/todos.md b/doc/user/todos.md index c48d2adfa45..061d81618a1 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -15,9 +15,9 @@ spend your time. This can include taking an action, or keeping track of things do your work, being able to get started quickly is important. Your *To-Do List* offers a chronological list of items waiting for your input -(known as *to do items*) in a single dashboard. +(known as *to-do items*) in a single dashboard. -The To-Do List supports tracking [actions](#what-triggers-a-to-do) related to +The To-Do List supports tracking [actions](#what-triggers-a-to-do-item) related to the following: - Issues @@ -27,17 +27,17 @@ the following:  You can access your To-Do List by clicking the To-Do List icon (**{task-done}**) -next to the search bar in the top navigation. If the to do item count is: +next to the search bar in the top navigation. If the to-do item count is: -- *Less than 100*, the number in blue is the number of to do items. +- *Less than 100*, the number in blue is the number of to-do items. - *100 or more*, the number displays as 99+. The exact number displays in the To-Do List.  -## What triggers a to do +## What triggers a to-do item -A to do item appears on your To-Do List when: +A to-do item appears on your To-Do List when: - An issue or merge request is assigned to you. - You're `@mentioned` in the description or comment of an issue or merge request @@ -60,19 +60,19 @@ When several trigger actions occur for the same user on the same object (for example, an issue), GitLab displays only the first action as a single to do item. -To do item triggers aren't affected by [GitLab notification email settings](profile/notifications.md). +To-do item triggers aren't affected by [GitLab notification email settings](profile/notifications.md). NOTE: **Note:** -When a user no longer has access to a resource related to a to do item (such as +When a user no longer has access to a resource related to a to-do item (such as an issue, merge request, project, or group), for security reasons GitLab -deletes any related to do items within the next hour. Deletion is delayed to +deletes any related to-do items within the next hour. Deletion is delayed to prevent data loss, in the case where a user's access is accidentally revoked. -### Directly addressing a to do +### Directly addressing a to-do item > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7926) in GitLab 9.0. -If you're mentioned at the start of a line, the to do item you receive will be +If you're mentioned at the start of a line, the to-do item you receive will be listed as *directly addressed*. For example, in the following comment: ```markdown @@ -87,11 +87,11 @@ listed as *directly addressed*. For example, in the following comment: @erin @frank thank you! ``` -The people receiving directly addressed to do items are `@alice`, `@erin`, and -`@frank`. Directly addressed to do items only differ from mentions in their type +The people receiving directly addressed to-do items are `@alice`, `@erin`, and +`@frank`. Directly addressed to-do items only differ from mentions in their type for filtering purposes; otherwise, they appear as normal. -### Manually creating a to do +### Manually creating a to-do item You can also add the following to your To-Do List by clicking the **Add a to do** button on an: @@ -100,14 +100,14 @@ You can also add the following to your To-Do List by clicking the **Add a to do* - [Epic](group/epics/index.md) **(ULTIMATE)** - [Design](project/issues/design_management.md) - + -## Marking a to do as done +## Marking a to-do item as done Any action to an issue or merge request (or epic **(ULTIMATE)**) will mark its -corresponding to do item as done. +corresponding to-do item as done. -Actions that dismiss to do items include: +Actions that dismiss to-do items include: - Changing the assignee - Changing the milestone @@ -115,28 +115,28 @@ Actions that dismiss to do items include: - Commenting on the issue Your To-Do List is personal, and items are only marked as done if you take -action. If you close the issue or merge request, your to do item is marked as +action. If you close the issue or merge request, your to-do item is marked as done. To prevent other users from closing issues without you being notified, if someone else closes, merges, or takes action on an issue or merge request (or -epic **(ULTIMATE)**), your to do item remains pending. +epic **(ULTIMATE)**), your to-do item remains pending. -There's just one to do item for each of these, so mentioning a user many times -in an issue only triggers one to do item. +There's just one to-do item for each of these, so mentioning a user many times +in an issue only triggers one to-do item. -If no action is needed, you can manually mark the to do item as done by +If no action is needed, you can manually mark the to-do item as done by clicking its corresponding **Done** button to have GitLab remove the item from your To-Do List.  -You can also mark a to do item as done by clicking the **Mark as done** button +You can also mark a to-do item as done by clicking the **Mark as done** button in the sidebar of an issue or merge request (or epic **(ULTIMATE)**).  -You can mark all your to do items as done at once by clicking the +You can mark all your to-do items as done at once by clicking the **Mark all as done** button. ## Filtering your To-Do List @@ -152,7 +152,7 @@ You can use the following types of filters with your To-Do List: | Action | Filter by the action that triggered the to do. | You can also filter by more than one of these at the same time. The previously -described [triggering actions](#what-triggers-a-to-do) include: +described [triggering actions](#what-triggers-a-to-do-item) include: - Any action - Assigned diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index 35fddc4a1d4..97d4b5e6a0a 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Updating to GitLab 13.2: Email confirmation issues In the [GitLab 13.0.1 security release](https://about.gitlab.com/releases/2020/05/27/security-release-13-0-1-released/), |
